一对多的数据库姻缘：ArkTS 为鸿蒙订单设计外键与明细表

实例：订单与明细（Order）｜技术：订单表 + 明细表、外键约束、OrderDao

一、业务需求分析：订单为什么需要两张表

「一个订单包含多件商品」是最经典的一对多关系：一张订单（SO20250601001）包含蓝牙耳机、数据线、手机壳三件商品。如果把商品直接塞进订单表（逗号分隔），查询「这件商品卖了多少单」会变成噩梦；正确的建模是拆成两张表：

• 订单表 orders：订单本体（订单号、状态、总价、收货人、时间）——一单一行；
• 明细表 order_item：订单里的每件商品（商品名、单价、数量、小计）——一商品一行，用 order_id 指向所属订单。

这个「一（订单）对多（明细）」的结构，是电商、点餐、进销存（实例 6 已见雏形）的通用数据模型，也是 JOIN 联表查询的天然舞台。

核心业务需求：

二、双表字段设计

订单表 orders

明细表 order_item

设计要点拆解：

1. order_no 业务唯一键。UNIQUE 约束保证订单号唯一——业务上订单号是「对外标识」（客服查单、物流对账都用它），比自增 id 更有业务意义。'SO' + Date.now() 生成规则简单可靠（毫秒级不会撞号）。

2. status 用 0~4 数字枚举。五个状态：待支付 → 已支付 → 已发货 → 已完成 → 已取消。数字编码可参与 WHERE status=0 过滤和状态统计，页面映射成文案。

3. product_name 存快照而非外键。明细里的商品名直接存文本（不引用商品表）——这是「快照」设计：订单确定后商品名/价格就是历史事实，不能随商品表变化。如果用户买了「无线蓝牙耳机」后商家改名「蓝牙耳机 Pro」，订单明细应保持当时的名称。价格同理（price 快照成交价）。

4. total_amount 冗余在订单表。总价 = Σ(明细小计)，但订单列表高频读取总价（卡片、统计、导出），冗余存储避免每次都 JOIN + SUM。冗余的代价是写入时必须保证一致——下单事务里先算 total 再写入（见 9-3 文章）。

5. 逻辑外键 order_id。与实例 6 相同，用 order_id INTEGER NOT NULL + 代码级联删除（deleteOrder 先删明细再删订单），不启用物理 FOREIGN KEY。

三、建表 SQL：双表 + 明细索引

CREATE TABLE IF NOT EXISTS orders (
id INTEGER PRIMARY KEY AUTOINCREMENT,
order_no TEXT NOT NULL UNIQUE,
status INTEGER NOT NULL DEFAULT 0,
total_amount REAL NOT NULL DEFAULT 0,
customer TEXT NOT NULL,
phone TEXT DEFAULT '',
address TEXT DEFAULT '',
created_time INTEGER NOT NULL
);

CREATE TABLE IF NOT EXISTS order_item (
id INTEGER PRIMARY KEY AUTOINCREMENT,
order_id INTEGER NOT NULL,
product_name TEXT NOT NULL,
price REAL NOT NULL,
quantity INTEGER NOT NULL,
subtotal REAL NOT NULL
);

CREATE INDEX IF NOT EXISTS idx_item_order ON order_item (order_id);

idx_item_order 索引的意义：明细表的高频查询是「某订单的全部明细」（WHERE order_id = ?）——没有索引，每次全表扫描；有索引，直接定位。外键列必须建索引，这是一对多建模的铁律。

表名 orders 而非 order：order 是 SQL 的保留关键字（ORDER BY），用 orders 复数避开歧义——这是表命名的一个实用技巧。

四、OrderDao 封装：实体与聚合体

数据层核心 OrderDao，实体接口：

export interface Order {
id: number;
orderNo: string;
status: number;
totalAmount: number;
customer: string;
phone: string;
address: string;
createdTime: number;
}

export interface OrderItem {
id: number;
orderId: number;
productName: string;
price: number;
quantity: number;
subtotal: number;
}

/** 订单 + 明细聚合体（页面渲染用） */
export interface OrderWithItems {
order: Order;
items: OrderItem[];
}

OrderWithItems 聚合体接口是本实例的亮点——它不是数据库表对应的实体，而是**「查询结果导向」的组合体**：一个订单 + 它的明细数组。页面 ForEach(this.orders) 直接渲染聚合体，数据层负责组装。聚合体接口让 DAO 返回「页面想要的形状」，UI 零组装。

下单参数用 OrderDraft（订单草稿）+ OrderItemDraft（明细草稿）表达「待创建的数据」：

export interface OrderDraft {
customer: string;
phone: string;
address: string;
items: OrderItemDraft[];
}

export interface OrderItemDraft {
productName: string;
price: number;
quantity: number;
}

为什么分开 Draft 和实体？ 草稿没有 id、orderId、subtotal（下单时才计算），语义上区分「输入数据」与「存储数据」——这是分层架构的细节修养。

五、基础查询：订单列表与单订单明细

全部订单（时间倒序）：

static async queryOrders(context: common.Context): Promise<Order[]> {
const store = await OrderDao.getStore(context);
const predicates = new relationalStore.RdbPredicates(OrderDao.TABLE);
predicates.orderByDesc('created_time');
const result = await store.query(predicates);
return OrderDao.collectOrders(result);
}

某订单的全部明细：

static async queryItemsByOrder(context: common.Context, orderId: number): Promise<OrderItem[]> {
const store = await OrderDao.getStore(context);
const predicates = new relationalStore.RdbPredicates(OrderDao.ITEM_TABLE);
predicates.equalTo('order_id', orderId).orderByAsc('id');
const result = await store.query(predicates);
return OrderDao.collectItems(result);
}

这两个基础查询是一对多关系的「按需加载」形态——先查订单列表，再按需查每个订单的明细。9-3 文章会介绍更高效的「一次 JOIN 查出全部」形态。

六、技术要点对照表

七、文章小结

订单实例建立了一对多双表模型：orders 存订单本体，order_item 存明细，order_id 关联 + 索引加速；明细用「快照」保存商品名和价格（历史事实不随主数据变），总价冗余在订单表（高频读 O(1)）。OrderWithItems 聚合体接口让 DAO 直接返回「页面想要的形状」。这是电商/点餐/进销存共同的骨架。

下一篇（9-2）展示主从嵌套列表 UI——订单卡片内嵌明细，状态标签 + 总价一目了然。

八、双表设计再深挖：主外键关联、状态枚举与金额精度

8.1 主外键关联：逻辑外键与物理外键的取舍

orders 与 order_item 通过 order_id 关联。SQLite 默认不强制外键（PRAGMA foreign_keys 默认 OFF），所以本实例采用逻辑外键：order_id INTEGER NOT NULL + 应用层保证一致性（删除订单先删明细）。为什么不用物理 FOREIGN KEY？

relationalStore 的 delete 支持 predicates，「先删明细再删订单」两行代码即可闭环：

// 删除订单：先删明细，再删订单（代码级联）
const itemPredicates = new relationalStore.RdbPredicates(OrderDao.ITEM_TABLE);
itemPredicates.equalTo('order_id', orderId);
await store.delete(itemPredicates);
const orderPredicates = new relationalStore.RdbPredicates(OrderDao.TABLE);
orderPredicates.equalTo('id', orderId);
await store.delete(orderPredicates);

8.2 订单状态枚举：0~4 数字编码的工程意义

status 用数字枚举而非文本，三个理由：

页面侧用映射函数把数字翻译成文案 + 标签色：

export function statusText(status: number): string {
const map: string[] = ['待支付', '已支付', '已发货', '已完成', '已取消'];
return map[status] ?? '未知';
}

8.3 金额为什么用 REAL：SQLite 没有 DECIMAL

SQLite 只有 INTEGER/REAL/TEXT/BLOB 四种存储类，没有数据库界的 DECIMAL(10,2)。金额用 REAL 后，0.1 + 0.2 这类浮点误差真实存在（0.30000000000000004）。本实例的应对策略：下单计算用 Math.round(total * 100) / 100 保留两位小数（见 9-3），页面展示用 toFixed(2) 格式化（见 9-2）：

// 金额规整：先乘 100 取整再除 100，消除浮点尾差
const total = Math.round(sum * 100) / 100;

九、为什么主从表：一单多品的范式设计

如果只建一张表「订单+商品平铺」，每件商品一行就会重复订单头信息（收货人、地址、电话各重复 N 遍），产生三类问题：

主从表（一对多）设计让 orders 每行代表「一个订单实体」，order_item 每行代表「一件商品」，用外键连接——这就是**第三范式（3NF）**的落地：非主属性完全依赖主键，明细只依赖 order_id，不重复订单头信息。

十、JOIN 联表查询的思路预览

9-1 的「按需加载」先查订单再查明细，N 个订单要 N+1 次查询；JOIN 一次查出全部：

SELECT o.*, i.product_name, i.price, i.quantity, i.subtotal
FROM orders o
LEFT JOIN order_item i ON o.id = i.order_id
ORDER BY o.created_time DESC, o.id DESC;

JOIN 的两种形态在 9-3 深入：INNER JOIN（只出有明细的订单）与 LEFT JOIN（保留无明细的订单）。配合 idx_item_order，JOIN 的关联条件 o.id = i.order_id 走索引而非全表扫描——索引是 JOIN 性能的前提，这就是为什么外键列必须建索引。

十一、索引设计复盘：订单号与外键

SQLite 中 PRIMARY KEY 与 UNIQUE 会自动建索引，idx_item_order 是唯一需要手动建的。三把索引覆盖了订单模块的全部高频查询路径——建表时想清楚「哪些列会被 WHERE/JOIN 命中」，索引设计就完成了。

十二、FAQ

Q1：为什么不用物理外键？
SQLite 的外键需要每次连接 PRAGMA foreign_keys = ON，relationalStore 封装下开启繁琐；且级联删除的默认行为（RESTRICT）反而要写额外代码。逻辑外键 + 应用层两行级联更直白。

Q2：status 为什么不用字符串 ‘PAID’ 而用数字？
数字可参与 GROUP BY status 统计和区间比较，字符串只能等值匹配；且数字编码天然对应流程顺序。代价是阅读性差，用 statusText() 映射函数弥补。

Q3：金额 REAL 会不会出错？
有理论误差，但两位小数的场景下 Math.round(x * 100) / 100 规整后展示无感。生产环境金额敏感系统可考虑「以分为单位存 INTEGER」——本实例为教学清晰选 REAL。

Q4：order_no 用 Date.now() 会不会撞号？
毫秒级时间戳在单机单线程下不会撞；多设备离线场景可加设备前缀（如 SO${deviceId}${Date.now()}），UNIQUE 约束兜底防重。

Q5：为什么明细表存 product_name 快照而不存商品 id？
订单是历史事实。若引用商品表，商家改价/改名后历史订单会被「篡改」，财务对账就出问题。快照 + 成交价才是订单明细的正解。

Q6：查询明细时 orderByAsc('id') 的意义？
明细按插入顺序（id 自增）返回，保证商品顺序与下单时一致——UI 展示的明细顺序就是用户加购的顺序。