跨平台开发 / 系统课时

用测试锁定 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。这样模型源码、生成代码与接口样本三者不一致时,问题会在合并代码前暴露,而不是等到运行时才由真实用户触发。

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

目录与阅读设置

记录一个想法

用测试锁定 JSON 契约

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

登录哪都通