أدخل صنف @Document من Spring Data MongoDB مع أصنافه وrecords المضمّنة، فيبني JSON نموذجيًا لما يُرجعه controller حين يرسل ذلك المستند. يتبع الشكل تسلسل Jackson الافتراضي في Spring Boot، فهو يصف استجابة الـ API لا BSON المخزَّن في MongoDB.
يوفّر الوقت مع مستندات MongoDB المليئة بالقوائم المضمّنة وحقول Map والطوابع الزمنية Instant، حيث تكون كتابة عيّنة استجابة يدويًا مملة، ويُظهر الفجوة بين صيغة التخزين وصيغة الاستجابة.
@Document وأصنافه أو records المضمّنة في خانة Spring Data MongoDB.id والتواريخ بقيم واقعية قبل استخدام JSON في الوثائق أو الاختبارات.@Document(collection = "devices")
public class Device {
@Id
private String id;
private String serial;
@Field("fw")
private String firmwareVersion;
private Map<String, Double> lastReadings;
private List<Alert> alerts;
private Instant registeredAt;
}
record Alert(String level, String message, Instant raisedAt) {}{
"id": "",
"serial": "",
"firmwareVersion": "",
"lastReadings": {
"key": 0
},
"alerts": [
{
"level": "",
"message": "",
"raisedAt": "1970-01-01T00:00:00Z"
}
],
"registeredAt": "1970-01-01T00:00:00Z"
}Alert في List<Alert> هو record، فتصبح مكوناته level وmessage وraisedAt حقولًا. ويصبح Map<String, Double> على شكل {"key": 0}، وInstant سلسلة UTC تنتهي بـ Z. أما @Field("fw") فلا يعيد تسمية الحقل إلا في التخزين داخل MongoDB، فيبقى مفتاح JSON firmwareVersion.
record Alert(String level, ...)، كحقول.List وSet مصفوفات من عنصر واحد؛ ويصبح Map<String, T> على شكل {"key": value}.Instant وZonedDateTime وOffsetDateTime القيمة 1970-01-01T00:00:00Z، بينما يعطي LocalDateTime سلسلة دون إزاحة.ObjectId تحصل على سلسلة ObjectId سداسية عشرية نموذجية.@DBRef تصبح كائنات متداخلة حين تكون جزءًا من الإدخال.@JsonIgnore و@JsonProperty و@JsonIgnoreProperties والحقول الموروثة القواعد نفسها المتبعة في صفحة JPA.البنى التي يجمعها MongoDB في مستند واحد، مثل قوائم المراجعات وخرائط الخيارات ومصفوفات السجل، تصنع أمثلة استجابات طويلة. الصق الأصناف فيُكتب كل مستوى متداخل نيابة عنك.
الأسماء القصيرة عبر @Field أو الحقول المرتبطة بـ _id تجعل مفاتيح قاعدة البيانات تختلف عن مفاتيح الـ API. يُظهر الناتج جانب الـ API، فيمكنك وضع الاثنين جنبًا إلى جنب.
@Field("...") و@Indexed و@TextIndexed لا تغيّر مفاتيح JSON ولا تنعكس في الناتج.@Id String id باسم _id لكنه يخرج من Jackson باسم id، وهذا ما يُظهره الناتج.org.bson.types.ObjectId ككائن فيه timestamp وdate، لا كسلسلة سداسية عشرية. لإرسال الصيغة النصية الظاهرة هنا، سجّل ToStringSerializer أو استخدم معرّفًا من نوع String.GeoJsonPoint، تصبح null.@Id من نوع ObjectId أم String؟مع String يحوّله Spring Data إلى ObjectId عند الحفظ ويُرجع الـ API سلسلة سداسية عشرية نظيفة. أما الإبقاء على النوع ObjectId فيعني حاجتك إلى إعدادات Jackson إضافية للاستجابات.
@DBRef فعلًا ككائنات متداخلة؟يحلّ @DBRef المستند المُشار إليه عند القراءة (عند أول وصول إن كان lazy)، فتحوي الاستجابات كائنًا متداخلًا. أما المراجع اليدوية التي لا تخزّن إلا معرّف ObjectId أو String فتُرجع المعرّف فقط.
Map<String, Object> حر الشكل؟نوع قيمته مجهول، فيصبح {"key": null}. استبدله بنوع القيمة التي تخزّنها فعلًا قبل وضعه في الوثائق.