跨平台开发 / 系统课时
在 Repository 转换模型
在 Repository 转换模型
REST API 返回的是面向传输的 JSON,页面需要的却是稳定、可预测的业务类型。本节把 JSON 解析、DTO 构造和领域模型转换统一收口到 Repository,让 UI 与状态管理不再依赖接口字段细节。
学习目标
- 理解为什么 Repository 适合作为网络模型与领域模型的转换边界
- 能把 JSON → DTO → 领域模型的链路集中在数据层
- 能判断接口字段变化时应该修改哪一层
Repository 为什么是转换边界
页面直接读取 Map<String, dynamic>,短期看代码少,长期会把字段名、空值规则和状态编码扩散到 Widget、Provider 或 Bloc。接口一旦把 display_name 改名,修改范围就会从数据层蔓延到整个应用。
Repository 的职责不是简单转发 HTTP 结果,而是向上层提供稳定契约:网络层负责拿到 JSON,DTO 负责描述传输结构,Repository 负责完成解析与转换,页面只接触领域模型。

把 DTO 与领域模型分开
DTO 应尽量忠实于接口结构,例如保留 display_name、status 这类传输语义;领域模型则表达应用真正关心的概念,例如 displayName 和 isActive。二者分离后,接口字段重命名、状态编码调整或某些字段变为可空,都可以先在数据边界被吸收。
| 层次 | 关注点 | 是否暴露给页面 |
|---|---|---|
| JSON / DTO | 接口字段名、可空性、传输状态码 | 否 |
| Repository | 解析、校验、转换、错误归一化 | 否 |
| Domain Model | 页面和业务真正使用的稳定属性 | 是 |
完整转换示例
下面示例可保存为 main.dart 并直接运行。这里用假的 API Client 返回固定 JSON,目的是把转换边界完整展示出来;真实项目中只需把 FakeUserApi 替换为实际的 HTTP 实现。
abstract class UserApi {
Future<Map<String, dynamic>> fetchUser(String id);
}
class FakeUserApi implements UserApi {
@override
Future<Map<String, dynamic>> fetchUser(String id) async {
return {
'id': id,
'display_name': 'Ada',
'status': 'active',
};
}
}
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,
);
}
}
class User {
const User({
required this.id,
required this.displayName,
required this.isActive,
});
final String id;
final String displayName;
final bool isActive;
}
class UserRepository {
const UserRepository(this.api);
final UserApi api;
Future<User> getUser(String id) async {
final json = await api.fetchUser(id);
final dto = UserDto.fromJson(json);
return _toDomain(dto);
}
User _toDomain(UserDto dto) {
return User(
id: dto.id,
displayName: dto.displayName,
isActive: dto.status == 'active',
);
}
}
Future<void> main() async {
final repository = UserRepository(FakeUserApi());
final user = await repository.getUser('u-1');
print('${user.id} ${user.displayName} active=${user.isActive}');
}预期输出
u-1 Ada active=true如果项目里的 DTO 已由 Freezed 与 json_serializable 生成 fromJson,Repository 中的调用方式仍然相同:生成代码只替代 DTO 的机械解析工作,_toDomain() 仍由数据边界负责把传输语义变成业务语义。
处理解析失败和接口变化
Repository 应把数据层错误控制在边界内,但不要静默吞掉无效数据。必填字段类型错误时,让解析失败并转换成应用定义的数据异常;可选字段则在 DTO 中明确声明可空,再决定是否在 _toDomain() 提供默认值。
接口变化时可以按影响范围定位:字段名或嵌套结构变化先改 DTO;传输状态到业务状态的映射变化改转换逻辑;页面展示规则变化才进入 UI。这样可以避免为了一个接口字段改动而同步修改多个页面。
边界怎么验收
可以用三个检查点判断设计是否真正收口:页面代码里不出现接口字段名;状态管理层不调用 fromJson;替换 API Client 时,Repository 以上的代码无需跟着改。做到这三点后,REST 接口细节就被限制在可控的数据层中。