feat: config + pglite db 封装 + 10 张表 schema 初始化

- config.rs: Config{port,pg_dir,project_dir,static_dir} + from_env(PORT 默认 30010、
  PGLITE_DIR 默认 <project>/src/backend/data/lite.pg、memory:// ⇒ 临时库、static_dir 缺失 ⇒ None)
- db.rs: Db{pglite + 进程级 tokio::Mutex};exec_params 在 query 之上实现;
  query_json 自包 row_to_json;ensure_schema 用 to_regclass 探测(只在 base_user 缺失时建库);
  split_sql_statements 字面量感知(单引号/E''/双引号/dollar-quote/行注释/可嵌套块注释)
- db.rs: JSON 键归一 —— PG 会把未加引号的别名折叠成小写(AS realName ⇒ realname),
  故按内层 SQL 的 AS 别名还原大小写,并支持 f_* 列名直投影(两种写法都出 camelCase)
- schema.sql: 只追加 3 张业务表 DDL(demo_item/shop_product/book_shop_book),
  列宽与默认值逐字对齐 react TypeORM entity;7 张 base_* 一字未动
- tests/db_it.rs: 共享一个临时库(pglite 进程级单实例),覆盖 10 表存在/幂等/
  numeric⇒字符串/int⇒数字/id 36 字符/DB 默认值/camelCase 键

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
This commit is contained in:
adminandClaude Sonnet 5.5 committed 2026-10-25 18:04:15 +08:00
1 parent d73b1617b2
commit ed449eb773
4 files changed
+1144 -3

No files matched your search

+45
View File
@@ -205,3 +205,48 @@ CREATE INDEX IF NOT EXISTS i_ba_foi ON base_authorize(f_object_id);
CREATE INDEX IF NOT EXISTS i_brr_fri ON base_role_relation(f_role_id);
CREATE INDEX IF NOT EXISTS i_bu_fa ON base_user(f_account);
CREATE INDEX IF NOT EXISTS i_bur_fui ON base_user_relation(f_user_id);
-- ============================================================================
-- 业务表 3 张(demo_item / shop_product / book_shop_book)
--
-- 🔴 逐字对齐 react 版 TypeORM entity(demo-item.entity.ts / product.entity.ts /
-- book.entity.ts)—— 这是「两版后端可开同一个库」成立的**前提**:
-- 两边必须是**同一张表**,否则 react 的 synchronize 会 ALTER 掉我们建的列。
-- 真源:docs/contract.md §5.1。
--
-- 🔴 有 DB 默认值的**只有两处**:f_delete_mark(三张表都有)与 book_shop_book.f_stock
-- (react 的 book.entity.ts 上 stock 也有 default: 0 ⇒ TypeORM 建的库同样带这个默认值)。
-- §7.6 路径 2(带 id 但行不存在 ⇒ 用该 id 新建)依赖它们补出 0;
-- 其余业务列一律不得有默认值(该路径要求「body 没给 ⇒ NULL」)。
-- ============================================================================
CREATE TABLE demo_item (
f_id VARCHAR(50) PRIMARY KEY,
f_title VARCHAR(255),
f_status VARCHAR(32),
f_creator_user_id VARCHAR(50),
f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_delete_mark INTEGER DEFAULT 0
);
CREATE TABLE shop_product (
f_id VARCHAR(50) PRIMARY KEY,
f_title VARCHAR(255),
f_price NUMERIC(12,2),
f_creator_user_id VARCHAR(50),
f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_delete_mark INTEGER DEFAULT 0
);
CREATE TABLE book_shop_book (
f_id VARCHAR(50) PRIMARY KEY,
f_title VARCHAR(255),
f_author VARCHAR(100),
f_isbn VARCHAR(32),
f_category VARCHAR(50),
f_price NUMERIC(12,2),
f_stock INTEGER DEFAULT 0,
f_creator_user_id VARCHAR(50),
f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_delete_mark INTEGER DEFAULT 0
);
+96 -1
View File
@@ -1,3 +1,98 @@
//! config —— 环境变量与路径解析(PORT / PGLITE_DIR / 静态目录)。
//!
//! TODO:占位模块,后续任务填充实现。
//! 契约:`docs/contract.md` §9「config.rs」。
//!
//! 路径口径:
//! - `project_dir` = 项目根(由 `main.rs` 从可执行文件向上定位锚点文件得到)。
//! - `pg_dir` 默认 `<project_dir>/src/backend/data/lite.pg`(pglite 数据目录)。
//! - `static_dir` = `<project_dir>/src/frontend/dist`,**不存在则 None**(前端产物没编译出来时
//! 不该让后端去托管一个不存在的目录)。
use std::path::{Path, PathBuf};
/// 后端默认端口。
///
/// 🔴 本仓固定 `:30010`;兄弟项目 `tdc-rs` 占 `:30000`,两者**不共享**任何东西。
pub const DEFAULT_PORT: u16 = 30010;
/// `PGLITE_DIR` 设成该值 ⇒ 用**临时库**(进程退出即销毁)。
///
/// pglite-rs 0.2.7 **没有** 真内存模式(`memory://` 不是它的协议),
/// 所以「临时库」= `PGlite::open_temp()` = 系统临时目录里的一个一次性数据目录。
pub const TEMP_DIR_MARKER: &str = "memory://";
/// 运行时配置(全部来自环境变量 + 项目目录推导)。
#[derive(Clone, Debug)]
pub struct Config {
/// HTTP 监听端口(env `PORT`,缺省或非法 ⇒ `30010`)。
pub port: u16,
/// pglite 数据目录(env `PGLITE_DIR`;值为 `memory://` ⇒ 临时库)。
pub pg_dir: PathBuf,
/// 项目根目录。
pub project_dir: PathBuf,
/// 前端产物目录 `<project_dir>/src/frontend/dist`;不存在 ⇒ `None`。
pub static_dir: Option<PathBuf>,
}
impl Config {
/// 从环境变量 + 传入的 `project_dir` 组装配置。
///
/// - `PORT`:非法值**不 panic**,回落 `30010`(配置写错不该让服务起不来)。
/// - `PGLITE_DIR`:空串按「未设置」处理 ⇒ 用默认数据目录。
pub fn from_env(project_dir: PathBuf) -> Config {
let port = std::env::var("PORT")
.ok()
.and_then(|v| v.trim().parse::<u16>().ok())
.unwrap_or(DEFAULT_PORT);
let pg_dir = match std::env::var("PGLITE_DIR") {
Ok(v) if !v.trim().is_empty() => PathBuf::from(v.trim()),
_ => project_dir.join("src/backend/data/lite.pg"),
};
let dist = project_dir.join("src/frontend/dist");
let static_dir = if dist.is_dir() { Some(dist) } else { None };
Config {
port,
pg_dir,
project_dir,
static_dir,
}
}
/// `pg_dir` 是否为「临时库」标记(`memory://`)⇒ 调用方应走 `Db::open_temp()`。
pub fn pg_is_temp(&self) -> bool {
self.pg_dir.as_path() == Path::new(TEMP_DIR_MARKER)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn defaults_without_env() {
// 外部若已设置 PORT / PGLITE_DIR,本断言的前提不成立 ⇒ 跳过(不改动进程环境)。
if std::env::var("PORT").is_ok() || std::env::var("PGLITE_DIR").is_ok() {
return;
}
// 默认端口恒为 30010,默认数据目录恒是 <project_dir>/src/backend/data/lite.pg。
assert_eq!(DEFAULT_PORT, 30010);
let dir = PathBuf::from("/tmp/does-not-exist-project");
let cfg = Config::from_env(dir.clone());
assert_eq!(cfg.port, DEFAULT_PORT);
assert_eq!(cfg.pg_dir, dir.join("src/backend/data/lite.pg"));
assert_eq!(cfg.project_dir, dir);
// src/frontend/dist 不存在 ⇒ None
assert!(cfg.static_dir.is_none());
}
#[test]
fn pg_is_temp_detects_marker() {
let mut cfg = Config::from_env(PathBuf::from("/tmp/x"));
assert!(!cfg.pg_is_temp());
cfg.pg_dir = PathBuf::from(TEMP_DIR_MARKER);
assert!(cfg.pg_is_temp());
}
}
+775 -2
View File
@@ -1,7 +1,780 @@
//! db —— pglite 封装(单 backend 串行化 + schema 初始化)。
//! db —— pglite 封装(单 backend 串行化 + schema 初始化 + `row_to_json` 序列化)。
//!
//! 契约:`docs/contract.md` §5.4 / §5.5。
//!
//! 官方 7 张 `base_*` 的 DDL 原文(逐字)见 `src/backend/db/schema.sql`。
//! 该文件**不在 web root**,杜绝「DDL 可从 HTTP 下载」。
//!
//! 🔴 三条硬约束(来自规格与裁决):
//! 1. pglite-rs 0.2.7 **没有** `exec_params` ⇒ 在 `query(sql, params)` 之上实现(S1)。
//! 2. 序列化只有一条路:`SELECT row_to_json(q)::text AS _row FROM (<sql>) AS q`
//! ⇒ 单列 text ⇒ `serde_json::from_str`。**不另起逐列类型映射分支**(S2)。
//! 3. pglite 自己的 `serial_guard()` 只覆盖**单次**调用;「一次业务操作跨多条 query」
//! 必须由本层进程级 `tokio::sync::Mutex` 兜住(S3)。
//!
//! 🔴 **JSON 键的大小写**:PostgreSQL 会把**未加双引号**的别名折叠成小写
//! (`AS realName` ⇒ 输出列名 `realname`)⇒ `row_to_json` 出来的键会变成 `realname`,
//! 与契约的 `realName` 对不上。⇒ `query_json` 内部做键归一(见 [`normalize_json_keys`]),
//! **两种投影写法都支持**:`AS <camelCase 别名>` 与直接投影 `f_*` 列。
/// 完整 schema DDL 原文(官方 `base_*` CREATE TABLE 逐字)。
use std::collections::HashMap;
use std::path::Path;
use std::sync::Arc;
use pglite::{PGlite, ToSql};
use serde_json::Value;
use tokio::sync::Mutex;
/// 重新导出 pglite crate。
///
/// `Db` 的公开签名里出现 `pglite::Error` / `pglite::ToSql`,下游(集成测试 crate、
/// 未来的独立 crate)要构造这些类型就必须能引用 pglite —— 而本仓的 `Cargo.toml`
/// **不重复声明**该依赖(依赖版本由 workspace 根统一锁死),所以在这里开一个口子。
pub use pglite;
/// 完整 schema DDL 原文(官方 `base_*` CREATE TABLE 逐字 + 业务表 3 张)。
pub const SCHEMA_SQL: &str = include_str!("../db/schema.sql");
/// `PGLITE_DIR=memory://` 的临时库标记(与 `config::TEMP_DIR_MARKER` 同值)。
const TEMP_DIR_MARKER: &str = "memory://";
/// pglite 封装。
///
/// 🔴 **一个进程一辈子只能开一个实例**(pglite 内部是进程级全局标志:
/// 第二次 `open()` ⇒ `Error::AlreadyOpen`;关掉再开 ⇒ `Error::ReopenUnsupported`)。
/// ⇒ 集成测试必须全文件共用一个实例。
#[derive(Clone)]
pub struct Db {
pg: PGlite,
/// 进程级业务锁(S3)。`Arc` 是因为 `Db` 需要 `Clone`。
lock: Arc<Mutex<()>>,
}
impl Db {
/// 打开(磁盘)数据目录。
///
/// `dir` 为 `memory://` ⇒ 等价于 `open_temp()`(pglite 0.2.7 没有真内存模式)。
pub async fn open(dir: &Path) -> Result<Db, pglite::Error> {
if dir == Path::new(TEMP_DIR_MARKER) {
return Self::open_temp().await;
}
let pg = PGlite::open(dir).await?;
Ok(Self::new(pg))
}
/// 打开临时库(系统临时目录里的一次性数据目录,进程退出即销毁)。
pub async fn open_temp() -> Result<Db, pglite::Error> {
let pg = PGlite::open_temp().await?;
Ok(Self::new(pg))
}
fn new(pg: PGlite) -> Db {
Db {
pg,
lock: Arc::new(Mutex::new(())),
}
}
/// schema 初始化(**只在 `base_user` 不存在时**整体执行一次)。
///
/// - 探测用 `to_regclass('public.base_user')`(一次 round-trip,S5)。
/// - 存在 ⇒ 直接返回(**不是**「每次启动都跑 schema.sql」,§5.5)。
/// - 不存在 ⇒ 按 `;` 切分(**字面量感知**)后逐条 exec。
pub async fn ensure_schema(&self) -> Result<(), pglite::Error> {
let _guard = self.lock.lock().await;
let existing = self
.scalar_text_inner("SELECT to_regclass('public.base_user')::text")
.await?;
if existing.is_some() {
return Ok(());
}
for stmt in split_sql_statements(SCHEMA_SQL) {
self.pg.exec(&stmt).await?;
}
Ok(())
}
/// 查一批行 ⇒ JSON 数组(每行一个对象)。
///
/// 🔴 调用方给的 SQL **必须自带 `AS <camelCase JSON 键>` 别名** ——
/// `row_to_json` 用的就是列的**输出名**当 JSON 键。
pub async fn query_json(&self, sql: &str) -> Result<Vec<Value>, pglite::Error> {
let _guard = self.lock.lock().await;
self.query_json_inner(sql, &[]).await
}
/// 同 [`Db::query_json`],但带参数(占位符 `$1, $2, …` 由**内层** SQL 消费)。
pub async fn query_json_params(
&self,
sql: &str,
params: &[&(dyn ToSql + Sync)],
) -> Result<Vec<Value>, pglite::Error> {
let _guard = self.lock.lock().await;
self.query_json_inner(sql, params).await
}
/// 执行(无返回值)语句。
pub async fn exec(&self, sql: &str) -> Result<(), pglite::Error> {
let _guard = self.lock.lock().await;
self.pg.exec(sql).await
}
/// 执行带参数语句。
///
/// 🔴 pglite-rs 0.2.7 **没有** `exec_params`(S1)⇒ 在 `query(sql, params)` 之上实现,
/// 拿到结果集后丢弃即可。
pub async fn exec_params(
&self,
sql: &str,
params: &[&(dyn ToSql + Sync)],
) -> Result<(), pglite::Error> {
let _guard = self.lock.lock().await;
self.pg.query(sql, params).await.map(|_| ())
}
/// 取第一行的第一列(text);无行或 NULL ⇒ `None`。
pub async fn scalar_text(&self, sql: &str) -> Result<Option<String>, pglite::Error> {
let _guard = self.lock.lock().await;
self.scalar_text_inner(sql).await
}
// ---- 以下为**持锁调用**的内部实现(调用方已持有 `self.lock`)----
async fn query_json_inner(
&self,
sql: &str,
params: &[&(dyn ToSql + Sync)],
) -> Result<Vec<Value>, pglite::Error> {
let inner = trim_sql(sql);
// 预先扫出内层 SQL 的 `AS <别名>` ⇒ 查询后能把 PG 折叠掉的大写还原回去。
let alias_map = collect_alias_map(inner);
let wrapped = format!("SELECT row_to_json(q)::text AS _row FROM ({inner}) AS q");
let rows = self.pg.query(&wrapped, params).await?;
let mut out = Vec::with_capacity(rows.len());
for row in rows {
// `_row` 是 text 列;理论上 row_to_json 不会是 NULL,保险起见按 Option 处理。
let Some(text) = row.get::<Option<String>>(0)? else {
continue;
};
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_map));
}
Ok(out)
}
async fn scalar_text_inner(&self, sql: &str) -> Result<Option<String>, pglite::Error> {
let rows = self.pg.query(sql, &[]).await?;
match rows.first() {
None => Ok(None),
Some(row) => Ok(row.get::<Option<String>>(0)?),
}
}
}
/// 去掉首尾空白与**结尾**的分号(调用方的 SQL 常带 `;`;包成子查询时不能留)。
fn trim_sql(sql: &str) -> &str {
sql.trim().trim_end_matches(';').trim_end()
}
/// 🔴 JSON 键归一(**本仓最容易被踩的坑**,务必读)。
///
/// PostgreSQL 会把**未加双引号**的别名折叠成小写:
/// `SELECT 1 AS realName` 的输出列名是 `realname` ⇒ `row_to_json` 出来的 JSON 键
/// 是 `"realname"`,而契约要的是 `"realName"` ⇒ 前端读不到字段。
/// (实测:PG 17.5 `SELECT row_to_json(q)::text FROM (SELECT 1 AS realName) q`
/// ⇒ `{"realname":1}`;写成 `AS "realName"` 才是 `{"realName":1}`。)
///
/// ⇒ 本仓在 `query_json` 里做**两件事**(两种投影写法都支持):
/// 1. **别名还原**:扫出内层 SQL 的 `AS <别名>`,把 PG 折叠掉的大写按作者原样还原
/// (`AS realName` ⇒ 键 `realName`;`AS "realName"` 本来就原样,无需处理)。
/// 2. **列名映射**:键以 `f_` 开头 ⇒ 走 `column_to_json_key`
/// (`f_real_name` ⇒ `realName`)—— 与 `tdc-rs` 的做法一致(那边是
/// `row_to_json(row)` 在 Rust 侧把 `f_*` 列名转 camelCase)。
///
/// 两条规则都**不会**改动已经是正确 camelCase 的键。
fn normalize_json_keys(value: Value, alias_map: &HashMap<String, String>) -> Value {
let Some(obj) = value.as_object() else {
return value;
};
let mut out = serde_json::Map::new();
for (key, val) in obj {
let new_key = if let Some(orig) = alias_map.get(key) {
orig.clone()
} else if key.starts_with("f_") {
column_to_json_key(key)
} else {
key.clone()
};
out.insert(new_key, val.clone());
}
Value::Object(out)
}
/// 扫出内层 SQL 里的 `AS <别名>` ⇒ `folded小写名 -> 作者写的原名`。
///
/// 🔴 **只收含大写字母的别名**:
/// - 小写别名(`AS id` / `AS f_real_name`)PG 折叠后不变 ⇒ 不必还原;
/// - 误识别(如 `CAST(x AS text)`、`AS SELECT`)只会产生**恒等**映射 ⇒ 无副作用。
fn collect_alias_map(sql: &str) -> HashMap<String, String> {
let b = sql.as_bytes();
let mut map: HashMap<String, String> = HashMap::new();
let mut i = 0usize;
while i < b.len() {
match b[i] {
b'\'' => {
i = skip_single_quoted(b, i);
continue;
}
b'"' => {
i = skip_double_quoted(b, i);
continue;
}
b'-' if b.get(i + 1) == Some(&b'-') => {
i = skip_line_comment(b, i);
continue;
}
b'/' if b.get(i + 1) == Some(&b'*') => {
i = skip_block_comment(b, i);
continue;
}
b'$' => {
if let Some(tag_end) = dollar_tag_end(b, i) {
i = skip_dollar_quoted(sql, b, i, tag_end);
continue;
}
}
_ => {}
}
let c = b[i];
if c.is_ascii_alphabetic() || c == b'_' {
let word_end = read_word_end(b, i);
let word = &sql[i..word_end];
if word.eq_ignore_ascii_case("AS") {
let mut j = word_end;
while j < b.len() && b[j].is_ascii_whitespace() {
j += 1;
}
if j < b.len() && b[j] == b'"' {
// 已加双引号的别名:PG 原样保留大小写 ⇒ 不需要还原
i = skip_double_quoted(b, j);
continue;
}
if j < b.len() && (b[j].is_ascii_alphabetic() || b[j] == b'_') {
let ident_end = read_word_end(b, j);
let ident = &sql[j..ident_end];
if ident.chars().any(|ch| ch.is_ascii_uppercase()) {
map.insert(ident.to_ascii_lowercase(), ident.to_string());
}
i = ident_end;
continue;
}
}
i = word_end;
continue;
}
i += 1;
}
map
}
/// 跳过一段单引号串(`i` 指向开头的 `'`),返回结束位置。
fn skip_single_quoted(b: &[u8], i: usize) -> usize {
let is_escape = i >= 2
&& (b[i - 1] == b'E' || b[i - 1] == b'e')
&& !(b[i - 2].is_ascii_alphanumeric() || b[i - 2] == b'_');
let mut j = i + 1;
while j < b.len() {
if is_escape && b[j] == b'\\' {
j += 2;
continue;
}
if b[j] == b'\'' {
if b.get(j + 1) == Some(&b'\'') {
j += 2;
continue;
}
return j + 1;
}
j += 1;
}
b.len()
}
/// 跳过一段双引号标识符(`i` 指向开头的 `"`),返回结束位置。
fn skip_double_quoted(b: &[u8], i: usize) -> usize {
let mut j = i + 1;
while j < b.len() {
if b[j] == b'"' {
if b.get(j + 1) == Some(&b'"') {
j += 2;
continue;
}
return j + 1;
}
j += 1;
}
b.len()
}
/// 跳过行注释(`i` 指向 `-`),返回结束位置。
fn skip_line_comment(b: &[u8], i: usize) -> usize {
let mut j = i + 2;
while j < b.len() && b[j] != b'\n' {
j += 1;
}
j
}
/// 跳过块注释(`i` 指向 `/`,可嵌套),返回结束位置。
fn skip_block_comment(b: &[u8], i: usize) -> usize {
let mut depth = 1usize;
let mut j = i + 2;
while j < b.len() {
if b[j] == b'/' && b.get(j + 1) == Some(&b'*') {
depth += 1;
j += 2;
continue;
}
if b[j] == b'*' && b.get(j + 1) == Some(&b'/') {
depth -= 1;
j += 2;
if depth == 0 {
break;
}
continue;
}
j += 1;
}
j
}
/// 跳过 dollar-quote 段(`i` 指向开头的 `$`,`tag_end` 是 tag 末尾 `$` 的下标)。
fn skip_dollar_quoted(sql: &str, b: &[u8], i: usize, tag_end: usize) -> usize {
let tag = &sql[i..=tag_end];
let rest = &sql[tag_end + 1..];
match rest.find(tag) {
Some(pos) => tag_end + 1 + pos + tag.len(),
None => b.len(),
}
}
/// 读一个单词(`[A-Za-z0-9_$]*`)的结束位置。
fn read_word_end(b: &[u8], i: usize) -> usize {
let mut j = i;
while j < b.len() && (b[j].is_ascii_alphanumeric() || b[j] == b'_' || b[j] == b'$') {
j += 1;
}
j
}
/// 列名 → JSON 键:去 `f_` 前缀 + `_` 拆词 camelCase。
///
/// `f_real_name` ⇒ `realName`;`f_id` ⇒ `id`;`f_is_administrator` ⇒ `isAdministrator`。
pub fn column_to_json_key(col: &str) -> String {
let core = col.strip_prefix("f_").unwrap_or(col);
let mut out = String::with_capacity(core.len());
for (i, part) in core.split('_').enumerate() {
if i == 0 {
out.push_str(part);
} else if let Some(first) = part.chars().next() {
out.extend(first.to_uppercase());
out.push_str(&part[first.len_utf8()..]);
}
}
out
}
/// JSON 键 → 列名([`column_to_json_key`] 的逆)。
///
/// `realName` ⇒ `f_real_name`;`id` ⇒ `f_id`;`isAdministrator` ⇒ `f_is_administrator`。
pub fn json_key_to_column(key: &str) -> String {
let chars: Vec<char> = key.chars().collect();
let mut snake = String::with_capacity(key.len() + 2);
for (i, &c) in chars.iter().enumerate() {
if c.is_uppercase() {
let prev_lower = i > 0 && (chars[i - 1].is_lowercase() || chars[i - 1].is_ascii_digit());
let prev_upper = i > 0 && chars[i - 1].is_uppercase();
let next_lower = i + 1 < chars.len() && chars[i + 1].is_lowercase();
if i > 0 && (prev_lower || (prev_upper && next_lower)) {
snake.push('_');
}
snake.extend(c.to_lowercase());
} else {
snake.push(c);
}
}
format!("f_{snake}")
}
/// 表名白名单:只收 `[A-Za-z][A-Za-z0-9_]*`。
///
/// 🔴 任何拼进 SQL 的标识符都必须过这里(规格 §1.10)。
pub fn valid_table(name: &str) -> Option<String> {
valid_identifier(name)
}
/// 列名白名单:只收 `[A-Za-z][A-Za-z0-9_]*`。
pub fn valid_column(name: &str) -> Option<String> {
valid_identifier(name)
}
fn valid_identifier(name: &str) -> Option<String> {
let mut chars = name.chars();
match chars.next() {
Some(c) if c.is_ascii_alphabetic() => {}
_ => return None,
}
if !chars.all(|c| c.is_ascii_alphanumeric() || c == '_') {
return None;
}
Some(name.to_string())
}
/// 字面量感知的 SQL 切分。
///
/// 单引号串(含 `E'...'` 的反斜杠转义)、双引号标识符、`$$...$$` / `$tag$...$tag$`、
/// 行注释 `--`、块注释 `/* */`(PG 语义**可嵌套**)里的 `;` **不切**。
/// 注释内容会被丢弃(不进结果),只保留换行以维持行号。
///
/// `$1` / `$2` 这类占位符**不是** dollar-quote,按普通字符处理。
pub fn split_sql_statements(sql: &str) -> Vec<String> {
let b = sql.as_bytes();
let mut out: Vec<String> = Vec::new();
let mut cur = String::new();
let mut i = 0usize;
while i < b.len() {
match b[i] {
b'-' if b.get(i + 1) == Some(&b'-') => {
// 行注释:丢弃到行尾(换行留给外层逻辑处理)
i += 2;
while i < b.len() && b[i] != b'\n' {
i += 1;
}
}
b'/' if b.get(i + 1) == Some(&b'*') => {
// 块注释:可嵌套(PG 语义)。`depth` 起始 1 = 已经吃掉了开头的 `/*`
let mut depth = 1usize;
i += 2;
loop {
if i >= b.len() {
break;
}
if b[i] == b'/' && b.get(i + 1) == Some(&b'*') {
depth += 1;
i += 2;
continue;
}
if b[i] == b'*' && b.get(i + 1) == Some(&b'/') {
depth -= 1;
i += 2;
if depth == 0 {
break;
}
continue;
}
if b[i] == b'\n' {
cur.push('\n');
}
i += 1;
}
}
b'\'' => {
// 单引号串:`E'...'` 走反斜杠转义,普通串只认 `''`
let is_escape = is_escape_prefix(&cur);
cur.push('\'');
i += 1;
while i < b.len() {
let ch = b[i];
if is_escape && ch == b'\\' {
cur.push('\\');
i += 1;
if i < b.len() {
let c = sql[i..].chars().next().unwrap_or('\0');
cur.push(c);
i += c.len_utf8();
}
continue;
}
if ch == b'\'' {
if b.get(i + 1) == Some(&b'\'') {
cur.push_str("''");
i += 2;
continue;
}
cur.push('\'');
i += 1;
break;
}
let c = sql[i..].chars().next().unwrap_or('\0');
cur.push(c);
i += c.len_utf8();
}
}
b'"' => {
// 双引号标识符:`""` 是转义
cur.push('"');
i += 1;
while i < b.len() {
if b[i] == b'"' {
if b.get(i + 1) == Some(&b'"') {
cur.push_str("\"\"");
i += 2;
continue;
}
cur.push('"');
i += 1;
break;
}
let c = sql[i..].chars().next().unwrap_or('\0');
cur.push(c);
i += c.len_utf8();
}
}
b'$' => {
if let Some(tag_end) = dollar_tag_end(b, i) {
let tag = &sql[i..=tag_end];
cur.push_str(tag);
i = tag_end + 1;
let rest = &sql[i..];
match rest.find(tag) {
Some(pos) => {
cur.push_str(&rest[..pos]);
i += pos + tag.len();
}
None => {
// 未闭合:整段当普通文本
cur.push_str(rest);
i = b.len();
}
}
continue;
}
let c = sql[i..].chars().next().unwrap_or('\0');
cur.push(c);
i += c.len_utf8();
}
b';' => {
let stmt = cur.trim();
if !stmt.is_empty() {
out.push(stmt.to_string());
}
cur.clear();
i += 1;
}
_ => {
let c = sql[i..].chars().next().unwrap_or('\0');
cur.push(c);
i += c.len_utf8();
}
}
}
let stmt = cur.trim();
if !stmt.is_empty() {
out.push(stmt.to_string());
}
out
}
/// 判断紧邻引号的前一个 token 是不是 `E`/`e`(⇒ `E'...'` 反斜杠转义串)。
fn is_escape_prefix(cur: &str) -> bool {
let b = cur.as_bytes();
if b.is_empty() {
return false;
}
let last = b[b.len() - 1];
if last != b'E' && last != b'e' {
return false;
}
if b.len() == 1 {
return true;
}
let prev = b[b.len() - 2];
!(prev.is_ascii_alphanumeric() || prev == b'_')
}
/// dollar-quote 的 tag 结束位置(`$` 之后的那个 `$` 的下标);不是 dollar-quote ⇒ `None`。
///
/// `$$` ⇒ tag 就是 `$$`;`$tag$` ⇒ tag 是 `$tag$`;`$1`(占位符)⇒ `None`。
fn dollar_tag_end(b: &[u8], i: usize) -> Option<usize> {
let mut j = i + 1;
if j >= b.len() {
return None;
}
let first = b[j];
if first.is_ascii_digit() {
return None; // $1 / $2 占位符
}
if !(first.is_ascii_alphabetic() || first == b'_') {
return if first == b'$' { Some(j) } else { None };
}
while j < b.len() && (b[j].is_ascii_alphanumeric() || b[j] == b'_') {
j += 1;
}
if j < b.len() && b[j] == b'$' {
Some(j)
} else {
None
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn split_keeps_semicolon_inside_literals() {
assert_eq!(split_sql_statements("SELECT 'a;b'").len(), 1);
assert_eq!(split_sql_statements("SELECT $$a;b$$").len(), 1);
assert_eq!(split_sql_statements("SELECT 1 -- a;b").len(), 1);
assert_eq!(split_sql_statements("SELECT /* a;b */ 1").len(), 1);
assert_eq!(split_sql_statements("SELECT 1; SELECT 2").len(), 2);
}
#[test]
fn split_more_literal_shapes() {
// 双引号标识符里的 `;` 不切
assert_eq!(split_sql_statements(r#"SELECT "a;b" FROM t"#).len(), 1);
// E'' 串里的 `;` 不切
assert_eq!(split_sql_statements(r"SELECT E'a;b'").len(), 1);
// $tag$ dollar-quote
assert_eq!(split_sql_statements("SELECT $tag$a;b$tag$").len(), 1);
// 嵌套块注释
assert_eq!(split_sql_statements("SELECT /* a /* b; */ c; */ 1").len(), 1);
// 占位符不是 dollar-quote
assert_eq!(split_sql_statements("SELECT * FROM t WHERE a = $1; SELECT 2").len(), 2);
// 空串 / 只有空白 ⇒ 0 条
assert!(split_sql_statements("").is_empty());
assert!(split_sql_statements(" \n ").is_empty());
// 只有注释 ⇒ 0 条
assert!(split_sql_statements("-- 注释\n/* 注释 */").is_empty());
}
#[test]
fn split_content_is_trimmed() {
let parts = split_sql_statements(" SELECT 1 ; SELECT 2 ");
assert_eq!(parts.len(), 2);
assert_eq!(parts[0], "SELECT 1");
assert_eq!(parts[1], "SELECT 2");
}
#[test]
fn json_key_mapping() {
assert_eq!(column_to_json_key("f_real_name"), "realName");
assert_eq!(column_to_json_key("f_id"), "id");
assert_eq!(column_to_json_key("f_is_administrator"), "isAdministrator");
assert_eq!(json_key_to_column("realName"), "f_real_name");
assert_eq!(json_key_to_column("id"), "f_id");
assert_eq!(json_key_to_column("isAdministrator"), "f_is_administrator");
}
#[test]
fn json_key_mapping_is_bijective_over_contract_columns() {
// docs/contract.md §4 的全部列 ⇒ 正反互逆
let cols = [
"f_id",
"f_tenant_id",
"f_account",
"f_real_name",
"f_password",
"f_secretkey",
"f_is_administrator",
"f_role_id",
"f_organize_id",
"f_creator_user_id",
"f_creator_time",
"f_enabled_mark",
"f_delete_mark",
"f_full_name",
"f_en_code",
"f_url_address",
"f_parent_id",
"f_sort_code",
"f_type",
"f_category",
"f_icon",
"f_object_type",
"f_object_id",
"f_item_type",
"f_item_id",
"f_user_id",
"f_org_id",
"f_title",
"f_status",
"f_price",
"f_stock",
"f_author",
"f_isbn",
];
for col in cols {
let key = column_to_json_key(col);
assert_eq!(json_key_to_column(&key), col, "往返失败: {col} -> {key}");
}
}
#[test]
fn alias_map_restores_author_case() {
// 契约 §5.3 的写法:`AS <camelCase JSON 键>`
let m = collect_alias_map(
"SELECT f_id AS id, f_real_name AS realName, f_creator_time AS creatorTime FROM base_user",
);
assert_eq!(m.get("realname").map(String::as_str), Some("realName"));
assert_eq!(m.get("creatortime").map(String::as_str), Some("creatorTime"));
// 小写别名不进映射(PG 折叠后不变)
assert!(!m.contains_key("id"));
// 字面量 / 注释里的 AS 不能被误识别
let m2 = collect_alias_map("SELECT 'AS realName' AS fooName, 1 -- AS barName\n");
assert_eq!(m2.get("fooname").map(String::as_str), Some("fooName"));
assert!(!m2.contains_key("realname"));
assert!(!m2.contains_key("barname"));
// 已加双引号的别名不需要还原
let m3 = collect_alias_map(r#"SELECT f_id AS "realName""#);
assert!(m3.is_empty());
}
#[test]
fn normalize_json_keys_handles_both_styles() {
let map = collect_alias_map("SELECT f_real_name AS realName, f_id AS id");
// 风格 A(契约 §5.3):别名是 camelCase —— PG 折叠成小写后被还原
let v = serde_json::json!({"realname": "张三", "id": "x"});
let out = normalize_json_keys(v, &map);
assert_eq!(out["realName"], "张三");
assert_eq!(out["id"], "x");
// 风格 B(tdc-rs):直接投影 f_ 列 —— 走 column_to_json_key
let v2 = serde_json::json!({"f_real_name": "张三", "f_id": "x"});
let out2 = normalize_json_keys(v2, &map);
assert_eq!(out2["realName"], "张三");
assert_eq!(out2["id"], "x");
// 已经是正确 camelCase 的键不受影响
let v3 = serde_json::json!({"realName": "张三"});
let out3 = normalize_json_keys(v3, &map);
assert_eq!(out3["realName"], "张三");
}
#[test]
fn identifier_whitelist() {
assert!(valid_table("base_user").is_some());
assert!(valid_table("base_user; DROP TABLE x").is_none());
assert!(valid_table("").is_none());
assert!(valid_table("1abc").is_none());
assert!(valid_table("用户").is_none());
assert!(valid_column("f_real_name").is_some());
assert!(valid_column("1abc").is_none());
assert!(valid_column("a b").is_none());
}
#[test]
fn schema_sql_has_ten_tables() {
// schema.sql 必须包含 10 张表的 CREATE TABLE(7 张 base_* + 3 张业务表)
let count = SCHEMA_SQL.matches("CREATE TABLE ").count();
assert_eq!(count, 10, "schema.sql 的 CREATE TABLE 数量应为 10");
}
}
+228
View File
@@ -0,0 +1,228 @@
//! db 集成测试 —— pglite 单实例。
//!
//! 🔴 pglite-rs 0.2.7 是**进程级全局标志**:一个进程一辈子只能开一个实例
//! (第二次 `open()` ⇒ `Error::AlreadyOpen`)。⇒ 全文件**共用一个临时库**
//! (`OnceCell` 起一次),不每个测试函数各开一个。
//!
//! 单元测试(`src/backend/src/db.rs` 里的 `#[cfg(test)]`)**一律不碰库**。
use tds_lite_rs::db::{pglite::ToSql, Db};
use tokio::sync::OnceCell;
/// 全文件共享的临时库。
static DB: OnceCell<Db> = OnceCell::const_new();
async fn db() -> &'static Db {
DB.get_or_init(|| async {
Db::open_temp()
.await
.expect("打开 pglite 临时库失败")
})
.await
}
/// 契约 §5.1 的 10 张表。
const EXPECTED_TABLES: [&str; 10] = [
"base_authorize",
"base_module",
"base_organize",
"base_role",
"base_role_relation",
"base_user",
"base_user_relation",
"demo_item",
"shop_product",
"book_shop_book",
];
#[tokio::test]
async fn db_schema_and_row_shapes() {
let db = db().await;
// ---- 1) ensure_schema 建库(10 张表) ----
db.ensure_schema().await.expect("ensure_schema 失败");
// ---- 2) 二次 ensure_schema 幂等(不报错、不重建) ----
db.ensure_schema().await.expect("二次 ensure_schema 失败");
// ---- 3) 10 张表都存在(查 pg_catalog.pg_tables) ----
let rows = db
.query_json(
"SELECT tablename AS tableName FROM pg_catalog.pg_tables \
WHERE schemaname = 'public' ORDER BY tablename",
)
.await
.expect("查表清单失败");
let names: Vec<String> = rows
.iter()
.map(|r| {
r["tableName"]
.as_str()
.unwrap_or_default()
.to_string()
})
.collect();
for t in EXPECTED_TABLES {
assert!(
names.iter().any(|n| n == t),
"缺表 {t};现有表: {names:?}"
);
}
// ---- 4) shop_product:f_price = 9.90 ⇒ 读回是**字符串** "9.90" ----
//
// 🔴 参数一律按 text 传(S7):显式 `::text::numeric` 让 PG 把 $3 推断成 TEXT,
// 再由 SQL 自己转成 numeric(否则 PG 会推断成 numeric,`&str` 绑不上去)。
let product_id = String::from("11111111-1111-4111-8111-111111111111");
let title = String::from("示例商品");
let price = String::from("9.90");
let creator = String::from("user-1");
let ctime = String::from("2026-01-01 00:00:00");
let mark = String::from("0");
let params: [&(dyn ToSql + Sync); 6] = [
&product_id,
&title,
&price,
&creator,
&ctime,
&mark,
];
db.exec_params(
"INSERT INTO shop_product (f_id, f_title, f_price, f_creator_user_id, f_creator_time, f_delete_mark) \
VALUES ($1::text, $2::text, $3::text::numeric, $4::text, $5::text::timestamp, $6::text::integer)",
&params,
)
.await
.expect("插入 shop_product 失败");
let product_rows = db
.query_json_params(
"SELECT f_id AS id, f_title AS title, f_price::text AS price, \
f_creator_user_id AS creatorUserId, f_delete_mark AS deleteMark \
FROM shop_product WHERE f_id = $1::text",
&[&product_id],
)
.await
.expect("读回 shop_product 失败");
assert_eq!(product_rows.len(), 1, "shop_product 应只有 1 行");
let p = &product_rows[0];
assert_eq!(
p["price"].as_str(),
Some("9.90"),
"numeric 必须序列化成字符串 \"9.90\",实际: {}",
p["price"]
);
assert!(p["price"].is_string(), "price 必须是 JSON 字符串");
// int 列保持 JSON 数字
assert_eq!(p["deleteMark"].as_i64(), Some(0));
// id 是 36 字符
let id = p["id"].as_str().expect("id 必须是字符串");
assert_eq!(id.len(), 36, "id 应为 36 位 UUID,实际: {id}");
assert_eq!(id, product_id);
// ---- 5) book_shop_book:f_stock = 100 ⇒ 读回是**数字** 100 ----
let book_id = String::from("22222222-2222-4222-8222-222222222222");
let author = String::from("作者");
let isbn = String::from("9780000000000");
let category = String::from("科技");
let stock = String::from("100");
let book_params: [&(dyn ToSql + Sync); 6] = [
&book_id,
&title,
&author,
&isbn,
&category,
&stock,
];
db.exec_params(
"INSERT INTO book_shop_book (f_id, f_title, f_author, f_isbn, f_category, f_stock) \
VALUES ($1::text, $2::text, $3::text, $4::text, $5::text, $6::text::integer)",
&book_params,
)
.await
.expect("插入 book_shop_book 失败");
let book_rows = db
.query_json(
"SELECT f_id AS id, f_title AS title, f_author AS author, f_isbn AS isbn, \
f_category AS category, f_price::text AS price, f_stock AS stock \
FROM book_shop_book WHERE f_id = '22222222-2222-4222-8222-222222222222'",
)
.await
.expect("读回 book_shop_book 失败");
assert_eq!(book_rows.len(), 1);
let b = &book_rows[0];
assert_eq!(b["stock"].as_i64(), Some(100), "int 列必须保持 JSON 数字");
assert!(b["stock"].is_i64(), "stock 必须是 JSON 数字");
assert_eq!(b["id"].as_str().map(|s| s.len()), Some(36));
// ---- 6) DB 默认值:f_delete_mark / f_stock 缺省补 0,其余列不给就是 NULL ----
let demo_id = String::from("33333333-3333-4333-8333-333333333333");
let demo_title = String::from("示例条目");
db.exec_params(
"INSERT INTO demo_item (f_id, f_title) VALUES ($1::text, $2::text)",
&[&demo_id, &demo_title],
)
.await
.expect("插入 demo_item 失败");
let demo_rows = db
.query_json(
"SELECT f_id AS id, f_title AS title, f_status AS status, f_delete_mark AS deleteMark \
FROM demo_item WHERE f_id = '33333333-3333-4333-8333-333333333333'",
)
.await
.expect("读回 demo_item 失败");
assert_eq!(demo_rows.len(), 1);
assert_eq!(
demo_rows[0]["deleteMark"].as_i64(),
Some(0),
"f_delete_mark 的 DB 默认值应为 0"
);
assert!(
demo_rows[0]["status"].is_null(),
"f_status 没有 DB 默认值 ⇒ 必须为 NULL(§7.6 路径 2)"
);
// ---- 7) scalar_text ----
let one = db.scalar_text("SELECT 1::text").await.expect("scalar_text 失败");
assert_eq!(one.as_deref(), Some("1"));
let none = db
.scalar_text("SELECT NULL::text")
.await
.expect("scalar_text 失败");
assert_eq!(none, None);
// ---- 8) 契约 §5.3 的投影写法 ⇒ JSON 键必须是 camelCase ----
//
// 🔴 PostgreSQL 会把未加引号的别名折叠成小写(`AS realName` ⇒ `realname`),
// 所以 `row_to_json` 直接出来的键是错的 ⇒ db.rs 负责还原。
let user_id = String::from("44444444-4444-4444-8444-444444444444");
let account = String::from("tester");
let real_name = String::from("张三");
let user_params: [&(dyn ToSql + Sync); 4] = [&user_id, &account, &real_name, &"1".to_string()];
db.exec_params(
"INSERT INTO base_user (f_id, f_account, f_real_name, f_is_administrator) \
VALUES ($1::text, $2::text, $3::text, $4::text::integer)",
&user_params,
)
.await
.expect("插入 base_user 失败");
let user_rows = db
.query_json(
"SELECT f_id AS id, f_account AS account, f_real_name AS realName, \
f_is_administrator AS isAdministrator, f_creator_time AS creatorTime, \
to_char(f_creator_time, 'YYYY-MM-DD\"T\"HH24:MI:SS') || 'Z' AS creatorTimeIso \
FROM base_user WHERE f_account = 'tester'",
)
.await
.expect("读回 base_user 失败");
assert_eq!(user_rows.len(), 1);
let u = &user_rows[0];
assert_eq!(u["realName"], "张三", "键必须是 camelCase 的 realName");
assert_eq!(u["account"], "tester");
assert_eq!(u["isAdministrator"].as_i64(), Some(1));
assert!(u.get("creatorTime").is_some(), "creatorTime 键必须存在");
// numeric / int 的形态
assert!(u["isAdministrator"].is_i64(), "int 列保持 JSON 数字");
}