تحويل JSON إلى Spring Boot MongoDB Schema!

أدخل JSON وحوله إلى Spring Boot MongoDB Schema! يدعم Spring Data MongoDB, @Document, @Id.
JSON
النتيجة
 

تحويل JSON إلى Spring Boot MongoDB Schema!

يحوّل مستندات JSON إلى صنف @Document في Spring Data MongoDB: المجموعة مسمّاة في @Document، وحقل @Id، وحقل private لكل مفتاح مع @Field حيث يختلف المفتاح المخزَّن، إضافة إلى تعليقات Lombok وjakarta.validation، وكل ذلك في ملف Java واحد.

استخدمه حين يجب قراءة بيانات تصل إلى MongoDB كـ JSON عادي (قراءات IoT، أحداث، نتائج كشط) وكتابتها من خدمة Spring Boot عبر MongoRepository.

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

  1. الصق مستندات موجودة في المجموعة أو ستوجد فيها. لصق عدة مستندات كمصفوفة، مثل ناتج find().limit(5) في mongosh، يميّز الحقول العرضية عن الثابتة.
  2. اكتب اسم النموذج (الفراغ يعني MyModel)؛ ويُستخدم لاسم الصنف وللمجموعة في @Document(collection = "...") معًا.
  3. أصلح سطر package، واحفظ الملف، وأنشئ repository يرث MongoRepository<DeviceLog, String>.

مثال

المدخلات (JSON)
[
  { "device_id": "th-sensor-07", "temperature": 21.4, "battery": 87, "online": true, "recorded_at": "2024-02-11T06:00:00Z" },
  { "device_id": "th-sensor-09", "temperature": 19.8, "battery": 12, "online": false, "recorded_at": "2024-02-11T06:00:00Z", "firmware": "1.4.2" }
]
المخرجات (Spring Data MongoDB)
package com.hello.world.devicelog;

import org.springframework.data.annotation.Id;
import org.springframework.data.mongodb.core.mapping.Document;
import org.springframework.data.mongodb.core.mapping.Field;

import jakarta.validation.constraints.NotEmpty;
import jakarta.validation.constraints.NotNull;

import java.time.LocalDateTime;

import lombok.Getter;
import lombok.Setter;
import lombok.experimental.FieldNameConstants;

@Document(collection = "DeviceLog")
@FieldNameConstants
@Getter
@Setter
public class DeviceLog {
    @Id
    private String id;

    @NotEmpty()
    @Field("device_id")
    private String deviceId;

    @NotNull()
    private Double temperature;

    @NotNull()
    private Long battery;

    @NotNull()
    private Boolean online;

    @NotNull()
    @Field("recorded_at")
    private LocalDateTime recordedAt;

    private String firmware;
}

يظهر firmware في المستند الثاني فقط، فلا تعليق عليه. ويُقرأ device_id وrecorded_at عبر @Field("device_id") و@Field("recorded_at")، فترتبط المستندات الموجودة بحقول camelCase دون ترحيل.

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

  • يسمّي المجموعة صراحة بـ @Document(collection = "DeviceLog").
  • يحمل @Id private String id الحقل _id في MongoDB؛ ومفتاح id أو _id في JSON الخاص بك يُدمج فيه ولا يُكرَّر، والـ id الرقمي يجعله Long.
  • يُحدَّد نوع كل حقل من قيمه: Long أو Double أو Boolean أو LocalDate (YYYY-MM-DD) أو LocalDateTime (التاريخ مع الوقت) أو String؛ وتصبح الكائنات المضمّنة Map<String, Object> والمصفوفات List<...>.
  • يُضاف @Field("...") كلما لم يكن الاسم في Java هو المفتاح المخزَّن، بما في ذلك الكلمات المحجوزة في Java التي يُعاد تسميتها بـ _ في آخرها.
  • الحقول الموجودة في كل مستند تحصل على @NotEmpty() للسلاسل غير الفارغة و@NotNull() في غير ذلك؛ والحقول العرضية أو التي قيمتها null لا تحصل على شيء.

حالات الاستخدام

APIs استعلام فوق مجموعات المستشعرات أو السجلات

حين يجب تقديم القراءات التي تكتبها الأجهزة مباشرة في MongoDB إلى لوحة معلومات، الصق بضعة مستندات لتحصل على الصنف وعرّف فورًا استعلامات مشتقة مثل findByDeviceIdOrderByRecordedAtDesc.

مشاركة مجموعة مع خدمة Node.js

إذا احتاج Spring إلى قراءة مجموعة تكتبها خدمة أخرى أصلًا بصيغة snake_case، فإن تعليقات @Field تتيح لجانب Java استخدام أسماء camelCase مع قراءة المفاتيح نفسها وكتابتها.

ملاحظات وقيود

  • لا يُفحص @NotEmpty و@NotNull عند الحفظ افتراضيًا؛ سجّل bean من نوع ValidatingMongoEventListener للتحقق مباشرة قبل save().
  • يُخزَّن LocalDateTime في MongoDB كـ Date مبني على UTC وقد يظهر مُزاحًا بحسب المنطقة الزمنية للخادم. للسجلات التي تهمّ فيها اللحظة الزمنية بدقة، Instant أكثر أمانًا.
  • معرّف Long لا يولّده MongoDB؛ يجب أن تسنده قبل الحفظ. لا تُملأ تلقائيًا إلا معرّفات String وObjectId وBigInteger.
  • تخرج المستندات المضمّنة على شكل Map<String, Object>. استبدلها بأصناف صغيرة حين تريد وصولًا ذا أنواع وتحققًا.

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

لماذا يُسمّى الحقل id بينما يخزّن MongoDB _id؟

يربط Spring Data تلقائيًا الحقل المسمّى id (أو المعلَّم بـ @Id) بـ _id، ويحوّل الـ String إلى ObjectId حين يبدو كذلك. تعريف _id بنفسك غير ضروري.

أريد أن تُسمّى المجموعة device_logs.

عدّل السلسلة النصية فقط: @Document(collection = "device_logs"). يُدرج المولّد اسم النموذج كما كُتب، لذا فإن إدخال device_logs اسمًا للنموذج سيحوّل الصنف أيضًا إلى DeviceLogs.

ما الفرق بينه وبين entity في JPA؟

يستخدم @Document و@Field و@Id الخاص بـ Spring Data بدلًا من @Entity و@Column و@GeneratedValue، وتبقى القيم المتداخلة مضمّنة بدلًا من الحاجة إلى عمود JSON. للجداول العلائقية، استخدم صفحة JSON → Spring Boot JPA.