移动端数据与同步
移动端如何通过 API 获取数据、缓存状态、刷新列表和处理弱网
移动端不直连数据库。它只通过 01MVP API 拿数据，App 里做短期缓存、刷新和错误恢复。
你将学到
- 移动端数据请求的基本流向：用户操作到 API 再到数据库
- 首次加载、下拉刷新、弱网、未登录等状态怎么处理
- 为什么缓存不能当数据库
- 多端同时编辑时的同步规则
- 弱网和离线体验的最低要求
数据流向
数据请求的链路很简单：用户操作触发请求，App 的 TanStack Query 负责缓存和刷新，请求通过 oRPC API 到达后端，后端访问数据库。App 不直接碰数据库。
这意味着数据的权威来源永远是服务端。App 里的任何缓存都只是副本，可以被丢弃、被替换、被清空，都不会影响数据本身。
移动端要处理这些状态
| 状态 | 怎么做 |
|---|---|
| 首次加载 | 给个轻量 loading，别白屏 |
| 下拉刷新 | 重新请求关键数据 |
| 弱网 | 给出能看懂的提示，让用户能重试 |
| 未登录 | 引导去登录，别显示一片空白 |
| 权限不足 | 说清楚原因，别暴露内部字段 |
这些状态覆盖好了，用户就不会卡在某个页面动弹不得。TanStack Query 会帮你处理大部分缓存和刷新逻辑，但你需要在 UI 层正确响应每种状态。
别把缓存当数据库
App 缓存只是为了更快显示页面，真正的数据在后端。用户退出登录、切换账号、权限变了，App 都要清掉或刷新缓存。
不要假设缓存里的数据一定是对的。任何时候拿到新数据，都应该用新数据替换缓存。如果一个请求失败了，告诉用户失败了，不要显示过期的缓存数据假装成功。
多端输入时的最低同步规则
如果用户会在 Web、Mobile、Desktop 同时创建或编辑内容，先把同步规则写清楚。MVP 可以简单，但不能含糊。
| 规则 | 建议 |
|---|---|
| 数据来源 | 服务端是最终来源，App 只做本地缓存和临时草稿 |
| 写入请求 | 每次创建、编辑、删除都带上用户身份和请求唯一标识，避免重复提交 |
| 列表刷新 | 进入页面、下拉刷新、重新联网后重新拉取关键列表 |
| 删除处理 | 用服务端删除状态或更新时间处理，避免旧设备把已删内容刷回来 |
| 冲突策略 | 先用"最后一次保存为准"，重要字段再做确认或合并 |
| 退出登录 | 清掉当前用户缓存、草稿和本地 token |
如果产品包含笔记、Todo、洞察这类高频编辑内容，建议把"最后保存时间"和"最后编辑端"显示给用户。这样即使发生冲突，用户也能理解当前看到的是哪一版。
弱网和离线体验
第一版不一定要做完整离线编辑，但要避免用户以为内容已经保存。
| 状态 | UI 应该怎么反馈 |
|---|---|
| 网络断开 | 明确显示当前无法同步 |
| 保存中 | 给出进行中状态，避免重复点击 |
| 保存失败 | 保留用户输入，提供重试 |
| 重新联网 | 自动刷新关键数据，必要时提示用户重新提交 |
网络状态变化时，不要弹模态框打断用户操作。用轻量的 banner 或 toast 提示就够了。
API 请求的基本规范
移动端发请求时，遵守几个基本规范：
- 所有请求都带用户身份，不要用匿名请求访问受保护接口
- 写入操作（创建、编辑、删除）带上请求唯一标识，防止重复提交
- 列表请求支持分页，不要一次拉全量数据
- 响应格式保持统一，方便统一处理错误
这些规范在 oRPC 的类型定义里大部分已经帮你约束了，但 UI 层的处理还是需要自己做。
下一步
数据请求和同步的规则搞清楚后，进入 本地存储与会话 了解 SecureStore、缓存和退出登录清理。
想和其他创造者交流？
这篇文档有问题？