حوّل كيانات JPA إلى JSON!

أدخل كيانات JPA لإنشاء JSON تجريبي! يدعم JPA @Entity, Hibernate, Spring Boot. مفيد لتوثيق واجهات API وأجسام الطلبات التجريبية (mock request body).
JPA
النتيجة
 

حوّل كيانات JPA إلى JSON!

الصق أصناف @Entity من JPA في Spring Boot لترى JSON نموذجيًا بالشكل الذي يُنتجه Jackson حين يُرجع controller تلك الكيانات. تُعالَج أسماء الحقول و@JsonIgnore و@JsonProperty والحقول الموروثة من @MappedSuperclass وأنواع التاريخ في Java 8 كلها وفق إعداد Jackson الافتراضي في Spring Boot.

استخدمه لأمثلة REST Docs أو Swagger، أو لأجسام الطلبات في Postman، أو لتدقيق الحقول التي تتسرب حين يُعرض entity دون DTO.

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

  1. الصق أصناف الـ entities في خانة JPA. يمكن أن تبقى أسطر الاستيراد وتعليقات Lombok؛ وضمّن الأصناف الأب والكيانات المرتبطة والـ enums حتى تُملأ قيمها.
  2. الصنف الذي لا يشير إليه أي صنف آخر يصبح الجذر. وحين تشير الكيانات إلى بعضها، يُختار الصنف public.
  3. انسخ النتيجة إلى اختبارك أو وثائقك.

مثال

المدخلات (Java · JPA)
@MappedSuperclass
public abstract class BaseEntity {
    @Id @GeneratedValue
    private Long id;
    private LocalDateTime createdAt;
}

@Entity
public class Appointment extends BaseEntity {
    private LocalDate visitDate;
    private BigDecimal fee;
    @Enumerated(EnumType.STRING)
    private Status status;
    @ManyToOne(fetch = FetchType.LAZY)
    private Patient patient;

    public enum Status { BOOKED, DONE, CANCELED }
}

@Entity
class Patient extends BaseEntity {
    private String name;
    @JsonIgnore
    private String residentNumber;
    @OneToMany(mappedBy = "patient")
    private List<Appointment> appointments;
}
المخرجات (JSON)
{
  "id": 0,
  "createdAt": "1970-01-01T00:00:00",
  "visitDate": "1970-01-01",
  "fee": 0,
  "status": "BOOKED",
  "patient": {
    "id": 0,
    "createdAt": "1970-01-01T00:00:00",
    "name": "",
    "appointments": []
  }
}

يشير Appointment وPatient كلٌّ منهما إلى الآخر، لذا يكون الصنف public Appointment هو الجذر ويُقطع Patient.appointments إلى مصفوفة فارغة بدلًا من الدوران بلا نهاية. يأتي id وcreatedAt من BaseEntity أولًا، ويختفي residentNumber بسبب @JsonIgnore. ويكون LocalDateTime سلسلة ISO دون إزاحة، ويُظهر الـ enum أول ثابت فيه، "BOOKED".

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

  • تُتخطى الحقول static وtransient وحقول @JsonIgnore، وكذلك الأسماء المدرجة في @JsonIgnoreProperties({"..."}) على مستوى الصنف.
  • @JsonProperty("doctor_name") يعيد تسمية مفتاح JSON.
  • حين يكون الصنف الأب (@MappedSuperclass أو أي extends) في الإدخال، تأتي حقوله أولًا.
  • القيمة الافتراضية في الـ entity مثل private Status status = Status.ACTIVE; أو private int visits = 0; تظهر بتلك القيمة، والـ getters المحسوبة التي لا يقابلها حقل (public int getAge()) تظهر كمفاتيح إضافية، تمامًا كما كان Jackson سيُخرجها.
  • ناتج التواريخ يتبع إعدادات Spring Boot الافتراضية: LocalDate → 1970-01-01، وLocalDateTime → 1970-01-01T00:00:00، وjava.util.Date → 1970-01-01T00:00:00.000+00:00.
  • الأغلفة الرقمية مثل BigDecimal وLong تعطي 0، وUUID يعطي UUID كله أصفار، وbyte[] يعطي سلسلة base64 "AA==".
  • List/Set تعطي مصفوفة من عنصر واحد، وMap<Long, String> يعطي كائنًا بمفتاح مطابق ({"0": ""})، وOptional<T> يُفك إلى قيمته الداخلية.
  • العلاقات ثنائية الاتجاه (@OneToMany مع @ManyToOne) تُقطع بـ null أو بمصفوفة فارغة حيث تعود على نفسها.

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

أمثلة Spring REST Docs وSwagger

ولّد JSON لـ @Schema(example = ...) أو لمقتطفات الوثائق مباشرة من الـ entity، والصقه مجددًا كلما تغيّرت الحقول لتبقى الوثائق متزامنة.

تدقيق الكيانات المعروضة

إن كنت تُرجع الكيانات دون DTOs، فتحقق مما إذا كانت حقول مثل كلمات المرور أو أرقام الهوية الوطنية تنتهي في الاستجابات. الحقول الظاهرة في الناتج هي التي كان Jackson سيُسلسِلها.

أجسام طلبات MockMvc

استخدم الناتج هيكلًا لـ mockMvc.perform(post("/appointments").content(...))، مع حذف id والطوابع الزمنية المولَّدة قبل ملء القيم.

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

  • يدخل Jackson الحقيقي في عودية لا نهائية (StackOverflowError) مع العلاقات ثنائية الاتجاه. إن بدا الناتج مقطوعًا، فهذه إشارتك لاستخدام @JsonManagedReference/@JsonBackReference أو @JsonIgnore أو DTO.
  • لا يتجاهل Jackson تعليق @Transient الخاص بـ JPA افتراضيًا، فتبقى تلك الحقول في الناتج؛ ولا تُحذف إلا الحقول ذات الكلمة المفتاحية transient في Java.
  • علاقات FetchType.LAZY قد تفشل في التسلسل كـ Hibernate proxies في الواقع؛ والناتج يفترض أن كل شيء محمَّل.
  • الحقول التي ليس صنفها في الإدخال تظهر null، ولا تُطبَّق قيود @Column مثل nullable أو length.

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

هل يجب فعلًا أن تكون التواريخ سلاسل نصية لا مصفوفات مثل [2024,1,1]؟

يعطّل Spring Boot الخيار WRITE_DATES_AS_TIMESTAMPS، فيُكتب LocalDateTime كسلسلة ISO. أما ObjectMapper مبني يدويًا لم يُسجَّل فيه إلا JavaTimeModule فقد يكتب مصفوفات بدلًا من ذلك.

هل تظهر كل الحقول حتى دون @Getter من Lombok؟

تعمل الأداة انطلاقًا من تعريفات الحقول. أما Jackson الحقيقي فيُسلسِل عبر الـ getters (أو الحقول العامة) افتراضيًا، لذا قد تغيب الحقول الخاصة التي ليس لها getters عن الاستجابات الفعلية.

هل يمكنني لصق أصناف @Document من MongoDB أيضًا؟

تتبع قواعد Jackson نفسها، لكن التحفظات الخاصة بـ MongoDB مثل ObjectId و@Field مشروحة في صفحة Spring Data MongoDB إلى JSON.