docs(spec): 投影别名改双引号(PG 折叠未加引号的标识符)
Task 3 实现者实测发现:PostgreSQL 把未加引号的别名折叠成小写 ——
`SELECT row_to_json(q)::text FROM (SELECT 1 AS realName) q` ⇒ {"realname":1},
写 AS "realName" 才是 {"realName":1}。规格原先给的示例(§R1.4 / §5.2 / §5.3)
照抄会**静默**产出小写 JSON 键 ⇒ 前端读不到字段。
- §R1.4 / §4 / §5.2 / §5.3:规范写法改为 `f_xxx AS "<JSON键>"`(带双引号)。
- §5.4:登记 db.rs 的键归一为**安全网**(能兜住漏引号的写法),但规范写法不依赖它。
Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
1 parent
08c266537a
commit
0fef2fbfb7
1 file changed
+28
-8
+28
-8
@@ -37,9 +37,17 @@
|
||||
所有 SELECT **必须显式列出列名**。原因:react 版库(TypeORM `synchronize`)只有 entity 里的列,
|
||||
官方 DDL 有 30~60 列。显式投影让本仓后端**能开 react 建出来的库**,且响应 JSON 与 react 逐字相同。
|
||||
|
||||
🔴 **每列还要显式 `AS <JSON键>`**(camelCase,见 §4)——`row_to_json` 用**列的输出名**当 JSON 键。
|
||||
🔴 **每列还要显式 `AS "<JSON键>"`**(camelCase + **双引号**,见 §4)——`row_to_json` 用**列的输出名**当 JSON 键。
|
||||
写成 `AS creator_time` 会得到 `"creator_time"`,react 是 `"creatorTime"` ⇒ 前端读不到字段。
|
||||
|
||||
🔴🔴 **别名必须加双引号**(2026-10-25 修订,Ruling P23)——
|
||||
**PostgreSQL 会把未加双引号的标识符折叠成小写**:`AS realName` 的输出列名是 `realname`
|
||||
⇒ `row_to_json` 出来的键是 `"realname"`,**不是** `"realName"` ⇒ 前端读不到字段,**且静默**。
|
||||
实测:`SELECT row_to_json(q)::text FROM (SELECT 1 AS realName) q` ⇒ `{"realname":1}`;
|
||||
写成 `AS "realName"` 才是 `{"realName":1}`。
|
||||
⇒ **规范写法:`f_real_name AS "realName"`、`f_price::text AS "price"`。**
|
||||
(`db.rs` 另有一层键归一兜底,见 §5.4 —— 它是**安全网**,不是本规范;规范写法本身不依赖它。)
|
||||
|
||||
### R1.5 numeric 列必须序列化成 JSON 字符串
|
||||
`f_price` 回显 `"9.90"`,不是 `9.9`。手段:**在 SQL 投影里就 cast 成 text**(`f_price::text AS price`)。
|
||||
`int` 列(`f_delete_mark` / `f_stock` / `f_is_administrator`)**保持数字**。
|
||||
@@ -152,6 +160,9 @@ react 的 `decryptToMd5` 遇非法 hex / 非法填充返回**空串** ⇒ 与库
|
||||
|
||||
**规则**:列名去 `f_` 前缀 → 剩余部分按 `_` 拆 → camelCase。
|
||||
|
||||
🔴 **投影时别名一律写 `AS "<JSON键>"`(带双引号)** —— PG 会把未加引号的标识符折叠成小写
|
||||
(`AS realName` ⇒ 键 `"realname"` ⇒ 前端读不到,**且静默**)。详见 §R1.4。
|
||||
|
||||
| 列 | JSON 键 |
|
||||
|---|---|
|
||||
| `f_id` | `id` |
|
||||
@@ -249,9 +260,10 @@ react 的 `book.entity.ts` 上 `stock` 也有 `default: 0` ⇒ TypeORM 建的库
|
||||
to_char(f_creator_time, 'YYYY-MM-DD"T"HH24:MI:SS') || 'Z' AS creatorTime
|
||||
```
|
||||
|
||||
🔴 **投影的 `AS` 别名必须就是 §4 的 JSON 键(camelCase)** ——
|
||||
🔴 **投影的 `AS` 别名必须就是 §4 的 JSON 键(camelCase),且必须加双引号** ——
|
||||
`row_to_json` 用的是**列的输出名**当 JSON 键。别名写成 `AS creator_time` 会得到 `"creator_time"`,
|
||||
与 react 的 `"creatorTime"` **对不上** ⇒ 前端所有字段读不到。**每一列**都要显式 `AS <JSON键>`。
|
||||
与 react 的 `"creatorTime"` **对不上** ⇒ 前端所有字段读不到。
|
||||
**每一列**都要显式 `AS "<JSON键>"`(**带双引号** —— PG 折叠未加引号的标识符,见 §R1.4)。
|
||||
|
||||
### 5.3 精确列清单(**投影真源**)
|
||||
|
||||
@@ -261,11 +273,12 @@ to_char(f_creator_time, 'YYYY-MM-DD"T"HH24:MI:SS') || 'Z' AS creatorTime
|
||||
|
||||
格式:`列名 → JSON 键`。列顺序 = react entity 的声明顺序。
|
||||
|
||||
🔴 **投影写法**:每列都写成 `f_xxx AS <JSON键>`(**别名 = 右边的 JSON 键,camelCase**)。
|
||||
`row_to_json` 用的就是别名当 JSON 键 —— 别名写错 ⇒ 响应键名对不上 react。
|
||||
例:`f_real_name AS realName`、`f_is_administrator AS isAdministrator`、
|
||||
`f_creator_time` ⇒ `to_char(f_creator_time, 'YYYY-MM-DD"T"HH24:MI:SS') || 'Z' AS creatorTime`、
|
||||
`f_price` ⇒ `f_price::text AS price`(numeric 必须是字符串)。
|
||||
🔴 **投影写法**:每列都写成 `f_xxx AS "<JSON键>"`(**别名 = 右边的 JSON 键,camelCase,且带双引号**)。
|
||||
`row_to_json` 用的就是别名当 JSON 键 —— 别名写错 ⇒ 响应键名对不上 react;
|
||||
**双引号漏了 ⇒ PG 折叠成小写 ⇒ 键名对不上且静默**(见 §R1.4)。
|
||||
例:`f_real_name AS "realName"`、`f_is_administrator AS "isAdministrator"`、
|
||||
`f_creator_time` ⇒ `to_char(f_creator_time, 'YYYY-MM-DD"T"HH24:MI:SS') || 'Z' AS "creatorTime"`、
|
||||
`f_price` ⇒ `f_price::text AS "price"`(numeric 必须是字符串)。
|
||||
|
||||
**base_authorize**(9 列)
|
||||
```
|
||||
@@ -378,6 +391,13 @@ SELECT row_to_json(q)::text AS _row FROM (<sql>) AS q
|
||||
```
|
||||
⇒ 取单列文本 ⇒ `serde_json::from_str`。**不要另起逐列类型映射分支。**
|
||||
|
||||
🔴 **键归一安全网**(`db.rs` 内建,Ruling P23):`query_json` 返回前会把 JSON 键还原成 camelCase ——
|
||||
① 内层 SQL 里 `AS <别名>`(**含大写字母**)的别名 ⇒ 按作者原样还原(`AS realName` ⇒ `"realName"`);
|
||||
② 键以 `f_` 开头 ⇒ 走 `column_to_json_key`(`f_real_name` ⇒ `realName`,与 `tdc-rs` 同思路)。
|
||||
已加双引号的别名(`AS "realName"`)PG 原样保留 ⇒ 两条规则都不动它。
|
||||
⇒ **两种写法都能出正确键**;但**规范写法是加双引号**(原生 PG 行为,不依赖这层解析)。
|
||||
安全网存在的意义是:万一某处漏了双引号,**不会静默产出小写键**。
|
||||
|
||||
**绑定参数一律按 text 传**(`&str` / `Option<&str>` 都实现了 `ToSql`);
|
||||
类型转换由 SQL 里的 `CAST` / 列上下文负责(PG 从目标列推断参数类型)。
|
||||
|
||||
|
||||
Reference in new issue
Block a user