Chuyển entity JPA thành JSON!

Nhập entity JPA để tạo JSON mẫu! Hỗ trợ JPA @Entity, Hibernate, Spring Boot. Hữu ích cho tài liệu API và request body thử nghiệm (mock request body).
JPA
Kết quả
 

Chuyển entity JPA thành JSON!

Dán các class @Entity của Spring Boot JPA để xem JSON ví dụ theo đúng hình dạng Jackson tạo ra khi controller trả về các entity đó. Tên field, @JsonIgnore và @JsonProperty, field kế thừa từ @MappedSuperclass, và kiểu ngày giờ của Java 8 đều được xử lý theo thiết lập Jackson mặc định của Spring Boot.

Dùng nó cho ví dụ của REST Docs hay Swagger, body request của Postman, hoặc để rà soát những field nào bị lộ ra khi entity được trả về mà không qua DTO.

Cách sử dụng

  1. Dán các class entity vào ô JPA. Import và annotation Lombok có thể để lại; hãy đưa vào cả class cha, entity có quan hệ và enum để giá trị của chúng được điền.
  2. Class không bị class nào khác tham chiếu sẽ thành gốc. Khi các entity tham chiếu lẫn nhau, class public được chọn.
  3. Sao chép kết quả vào test hoặc tài liệu.

Ví dụ

Đầu vào (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;
}
Đầu ra (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 và Patient tham chiếu lẫn nhau, nên class public Appointment là gốc và Patient.appointments bị cắt thành mảng rỗng thay vì lặp vô hạn. id và createdAt từ BaseEntity đứng đầu, còn residentNumber biến mất vì @JsonIgnore. LocalDateTime là chuỗi ISO không có offset, và enum hiện hằng đầu tiên, "BOOKED".

Tính năng hỗ trợ

  • Field static và transient cùng field có @JsonIgnore bị bỏ qua, các tên liệt kê trong @JsonIgnoreProperties({"..."}) ở cấp class cũng vậy.
  • @JsonProperty("doctor_name") đổi tên key JSON.
  • Khi class cha (@MappedSuperclass hoặc bất kỳ extends nào) có trong đầu vào, field của nó đứng trước.
  • Giá trị mặc định của entity như private Status status = Status.ACTIVE; hay private int visits = 0; hiện ra đúng giá trị đó, và getter tính toán không có field tương ứng (public int getAge()) xuất hiện thành key bổ sung, đúng như Jackson sẽ xuất ra.
  • Output ngày giờ theo mặc định của Spring Boot: LocalDate → 1970-01-01, LocalDateTime → 1970-01-01T00:00:00, java.util.Date → 1970-01-01T00:00:00.000+00:00.
  • Wrapper số như BigDecimal và Long cho 0, UUID cho UUID toàn số 0, và byte[] cho chuỗi base64 "AA==".
  • List/Set cho mảng một phần tử, Map<Long, String> cho object có key tương ứng ({"0": ""}), và Optional<T> được mở thành giá trị bên trong.
  • Quan hệ hai chiều (@OneToMany với @ManyToOne) được cắt bằng null hoặc mảng rỗng ở chỗ chúng vòng lại.

Trường hợp sử dụng

Ví dụ cho Spring REST Docs và Swagger

Tạo JSON cho @Schema(example = ...) hoặc snippet tài liệu thẳng từ entity, và dán lại mỗi khi field thay đổi để tài liệu luôn đồng bộ.

Rà soát entity bị lộ ra ngoài

Nếu bạn trả entity mà không qua DTO, hãy kiểm tra xem các field như mật khẩu hay số định danh cá nhân có lọt vào response không. Field trong output chính là những field Jackson sẽ serialize.

Body request cho MockMvc

Dùng output làm khung cho mockMvc.perform(post("/appointments").content(...)), bỏ id và timestamp được tạo trước khi điền giá trị.

Lưu ý và giới hạn

  • Jackson thật sẽ đệ quy vô hạn (StackOverflowError) với quan hệ hai chiều. Nếu output trông như bị cắt, đó là tín hiệu để dùng @JsonManagedReference/@JsonBackReference, @JsonIgnore hoặc DTO.
  • Annotation @Transient của JPA mặc định không bị Jackson bỏ qua, nên các field đó vẫn ở trong output; chỉ field có từ khóa transient của Java mới bị loại.
  • Quan hệ FetchType.LAZY trong thực tế có thể serialize thất bại dưới dạng proxy của Hibernate; output giả định mọi thứ đã được nạp.
  • Field có class không nằm trong đầu vào hiện thành null, và ràng buộc @Column như nullable hay length không được áp dụng.

Câu hỏi thường gặp

Ngày tháng có thật sự là chuỗi chứ không phải mảng như [2024,1,1]?

Spring Boot tắt WRITE_DATES_AS_TIMESTAMPS, nên LocalDateTime được ghi thành chuỗi ISO. Một ObjectMapper tự dựng chỉ đăng ký JavaTimeModule có thể ghi thành mảng.

Không có Lombok @Getter thì mọi field có hiện ra không?

Công cụ làm việc từ khai báo field. Jackson thật mặc định serialize qua getter (hoặc field public), nên field private không có getter có thể bị thiếu trong response thực tế.

Có dán class @Document của MongoDB được không?

Chúng theo cùng quy tắc Jackson, nhưng các lưu ý riêng của MongoDB như ObjectId và @Field được đề cập trên trang Spring Data MongoDB to JSON.