跨平台开发 / 系统课时
分离 DTO 与领域模型
分离 DTO 与领域模型
把 REST JSON 直接反序列化成页面和业务层共用的模型,起步很快,但接口字段一变就可能把影响扩散到整个应用。本节通过 DTO 到 Domain 的转换边界,说明如何把传输格式、兼容处理和业务约束分开,并判断什么时候值得承担这层映射成本。
学习目标
- 识别 API DTO 与领域模型分别应该表达什么
- 在 DTO 到 Domain 的映射中完成校验、默认值和语义转换
- 根据接口稳定性与业务复杂度判断是否需要保留独立转换边界
两种模型承担不同责任
DTO 面向接口契约,字段名和可空性通常由服务端决定。例如接口可能返回 display_name、可空的 status,甚至为了兼容旧版本暂时保留废弃字段。领域模型则面向客户端业务,应该使用业务能理解的命名、不变量和值对象。
如果两者直接共用一个类,传输层的小改动就可能迫使 UI、用例和测试一起变化。独立 DTO 的价值,是把这种变化集中在数据边界处。

在转换处吸收接口差异
下面的 Dart 示例不依赖代码生成,可以直接运行。DTO 保留服务端字段特征,toDomain() 则把字符串和可空值转换为领域层需要的稳定语义。
enum UserStatus { active, disabled }
final class UserId {
UserId(String value)
: value = value.isEmpty
? (throw const FormatException('user id is empty'))
: value;
final String value;
}
final class User {
const User({
required this.id,
required this.name,
required this.status,
});
final UserId id;
final String name;
final UserStatus status;
}
final class UserDto {
const UserDto({
required this.id,
required this.displayName,
required this.status,
});
final String id;
final String displayName;
final String? status;
factory UserDto.fromJson(Map<String, dynamic> json) {
return UserDto(
id: json['id'] as String,
displayName: json['display_name'] as String,
status: json['status'] as String?,
);
}
User toDomain() {
return User(
id: UserId(id),
name: displayName.trim(),
status: _mapStatus(status),
);
}
static UserStatus _mapStatus(String? value) {
if (value == null || value == 'active') {
return UserStatus.active;
}
if (value == 'disabled') {
return UserStatus.disabled;
}
throw FormatException('unsupported status: $value');
}
}
void main() {
final dto = UserDto.fromJson({
'id': 'u-100',
'display_name': ' Ada ',
'status': null,
});
final user = dto.toDomain();
print('${user.id.value}|${user.name}|${user.status.name}');
}预期输出
u-100|Ada|active这个边界做了三件事:把 display_name 转成领域命名 name,去掉展示名两端空白,并把接口的可空字符串状态收敛为领域枚举。示例约定 null 与 active 都表示启用;其他未知状态会抛出 FormatException,避免把未识别值静默解释成某个业务状态。
映射不是机械复制字段
DTO 到 Domain 最有价值的地方,是把“接口合法”转换成“业务合法”。例如接口允许空字符串,但业务要求 ID 永远非空;接口用字符串表达状态,但业务层希望编译器限制可选值。转换失败时,也应该在数据边界暴露,而不是让无效状态继续流入业务代码。
反过来,不要为了所谓分层而把二十个字段逐字复制到另一个完全相同的类。如果接口非常稳定、模型只是一次性展示、没有业务不变量,也没有多个数据源需要统一语义,直接使用 API 模型通常更省成本。
什么时候值得分离
当字段经常调整、同一业务对象来自 REST 与本地缓存等多个来源、业务层需要值对象或严格枚举,或者一个 API DTO 只代表服务端视图的一部分时,DTO 与 Domain 分离通常能明显缩小变更范围。
如果决定分离,最好让转换方向保持单一:网络层解析 DTO,映射器产出 Domain,业务层不再读取原始 JSON。这样测试也更清楚——DTO 测接口兼容,映射器测语义转换,领域模型测业务规则,各自失败时更容易定位。