第五章 数据进出：网络与同步
第五章 · 数据进出
章节摘要：状态与存储立好后，轻记账还差"与外界对话"的能力。本章打通数据的进出通道：网络请求的两套主流写法（http 与 dio）、报文到 Dart 对象的模型层工程、离线优先的同步设计（弱网与断网时账照样记，联网后补传与和解），最后是依赖生态的管理与后端服务的接入方式。读完本章，轻记账从单机应用升级为多设备同步的应用。
学习目标
读完本章，你应当能够：
- 为给定场景在 http 与 dio 之间选择，并说明理由；
- 搭一个带拦截器的 dio 客户端：统一超时、鉴权头、错误归一化与重试日志；
- 手写健壮的 JSON 模型层，处理嵌套对象、枚举、数字类型坑与空字段；
- 设计离线优先的写入路径：本地先落盘、标记未同步、联网补传、按规则和解冲突；
- 用语义化版本与约束管理 pubspec 依赖，看懂版本解析报告，安全升级；
- 说出 Firebase 这类后端即服务与自建 GraphQL 服务的适用分界与接入成本。
核心概念速览
一句话立住本章：网络层的工程质量不在"能发请求"，而在"失败时应用该怎么办"——超时、重试、离线、冲突，这四件事才是真实世界的数据进出。
子章节导航
05-1 网络请求落地：http 与 dio：从最短可用的 http 请求起步，到 dio 的拦截器体系——鉴权、日志、错误归一化一次配好，全程服务轻记账的账单同步接口。
05-2 JSON 模型层：从报文到 Dart 对象：手写 fromMap 与 toMap 的完整工程，嵌套结构、枚举与数字类型的坑逐一排掉，并给出代码生成方案的取舍账。
05-3 离线优先的同步设计：移动网络注定不可靠。本节设计"本地先赢"的写入路径，把第 4 章埋的 synced 标志位用起来，处理补传顺序与冲突和解。
05-4 依赖生态与后端集成：pubspec 的版本约束与解析规则，安全升级依赖的操作序列；Firebase 类后端即服务与自建服务的接入方式与成本对比。
子章节之间的逻辑关系
四节是"一条报文的完整旅程"：发出去（05-1）、翻译回来（05-2）、失败了也有出路（05-3）、而这整套能力的供应链有人管（05-4）。它们建立在第 4 章的仓库模式之上——网络层是仓库的又一种实现；也为第 6 章提供测试素材——网络异常、超时与冲突正是测试用例的富矿。
本章知识点清单
以下条目均可自测，答不出的就是没读透的位置：
- 说出 http 换 dio 的判断线：需要横切逻辑（鉴权、日志、重试、归一化）时换；
- 配置 dio 的两级拦截器，解释 401 自动刷新重放为什么放在拦截器而不是调用处；
- 写出过四道坑的 fromMap：数字过 num、可空用问号取、时间存 UTC、枚举带兜底；
- 说出代码生成方案的适用线：模型成规模或字段频繁变动再上；
- 画出离线优先的双路径：写入只碰本地，同步退到后台补课；
- 解释同步任务的幂等要求，以及离线整批暂停与单条拒绝跳过的产品语义；
- 复述冲突和解的两条规则：最后写入胜出、删除赢过修改；
- 读懂插入符约束与锁文件的分工，执行一次安全的大版本升级序列。
[05-1 请求] ──发出──> [05-2 模型] ──翻译──> [05-3 同步] ──兜底──> [真实弱网世界] [05-4 依赖与后端] ──供给──> 整条链路
前置知识与后续延伸
前置：第 2 章的异步与 Isolate（大报文解析要挪出界面线程）、第 4 章的仓库模式与 synced 标志位；HTTP 的基本概念（方法、状态码、头部）按需补即可。
本章的阅读顺序不建议打乱：05-1 与 05-2 是硬技能，代码要亲手跑；05-3 是设计题，先读懂"为什么"再抄实现，直接抄容易把幂等与事务这些关键处抄丢；05-4 可以放到工程稳定后补读。每节末尾的要点回顾按"能复述"标准自测——网络层的知识只有能讲出来，才说明真的组织过了。
延伸：05-1 的拦截器是第 6 章日志体系的一部分；05-3 的同步队列将在第 6 章的集成测试里被弱网模拟反复敲打；05-4 的依赖纪律直接决定 CI 环境的稳定性。Web 与桌面上，本章的部分选型要重新裁决——存储插件、平台差异与 CORS 限制在第 7 章有专节对照，读完本章先别急着把同步功能搬到 Web。