引言

在现代移动应用开发中，JSON（JavaScript Object Notation）已经成为数据交换的标准格式。无论是网络请求、本地存储还是API通信，JSON都扮演着至关重要的角色。对于Flutter开发者来说，掌握JSON的编码和解码是一项必备技能。

本章节将深入探讨Dart标准库中dart:convert的使用方法，结合天气查询应用的实际场景，帮助读者全面理解JSON处理的核心技术。

1. dart:convert 概述

dart:convert是Dart标准库提供的编码解码工具包，包含了JSON、UTF-8、Base64等多种编码解码功能。其中，JSON处理是最常用的功能之一。

1.1 核心组件

dart:convert中与JSON相关的核心组件包括：

• json：全局函数对象，提供decode和encode静态方法
• JsonCodec：JSON编解码器类，是json对象的底层实现
• JsonEncoder：JSON编码器，负责将对象转换为JSON字符串
• JsonDecoder：JSON解码器，负责将JSON字符串转换为对象

1.2 基本导入

使用dart:convert非常简单，只需在文件顶部添加导入语句：

import 'dart:convert';

这一行代码就可以让我们访问所有JSON处理相关的功能。

2. JSON解码详解

JSON解码是将JSON字符串转换为Dart对象的过程，是网络请求后处理数据的关键步骤。

2.1 基本解码操作

json.decode()方法是最常用的解码方式：

void decodeJson() {
  String jsonString = '{"name":"张三","age":25,"city":"北京"}';
  
  Map<String, dynamic> user = json.decode(jsonString);
  
  print("姓名: ${user["name"]}");
  print("年龄: ${user["age"]}");
  print("城市: ${user["city"]}");
}

代码解析：

• json.decode()接收一个JSON格式的字符串参数
• 返回值类型为dynamic，通常我们将其转换为Map<String, dynamic>或List<dynamic>
• 通过键值对方式访问解析后的数据

2.2 解码JSON数组

当JSON数据是数组格式时，解码方式稍有不同：

void decodeJsonArray() {
  String jsonArray = '[{"id":1,"name":"苹果"},{"id":2,"name":"香蕉"}]';
  
  List<dynamic> fruits = json.decode(jsonArray);
  
  for (var fruit in fruits) {
    print("${fruit["id"]}: ${fruit["name"]}");
  }
}

代码解析：

• 数组类型的JSON字符串解码后返回List<dynamic>
• 需要遍历列表来访问每个元素
• 每个元素仍然是dynamic类型，需要根据实际数据结构进行类型转换

2.3 解码嵌套JSON

实际应用中，JSON数据往往包含多层嵌套：

void nestedJson() {
  String nested = '''{
    "user": {
      "name": "王五",
      "address": {
        "city": "上海",
        "street": "南京路"
      }
    }
  }''';
  
  Map<String, dynamic> data = json.decode(nested);
  String city = data["user"]["address"]["city"];
  print("城市: $city");
}

代码解析：

• 嵌套JSON解码后形成多层Map结构
• 需要逐级访问，每一级都是dynamic类型
• 这种方式虽然直观，但在深层嵌套时容易出错

3. JSON编码详解

JSON编码是将Dart对象转换为JSON字符串的过程，常用于数据存储和网络请求。

3.1 基本编码操作

void encodeJson() {
  Map<String, dynamic> user = {
    "name": "李四",
    "age": 30,
    "isStudent": false,
  };
  
  String jsonString = json.encode(user);
  print(jsonString);
  // 输出: {"name":"李四","age":30,"isStudent":false}
}

代码解析：

• json.encode()接收一个Dart对象作为参数
• 返回JSON格式的字符串
• 支持的类型包括：num、String、bool、null、List、Map

3.2 编码JSON数组

void encodeJsonArray() {
  List<Map<String, dynamic>> fruits = [
    {"id": 1, "name": "苹果", "price": 5.99},
    {"id": 2, "name": "香蕉", "price": 3.99},
  ];
  
  String jsonString = json.encode(fruits);
  print(jsonString);
}

代码解析：

• List类型可以直接编码为JSON数组
• 列表中的元素必须是可编码类型
• 编码后的字符串以[开头，]结尾

3.3 格式化输出

默认情况下，json.encode()输出的是紧凑格式的JSON字符串。如果需要可读性更好的格式化输出，可以使用JsonEncoder.withIndent()：

void customCodec() {
  JsonCodec codec = JsonCodec();
  
  Map<String, dynamic> data = codec.decode('{"key":"value"}');
  
  String prettyJson = JsonEncoder.withIndent("  ").convert(data);
  print(prettyJson);
}

代码解析：

• JsonEncoder.withIndent()可以指定缩进字符
• .convert()方法与json.encode()功能相同
• 格式化后的JSON更易于阅读和调试

4. 类型映射关系

理解JSON类型与Dart类型的映射关系是正确处理JSON数据的基础。

4.1 类型对应表

JSON类型	Dart类型	说明
string	String	字符串
number	int / double	数字
boolean	bool	布尔值
null	null	空值
array	List	数组
object	Map<String, dynamic>	对象

4.2 数字类型处理

JSON中的数字在Dart中默认解析为num类型，需要根据实际情况转换为int或double：

void handleNumbers() {
  String jsonStr = '{"count": 10, "price": 9.99}';
  Map<String, dynamic> data = json.decode(jsonStr);
  
  int count = data["count"] as int;
  double price = data["price"] as double;
  
  int safeCount = (data["count"] as num).toInt();
  double safePrice = (data["price"] as num).toDouble();
}

代码解析：

• 使用as关键字进行类型转换
• 使用toInt()和toDouble()方法进行安全转换
• 当不确定数字类型时，先转为num再转换为目标类型

5. 实际应用：天气数据处理

结合天气查询应用场景，展示dart:convert的实际应用。

5.1 解析天气API响应

void parseWeatherResponse() {
  String weatherJson = '''{
    "city": "北京",
    "current": {
      "temp": 28.5,
      "humidity": 65,
      "condition": "晴"
    },
    "forecast": [
      {"date": "2024-01-01", "high": 30, "low": 20},
      {"date": "2024-01-02", "high": 28, "low": 18}
    ]
  }''';
  
  Map<String, dynamic> data = json.decode(weatherJson);
  
  String city = data["city"] as String;
  Map<String, dynamic> current = data["current"] as Map<String, dynamic>;
  double temp = (current["temp"] as num).toDouble();
  
  print("$city 当前温度: ${temp}度");
}

5.2 构建天气请求数据

void buildWeatherRequest() {
  Map<String, dynamic> requestData = {
    "city": "上海",
    "type": "forecast",
    "days": 7,
    "options": {
      "includeAqi": true,
      "includeHourly": false
    }
  };
  
  String jsonRequest = json.encode(requestData);
  print(jsonRequest);
}

6. 错误处理

在处理JSON数据时，错误处理是必不可少的环节。

6.1 常见错误类型

• 格式错误：JSON字符串格式不正确
• 类型错误：数据类型与预期不符
• 键缺失：访问不存在的键
• 嵌套错误：嵌套结构与预期不符

6.2 安全解析示例

Map<String, dynamic>? safeDecode(String jsonStr) {
  try {
    return json.decode(jsonStr) as Map<String, dynamic>;
  } catch (e) {
    print("JSON解析错误: $e");
    return null;
  }
}

T? safeGet<T>(Map<String, dynamic> data, String key) {
  if (data.containsKey(key) && data[key] is T) {
    return data[key] as T;
  }
  return null;
}

代码解析：

• 使用try-catch捕获解析异常
• 检查键是否存在以及类型是否匹配
• 返回可选类型，调用方可以安全处理null值

7. JsonCodec深入理解

JsonCodec是json全局对象的底层实现，提供了更灵活的配置选项。

7.1 创建自定义Codec

final JsonCodec customCodec = JsonCodec(
  reviver: (key, value) {
    if (key != null && value is String) {
      return value.trim();
    }
    return value;
  }
);

代码解析：

• reviver参数允许在解码过程中对每个键值对进行处理
• 可以用于数据清洗、类型转换等自定义操作

7.2 性能优化

预创建JsonCodec实例可以避免重复创建带来的性能开销：

final JsonCodec jsonCodec = JsonCodec();

void usePreCreatedCodec(String jsonStr) {
  Map<String, dynamic> data = jsonCodec.decode(jsonStr);
}

8. 最佳实践总结

8.1 编码规范

1. 统一数据格式：确保前后端使用一致的JSON格式
2. 字段命名：使用驼峰命名法或下划线命名法，保持一致性
3. 类型一致性：同一字段在不同数据中保持相同类型
4. 版本兼容：考虑API版本升级时的向后兼容性

8.2 性能优化

1. 预创建Codec：避免重复创建JsonCodec实例
2. 按需解析：只解析需要的数据，避免全量解析
3. 缓存结果：对于重复使用的数据进行缓存
4. 使用Isolate：对于大JSON数据，考虑在后台线程解析

8.3 代码组织

1. 数据模型分离：将JSON解析逻辑封装到数据模型类中
2. 工具类封装：创建统一的JSON处理工具类
3. 错误处理统一：使用统一的错误处理机制
4. 日志记录：记录解析错误便于排查问题

9. 总结

dart:convert是Dart处理JSON数据的核心工具，掌握其使用方法对于Flutter开发者至关重要。本章详细介绍了JSON解码、编码、类型映射、错误处理等核心内容，并结合天气查询应用场景展示了实际应用。

在实际开发中，建议结合代码生成工具（如json_serializable）来提高开发效率和代码质量。下一章将详细介绍json_serializable的使用方法。