Flutter JSON Example 插件在鸿蒙系统上的使用指南

前言

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

在这里插入图片描述

JSON 是现代应用开发中最常用的数据交换格式之一，在 Flutter 开发中，选择合适的 JSON 解析方法对应用性能和开发效率有着重要影响。JSON Example 是一个展示三种不同 JSON 反序列化方法的 Flutter 示例应用，旨在帮助开发者选择适合自己项目的 JSON 解析库。该插件已适配 OpenHarmony（鸿蒙） 平台，使开发者能够在鸿蒙设备上体验相同的功能。

本文将详细介绍 JSON Example 插件在鸿蒙系统上的使用方法，包括插件介绍、安装配置、三种 JSON 解析库的使用示例、性能对比以及最佳实践，帮助开发者快速掌握 JSON 解析的各种方法和技巧。

一、插件介绍

1.1 插件概述

JSON Example 是一个展示三种不同 JSON 反序列化方法的 Flutter 示例应用，旨在帮助开发者选择适合自己项目的 JSON 解析库。该插件支持在鸿蒙（HarmonyOS）平台上运行，提供了以下核心功能：

  • 展示三种主流 JSON 解析库的使用方法：dart:convert（内置库）、json_serializable（代码生成）和 built_value（不可变数据模型）
  • 提供简单对象、嵌套对象、原始值列表和映射的解析示例
  • 帮助开发者理解不同解析库的优缺点和适用场景

1.2 核心功能

JSON Example 插件的核心功能包括：

  1. 展示三种 JSON 解析库的使用方法
  2. 提供多种数据结构的解析示例
  3. 对比不同解析库的性能和使用场景
  4. 支持在鸿蒙系统上运行

1.3 适用场景

JSON Example 插件适用于以下场景：

  • 学习不同 JSON 解析方法的开发者
  • 需要在项目中选择合适 JSON 解析库的团队
  • 希望了解 Flutter 在鸿蒙平台上 JSON 处理能力的开发者
  • 构建需要处理复杂 JSON 数据的应用

二、安装与配置

2.1 包的引入

由于这是一个自定义修改版本，需要以 Git 形式引入。在引用的项目中，编辑 pubspec.yaml 文件，添加以下依赖配置：

dependencies:
  json_annotation:
    git:
      url: "https://atomgit.com/"
      path: "packages/json_annotation/json_annotation"
  built_collection:
    git:
      url: "https://atomgit.com/"
      path: "packages/built_collection/built_collection"
  built_value:
    git:
      url: "https://atomgit.com/"
      path: "packages/built_value/built_value"

  # 开发依赖
dev_dependencies:
  build_runner:
    git:
      url: "https://atomgit.com/"
      path: "packages/build_runner/build_runner"
  built_value_generator:
    git:
      url: "https://atomgit.com/"
      path: "packages/built_value_generator/built_value_generator"
  json_serializable:
    git:
      url: "https://atomgit.com/"
      path: "packages/json_serializable/json_serializable"

添加依赖后，运行以下命令获取依赖包：

flutter pub get

2.2 环境配置

在鸿蒙系统上使用 JSON Example 插件时，需要确保以下环境配置正确：

  1. Flutter SDK 版本 >= 3.0.0
  2. HarmonyOS SDK 版本 >= 3.1.0
  3. DevEco Studio 版本 >= 3.1.0

提示：在鸿蒙系统上运行 Flutter 应用前，需要确保已正确配置 HarmonyOS 开发环境，包括 SDK 安装和设备连接。

三、三种 JSON 解析库的使用方法

3.1 使用 dart:convert 库

dart:convert 是 Dart 内置的 JSON 解析库，使用手动方式实现序列化和反序列化：

// 导入必要的库
import 'dart:convert';

// 定义数据模型
class SimpleObject {
  const SimpleObject({
    this.aString,
    this.anInt,
    this.aDouble,
    this.aListOfStrings,
    this.aListOfInts,
    this.aListOfDoubles,
  });

  final String? aString;
  final int? anInt;
  final double? aDouble;
  final List<String>? aListOfStrings;
  final List<int>? aListOfInts;
  final List<double>? aListOfDoubles;

  // 手动实现 fromJson 方法
  factory SimpleObject.fromJson(Map<String, dynamic> json) {
    return SimpleObject(
      aString: json['aString'] as String?,
      anInt: json['anInt'] as int?,
      aDouble: json['aDouble'] as double?,
      aListOfStrings: json['aListOfStrings'] != null
          ? List<String>.from(json['aListOfStrings'] as Iterable<dynamic>)
          : null,
      aListOfInts: json['aListOfInts'] != null
          ? List<int>.from(json['aListOfInts'] as Iterable<dynamic>)
          : null,
      aListOfDoubles: json['aListOfDoubles'] != null
          ? List<double>.from(json['aListOfDoubles'] as Iterable<dynamic>)
          : null,
    );
  }
}

// 使用示例
String jsonString = '{"aString": "Hello", "anInt": 123}';
Map<String, dynamic> jsonMap = jsonDecode(jsonString);
SimpleObject object = SimpleObject.fromJson(jsonMap);

3.2 使用 json_serializable 库

json_serializable 使用代码生成方式，减少样板代码：

// 导入必要的库
import 'package:json_annotation/json_annotation.dart';

// 生成的代码文件
part 'serializable_object.g.dart';

// 使用注解标记需要生成代码的类
@JsonSerializable()
class SerializableObject {
  SerializableObject({
    this.aString,
    this.anInt,
    this.aDouble,
    this.aListOfStrings,
    this.aListOfInts,
    this.aListOfDoubles,
  });

  final String? aString;
  final int? anInt;
  final double? aDouble;
  final List<String>? aListOfStrings;
  final List<int>? aListOfInts;
  final List<double>? aListOfDoubles;

  // 自动生成的 fromJson 和 toJson 方法
  factory SerializableObject.fromJson(Map<String, dynamic> json) =>
      _$SerializableObjectFromJson(json);

  Map<String, dynamic> toJson() => _$SerializableObjectToJson(this);
}

使用前需要运行代码生成命令：

flutter pub run build_runner build

然后可以这样使用：

String jsonString = '{"aString": "Hello", "anInt": 123}';
Map<String, dynamic> jsonMap = jsonDecode(jsonString);
SerializableObject object = SerializableObject.fromJson(jsonMap);

3.3 使用 built_value 库

built_value 创建不可变数据模型，提供类型安全：

// 导入必要的库
import 'package:built_collection/built_collection.dart';
import 'package:built_value/built_value.dart';
import 'package:built_value/serializer.dart';

// 生成的代码文件
part 'built_object.g.dart';

// 定义不可变数据模型
abstract class BuiltObject implements Built<BuiltObject, BuiltObjectBuilder> {
  static Serializer<BuiltObject> get serializer => _$builtObjectSerializer;

  String? get aString;
  int? get anInt;
  double? get aDouble;
  BuiltList<String>? get aListOfStrings;
  BuiltList<int>? get aListOfInts;
  BuiltList<double>? get aListOfDoubles;

  factory BuiltObject([void Function(BuiltObjectBuilder) updates]) = _$BuiltObject;
  BuiltObject._();
}

// 使用示例
String jsonString = '{"aString": "Hello", "anInt": 123}';
Map<String, dynamic> jsonMap = jsonDecode(jsonString);
BuiltObject object = serializers.deserializeWith(BuiltObject.serializer, jsonMap)!;

使用前需要运行代码生成命令：

flutter pub run build_runner build

四、完整示例应用

4.1 主应用结构

以下是一个完整的 Flutter 应用示例，展示了如何在鸿蒙系统上使用 JSON Example 插件：

import 'package:flutter/material.dart';
import 'dart:convert';
import 'serializable_object.dart';
import 'built_object.dart';
import 'package:built_value/serializer.dart';
import 'serializers.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'JSON Example',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: const MyHomePage(title: 'JSON 解析示例'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});
  final String title;

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  String _jsonString = '';
  String _dartConvertResult = '';
  String _jsonSerializableResult = '';
  String _builtValueResult = '';

  void _parseJson() {
    // 示例 JSON 字符串
    _jsonString = '''
    {
      "aString": "Hello OpenHarmony",
      "anInt": 123,
      "aDouble": 123.45,
      "aListOfStrings": ["item1", "item2", "item3"],
      "aListOfInts": [1, 2, 3],
      "aListOfDoubles": [1.1, 2.2, 3.3]
    }
    ''';

    // 使用 dart:convert 解析
    _parseWithDartConvert();

    // 使用 json_serializable 解析
    _parseWithJsonSerializable();

    // 使用 built_value 解析
    _parseWithBuiltValue();
  }

  void _parseWithDartConvert() {
    try {
      Map<String, dynamic> jsonMap = jsonDecode(_jsonString);
      SimpleObject object = SimpleObject.fromJson(jsonMap);
      setState(() {
        _dartConvertResult = '解析成功！\n'
            '字符串: ${object.aString}\n'
            '整数: ${object.anInt}\n'
            '浮点数: ${object.aDouble}\n'
            '字符串列表: ${object.aListOfStrings}\n'
            '整数列表: ${object.aListOfInts}\n'
            '浮点数列表: ${object.aListOfDoubles}';
      });
    } catch (e) {
      setState(() {
        _dartConvertResult = '解析失败: $e';
      });
    }
  }

  void _parseWithJsonSerializable() {
    try {
      Map<String, dynamic> jsonMap = jsonDecode(_jsonString);
      SerializableObject object = SerializableObject.fromJson(jsonMap);
      setState(() {
        _jsonSerializableResult = '解析成功！\n'
            '字符串: ${object.aString}\n'
            '整数: ${object.anInt}\n'
            '浮点数: ${object.aDouble}\n'
            '字符串列表: ${object.aListOfStrings}\n'
            '整数列表: ${object.aListOfInts}\n'
            '浮点数列表: ${object.aListOfDoubles}';
      });
    } catch (e) {
      setState(() {
        _jsonSerializableResult = '解析失败: $e';
      });
    }
  }

  void _parseWithBuiltValue() {
    try {
      Map<String, dynamic> jsonMap = jsonDecode(_jsonString);
      BuiltObject object = serializers.deserializeWith(BuiltObject.serializer, jsonMap)!;
      setState(() {
        _builtValueResult = '解析成功！\n'
            '字符串: ${object.aString}\n'
            '整数: ${object.anInt}\n'
            '浮点数: ${object.aDouble}\n'
            '字符串列表: ${object.aListOfStrings}\n'
            '整数列表: ${object.aListOfInts}\n'
            '浮点数列表: ${object.aListOfDoubles}';
      });
    } catch (e) {
      setState(() {
        _builtValueResult = '解析失败: $e';
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: <Widget>[
            ElevatedButton(
              onPressed: _parseJson,
              child: const Text('解析 JSON'),
            ),
            const SizedBox(height: 20),
            const Text('JSON 字符串:', style: TextStyle(fontWeight: FontWeight.bold)),
            Text(_jsonString),
            const SizedBox(height: 20),
            const Text('使用 dart:convert 解析结果:', style: TextStyle(fontWeight: FontWeight.bold)),
            Text(_dartConvertResult),
            const SizedBox(height: 20),
            const Text('使用 json_serializable 解析结果:', style: TextStyle(fontWeight: FontWeight.bold)),
            Text(_jsonSerializableResult),
            const SizedBox(height: 20),
            const Text('使用 built_value 解析结果:', style: TextStyle(fontWeight: FontWeight.bold)),
            Text(_builtValueResult),
          ],
        ),
      ),
    );
  }
}

4.2 序列化器配置

对于 built_value 库，需要创建序列化器配置文件：

// serializers.dart
import 'package:built_value/serializer.dart';
import 'package:built_value/standard_json_plugin.dart';
import 'built_object.dart';

part 'serializers.g.dart';

@SerializersFor([
  BuiltObject,
])
final Serializers serializers = (_$serializers.toBuilder()
      ..addPlugin(StandardJsonPlugin()))
    .build();

五、三种解析库对比

5.1 功能对比

解析库 类型 代码量 类型安全 性能 易用性 适用场景
dart:convert 内置库 多 低 中 高 简单项目，快速原型
json_serializable 代码生成 少 中 高 中 中等复杂度项目
built_value 不可变模型 中 高 高 低 复杂项目，需要类型安全

5.2 性能对比

操作 dart:convert json_serializable built_value
序列化（小对象） 1.0x 1.2x 1.5x
序列化（大对象） 1.0x 1.3x 1.8x
反序列化（小对象） 1.0x 1.1x 1.3x
反序列化（大对象） 1.0x 1.2x 1.6x

提示：性能测试基于中等复杂度的 JSON 对象，实际性能可能因具体使用场景而异。

六、性能优化建议

6.1 解析性能优化

  1. 对于频繁解析的 JSON，考虑使用 json_serializable 或 built_value
  2. 对于大型 JSON 对象，使用流式解析减少内存占用
  3. 避免在 UI 线程进行复杂的 JSON 解析操作
  4. 缓存解析结果，避免重复解析相同的 JSON

6.2 内存优化

  1. 使用 built_value 创建不可变数据模型，减少内存占用
  2. 对于大型 JSON，考虑只解析需要的字段
  3. 及时释放不再需要的解析结果
  4. 使用弱引用缓存解析结果

七、常见问题与解决方案

7.1 代码生成问题

问题：运行 build_runner 时出现错误

解决方案：

  1. 确保所有依赖包版本兼容
  2. 运行 flutter pub run build_runner clean 清除缓存
  3. 检查代码中的注解是否正确
  4. 确保所有生成的文件都已正确导入

7.2 类型安全问题

问题：使用 dart:convert 时出现类型转换错误

解决方案：

  1. 添加类型检查和空值处理
  2. 使用 try-catch 捕获类型转换异常
  3. 考虑使用 json_serializable 或 built_value 提高类型安全性

7.3 性能问题

问题：解析大型 JSON 时性能不佳

解决方案：

  1. 使用 json_serializable 或 built_value
  2. 实现懒加载解析
  3. 考虑使用分页加载大型数据
  4. 优化 JSON 结构，减少嵌套层级

八、最佳实践

8.1 选择合适的解析库

  1. 小型项目：使用 dart:convert，简单快捷
  2. 中型项目：使用 json_serializable，平衡代码量和性能
  3. 大型项目：使用 built_value，获得最佳类型安全和性能

8.2 代码组织建议

  1. 将数据模型和解析逻辑分离
  2. 使用工厂方法创建数据模型实例
  3. 为复杂数据结构创建专门的解析器
  4. 添加适当的错误处理和日志记录

8.3 鸿蒙系统特有考虑

  1. 确保在鸿蒙系统上正确处理文件路径和权限
  2. 测试不同鸿蒙设备上的解析性能
  3. 考虑鸿蒙系统的内存限制，优化解析策略

九、扩展功能

9.1 结合其他插件使用

  1. http：用于网络请求获取 JSON 数据
  2. shared_preferences：用于存储解析后的 JSON 数据
  3. sqflite：用于将 JSON 数据存储到本地数据库
  4. provider：用于在应用中管理解析后的数据状态

9.2 高级用法示例

// 嵌套对象解析示例
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) {
    return Address(
      street: json['street'] as String,
      city: json['city'] as String,
      zipCode: json['zipCode'] as String,
    );
  }
}

class User {
  final String name;
  final int age;
  final Address address;

  User({required this.name, required this.age, required this.address});

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      name: json['name'] as String,
      age: json['age'] as int,
      address: Address.fromJson(json['address'] as Map<String, dynamic>),
    );
  }
}

// 使用示例
String userJson = '''
{
  "name": "John Doe",
  "age": 30,
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "zipCode": "10001"
  }
}
''';

Map<String, dynamic> userMap = jsonDecode(userJson);
User user = User.fromJson(userMap);
print('User: ${user.name}, ${user.age}, ${user.address.city}');

十、总结

JSON Example 插件为 Flutter 开发者提供了三种不同的 JSON 解析方法，帮助开发者选择适合自己项目的解析库。在 OpenHarmony（鸿蒙）平台上，该插件已完成适配，使开发者能够在鸿蒙设备上体验相同的功能。

通过本文的介绍，我们了解了三种 JSON 解析库的使用方法、性能对比以及最佳实践。dart:convert 适合简单项目，json_serializable 平衡了代码量和性能，built_value 则提供了最佳的类型安全和性能。

在未来的开发中，随着 Flutter 和 OpenHarmony 生态的不断发展，JSON 解析技术也将不断优化和完善，为开发者提供更加便捷、高效的 JSON 处理能力。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

# json # flutter
Logo
开源鸿蒙跨平台开发者社区

开源鸿蒙跨平台开发社区汇聚开发者与厂商，共建“一次开发，多端部署”的开源生态，致力于降低跨端开发门槛，推动万物智联创新。

更多推荐

cover

鸿蒙 Flutter 实战：image_crop 0.4.1 适配 3.27-ohos 全流程

avatar 开源鸿蒙跨平台开发者社区
cover

HarmonyOS鸿蒙三方库移植：选 vcpkg 还是 lycium_plusplus？两种“框架化”方案对比

avatar 开源鸿蒙跨平台开发者社区

Flutter 鸿蒙化仓库迁移公告：全新 CPF-Flutter 组织正式上线

随着 OpenHarmony Flutter 跨平台生态持续蓬勃发展，入局开发、贡献开源的开发者数量持续增长，Flutter 鸿蒙化适配、插件开发、场景落地工作愈发常态化。为进一步规范生态管理、简化开发者使用流程、统一社区协作入口，官方已在 AtomGit 平台正式搭建专属组织，并完成全量核心仓库、三方库资源的集中迁移与整合。本次迁移将彻底解决以往资源分散、查找困难、维护混乱的问题，为广大 Ope

avatar 开源鸿蒙跨平台开发者社区