移动应用的用户体验往往受制于网络环境。地铁里、电梯中、偏远山区，网络随时可能中断，如果应用完全依赖服务端接口，一旦断网就寸步难行。离线优先架构的核心思想是：所有数据操作先落本地，网络可用时再与服务器同步。而承载本地数据的引擎，SQLite几乎是事实标准——它体积小、零配置、支持事务、单文件存储，Android、iOS、Flutter、Electron等主流平台都内置或易于集成。本文将以实战视角，讲清楚如何用SQLite搭建一套完整的离线优先数据层。
一、离线优先架构的整体设计思路
离线优先并不意味着把整个服务端数据库复制到本地，而是围绕业务需要，把用户高频读写的数据缓存到SQLite中，让界面渲染只依赖本地库。整体数据流通常是：用户操作先写入本地SQLite，界面通过监听本地数据变化自动刷新；同时操作被记录到待同步队列，网络恢复后由同步模块推送到服务端，并把服务端返回的结果合并回本地。
这个设计带来一个重要转变：本地数据库是唯一的数据真相来源（Source of Truth），UI层永远只读本地，不直接请求网络。好处非常明显：界面响应速度极快（本地查询通常在毫秒级），且网络波动对用户完全透明。代价则是需要自行解决数据同步、冲突处理这两个复杂问题，这也是后面章节的重点。
在分层上，建议把架构拆为三块：数据访问层负责SQLite的增删改查封装；同步层负责操作队列管理和与服务端通信；观察层通过监听机制（如Room的LiveData、Flutter的Stream）把数据变化通知到UI。三层职责清晰，后续维护和测试都会轻松很多。
二、本地数据库表设计与同步字段
离线场景下，表结构不能照搬服务端，必须额外增加同步相关的字段。最常见的做法是给每张业务表加上四个字段：本地主键、服务端ID、更新时间和同步状态。下面是一个典型的建表语句：
CREATE TABLE IF NOT EXISTS todo (
local_id TEXT PRIMARY KEY, -- 本地生成的UUID
remote_id TEXT UNIQUE, -- 服务端ID，未同步时为NULL
title TEXT NOT NULL,
status INTEGER DEFAULT 0,
updated_at INTEGER NOT NULL, -- 本地更新时间戳(毫秒)
sync_state INTEGER DEFAULT 0 -- 0待同步 1已同步 2冲突
);
CREATE INDEX IF NOT EXISTS idx_todo_sync ON todo(sync_state);
CREATE TABLE IF NOT EXISTS sync_log (
id INTEGER PRIMARY KEY AUTOINCREMENT,
entity TEXT NOT NULL, -- 业务表名
local_id TEXT NOT NULL, -- 对应业务记录
action TEXT NOT NULL, -- INSERT/UPDATE/DELETE
payload TEXT, -- JSON快照
created_at INTEGER NOT NULL
);
sync_state字段配合索引，可以让同步模块用极低的代价捞出所有待同步记录。sync_log表则是操作日志，记录每次写操作的类型和数据快照，好处是即使业务数据被覆盖修改，同步队列依然完整。有一点要特别注意：主键必须本地生成（比如UUID），绝不能用自增整数，否则多设备插入时会主键冲突。remote_id先留空，同步成功后回填。
另一个实战技巧是软删除。离线场景下不能直接DELETE记录，否则同步时无从得知这条数据被删过。正确做法是加一个deleted标记位，查询时过滤，同步完成后再物理删除。
三、数据访问层封装与并发性能优化
数据访问层建议提供统一的DAO接口，并在内部保证所有写操作都走事务、同时追加同步日志。以Android的Room或直接用SQLiteOpenHelper为例，核心写入逻辑如下：
public void updateTodo(Todo todo) {
db.beginTransaction();
try {
todo.setUpdatedAt(System.currentTimeMillis());
todo.setSyncState(0); // 标记为待同步
todoDao.upsert(todo);
SyncLog log = new SyncLog();
log.setEntity("todo");
log.setLocalId(todo.getLocalId());
log.setAction("UPDATE");
log.setPayload(gson.toJson(todo));
log.setCreatedAt(System.currentTimeMillis());
syncLogDao.insert(log);
db.setTransactionSuccessful();
} finally {
db.endTransaction();
}
}
把业务写入和日志写入放在同一个事务里，能保证两者要么同时成功要么同时回滚，这是同步可靠性的基石。如果漏掉这一点，可能出现业务数据已改但同步队列没有记录的脏状态，导致数据永远同步不上去。
并发性能方面，强烈建议开启WAL（Write-Ahead Logging）模式。默认的journal模式下，写操作会阻塞读操作，而WAL模式允许读写并发进行，对离线应用这种本地读写频繁的场景提升明显：
PRAGMA journal_mode = WAL; PRAGMA synchronous = NORMAL; PRAGMA foreign_keys = ON;
同时要注意SQLite的写入是库级别串行的，不要在多个线程里各自持有连接并发写，正确做法是单写多读：写操作集中在一个串行队列或单一写连接中执行，读操作可以并行。Room框架默认就是这么处理的，自己封装时也要遵守这个原则，否则会遇到database is locked异常。
四、网络恢复后的增量同步与冲突处理
同步模块的触发时机一般有两个：应用启动后和监听到网络恢复事件。同步流程是典型的生产者消费者模型：从sync_log中按时间顺序取出未处理的日志，逐条调用服务端接口，成功后更新业务表的sync_state并回填remote_id，最后删除该条日志。任何一条失败就停止本次同步，下次继续，保证顺序性。
public void syncUp() {
List<SyncLog> logs = syncLogDao.peekBatch(50);
for (SyncLog log : logs) {
try {
SyncResult r = api.push(log.getAction(), log.getPayload());
todoDao.markSynced(log.getLocalId(), r.getRemoteId());
syncLogDao.deleteById(log.getId());
} catch (IOException e) {
break; // 网络异常，终止本轮，下轮重试
} catch (ConflictException e) {
todoDao.markConflict(log.getLocalId());
syncLogDao.deleteById(log.getId());
}
}
}
冲突处理是离线架构绕不开的话题。典型的冲突是：设备A和设备B都修改了同一条记录且都未同步。常见策略有三种：最后写入胜出（Last Write Wins，按updated_at比较，实现简单但可能丢数据）、服务端权威（以服务端为准，客户端覆盖）、字段级合并（最精细但实现复杂）。实际项目中，对于笔记、待办这类个人数据，用updated_at做LWS通常够用；对协作类数据则建议引入版本号或操作变换（OT/CRDT）机制。
下载同步同样重要。除了推数据上去，应用还要定期拉取服务端变更。高效的做法是增量拉取：服务端提供按updated_at游标查询的接口，客户端记录上次同步时间点，每次只拉取之后的变更，再按remote_id合并到本地。整体方向上建议遵循向上推操作日志、向下拉数据快照的原则，两个方向职责分离，逻辑最清晰。
五、总结
用SQLite实现离线优先架构，关键点可以归纳为四条：一是确立本地库为唯一数据真相，UI只读本地；二是表设计提前规划好同步字段与操作日志，主键本地生成；三是写操作走事务并开启WAL模式，兼顾可靠性与并发性能；四是同步采用队列化推送加增量拉取，配合明确的冲突策略。这套思路在待办、笔记、表单采集、地图等强离线场景中已被反复验证，掌握之后，无论是原生开发还是跨平台框架，都能快速落地一套稳定可靠的离线数据层。