docs(req): 修正第三份需求的业务侧切换面(12 处写路径已收拢)
- 切换面从 5 个函数改为 6 个:新增 platform::db::exec_params
- 业务层原有 12 处裸 state.db.query 已全部收拢,护栏 check-db-access.sh 跑绿
- 同步 v0.4.0 tag 已重打到 ff34ca5 的事实,删掉过时的未提交改动说明
This commit is contained in:
1 parent
ff34ca50c1
commit
060e6eb755
1 file changed
+21
-15
@@ -71,25 +71,29 @@ mapper 已经做了一次转换。若业务侧直接改调 `Db::query_json_param
|
||||
> 🔴 **因此:禁止用「把业务 SQL 改调现有 `Db::query_json*`」来实现本题。**
|
||||
> 现有 `query_json*` 的归一行为一个字都不许改(面 A / 面 B 契约依赖它)。
|
||||
|
||||
### 2.4 业务仓的库操作已经收在一个文件里
|
||||
### 2.4 业务仓的库操作已经收在一个文件里(本轮先做了收拢)
|
||||
|
||||
`tdc-rs/src/platform/db.rs` 是唯一出口,5 个 `pub` 函数:
|
||||
🔴 **调研时发现的坑**:原先 `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` 即可 |
|
||||
|
||||
`src/tdc/schema.rs::ensure_schema_coexist` 是另一处直接用裸句柄的地方,
|
||||
但**只在启动时 `on_ready` 单线程跑**,不参与请求期并发 ⇒ 可以保持现状,
|
||||
文档 §5 会把它列为豁免。
|
||||
另有 2 处**豁免**(护栏白名单,不参与请求期并发):
|
||||
- `src/tdc/schema.rs::ensure_schema_coexist` —— 启动期 `on_ready` 单线程建表;
|
||||
- `src/main.rs` 的 `on_ready` —— 调的是 **`sspf::Db::exec`**(本身已持平台锁,不是裸句柄)。
|
||||
|
||||
⇒ 业务侧切换只需改 `platform/db.rs` 的 5 个函数 + 状态里注入 `Arc<Db>`;
|
||||
`mapper.rs` / `service/crud.rs` / `service/account.rs` / `service/identity.rs` /
|
||||
`controller/health.rs` / `controller/tds_biz.rs` **零改动**。
|
||||
⇒ 业务侧切换只需改 `platform/db.rs` 的 6 个函数 + 状态里注入 `Arc<Db>`;
|
||||
`mapper.rs` / `service/*` / `controller/*` **零改动**(它们已经全部走封装)。
|
||||
|
||||
---
|
||||
|
||||
@@ -245,9 +249,10 @@ impl Db {
|
||||
(或进程级 `OnceLock<Arc<Db>>`,与现有 `process_db_lock()` 同款),
|
||||
`AppState::new` 保持签名不变、默认 `None`,加一个 `with_sspf_db()` builder。
|
||||
4. `src/main.rs`:`boot.state.db.clone()` 注入(`boot.state.db` 是 `Arc<Db>`)。
|
||||
5. `src/platform/db.rs` 5 个函数内部改为持平台锁 / 调 Raw API,**函数签名保持
|
||||
5. `src/platform/db.rs` **6 个函数**内部改为持平台锁 / 调 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` 保持启动期裸句柄(**豁免**,见下)。
|
||||
@@ -257,8 +262,10 @@ impl Db {
|
||||
7. **豁免** `src/tdc/schema.rs::ensure_schema_coexist`:只在 `on_ready` 启动期、
|
||||
平台路由还没开始服务时单线程跑,不存在并发写;继续保持裸 `pg.exec`。
|
||||
若将来它移到请求期,必须一并改走 `Db::exec`。
|
||||
8. 新增静态护栏(本轮已先行落地):把「业务代码不得直接碰裸 `PGlite`」钉死,
|
||||
允许清单只有 `src/platform/db.rs`(封装本身)与 `src/tdc/schema.rs`(启动建表)。
|
||||
8. 静态护栏 `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 到位后)
|
||||
@@ -292,10 +299,9 @@ impl Db {
|
||||
3. 通知业务仓;业务仓按 §5 切换,跑完业务侧验收;
|
||||
4. 两仓各自写工作日志 / `CHANGELOG`,`docs/known-limitations.md` 销条。
|
||||
|
||||
> 🔴 `v0.4.0` 已是「零业务清理」版且已推远程,**不要挪动它**;
|
||||
> 平台仓工作区当前还有「门面版本 0.3.0 → 0.4.0」的两处未提交改动
|
||||
> (`crates/sspf/Cargo.toml` 与 `crates/sspf/src/lib.rs`),
|
||||
> 实现本需求时请先把它收干净,别和 v0.5.0 的版本号改动混在一起。
|
||||
> 🔴 `v0.4.0` 已是「零业务清理」版且已推远程(tag 现指向 `ff34ca5`,
|
||||
> 其后含「门面 cargo 版本对齐 0.4.0」与「本需求入库」两个提交),**不要挪动它**;
|
||||
> 实现本需求请直接在这条基线上开 `v0.5.0`,别改 `v0.4.0` 的 tag 或版本号。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in new issue
Block a user