从单机到云同步:纯血鸿蒙应用「奶茶派」 App 的数据库的架构升级记录

数据模型很难一次设计到位。它是在业务不断“折腾”中慢慢长出来的。本文是记录我的纯血鸿蒙应用「奶茶派」App，复盘从单机到多设备云同步的数据库演变，重点聊主键选择、SPU/SKU 拆分、冲突解决，还有系统数据排序那些看似不起眼但很磨人的细节。

一、起点：跑得动，但经不起推敲

项目一开始需求很简单：记录每天喝的饮品、品牌、杯型和贴纸。我顺手把信息塞进了两张表：

-- 饮品模板
CREATE TABLE drink_template (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT,           -- 饮品名称
  brandName TEXT,
  cupSizeCode TEXT,    -- 'small','medium','large'
  stickerCode TEXT,
  sugarAmount REAL,
  caffeineAmount REAL,
  priceCent INTEGER
);

-- 饮用记录
CREATE TABLE drink_record (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT,
  typeCode TEXT,
  stickerCode TEXT,
  drinkAt INTEGER
);

本地跑起来很快。直到要跨设备同步，三个问题才暴露出来。

自增主键会撞车

设备 A 离线建了个模板 id=15，设备 B 离线也建了 id=15。两条完全不同的记录一同步就冲突。就算改用复合主键或重新映射 ID，也得大面积修改外键——这不是打补丁能救的。

设备时间不可信

updatedAt 本来可以用来裁决冲突，但用户可能手动调时间，或者 NTP 校时会回拨。单靠时间戳，先发生的操作可能因为时钟偏差被后发生的覆盖掉。

没有数据归属

表里根本没有 user_id，同步引擎不知道数据该归谁，更没法安全地隔离多用户。

这三个问题让我意识到：同步不是额外加的功能，得从根上融入到数据模型里。

二、第一次重构：SPU/SKU 分层 + 全局 ID

SPU/SKU 分离

旧设计里，“杨梅果茶”的不同杯型要靠多条 drink_template 记录实现，品牌、类型等属性大量冗余。我照着电商的常见做法拆成了两层：

-- SPU: 与杯型无关的公共属性
CREATE TABLE drink_base (
  id TEXT PRIMARY KEY,        -- 改为 UUID
  brand_id TEXT NOT NULL,
  drink_name TEXT NOT NULL,
  drink_type INTEGER DEFAULT 0,    -- 0=未分类,1=奶茶,2=咖啡...
  default_temp INTEGER DEFAULT 0,
  default_sugar_level INTEGER DEFAULT 0,
  default_sticker_id TEXT,
-- 不含价格、热量、具体容量
  ...
);

-- SKU: 杯型维度的差异化属性
CREATE TABLE drink_variant (
  id TEXT PRIMARY KEY,
  base_id TEXT NOT NULL REFERENCES drink_base(id),
  cup_spec_id TEXT NOT NULL,
  price_cent INTEGER,
  calorie_kcal INTEGER,
  is_default INTEGER DEFAULT 0,
  ...
);

一个 SPU 对应多个 SKU，冗余没了，查询也不用再按 (name, brand) 笨拙地分组。

为什么是 UUID，而不是雪花算法或自增整数？

这个问题很多人纠结。我的选择是基于离线生成唯一性和工程代价的权衡：

• UUID v4：客户端一行代码就能生成，冲突概率可以忽略，不依赖网络。在 SQLite 里当 TEXT 主键，十万级数据的索引效率完全够。去掉连字符后的 32 位 HEX 比标准 UUID 更紧凑。
• Snowflake：虽然是趋势递增的 64 位整数，但要全局唯一就得解决 workerId 分配和时钟回拨。在移动端这几乎是个分布式难题，而且离线新建会受限。
• 自增整数：直接淘汰，原因前面说了。

所以我用了这样的主键生成（客户端实现）：

// 生成 32 位无连字符的 UUID
String uuid = UUID.randomUUID().toString().replace("-", "");

所有表的主键和外键都用这个 TEXT 格式。父记录创建时就有了全局唯一标识，子记录可以在离线状态下直接引用，不需要等服务端分配 ID。

三、为同步而生的三剑客字段

有了全局 ID，还得解决冲突检测、增量同步、数据归属三个问题。我为每张表加了这几个标准化字段：

乐观锁：让冲突裁决有据可依

同步时的核心比较逻辑（伪代码）：

def merge(record_from_remote):
    local = db.find(record_from_remote.id)
if local is None:
        insert(record_from_remote)
elif record_from_remote.version > local.version:
        update_local_with_remote(record_from_remote)
# 否则保留本地，不做任何事（或进入冲突解决策略）

本地每次修改都会 version += 1。version 单调递增，不受时钟影响，冲突裁决变得确定且可追溯。比单纯依赖 updatedAt 可靠——可以看成一种更健壮的“最后写入胜出”。

增量同步的开关：sync_status

每次本地增删改，把对应行的 sync_status 设为 1。同步引擎只需要：

SELECT * FROM drink_base WHERE user_id = ? AND sync_status = 1;

推送成功后，把状态改回 0 并更新 last_sync_at。拉取时也可以按 last_sync_at 增量拉远端变更，双向流量都很小。

数据隔离：user_id 的两种形态

系统预置的品牌、杯型、贴纸等基础数据，user_id 统一为 'system'，永远不参与用户同步。用户创建的数据用实际用户 ID。同步时所有查询都带上 WHERE user_id = ?，天然隔离。系统数据的新增只依赖应用版本升级时的 SQL 迁移脚本。

四、一个小细节：系统数据的排序治理

版本迭代会不断加新的系统杯型或品牌。如果依赖物理插入顺序，新数据就会跑到列表末尾，体验很差。我在所有可能包含系统数据的表里加了 sort_order：

-- 系统数据使用 1–9999 区间
INSERT INTO cup_spec (id, user_id, sort_order, ...) 
VALUES ('sys-cup-small', 'system', 100, ...);   -- 小杯
VALUES ('sys-cup-medium', 'system', 200, ...);  -- 中杯

-- 用户数据从 10000 开始自增

任何查询统一 ORDER BY sort_order ASC，保证系统数据永远在前。以后新增“超大杯”可以插到 250 的位置，完全不影响现有顺序。不要依赖物理存储顺序，这是数据库设计的基本常识。

五、同步引擎的节奏

数据模型稳了，同步逻辑就清爽了：

同步顺序严格按外键依赖拓扑来：

1. brand → cup_spec → sticker_asset（字典表）
2. drink_base（SPU）
3. drink_variant（SKU）
4. drink_record（饮用记录）

每层数据独立事务处理，推送和拉取都用 version 做裁判。删除通过 deleted_at 软删除传播，而不是物理删除，防止灾难性数据丢失。

因为所有 ID 都是 UUID，创建父子关系时不用等服务端返回 ID，离线体验不受影响。

六、回看：值得带走的几条实践准则

1. 主键策略从一开始就要考虑同步：自增整数是单机时代的惯性。多设备写入场景下，全局唯一、不可变的标识才是正解。
2. 用整数枚举代替魔法字符串：可读性靠注释和文档，存储效率、索引性能、类型安全靠整数。drink_type = 1 比 'tea' 健壮得多。
3. 为每张表预留同步元数据：version、sync_status、last_sync_at 不是冗余，是基础设施。哪怕现在不同步，这些字段也能为将来铺路。
4. 显式排序优于隐式顺序：sort_order 让系统数据的演进变得可控，不再受制于数据库的物理实现。
5. 避免同步时产生 ID 循环依赖：客户端预生成 UUID，关联在本地就能完成。联网后只是单纯的数据搬运，架构复杂度直线下降。

整个重构虽然涉及多张表的新增和字段扩展，但因为迁移及时，反而为后面的功能（比如多规格价格、历史快照）铺平了道路。说到底，数据模型的设计是对未来不确定性的投资。 等业务真走到云同步这一步，你会发现，那些当初觉得“多余”的字段，恰恰是保障系统稳定的定海神针。

文章的最后附上APP截图，纯血鸿蒙设备华为应用商店搜索“奶茶派”。