当java对象包含嵌套结构，而api响应仅需其简单值时，默认的json序列化可能过于冗长。本教程将详细介绍如何通过引入数据传输对象（dto）模式，有效简化spring boot应用中的api响应，将复杂的内部对象转换为简洁的单值表示，从而提升api的清晰度和易用性。
引言
在构建基于Spring Boot的RESTful API时，我们经常会遇到将领域模型（Entities）直接暴露给客户端的情况。然而，领域模型通常包含丰富的业务逻辑和复杂的对象关系，这在JSON序列化时可能导致API响应过于冗长或暴露不必要的内部细节。特别地，当一个领域对象中包含另一个“单值对象”（即该对象的核心价值可以由一个简单的基本类型表示）时，默认的JSON表示会将其序列化为一个嵌套的JSON对象，而非我们期望的简单值。
例如，一个EmailAddress类如果只包含一个value字段，当它作为另一个实体（如Customer）的属性时，其默认JSON表示会是"email": { "value": "test@example.com" }，而我们往往希望得到更简洁的"email": "test@example.com"。
问题场景：冗余的JSON表示
假设我们有以下Java类结构：
// EmailAddress是一个单值对象，其核心是邮箱字符串
public class EmailAddress {
public String value;
// 构造函数、getter/setter等省略
public EmailAddress(String value) {
this.value = value;
}
// 其他业务方法，如tld(), host(), mailbox()等
public String tld() { /* ... */ return value.substring(value.lastIndexOf('.') + 1); }
public String host() { /* ... */ return value.substring(value.indexOf('@') + 1, value.lastIndexOf('.')); }
public String mailbox() { /* ... */ return value.substring(0, value.indexOf('@')); }
}以及一个使用EmailAddress的实体类：
立即学习“Java免费学习笔记（深入）”；
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
@Entity
public class Customer {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
private String name;
private EmailAddress mail; // 假设EmailAddress通过某种方式被持久化，例如@Embedded或自定义转换器
// 构造函数、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对象时，默认的JSON序列化结果可能会是这样：
{
"id": 1,
"name": "Test Customer",
"mail": {
"value": "test@example.com"
}
}这与我们期望的简洁格式"mail": "test@example.com"不符。
解决方案：使用数据传输对象（DTO）
解决此类问题的最佳实践是引入数据传输对象（Data Transfer Object, DTO）。DTO是一种设计模式，用于在不同层之间传输数据。在API设计中，DTO的作用是定义API的契约，它通常是实体（Entity）的简化或聚合视图，专门用于输入或输出。
DTO的优势
- 控制API响应结构： DTO允许我们精确定义API返回的JSON结构，避免暴露不必要的内部字段。
- 解耦领域模型与API契约： 领域模型可以自由演进，而不直接影响API的外部契约。
- 安全性： 避免敏感数据通过API泄露。
- 性能： 只传输必要的数据，减少网络负载。
实现步骤
1. 定义DTO类
为Customer实体创建一个对应的CustomerDTO。在这个DTO中，我们将EmailAddress属性简化为一个String类型。
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. 在REST控制器中使用DTO
在Spring Boot的REST控制器中，不再直接返回Customer实体，而是返回CustomerDTO。这意味着我们需要在从数据库获取实体后，将其转换为DTO。
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 org.springframework.http.ResponseEntity;
@RestController
@RequestMapping("/api/customers")
public class CustomerController {
private final CustomerService customerService; // 假设有一个CustomerService来处理业务逻辑
public CustomerController(CustomerService customerService) {
this.customerService = customerService;
}
@GetMapping("/{id}")
public ResponseEntity<CustomerDTO> getCustomerById(@PathVariable Long id) {
// 从服务层获取Customer实体
Customer customer = customerService.findCustomerById(id);
if (customer == null) {
return ResponseEntity.notFound().build();
}
// 将Customer实体转换为CustomerDTO
CustomerDTO customerDTO = new CustomerDTO(
customer.getId(),
customer.getName(),
customer.getMail().value // 直接获取EmailAddress的value字段
);
return ResponseEntity.ok(customerDTO);
}
}3. 实体到DTO的转换（通常在服务层或专用Mapper中）
实际项目中，通常会在服务层或专门的映射器（Mapper）中执行实体到DTO的转换逻辑。这有助于保持控制器层的简洁性。
import org.springframework.stereotype.Service;
@Service
public class CustomerService {
private final CustomerRepository customerRepository; // 假设有一个CustomerRepository
public CustomerService(CustomerRepository customerRepository) {
this.customerRepository = customerRepository;
}
public Customer findCustomerById(Long id) {
return customerRepository.findById(id).orElse(null);
}
// 假设这是将实体转换为DTO的方法，可以在Service层提供
public CustomerDTO convertToDto(Customer customer) {
if (customer == null) {
return null;
}
return new CustomerDTO(
customer.getId(),
customer.getName(),
customer.getMail() != null ? customer.getMail().value : null
);
}
}在控制器中调用：
// ... (CustomerController)
@GetMapping("/{id}")
public ResponseEntity<CustomerDTO> getCustomerById(@PathVariable Long id) {
Customer customer = customerService.findCustomerById(id);
if (customer == null) {
return ResponseEntity.notFound().build();
}
CustomerDTO customerDTO = customerService.convertToDto(customer); // 使用服务层的方法转换
return ResponseEntity.ok(customerDTO);
}经过上述改造，当访问/api/customers/1时，API响应将是：
{
"id": 1,
"name": "Test Customer",
"email": "test@example.com"
}这正是我们期望的简洁JSON表示。
注意事项与进阶
双向映射： 如果API需要接收DTO作为输入（例如，创建或更新Customer），则需要实现DTO到实体的反向映射。
映射工具： 对于复杂的实体和DTO结构，手动编写转换代码会变得繁琐。可以使用MapStruct或ModelMapper等库来自动化映射过程，大大提高开发效率和代码可维护性。
-
Jackson注解： 对于非常简单的单值对象，也可以考虑在EmailAddress类上使用Jackson的@JsonValue注解，使其在序列化时直接输出其值。
import com.fasterxml.jackson.annotation.JsonValue; public class EmailAddress { public String value; public EmailAddress(String value) { this.value = value; } @JsonValue // 当EmailAddress对象被序列化时，直接使用此方法返回值 public String getValue() { return value; } // 其他方法... }这种方法可以直接作用于EmailAddress对象本身，使其在任何被序列化的地方都表现为字符串。然而，对于控制整个API响应结构而言，DTO仍然是更灵活和推荐的做法，因为它提供了更强的隔离和定制能力。
总结
通过引入数据传输对象（DTO）模式，我们能够有效地控制Spring Boot RESTful API的JSON响应格式，将复杂的内部Java对象（如单值对象）转换为简洁的、符合API契约的表示。这不仅简化了客户端的解析工作，提高了API的可读性和易用性，还有助于实现领域模型与API契约的解耦，提升了系统的可维护性和安全性。在实际项目中，结合使用映射工具可以进一步优化DTO的实现效率。
