حوّل JSON إلى class بلغة Java!

أدخل JSON لتوليد كود class بلغة Java بما في ذلك الكائنات المتداخلة! يدعم Jackson @JsonProperty, Lombok. Spring Boot JPA @Entity · MongoDB @Document في التبويبات أعلاه.
JSON
النتيجة
 

حوّل JSON إلى class بلغة Java!

الصق عيّنة JSON لتحصل على أصناف Java أو records يستطيع Jackson فك تسلسلها مباشرة. تصبح الكائنات المتداخلة أصنافًا إضافية في الملف نفسه، وتصبح المصفوفات List<T>.

استخدمه لكائنات DTO التي كنت ستكتبها يدويًا في Spring Boot: أنواع الاستجابات لعملاء RestTemplate أو WebClient أو Feign، أو أجسام الطلبات لـ APIs خارجية. على Java 16+ يمكنك إخراج records، وإن كان مشروعك يستخدم Lombok أصلًا، فخيار Lombok يُبقي الناتج بالأسلوب نفسه.

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

  1. الصق JSON استجابة الـ API في خانة الإدخال.
  2. أدخل اسم الـ DTO في اسم النوع. الصنف الأول وحده public، فاجعله مطابقًا لاسم الملف.
  3. اختر class (مع getters/setters) أو record من النمط.
  4. مع class، فعّل Lombok لاستبدال الـ getters/setters بـ @Data و@NoArgsConstructor و@AllArgsConstructor.
  5. الصق النتيجة في ملف .java وأضف تعريف الحزمة (package).

مثال

المدخلات (JSON)
{
  "id": 1296269,
  "full_name": "octocat/Hello-World",
  "private": false,
  "stargazers_count": 80,
  "owner": { "login": "octocat", "site_admin": false },
  "topics": ["api", "demo"]
}
المخرجات (Java · class)
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;

public class Repository {
    private Integer id;
    @JsonProperty("full_name") private String fullName;
    @JsonProperty("private") private Boolean private_;
    @JsonProperty("stargazers_count") private Integer stargazersCount;
    private Owner owner;
    private List<String> topics;

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getFullName() {
        return fullName;
    }

    public void setFullName(String fullName) {
        this.fullName = fullName;
    }

    public Boolean getPrivate() {
        return private_;
    }

    public void setPrivate(Boolean private_) {
        this.private_ = private_;
    }

    public Integer getStargazersCount() {
        return stargazersCount;
    }

    public void setStargazersCount(Integer stargazersCount) {
        this.stargazersCount = stargazersCount;
    }

    public Owner getOwner() {
        return owner;
    }

    public void setOwner(Owner owner) {
        this.owner = owner;
    }

    public List<String> getTopics() {
        return topics;
    }

    public void setTopics(List<String> topics) {
        this.topics = topics;
    }
}

class Owner {
    private String login;
    @JsonProperty("site_admin") private Boolean siteAdmin;

    public String getLogin() {
        return login;
    }

    public void setLogin(String login) {
        this.login = login;
    }

    public Boolean getSiteAdmin() {
        return siteAdmin;
    }

    public void setSiteAdmin(Boolean siteAdmin) {
        this.siteAdmin = siteAdmin;
    }
}

المفاتيح بصيغة snake_case مثل full_name ترتبط بحقل fullName عبر @JsonProperty. وبما أن private كلمة محجوزة في Java، أصبح الحقل private_ بينما بقيت دوال الوصول getPrivate()/setPrivate()، وفُصل الكائن owner في صنف Owner داخل الملف نفسه.

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

  • أسلوبان للإخراج: class عادي مع getters/setters، أو record غير قابل للتغيير.
  • خيار Lombok (لأسلوب class فقط): يضيف @Data و@NoArgsConstructor و@AllArgsConstructor مع أسطر الاستيراد ويحذف كود دوال الوصول.
  • لا يُضاف @JsonProperty إلا حيث يختلف اسم الحقل عن مفتاح JSON، مع سطر استيراده.
  • كل حقل يستخدم نوعًا مغلِّفًا (Integer، Long، Double، Boolean)، فتتسع قيمة null في JSON دون عمل إضافي.
  • الأعداد الصحيحة التي تتجاوز نطاق 32 بت تصبح Long؛ والقيم مختلطة الأنواع تصبح Object.
  • المفاتيح التي هي كلمات محجوزة مثل class أو default تحصل على _ في آخرها؛ والمفاتيح التي تبدأ برقم تحصل على البادئة n.
  • لا توجد أسماء بديلة للأنواع في Java، لذا تُنتج المصفوفة على المستوى الأعلى تعليقًا // Root: List<RootItem> إضافة إلى صنف العنصر.

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

كائنات DTO لـ APIs خارجية في Spring Boot

الصق الاستجابة النموذجية من وثائق API للدفع أو الخرائط أو المراسلة ومرّر الصنف المولَّد إلى restTemplate.getForObject(url, PaymentResponse.class). كلما ازداد التداخل عمقًا، ازداد عدد الحقول التي تتجنب إغفالها مقارنة بالكتابة اليدوية.

نماذج استجابة للقراءة فقط على شكل records

للاستجابات التي تقرؤها فقط، يكون record أقصر ولا setters فيه؛ ويفك Jackson 2.12+ تسلسله عبر الـ constructor القانوني للـ record.

استعادة نموذج من بيانات الاختبار الثابتة

في مشروع قديم لا توجد فيه إلا ملفات JSON للاختبارات، أدخل أحدها لترى توزيع الحقول وتحصل على مسودة أولى للـ DTO.

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

  • الحقل الغائب في بعض العناصر يصل ببساطة على شكل null في النوع المغلِّف؛ ولا شيء يعلّمه كاختياري. أضف @NotNull أو ما شابه بنفسك إن كنت تتحقق من القيم المطلوبة.
  • مع الإعدادات الافتراضية يرمي Jackson خطأً عند المفاتيح المجهولة. إن كان الـ API قد يضيف حقولًا، ففكّر في @JsonIgnoreProperties(ignoreUnknown = true) أو في تعطيل FAIL_ON_UNKNOWN_PROPERTIES.
  • تخرج سلاسل التاريخ على شكل String. ربطها بـ LocalDateTime أو OffsetDateTime يحتاج إلى الوحدة jackson-datatype-jsr310.
  • اختيار record يُخفي مربع اختيار Lombok، لأن الـ records لا تحتاج إليه.
  • الأصناف المتداخلة أصناف ذات نطاق الحزمة في الملف نفسه، وليست public. افصلها في ملفات مستقلة إن احتاجتها حزم أخرى.

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

لماذا يكون getter الحقل المنطقي getXxx لا isXxx؟

نوع الحقل هو المغلِّف Boolean لا النوع البدائي boolean. لطالما تعرّف Jackson على دوال isXxx للنوع البدائي boolean فقط، لذا يُستخدم getXxx ليرتبط الحقل بالطريقة نفسها في أي إصدار من Jackson.

هل يحتفظ ناتج record بـ @JsonProperty؟

نعم، المكونات المعاد تسميتها تُكتب بالشكل @JsonProperty("full_name") String fullName. ويملؤها Jackson 2.12 أو أحدث عبر الـ constructor القانوني.

إذا ضبطت spring.jackson.property-naming-strategy=SNAKE_CASE، فهل يمكنني حذف التعليقات التوضيحية؟

مع استراتيجية SNAKE_CASE عامة، يرتبط full_name ↔ fullName دون تعليقات توضيحية. أما الأسماء التي تغيّرت بسبب الكلمات المحجوزة، مثل private_، فلا تشملها الاستراتيجية، فأبقِ تعليقاتها التوضيحية.

هل يمكنني استخدام الناتج مع Gson؟

يتجاهل Gson @JsonProperty. استبدله بـ @SerializedName في ناتج class فتعمل البنية نفسها مع Gson؛ والـ records مدعومة بدءًا من Gson 2.10.