Flutter JSON解析全攻略：使用json_serializable实现高效序列化

引言：为什么我们需要JSON序列化工具？

在现代移动应用开发中，与服务器进行数据交互是必不可少的功能。JSON（JavaScript Object Notation）作为一种轻量级的数据交换格式，因其易读性、简洁性和广泛支持性，已成为前后端通信的事实标准。在Flutter开发中，我们经常需要将JSON数据转换为Dart对象（反序列化），或将Dart对象转换为JSON数据（序列化）。

手动编写序列化代码虽然可行，但随着项目规模扩大和数据结构复杂化，这种方式会变得繁琐且容易出错。这时，json_serializable这个强大的代码生成库就能大显身手了。本文将全面介绍如何使用json_serializable实现高效、安全的JSON序列化操作。

第一部分：json_serializable基础

1.1 核心概念解析

json_serializable是一个基于Dart构建系统的代码生成库，它通过注解驱动的方式，自动为你的模型类生成序列化代码。它的核心优势在于：

类型安全：生成的代码完全类型安全，避免了手动转换可能带来的类型错误
减少样板代码：自动生成重复的序列化代码，提高开发效率
可维护性：模型变更时，只需重新生成代码即可同步更新序列化逻辑
灵活性：提供多种配置选项处理各种复杂场景

1.2 环境配置详解

要开始使用json_serializable，首先需要在项目的pubspec.yaml中添加必要的依赖：

dependencies:flutter:sdk: flutterjson_annotation: ^4.8.1  # 提供必要的注解dev_dependencies:build_runner: ^2.4.6     # 代码生成工具json_serializable: ^6.7.1 # 序列化代码生成器

添加依赖后，运行flutter pub get获取包。这里需要注意：

json_annotation是运行时依赖，包含我们需要的注解
build_runner和json_serializable是开发时依赖，只在开发阶段需要
版本号可能会随时间变化，建议查看pub.dev获取最新版本

1.3 创建基础模型类

让我们从一个简单的用户模型开始，展示基本的序列化实现：

import 'package:json_annotation/json_annotation.dart';// 这个文件是自动生成的，必须声明part
part 'user.g.dart';/// 用户模型类
@JsonSerializable() // 核心注解，表示这个类需要生成序列化代码
class User {final String name;final String email;final int age;final DateTime registeredAt;User({required this.name,required this.email,required this.age,required this.registeredAt,});/// 从JSON映射创建User实例的工厂构造函数factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);/// 将User实例转换为JSON映射的方法Map<String, dynamic> toJson() => _$UserToJson(this);
}

关键点说明：

part 'user.g.dart'声明表示这个文件将包含自动生成的代码
@JsonSerializable()注解告诉生成器需要为这个类生成序列化代码
_$UserFromJson和_$UserToJson是自动生成的函数，前缀_$是生成器的命名约定
模型类应尽可能使用不可变字段（final），这符合函数式编程的最佳实践

1.4 生成序列化代码

配置好模型类后，我们需要运行代码生成器。在项目根目录执行：

flutter pub run build_runner build

这个命令会：

扫描项目中所有被@JsonSerializable()注解的类
为每个类生成对应的.g.dart文件
生成的代码包含完整的序列化和反序列化实现

对于大型项目，推荐使用watch模式，它会监听文件变化并自动重新生成代码：

flutter pub run build_runner watch

第二部分：高级配置与技巧

2.1 字段自定义配置

json_serializable提供了丰富的配置选项，通过@JsonKey注解可以精细控制每个字段的序列化行为：

@JsonSerializable()
class AdvancedUser {@JsonKey(name: 'user_name') // 自定义JSON字段名final String name;@JsonKey(ignore: true) // 忽略此字段，不参与序列化final String? temporaryToken;@JsonKey(defaultValue: 'unknown') // 默认值final String status;@JsonKey(fromJson: _parseBalance, toJson: _stringifyBalance) // 自定义转换final double balance;@JsonKey(includeIfNull: false) // 为null时不包含在JSON中final String? nickname;AdvancedUser({required this.name,this.temporaryToken,this.status = 'unknown',required this.balance,this.nickname,});static double _parseBalance(String json) => double.parse(json);static String _stringifyBalance(double balance) => balance.toStringAsFixed(2);// ... fromJson/toJson方法
}

2.2 处理复杂嵌套结构

现实项目中的数据往往具有复杂的嵌套结构，json_serializable可以优雅地处理这种情况：

@JsonSerializable()
class Address {final String street;final String city;final String zipCode;Address({required this.street, required this.city, required this.zipCode});factory Address.fromJson(Map<String, dynamic> json) => _$AddressFromJson(json);Map<String, dynamic> toJson() => _$AddressToJson(this);
}@JsonSerializable()
class Company {final String name;final Address address;Company({required this.name, required this.address});factory Company.fromJson(Map<String, dynamic> json) => _$CompanyFromJson(json);Map<String, dynamic> toJson() => _$CompanyToJson(this);
}@JsonSerializable()
class Employee {final String id;final String name;final Company company;final List<String> skills; // 简单列表final List<Address> previousAddresses; // 复杂对象列表Employee({required this.id,required this.name,required this.company,required this.skills,required this.previousAddresses,});factory Employee.fromJson(Map<String, dynamic> json) => _$EmployeeFromJson(json);Map<String, dynamic> toJson() => _$EmployeeToJson(this);
}

2.3 枚举和泛型支持

json_serializable对枚举和泛型也有很好的支持：

enum UserRole {@JsonValue('admin')admin,@JsonValue('editor')editor,@JsonValue('viewer')viewer,@JsonValue('guest')guest,
}@JsonSerializable(genericArgumentFactories: true) // 启用泛型支持
class PaginatedResponse<T> {final int page;final int totalPages;final List<T> data;PaginatedResponse({required this.page,required this.totalPages,required this.data,});factory PaginatedResponse.fromJson(Map<String, dynamic> json,T Function(Object? json) fromJsonT,) => _$PaginatedResponseFromJson(json, fromJsonT);Map<String, dynamic> toJson(Object? Function(T value) toJsonT) =>_$PaginatedResponseToJson(this, toJsonT);
}// 使用示例
final userResponse = PaginatedResponse<User>.fromJson(jsonMap,(json) => User.fromJson(json as Map<String, dynamic>),
);

第三部分：实战应用与性能优化

3.1 与HTTP库集成

在实际项目中，我们通常会将json_serializable与HTTP库（如dio或http）结合使用：

import 'package:dio/dio.dart';
import 'package:flutter/foundation.dart';class UserRepository {final Dio _dio = Dio();Future<User> fetchUser(String userId) async {try {final response = await _dio.get('/users/$userId');return User.fromJson(response.data);} on DioError catch (e) {debugPrint('Error fetching user: $e');rethrow;}}Future<PaginatedResponse<User>> fetchUsers({int page = 1}) async {try {final response = await _dio.get('/users', queryParameters: {'page': page});return PaginatedResponse<User>.fromJson(response.data,(json) => User.fromJson(json as Map<String, dynamic>),);} on DioError catch (e) {debugPrint('Error fetching users: $e');rethrow;}}
}

3.2 性能优化建议

批量生成：一次性为所有模型生成代码，而不是频繁运行生成器
使用freezed：结合freezed包可以生成不可变类，获得更好的性能和安全性
缓存结果：对于频繁访问的JSON数据，考虑在转换为对象后缓存结果
懒加载：对于大型JSON结构，考虑使用懒加载或分页技术

3.3 常见问题解决方案

问题1：生成代码时报错"Conflicting outputs"

解决方案：

flutter pub run build_runner build --delete-conflicting-outputs

问题2：DateTime类型的处理

解决方案：

@JsonKey(fromJson: _dateFromJson, toJson: _dateToJson)
final DateTime createdAt;static DateTime _dateFromJson(String json) => DateTime.parse(json);
static String _dateToJson(DateTime date) => date.toIso8601String();

问题3：处理可能为null的字段

解决方案：

@JsonSerializable()
class Product {final String id;final String name;final String? description; // 可空字段Product({required this.id, required this.name, this.description});factory Product.fromJson(Map<String, dynamic> json) => _$ProductFromJson(json);Map<String, dynamic> toJson() => _$ProductToJson(this);
}