7.4 工程结构与多端发布清单

7.4 工程结构与多端发布清单

本节摘要：全书旅程的收口动作。前半节管工程的长久：按功能切分的目录组织、静态分析的纪律化、国际化与可访问性的最低水位、敏感数据的安全存放；后半节管交付的稳妥：四端各自的签名与构建、上架物料、灰度与监控回滚。读完这一节，轻记账从"能跑的工程"正式成为"能交付的产品"。

工程结构：按功能切，不按层切

工程过万行后，组织方式决定迭代速度。两种流派：按层切（全部模型一摊、全部页面一摊、全部仓库一摊）与按功能切（记账一个目录、统计一个目录、同步一个目录，各自内部再分层）。轻记账选后者，理由在变更的局部性——需求几乎总是"动某一个功能"，按功能切时改动集中在一个目录，评审、测试、回滚的边界都清楚：

lib/
  main.dart               # 装配：路由、主题、 ProviderScope
  core/                   # 跨功能的基础件：网络客户端、通用组件
  features/
    ledger/               # 记账功能
      data/               #   仓库实现与数据库访问
      domain/             #   模型与业务规则
      ui/                 #   页面与组件
    stats/                # 统计功能（同构：data、domain、ui）
    sync/                 # 同步功能
    settings/             # 设置功能
​

两条配套纪律。功能目录之间不互相 import 内部实现（要用统计的计算逻辑，把接口提到共享层或经依赖注入），否则"功能"只是目录表演；core 只放真正的通用件，判断标准是"删掉所有功能它依然完整成立"——放进去一个业务组件，跨功能的下水道很快堵住。

静态分析是结构纪律的执法者：工程默认带 lint 基线（不用的导入、print 语句、可空误用都会标红），再加两条自定义规则——禁止功能间越界导入、禁止在界面层直接引用数据库类。分析不通过的代码进不了合并，纪律才能长在流程里而不是靠自觉。

国际化与可访问性：最低水位线

不必等"出海"才开始，两件事都有成本极低的最低水位。国际化：界面文案全部经字符串表引用而非硬编码（配合代码生成保持类型安全），日期与数字用本地化格式化输出——今天只支持中文的应用，明天要加英文时，工作量是"翻一份表"而不是"全项目搜字符串"。可访问性：交互组件用标准组件自带语义（第 2 章说过裸 GestureDetector 缺语义），图片配语义说明，色彩对比度过达标线，字号跟随系统缩放（第 3 章的主题令牌此时免费受益）。适老化检查（第 1 章工具链里 DevTools 的辅助功能视图）放进发布前检查单，抓大放小。

安全实践：敏感数据的三条铁律

记账数据天然敏感，安全投入按风险排序。铁律一：令牌不进普通存储。 登录令牌放在系统级安全存储（Android 的 Keystore 封装、iOS 的钥匙串，现成插件已封装好），shared_preferences 只放可公开的偏好——明文落盘的令牌是安全审计的一票否决项。铁律二：传输全链路加密。 所有接口走 HTTPS 且校验证书，不发明自己的加密——第 5 章网络层的 baseUrl 里那串 scheme 不是装饰。铁律三：日志不落敏感数据。 第 5 章的请求日志在上线构建里关闭响应体输出，崩溃上报的字段白名单化——日志是最常被忽视的泄露面。三条都不难，难在第一行代码就照做：安全是设计属性，不是补丁。

图 18 多端发布流水线

发布清单：四端各自的收口动作

构建命令是发布的最小单元，四端各有一条；签名与物料决定"能不能上"，监控与回滚决定"上了稳不稳"。

$ flutter build appbundle --release          # Android：商店包格式
$ flutter build ipa --release                # iOS：需要证书与描述文件就位
$ flutter build web --release                # Web：静态产物，直接可部署
$ flutter build windows --release            # 桌面示例：产物为目录，另行打包安装器
​

清单按"出包前、过审前、上线后"三段走。出包前：测试流水线全绿、版本号与构建号递增、敏感配置核对（无测试令牌混入）、包体积对比基线无异常增长。过审前：商店截图与描述文案更新、隐私政策与权限声明对齐实际用法（权限要一个审一个，索取与功能无关的权限是拒审高频原因）、审核备注写清测试账号与路径。上线后：崩溃率与关键路径成功率看板就位、用户评价关键词巡检、回滚预案演练过——Android 可停灰度、Web 可秒回滚、iOS 审核期通常要数日，这份"时间差"决定了灰度对 iOS 更重要：宁可灰度多等两天，不做全量翻车的大冒险。

发布不是终点而是回路：监控数据喂回下一轮迭代，崩溃热点喂回测试用例，性能基线喂回优化清单——第 6 章的关卡与本章的流水线首尾相接，轻记账的落地之旅进入常态运转。

版本策略与发布节奏

清单之外还有一个常被轻视的管理动作：版本号策略。四端共用一套语义化版本（主版本.次版本.修订号），构建号单调递增不回退；每次发版前在变更日志里写清"用户可感知的变化"与"内部修复"两栏——前者给商店文案供料，后者给排障定位供线索。混乱的版本号在多端排障时的代价会被放大：用户报障说"最新版"，你要能从版本号还原出那台设备跑的是哪次提交。

发布节奏建议按"火车模型"运转：固定发车时间（比如每两周一个发布窗口），功能赶得上就上车，赶不上等下一班。它比"功能齐了再发" healthier 的地方在于：发布变成了常规动作，每次的变更量小、回滚成本低、团队肌肉记忆不生锈。轻记账两年运营下来，火车模型最大的红利是心理上的——发布不再是全团队屏息的大事件，而是日历上的一格。

本节要点回顾

• 按功能切目录，变更集中在单目录；功能间不引内部实现，静态分析执法；
• 国际化最低水位是文案进表加本地化格式化，可访问性靠标准组件与语义标注；
• 安全三铁律：令牌进系统安全存储、全链路 HTTPS、日志不落敏感数据；
• 出包前查测试与版本与体积，过审前查物料与权限，上线后靠看板与回滚预案；
• iOS 审核期长决定了灰度更重要，Web 可秒回滚，Android 可停灰度。

至此全书闭环。回头看：从第 1 章算清跨平台的成本账开始，骨架、界面、状态、数据、质量、出圈——同一份 Dart 代码走过的每一步落地，你都亲手走过了。