แปลงเอนทิตี JPAเป็น JSON!

ป้อนเอนทิตี JPAเพื่อสร้าง JSON ตัวอย่าง! รองรับ JPA @Entity, Hibernate, Spring Boot เหมาะสำหรับเอกสาร API และ request body สำหรับทดสอบ (mock request body)
JPA
ผลลัพธ์
 

แปลงเอนทิตี JPAเป็น JSON!

วางคลาส @Entity ของ Spring Boot JPA แล้วดู JSON ตัวอย่างในรูปที่ Jackson สร้างเมื่อ controller คืน entity เหล่านั้น ชื่อฟิลด์ @JsonIgnore และ @JsonProperty ฟิลด์ที่สืบทอดจาก @MappedSuperclass และไทป์วันที่ของ Java 8 ถูกจัดการทั้งหมดตามการตั้งค่า Jackson ค่าเริ่มต้นของ Spring Boot

ใช้สำหรับตัวอย่างใน REST Docs หรือ Swagger request body ของ Postman หรือตรวจว่าฟิลด์ไหนหลุดออกไปเมื่อเปิดเผย entity โดยไม่มี DTO

วิธีใช้

  1. วางคลาส entity ลงในช่อง JPA ไม่ต้องลบ import และ annotation ของ Lombok ให้ใส่คลาส parent, entity ที่สัมพันธ์กัน และ enum ไว้ด้วยเพื่อให้ค่าถูกเติม
  2. คลาสที่ไม่มีคลาสอื่นอ้างถึงจะเป็นราก ถ้า entity อ้างถึงกันไปมา จะเลือกคลาสที่เป็น 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 ที่ไม่มี offset และ enum แสดงค่าคงที่ตัวแรกคือ "BOOKED"

ฟีเจอร์ที่รองรับ

  • ฟิลด์ static และ transient และฟิลด์ที่มี @JsonIgnore ถูกข้าม รวมถึงชื่อที่ระบุใน @JsonIgnoreProperties({"..."}) ระดับคลาส
  • @JsonProperty("doctor_name") เปลี่ยนชื่อคีย์ JSON
  • เมื่อคลาส parent (@MappedSuperclass หรือ extends ใด ๆ) อยู่ในอินพุต ฟิลด์ของมันจะมาก่อน
  • ค่าเริ่มต้นใน entity อย่าง private Status status = Status.ACTIVE; หรือ private int visits = 0; แสดงเป็นค่านั้น และ getter คำนวณที่ไม่มีฟิลด์รองรับ (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
  • wrapper ตัวเลขอย่าง 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 = ...) หรือ snippet ของเอกสารจาก entity โดยตรง และวางใหม่ทุกครั้งที่ฟิลด์เปลี่ยนเพื่อให้เอกสารตรงกับโค้ด

ตรวจ entity ที่ถูกเปิดเผย

ถ้าคืน entity โดยไม่มี DTO ให้ตรวจว่าฟิลด์อย่างรหัสผ่านหรือเลขประจำตัวประชาชนหลุดไปใน response หรือไม่ ฟิลด์ในผลลัพธ์คือฟิลด์ที่ Jackson จะ serialize

request body สำหรับ MockMvc

ใช้ผลลัพธ์เป็นโครงสำหรับ mockMvc.perform(post("/appointments").content(...)) โดยลบ id และ timestamp ที่สร้างขึ้นก่อนเติมค่า

ข้อควรระวังและข้อจำกัด

  • Jackson จริงจะวนไม่จบ (StackOverflowError) กับความสัมพันธ์สองทาง ถ้าผลลัพธ์ดูถูกตัด นั่นคือสัญญาณให้ใช้ @JsonManagedReference/@JsonBackReference, @JsonIgnore หรือ DTO
  • annotation @Transient ของ JPA ไม่ถูก Jackson เพิกเฉยโดยค่าเริ่มต้น ฟิลด์เหล่านั้นจึงยังอยู่ในผลลัพธ์ มีแค่ฟิลด์ที่ใช้คีย์เวิร์ด transient ของ Java ที่ถูกตัดออก
  • ความสัมพันธ์ FetchType.LAZY อาจ serialize ไม่ได้ในทางปฏิบัติเพราะเป็น Hibernate proxy แต่ผลลัพธ์สมมติว่าทุกอย่างถูกโหลดแล้ว
  • ฟิลด์ที่คลาสไม่อยู่ในอินพุตแสดงเป็น null และข้อจำกัดของ @Column อย่าง nullable หรือ length ไม่ถูกนำมาใช้

คำถามที่พบบ่อย

วันที่ควรเป็นสตริงจริง ๆ หรือ ไม่ใช่อาร์เรย์อย่าง [2024,1,1]?

Spring Boot ปิด WRITE_DATES_AS_TIMESTAMPS ไว้ LocalDateTime จึงถูกเขียนเป็นสตริง ISO ส่วน ObjectMapper ที่สร้างเองและลงทะเบียนแค่ JavaTimeModule อาจเขียนเป็นอาร์เรย์แทน

ทุกฟิลด์แสดงแม้ไม่มี Lombok @Getter เลยหรือ?

เครื่องมือทำงานจากการประกาศฟิลด์ แต่ Jackson จริง serialize ผ่าน getter (หรือฟิลด์ public) โดยค่าเริ่มต้น ฟิลด์ private ที่ไม่มี getter จึงอาจไม่อยู่ใน response จริง

วางคลาส @Document ของ MongoDB ได้ด้วยไหม?

ใช้กฎของ Jackson แบบเดียวกัน แต่ข้อควรระวังเฉพาะของ MongoDB อย่าง ObjectId และ @Field อธิบายไว้ในหน้า Spring Data MongoDB to JSON