feat(db): v0.5.0 业务库操作收进同一个 Db —— query_json_raw / query_rows / lock_owned

- Db::query_json_raw:持 Db.lock、row_to_json 包裹、不做 JSON 键归一(给自带归一语义的厚业务仓)
- Db::query_rows:持锁返回原始 pglite::Row(pg_catalog 元数据 / 取首行首列)
- Db::lock_owned():与所有 Db::* / DbTransaction 共用同一把锁,guard 内可用裸句柄跑自有 SQL
- query_json_inner 拆出共用段 query_json_inner_raw ⇒ SQL 包裹只有一份,query_json* 行为未改
- 闸门 AR20(raw 不归一 / 共用段 / 8 个公开入口全持锁)+ 反自证 14 → 15 项
- 探针 db_raw_it(4 条):raw 不归一 · 归一路径同时成立 · guard 期间 Db::exec 被阻塞 · query_rows 读 pg_catalog
- 销掉 known-limitations 的「双锁」条;CHANGELOG / README 版本表升 0.5.0
- 验收:653 passed / 0 failed;verify.sh --smoke 14/14;check-arch 25/25 自证 15/15
This commit is contained in:
admin committed 2026-11-04 22:54:35 +08:00
1 parent 18a6586c1d
commit e86746637c
11 files changed
+503 -33

No files matched your search

+10
View File
@@ -1,5 +1,15 @@
# CHANGELOG
## v0.5.0(2026-11-04,业务库操作收进同一个 `Db`)
- 新增 `Db::query_json_raw(sql, params)`:持 `Db.lock`、`row_to_json` 包裹、**不做 JSON 键归一**(`f_id` 原样返回),给自带归一语义的厚业务仓用。
- 新增 `Db::query_rows(sql, params)`:持锁返回原始 `pglite::Row`(`pg_catalog` 元数据 / 取首行首列),业务仓经 `sspf::pglite` 引用类型、不必自己声明依赖。
- 新增 `Db::lock_owned() -> OwnedMutexGuard<()>`:与所有 `Db::*` / `DbTransaction` 共用同一把锁;持 guard 期间可在裸句柄上跑自有 SQL。
- `query_json_inner` 拆成共用的 `query_json_inner_raw`(包裹 + 反序列化)+ 归一那一层 ⇒ SQL 包裹只有一份;`query_json*` 行为**一字未改**。
- 新增闸门 AR20(raw 不归一 / 共用包裹段 / 公开入口全持同一把锁)+ 反自证 15/15;新增探针 `db_raw_it.rs`(4 条:raw 键不归一、归一路径同时成立、guard 期间 `Db::exec` 被阻塞、`query_rows` 读 `pg_catalog`)。
- `Db::pg()` 文档补「要与平台共用串行域该走哪个入口」的指路表;销掉 v0.3.0 的「双锁」已知局限(`docs/known-limitations.md` 的 (bq))。
- 影响:面 A / 面 B 端点形状、码表、表结构零变化;`Platform` 的公开签名未改(`Finish::default()` 路径逐字等价)。`sspf` 版本 0.5.0。
## v0.4.0(2026-11-04,平台包零业务清理)
- 4 个示例业务包与 `modules/` 的 4 个面 A 适配器整体移出本仓;`packs/` 与 `sspf-pack-*` 依赖、 `example-packs` feature、门面 `example_packs()` 全部移除。
Generated
+1 -1
View File
@@ -1069,7 +1069,7 @@ dependencies = [
[[package]]
name = "sspf"
version = "0.4.0"
version = "0.5.0"
dependencies = [
"axum",
"libc",
+48
View File
@@ -9,6 +9,54 @@
---
## 0. 2026-11-04 深夜:`v0.5.0` —— 业务库操作收进同一个 `Db`(**最新**)
需求:`docs/SSPF-BUSINESS-DB-ACCESS.md`(第三份,`tdc-rs` 提)。要销的是 v0.3.0 留下的
那条已知局限:**`Db::pg()` 绕过 `Db.lock`** ⇒ 平台与业务各一把锁,跨平台的多语句事务不保证串行。
**做了什么**
1. **新增三个库入口**(`crates/sspf-store/src/db.rs`):
- `Db::query_json_raw(sql, params)` —— 持 `Db.lock`、`row_to_json` 包裹、**不做 JSON 键归一**
(`f_id` 原样回来),给自带归一语义的厚业务仓;
- `Db::query_rows(sql, params)` —— 持锁返回原始 `pglite::Row`(`pg_catalog` 元数据 / 取首行首列);
- `Db::lock_owned() -> OwnedMutexGuard<()>` —— 与所有 `Db::*` / `DbTransaction` 共用**同一把**锁,
持 guard 期间可在裸句柄上跑自有 SQL。
2. **拆共用段**:`query_json_inner` → `query_json_inner_raw`(包裹 + 反序列化)+ 归一那一层。
SQL 包裹逻辑只有一份 ⇒ 两条路不会漂。`query_json*` 的对外行为**一字未改**。
3. **文档指路**:`Db::pg()` 的注释补了一张「要与平台共用串行域该走哪个入口」的表,
并写明持 `lock_owned()` 期间**不许**再调 `Db::*`(tokio Mutex 不可重入)。
4. **闸门 AR20**(`scripts/check-arch.sh`):扫 `db.rs` 的函数体,钉住
① `query_json_raw` 里不出现 `normalize_json_keys`;② 它必须走共用的 `query_json_inner_raw`
且不调会归一的 `query_json_inner`;③ 共用段自身不归一;④ 8 个公开库入口都持 `self.lock`;
⑤ `lock_owned` 基于 `self.lock`(不是第二把锁)。反自证从 14 项加到 **15 项**。
5. **探针 `db_raw_it.rs`**(4 条):raw 键不归一 / 同一条 SQL 走 `query_json` 仍归一(两条路同时成立)/
持 `lock_owned()` 期间 `Db::exec` 被阻塞(用 `timeout` 断言「没完成」,不用 sleep 猜)/
`query_rows` 读 `pg_catalog` 原始行。
6. **销条**:`docs/known-limitations.md` 的 (bq)「双锁」改为「已由 v0.5.0 解决」;
`CHANGELOG.md` 加 v0.5.0 条目;`README.md` 版本表 + 依赖示例升到 `v0.5.0`。
**验收**
| 判据 | 结果 |
|---|---|
| `cargo test --workspace --no-fail-fast` | **653 passed / 0 failed / 8 ignored**(v0.4.0 基线 649 + 4 条 `db_raw_it`) |
| `verify.sh --smoke` | **14/14 步全绿**(122.7s) |
| `check-arch.sh` / `--self-test` | **25/25 / 0 跳过**,反自证 **15/15** |
| `cargo tree -p sspf` | 仍 **0 个 `sspf-pack-*`**(AR17 不回归) |
| 面 A / 面 B | 端点形状 / 码表 / 表结构零变化;`Platform` 公开签名未改 |
**踩过 / 别踩**
- 🔴 AR20 的函数体提取**必须允许不带 `pub`**:`query_json_inner_raw` 是私有共用段,
只认 `pub async fn` 会把它判成「不存在」⇒ 尺子自己先红(本轮踩过)。
- 🔴 自证注入点要落在**函数体内部**(`{` 之后插一行),落在文件末尾不构成「raw 路径归了」。
**下游**:`tdc-rs` 按需求 §5 切换(`tag → v0.5.0` + `platform/db.rs` 六个函数改走 `Db`),
业务侧验收清单在需求文档 §5 末尾。
---
## 0. 2026-11-04 晚:平台包零业务清理 → `v0.4.0`(第一批,**已推 `origin`:`main` + tag**)
需求:`@docs/SSPF-BUSINESS-COMPOSITION.md` 之后的追加要求 —— 「示例部分拿到外面去做,
+3 -2
View File
@@ -24,7 +24,7 @@
```toml
[dependencies]
sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.4.0" }
sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.5.0" }
```
```rust
@@ -109,7 +109,8 @@ cargo tree -p sspf | grep sspf-pack # 必须无输出(平台包零业务
|---|---|
| `v0.2.0` | 标准平台包 P0:门面 `sspf`、示例包选装、AR17/AR18 |
| `v0.3.0` | P1:`Db::pg()` 同句柄、`assemble()/Finish` 两阶段装配、AR19 |
| `v0.4.0` | 平台包零业务清理:示例包 / 面 A 适配器 / `example-packs` 全部退役,闸门改防回流(**已推 `origin`**) |
| `v0.4.0` | 平台包零业务清理:示例包 / 面 A 适配器 / `example-packs` 全部退役,闸门改防回流 |
| `v0.5.0` | 业务库操作收进同一个 `Db`:`query_json_raw`(持锁不归一)/ `query_rows` / `lock_owned()`,闸门 AR20(**已推 `origin`**) |
发布说明见 `CHANGELOG.md`,逐版实施记录见 `HANDOFF.md` 与 `docs/SSPF-*.md`。
已发布的 tag **一字不动**;破坏性变更走新 tag。
+105 -8
View File
@@ -27,7 +27,7 @@ use std::sync::OnceLock;
use pglite::{PGlite, ToSql};
use serde_json::Value;
use tokio::sync::Mutex;
use tokio::sync::{Mutex, OwnedMutexGuard};
/// 重新导出 pglite crate。
///
@@ -233,13 +233,47 @@ impl Db {
///
/// 🔴 返回的是 `Arc::clone`,不是 `PGlite::clone()`:`Arc` 的共享可用
/// `Arc::ptr_eq` 钉住,`PGlite` 自己的 `Clone` 语义不对外承诺。
/// 🔴 这个句柄**绕过本层的 `Db.lock`**:单次 SQL 有 pglite 的 `serial_guard`
/// 兜着,但「一次业务操作跨多条 SQL」的串行化要业务仓自己保证
/// (见 `docs/known-limitations.md` 的「双锁」条)。
/// 🔴 **这个句柄绕过本层的 `Db.lock`**:单次 SQL 有 pglite 的 `serial_guard`
/// 兜着,但「一次业务操作跨多条 SQL」的串行化**不由本层保证**。
///
/// ## 要与平台共用串行域 ⇒ 用这四个入口,别用裸句柄
///
/// | 想要什么 | 用什么 |
/// |---|---|
/// | SELECT,且**自己**做 `f_* → camelCase` 归一 | [`Db::query_json_raw`](持锁、**不归一**) |
/// | SELECT,想要平台风格的 JSON 键 | [`Db::query_json`] / [`Db::query_json_params`] |
/// | 要原始 `pglite::Row`(`pg_catalog` 元数据、取首行首列) | [`Db::query_rows`] |
/// | 写(INSERT / UPDATE / DELETE / DDL) | [`Db::exec`] / [`Db::exec_params`] |
/// | 要自己在裸句柄上跑一批 SQL,但**必须与平台互斥** | [`Db::lock_owned`](持 guard 期间用 `pg()`) |
///
/// 🔴 `pg()` 本句柄只适合**启动期单线程建表**与**只读元数据探测**;
/// 请求期用它会与平台侧各自开锁(见 `docs/known-limitations.md` 的「双锁」条,
/// v0.5.0 起已有正式的替代入口)。
pub fn pg(&self) -> Arc<PGlite> {
Arc::clone(&self.pg)
}
/// 取得**进程级业务锁**(与所有 `Db::*` / [`DbTransaction`] 共用同一把)。
///
/// 给「必须自己写 SQL、又要与平台互斥」的业务仓用:guard 存活期间,
/// 平台侧任何 `Db::*` 调用都会排队;`drop` 即释放。
///
/// ```ignore
/// let _g = db.lock_owned().await;
/// let rows = db.pg().query(&sql, &params).await?; // 裸句柄,但在锁内
/// ```
///
/// ## 🔴 两条纪律(违反必死锁 / 必错乱)
///
/// 1. **持 guard 期间不得再调任何 `Db::*` 方法**(`begin()` 也算)——
/// tokio 的 `Mutex` **不可重入** ⇒ 自己等自己。
/// 2. **不得把 guard 传出去跨请求持有** —— 那是全局串行点,持有越久吞吐越低。
///
/// 比 `pub fn lock(&self) -> &Mutex<()>` 安全:不暴露内部可变性,guard 有明确生命周期。
pub async fn lock_owned(&self) -> OwnedMutexGuard<()> {
Arc::clone(&self.lock).lock_owned().await
}
/// schema 初始化(**只在 `base_user` 不存在时**整体执行一次)。
///
/// - 探测用 `to_regclass('public.base_user')`(一次 round-trip,S5)。
@@ -316,6 +350,52 @@ impl Db {
self.query_json_inner(sql, params).await
}
/// 同 [`Db::query_json_params`],但**不做任何 JSON 键归一**(v0.5.0)。
///
/// 持 `Db.lock`、`row_to_json` 包裹、参数绑定、错误类型与
/// [`Db::query_json_params`] **逐字一致**;唯一差别是返回 PostgreSQL
/// **原样**的列名 / 别名折叠结果(`f_id` 还是 `f_id`,不会变 `id`)。
///
/// ## 🔴 给谁用
///
/// 自带归一语义的厚业务仓(例如 `tdc-rs`:它在上层用 `column_to_json_key`
/// 把 `f_*` 转 camelCase)。对它们来说,平台再归一一次就是**第二次转换**
/// ⇒ 键会漂移(尤其加引号别名)。
///
/// 无参形态直接传 `&[]`。
///
/// ```ignore
/// let rows = db.query_json_raw("SELECT f_id, f_real_name FROM base_user", &[]).await?;
/// // ⇒ [{"f_id": "...", "f_real_name": "..."}]
/// ```
pub async fn query_json_raw(
&self,
sql: &str,
params: &[&(dyn ToSql + Sync)],
) -> Result<Vec<Value>, pglite::Error> {
let _guard = self.lock.lock().await;
let (_alias_info, rows) = self.query_json_inner_raw(sql, params).await?;
Ok(rows)
}
/// 持 `Db.lock` 执行带参查询,返回**原始** `pglite::Row`(v0.5.0)。
///
/// 给元数据类查询用(`pg_catalog`、`to_regclass`、取首行首列)——
/// 那些场景不需要 `row_to_json`,也不需要 JSON 键归一。
///
/// `pglite::Row` 类型经 `sspf::pglite` 可见,业务仓不必自己声明 `pglite` 依赖。
///
/// 🔴 **列类型按 OID 自己判**:`row.get::<Option<String>>(0)` 对非 text 列
/// 是拿二进制字节做 `from_utf8`(不校验类型,静默判错)。
pub async fn query_rows(
&self,
sql: &str,
params: &[&(dyn ToSql + Sync)],
) -> Result<Vec<pglite::Row>, pglite::Error> {
let _guard = self.lock.lock().await;
self.pg.query(sql, params).await
}
/// 执行(无返回值)语句。
///
/// 🔴 走 **simple protocol** ⇒ **可以一次执行多条语句**,且整批是一个**隐式事务**
@@ -391,11 +471,16 @@ impl Db {
// ---- 以下为**持锁调用**的内部实现(调用方已持有 `self.lock`)----
async fn query_json_inner(
/// `row_to_json` 包裹 + 参数绑定 + 反序列化,**不归一**(v0.5.0 拆出来)。
///
/// 🔴 [`Db::query_json_raw`] 与 [`Db::query_json_inner`] **共用这一段**:
/// SQL 包裹逻辑只许有一份(复制必漂移)。
/// 返回值里的 [`AliasInfo`] 只有归一那一侧用得上,raw 侧丢弃。
async fn query_json_inner_raw(
&self,
sql: &str,
params: &[&(dyn ToSql + Sync)],
) -> Result<Vec<Value>, pglite::Error> {
) -> Result<(AliasInfo, Vec<Value>), pglite::Error> {
let inner = trim_sql(sql);
// 预先扫出**外层投影列表**的 `AS <别名>` ⇒ 查询后能把 PG 折叠掉的大写还原回去。
let alias_info = collect_alias_info(inner);
@@ -410,9 +495,21 @@ impl Db {
let value = serde_json::from_str::<Value>(&text).map_err(|e| {
pglite::Error::Protocol(format!("row_to_json 结果反序列化失败: {e}"))
})?;
out.push(normalize_json_keys(value, &alias_info));
out.push(value);
}
Ok(out)
Ok((alias_info, out))
}
async fn query_json_inner(
&self,
sql: &str,
params: &[&(dyn ToSql + Sync)],
) -> Result<Vec<Value>, pglite::Error> {
let (alias_info, rows) = self.query_json_inner_raw(sql, params).await?;
Ok(rows
.into_iter()
.map(|v| normalize_json_keys(v, &alias_info))
.collect())
}
/// 取第一行的第一列 ⇒ 文本。
+2 -2
View File
@@ -1,12 +1,12 @@
[package]
name = "sspf"
version = "0.4.0"
version = "0.5.0"
edition = "2021"
rust-version = "1.85"
description = "SSPF 标准平台包 —— 业务仓唯一依赖的门面(平台能力 + 装配注入)"
# 🔴 **为什么显式写 version,不用 `version.workspace = true`**:
# 业务仓(tdc-rs)锁的是**这个 crate 的语义版本**(`sspf = "0.4"` / tag `v0.4.0`),
# 业务仓(tdc-rs)锁的是**这个 crate 的语义版本**(`sspf = "0.5"` / tag `v0.5.0`),
# 而本仓 workspace 版本(0.1.0)跟的是内核实现节奏。两者独立演进 —— 混用会让
# 「业务仓能不能升级」变成「内核发了几个 commit」。
#
+2 -2
View File
@@ -41,7 +41,7 @@
//!
//! | 版本 | 值 | 谁看 |
//! |---|---|---|
//! | 本 crate(cargo) | `0.4.0` | 业务仓锁依赖 / git tag |
//! | 本 crate(cargo) | `0.5.0` | 业务仓锁依赖 / git tag |
//! | 契约版本 | `0.4.0` | 业务包 `pack.toml` 的 `kernel_req` |
//! | workspace(cargo) | `0.1.0` | 内核实现节奏 |
//!
@@ -109,7 +109,7 @@ mod tests {
/// **改版本时这里必须同步改**,否则测试当场红 —— 这是有意的护栏。
#[test]
fn version_matches_the_manifest() {
assert_eq!(super::VERSION, "0.4.0");
assert_eq!(super::VERSION, "0.5.0");
}
/// 🔴 **平台包恒零业务**(2026-11-04 清理)—— 与 AR17 的静态判据互补:
+142
View File
@@ -0,0 +1,142 @@
//! db_raw —— v0.5.0 新入口的集成探针(`query_json_raw` / `query_rows` / `lock_owned`)。
//!
//! ## 这四条断言在钉什么
//!
//! 1. **raw 不归一**:`f_id` / `f_real_name` 原样返回(厚业务仓自己转 camelCase);
//! 2. **归一那侧没被改坏**:同一条 SQL 走 `query_json` 仍是 `id` / `realName`
//! —— 两条路径**同时**成立,说明 R1 只是「多开一条不归一的出口」,
//! 不是「把归一逻辑挪走」;
//! 3. **同一把锁**:持 `lock_owned()` 期间 `Db::exec` 必须**排队**(用 `timeout`
//! 断言「没完成」,而不是 `sleep` 后猜「应该没完成」);
//! 4. **`query_rows` 能读 `pg_catalog` 原始行**(元数据查询不需要 `row_to_json`)。
//!
//! 🔴 断言 3 是本题的**核心**:这两把锁如果不统一,业务仓与平台并发写同一个
//! PGlite 后端时会交错 —— 而这在任何单线程测试里都看不出来。
use std::time::Duration;
use sspf_core::db::Db;
use tokio::sync::OnceCell;
/// 全文件共享的临时库(pglite 进程级单实例,见 `db_it.rs` 的说明)。
static DB: OnceCell<Db> = OnceCell::const_new();
async fn db() -> &'static Db {
DB.get_or_init(|| async { Db::open_temp().await.expect("打开 pglite 临时库失败") })
.await
}
/// 一条**不需要建表**的投影:直接把字面量起成 `f_*` 列名。
///
/// 🔴 刻意不用 `base_user`:`query_json` 的键归一与「表里有没有数据」无关,
/// 用字面量投影才能让这条断言**不依赖种子 / DDL**(失败时原因唯一)。
const SQL_LITERAL_ROW: &str = "SELECT 'u-1'::text AS f_id, '张三'::text AS f_real_name";
#[tokio::test]
async fn raw_does_not_normalize_keys() {
let db = db().await;
let rows = db
.query_json_raw(SQL_LITERAL_ROW, &[])
.await
.expect("query_json_raw 失败");
assert_eq!(rows.len(), 1, "字面量投影必须恰好一行");
let obj = rows[0].as_object().expect("行必须是 JSON 对象");
assert_eq!(
obj.get("f_id").and_then(|v| v.as_str()),
Some("u-1"),
"raw 路径必须保留 f_id 原样(归一了就说明走错入口)"
);
assert_eq!(
obj.get("f_real_name").and_then(|v| v.as_str()),
Some("张三"),
"raw 路径必须保留 f_real_name 原样"
);
assert!(
obj.get("id").is_none() && obj.get("realName").is_none(),
"raw 路径**不许**出现归一后的键:{obj:?}"
);
}
#[tokio::test]
async fn normalize_path_still_works_on_the_same_sql() {
let db = db().await;
// 🔴 同一条 SQL,两个入口 ⇒ 两种键集合,同时成立。
// 这条断言防的是「为了做 raw 把 normalize_json_keys 挪走 / 改掉」。
let rows = db
.query_json(SQL_LITERAL_ROW)
.await
.expect("query_json 失败");
assert_eq!(rows.len(), 1, "字面量投影必须恰好一行");
let obj = rows[0].as_object().expect("行必须是 JSON 对象");
assert_eq!(
obj.get("id").and_then(|v| v.as_str()),
Some("u-1"),
"query_json 必须把 f_id 归一成 id"
);
assert_eq!(
obj.get("realName").and_then(|v| v.as_str()),
Some("张三"),
"query_json 必须把 f_real_name 归一成 realName"
);
assert!(
obj.get("f_id").is_none() && obj.get("f_real_name").is_none(),
"query_json 不许残留 f_* 键:{obj:?}"
);
}
#[tokio::test]
async fn lock_owned_blocks_db_calls_until_dropped() {
let db = db().await;
let guard = db.lock_owned().await;
// 持 guard 期间另起一个 `Db::exec`:它必须**卡在锁上**。
let db2 = db.clone();
let mut task = tokio::spawn(async move { db2.exec("SELECT 1").await });
let early = tokio::time::timeout(Duration::from_millis(200), &mut task).await;
assert!(
early.is_err(),
"持 lock_owned() 期间 Db::exec 不该完成 —— 两把锁没统一?"
);
// 放锁之后必须很快完成(5s 上限只是防挂死)。
drop(guard);
let done = tokio::time::timeout(Duration::from_secs(5), task)
.await
.expect("释放 guard 后 Db::exec 仍没完成 —— 锁没被释放?");
done.expect("Db::exec 任务 panic").expect("Db::exec 失败");
}
#[tokio::test]
async fn query_rows_reads_pg_catalog() {
let db = db().await;
// 先建一张**探针表**(不依赖平台 schema,失败原因唯一)。
// 顺带证明写路径走的 `Db::exec`(持锁)与读路径共用同一个库。
db.exec("CREATE TABLE IF NOT EXISTS raw_probe_tbl (f_id text)")
.await
.expect("建探针表失败");
// 原始行:不包 `row_to_json`,直接拿 `pglite::Row`。
let rows = db
.query_rows(
"SELECT tablename FROM pg_catalog.pg_tables \
WHERE schemaname = 'public' AND tablename = 'raw_probe_tbl'",
&[],
)
.await
.expect("query_rows 失败");
assert_eq!(rows.len(), 1, "pg_catalog 里必须能查到刚建的表");
// 第一列是 name 类型 ⇒ 按 String 取(pglite 的 Row::get 会做类型转换)。
let name: String = rows[0].get::<String>(0).expect("取 tablename 失败");
assert_eq!(name, "raw_probe_tbl", "取出来的列值不对");
}
+31 -1
View File
@@ -2,7 +2,8 @@
> 目标 tag:**`v0.5.0`**(`v0.4.0` 已用于「平台包零业务清理」,不能复用)
> 提出方:`tdc-rs`(厚业务仓,自带状态类型 / 自带 JSON 归一语义)
> 状态:**待平台侧实现**。业务仓本轮只做切换面收拢,不改 `Cargo.toml` 的 tag。
> 状态:**已实施并发布 → annotated tag `v0.5.0` 已推 `origin`**(实施记录见 §10)。
> 业务仓本轮只做切换面收拢,不改 `Cargo.toml` 的 tag;切换单见 §5。
> 前两份需求:`SSPF-PLATFORM-PACKAGE.md`(v0.2.0)、`SSPF-BUSINESS-COMPOSITION.md`(v0.3.0)。
---
@@ -327,3 +328,32 @@ impl Db {
| 双锁已知局限 | `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 段)。
**两条实现纪律(别再踩)**
1. 归一逻辑**只准有一处**(`query_json_inner`),raw 侧共用 `query_json_inner_raw`;
复制 SQL 包裹会让两条路慢慢漂,而漂的方向永远是「raw 也开始归一」。
2. `lock_owned` 的 guard 期间**再调 `Db::*` 必死锁**(tokio Mutex 不可重入)——
探针用 `timeout` 断言,不用 sleep 猜。
+2 -2
View File
@@ -167,12 +167,12 @@
## L. 单进程双 DB 锁与 413 改写(v0.3.0,2026-11-04)
## L. 单进程双 DB 锁(**v0.5.0 已销**)与 413 改写(v0.3.0,2026-11-04)
> 需求与决策见 `docs/SSPF-BUSINESS-COMPOSITION.md` §10.3 / §10.4 / §11.1。
> 这两条都是「平台包承载自带状态的厚业务仓」时**主动接受**的边界,不是缺陷回归。
| # | 限制 | 为什么接受 / 代价 |
|---|---|---|
| (bq) | **平台与业务各有一把 DB 锁**:业务仓经 `Db::pg()` 拿 `Arc<PGlite>` 后绕过 `sspf_store::Db::lock`,自己的 `process_db_lock()` 与平台那把互不覆盖 ⇒ 并发下「一次业务操作跨多条 SQL」可能与平台 SQL 交错 | 单次 SQL 有 pglite 的 `serial_guard()` 串行化,不会破坏单条查询;本轮只求「同一个库、同一个端口」,统一到 `Db::begin()` 或暴露共享锁出口属 P3。代价:跨平台 / 业务的**多语句事务**不保证整体串行,业务仓需自行持锁;暂不暴露 `Db::lock()` 也避免了「业务持锁误调 `db.*` 死锁」 |
| (bq) | ~~**平台与业务各有一把 DB 锁**~~ —— **已由 v0.5.0 解决**:`Db::query_json_raw` / `Db::query_rows` / `Db::lock_owned()` 三个入口都持**同一把** `Db.lock`,业务仓把库操作收进 `Db` 后不再需要自造锁 | v0.3.0 时只暴露了 `Db::pg()`(裸句柄),业务仓只能自己开一把锁 ⇒ 跨平台的多语句事务不保证串行。v0.5.0 补齐入口后,纪律变成「业务 SQL 要么走 `Db::*`,要么在 `lock_owned()` 的 guard 内用裸句柄」;沿用旧的 `pg()` 仍**不**持锁(那是有意的:启动期建表要能跑)。判据 `check-arch.sh` 的 AR20 + 探针 `db_raw_it.rs` 钉住「raw 不归一 / 同一把锁」 |
| (br) | **业务侧的 413 / 非空体 405 会被平台改写成信封**:`m_status_rewrite()` 挂在总 Router 上,对任何 405 / 413 无条件改写;tdc 原来的 413 是 axum 默认 `text/plain` | 保持 S25「fallback 在两个平台 layer 之前、catch-all 覆盖面 B 与业务路由」这条硬约束,不给 `Extras` 加「跳过平台层」开关。405 两边形状逐字相同(`code/msg/data`),改写幂等;**413 与带 body 的 405 形状会变**。代价:业务契约里若钉死 413 的裸响应,需在业务 Router 自己的 `route_layer` 上抢先处理 |
+157 -15
View File
@@ -66,6 +66,7 @@
# 404 兜底会静默错位且测试全绿(S25)。
# 🔴 AR17/AR18 是「sspf 标准平台包」(2026-11-04 P0)的边界:平台包里零业务。
# 🔴 AR19 是「业务自带状态的可组合装配」(2026-11-04 P1)的边界:装配链仍然只有一份。
# 🔴 AR20 是「业务仓库操作共用同一把锁」(2026-11-04 v0.5.0)的边界:raw 入口不归一、不造第二把锁。
set -u
@@ -101,7 +102,7 @@ skip() { SKIP=$((SKIP + 1)); printf '⏭ %s\n' "$1"; }
usage() {
echo "用法: bash scripts/check-arch.sh [--self-test]"
echo " 静态检查 crate 依赖纪律(AR1–AR19)与内存红线(MEM1–MEM2)"
echo " 静态检查 crate 依赖纪律(AR1–AR20)与内存红线(MEM1–MEM2)"
echo "退出码: 0 全过 / 1 有 ❌ / 2 用法错"
}
@@ -935,12 +936,116 @@ PY
fi
}
# ---------------------------------------------------------------- AR20
# **库入口的锁与归一纪律**(2026-11-04 v0.5.0:`query_json_raw` / `query_rows` / `lock_owned`)。
#
# 🔴 **为什么需要**:新增的 raw 入口是为了让厚业务仓(`tdc-rs`)把库操作收进
# **同一把 `Db.lock`**。它一旦被「顺手加上归一」或「自己造第二把锁」,
# 后果都不是报错,而是**静默变形状 / 静默并发交错**:
# - raw 路径混进 `normalize_json_keys` ⇒ 业务仓 132 条端点的 JSON 键漂移;
# - 新入口不持 `self.lock` ⇒ 平台与业务各开一把锁,并发写同一个 PGlite 交错。
#
# 判据(扫 `crates/sspf-store/src/db.rs` 的函数体):
# 1. `query_json_raw` 里**不许**出现 `normalize_json_keys`;
# 2. `query_json_raw` **必须**走共用的 `query_json_inner_raw`(不许复制一份 SQL 包裹),
# 且**不许**调会归一的 `query_json_inner`;
# 3. 共用段 `query_json_inner_raw` 自身也不许归一(否则两条路都归一了);
# 4. 所有公开库入口都持 `self.lock`;`lock_owned` 必须基于 `self.lock`(不是第二把锁)。
check_ar20() {
local file="$ROOT/crates/sspf-store/src/db.rs"
[ -f "$file" ] || { skip "AR20 db.rs 不存在"; return; }
local hits
hits="$(python3 - "$file" <<'PY'
import re
import sys
src = open(sys.argv[1], encoding="utf-8").read()
def body(name):
"""取 `<[pub] async fn> <name>` 的函数体(花括号配平)。
🔴 **允许不带 `pub`**:`query_json_inner_raw` 是私有的共用段,
只认 `pub async fn` 会把它判成「不存在」⇒ 尺子自己先红。
"""
m = re.search(r"(?:\bpub )?\basync fn " + name + r"\b", src)
if not m:
return None
i = src.find("{", m.end())
if i < 0:
return None
depth, j = 0, i
while j < len(src):
c = src[j]
if c == "{":
depth += 1
elif c == "}":
depth -= 1
if depth == 0:
return src[i : j + 1]
j += 1
return None
bad = []
raw = body("query_json_raw")
if raw is None:
bad.append("raw-missing: 找不到 async fn query_json_raw")
else:
if "normalize_json_keys" in raw:
bad.append("raw-normalizes: query_json_raw 里出现 normalize_json_keys(raw 必须不归一)")
if "query_json_inner_raw" not in raw:
bad.append("raw-not-shared: query_json_raw 没走共用的 query_json_inner_raw(SQL 包裹会漂成两份)")
if re.search(r"query_json_inner\s*\(", raw):
bad.append("raw-goes-through-normalizing-path: query_json_raw 调了 query_json_inner(那条会归一)")
shared = body("query_json_inner_raw")
if shared is None:
bad.append("shared-missing: 找不到 query_json_inner_raw(raw 与归一必须共用同一段)")
elif "normalize_json_keys" in shared:
bad.append("shared-normalizes: query_json_inner_raw 里出现 normalize_json_keys")
for fn in (
"query_json",
"query_json_params",
"query_json_raw",
"query_rows",
"exec",
"exec_params",
"scalar_text",
"begin",
):
b = body(fn)
if b is None:
bad.append(f"lock-fn-missing: 找不到 {fn}")
elif "self.lock" not in b:
bad.append(f"lock-missing: {fn} 没有持 self.lock(并发会绕过平台串行域)")
lo = body("lock_owned")
if lo is None:
bad.append("lock-owned-missing: 找不到 async fn lock_owned")
elif "self.lock" not in lo:
bad.append("lock-owned-different: lock_owned 没基于 self.lock(等于造了第二把锁)")
for b in bad:
print(b)
PY
)"
if [ -z "$hits" ]; then
ok "AR20 库入口纪律(raw 不归一 / 共用包裹段 / 全部持同一把 lock)"
else
bad "AR20 库入口纪律被破坏(归一漂移或第二把锁):"
printf '%s\n' "$hits" | sed 's/^/ /'
fi
}
# ---------------------------------------------------------------- 反自证
# 🔴 永远返回「干净」的尺子 = 没有尺子。造明知违规的输入,必须被抓到。
self_test() {
local rc=0
echo "── 反自证 1/14:造一个依赖越界的假 pack,AR2 必须报 ❌ ──"
echo "── 反自证 1/15:造一个依赖越界的假 pack,AR2 必须报 ❌ ──"
local tmp="$ROOT/packs/__arch_selftest__"
mkdir -p "$tmp"
cat > "$tmp/Cargo.toml" <<'TOML'
@@ -970,7 +1075,7 @@ TOML
rc=1
fi
echo "── 反自证 2/14:往平台层塞一个 use sspf_pack_*,AR9 必须报 ❌ ──"
echo "── 反自证 2/15:往平台层塞一个 use sspf_pack_*,AR9 必须报 ❌ ──"
#
# 🔴 **为什么必须自证 AR9**:它的判据是 `grep 目录`。
# 目录名写错 / 路径拼错 ⇒ `grep` 永远返回空 ⇒ **永远"通过"**。
@@ -1009,7 +1114,7 @@ TOML
rc=1
fi
echo "── 反自证 3/14:往 re-export 的模块里塞一份 spec,PACK1 必须报 ❌ ──"
echo "── 反自证 3/15:往 re-export 的模块里塞一份 spec,PACK1 必须报 ❌ ──"
#
# 🔴 造在**临时模块文件**上(不动真文件):只要它同时有 `pub use sspf_pack_`
# 和 `= EntitySpec {`,PACK1 就必须红。
@@ -1035,7 +1140,7 @@ RS
echo "⏭ 跳过 PACK1 反自证(业务模块目录不存在)"
fi
echo "── 反自证 4/14:往 sspf-plugin 塞 axum 依赖,AR8 必须报 ❌ ──"
echo "── 反自证 4/15:往 sspf-plugin 塞 axum 依赖,AR8 必须报 ❌ ──"
local pfile="$CRATES/sspf-plugin/Cargo.toml"
if [ -f "$pfile" ]; then
cp "$pfile" "$pfile.bak"
@@ -1056,7 +1161,7 @@ RS
echo "⏭ 跳过 AR8 反自证(sspf-plugin 不存在)"
fi
echo "── 反自证 5/14:往平台层塞 crate::platform::compat,AR10 必须报 ❌ ──"
echo "── 反自证 5/15:往平台层塞 crate::platform::compat,AR10 必须报 ❌ ──"
#
# 🔴 **必须自证 AR10**:它的判据是「扫平台层目录找契约面引用」。
# 目录名写错 / 路径拼错 ⇒ 扫描永远返回空 ⇒ **永远"通过"** ⇒ 虚假安全感。
@@ -1092,7 +1197,7 @@ RS
rc=1
fi
echo "── 反自证 6/14:往契约面底座塞 use super::system,AR11 必须报 ❌ ──"
echo "── 反自证 6/15:往契约面底座塞 use super::system,AR11 必须报 ❌ ──"
#
# 🔴🔴 **M7 起底座只有一处**:真源 `crates/sspf-compat-core/src/helper.rs`
# (转发壳 `src/backend/src/platform/compat/helper.rs` 已随 M7 删除)。
@@ -1115,7 +1220,7 @@ RS
rc=1
fi
echo "── 反自证 7/14:往壳里写 crate::platform::,AR15 必须报 ❌ ──"
echo "── 反自证 7/15:往壳里写 crate::platform::,AR15 必须报 ❌ ──"
#
# 🔴 **必须自证 AR15**:删掉 `platform/` 转发壳之后,旧路径就**没有编译器**兜底了
# —— 只要有人重建壳目录并把 import 改回去,**一切照常编译、测试照常全绿**,
@@ -1157,7 +1262,7 @@ RS
rc=1
fi
echo "── 反自证 8/14:给域包塞一条未授权的跨包依赖,AR12 必须报 ❌ ──"
echo "── 反自证 8/15:给域包塞一条未授权的跨包依赖,AR12 必须报 ❌ ──"
#
# 🔴 **为什么必须自证 AR12**:它的判据是「读 Cargo.toml 找 sspf-compat-* 依赖」。
# 若 grep 模式写错(包名含连字符/下划线混用)⇒ 永远扫不到依赖 ⇒
@@ -1184,7 +1289,7 @@ RS
rc=1
fi
echo "── 反自证 9/14:给执行层塞一个越界依赖 + 一条业务包引用,AR13 必须报 ❌ ──"
echo "── 反自证 9/15:给执行层塞一个越界依赖 + 一条业务包引用,AR13 必须报 ❌ ──"
#
# 🔴 **必须自证 AR13**:它的判据是「读 Cargo.toml + grep 源码」。
# 两种失效模式都得堵:
@@ -1217,7 +1322,7 @@ RS
rc=1
fi
echo "── 反自证 10/14:给适配层塞一个越界依赖 + 一条业务包引用,AR14 必须报 ❌ ──"
echo "── 反自证 10/15:给适配层塞一个越界依赖 + 一条业务包引用,AR14 必须报 ❌ ──"
#
# 🔴 **必须自证 AR14**:它是 M6 新增的判据,守护的是「全仓唯一知道全部包的
# 汇聚点」的依赖面。两种失效模式都得堵:
@@ -1250,7 +1355,7 @@ RS
rc=1
fi
echo "── 反自证 11/14:内核加回 [[bin]] + 塞回 tests/*.rs,AR16 必须两处都报 ❌ ──"
echo "── 反自证 11/15:内核加回 [[bin]] + 塞回 tests/*.rs,AR16 必须两处都报 ❌ ──"
#
# 🔴 **必须自证 AR16**:它的三条判据全是「文件/目录在不在」——
# 路径写错(比如把 $KERNEL 拼成别的名字)⇒ 永远判「没问题」⇒
@@ -1284,7 +1389,7 @@ RS
rc=1
fi
echo "── 反自证 12/14:往内核塞回一条 sspf-pack 依赖,AR17 必须报 ❌ ──"
echo "── 反自证 12/15:往内核塞回一条 sspf-pack 依赖,AR17 必须报 ❌ ──"
#
# 🔴 **2026-11-04 清理**:依赖清单里已经没有 pack 行可改 ⇒ 旧探针(去掉
# `optional = true`)找不到锚点,自证会**假红**。改成「注入一整条硬依赖」,
@@ -1309,7 +1414,7 @@ RS
rc=1
fi
echo "── 反自证 13/14:往门面里塞一句业务字面量,AR18 必须报 ❌ ──"
echo "── 反自证 13/15:往门面里塞一句业务字面量,AR18 必须报 ❌ ──"
#
# 🔴 **为什么自证 AR18**:它扫的是「门面源码里的业务名」。目录写错 / 正则写错
# ⇒ 永远空 ⇒ 永远"通过"。这条自证保证「平台包里零业务」不是一句口号。
@@ -1332,7 +1437,7 @@ RS
rc=1
fi
echo "── 反自证 14/14:往 routes.rs 塞第二处 .layer(catch_all()),AR19 必须报 ❌ ──"
echo "── 反自证 14/15:往 routes.rs 塞第二处 .layer(catch_all()),AR19 必须报 ❌ ──"
#
# 🔴 **为什么自证 AR19**:它数的是「非注释代码里 catch_all 层的条数」。
# 正则写错 / 扫描面写错 ⇒ 永远数到 1 ⇒ 永远"通过"。
@@ -1356,6 +1461,42 @@ RS
rc=1
fi
echo "── 反自证 15/15:往 query_json_raw 里塞 normalize_json_keys,AR20 必须报 ❌ ──"
#
# 🔴 **为什么自证 AR20**:它读的是「函数体里有没有某个标识符」。
# 正则写错 / 取错函数体 ⇒ 永远判干净 ⇒ raw 某天被顺手加上归一,
# 业务仓 132 条端点的键就静默漂移,而且**测试可能全绿**(只要没人比键名)。
local a20file="$ROOT/crates/sspf-store/src/db.rs"
local a20ok=0
if [ -f "$a20file" ]; then
cp "$a20file" "$a20file.ar20bak"
python3 - "$a20file" <<'PY'
import re
import sys
path = sys.argv[1]
src = open(path, encoding="utf-8").read()
m = re.search(r"pub async fn query_json_raw\b", src)
i = src.find("{", m.end())
# 在函数体开头注入一行「归一」—— 这正是本题最怕的退化。
src = src[: i + 1] + "\n let _ar20_probe = normalize_json_keys;" + src[i + 1 :]
open(path, "w", encoding="utf-8").write(src)
PY
local a20before=$FAIL
check_ar20 >/dev/null 2>&1
local a20caught=0
[ "$FAIL" -gt "$a20before" ] && a20caught=1
mv "$a20file.ar20bak" "$a20file"
FAIL=$a20before
[ "$a20caught" -eq 1 ] && a20ok=1
fi
if [ "$a20ok" -eq 1 ]; then
echo "✅ 反自证通过:AR20 抓到了 raw 路径里的归一"
else
echo "❌ 反自证失败:AR20 没抓到 raw 路径里的 normalize_json_keys ⇒ 尺子是假的"
rc=1
fi
return $rc
}
@@ -1382,6 +1523,7 @@ check_ar16
check_ar17
check_ar18
check_ar19
check_ar20
check_pack1
check_mem1
check_mem2