Java 后端 / 系统课时

实现对象映射策略

实现对象映射策略

对象映射用于隔离接口 DTO、领域模型和持久化对象,避免任何一层的数据结构变化向其他层扩散。本课将比较手写映射与 MapStruct,建立明确的字段转换、空值处理和测试规则,并给出可直接复用的实现方式。

学习目标

  • 判断手写映射与 MapStruct 的适用场景
  • 为 DTO、领域对象和持久化对象设计单向转换
  • 使用测试锁定字段映射和边界行为

先确定映射边界

映射不是简单复制字段,而是在层与层之间执行语义转换。接口层的 CreateUserRequest 可以接受字符串形式的邮箱,领域层则应使用经过校验的 Email 值对象;持久化层可能把枚举保存为字符串。每个映射器只负责一条明确方向,例如“请求 DTO 到领域命令”或“领域对象到响应 DTO”,不要设计一个能任意互转的万能工具类。

映射规则还应明确空值、默认值和格式转换。对于必填字段,尽早拒绝空值;对于展示字段,可以在输出阶段格式化;涉及权限、金额或状态的字段,不应由客户端直接覆盖。

手写映射

手写映射适合规则少但包含业务语义的场景。它的优点是执行过程直观、调试方便,缺点是字段较多时容易遗漏。下面是片段示例,需放入同一 Java 包并由测试或应用服务调用;它把创建请求转换为领域命令,并显式处理姓名清洗和邮箱校验。

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()));
    }
}
java
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 依赖与编译插件配置如下。

xml
<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 会在生成源码目录创建映射器实现类。可使用以下命令验证。

bash
mvn clean compile

预期输出:

text
[INFO] BUILD SUCCESS

实际构建时间和本地路径可能不同,可分别视为 <TIME> 与 <PATH>。

映射接口可以通过表达式或辅助方法处理值对象。以下为片段示例,依赖前述 MapStruct 配置和 Spring 容器。

java
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);
}
java
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 和前述手写映射类。

java
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());
    }
}

预期输出:

text
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

字段少、规则复杂、需要逐步调试时优先手写;字段多、转换稳定、希望通过编译检查漏字段时优先 MapStruct。实际项目可以混用:MapStruct 负责机械字段复制,手写方法负责值对象构造、格式清洗和明确的业务边界。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

实现对象映射策略

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通