22 KiB
SSPF 平台包需求(三):让业务仓的库操作走同一个 Db
目标 tag:
v0.5.0(v0.4.0已用于「平台包零业务清理」,不能复用) 提出方:tdc-rs(厚业务仓,自带状态类型 / 自带 JSON 归一语义) 状态:已实施并发布 → annotated tagv0.5.0已推origin(实施记录见 §10)。 业务侧已按 §5 完成切换(tdc-rs提交e13768e,见 §11);两条附加判据全部落地。 前两份需求:SSPF-PLATFORM-PACKAGE.md(v0.2.0)、SSPF-BUSINESS-COMPOSITION.md(v0.3.0)。
0. 一句话
Db::pg() 把同一个 Arc<PGlite> 交给了业务仓,但没有把 Db.lock 一起交出去。
⇒ 平台侧所有 SQL 持 Db.lock,业务侧所有 SQL 持业务仓自己的 db_lock,
两把锁互不覆盖,两边并发写同一个 PGlite 后端时可能交错。
本需求要平台包补一个「持同一把锁、但不碰业务仓的 JSON 键归一」的入口,
让业务仓把库操作统一收进 Db 的串行域,且对外契约一字不变。
1. 背景:三版之后剩下的唯一硬缺口
| 版本 | 解决了什么 | 留下什么 |
|---|---|---|
| v0.2.0 | 门面 crates/sspf/、零业务、git tag 依赖 |
业务仓只能整包注入 |
| v0.3.0 | Db.pg: Arc<PGlite> + pg()、两阶段装配、Extras 三注入点 |
Db::pg() 绕过 Db.lock(db.rs 的 pg() 文档自己写明了) |
| v0.4.0 | 平台包零业务清理、示例搬技能仓 | 与本题无关 |
| v0.5.0(本需求) | 业务仓库操作与平台共用同一把 Db.lock |
— |
tdc-rs 在 P2 完成了单进程 / 单库 / 单端口装配,P3 打通了两套会话;
CHANGELOG.md 的 v0.3.0 条目也已如实登记「Db::pg() 绕过 Db.lock 时,
平台与业务各自的多语句事务可能交错」。本需求就是来销这一条的。
2. 硬约束(已核实,不是推测)
2.1 单实例 / 单后端
pglite-rs 0.2 进程级只允许一个 PGlite 实例;平台与业务共用同一个
Arc<PGlite>(Db::pg())。因此本题不是「再开一个连接」,而是
「同一个连接上,两边的临界区必须互斥」。
2.2 平台侧的锁是私有的
crates/sspf-store/src/db.rs:
Db { pg: Arc<PGlite>, lock: Arc<Mutex<()>> }——lock字段private;Db::query_json/query_json_params/exec/exec_params/scalar_text/ensure_schema全部先let _guard = self.lock.lock().await;Db::begin()返回DbTransaction,_guard在整个事务期间持有同一把锁;Db::pg()的文档明写:「这个句柄绕过本层的Db.lock……一次业务操作跨多条 SQL 的串行化要业务仓自己保证」。
⇒ 业务仓今天拿不到 Db.lock,只能自己造一把 → 两把锁。
2.3 🔴 JSON 键归一是两套,直接换 Db::query_json 会破契约
这是本需求最容易踩的坑,务必先读:
sspf::Db::query_json* |
tdc-rs::platform::db::query_json* |
|
|---|---|---|
| SQL 包裹 | SELECT row_to_json(q)::text AS _row FROM (…) AS q |
同款 |
| 键归一 | normalize_json_keys:f_ 前缀 → camelCase、还原被 PG 折叠的未加引号别名、双引号别名视为权威 |
完全不归一,原样返回 PG 折叠后的列名 |
| 谁再归一 | 平台 handler 直接用 | tdc::mapper 用 column_to_json_key 在 Rust 侧做 f_* → camelCase |
db.rs 的 normalize_json_keys 注释也承认「与 tdc-rs 的做法一致」,
但那是最终结果一致,中间层不一致:业务仓的 SQL 投影是 f_ 列名,
mapper 已经做了一次转换。若业务侧直接改调 Db::query_json_params,
键会被归一两次 / 在加引号别名上漂移 ⇒ tdc-rs 的 132 条端点响应形状会变。
🔴 因此:禁止用「把业务 SQL 改调现有
Db::query_json*」来实现本题。 现有query_json*的归一行为一个字都不许改(面 A / 面 B 契约依赖它)。
2.4 业务仓的库操作已经收在一个文件里(本轮先做了收拢)
🔴 调研时发现的坑:原先 tdc-rs/src/tdc/service/{crud,account,identity}.rs 有 12 处
直接 state.db.query(&sql, &refs)(写路径),绕过了 platform/db.rs。
本轮已把它们全部收进新增的 platform::db::exec_params,并用
scripts/check-db-access.sh 护栏钉死「业务层不许再直接碰裸 PGlite」。
⇒ 现在 tdc-rs/src/platform/db.rs 是唯一出口,6 个 pub 函数:
| 函数 | 用途 | 平台侧对应能力 |
|---|---|---|
query_json(db, sql) |
无参 SELECT | query_json_params(db, sql, &[]) |
query_json_params(db, sql, params) |
带参 SELECT(row_to_json 包裹,不归一) |
需要新增 Db::query_json_raw |
exec_params(db, sql, params) |
带参写(INSERT / UPDATE / DELETE,丢弃结果集) | 现有 Db::exec_params 即可 |
query_scalar_text(db, sql, params) |
取第一行第一列文本(带参) | 需要新增 Db::query_rows |
column_types(db, table) |
查 pg_catalog 拿列类型(原始行) |
需要新增 Db::query_rows |
ensure_schema(db) |
启动期建表(多语句 exec) |
现有 Db::exec 即可 |
另有 2 处豁免(护栏白名单,不参与请求期并发):
src/tdc/schema.rs::ensure_schema_coexist—— 启动期on_ready单线程建表;src/main.rs的on_ready—— 调的是sspf::Db::exec(本身已持平台锁,不是裸句柄)。
⇒ 业务侧切换只需改 platform/db.rs 的 6 个函数 + 状态里注入 Arc<Db>;
mapper.rs / service/* / controller/* 零改动(它们已经全部走封装)。
3. 需求(R1–R7)
R1(必选)新增 Db::query_json_raw —— 持锁 + 不归一
impl Db {
/// 持 `Db.lock`,把 `sql` 用 `row_to_json` 包成单行文本并反序列化,
/// **不做任何 JSON 键归一**(返回 PostgreSQL 原样的列名 / 别名折叠结果)。
///
/// 给自带归一语义的厚业务仓用:它们自己在上层把 `f_*` 转 camelCase,
/// 平台不能替它做第二次。
///
/// 🔴 与 `Db::query_json` 的唯一差别就是「不归一」;SQL 包裹、参数绑定、
/// 错误类型、锁,全部与 `query_json_params` 逐字一致。
pub async fn query_json_raw(
&self,
sql: &str,
params: &[&(dyn ToSql + Sync)],
) -> Result<Vec<Value>, pglite::Error>;
}
实现建议:把 query_json_inner 拆成 query_json_inner_raw(只持锁 + 包裹 +
反序列化)与 query_json_inner(在其结果上再跑 normalize_json_keys),
两者共用同一个 let _guard = self.lock.lock().await。
不要复制粘贴一整份 SQL 包裹逻辑 —— 复制必然漂移。
对应的无参便捷方法 query_json_raw(sql) 可选(业务仓只有一个 query_json 无参入口,
内部转调带参版即可)。
R2(必选)新增 Db::query_rows —— 持锁 + 原始行
impl Db {
/// 持 `Db.lock`,执行带参查询并返回原始 `pglite::Row`。
/// 用于元数据查询(`pg_catalog`)、取第一行第一列等**不需要 row_to_json** 的场景。
pub async fn query_rows(
&self,
sql: &str,
params: &[&(dyn ToSql + Sync)],
) -> Result<Vec<pglite::Row>, pglite::Error>;
}
Row 类型通过 crates/sspf-store/src/db.rs 已有的 pub use pglite 对外可见;
门面 crates/sspf/src/lib.rs 已 pub use sspf_store::db::pglite ⇒ 业务仓无需
重复声明 pglite 依赖。
R3(必选,零新增代码)写路径复用现有 Db::exec / exec_params
平台已有且都持锁:
exec(sql):simple protocol,可多语句、整批一个隐式事务(建表 / 批量 DDL 用);exec_params(sql, params):extended protocol,单语句(带参 INSERT/UPDATE/DELETE 用)。
需求里明确写一句「业务仓写路径一律改调这两个,不许再直接 pg.exec(...)」即可,
平台侧不需要新增方法。
R4(推荐,作为 R1/R2 的保守替代)Db::lock_owned()
若平台侧不愿在公开签名里出现 pglite::Row,可改成暴露一个所有权 guard:
impl Db {
/// 取得进程级业务锁(与所有 `Db::*` / `DbTransaction` 共用同一把)。
/// 业务仓可在 guard 存活期间用 `Db::pg()` 的裸句柄执行自有 SQL,
/// 保持自己的归一语义;guard drop 即释放。
pub async fn lock_owned(&self) -> tokio::sync::OwnedMutexGuard<()> {
Arc::clone(&self.lock).lock_owned().await
}
}
- 比
pub fn lock(&self) -> &Mutex<()>安全:不暴露内部可变性,guard 有明确生命周期; - 业务仓写
let _g = db.lock_owned().await;后函数体一字不改 ⇒ 切换成本最低; - 🔴 文档必须写明纪律:持 guard 期间不得再调任何
Db::*方法(tokio Mutex 不可重入 ⇒ 死锁),也不得再begin()。
平台侧可 R1+R2 与 R4 二选一:给了 R4,业务仓就能用「只加锁」路径完成本题; 给了 R1+R2,业务仓改用
Db而不是PGlite,封装更好。两者都给也欢迎, 但至少要有一个。
R5(必选)Db::pg() 注释补一句指路
现有 pg() 文档已经写了「绕过 Db.lock」,但没写「该怎么办」。补:
/// 若业务仓需要与平台共用串行域,请改用 `query_json_raw` / `query_rows` /
/// `exec*` / `lock_owned()`;本句柄只适合启动期单线程建表与只读元数据探测。
R6(必选)门面导出核对
crates/sspf/src/lib.rs 已 pub use sspf_store::db::Db 与 pub use sspf_store::db::pglite。
新增方法自动可见,不需要新增 re-export;但要在门面文档的版本表与
version_matches_the_manifest 单测里把 cargo 版本同步为 0.5.0。
R7(必选)静态闸门 + 集成探针
- 新增静态闸门 AR20(编号按实现时的最大编号顺延):钉住
「
query_json_raw的实现里不出现normalize_json_keys」以及 「query_json/query_json_raw共用同一个lock」—— 反自证: 把normalize_json_keys塞进 raw 路径 ⇒ 当场红。 - 新增集成探针
db_raw_it.rs(或并入db_it.rs):query_json_raw("SELECT f_id, f_real_name FROM …")⇒ 键仍是f_id/f_real_name(没有被转成id/realName);- 同一个 SQL 走
query_json⇒ 键是id/realName;两条路径结果同时成立; - 持
lock_owned()(若实现)期间并发跑Db::exec⇒ 后者被阻塞到 guard 释放 (用tokio::time::timeout断言,别用 sleep 猜); query_rows能读pg_catalog原始行。
明确不做
- ❌ 不改
Db::query_json/query_json_params/normalize_json_keys的任何行为; - ❌ 不把业务仓的 18 实体
EntitySpec化(那是另一条独立改造,见 §8); - ❌ 不引入第二把锁、不在业务仓复制一份归一逻辑;
- ❌ 不改面 A / 面 B 任何端点形状、码表、表结构;
- ❌ 不给
Db::pg()加隐式锁(会破坏启动期建表与现有探针)。
4. 验收判据(平台侧)
| # | 判据 |
|---|---|
| A1 | cargo test --workspace 全绿,测试数不低于当前基线(v0.4.0 清理后基线见 HANDOFF.md,别硬写旧数字 710) |
| A2 | scripts/check-arch.sh 全绿 + --self-test 全绿(含新增 AR20) |
| A3 | scripts/verify.sh --fast 全绿 |
| A4 | 新探针 db_raw_it 4 条断言全过(尤其「raw 不归一」与「同一把锁互斥」) |
| A5 | cargo tree -p sspf 依赖树仍 0 个 sspf-pack-*(AR17 不回归) |
| A6 | Finish::default() 路径与 v0.4.0 逐字等价;Platform::assemble() / serve() 签名未改 |
| A7 | 门面 sspf::VERSION == "0.5.0",crates/sspf/Cargo.toml 显式 version = "0.5.0" |
| A8 | CHANGELOG.md 追加 5–8 行,只写「改了什么 / 什么影响」,并销掉 v0.3.0 那条「双锁」已知局限 |
| A9 | docs/known-limitations.md 的「双锁」条改成「已由 v0.5.0 的 raw 入口解决」 |
| A10 | git tag -a v0.5.0 annotated 并推远程(git ls-remote --tags origin 可见 tag 与 ^{}) |
| A11 | 仓外 git 依赖实测一次:只写 sspf = { git = "…", tag = "v0.5.0" } 的空 crate |
cargo check 通过,且能调用 Db::query_json_raw / lock_owned() |
5. 业务仓侧切换清单(tdc-rs,等 v0.5.0 到位后由本仓执行)
这一节是给平台侧看的「下游会怎么用」,也是业务仓自己的施工单。
Cargo.toml:tag = "v0.4.0"→tag = "v0.5.0"(当前业务仓仍锁v0.3.0, 中间跨一个版本,需复核 v0.4.0 的零业务清理对业务仓零影响 —— 已确认: 业务仓从没用过示例包,cargo tree里 0 个sspf-pack-*)。tests/sspf_platform_package.rs:版本断言同步。src/platform/state.rs:AppState增加sspf_db: Option<Arc<sspf::Db>>(或进程级OnceLock<Arc<Db>>,与现有process_db_lock()同款),AppState::new保持签名不变、默认None,加一个with_sspf_db()builder。src/main.rs:boot.state.db.clone()注入(boot.state.db是Arc<Db>)。src/platform/db.rs6 个函数内部改为持平台锁 / 调 Raw API,函数签名保持db: &PGlite不变 ⇒ 所有调用点零改动:query_json_params→Db::query_json_raw(或lock_owned()+ 原样db.query);exec_params→ 现有Db::exec_params(或 guard + 原样db.query);query_scalar_text/column_types→Db::query_rows(或 guard + 原样db.query);query_json→ 转调query_json_params;ensure_schema保持启动期裸句柄(豁免,见下)。
- 保留 tdc 的
db_lock:它负责「一次业务操作跨多条 SQL」的原子性 (如service/identity.rs的「查不到 ⇒ 插入」),与跨平台互斥是两件事。 切换后Db.lock成为全局串行点,tdc 锁只是业务内部额外一层,无害。 - 豁免
src/tdc/schema.rs::ensure_schema_coexist:只在on_ready启动期、 平台路由还没开始服务时单线程跑,不存在并发写;继续保持裸pg.exec。 若将来它移到请求期,必须一并改走Db::exec。 - 静态护栏
scripts/check-db-access.sh(本轮已落地并跑绿): 把「业务代码不得直接碰裸PGlite」钉死;允许清单 3 个文件 (platform/db.rs封装本身 /tdc/schema.rs启动建表 /main.rs的sspf::Db::exec),当前命中 7 处全在白名单、0 处越界。 ⇒ v0.5.0 到位时切换面确定、可验证,不会有人从别处漏一条 SQL 出去。
业务侧验收(v0.5.0 到位后)
cargo test≥ 294 passed / 0 failed / 1 ignored(当前基线 294);- 五把尺子全绿:smoke 80/80、
check-contract.sh132 条端点一致、其余三把静态全绿; check-dual-contract.sh17/17(含 P3 会话桥断言);- 🔴 响应形状零漂移:切前后的
/api/ssw/tdc/*列表 / 详情 / 分页 JSON 键集合 逐字相同(可直接用 smoke 的hidden_fields/ numeric 列断言覆盖); - 并发探针:业务侧与面 B 同时写同一库不出现
database is locked/ 交错读。
6. 风险表
| 风险 | 后果 | 缓解 |
|---|---|---|
把 normalize_json_keys 塞进 raw 路径 |
业务仓 132 端点响应键漂移 | AR20 反自证 + db_raw_it 断言 1&2 |
lock_owned() guard 期间再调 Db::* |
tokio Mutex 不可重入 ⇒ 死锁 | 文档纪律 + 探针用 timeout 而非 sleep |
query_rows 暴露 pglite::Row |
业务仓被迫声明 pglite 依赖 | 门面已 pub use pglite,用 sspf::pglite::Row 命名 |
| 复制一份 SQL 包裹逻辑 | 两份实现漂移 | R1 明确要求拆 *_inner_raw 共用 |
| 业务仓忘了改某条 SQL | 仍绕过锁 | 业务侧静态护栏(§5.8)+ 五把尺子 |
| 版本号与 tag 不一致 | 业务仓 git + tag 解析到旧代码 |
A7 / A10 / A11 三道核对 |
7. 发布节奏
- 平台侧实现 R1–R7,跑完 A1–A9;
- 打 annotated tag
v0.5.0并推远程(A10),跑仓外 git 探针(A11); - 通知业务仓;业务仓按 §5 切换,跑完业务侧验收;
- 两仓各自写工作日志 /
CHANGELOG,docs/known-limitations.md销条。
🔴
v0.4.0已是「零业务清理」版且已推远程(tag 现指向ff34ca5, 其后含「门面 cargo 版本对齐 0.4.0」与「本需求入库」两个提交),不要挪动它; 实现本需求请直接在这条基线上开v0.5.0,别改v0.4.0的 tag 或版本号。
8. 与「18 实体 EntitySpec 化」的关系
tdc-rs 的 18 个实体至今走自研 CRUD 引擎(分档判定 / 状态机 / 聚合详情 /
编码生成 / 隐藏字段),EntitySpec 只声明列清单并生成 6 条 CRUD 路由。
EntitySpec 化是另一条独立改造,不是本题的前置条件,也不该搭车做:
本题只统一「库操作的锁与入口」,不改任何业务规则、不动 132 条端点。
等本题落地、Db.lock 成为唯一串行点之后,再逐实体评估是否迁移更稳妥。
9. 事实出处(实现前请自己复核一遍)
| 结论 | 出处 |
|---|---|
Db.lock 私有、所有 Db::* 持锁 |
crates/sspf-store/src/db.rs 的 pub struct Db / query_json_inner / exec / exec_params |
Db::pg() 明确说「绕过 Db.lock」 |
同文件 Db::pg() 文档注释 |
DbTransaction 也持同一把锁 |
同文件 pub struct DbTransaction 的 _guard 字段与三条使用纪律 |
平台归一 normalize_json_keys |
同文件 normalize_json_keys / collect_alias_info / column_to_json_key |
| 业务仓不归一、mapper 才归一 | tdc-rs/src/platform/db.rs 的 query_json_params;tdc-rs/src/tdc/mapper.rs |
| 双锁已知局限 | CHANGELOG.md v0.3.0 末条、docs/known-limitations.md |
| 业务仓库操作单一出口 | tdc-rs/src/platform/db.rs 的 5 个 pub 函数;启动建表在 tdc-rs/src/tdc/schema.rs |
| P2 装配 / P3 会话桥 | tdc-rs/src/main.rs、tdc-rs/src/tdc/session_bridge.rs |
10. 实施记录(2026-11-04,tag v0.5.0)
| 需求 | 落地 | 位置 |
|---|---|---|
R1 Db::query_json_raw |
✅ 持锁 + 包裹 + 不归一;与 query_json_params 共用 query_json_inner_raw(SQL 包裹只有一份) |
crates/sspf-store/src/db.rs |
R2 Db::query_rows |
✅ 持锁返回 Vec<pglite::Row>;pglite::Row 经 sspf::pglite 可见 |
同上 |
| R3 写路径复用 | ✅ 文档口径写清(exec 多语句 / exec_params 单语句,两者都持锁);零新增代码 |
同上 |
R4 Db::lock_owned() |
✅ 返回 OwnedMutexGuard<()>,基于 Arc::clone(&self.lock).lock_owned();注释写明「持 guard 期间不许再调 Db::*」 |
同上 |
R5 Db::pg() 指路 |
✅ 注释补入口对照表(raw / 归一 / 原始行 / 写 / 持锁裸句柄) | 同上 |
| R6 门面导出 | ✅ 无需新增 re-export;crates/sspf/Cargo.toml 与 VERSION 断言同步为 0.5.0 |
crates/sspf/ |
| R7 闸门 + 探针 | ✅ AR20(raw 不归一 / 共用段 / 8 个公开入口全持同一把锁)+ 反自证 15/15;探针 db_raw_it.rs 4/4 |
scripts/check-arch.sh / crates/tests/tests/db_raw_it.rs |
验收对照(§4):A1 653 passed / 0 failed / 8 ignored(基线 649 + 新增 4 条)· A2 check-arch 25/25、自证 15/15 · A3 verify.sh --smoke 14/14 ·
A4 db_raw_it 4/4 · A5 cargo tree -p sspf 0 个 sspf-pack-* · A6 Finish::default() 路径未改 ·
A7 sspf::VERSION == "0.5.0" · A8 CHANGELOG 已加并销双锁条 · A9 已知限制 (bq) 已改 · A10 tag 已推 · A11 仓外探针见下。
A11 仓外探针:空 crate 只写 sspf = { git = "...", tag = "v0.5.0" },
cargo check 通过并调用 Db::query_json_raw / Db::lock_owned()(探针代码见
HANDOFF.md §0 的 v0.5.0 段)。
两条实现纪律(别再踩)
- 归一逻辑只准有一处(
query_json_inner),raw 侧共用query_json_inner_raw; 复制 SQL 包裹会让两条路慢慢漂,而漂的方向永远是「raw 也开始归一」。 lock_owned的 guard 期间再调Db::*必死锁(tokio Mutex 不可重入)—— 探针用timeout断言,不用 sleep 猜。
11. 业务侧切换记录(tdc-rs 提交 e13768e,2026-11-04)
| 项 | 落地 |
|---|---|
| 依赖 | Cargo.toml 的 sspf tag v0.3.0 → v0.5.0 |
| 注入 | src/platform/db.rs 新增进程级 OnceLock<Arc<sspf::Db>> + install_sspf_db();main.rs 在任何业务 DB 操作之前注入,失败即 exit(1) |
| R1 | query_json_params → Db::query_json_raw(不归一;归一仍由 mapper 做) |
| R2 | query_scalar_text / column_types → Db::query_rows |
| R3 | exec_params → Db::exec_params |
| 签名 | 6 个函数仍是 db: &PGlite ⇒ service/*、controller/*、mapper 零改动 |
| 豁免 | platform::db::ensure_schema 与 tdc/schema.rs::ensure_schema_coexist(启动期单线程建表) |
| 回落 | 未注入(单测 / 集成测试自建 AppState)走裸句柄旧路径,行为与 v0.4.0 一致 |
两条新判据(替代「文档承诺」)
tdc-rs/tests/sspf_db_lock.rs(真库 2 条):query_json_params出来的键仍是f_id/f_name(并显式断言get("id").is_none());平台lock_owned()持锁时业务exec_params在 300ms 内写不进去,解锁后立刻可写且只落 1 行。tdc-rs/scripts/check-dual-contract.sh第 18 条:真进程启动日志必须出现 「库操作出口已持平台锁」—— 该行只在install_sspf_db返回true时打印。
业务侧验收:cargo test 296 passed / 0 failed / 1 ignored;七把尺子全绿
(smoke 80/80、check-contract 132 条端点一致、双契约 18/18、check-db-access 0 处越界、
其余三把静态);check-citations.py 仍是既有的 32 条失效(全指向上游 Java/TS 文件),无新增。
🔴 切换踩到的唯一坑:不能图省事改调
Db::query_json*(非 raw) —— 会多一层f_* → camelCase归一 + 别名还原,业务侧mapper再做一次 ⇒ 键二次转换。 现由tests/sspf_db_lock.rs的裸键断言钉住,改错当场红。