跨平台开发 / 系统课时

在 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 负责完成解析与转换,页面只接触领域模型。

REST API 到领域模型的数据边界

把 DTO 与领域模型分开

DTO 应尽量忠实于接口结构,例如保留 display_name、status 这类传输语义;领域模型则表达应用真正关心的概念,例如 displayName 和 isActive。二者分离后,接口字段重命名、状态编码调整或某些字段变为可空,都可以先在数据边界被吸收。

层次 关注点 是否暴露给页面
JSON / DTO 接口字段名、可空性、传输状态码 否
Repository 解析、校验、转换、错误归一化 否
Domain Model 页面和业务真正使用的稳定属性 是

完整转换示例

下面示例可保存为 main.dart 并直接运行。这里用假的 API Client 返回固定 JSON,目的是把转换边界完整展示出来;真实项目中只需把 FakeUserApi 替换为实际的 HTTP 实现。

dart
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}');
}

预期输出

text
u-1 Ada active=true

如果项目里的 DTO 已由 Freezed 与 json_serializable 生成 fromJson,Repository 中的调用方式仍然相同:生成代码只替代 DTO 的机械解析工作,_toDomain() 仍由数据边界负责把传输语义变成业务语义。

处理解析失败和接口变化

Repository 应把数据层错误控制在边界内,但不要静默吞掉无效数据。必填字段类型错误时,让解析失败并转换成应用定义的数据异常;可选字段则在 DTO 中明确声明可空,再决定是否在 _toDomain() 提供默认值。

接口变化时可以按影响范围定位:字段名或嵌套结构变化先改 DTO;传输状态到业务状态的映射变化改转换逻辑;页面展示规则变化才进入 UI。这样可以避免为了一个接口字段改动而同步修改多个页面。

边界怎么验收

可以用三个检查点判断设计是否真正收口:页面代码里不出现接口字段名;状态管理层不调用 fromJson;替换 API Client 时,Repository 以上的代码无需跟着改。做到这三点后,REST 接口细节就被限制在可控的数据层中。

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

目录与阅读设置

记录一个想法

在 Repository 转换模型

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

登录哪都通