跨平台开发 / 系统课时
用测试锁定 JSON 契约
用测试锁定 JSON 契约
JSON 模型一旦跟后端契约绑定,字段默认值、枚举兜底或联合类型标签的细小改动都可能造成兼容性回归。本节用一组可重复执行的单元测试,把 fromJson、toJson 和代表性 fixture 固定成可验证的契约。
学习目标
- 为
fromJson与toJson编写对称的契约测试 - 覆盖默认值、未知枚举值和联合类型分支
- 用代表性 JSON fixture 在模型或接口变更时尽早发现回归
先把契约写进模型
下面的模型同时包含默认值、未知枚举兜底和 Freezed 联合类型。测试会围绕这些稳定约束展开,而不是去验证生成代码内部实现。
dart
import 'package:freezed_annotation/freezed_annotation.dart';
import 'package:json_annotation/json_annotation.dart';
part 'order.freezed.dart';
part 'order.g.dart';
enum OrderStatus { pending, paid, unknown }
@freezed
abstract class Order with _$Order {
const factory Order({
required String id,
@Default(0) int quantity,
@JsonKey(unknownEnumValue: OrderStatus.unknown)
required OrderStatus status,
}) = _Order;
factory Order.fromJson(Map<String, dynamic> json) => _$OrderFromJson(json);
}
@freezed
sealed class SyncResult with _$SyncResult {
const factory SyncResult.success({
required Order order,
}) = SyncSuccess;
const factory SyncResult.failure({
required String message,
}) = SyncFailure;
factory SyncResult.fromJson(Map<String, dynamic> json) =>
_$SyncResultFromJson(json);
}模型生效后,缺少 quantity 时应得到 0;遇到未知 status 字符串时应映射到 OrderStatus.unknown;联合类型则通过默认的 runtimeType 字段选择 success 或 failure 分支。
用代表性 fixture 覆盖正常路径
fixture 不需要很大,关键是能代表接口真正承诺的字段。正常路径最好同时验证反序列化结果与再次序列化后的 Map,避免只锁住单向行为。
dart
import 'package:flutter_test/flutter_test.dart';
import '../lib/order.dart';
void main() {
test('fromJson and toJson keep the normal contract', () {
final fixture = <String, dynamic>{
'id': 'o-100',
'quantity': 2,
'status': 'paid',
};
final order = Order.fromJson(fixture);
expect(
order,
const Order(id: 'o-100', quantity: 2, status: OrderStatus.paid),
);
expect(order.toJson(), fixture);
});
test('missing quantity uses the declared default', () {
final order = Order.fromJson(<String, dynamic>{
'id': 'o-101',
'status': 'pending',
});
expect(order.quantity, 0);
});
test('unknown enum value falls back safely', () {
final order = Order.fromJson(<String, dynamic>{
'id': 'o-102',
'status': 'settled',
});
expect(order.status, OrderStatus.unknown);
});
test('runtimeType selects the union branch', () {
final result = SyncResult.fromJson(<String, dynamic>{
'runtimeType': 'success',
'order': <String, dynamic>{
'id': 'o-103',
'quantity': 1,
'status': 'paid',
},
});
expect(
result,
const SyncResult.success(
order: Order(id: 'o-103', quantity: 1, status: OrderStatus.paid),
),
);
expect(result.toJson()['runtimeType'], 'success');
});
}这组测试故意不比较生成类名或私有实现细节,只比较公开模型行为。这样 Freezed 内部生成策略变化时,测试不会无意义地碎掉。
生成代码并执行契约测试
先确保生成物与当前模型一致,再执行测试文件。下面命令从 package 根目录运行。
bash
dart run build_runner build --delete-conflicting-outputs
flutter test test/order_contract_test.dart预期输出
text
<TIME> +4: All tests passed!<TIME> 会随机器和项目规模变化。若失败,优先看是哪一条契约破坏:默认值改变、枚举不再兜底、字段名变化,还是联合类型标签不匹配。
让 fixture 真正承担回归保护
代表性 fixture 应覆盖“最容易被接口演进影响”的输入,而不是穷举所有字段组合。通常保留一份正常响应,再针对兼容性风险补少量边界样本即可,例如缺省字段、后端新增枚举值、联合分支切换。
如果团队会修改 @JsonKey、默认值或联合类型配置,可以把这组测试加入 CI。这样模型源码、生成代码与接口样本三者不一致时,问题会在合并代码前暴露,而不是等到运行时才由真实用户触发。
按自己的节奏,确认真正理解。