From 0fef2fbfb744ffb825e06a707f6d78219522b618 Mon Sep 17 00:00:00 2001 From: admin Date: Sun, 25 Oct 2026 18:07:45 +0800 Subject: [PATCH] =?UTF-8?q?docs(spec):=20=E6=8A=95=E5=BD=B1=E5=88=AB?= =?UTF-8?q?=E5=90=8D=E6=94=B9=E5=8F=8C=E5=BC=95=E5=8F=B7=EF=BC=88PG=20?= =?UTF-8?q?=E6=8A=98=E5=8F=A0=E6=9C=AA=E5=8A=A0=E5=BC=95=E5=8F=B7=E7=9A=84?= =?UTF-8?q?=E6=A0=87=E8=AF=86=E7=AC=A6=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 ""`(带双引号)。 - §5.4:登记 db.rs 的键归一为**安全网**(能兜住漏引号的写法),但规范写法不依赖它。 Co-Authored-By: Claude Code --- docs/contract.md | 36 ++++++++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/docs/contract.md b/docs/contract.md index c0548fa..0841e35 100644 --- a/docs/contract.md +++ b/docs/contract.md @@ -37,9 +37,17 @@ 所有 SELECT **必须显式列出列名**。原因:react 版库(TypeORM `synchronize`)只有 entity 里的列, 官方 DDL 有 30~60 列。显式投影让本仓后端**能开 react 建出来的库**,且响应 JSON 与 react 逐字相同。 -🔴 **每列还要显式 `AS `**(camelCase,见 §4)——`row_to_json` 用**列的输出名**当 JSON 键。 +🔴 **每列还要显式 `AS ""`**(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 ""`(带双引号)** —— 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 `。 +与 react 的 `"creatorTime"` **对不上** ⇒ 前端所有字段读不到。 +**每一列**都要显式 `AS ""`(**带双引号** —— 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 键,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 键,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 () 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 从目标列推断参数类型)。