Java 后端 / 系统课时
实现对象映射策略
实现对象映射策略
对象映射用于隔离接口 DTO、领域模型和持久化对象,避免任何一层的数据结构变化向其他层扩散。本课将比较手写映射与 MapStruct,建立明确的字段转换、空值处理和测试规则,并给出可直接复用的实现方式。
学习目标
- 判断手写映射与 MapStruct 的适用场景
- 为 DTO、领域对象和持久化对象设计单向转换
- 使用测试锁定字段映射和边界行为
先确定映射边界
映射不是简单复制字段,而是在层与层之间执行语义转换。接口层的 CreateUserRequest 可以接受字符串形式的邮箱,领域层则应使用经过校验的 Email 值对象;持久化层可能把枚举保存为字符串。每个映射器只负责一条明确方向,例如“请求 DTO 到领域命令”或“领域对象到响应 DTO”,不要设计一个能任意互转的万能工具类。
映射规则还应明确空值、默认值和格式转换。对于必填字段,尽早拒绝空值;对于展示字段,可以在输出阶段格式化;涉及权限、金额或状态的字段,不应由客户端直接覆盖。
手写映射
手写映射适合规则少但包含业务语义的场景。它的优点是执行过程直观、调试方便,缺点是字段较多时容易遗漏。下面是片段示例,需放入同一 Java 包并由测试或应用服务调用;它把创建请求转换为领域命令,并显式处理姓名清洗和邮箱校验。
package com.example.user.application;
public final class UserMapper {
private UserMapper() {
}
public static CreateUserCommand toCommand(CreateUserRequest request) {
if (request == null) {
throw new IllegalArgumentException("请求不能为空");
}
String name = request.name() == null ? "" : request.name().trim();
if (name.isBlank()) {
throw new IllegalArgumentException("姓名不能为空");
}
return new CreateUserCommand(name, new Email(request.email()));
}
}package com.example.user.application;
record CreateUserRequest(String name, String email) {
}
record CreateUserCommand(String name, Email email) {
}
record Email(String value) {
public Email {
if (value == null || !value.matches("^[^@]+@[^@]+\\.[^@]+$")) {
throw new IllegalArgumentException("邮箱格式不正确");
}
}
}预期结果:输入姓名 " Alice " 和邮箱 "alice@example.com" 时,得到姓名为 "Alice" 的 CreateUserCommand;邮箱格式错误或姓名为空时抛出 IllegalArgumentException。
使用 MapStruct
当字段多、映射方向稳定且主要是结构转换时,MapStruct 可以在编译期生成实现类。它不会通过反射运行,因此性能和手写代码接近,同时能在字段缺失时通过编译告警暴露问题。Maven 依赖与编译插件配置如下。
<properties>
<org.mapstruct.version>1.6.3</org.mapstruct.version>
</properties>
<dependencies>
<dependency>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct</artifactId>
<version>${org.mapstruct.version}</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<annotationProcessorPaths>
<path>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>${org.mapstruct.version}</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
</plugins>
</build>生效行为:执行 Maven 编译后,MapStruct 会在生成源码目录创建映射器实现类。可使用以下命令验证。
mvn clean compile预期输出:
[INFO] BUILD SUCCESS实际构建时间和本地路径可能不同,可分别视为 <TIME> 与 <PATH>。
映射接口可以通过表达式或辅助方法处理值对象。以下为片段示例,依赖前述 MapStruct 配置和 Spring 容器。
package com.example.user.application;
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.ReportingPolicy;
@Mapper(
componentModel = "spring",
unmappedTargetPolicy = ReportingPolicy.ERROR
)
public interface UserResponseMapper {
@Mapping(target = "email", expression = "java(user.email().value())")
UserResponse toResponse(User user);
}package com.example.user.application;
record UserResponse(String id, String name, String email) {
}
record User(String id, String name, Email email) {
}这里将 unmappedTargetPolicy 设为 ERROR,新增目标字段但未配置映射时会直接编译失败,能够防止静默漏字段。对于包含复杂条件、仓储查询或权限判断的转换,不应塞进 MapStruct 表达式,而应由应用服务先完成业务决策,再交给映射器做结构转换。
测试并选择策略
映射测试应关注字段语义和边界,而不是测试框架生成代码本身。手写映射要覆盖正常值、空值和非法值;MapStruct 映射要断言关键字段、枚举和值对象是否按约定转换。下面的测试依赖 JUnit 5 和前述手写映射类。
package com.example.user.application;
import static org.junit.jupiter.api.Assertions.assertEquals;
import org.junit.jupiter.api.Test;
class UserMapperTest {
@Test
void shouldTrimNameAndCreateEmailValueObject() {
CreateUserRequest request =
new CreateUserRequest(" Alice ", "alice@example.com");
CreateUserCommand command = UserMapper.toCommand(request);
assertEquals("Alice", command.name());
assertEquals("alice@example.com", command.email().value());
}
}预期输出:
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0字段少、规则复杂、需要逐步调试时优先手写;字段多、转换稳定、希望通过编译检查漏字段时优先 MapStruct。实际项目可以混用:MapStruct 负责机械字段复制,手写方法负责值对象构造、格式清洗和明确的业务边界。