在json_serializable项目中同时使用JsonKey与JsonConverter实现字段映射与转换

在Dart语言的JSON序列化库json_serializable的实际开发中，开发者经常需要对数据模型的字段进行双重处理：既要自定义JSON字段名称，又要对字段值进行特殊格式转换。通过结合使用JsonKey注解和JsonConverter转换器，我们可以优雅地实现这一需求。

核心概念解析

JsonKey注解

JsonKey是json_serializable提供的字段级注解，主要用于控制单个字段的序列化行为。其核心功能包括：

• 指定JSON字段名称（通过name参数）
• 控制字段是否参与序列化/反序列化
• 设置默认值等基础配置

JsonConverter接口

JsonConverter是一个更强大的转换接口，允许开发者：

• 完全自定义字段值的序列化逻辑
• 处理复杂的数据类型转换
• 实现加密/解密等特殊处理

组合使用实践

在实际编码中，这两种机制可以完美配合使用。例如处理一个API返回的日期字段：

@JsonSerializable()
class User {
  @JsonKey(name: 'create_time')  // 指定JSON字段名
  @EpochDateTimeConverter()      // 添加自定义转换器
  final DateTime createTime;

  User(this.createTime);
}

class EpochDateTimeConverter implements JsonConverter<DateTime, int> {
  const EpochDateTimeConverter();
  
  @override
  DateTime fromJson(int json) => DateTime.fromMillisecondsSinceEpoch(json);
  
  @override
  int toJson(DateTime object) => object.millisecondsSinceEpoch;
}

这个例子展示了典型的使用场景：

1. 通过JsonKey将JSON中的"create_time"字段映射到Dart类的createTime属性
2. 通过JsonConverter实现时间戳(整型)与DateTime类型的相互转换

实现原理

json_serializable的代码生成器会按照以下顺序处理字段：

1. 首先应用JsonKey的配置（包括字段重命名）
2. 然后应用JsonConverter的转换逻辑
3. 最后处理基础的序列化/反序列化

这种分层处理的设计使得各个关注点分离，既保持了代码的清晰性，又提供了足够的灵活性。

最佳实践建议

1. 明确职责划分：JsonKey应只用于字段配置，复杂转换逻辑交给JsonConverter
2. 注意处理顺序：转换器接收的是重命名后的字段值
3. 保持转换器纯净：避免在转换器中引入业务逻辑
4. 考虑性能影响：对于高频调用的模型，复杂的转换逻辑可能影响性能

通过合理运用这两种机制，开发者可以构建出既符合外部接口规范，又保持内部类型安全的健壮数据模型。