Flutter 项目实战
在最小待办页面已经具备加载、失败、空、成功与重试后,再加入真实接口、缓存和离线编辑。先明确事实属于哪里:页面保存展示状态,服务器保存业务事实,本地数据库保存缓存与待同步修改,三者不能相互冒充。
用一次离线编辑确定合同
用户A在离线时修改待办42标题,重新联网时服务器上该任务也可能已被别人修改。只把本地整行覆盖回服务器,会丢失另一方编辑;只按最后返回请求覆盖页面,也可能把新标题改回旧值。
为待同步记录保存账号、任务ID、操作ID、基准版本、修改内容与状态。请求携带预期版本或服务端支持的条件更新;冲突返回后保留本地草稿与服务器版本,按业务选择合并、重新编辑或放弃。客户端生成的操作ID只有服务端校验并持久化去重后,才能支持可靠重试。
| 状态 | 进入条件 | 后续行为 |
|---|---|---|
| 待同步 | 本地事务已保存草稿与操作 | 有网后按受控并发发送 |
| 同步中 | 当前操作获得发送资格 | 禁止重复并发发送同一操作 |
| 已确认 | 服务端返回确定结果 | 原子更新本地版本和队列 |
| 冲突 | 基准版本已变化 | 保留两方内容并提示处理 |
| 待重试 | 网络故障或暂时失败 | 退避、次数限制与人工重试 |
| 结果未知 | 超时但可能已写入 | 按操作ID查询后再决定重发 |
取消页面等待不代表取消后端修改。移动端进程可能被系统终止,不能指望 dispose 一定写回草稿;需要恢复的数据应在操作过程中持久化。后台运行也受系统限制,不承诺离线队列能无限驻留执行。
请求与缓存按身份隔离
缓存键至少包括账号或租户、查询条件、排序与分页身份。账号切换时停止旧请求、清理或隔离旧缓存、状态与待同步队列;否则相同任务ID可能显示另一个账号的数据。
第一页刷新可先显示缓存并标明刷新状态;刷新失败保留旧数据和错误,不把网络失败解释成空列表。加载更多失败保留已有内容与重试入口,过滤条件改变后重置游标。旧请求返回时验证查询代次,不能覆盖新筛选结果;稳定排序与去重还需服务端合同配合。
目录跟随责任拆分
小项目先按功能分组:features/task/ 内放模型、页面、状态对象和Repository。确实需要多个实现时再分 presentation/application/domain/data,不要为了分层制造空文件。
Repository负责远程、本地与错误策略;页面不拼URL或处理数据库。DTO负责接口字段与解析,领域模型负责业务含义,ViewState负责页面状态。例如 due_at 必须明确时区与可空规则,再格式化为本地时间;不能把解析失败默认为“没有截止日期”。
状态管理与路由
加载、空、成功、失败是起点,刷新和加载更多通常与已有数据同时存在。若每次刷新都切成纯Loading,会造成列表闪烁、滚动位置和输入丢失。选择ChangeNotifier、Riverpod或Bloc时,优先比较状态能否描述这些组合、依赖如何注入与释放,而非库名热度。
路由需覆盖冷启动深链、未登录恢复目标、任务不存在、无权限与系统返回。简单栈可用Navigator;有Web URL同步或复杂深链时选择合适的Router方案,不把命名路由当作通用推荐。账号变化时重新校验目标权限,不能只凭本地路由守卫保护后端。
测试与观测
| 场景 | 可执行断言 |
|---|---|
| 刷新失败 | 旧列表保留,错误可重试 |
| A慢于B返回 | 页面仍显示B的筛选结果 |
| 账号切换 | 旧响应与旧缓存不出现在新账号 |
| 同一操作超时后重试 | 服务端只产生一次业务效果 |
| 版本冲突 | 草稿不丢失,不静默覆盖服务端 |
| 进程被终止后重启 | 从本地恢复未确认操作 |
Repository测试使用受控时钟、Completer与隔离数据库;Widget测试验证实际分支和操作;真机集成验证权限、后台、系统返回、弱网与发布包。Golden测试控制字体和设备尺寸,不能替代语义、交互及屏幕阅读器验证。
记录版本、平台、查询/操作ID、耗时、错误类别与队列积压,避免记录token或完整业务内容。存储插件按维护状态、事务、迁移、加密与平台能力选择,不把库名清单当作选型结论。发布与符号保留见项目交付。
