حوّل أصناف Java إلى JSON!

الصق شيفرة Java (class·record) واحصل على مثال JSON! يدعم Jackson @JsonProperty, @JsonIgnore, Lombok. مفيد لتوثيق واجهات API وأجسام الطلبات التجريبية (mock request body).
Java
النتيجة
 

حوّل أصناف Java إلى JSON!

أدخل كود Java لـ DTO أو POJO أو record لتحصل على JSON الذي يُرجَّح أن ينتجه إعداد Jackson الافتراضي في Spring Boot. تأتي المفاتيح من الحقول المُعلنة، مع تطبيق @JsonProperty و@JsonIgnore و@JsonIgnoreProperties واستبعاد static/transient.

استخدمه لإنتاج مثال Swagger أو payload نموذجي للواجهة الأمامية من DTO الطلب أو الاستجابة في controller، أو ببساطة للتحقق من المفاتيح التي سيُخرجها صنف يستخدم @Data من Lombok.

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

  1. الصق كود الـ DTO كما هو. يمكن أن تبقى أسطر الاستيراد وتعليقات Lombok والـ constructors والدوال.
  2. ضمّن تعريفات static class وrecord وenum المتداخلة في الإدخال نفسه حتى تُملأ الحقول التي تشير إليها ببنيتها.
  3. عندما يكون النوع الجذري على تلقائي، يُختار الصنف الذي لا يستخدمه أي صنف آخر نوعًا لحقل. وحين تشير الكيانات إلى بعضها، اختر ما تريده من القائمة.
  4. انسخ الناتج إلى @Schema(example = ...) أو مقتطف REST Docs أو جسم طلب في MockMvc.

مثال

المدخلات (Java)
@Data
@JsonIgnoreProperties({"password"})
public class MemberResponse {
    private Long memberId;
    @JsonProperty("nick_name")
    private String nickname;
    private String password;
    private Grade grade = Grade.SILVER;
    private LocalDate birthDate;
    private List<Address> addresses;
    private static final long serialVersionUID = 1L;

    public enum Grade { BRONZE, SILVER, GOLD }

    public record Address(String zipCode, String city, boolean primary) {}
}
المخرجات (JSON)
{
  "memberId": 0,
  "nick_name": "",
  "grade": "SILVER",
  "birthDate": "1970-01-01",
  "addresses": [
    {
      "zipCode": "",
      "city": "",
      "primary": false
    }
  ]
}

يُحذف password بسبب @JsonIgnoreProperties({"password"}) على مستوى الصنف، ولا يظهر serialVersionUID المعرَّف بـ static final أبدًا. تُقرأ القيمة الابتدائية Grade.SILVER، فيكون grade هو "SILVER" لا أول ثابت في الـ enum. ويتوسع record Address المتداخل إلى مصفوفة من الكائنات.

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

  • تصبح أسماء الحقول مفاتيح، ويتجاوزها @JsonProperty("x") أو @JsonProperty(value = "x").
  • المستبعد: حقول @JsonIgnore، والمفاتيح المدرجة في @JsonIgnoreProperties({...}) على مستوى الصنف، والحقول static أو transient.
  • يدعم مكونات record في Java 16+، وتعريفات static class المتداخلة، والحقول الموروثة عبر extends (حقول الأب أولًا).
  • حقول الـ enum تحمل أول ثابت كسلسلة نصية، أو الثابت المذكور في القيمة الابتدائية للحقل؛ و@JsonProperty("x") على الثابت يغيّر السلسلة إلى x.
  • التواريخ تتبع ناتج Jackson الافتراضي في Spring Boot: LocalDateTime → 1970-01-01T00:00:00، LocalDate → 1970-01-01، Instant/OffsetDateTime/ZonedDateTime → سلسلة ISO تنتهي بـ Z، java.util.Date/Timestamp → 1970-01-01T00:00:00.000+00:00.
  • الأغلفة الرقمية مثل BigDecimal وLong تصبح 0، وOptional<T> يُفك إلى T، وbyte[] يصبح سلسلة Base64، ويحصل UUID وObjectId في MongoDB على قيم سليمة الصيغة.
  • List وSet والمصفوفات تحصل على عنصر نموذجي واحد؛ والـ map ذات المفتاح الرقمي مثل Map<Long, V> تستخدم "0"، وإلا فـ "key".

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

ملء أمثلة springdoc / Swagger

قيم example المكتوبة يدويًا تتقادم كلما أُضيف حقل إلى الـ DTO. ولّد JSON من كود الـ DTO وحسّن القيم انطلاقًا منه، فلا يكون أي مفتاح ناقصًا أو مكتوبًا خطأً.

أجسام الطلبات لاختبارات MockMvc أو RestAssured

أنشئ JSON الطلب مباشرة من DTO الـ @RequestBody والصقه في text block (""") داخل اختبارك. المفاتيح المعاد تسميتها بـ @JsonProperty مطبّقة أصلًا، مطابقةً للربط الحقيقي.

مشاركة شكل الاستجابة مع الواجهة الأمامية

مطورو الواجهة الأمامية الذين لا يقرؤون كود الخلفية يحصلون على بنية JSON لنقطة النهاية مباشرة، بدلًا من الاضطرار إلى تفسير صنف Java.

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

  • تُستخدم القيم الابتدائية للحقول حين تكون قيمة حرفية (= "guest"، = 100، = true) أو ثابت enum (= Grade.SILVER)؛ وأي شيء آخر، مثل new ArrayList<>() أو استدعاء دالة، يعود إلى القيمة البديلة للنوع.
  • الـ getters التي لا يقابلها حقل، مثل getFullName() أو boolean isVip()، تُضاف كخصائص كما يفعل Jackson، مع احترام @JsonIgnore/@JsonProperty على ذلك الـ getter. وفي المقابل، يُفترض أن الحقل private الذي ليس له getter مرئي (كما مع @Getter/@Data في Lombok).
  • لا تُطبَّق قواعد التسمية العامة (@JsonNaming(SnakeCaseStrategy.class)، spring.jackson.property-naming-strategy) ولا أنماط التاريخ في @JsonFormat.
  • دوال @JsonValue في الـ enums لا تُقيَّم، لذا تظل هذه الـ enums تُظهر الثابت (أو اسم @JsonProperty الخاص به).
  • حقول Page<T>/Slice<T> في Spring Data تُبسَّط إلى مصفوفة عناصر؛ بينما التسلسل الحقيقي لـ Page كائن فيه content وpageable وغيرهما.

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

هل يعمل حين يولّد @Data أو @Getter من Lombok دوال الوصول؟

نعم. تُبنى المفاتيح من الحقول المُعلنة، لذا لا حاجة لوجود الـ getters والـ setters التي يولّدها Lombok وقت الترجمة في الكود.

لماذا يكون LocalDateTime سلسلة نصية لا مصفوفة أرقام؟

يسجّل Spring Boot الوحدة jackson-datatype-jsr310 ويعطّل WRITE_DATES_AS_TIMESTAMPS افتراضيًا، فينتج سلاسل ISO؛ والعيّنة تتبع هذا الإعداد الافتراضي. أما ObjectMapper من Jackson المجرد فقد يكتب بدلًا من ذلك مصفوفة مثل [1970,1,1,0,0].

هل يمكنني لصق entity من JPA؟

للكيانات بنية الحقول نفسها، فتُحلَّل بلا مشكلة. العلاقات ثنائية الاتجاه مثل @OneToMany كانت ستدور في حلقة، لذا تُوسَّع مرة واحدة ثم تُقطع بـ null أو بمصفوفة فارغة. وهناك أيضًا صفحة مخصصة Spring Boot JPA → JSON.

ماذا لو كان @JsonIgnore على setter أو على getter لحقل موجود؟

التعليقات التوضيحية على تعريف الحقل تُطبَّق دائمًا، أما التي على الـ getter فلا تُطبَّق إلا إذا لم يوجد حقل بذلك الاسم. لا يُطبَّق @JsonIgnore على setter، ولا على getter لحقل مُعلن، فانقله إلى الحقل لترى أثره.