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

أدخل JSON وحوله إلى Spring Boot JPA Schema! يدعم Spring Data JPA, Hibernate, @Entity, @Id, @GeneratedValue, Lombok.
JSON
النتيجة
 

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

يحوّل JSON إلى صنف @Entity لـ Spring Data JPA على Spring Boot 3. يتضمن ملف Java الواحد أسطر استيراد jakarta.persistence وjakarta.validation، ومفتاحًا أساسيًا @Id، وحقلًا private لكل مفتاح، و@Getter و@Setter و@FieldNameConstants من Lombok، و@NotEmpty/@NotNull من Bean Validation.

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

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

  1. الصق سجلًا واحدًا ككائن أو عدة سجلات كمصفوفة. الحقول الغائبة في أي سجل لا تحصل على تعليق تحقق.
  2. أدخل اسم صنف الـ entity في اسم النموذج (الافتراضي MyModel). وتُستخدم صيغته بالأحرف الصغيرة أيضًا في آخر اسم الحزمة (com.hello.world.reservation).
  3. غيّر سطر package إلى حزمة مشروعك، واحفظه باسم Reservation.java، وأنشئ repository يرث JpaRepository<Reservation, Long>.

مثال

المدخلات (JSON)
{
  "guest_name": "Hana Lee",
  "room_no": 1204,
  "nights": 3,
  "rate": 149.5,
  "breakfast": true,
  "check_in": "2024-08-09T15:00:00"
}
المخرجات (Spring Data JPA)
package com.hello.world.reservation;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.validation.constraints.NotEmpty;
import jakarta.validation.constraints.NotNull;

import java.time.LocalDateTime;

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

@Entity
@FieldNameConstants
@Getter
@Setter
public class Reservation {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @NotEmpty()
    @Column(name = "guest_name")
    private String guestName;

    @NotNull()
    @Column(name = "room_no")
    private Long roomNo;

    @NotNull()
    private Long nights;

    @NotNull()
    private Double rate;

    @NotNull()
    private Boolean breakfast;

    @NotNull()
    @Column(name = "check_in")
    private LocalDateTime checkIn;
}

أصبحت الأعداد الصحيحة مثل room_no وnights من نوع Long، وrate من نوع Double، وcheck_in من نوع LocalDateTime. يحصل كل مفتاح بصيغة snake_case على @Column(name = "...")، وبما أن كل القيم مملوءة، يحصل حقل String المسمّى guestName على @NotEmpty() والبقية على @NotNull().

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

  • أنواع Java: الأعداد الصحيحة → Long، والعشرية → Double، والمنطقية → Boolean، وYYYY-MM-DD → LocalDate، والتاريخ مع الوقت → LocalDateTime، والسلاسل الأخرى (بما فيها المكوّنة من أرقام فقط) → String.
  • تصبح الكائنات Map<String, Object> والمصفوفات List<...>، وكلاهما معلَّم بـ @JdbcTypeCode(SqlTypes.JSON) ليخزّنهما Hibernate 6 في عمود JSON.
  • يُبقي @Column(name = "guest_name") المفتاح الأصلي اسمًا للعمود كلما اختلف اسم الحقل في Java؛ والمفاتيح التي هي كلمات محجوزة في Java، مثل class، تصبح class_.
  • يتبع المفتاح الأساسي JSON الخاص بك: غياب id أو وجود id عددي صحيح يعطي @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id، والـ id النصي يعطي @Id private String id عاديًا.
  • الحقول الموجودة دائمًا تحصل على @NotEmpty() حين تكون سلاسل غير فارغة و@NotNull() في غير ذلك، لأن @NotEmpty لا ينطبق إلا على السلاسل والمجموعات.
  • يولّد @FieldNameConstants من Lombok ثوابت للأسماء مثل Reservation.Fields.guestName.

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

مهام دفعية تخزّن بيانات API خارجي

حين يجب سحب الحجوزات أو الطلبات من نظام آخر دوريًا وحفظها، يعطيك JSON استجابة واحدة الـ entity، ويتبعه سريعًا هيكل المهمة الدفعية حول saveAll().

جداول التطوير عبر `ddl-auto`

مع تفعيل spring.jpa.hibernate.ddl-auto=update محليًا، ينشئ Hibernate الجدول من الـ entity المولَّد، فيمكنك تحميل البيانات لعمل الواجهة فورًا.

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

  • تستهدف أسطر الاستيراد Jakarta EE (Spring Boot 3، Hibernate 6). على Spring Boot 2، أعد jakarta. إلى javax. واستبدل @JdbcTypeCode بـ converter، لأنه غير موجود في Hibernate 5.
  • 149.0 في JSON يُحلَّل إلى الرقم نفسه الذي يُحلَّل إليه 149، فيصبح Long. يحتاج الحقل العشري إلى قيمة كسرية في العيّنة ليخرج Double، والمبالغ المالية يخدمها BigDecimal بشكل أفضل.
  • الطوابع الزمنية ذات الإزاحة، مثل 2024-08-09T15:00:00+09:00، تفقد الإزاحة في LocalDateTime. استخدم OffsetDateTime أو Instant حين تهمّ اللحظة الزمنية بدقة.
  • أعمدة JSON تحتاج إلى قاعدة بيانات تدعمها (MySQL 5.7+، PostgreSQL، H2 2.x). للعلاقات الحقيقية، استبدل الـ Map بصنف @Embedded أو بعلاقة @OneToMany.

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

لماذا وضع @Column(name = ...) على حقول كان Spring سيربطها بصيغة snake_case على أي حال؟

استراتيجية التسمية الافتراضية في Spring Boot تحوّل guestName إلى guest_name مصادفةً، لكن ذلك ينكسر ما إن يكون مفتاح ما ليس snake_case بسيطًا أو تتغير الاستراتيجية. الاسم الصريح يُبقي الربط صحيحًا أيًّا كانت الإعدادات.

هل يُطبَّق @NotNull عند الحفظ؟

مع وجود spring-boot-starter-validation (Hibernate Validator) في الـ classpath، يشغّل Hibernate تحقق Bean Validation مباشرة قبل الحفظ والتحديث ويرمي ConstraintViolationException. ودونه تُتجاهل التعليقات التوضيحية.

ما فائدة @FieldNameConstants؟

يولّد Lombok ثوابت نصية مثل Reservation.Fields.checkIn. استخدمها في Sort.by(Reservation.Fields.checkIn) أو في استعلامات Specification/Criteria بدلًا من السلاسل الحرفية، فإعادة تسمية حقل تكسر البناء لا الاستعلام.