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

最新推荐文章于 2025-06-15 17:23:16 发布
最新推荐文章于 2025-06-15 17:23:16 发布
阅读量551 收藏 18
点赞数 24
分类专栏： Flutter 文章标签： flutter json
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/vvilkim/article/details/148553956
版权

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

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

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

第一部分：json_serializable基础

1.1 核心概念解析

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

  1. 类型安全：生成的代码完全类型安全，避免了手动转换可能带来的类型错误

  2. 减少样板代码：自动生成重复的序列化代码，提高开发效率

  3. 可维护性：模型变更时，只需重新生成代码即可同步更新序列化逻辑

  4. 灵活性：提供多种配置选项处理各种复杂场景

1.2 环境配置详解

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

dependencies:
  flutter:
    sdk: flutter
  json_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);
}

关键点说明：

  1. part 'user.g.dart'声明表示这个文件将包含自动生成的代码

  2. @JsonSerializable()注解告诉生成器需要为这个类生成序列化代码

  3. _$UserFromJson和_$UserToJson是自动生成的函数，前缀_$是生成器的命名约定

  4. 模型类应尽可能使用不可变字段（final），这符合函数式编程的最佳实践

1.4 生成序列化代码

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

flutter pub run build_runner build

这个命令会：

  1. 扫描项目中所有被@JsonSerializable()注解的类

  2. 为每个类生成对应的.g.dart文件

  3. 生成的代码包含完整的序列化和反序列化实现

对于大型项目，推荐使用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 性能优化建议

  1. 批量生成：一次性为所有模型生成代码，而不是频繁运行生成器

  2. 使用freezed：结合freezed包可以生成不可变类，获得更好的性能和安全性

  3. 缓存结果：对于频繁访问的JSON数据，考虑在转换为对象后缓存结果

  4. 懒加载：对于大型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);
}

结语：选择适合项目的序列化方案

json_serializable是Flutter生态中最强大、最灵活的JSON序列化解决方案之一。它特别适合：

  • 中大型项目，有复杂的数据结构

  • 需要严格类型安全的项目

  • 长期维护的项目，需要良好的可维护性

对于小型项目或原型开发，手动序列化或dart:convert的基本功能可能就足够了。但对于生产级应用，特别是需要与复杂API交互的项目，json_serializable提供的类型安全和自动化优势将大大提升开发效率和代码质量。

通过本文的介绍，你应该已经掌握了json_serializable的核心用法和高级技巧。现在，是时候在你的Flutter项目中实践这些知识，享受自动化JSON序列化带来的便利了！

【Flutter】Flutter 使用 json_serializable 进行 JSON 序列化
Code Metaverse
06-30 1263
json_serializable 是一个 Dart 包，它可以自动为你生成 JSON 序列化和反序列化的代码。
【Flutter】包管理（11）Flutter JSON 反序列化 json_serializable 进阶 自定义序列化、嵌套的 JSON 对象
Code Metaverse
07-01 997
我们将深入探讨 json_serializable 的高级特性，并学习如何在复杂的业务逻辑中使用 json_serializable。
Flutter中高级JSON处理：使用json_serializable进行深入定制
jclee95的个人博客
02-27 3845
本文适合具有一定Flutter开发经验，希望进一步提升JSON处理技能的开发者。通过学习本文，读者将能够掌握json_serializable的高级用法，从而更加轻松地处理Flutter项目中的复杂JSON数据。
Flutter 关于序列化JSON之json_serializable库的使用
qq_38774121的博客
08-29 1775
Flutter 关于序列化JSON之json_serializable库的使用
[Flutter]Json序列化json_serializable使用属性全介绍
曹世鑫的杂谈
12-03 2548
json_serializable参数介绍
2024年Flutter Json自动反序列化——json_serializable v1，flutter页面跳转数据
2401_84557136的博客
05-06 985
其实Android开发的知识点就那么多，面试问来问去还是那么点东西。所以面试没有其他的诀窍，只看你对这些知识点准备的充分程度。so，出去面试时先看看自己复习到了哪个阶段就好。虽然 Android 没有前几年火热了，已经过去了会四大组件就能找到高薪职位的时代了。这只能说明 Android 中级以下的岗位饱和了，，很多高级职位给的薪资真的特别高（钱多也不一定能找到合适的），所以努力让自己成为高级工程师才是最重要的。
Flutter Json自动反序列化——json_serializable v1
2401_84123213的博客
05-13 1039
自我介绍一下，小编13年上海交大毕业，曾经在小公司待过，也去过华为、OPPO等大厂，18年进入阿里一直到现在。深知大多数初中级Android工程师，想要提升技能，往往是自己摸索成长，自己不成体系的自学效果低效漫长且无助。因此我收集整理了一份《2024年Android移动开发全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升又不知道该从何学起的朋友，同时减轻大家的负担。既有适合小白学习的零基础资料，也有适合3年以上经验的小伙伴深入学习提升的进阶课程，基本涵盖了95%以上Android开发知识点！
Flutter数据解析--json_serializable
eastWind1101的博客
03-21 940
json_serializable是dart官方推荐和提供的JSON转Model的方式：一个自动化源代码生成器来为你生成 JSON 序列化数据模板；由于序列化数据代码不再需要手动编写或者维护，你可以将序列化 JSON 数据在运行时的异常风险降到最低；
使用 json_serializable 实现 Dart 泛型类的 JSON 序列化和反序列化
qq_15396485的博客
11-11 1312
使用处理 Dart 泛型类的 JSON 序列化和反序列化能够简化代码，同时避免手动编写序列化方法。添加依赖和。使用注解支持泛型。在终端运行自动生成序列化代码。通过这些步骤，我们可以更灵活地操作接口数据并封装泛型响应结构，极大地提升了代码的可读性和复用性。这篇文章帮助大家理解如何在 Flutter 中使用处理泛型类的 JSON 序列化问题，并提供了完整的代码示例和详细的解释。
Flutter json_serializable解析json泛型常用方法(genericArgumentFactories)
qq_20352713的博客
06-30 1729
json_serializable是flutter开发中比较流行的插件了.由于dart禁止运行时反射,没有不能动态获取类型来创建对象.所以在解析json的时候比较麻烦这里介绍最通用的方法json例子: 使用genericArgumentFactories 首先genericArgumentFactories参数设置为true,就开启了框架默认的json解析方式 可以看到生成的解析方法多了一个函数参数`T Function(Object? json) fromJsonT,`并且把我们的泛型dat
Flutter JSON使用示例：dart:convert与json_serializable
这条命令会分析你的项目中的`@JsonSerializable`注解，并生成对应的序列化代码。 4. 使用这些生成的方法来编码和解码JSON数据： ```dart final user = User(name: 'John', age: 25); final jsonString = json...
Flutter-使用Json序列化工具json_serializable数据解析生成xx.g.dart文件步骤
qq_17189617的专栏
01-18 1216
如何根据json生成dart和g.dart 文件？flutter中文网地址这个网站可以自动将json文件转成json_serializable所需要的格式，新建并复制成***.dart文件，通过在terminal内输入下面代码，自动生成.g.dart文件如果有报错可以尝试一下下面这条。
flutter 项目配置Gradle下载代理
最新发布
06-15 148
如图， 在Android Studio中配置代理是不生效的。需要在flutter sdk的Gradle中去配置代理。
Flutter setState() 状态管理详细使用指南
帅次的博客
06-11 1837
在 Flutter 开发中，setState() 是管理 Widget 状态变化最基础的方法。它用于更新 StatefulWidget 中的 UI，使 Flutter 重新构建该 Widget 及其子组件。本文将详细介绍 setState() 的基本原理、使用方法，并通过代码示例展示如何正确使用 setState() 进行状态更新。此外，我们还会探讨 setState() 的局限性，以及在复杂应用中可能需要的更高级状态管理方案。
Flutter Android打包和发布Build APK
zyy_give的博客
06-13 793
Flutter Android打包和发布Build APK
Flutter布局系统全面解析：从基础组件到复杂界面构建
vvilkin的学习备忘
06-11 1468
在移动应用开发领域，良好的界面布局是用户体验的基础。Flutter作为Google推出的跨平台UI框架，提供了一套强大而灵活的布局系统，使开发者能够高效构建美观且响应式的用户界面。本文将全面剖析Flutter的核心布局组件，包括Row、Column、Stack、Flex、Container和Padding等，通过理论讲解和实际代码示例，帮助开发者掌握Flutter布局的精髓。
flutter把 pubspec.yaml 中的name改成了新的值
getapi的博客
06-12 570
Flutter 允许安全删除并重建 ios/ 文件夹： 1️⃣ 确认无自定义配置后删除原文件夹：rm -rf ios/； 2️⃣ 执行 flutter create . 自动重建 iOS 项目结构； 3️⃣ 安装 CocoaPods 依赖：cd ios && pod install； 4️⃣ 通过 flutter run 或 Xcode 验证新项目。 ⚠️ 注意事项：需重新配置签名、插件权限和 Info.plist 设置。该操作适合需要重置 iOS 模块或解决构建问题的场景。
快速使用 Flutter 中的 SnackBar 和 Toast
帅次的博客
06-15 588
本篇文章将详细介绍 Snackbar 的基本用法，包括如何创建、定制样式、添加交互按钮，并探索不同的显示方式。此外，还将对 ScaffoldMessenger 进行讲解，帮助开发者更灵活地控制 Snackbar 的展示方式。同时，文章还将介绍 fluttertoast 插件的使用方法，为开发者提供更多消息提示的选择。通过示例代码，读者可以快速掌握 Snackbar 和 fluttertoast 的用法，提高应用的用户体验
在 Flutter 项目中iOS 的 App 图标和 App 名称 的设置
getapi的博客
06-12 734
摘要：在Flutter项目中设置iOS应用的图标和名称需修改以下内容： 应用名称：通过Xcode修改Info.plist中的CFBundleName键值 应用图标： 方法1：在Xcode中拖拽图标到Assets.xcassets/AppIcon 方法2：手动替换AppIcon.appiconset目录中的图标文件 可选修改Bundle ID 修改完成后需运行flutter build ios验证效果。操作主要涉及Xcode界面操作或直接修改项目配置文件。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值