MyBatis/MyBatis-Plus 多表查询返回实体的陷阱与 DTO 应对方案

多表查询时，让 Mapper 方法直接返回数据库实体（Entity），这究竟合不合理？

先说结论：不合理，但很常见。

技术上，这样写程序能跑通；但在工程实践上，它埋下了巨大的隐患。

一、为什么开发者倾向于直接返回实体？

先看一个典型的写法，在 MyBatis 中可能是这样的：

@Select("""
    SELECT u.*, r.name AS roleName
    FROM user u
    LEFT JOIN role r ON u.role_id = r.id
""")
User selectUserWithRole(Long id);

开发者这么做，原因通常很简单：

• 省事：少定义一个新的数据传输对象（DTO）或视图对象（VO）。
• 方便：实体类（如 User）的字段是现成的，查询结果可以直接映射。
• 快捷：查完数据后，实体对象能直接用于后续业务逻辑或展示。

这看似省事的做法，真的合理吗？短期来看确实提高了开发速度，但问题会在字段不匹配或业务场景复杂化时集中爆发。

二、多表查询返回实体存在哪些问题？

1. 实体遭遇“数据污染”

为了接收 JOIN 查询产生的、不属于本表的字段（例如上述SQL中的 roleName），你不得不在 User 实体类中添加一个数据库表中不存在的字段：

private String roleName;

这样做的直接后果是：

• 实体类不再纯粹地对应数据库表结构。
• 实体变得臃肿，混杂了来自其他表的字段。
• 团队成员难以分辨哪些是真正的表字段，哪些是“嫁接”过来的查询字段。

实体不再等于表结构，其语义变得模糊不清。

2. 写操作风险急剧升高

当这个被“污染”的实体对象被用于更新操作时，危险悄然来临：

userMapper.updateById(user);

你需要时刻警惕：

• 哪些字段应该被更新到数据库（如 name, email）？
• 哪些字段是查询附加的，绝对不能写回数据库（如 roleName）？

一旦有开发者在不知情或疏忽的情况下，将包含非表字段的实体用于全字段更新，极易产生脏数据，且这类问题通常隐蔽且难以排查。

3. 实体复用与维护成本飙升

随着业务发展，不同场景对数据的需求各不相同：

• 列表页可能只需要用户ID、名称和角色名。
• 详情页需要额外展示邮箱、手机号。
• 导出功能又需要关联部门的名称。

如果所有场景都强行复用同一个被不断“增肥”的实体，它最终会变成一个满足所有需求但又让所有人望而却步的“巨无霸”：谁都在用，但谁都不敢轻易修改，维护成本成指数级增长。关于如何规范代码结构和设计模式，可以参考 云栈社区 上的相关讨论。

三、更清晰、更安全的最佳实践是什么？

1. 多表查询请使用 DTO / VO

为特定的多表查询场景创建专属的数据传输对象（DTO）或视图对象（VO）。这是处理 数据库 关联查询的推荐方式。

public class UserDetailVO {
    private Long id;
    private String name;
    private String roleName; // 明确来自关联查询
    // 其他需要展示的字段...
}

Mapper 接口也应当明确返回这个类型：

UserDetailVO selectUserDetail(Long id);

这样做最大的好处就是：职责清晰。UserDetailVO 的结构一目了然，它就是为“用户详情”这个视图场景服务的，不掺杂任何歧义。

2. 严格区分实体与业务模型的职责

建立一个简单的规则，可以有效避免混乱：

• 单表 CRUD 操作 → 使用 Entity（实体）。
• 多表关联查询、复杂业务数据聚合 → 使用 DTO / VO。

让实体类专心负责与数据库表结构的映射和单表操作。让 DTO / VO 来承担在业务层、控制层之间传递数据，以及面向前端或外部API的数据展示职责。掌握不同类型对象的使用场景，是编写高质量 技术文档 和代码的基础。

核心总结：实体一旦被多表关联查询的结果“污染”，其纯洁性和可维护性就会遭到破坏，后期的技术债务会像滚雪球一样越来越大。为不同的数据流动场景定义专门的对象，是保持代码清晰、可维护的关键。