fix(final): 前端就绪校验 + 绑 127.0.0.1 + 413 信封化 + 优雅停机 + 文档事实修正
- run.sh: dev 增加前端就绪轮询(60s),失败收前端(PID 文件 + 按端口兜底)、打印 frontend.log 尾部、退出码 1,并写明后端仍在运行 - 后端默认只监听 127.0.0.1(BIND_ADDR 可覆盖,非法值回落 127.0.0.1),横幅打印实际绑定地址 - 响应改写层新增 413 ⇒ 信封(保留 HTTP 413 状态码),并补一条 >2MB body 的单测 - SIGTERM/SIGINT 优雅停机:先收完在途请求,再关嵌入式 PG(数据目录不再留 postmaster.pid) - 文档事实修正:畸形百分号编码的假断言、memory:// 的口径、模块表 API、门④命令、端口口径、token 实际寿命 Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
1 parent
621e636e76
commit
1539892d86
9 files changed
+337
-47
No files matched your search
@@ -8,6 +8,16 @@
|
||||
# 两套服务必须彻底分开(不共享端口 / 数据目录 / 代码)。
|
||||
PORT=30010
|
||||
|
||||
# 后端监听地址。
|
||||
#
|
||||
# 🔴 **默认只监听本机**(127.0.0.1):本仓的种子口令是 admin/123456、token 永不过期
|
||||
# ⇒ 若默认监听所有网卡,局域网内可以直接连上后端 ⇒ 必须朝安全方向默认。
|
||||
# 要在容器 / 反代里对外暴露,才把它改成 0.0.0.0。
|
||||
#
|
||||
# 🔴 只接受**字面 IP**(127.0.0.1 / 0.0.0.0 / ::1);写主机名(如 localhost)
|
||||
# 会被判非法 ⇒ 回落 127.0.0.1。
|
||||
BIND_ADDR=127.0.0.1
|
||||
|
||||
# pglite 数据目录。
|
||||
#
|
||||
# 🔴 **留空** ⇒ 用后端的默认值 `<项目根>/src/backend/data/lite.pg`
|
||||
|
||||
+25
-11
@@ -72,7 +72,7 @@ Redis+Sa-Token / 分页 / `secretkey` 的官方双层 md5 算法。理由见 `CL
|
||||
tds-lite-rs/ ← 独立 git 仓(已 init,未 commit)
|
||||
├── Cargo.toml ← 【workspace 根】members=["src/backend"] + [profile.release]
|
||||
├── src/backend/ ← 名字保留是为了将来抽技能时目录与 react 版对齐
|
||||
│ ├── src/*.rs ← 14 个模块(见 §3.3)
|
||||
│ ├── src/*.rs ← 16 个模块(见 §3.3)
|
||||
│ ├── db/schema.sql ← 10 张表完整 DDL
|
||||
│ └── data/ ← 运行期(gitignore)
|
||||
├── src/frontend/ ← react 技能前端逐字复制(零改)
|
||||
@@ -81,9 +81,14 @@ tds-lite-rs/ ← 独立 git 仓(已 init,未 commit)
|
||||
└── .env.example
|
||||
```
|
||||
|
||||
**端口**:后端 `30010`(`PORT` 可覆盖)· 前端 `5173`(vite)· vite proxy `/api` → `http://127.0.0.1:30010`。
|
||||
**端口**:后端 `30010` · 前端 `5173`(vite)· vite proxy `/api` → `http://127.0.0.1:30010`。
|
||||
🔴 **本仓端口是硬约定**:`run.sh` 的端口常量不许改 —— `PORT` 被设成 ≠ 30010 时
|
||||
`run.sh dev` / `run.sh backend` **报错退出 2**(要换端口请**直接跑二进制**);
|
||||
**后端二进制本身**确实吃 `PORT`(非法值回落 30010)。
|
||||
🔴 后端**默认只监听 `127.0.0.1`**(`BIND_ADDR` 可覆盖);`BIND_ADDR=0.0.0.0` 才对外暴露。
|
||||
|
||||
**数据库**:`pglite-rs`,默认落盘 `src/backend/data/lite.pg`;`PGLITE_DIR=memory://` ⇒ 纯内存。
|
||||
**数据库**:`pglite-rs`,默认落盘 `src/backend/data/lite.pg`;`PGLITE_DIR=memory://` ⇒ **临时库**
|
||||
(系统临时目录里的一次性数据目录,进程退出即销毁;pglite-rs 0.2.7 **没有**真内存模式)。
|
||||
|
||||
### 3.2 契约逐字对齐表(对着 react 技能源码抄)
|
||||
|
||||
@@ -149,11 +154,11 @@ tds-lite-rs/ ← 独立 git 仓(已 init,未 commit)
|
||||
|
||||
| 模块 | 职责 | 备注 |
|
||||
|---|---|---|
|
||||
| `main.rs` | 启动装配:开库 → 起 schema → seed → 建路由 → 挂中间件 → 监听 | `with_state` 必须是最后一步 |
|
||||
| `config.rs` | `PORT` / `PGLITE_DIR` / 静态目录 / 种子开关 | 环境变量 |
|
||||
| `db.rs` | pglite 封装:`query_json()` / `query_rows()` / `exec()` / `ensure_schema()` / `valid_table()` | 单 backend ⇒ 进程级 `db_lock` |
|
||||
| `main.rs` | 启动装配:开库 → 起 schema → seed → 建路由 → 挂中间件 → 监听(+ 优雅停机) | `with_state` 必须是最后一步 |
|
||||
| `config.rs` | `PORT` / `BIND_ADDR` / `PGLITE_DIR` / 静态目录 / 种子开关 | 环境变量 |
|
||||
| `db.rs` | pglite 封装:`open()` / `open_temp()` / `ensure_schema()` / `query_json()` / `query_json_params()` / `exec()` / `exec_params()` / `scalar_text()` | 单 backend ⇒ 进程级 `db_lock` |
|
||||
| `cipher.rs` | `md5_hex()` / `encrypt_password()` / `decrypt_to_md5()` | **逐字对齐 `cipher.ts`** + 上游向量单测 |
|
||||
| `envelope.rs` | `ActionResult{code,msg,data}` + `ok/fail/fail_code` | 业务失败恒 HTTP 200 |
|
||||
| `envelope.rs` | `ActionResult{code,msg,data}` + `ok()` / `fail()` | 业务失败恒 HTTP 200 |
|
||||
| `ids.rs` | `new_uuid()` → 36 位 UUID v4 | **不是** tdc-rs 的雪花 |
|
||||
| `session.rs` | 内存 token 表(`lite-` 前缀 + 32 hex) | 进程重启即失效 |
|
||||
| `auth.rs` | 登录 / CurrentUser / `require_login()` / `require_module()` | 守卫返回 `ActionResult`(600 / 403) |
|
||||
@@ -162,7 +167,9 @@ tds-lite-rs/ ← 独立 git 仓(已 init,未 commit)
|
||||
| `sys.rs` | 5 组 `base_*` 的显式 handler 语义 | 用户/角色/机构/菜单/授权 |
|
||||
| `crud.rs` | spec 驱动的通用 CRUD(List/Save/Delete) | 业务实体用 |
|
||||
| `entities.rs` | 业务实体 spec 表(表名 / 列 / 类型 / 数值列 / 守卫菜单 key) | 加业务模块 = 加一条 spec |
|
||||
| `routes.rs` | 路由装配 | |
|
||||
| `routes.rs` | 路由装配(404 / 405 / 413 改写 / catch-all 三层兜底) | |
|
||||
| `state.rs` | `AppState{config, db, sessions}`(三个字段全是 `Arc`) | axum `State` 的载体 |
|
||||
| `lib.rs` | 库入口:`pub mod` 声明全部模块 | 让单测 / 集成测试能直接引用各模块 |
|
||||
|
||||
### 3.4 三个关键取舍
|
||||
|
||||
@@ -223,7 +230,7 @@ tds-lite-rs/ ← 独立 git 仓(已 init,未 commit)
|
||||
|
||||
| step | 内容 | 完成判据 |
|
||||
|---|---|---|
|
||||
| **0** | 建 **cargo workspace**(根 `Cargo.toml`:`[workspace] members=["src/backend"]` + `[profile.release]`)+ 成员 crate(依赖照 tdc-rs:axum 0.8 / tokio / tower-http 0.6 / serde / serde_json / serde_urlencoded 0.7 / rand 0.8 / hex 0.4 / aes 0.8 / ecb 0.1 / md-5 0.10 / uuid v4 / pglite-rs 0.2 / chrono 0.4) | 根目录 `cargo build` 通过(哪怕是空 main) |
|
||||
| **0** | 建 **cargo workspace**(根 `Cargo.toml`:`[workspace] members=["src/backend"]` + `[profile.release]`)+ 成员 crate(依赖照 tdc-rs:axum 0.8 / tokio / serde / serde_json / serde_urlencoded 0.7 / rand 0.8 / hex 0.4 / aes 0.8 / ecb 0.1 / md-5 0.10 / uuid v4 / pglite-rs 0.2 / chrono 0.4) | 根目录 `cargo build` 通过(哪怕是空 main) |
|
||||
| **1** | `src/cipher.rs` + 单测 | 上游向量**逐字节**相等;`md5_hex` 与 `decrypt_to_md5` 往返一致 |
|
||||
| **2** | `src/envelope.rs` + 单测 | 业务失败 HTTP 200 + `code=400`;`code=600/403` 同形 |
|
||||
| **3** | `src/db.rs` + `src/config.rs` + `db/schema.sql`(10 张表) | 进程能开库并建表;`query_json()` 能取回 JSON |
|
||||
@@ -377,8 +384,9 @@ bash run.sh dev # 日常:后台起后端(30010) + 前端(5173)
|
||||
```
|
||||
|
||||
- 前端:**http://127.0.0.1:5173**(vite dev server,`/api` 代理到后端)
|
||||
- 后端:**http://127.0.0.1:30010**
|
||||
- 后端:**http://127.0.0.1:30010**(**默认只监听本机**;`BIND_ADDR=0.0.0.0` 才对外暴露)
|
||||
- 账号:**`admin` / `123456`**(首次启动自动种子)
|
||||
- `bash run.sh dev` 的**后端与前端都就绪**才算成功(任一没就绪 ⇒ 退出码 1 并打印对应日志尾部)
|
||||
- `bash run.sh logs` 看日志(`.logs/backend.log`、`.logs/frontend.log`);`bash run.sh stop` 停(幂等)
|
||||
- 🔴 `run.sh` 的 `kill_ports` 是 `kill -9` ⇒ 只清 **30010 / 5173**,**绝不碰兄弟项目 `tdc-rs` 的端口**
|
||||
- 🔴 打 localhost 用 curl **必须**加 `--noproxy '*'`(本机 curl 走系统代理)
|
||||
@@ -413,12 +421,18 @@ bash run.sh dev # 日常:后台起后端(30010) + 前端(5173)
|
||||
|
||||
- **(k)** release 二进制**没有** catch-all 的自动化覆盖(触发 panic 的端点是 `#[cfg(test)]` 专属;
|
||||
catch-all 中间件代码在测试构建与 release 构建里**逐字相同**,且 release profile **没有**启用 abort 型 panic ⇒ 行为等价)。
|
||||
- **(l)** `Path<String>` 遇**畸形百分号编码** ⇒ axum 默认返**纯文本 400(非信封)**(handler 签名由契约 §S17 定死,改它要动 `sys.rs`)。
|
||||
- **(l)** ~~`Path<String>` 遇**畸形百分号编码** ⇒ axum 默认返**非信封的 400 响应**~~ ⇒ 🔴 **已推翻**
|
||||
(最终整体评审修复轮 R=3 实测):axum 0.8.9 **接受**该转义 ——
|
||||
`PUT /api/permission/Authority/Data/%zz` 实测返回 **HTTP 200 + `{"code":600,"msg":"未登录","data":null}`**
|
||||
(信封,正常)⇒ **不存在**「返非信封 400」这种破口,原裁决的前提不成立 ⇒ **不改代码**。
|
||||
- **(m)** 冒烟脚本**每次跑**会往库里留一行 `shop_product` + 一行 `book_shop_book` + 一行 `smoke_user`
|
||||
(react 同款行为;契约 §13 未要求清理 ⇒ 不改)。
|
||||
- **(n)** 冒烟脚本在「重复账号 curl 超时」场景下 stderr 会多一行 `cat: … No such file`(观感,判据不受影响)。
|
||||
- **(o)** 冒烟脚本在「空 body 前置失败」时 jq / python 两条路径的**前置提示文案**不同
|
||||
(`code=无` vs `code=ERR`),退出码都是 2。
|
||||
- **(p)** **token 的真实寿命 = 后端进程寿命**(`session.rs` 是内存 token 表、**没有 TTL**):
|
||||
登录响应里的 `expiresIn: 7200` 是**契约 §6.1 逐字定死**的字面量、**不会被强制执行**
|
||||
(进程不重启就永不过期);契约未覆盖 TTL ⇒ **不改**。
|
||||
|
||||
Task 12 修复轮 R=1 另记两条 `run.sh` 的**行为口径**(不是缺陷,是刻意设计):
|
||||
|
||||
|
||||
@@ -22,6 +22,7 @@ bash run.sh build
|
||||
bash run.sh dev
|
||||
# 前端 http://127.0.0.1:5173 后端 http://127.0.0.1:30010
|
||||
# 账号 admin / 123456
|
||||
# (**后端与前端都就绪**才算成功;任一没就绪 ⇒ 退出码 1 并打印对应日志尾部)
|
||||
|
||||
bash run.sh stop # 停(幂等)
|
||||
bash run.sh logs # 看日志尾部
|
||||
@@ -29,7 +30,7 @@ bash run.sh logs # 看日志尾部
|
||||
|
||||
| 端口 | 谁 | 说明 |
|
||||
|---|---|---|
|
||||
| `30010` | 后端(Rust) | `PORT` 可覆盖;**兄弟项目 `tdc-rs` 占了 `:30000`,本仓不碰** |
|
||||
| `30010` | 后端(Rust) | **硬约定**:`run.sh` 的端口不许改 —— `PORT` ≠ 30010 时 `run.sh dev` / `run.sh backend` 报错退出 2(要换端口请**直接跑二进制**)。**后端二进制本身**吃 `PORT`(非法值回落 30010)。默认**只监听 `127.0.0.1`**;`BIND_ADDR=0.0.0.0` 才对外暴露 |
|
||||
| `5173` | 前端(vite dev) | `strictPort: true` ⇒ 端口被占直接报错,不自动换端口 |
|
||||
|
||||
---
|
||||
@@ -40,7 +41,7 @@ bash run.sh logs # 看日志尾部
|
||||
tds-lite-rs/
|
||||
├── Cargo.toml # cargo workspace 根(成员 = src/backend)+ release profile
|
||||
├── run.sh # install / build / dev / backend / frontend / stop / logs
|
||||
├── .env.example # PORT / PGLITE_DIR(PGLITE_DIR 只能写绝对路径或 memory://)
|
||||
├── .env.example # PORT / BIND_ADDR / PGLITE_DIR(PGLITE_DIR 只能写绝对路径或 memory://)
|
||||
├── src/backend/ # Rust 后端(axum 0.8 + pglite-rs 0.2,10 张表,27 条路由)
|
||||
├── src/frontend/ # react 技能前端**逐字复制**(只改 vite 代理端口 30000 → 30010)
|
||||
├── scripts/perm-smoke.sh # 权限闭环冒烟(32 条断言,零 node 依赖)
|
||||
@@ -78,7 +79,7 @@ tds-lite-rs/
|
||||
| ① 编译 | `cargo build --release` | 0 error **0 warning** |
|
||||
| ② 单测 | `cargo test` | 全绿(当前 **177 passed / 0 failed**) |
|
||||
| ③ 冒烟 | `bash scripts/perm-smoke.sh` | **PASS=32 FAIL=0**(需后端已起在 `:30010`) |
|
||||
| ④ 前端手验 | `bash run.sh frontend` | `http://127.0.0.1:5173` → `admin/123456` 登录 → 菜单树正确 → 5 个管理页可增删改 → DemoItem/Product/Book 三页可用 → 退出再登录 |
|
||||
| ④ 前端手验 | `bash run.sh dev` | `http://127.0.0.1:5173` → `admin/123456` 登录 → 菜单树正确 → 5 个管理页可增删改 → DemoItem/Product/Book 三页可用 → 退出再登录 |
|
||||
|
||||
外加:`bash scripts/check-module.sh`(9 接触点静态自检)—— 加业务模块后立刻跑的前置闸门。
|
||||
|
||||
@@ -100,7 +101,11 @@ tds-lite-rs/
|
||||
|
||||
- **release 二进制没有 catch-all 的自动化覆盖**:触发 panic 的端点是 `#[cfg(test)]` 专属;
|
||||
catch-all 中间件代码在测试构建与 release 构建里逐字相同,且 release profile **无** `panic = "abort"` ⇒ 行为等价。
|
||||
- **`Path<String>` 遇畸形百分号编码** ⇒ axum 默认返纯文本 400(**非信封**);handler 签名由契约定死。
|
||||
- **`Path<String>` 遇畸形百分号编码** ⇒ **实测 axum 0.8.9 接受该转义**:`PUT /api/permission/Authority/Data/%zz`
|
||||
返回 **HTTP 200 + `{"code":600,"msg":"未登录","data":null}`**(信封,正常)⇒ **不存在**「返非信封 400」这种破口。
|
||||
- **token 的真实寿命 = 后端进程寿命**(`session.rs` 是内存 token 表、**没有 TTL**):
|
||||
登录响应里的 `expiresIn: 7200` 是**契约 §6.1 逐字定死**的字面量、**不会被强制执行**
|
||||
(进程不重启就永不过期);契约未覆盖 TTL ⇒ 不改。
|
||||
- **冒烟脚本每次跑会往库里留一行** `shop_product` + 一行 `book_shop_book` + 一行 `smoke_user`(react 同款行为,契约未要求清理)。
|
||||
- 冒烟脚本在「重复账号 curl 超时」场景下 stderr 会多一行 `cat: … No such file`(观感,判据不受影响)。
|
||||
- 冒烟脚本在「空 body 前置失败」时 jq / python 两条路径的前置提示文案不同(退出码都是 2)。
|
||||
|
||||
+23
-4
@@ -51,6 +51,8 @@ bash run.sh stop # 停(幂等:无进程时也不报错,退出码 0
|
||||
- 前端:**http://127.0.0.1:5173**
|
||||
- 后端:**http://127.0.0.1:30010**
|
||||
- 账号:**`admin` / `123456`**(首次启动自动种;密码用浏览器侧 `utils/cipher.ts` 加密后提交)
|
||||
—— 登录后的 **token 寿命 = 后端进程寿命**(`session.rs` 是内存 token 表、**没有 TTL**);
|
||||
响应里的 `expiresIn: 7200` 是**契约 §6.1 逐字定死**的字面量、**不会被强制执行**。
|
||||
- PID 在 `.run/{backend,frontend}.pid`,日志在 `.logs/{backend,frontend}.log`(两者都在 `.gitignore` 里)
|
||||
|
||||
单起一半:
|
||||
@@ -70,18 +72,34 @@ bash run.sh frontend # 前台跑 vite
|
||||
其它子命令(`--help` / 无参 / `logs` / `install` / `build` / `stop` / `frontend`)**不碰端口**
|
||||
⇒ **完全不受 `PORT` 影响**(环境里恰好有个 `PORT` 不会让它们失败)。
|
||||
要用别的端口请直接跑二进制:`PORT=xxxx ./target/release/tds-lite-rs`。
|
||||
🔴 **后端默认只监听 `127.0.0.1`**(`BIND_ADDR` 可覆盖)—— 本仓的种子口令是 `admin/123456`、
|
||||
token 永不过期 ⇒ 默认不监听所有网卡;要在容器 / 反代里对外暴露才设 `BIND_ADDR=0.0.0.0`。
|
||||
|
||||
🔴 **`run.sh` 的 `kill_ports` 是 `kill -9`** ⇒ 它只会清 **30010** 和 **5173** 两个端口。
|
||||
**兄弟项目 `tdc-rs` 的端口不在列表里**(打死它就是破坏兄弟项目)。
|
||||
|
||||
🔴 **`dev` 会等后端真的就绪**(轮询 `/api/health`,最长 30 秒)⇒ 后端起不来(数据库路径写错等)时
|
||||
**脚本退出码 1 并打印 `.logs/backend.log` 尾部**,不会「报成功但其实没有服务」。
|
||||
此时**本次刚起的前端进程会被一并收掉**(按 PID 文件 SIGTERM → SIGKILL)⇒ **不会在 5173 上留残进程**。
|
||||
🔴 **`dev` 会等后端与前端都真的就绪**(后端轮询 `/api/health`,最长 30 秒;前端轮询 vite 根路径,最长 60 秒)
|
||||
⇒ 任一没真正起来(数据库路径写错 / 依赖没装 / 端口被占 / `npm run dev` 立刻报错退出)时,
|
||||
**脚本退出码 1** 并打印对应日志尾部(后端失败 ⇒ `.logs/backend.log`;前端失败 ⇒ `.logs/frontend.log`),
|
||||
**不会**「报成功但其实没有服务」。
|
||||
此时**本次刚起的前端进程会被一并收掉**(**PID 文件 SIGTERM → SIGKILL** + **按端口 `kill -9` 兜底**)⇒
|
||||
**不会在 5173 上留残进程**(`stop_pid` 依赖 npm 把 SIGTERM 转发给 vite —— 那是 npm 的内部实现细节、
|
||||
不是保证 ⇒ 必须有 `kill_ports` 兜底)。
|
||||
🔴 前端没就绪时**不收后端**(后端可能只是慢;下一次 `dev` / `stop` 的 `kill_ports 30010` 会自愈),
|
||||
脚本会明确提示「后端仍在 30010 上运行,要停请执行 `./run.sh stop`」。
|
||||
|
||||
🔴 **`stop` 的实际停止路径 = PID 文件(SIGTERM → 1s → SIGKILL)+ `kill_ports`(按端口 `kill -9`)**;
|
||||
`pkill` 只是最后兜底,且模式收窄到**后端本体的完整路径**
|
||||
(macOS/BSD 的 `pkill -f` 匹配**完整命令行**,宽模式会连「命令行里提到本仓名字」的无关进程一起杀掉)。
|
||||
vite 由 `kill_ports 5173` 按**端口**收 ⇒ 不会误杀别的项目的 vite dev server。
|
||||
🔴 **后端收到 SIGTERM / SIGINT 会优雅关闭**嵌入式 PostgreSQL(先收完在途请求,再正常关库)
|
||||
⇒ 不再被 SIGKILL 打断(以前每次停机都是 SIGKILL 掉嵌入式 PG ⇒ 下次启动要 crash recovery、
|
||||
数据目录里还留 `postmaster.pid`);`./run.sh stop` 的 1 秒宽限期对优雅停机足够(实测 < 200ms)。
|
||||
> ℹ️ 停机瞬间 `.logs/backend.log` 里可能出现**几十行**
|
||||
> `FATAL: terminating connection because protocol synchronization was lost` ——
|
||||
> 那是 **pglite-rs 0.2.7 的收尾噪音**(PG 收到 Terminate 后 postmaster 反复拉起后端),
|
||||
> **无害**:PG 本身是干净关库的(`postmaster.pid` 会被清掉)。
|
||||
> 后端会在 PG 干净关库后**立刻**退出(日志尾行 `tds-lite-rs 已停止(嵌入式 PostgreSQL 已优雅关闭)。`)。
|
||||
|
||||
🔴 **`backend` 子命令用 `exec`** ⇒ **后端自己的退出码原样透传**(后端 panic 时是 **101**,不是 1)。
|
||||
|
||||
@@ -93,7 +111,8 @@ vite 由 `kill_ports 5173` 按**端口**收 ⇒ 不会误杀别的项目的 vite
|
||||
|
||||
| 变量 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `PORT` | `30010` | 后端监听端口 |
|
||||
| `PORT` | `30010` | 后端监听端口(**非法值回落 30010**) |
|
||||
| `BIND_ADDR` | `127.0.0.1` | 后端监听地址 —— 🔴 **默认只监听本机**;要在容器 / 反代里对外暴露才设 `0.0.0.0`(只接受**字面 IP**,主机名会被判非法 ⇒ 回落 127.0.0.1) |
|
||||
| `PGLITE_DIR` | `<项目根>/src/backend/data/lite.pg` | 数据目录(**绝对路径**,与 cwd 无关) |
|
||||
|
||||
🔴 **`PGLITE_DIR` 只能写绝对路径**。`config.rs` 对它是**原样使用** ⇒ 相对路径会相对**当前工作目录**解析
|
||||
|
||||
@@ -8,6 +8,7 @@
|
||||
# ./run.sh install 安装依赖(cargo fetch + npm install)
|
||||
# ./run.sh build 构建(cargo build --release + vite build)
|
||||
# ./run.sh dev 后台起后端(30010) + 前端(5173),日志进 .logs/,PID 写入 .run/
|
||||
# (**后端与前端都就绪**才算成功;任一没就绪 ⇒ 退出码 1)
|
||||
# ./run.sh backend 前台起后端
|
||||
# ./run.sh frontend 前台起前端
|
||||
# ./run.sh stop 用 PID 文件停后台进程 + 兜底 kill_ports
|
||||
@@ -57,7 +58,7 @@ usage() {
|
||||
用法: ./run.sh <子命令>
|
||||
install 安装依赖(cargo fetch + npm install)
|
||||
build 构建(cargo build --release + vite build)
|
||||
dev 后台起后端(30010) + 前端(5173)
|
||||
dev 后台起后端(30010) + 前端(5173);**后端与前端都就绪**才算成功
|
||||
backend 前台起后端
|
||||
frontend 前台起前端
|
||||
stop 停止后台进程
|
||||
@@ -103,6 +104,22 @@ wait_backend_ready() {
|
||||
return 1
|
||||
}
|
||||
|
||||
# 🔴 **就绪轮询(前端)**:与 wait_backend_ready 同形,轮 vite 的根路径。
|
||||
# 超时 60 秒(比后端长):vite 首次启动要做依赖预打包,冷启动可能十几秒。
|
||||
# 没有它 ⇒ 前端 vite 起不来(依赖没装 / 端口被占 / npm run dev 立刻报错退出)时,
|
||||
# 脚本照样打印「服务已在后台启动」⇒ **脚本报成功、实际没有前端**。
|
||||
# 本机 curl 走系统代理 ⇒ 必须带 --noproxy '*'。
|
||||
wait_frontend_ready() {
|
||||
local i
|
||||
for i in $(seq 1 60); do
|
||||
if curl --noproxy '*' -fsS -m 2 "http://127.0.0.1:${FRONTEND_PORT}/" >/dev/null 2>&1; then
|
||||
return 0
|
||||
fi
|
||||
sleep 1
|
||||
done
|
||||
return 1
|
||||
}
|
||||
|
||||
# 用 PID 文件优雅停(先 SIGTERM,1s 后 SIGKILL),清理 root 进程树
|
||||
stop_pid() {
|
||||
local f="$1"
|
||||
@@ -171,15 +188,35 @@ case "${1:-}" in
|
||||
echo "[启动失败] 后端在 30 秒内没就绪(/api/health 不通)。"
|
||||
# 🔴 本次刚起的前端**一并收掉** —— 不许把一个 vite dev server 残在后台占着 5173
|
||||
# (用户看到「启动失败」,机器上却留着一个前端 dev server,极难联想到是同一次启动留下的)。
|
||||
# 用 PID 文件收(SIGTERM → 1s → SIGKILL);**不用** pkill(模式太宽会误杀别的项目)。
|
||||
# **两条都做**:`stop_pid` 走 PID 文件(SIGTERM → 1s → SIGKILL),
|
||||
# `kill_ports` 按端口 kill -9 **兜底** ——
|
||||
# 因为 `stop_pid` 依赖 npm 把 SIGTERM 转发给 vite(npm 的内部实现细节,**不是保证**),
|
||||
# 有了 `kill_ports` 兜底 ⇒「不会在 5173 上留残进程」**无条件**成立。
|
||||
# **不用** pkill(模式太宽会误杀别的项目)。
|
||||
stop_pid "$RUN/frontend.pid"
|
||||
echo " ↳ 本次刚起的前端进程已一并收掉(按 PID 文件 SIGTERM → SIGKILL)"
|
||||
kill_ports "$FRONTEND_PORT"
|
||||
echo " ↳ 本次刚起的前端进程已一并收掉(PID 文件 SIGTERM → SIGKILL + 按端口 kill -9 兜底)"
|
||||
echo "--- .logs/backend.log 尾部 ---"
|
||||
tail -n 20 "$LOGS/backend.log" 2>/dev/null || true
|
||||
exit 1
|
||||
fi
|
||||
# 🔴 就绪校验(前端):vite 起不来时同样**不许**报成功。
|
||||
if ! wait_frontend_ready; then
|
||||
echo
|
||||
echo "[启动失败] 前端在 60 秒内没就绪(http://127.0.0.1:${FRONTEND_PORT}/ 不通)。"
|
||||
# 🔴 同上:PID 文件 + 按端口兜底,两条都做 ⇒ 不在 5173 上留残进程。
|
||||
stop_pid "$RUN/frontend.pid"
|
||||
kill_ports "$FRONTEND_PORT"
|
||||
echo " ↳ 本次刚起的前端进程已一并收掉(PID 文件 SIGTERM → SIGKILL + 按端口 kill -9 兜底)"
|
||||
# 🔴 本仓既定裁决:dev 失败**不收后端**(后端可能只是慢;下一次 dev/stop 的
|
||||
# kill_ports ${BACKEND_PORT} 会自愈)⇒ 但必须把后端的去留**说清楚**。
|
||||
echo " ↳ 后端仍在 ${BACKEND_PORT} 上运行,要停请执行「./run.sh stop」"
|
||||
echo "--- .logs/frontend.log 尾部 ---"
|
||||
tail -n 20 "$LOGS/frontend.log" 2>/dev/null || true
|
||||
exit 1
|
||||
fi
|
||||
echo
|
||||
echo "服务已在后台启动。后端: http://127.0.0.1:${BACKEND_PORT} 前端: http://127.0.0.1:${FRONTEND_PORT}"
|
||||
echo "服务已在后台启动(后端与前端**都已就绪**)。后端: http://127.0.0.1:${BACKEND_PORT} 前端: http://127.0.0.1:${FRONTEND_PORT}"
|
||||
echo "日志:tail -f $LOGS/{backend,frontend}.log"
|
||||
echo "停止:./run.sh stop"
|
||||
;;
|
||||
|
||||
@@ -8,6 +8,7 @@
|
||||
//! - `static_dir` = `<project_dir>/src/frontend/dist`,**不存在则 None**(前端产物没编译出来时
|
||||
//! 不该让后端去托管一个不存在的目录)。
|
||||
|
||||
use std::net::{IpAddr, Ipv4Addr};
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
/// 后端默认端口。
|
||||
@@ -15,6 +16,13 @@ use std::path::{Path, PathBuf};
|
||||
/// 🔴 本仓固定 `:30010`;兄弟项目 `tdc-rs` 占 `:30000`,两者**不共享**任何东西。
|
||||
pub const DEFAULT_PORT: u16 = 30010;
|
||||
|
||||
/// 后端**默认监听地址** = `127.0.0.1`(**只监听本机**)。
|
||||
///
|
||||
/// 🔴 默认值朝**安全方向**:本仓的种子口令是 `admin/123456`、token 永不过期
|
||||
/// ⇒ 若默认监听所有网卡,局域网内可直接连上后端 ⇒ 必须默认只绑本机。
|
||||
/// 要在容器 / 反代里对外暴露 ⇒ 显式设 `BIND_ADDR=0.0.0.0`。
|
||||
pub const DEFAULT_BIND_ADDR: IpAddr = IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1));
|
||||
|
||||
/// `PGLITE_DIR` 设成该值 ⇒ 用**临时库**(进程退出即销毁)。
|
||||
///
|
||||
/// pglite-rs 0.2.7 **没有** 真内存模式(`memory://` 不是它的协议),
|
||||
@@ -26,6 +34,11 @@ pub const TEMP_DIR_MARKER: &str = "memory://";
|
||||
pub struct Config {
|
||||
/// HTTP 监听端口(env `PORT`,缺省或非法 ⇒ `30010`)。
|
||||
pub port: u16,
|
||||
/// HTTP 监听地址(env `BIND_ADDR`,缺省或非法 ⇒ `127.0.0.1`)。
|
||||
///
|
||||
/// 🔴 **只接受字面 IP**(`127.0.0.1` / `0.0.0.0` / `::1`)⇒ **不解析主机名**
|
||||
/// (`localhost` 会被判非法 ⇒ 回落 `127.0.0.1`,即朝安全方向回落)。
|
||||
pub bind_addr: IpAddr,
|
||||
/// pglite 数据目录(env `PGLITE_DIR`;值为 `memory://` ⇒ 临时库)。
|
||||
pub pg_dir: PathBuf,
|
||||
/// 项目根目录。
|
||||
@@ -38,6 +51,8 @@ impl Config {
|
||||
/// 从环境变量 + 传入的 `project_dir` 组装配置。
|
||||
///
|
||||
/// - `PORT`:非法值**不 panic**,回落 `30010`(配置写错不该让服务起不来)。
|
||||
/// - `BIND_ADDR`:非法值**不 panic**,回落 `127.0.0.1`(**朝安全方向**回落,
|
||||
/// 与 `PORT` 非法回落 `30010` 同一政策);**只接受字面 IP**,不解析主机名。
|
||||
/// - `PGLITE_DIR`:空串按「未设置」处理 ⇒ 用默认数据目录。
|
||||
pub fn from_env(project_dir: PathBuf) -> Config {
|
||||
let port = std::env::var("PORT")
|
||||
@@ -45,6 +60,11 @@ impl Config {
|
||||
.and_then(|v| v.trim().parse::<u16>().ok())
|
||||
.unwrap_or(DEFAULT_PORT);
|
||||
|
||||
let bind_addr = std::env::var("BIND_ADDR")
|
||||
.ok()
|
||||
.and_then(|v| v.trim().parse::<IpAddr>().ok())
|
||||
.unwrap_or(DEFAULT_BIND_ADDR);
|
||||
|
||||
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"),
|
||||
@@ -55,6 +75,7 @@ impl Config {
|
||||
|
||||
Config {
|
||||
port,
|
||||
bind_addr,
|
||||
pg_dir,
|
||||
project_dir,
|
||||
static_dir,
|
||||
@@ -88,6 +109,19 @@ mod tests {
|
||||
assert!(cfg.static_dir.is_none());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn bind_addr_defaults_to_loopback() {
|
||||
// 外部若已设置 BIND_ADDR,本断言的前提不成立 ⇒ 跳过(不改动进程环境)。
|
||||
if std::env::var("BIND_ADDR").is_ok() {
|
||||
return;
|
||||
}
|
||||
// 未设 BIND_ADDR ⇒ 只监听本机(朝安全方向回落;与 PORT 非法回落 30010 同一政策)。
|
||||
assert_eq!(DEFAULT_BIND_ADDR, IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)));
|
||||
let cfg = Config::from_env(PathBuf::from("/tmp/does-not-exist-project"));
|
||||
assert_eq!(cfg.bind_addr, DEFAULT_BIND_ADDR);
|
||||
assert!(cfg.bind_addr.is_loopback());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn pg_is_temp_detects_marker() {
|
||||
let mut cfg = Config::from_env(PathBuf::from("/tmp/x"));
|
||||
|
||||
@@ -165,6 +165,15 @@ impl Db {
|
||||
self.scalar_text_inner(sql).await
|
||||
}
|
||||
|
||||
/// 优雅关闭底层 pglite 后端(SIGTERM / SIGINT 停机路径用)。
|
||||
///
|
||||
/// 🔴 以前后端**忽略 SIGTERM** ⇒ 每次停机都是 `SIGKILL` 掉嵌入式 PostgreSQL
|
||||
/// ⇒ 下次启动要 crash recovery,数据目录里还留 `postmaster.pid`。
|
||||
/// 现在停机路径会先让 HTTP 服务收完在途请求,再调这里正常关库。
|
||||
pub async fn shutdown(&self) -> Result<(), pglite::Error> {
|
||||
self.pg.shutdown().await
|
||||
}
|
||||
|
||||
// ---- 以下为**持锁调用**的内部实现(调用方已持有 `self.lock`)----
|
||||
|
||||
async fn query_json_inner(
|
||||
|
||||
+88
-5
@@ -12,6 +12,9 @@
|
||||
//! → `with_state(state)`(**链尾**));
|
||||
//! 7. `TcpListener::bind` ⇒ 绑定失败**打印人话 + `exit 1`**(**不 panic**)。
|
||||
//!
|
||||
//! 🔴 **优雅停机**:`SIGTERM` / `SIGINT` ⇒ `with_graceful_shutdown` 收完在途请求 ⇒
|
||||
//! 优雅关闭嵌入式 PostgreSQL(不再被 `SIGKILL` 打断 ⇒ 数据目录不留 `postmaster.pid`)。
|
||||
//!
|
||||
//! 🔴 本仓**刻意不同**于 react 版(那里是 try/catch + `logger.warn` 后**继续跑**):
|
||||
//! 本仓是单二进制,启动期不变量破了就立刻退出 —— 服务要么正常起来,要么根本不起来。
|
||||
|
||||
@@ -139,6 +142,7 @@ fn print_usage() {
|
||||
println!();
|
||||
println!("环境变量:");
|
||||
println!(" PORT 监听端口(缺省 30010)");
|
||||
println!(" BIND_ADDR 监听地址(缺省 127.0.0.1 = 只监听本机;要对外暴露设 0.0.0.0)");
|
||||
println!(" PGLITE_DIR pglite 数据目录;设成 memory:// 用临时库(进程退出即销毁)");
|
||||
}
|
||||
|
||||
@@ -174,6 +178,8 @@ async fn run() -> Result<(), String> {
|
||||
db: Arc::new(db),
|
||||
sessions: Arc::new(SessionStore::new()),
|
||||
};
|
||||
// 🔴 保留一个 `Db` 句柄用于**停机时优雅关闭**嵌入式 PG(`state` 会被 `build_app` 吃掉)。
|
||||
let db_for_shutdown = state.db.clone();
|
||||
|
||||
// ---- 第 6 步:路由装配 + 三层兜底 ----
|
||||
// 🔴 装配链**只有一份**:`routes::build_app` —— S25 的顺序(`.fallback()` 在两个
|
||||
@@ -182,21 +188,98 @@ async fn run() -> Result<(), String> {
|
||||
let app = routes::build_app(state);
|
||||
|
||||
// ---- 第 7 步:绑定端口 ----
|
||||
let addr = format!("0.0.0.0:{}", config.port);
|
||||
let listener = tokio::net::TcpListener::bind(&addr)
|
||||
// 🔴 **默认只监听 127.0.0.1**(`BIND_ADDR` 可覆盖)⇒ 与「文档写的就是 127.0.0.1」一致,
|
||||
// 也避免「弱口令 + token 永不过期」的后端被局域网直接连上。
|
||||
let addr = std::net::SocketAddr::new(config.bind_addr, config.port);
|
||||
let listener = tokio::net::TcpListener::bind(addr)
|
||||
.await
|
||||
.map_err(|e| format!("绑定 {addr} 失败: {e}"))?;
|
||||
|
||||
println!(
|
||||
"tds-lite-rs {} 已启动:http://127.0.0.1:{}(数据目录 {})",
|
||||
"tds-lite-rs {} 已启动:http://{addr}(数据目录 {})",
|
||||
env!("CARGO_PKG_VERSION"),
|
||||
config.port,
|
||||
config.pg_dir.display()
|
||||
);
|
||||
|
||||
// 🔴 **优雅停机**:收到 SIGTERM / SIGINT ⇒ 先让 HTTP 服务收完在途请求,再关嵌入式 PG。
|
||||
// (以前 SIGTERM 被忽略 ⇒ 每次停机都是 SIGKILL 掉嵌入式 PostgreSQL ⇒ 下次启动要
|
||||
// crash recovery,数据目录里还留 `postmaster.pid`。)
|
||||
axum::serve(listener, app)
|
||||
.with_graceful_shutdown(shutdown_signal())
|
||||
.await
|
||||
.map_err(|e| format!("HTTP 服务异常退出: {e}"))
|
||||
.map_err(|e| format!("HTTP 服务异常退出: {e}"))?;
|
||||
|
||||
// ---- 停机:优雅关闭嵌入式 PostgreSQL ----
|
||||
// 🔴 **不 await** pglite 的关闭 future:pglite-rs 0.2.7 的 `PGlite::shutdown()` 给嵌入式 PG
|
||||
// 发完 Terminate 之后**不会返回** —— PG 的 postmaster 会进入「拉起后端 → 后端读不到
|
||||
// 完整协议 → FATAL → 再拉起」的循环(实测一次停机刷 30 多万行日志),收尾线程卡死在那儿。
|
||||
// ⇒ 另起任务去发 Terminate,同时**盯住 `postmaster.pid` 何时消失**
|
||||
// (PG 干净关库的**权威信号**)⇒ 一旦消失就立刻结束进程
|
||||
// (顺带把 pglite 那段日志噪声压到最小)。
|
||||
let shutdown_db = db_for_shutdown.clone();
|
||||
tokio::spawn(async move {
|
||||
if let Err(e) = shutdown_db.shutdown().await {
|
||||
eprintln!("[停机] 关闭嵌入式 PostgreSQL 失败: {e}");
|
||||
}
|
||||
});
|
||||
|
||||
let pid_file = config.pg_dir.join("postmaster.pid");
|
||||
let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(3);
|
||||
if pid_file.exists() {
|
||||
// 数据目录已知 ⇒ 等 `postmaster.pid` 消失(= PG 已干净关库)。
|
||||
while pid_file.exists() && tokio::time::Instant::now() < deadline {
|
||||
tokio::time::sleep(std::time::Duration::from_millis(5)).await;
|
||||
}
|
||||
} else {
|
||||
// 临时库(`PGLITE_DIR=memory://`)⇒ 数据目录路径不可知 ⇒ 退化成「固定等 200ms」
|
||||
//(实测嵌入式 PG 的干净关库只要几毫秒)。
|
||||
tokio::time::sleep(std::time::Duration::from_millis(200)).await;
|
||||
}
|
||||
|
||||
if pid_file.exists() {
|
||||
eprintln!("[停机] ⚠️ 嵌入式 PostgreSQL 未在 3 秒内干净关库(`postmaster.pid` 仍在)");
|
||||
} else {
|
||||
println!("tds-lite-rs 已停止(嵌入式 PostgreSQL 已优雅关闭)。");
|
||||
}
|
||||
// 🔴 明确结束进程:pglite 的收尾线程可能卡死 ⇒ 不能让它吊住整个进程。
|
||||
std::process::exit(0);
|
||||
}
|
||||
|
||||
/// 等待**停机信号**(SIGTERM / SIGINT)—— 任一到来即返回。
|
||||
///
|
||||
/// 🔴 **只影响关停**,不改变任何请求处理路径的行为(契约一字不改)。
|
||||
/// 🔴 tokio 的 `signal` feature 已在 workspace 的 `features = ["full"]` 里 ⇒ **不新增依赖**。
|
||||
async fn shutdown_signal() {
|
||||
#[cfg(unix)]
|
||||
{
|
||||
use tokio::signal::unix::{signal, SignalKind};
|
||||
|
||||
let mut term = match signal(SignalKind::terminate()) {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
eprintln!("[停机] 注册 SIGTERM 失败(回落 Ctrl-C):{e}");
|
||||
let _ = tokio::signal::ctrl_c().await;
|
||||
return;
|
||||
}
|
||||
};
|
||||
let mut intr = match signal(SignalKind::interrupt()) {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
eprintln!("[停机] 注册 SIGINT 失败(只等 SIGTERM):{e}");
|
||||
term.recv().await;
|
||||
return;
|
||||
}
|
||||
};
|
||||
|
||||
tokio::select! {
|
||||
_ = term.recv() => {}
|
||||
_ = intr.recv() => {}
|
||||
}
|
||||
}
|
||||
#[cfg(not(unix))]
|
||||
{
|
||||
let _ = tokio::signal::ctrl_c().await;
|
||||
}
|
||||
}
|
||||
|
||||
/// 从可执行文件向上找项目根(**与 cwd 解耦**)。
|
||||
|
||||
+98
-19
@@ -1,4 +1,4 @@
|
||||
//! routes —— 路由装配 + 三层兜底(404 / 405 / catch-all)。
|
||||
//! routes —— 路由装配 + 三层兜底(404 / 405 / 413 改写 / catch-all)。
|
||||
//!
|
||||
//! 契约:`docs/contract.md` §9(`routes.rs` 接口)、§6.5(兜底三条)、§R1.2(业务失败恒 HTTP 200)。
|
||||
//!
|
||||
@@ -7,12 +7,12 @@
|
||||
//! build_app(state) // ← 生产(main.rs)与单测都调它
|
||||
//! build_router(state.clone())
|
||||
//! .fallback(not_found_handler) // 404 兜底
|
||||
//! .layer(m405_rewrite()) // 405 改写中间件
|
||||
//! .layer(m_status_rewrite()) // 405 / 413 改写中间件
|
||||
//! .layer(catch_all()) // panic 捕获中间件
|
||||
//! .with_state(state) // ← 链尾(唯一一次把类型落成 Router<()>)
|
||||
//! ```
|
||||
//! `Router::layer` 是**后进先出** ⇒ 最后挂的最外层 ⇒ 请求**先**撞 `catch_all`,
|
||||
//! **再**撞 `m405_rewrite`,**最后**才进 handler / 404 兜底。
|
||||
//! **再**撞 `m_status_rewrite`,**最后**才进 handler / 404 兜底。
|
||||
//!
|
||||
//! 🔴 `.fallback(...)` 必须写在两个 `.layer(...)` **之前** —— axum 官方文档原话:
|
||||
//! 「the middleware is only applied to existing routes. So you have to first add your
|
||||
@@ -138,7 +138,7 @@ pub fn build_router(state: AppState) -> axum::Router<AppState> {
|
||||
pub fn build_app(state: AppState) -> axum::Router {
|
||||
build_router(state.clone())
|
||||
.fallback(not_found_handler)
|
||||
.layer(m405_rewrite())
|
||||
.layer(m_status_rewrite())
|
||||
.layer(catch_all())
|
||||
.with_state(state)
|
||||
}
|
||||
@@ -174,7 +174,7 @@ pub async fn not_found_handler() -> (StatusCode, Json<ActionResult>) {
|
||||
(StatusCode::NOT_FOUND, Json(envelope::fail(404, "接口不存在").0))
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------- 405 改写中间件
|
||||
// ---------------------------------------------------------------- 405 / 413 改写中间件
|
||||
|
||||
/// 中间件 future 的统一类型(boxed ⇒ 可命名 ⇒ 工厂函数的返回类型能写死)。
|
||||
type MwFuture = Pin<Box<dyn Future<Output = Response> + Send>>;
|
||||
@@ -182,36 +182,42 @@ type MwFuture = Pin<Box<dyn Future<Output = Response> + Send>>;
|
||||
/// 中间件函数指针类型(fn 指针可命名 ⇒ 工厂函数的返回类型能写死)。
|
||||
type MwFn = fn(Request, Next) -> MwFuture;
|
||||
|
||||
/// 405 改写中间件(挂在链尾的响应改写层)。
|
||||
/// 405 / 413 改写中间件(挂在链尾的响应改写层)。
|
||||
///
|
||||
/// - **任何 405 都改写**成信封 body(契约 §6.5:405 ⇒ HTTP 405 +
|
||||
/// `{code:405,msg:"方法不被允许",data:null}`)—— 🔴 **不看 body 是否为空**:
|
||||
/// 「万一有 body 的 405 漏出非信封 body」是唯一的破口,不能留;
|
||||
/// - **任何 413 都改写**成信封 body(传输状态码**保留** HTTP 413,body 换成
|
||||
/// `{code:413,msg:"请求体过大",data:null}`)—— 改写前 axum 默认吐的是
|
||||
/// `text/plain` 的 `Failed to buffer the request body: length limit exceeded`
|
||||
/// ⇒ 服务端会冒出**第三种 body 形状**(契约 §2「没有第三种形状」的破口);
|
||||
/// - **保留 `parts.headers`**(保住 `Allow` 头);
|
||||
/// - 改写 `Content-Length`,body 换成 `{code:405,msg:"方法不被允许",data:null}`。
|
||||
/// - 改写 `Content-Type` / `Content-Length`,body 换成对应信封。
|
||||
///
|
||||
/// 🔴 **非 405 响应原样放行**(不改写)。
|
||||
/// 🔴 **非 405 / 非 413 的响应原样放行**(不改写)。
|
||||
/// 🔴 **不要**用 axum 的 `method_not_allowed_fallback` —— 它只对「调用那一刻已注册的路由」
|
||||
/// 生效,且**丢 `Allow` 头**。
|
||||
pub fn m405_rewrite() -> axum::middleware::FromFnLayer<MwFn, (), (Request,)> {
|
||||
axum::middleware::from_fn::<_, (Request,)>(m405_rewrite_fn)
|
||||
pub fn m_status_rewrite() -> axum::middleware::FromFnLayer<MwFn, (), (Request,)> {
|
||||
axum::middleware::from_fn::<_, (Request,)>(m_status_rewrite_fn)
|
||||
}
|
||||
|
||||
fn m405_rewrite_fn(req: Request, next: Next) -> MwFuture {
|
||||
Box::pin(m405_rewrite_inner(req, next))
|
||||
fn m_status_rewrite_fn(req: Request, next: Next) -> MwFuture {
|
||||
Box::pin(m_status_rewrite_inner(req, next))
|
||||
}
|
||||
|
||||
async fn m405_rewrite_inner(req: Request, next: Next) -> Response {
|
||||
async fn m_status_rewrite_inner(req: Request, next: Next) -> Response {
|
||||
let res = next.run(req).await;
|
||||
|
||||
// 只处理 405(非 405 原样放行)。
|
||||
if res.status() != StatusCode::METHOD_NOT_ALLOWED {
|
||||
return res;
|
||||
}
|
||||
// 🔴 **任何 405 都改写**(不看 body 是否为空)—— 契约 §6.5 要求 405 恒是信封 body。
|
||||
// 只处理 405 / 413(其它状态码原样放行)。
|
||||
let (code, msg) = match res.status() {
|
||||
StatusCode::METHOD_NOT_ALLOWED => (405, "方法不被允许"),
|
||||
StatusCode::PAYLOAD_TOO_LARGE => (413, "请求体过大"),
|
||||
_ => return res,
|
||||
};
|
||||
// 🔴 **任何 405 / 413 都改写**(不看 body 是否为空)—— 契约要求这两类恒是信封 body。
|
||||
|
||||
// 🔴 `serde_json::to_vec` 对本结构体恒成功;真失败 ⇒ 保留原响应(不冒险改坏)。
|
||||
let Ok(bytes) = serde_json::to_vec(&envelope::fail(405, "方法不被允许").0) else {
|
||||
let Ok(bytes) = serde_json::to_vec(&envelope::fail(code, msg).0) else {
|
||||
return res;
|
||||
};
|
||||
|
||||
@@ -355,6 +361,38 @@ mod tests {
|
||||
String::from_utf8_lossy(&buf).to_string()
|
||||
}
|
||||
|
||||
/// 发一个**超大 body** 的 POST,返回完整原始响应(头 + 体)。
|
||||
///
|
||||
/// 🔴 写 / 读的错误**必须容忍**:服务端判定 body 超限后会**立刻回 413**,
|
||||
/// 并且**不再继续读**请求体 ⇒ 若客户端多写了,socket 上有未读数据 ⇒
|
||||
/// 服务端只能 RST(这正是真实客户端 curl 会看到的形态)。
|
||||
/// ⇒ 这里把 body 控制在「**刚好超过上限 1 字节**」,
|
||||
/// 让服务端把 body 全部读走 ⇒ 干净 FIN ⇒ 响应能完整读到。
|
||||
async fn raw_oversized(port: u16, request: &str) -> String {
|
||||
let mut stream = tokio::net::TcpStream::connect(("127.0.0.1", port))
|
||||
.await
|
||||
.expect("连接失败");
|
||||
let _ = stream.write_all(request.as_bytes()).await;
|
||||
let _ = stream.flush().await;
|
||||
let mut buf = Vec::new();
|
||||
let mut tmp = [0u8; 16 * 1024];
|
||||
// 收尾读:容忍 `ECONNRESET`(服务端 RST)—— 已读到的字节照样能用。
|
||||
loop {
|
||||
match tokio::time::timeout(
|
||||
std::time::Duration::from_secs(2),
|
||||
stream.read(&mut tmp),
|
||||
)
|
||||
.await
|
||||
{
|
||||
Ok(Ok(0)) => break,
|
||||
Ok(Ok(n)) => buf.extend_from_slice(&tmp[..n]),
|
||||
Ok(Err(_)) => break,
|
||||
Err(_) => break,
|
||||
}
|
||||
}
|
||||
String::from_utf8_lossy(&buf).to_string()
|
||||
}
|
||||
|
||||
fn get(path: &str) -> String {
|
||||
format!("GET {path} HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n")
|
||||
}
|
||||
@@ -402,6 +440,47 @@ mod tests {
|
||||
assert_eq!(body["data"], Value::Null);
|
||||
}
|
||||
|
||||
/// 🔴 **超大 body ⇒ HTTP 413 + 信封**(契约 §2「没有第三种形状」)。
|
||||
///
|
||||
/// axum 的默认 body 上限是 2MB ⇒ 这里发**刚好超过 1 字节**的 JSON。
|
||||
/// 改写前服务端会吐 `text/plain` 的 `Failed to buffer the request body: length limit exceeded`
|
||||
/// ⇒ 那就是**第三种 body 形状** ⇒ 必须被归一成信封。
|
||||
#[tokio::test]
|
||||
async fn oversized_body_returns_http_413_with_envelope() {
|
||||
let port = serve(new_state(db().await)).await;
|
||||
// axum 默认 body 上限 = 2MB(2*1024*1024 字节)⇒ 这里发**刚好超过 1 字节**的 JSON。
|
||||
// 🔴 刻意不做「远远超过」:多写的字节服务端不会读 ⇒ socket 残留未读数据 ⇒ RST ⇒ 响应读不全。
|
||||
const LIMIT: usize = 2 * 1024 * 1024;
|
||||
let prefix = "{\"account\":\"big_user\",\"password\":\"x\",\"realName\":\"";
|
||||
let suffix = "\"}";
|
||||
let padding = "a".repeat(LIMIT + 1 - prefix.len() - suffix.len());
|
||||
let payload = format!("{prefix}{padding}{suffix}");
|
||||
assert_eq!(payload.len(), LIMIT + 1);
|
||||
let req = format!(
|
||||
"POST /api/ssw/sys/User/Save HTTP/1.1\r\nHost: localhost\r\n\
|
||||
Content-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
|
||||
payload.len(),
|
||||
payload
|
||||
);
|
||||
let raw = raw_oversized(port, &req).await;
|
||||
|
||||
assert!(
|
||||
raw.starts_with("HTTP/1.1 413 Payload Too Large"),
|
||||
"超大 body 必须是 HTTP 413,实际: {}",
|
||||
&raw[..raw.len().min(400)]
|
||||
);
|
||||
let (head, body) = raw.split_once("\r\n\r\n").expect("响应必须有头体分隔");
|
||||
assert!(
|
||||
head.to_ascii_lowercase()
|
||||
.contains("content-type: application/json"),
|
||||
"413 必须是 JSON 信封,实际头: {head}"
|
||||
);
|
||||
let body: Value = serde_json::from_str(body).expect("响应体必须是合法 JSON");
|
||||
assert_eq!(body["code"], 413);
|
||||
assert_eq!(body["msg"], "请求体过大");
|
||||
assert_eq!(body["data"], Value::Null);
|
||||
}
|
||||
|
||||
/// 🔴 **路由表钉子测试** —— 27 条路径一条都不许少、一条都不许拼错。
|
||||
///
|
||||
/// 用「错方法 ⇒ 405」当作「这条路径确实注册了」的探针(比逐条调真接口便宜,
|
||||
|
||||
Reference in new issue
Block a user