حوّل فئات مستندات MongoDB إلى JSON!

أدخل فئات مستندات MongoDB لإنشاء JSON تجريبي! يدعم Spring Data MongoDB @Document. مفيد لتوثيق واجهات API وأجسام الطلبات التجريبية (mock request body).
Spring Data MongoDB
النتيجة
 

حوّل فئات مستندات MongoDB إلى JSON!

أدخل صنف @Document من Spring Data MongoDB مع أصنافه وrecords المضمّنة، فيبني JSON نموذجيًا لما يُرجعه controller حين يرسل ذلك المستند. يتبع الشكل تسلسل Jackson الافتراضي في Spring Boot، فهو يصف استجابة الـ API لا BSON المخزَّن في MongoDB.

يوفّر الوقت مع مستندات MongoDB المليئة بالقوائم المضمّنة وحقول Map والطوابع الزمنية Instant، حيث تكون كتابة عيّنة استجابة يدويًا مملة، ويُظهر الفجوة بين صيغة التخزين وصيغة الاستجابة.

طريقة الاستخدام

  1. الصق صنف @Document وأصنافه أو records المضمّنة في خانة Spring Data MongoDB.
  2. صنف المستند الذي لا يشير إليه أي صنف آخر يصبح جذر الناتج.
  3. استبدل القيم البديلة لـ id والتواريخ بقيم واقعية قبل استخدام JSON في الوثائق أو الاختبارات.

مثال

المدخلات (Java · Spring Data MongoDB)
@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) {}
المخرجات (JSON)
{
  "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.

الميزات المدعومة

  • تُقرأ مكونات records في Java، كما في 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، وهذا ما يُظهره الناتج.
  • يكتب Jackson الافتراضي في Spring Boot org.bson.types.ObjectId ككائن فيه timestamp وdate، لا كسلسلة سداسية عشرية. لإرسال الصيغة النصية الظاهرة هنا، سجّل ToStringSerializer أو استخدم معرّفًا من نوع String.
  • الأصناف الغائبة عن الإدخال، بما فيها أنواع Spring Data مثل GeoJsonPoint، تصبح null.

الأسئلة الشائعة

هل يكون @Id من نوع ObjectId أم String؟

مع String يحوّله Spring Data إلى ObjectId عند الحفظ ويُرجع الـ API سلسلة سداسية عشرية نظيفة. أما الإبقاء على النوع ObjectId فيعني حاجتك إلى إعدادات Jackson إضافية للاستجابات.

هل تعود حقول @DBRef فعلًا ككائنات متداخلة؟

يحلّ @DBRef المستند المُشار إليه عند القراءة (عند أول وصول إن كان lazy)، فتحوي الاستجابات كائنًا متداخلًا. أما المراجع اليدوية التي لا تخزّن إلا معرّف ObjectId أو String فتُرجع المعرّف فقط.

كيف يبدو حقل Map<String, Object> حر الشكل؟

نوع قيمته مجهول، فيصبح {"key": null}. استبدله بنوع القيمة التي تخزّنها فعلًا قبل وضعه في الوثائق.