Spring Boot中单值对象JSON序列化扁平化处理教程

本文旨在解决spring boot应用中，将包含单值java对象的实体序列化为json时，出现嵌套结构而非扁平化字符串的问题。通过引入数据传输对象（dto）模式，我们将详细演示如何重构数据模型和api响应，以实现更简洁、符合预期的json输出格式，同时提升api设计的灵活性与安全性。

在构建基于Spring Boot和Hibernate的RESTful服务时，我们经常会遇到将领域模型对象转换为JSON响应的需求。然而，当领域模型中包含一些本质上是“单值对象”（Value Object），例如包装了字符串的EmailAddress类时，默认的JSON序列化行为可能会导致不必要的嵌套结构，这与我们期望的扁平化表示不符。

问题场景描述

假设我们有一个EmailAddress类，它封装了一个电子邮件地址的字符串值以及一些相关业务逻辑（如获取域名、邮箱等）。

// EmailAddress.java
public class EmailAddress {
    public String value; // 实际的邮箱地址字符串

    public EmailAddress(String value) {
        this.value = value;
    }

    // 假设还有其他业务方法，如tld(), host(), mailbox()等
    public String tld() { /* ... */ return "com"; }
    public String host() { /* ... */ return "example.com"; }
    public String mailbox() { /* ... */ return "user"; }

    // 为了方便演示，添加getter
    public String getValue() {
        return value;
    }
}

接着，这个EmailAddress类被用作Customer实体的一个字段：

// Customer.java
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;

@Entity
public class Customer {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private EmailAddress mail; // 使用EmailAddress对象

    // 构造函数、getter/setter略
    public Customer() {}

    public Customer(String name, EmailAddress mail) {
        this.name = name;
        this.mail = mail;
    }

    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public EmailAddress getMail() { return mail; }
    public void setMail(EmailAddress mail) { this.mail = mail; }
}

当通过Spring Boot的REST服务暴露Customer实体时，默认的Jackson序列化器会将其中的EmailAddress对象视为一个普通的POJO，并将其内部的value字段也序列化出来，导致生成如下的JSON结构：

{
    "id": 1,
    "name": "Test",
    "mail": {
        "value": "test@example.com"
    }
}

然而，我们期望的输出是更简洁的扁平化结构，直接将mail字段表示为字符串：

{
    "id": 1,
    "name": "Test",
    "mail": "test@example.com"
}

解决方案：引入数据传输对象（DTO）

为了解决这个问题，最推荐且最灵活的方法是引入数据传输对象（DTO）。DTO是一种设计模式，用于在应用程序的不同层之间传输数据。它将API响应与内部领域模型解耦，允许我们精确控制API的输出格式。

1. 定义DTO类

首先，为我们的API响应定义一个CustomerDTO类。在这个DTO中，我们将EmailAddress字段扁平化为一个简单的String类型。

// CustomerDTO.java
public class CustomerDTO {
    private Long id;
    private String name;
    private String email; // 将EmailAddress扁平化为String

    // 构造函数、getter/setter
    public CustomerDTO() {}

    public CustomerDTO(Long id, String name, String email) {
        this.id = id;
        this.name = name;
        this.email = email;
    }

    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
}

2. 实现实体到DTO的映射

接下来，我们需要在服务层或控制器层实现从Customer实体到CustomerDTO的映射逻辑。这可以通过手动创建DTO实例、使用构造函数、或者利用专门的映射库（如ModelMapper、MapStruct）来完成。

手动映射示例：

// CustomerService.java (示例服务层)
import org.springframework.stereotype.Service;
import java.util.List;
import java.util.stream.Collectors;

@Service
public class CustomerService {

    // 假设这里有CustomerRepository或其他数据访问层
    // private final CustomerRepository customerRepository;

    // 构造函数注入略

    public CustomerDTO getCustomerById(Long id) {
        // 假设从数据库获取Customer实体
        Customer customer = new Customer(
            "Test", new EmailAddress("test@example.com")
        ); // 模拟从数据库获取
        customer.setId(id);

        return mapToDTO(customer);
    }

    public List getAllCustomers() {
        // 假设从数据库获取所有Customer实体
        List customers = List.of(
            new Customer("Alice", new EmailAddress("alice@example.com")),
            new Customer("Bob", new EmailAddress("bob@example.com"))
        );
        customers.get(0).setId(1L);
        customers.get(1).setId(2L);

        return customers.stream()
                        .map(this::mapToDTO)
                        .collect(Collectors.toList());
    }

    private CustomerDTO mapToDTO(Customer customer) {
        if (customer == null) {
            return null;
        }
        return new CustomerDTO(
            customer.getId(),
            customer.getName(),
            customer.getMail() != null ? customer.getMail().getValue() : null
        );
    }

    // 如果需要处理传入的DTO，也需要实现DTO到实体的映射
    public Customer saveCustomer(CustomerDTO customerDTO) {
        Customer customer = mapToEntity(customerDTO);
        // 保存customer到数据库
        return customer;
    }

    private Customer mapToEntity(CustomerDTO customerDTO) {
        if (customerDTO == null) {
            return null;
        }
        return new Customer(
            customerDTO.getName(),
            customerDTO.getEmail() != null ? new EmailAddress(customerDTO.getEmail()) : null
        );
    }
}

3. 更新REST控制器

最后，修改您的REST控制器，使其返回CustomerDTO对象而不是Customer实体。

// CustomerController.java
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;

@RestController
@RequestMapping("/api/customers")
public class CustomerController {

    private final CustomerService customerService;

    public CustomerController(CustomerService customerService) {
        this.customerService = customerService;
    }

    @GetMapping("/{id}")
    public CustomerDTO getCustomer(@PathVariable Long id) {
        return customerService.getCustomerById(id);
    }

    @GetMapping
    public List getAllCustomers() {
        return customerService.getAllCustomers();
    }
}

现在，当您访问/api/customers/1时，将会得到期望的扁平化JSON响应：

{
    "id": 1,
    "name": "Test",
    "email": "test@example.com"
}

注意事项与最佳实践

1. 映射库的选择： 对于复杂的实体和DTO映射，手动编写映射代码会变得繁琐且容易出错。推荐使用成熟的映射库：

   • ModelMapper： 运行时反射映射，配置简单，但性能略低于编译时映射。
   • MapStruct： 编译时代码生成，性能优异，但需要更多配置。

2. DTO的职责： DTO应专注于数据传输，不包含业务逻辑。它通常只包含字段、构造函数、getter和setter。

3. 双向映射： 在处理POST/PUT请求时，您可能还需要实现从DTO到实体的映射。确保在映射过程中处理好可能的空值和数据转换。

4. 数据验证： 可以在DTO上使用JSR 303/349 (Bean Validation) 注解（如@NotBlank, @Email等）来对传入的数据进行验证，从而将验证逻辑与领域模型分离。

5. 安全性： 使用DTO可以避免在API响应中暴露敏感的内部实体字段，从而提高安全性。

6. @JsonValue注解（替代方案）： 如果EmailAddress对象在任何JSON序列化场景下都应该被表示为一个简单的字符串，那么可以直接在EmailAddress类上使用@JsonValue注解。

   // EmailAddress.java
   import com.fasterxml.jackson.annotation.JsonValue;
   
   public class EmailAddress {
       public String value;
   
       public EmailAddress(String value) {
           this.value = value;
       }
   
       @JsonValue // 标记此方法返回的值作为JSON序列化的内容
       public String getValue() {
           return value;
       }
       // 其他方法...
   }

   这种方式更简洁，但不如DTO灵活，因为它强制了EmailAddress的单一JSON表示。如果EmailAddress在不同上下文需要不同的JSON表示，DTO是更好的选择。

总结

通过采用数据传输对象（DTO）模式，我们能够有效地解决Spring Boot中单值对象默认JSON序列化为嵌套结构的问题。DTO不仅能帮助我们实现扁平化的JSON输出，还带来了API与领域模型解耦、增强数据验证、提升安全性和灵活性的诸多优势。在实际开发中，结合映射库的使用，可以进一步提高开发效率和代码质量。

# ai  # app  # js  # json  # java  # stream  # string类  # 数据访问  # 邮箱 

相关栏目： <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 AI推广<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 SEO优化<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 技术百科<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 谷歌推广<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 百度推广<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 网络营销<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 案例网站<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 精选文章<？ｍｕｍａ echo $count; ?> 】