refactor(routes): 装配链单一真源 + 405 无条件改写 + 子命令退出码可测 + 路由表钉子测试

必改 1:新增 routes::build_app(state) -> Router 作为**唯一权威的装配链**
(build_router → .fallback(404 兜底) → .layer(405 改写) → .layer(catch-all)
→ .with_state 链尾)。main.rs 第 6 步与 routes.rs 的测试辅助都只调它,
那条链在仓库里只剩一份 ⇒ 改顺序时生产与测试一起变。
build_router 的签名一个字未改(仍收 state、仍返回 Router<AppState>)。

必改 2:405 改写中间件**无条件**改写任何 405(不再看 body 是否为空),
杜绝「有 body 的 405 漏出非信封 body」这个唯一破口;非 405 原样放行。

必改 3:build_router 的文档注释改为如实说明——内部那次 with_state 是类型
层面的 no-op,真正喂状态给 handler 的是链尾那次;两次拿到的是同一个
AppState 的两个 clone,而三个字段全是 Arc ⇒ 共享同一份底层状态。

必改 4:子命令解析抽成纯函数 parse_args(&[String]) -> Cmd + exit_code(&Cmd)
(不读环境变量、不退出进程),补 6 条单测覆盖每种 args 的退出码:
--enc 0 / --enc 缺参 2 / --help 0 / -h 0 / 未知参数 2 / 无参 = Serve。

必改 5:补两条测试——路由表钉子测试(27 条路径逐条用「错方法 ⇒ 405」探测,
外加一条未注册路径 ⇒ 404)与「非 405 响应原样穿过改写中间件」。

未动:sys.rs / crud.rs / entities.rs / auth.rs / db.rs / config.rs /
envelope.rs / seed.rs / state.rs / lib.rs / Cargo.toml / docs/contract.md /
scripts/ / src/frontend/ / db/schema.sql / src/backend/tests/;未加任何依赖。

Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
adminandClaude Code committed 2026-10-26 02:05:48 +08:00
1 parent b21b9448da
commit c906b7d8e8
2 files changed
+244 -44

No files matched your search

+122 -20
View File
@@ -44,31 +44,78 @@ const EXPECTED_TABLES: [&str; 10] = [
"book_shop_book",
];
/// 命令行解析的结果(**纯数据**,便于单测)。
#[derive(Debug, Clone, PartialEq, Eq)]
enum Cmd {
/// `--enc <明文>` ⇒ 打印 hex 到 stdout,退出码 **0**。
Enc(String),
/// `--enc` **缺明文** ⇒ 用法错,退出码 **2**(且必须有人话提示)。
EncMissing,
/// `--help` / `-h` ⇒ 打印用法,退出码 **0**。
Help,
/// 未知参数 ⇒ 用法错,退出码 **2**。
Unknown(String),
/// 无参数 ⇒ 起服务。
Serve,
}
/// 解析命令行参数(**纯函数**:不读环境变量、不退出进程、不打日志)。
///
/// 🔴 语义逐字照搬契约 §10 的子命令条:
/// - `["--enc", <明文>]` ⇒ `Cmd::Enc`(退出码 0);
/// - `["--enc"]`(缺明文)⇒ `Cmd::EncMissing`(退出码 2 + 人话提示);
/// - `["--help"]` / `["-h"]` ⇒ `Cmd::Help`(退出码 0);
/// - `["<其它>"]` ⇒ `Cmd::Unknown`(退出码 2);
/// - `[]` ⇒ `Cmd::Serve`。
fn parse_args(args: &[String]) -> Cmd {
match args.first().map(String::as_str) {
Some("--enc") => match args.get(1) {
Some(plain) => Cmd::Enc(plain.clone()),
None => Cmd::EncMissing,
},
Some("--help") | Some("-h") => Cmd::Help,
Some(other) => Cmd::Unknown(other.to_string()),
None => Cmd::Serve,
}
}
/// 子命令的**退出码**(纯函数 ⇒ 可单测)。
///
/// 🔴 `Cmd::Serve` ⇒ 0:起服务**不因用法出错而退出**(实际不会调用 `exit`)。
fn exit_code(cmd: &Cmd) -> i32 {
match cmd {
Cmd::Enc(_) | Cmd::Help => 0,
Cmd::EncMissing | Cmd::Unknown(_) => 2,
Cmd::Serve => 0,
}
}
#[tokio::main]
async fn main() {
let args: Vec<String> = std::env::args().skip(1).collect();
let cmd = parse_args(&args);
match args.first().map(String::as_str) {
match &cmd {
// `--enc <明文>` ⇒ 打印 hex 到 stdout,退出码 0(冒烟脚本用它自证 cipher,不依赖 node)。
Some("--enc") => {
let Some(plain) = args.get(1) else {
eprintln!("--enc 需要一个明文参数");
print_usage();
std::process::exit(2);
};
Cmd::Enc(plain) => {
println!("{}", cipher::encrypt_password(plain));
return;
std::process::exit(exit_code(&cmd));
}
Some("--help") | Some("-h") => {
Cmd::EncMissing => {
eprintln!("--enc 需要一个明文参数");
print_usage();
return;
std::process::exit(exit_code(&cmd));
}
Some(other) => {
Cmd::Help => {
print_usage();
std::process::exit(exit_code(&cmd));
}
Cmd::Unknown(other) => {
eprintln!("未知参数: {other}");
print_usage();
std::process::exit(2);
std::process::exit(exit_code(&cmd));
}
None => {}
Cmd::Serve => {}
}
if let Err(msg) = run().await {
@@ -128,13 +175,10 @@ async fn run() -> Result<(), String> {
};
// ---- 第 6 步:路由装配 + 三层兜底 ----
// 🔴 顺序见控制器裁决 S25:`.fallback()` 在两个 `.layer()` **之前**;
// `.with_state()` 是**链尾**(唯一一次把类型落成 `Router<()>`)。
let app = routes::build_router(state.clone())
.fallback(routes::not_found_handler)
.layer(routes::m405_rewrite())
.layer(routes::catch_all())
.with_state(state);
// 🔴 装配链**只有一份**:`routes::build_app` —— S25 的顺序(`.fallback()` 在两个
// `.layer()` **之前**、`.with_state()` 是**链尾**)就写在那儿。
// 生产与单测走**同一条路** ⇒ 以后改顺序,两边一起变。
let app = routes::build_app(state);
// ---- 第 7 步:绑定端口 ----
let addr = format!("0.0.0.0:{}", config.port);
@@ -225,3 +269,61 @@ async fn open_db(config: &Config) -> Result<Db, pglite::Error> {
Db::open(&config.pg_dir).await
}
}
#[cfg(test)]
mod tests {
use super::*;
fn args(list: &[&str]) -> Vec<String> {
list.iter().map(|s| s.to_string()).collect()
}
/// `--enc <明文>` ⇒ `Cmd::Enc` + 退出码 **0**。
#[test]
fn enc_with_plaintext_exits_zero() {
let cmd = parse_args(&args(&["--enc", "123456"]));
assert_eq!(cmd, Cmd::Enc("123456".to_string()));
assert_eq!(exit_code(&cmd), 0);
}
/// `--enc` **缺明文** ⇒ 用法错 ⇒ 退出码 **2**(不是 0,也不是 1)。
#[test]
fn enc_without_plaintext_exits_two() {
let cmd = parse_args(&args(&["--enc"]));
assert_eq!(cmd, Cmd::EncMissing);
assert_eq!(exit_code(&cmd), 2);
}
/// `--help` / `-h` ⇒ `Cmd::Help` + 退出码 **0**。
#[test]
fn help_variants_exit_zero() {
for flag in ["--help", "-h"] {
let cmd = parse_args(&args(&[flag]));
assert_eq!(cmd, Cmd::Help, "flag {flag} 必须是 Help");
assert_eq!(exit_code(&cmd), 0, "flag {flag} 必须退出码 0");
}
}
/// 未知参数 ⇒ 用法错 ⇒ 退出码 **2**。
#[test]
fn unknown_flag_exits_two() {
let cmd = parse_args(&args(&["--bogus"]));
assert_eq!(cmd, Cmd::Unknown("--bogus".to_string()));
assert_eq!(exit_code(&cmd), 2);
}
/// 无参数 ⇒ **起服务**(不是退出码)。
#[test]
fn empty_args_mean_serve() {
assert_eq!(parse_args(&args(&[])), Cmd::Serve);
}
/// 🔴 解析是**纯函数** —— 同一个 args 反复解析结果恒等(不依赖环境变量 / 进程状态)。
#[test]
fn parse_args_is_pure() {
let a = args(&["--enc", "123456"]);
let b = a.clone();
assert_eq!(parse_args(&a), parse_args(&b));
assert_eq!(parse_args(&a), Cmd::Enc("123456".to_string()));
}
}
+122 -24
View File
@@ -2,13 +2,14 @@
//!
//! 契约:`docs/contract.md` §9(`routes.rs` 接口)、§6.5(兜底三条)、§R1.2(业务失败恒 HTTP 200)。
//!
//! 🔴 **三层兜底的挂法**(控制器裁决 S25)—— `main.rs` 按这个顺序装配:
//! 🔴 **三层兜底的挂法**(控制器裁决 S25)—— **唯一真源**是 [`build_app`]:
//! ```text
//! build_router(state)
//! .fallback(not_found_handler) // 404 兜底
//! .layer(m405_rewrite()) // 405 改写中间件
//! .layer(catch_all()) // panic 捕获中间件
//! .with_state(state) // ← 链尾(唯一一次把类型落成 Router<()>)
//! build_app(state) // ← 生产(main.rs)与单测都调它
//! build_router(state.clone())
//! .fallback(not_found_handler) // 404 兜底
//! .layer(m405_rewrite()) // 405 改写中间件
//! .layer(catch_all()) // panic 捕获中间件
//! .with_state(state) // ← 链尾(唯一一次把类型落成 Router<()>)
//! ```
//! `Router::layer` 是**后进先出** ⇒ 最后挂的最外层 ⇒ 请求**先**撞 `catch_all`,
//! **再**撞 `m405_rewrite`,**最后**才进 handler / 404 兜底。
@@ -28,7 +29,7 @@ use std::panic::{catch_unwind, AssertUnwindSafe};
use std::pin::Pin;
use std::task::{Context, Poll};
use axum::body::{Body, HttpBody};
use axum::body::Body;
use axum::extract::{Request, State};
use axum::http::{header, HeaderMap, HeaderValue, StatusCode};
use axum::middleware::Next;
@@ -53,12 +54,17 @@ async fn panic_handler() -> Json<ActionResult> {
/// 装配全部路由(27 条,见 S15 的路由表)。
///
/// 🔴 **不在这里终结状态** —— 契约 §9 的括注与 §10 第 6 步都要求
/// `with_state` 由 `main.rs` 在**链尾**调用(axum 0.8 的 `Router<S>` 的 `S`
/// `with_state` 由调用方在**链尾**调用(axum 0.8 的 `Router<S>` 的 `S`
/// 是「还缺什么状态」,`with_state` 必须是**链条最后一步**)。
/// ⇒ **完整的装配链只有一份**,在 [`build_app`](生产与单测都调它)。
///
/// 这里末尾的 `.with_state(state)` 只是为了让契约 §9 的 `state` 参数**有去处**
/// (否则 `unused_variables` warning ⇒ 验收门① 破);`S2` 显式落在 `AppState`
/// ⇒ 返回类型仍是 `Router<AppState>`,**没有**终结状态。
/// 这里末尾的 `.with_state(state)` 是**类型层面**的 no-op(`S2` 显式落在 `AppState`
/// ⇒ 返回类型仍是 `Router<AppState>`):它只是让契约 §9 的 `state` 参数**有去处**
/// (否则 `unused_variables` warning ⇒ 验收门① 破),**并不**把状态喂给 handler。
/// 🔴 **真正把状态喂给 handler 的是链尾那次 `with_state`**(在 [`build_app`] 里)。
/// 🔴 两次拿到的是**同一个 `AppState` 的两个 clone** —— 而 `AppState` 的三个字段
/// (`config` / `db` / `sessions`)**全是 `Arc`** ⇒ 两份 clone **共享同一份底层状态**
/// ⇒ 行为完全等价,**不是**两个独立状态。
pub fn build_router(state: AppState) -> axum::Router<AppState> {
let router = Router::new()
// ---- 探活(§6.5 末条,非契约)----
@@ -120,6 +126,23 @@ pub fn build_router(state: AppState) -> axum::Router<AppState> {
router.with_state(state)
}
/// 完整装配(**唯一权威的装配链**)—— 生产(`main.rs`)与单测**都调它**。
///
/// 🔴 顺序即 S25 的要害:`.fallback()` 必须在两个 `.layer()` **之前**
/// (axum:`layer` 只作用于**已注册**的路由)⇒ 否则 404 兜底不在中间件保护范围内。
/// `.layer()` 是 per-route 的 ⇒ **最后挂的最外层** ⇒ 请求先撞 catch-all。
/// 🔴 `with_state` 是**链尾**(唯一一次把类型落成 `Router<()>`)。
///
/// 🔴 **这条链在仓库里只有这一份** —— 生产与测试共用 ⇒ 改顺序时两边一起变,
/// 测试永远钉得住(不要在 `main.rs` 或测试里再抄一遍)。
pub fn build_app(state: AppState) -> axum::Router {
build_router(state.clone())
.fallback(not_found_handler)
.layer(m405_rewrite())
.layer(catch_all())
.with_state(state)
}
/// `GET /api/health` —— 探活(契约 §6.5 末条,**非契约**)。
///
/// 🔴 **永远要有响应**:查不到表 / DB 报错 ⇒ 仍然 HTTP 200 + `{"ok": false, "tables": 0, …}`
@@ -161,11 +184,13 @@ type MwFn = fn(Request, Next) -> MwFuture;
/// 405 改写中间件(挂在链尾的响应改写层)。
///
/// - 只改写 **405 且 body 为空** 的响应(axum 的 `MethodRouter` 方法不匹配时
/// 给的就是 405 + `Allow` 头 + 空 body ⇒ 正合适);
/// - **任何 405 都改写**成信封 body(契约 §6.5:405 ⇒ HTTP 405 +
/// `{code:405,msg:"方法不被允许",data:null}`)—— 🔴 **不看 body 是否为空**:
/// 「万一有 body 的 405 漏出非信封 body」是唯一的破口,不能留;
/// - **保留 `parts.headers`**(保住 `Allow` 头);
/// - 改写 `Content-Length`,body 换成 `{code:405,msg:"方法不被允许",data:null}`。
///
/// 🔴 **非 405 响应原样放行**(不改写)。
/// 🔴 **不要**用 axum 的 `method_not_allowed_fallback` —— 它只对「调用那一刻已注册的路由」
/// 生效,且**丢 `Allow` 头**。
pub fn m405_rewrite() -> axum::middleware::FromFnLayer<MwFn, (), (Request,)> {
@@ -179,14 +204,11 @@ fn m405_rewrite_fn(req: Request, next: Next) -> MwFuture {
async fn m405_rewrite_inner(req: Request, next: Next) -> Response {
let res = next.run(req).await;
// 只处理 405。
// 只处理 405(非 405 原样放行)。
if res.status() != StatusCode::METHOD_NOT_ALLOWED {
return res;
}
// 只处理「body 为空」的 405(有 body 的不动)。
if res.body().size_hint().exact() != Some(0) {
return res;
}
// 🔴 **任何 405 都改写**(不看 body 是否为空)—— 契约 §6.5 要求 405 恒是信封 body。
// 🔴 `serde_json::to_vec` 对本结构体恒成功;真失败 ⇒ 保留原响应(不冒险改坏)。
let Ok(bytes) = serde_json::to_vec(&envelope::fail(405, "方法不被允许").0) else {
@@ -293,13 +315,9 @@ mod tests {
}
}
/// 按 `main.rs` 的装配顺序造出完整 app(**含三层兜底**)。
/// 按**生产同一条链**造出完整 app(🔴 唯一真源 = [`build_app`],不在测试里抄一遍)。
fn app(state: AppState) -> Router {
build_router(state.clone())
.fallback(not_found_handler)
.layer(m405_rewrite())
.layer(catch_all())
.with_state(state)
build_app(state)
}
/// 起一个真实的 HTTP 服务(随机端口),返回端口号。
@@ -341,6 +359,11 @@ mod tests {
format!("GET {path} HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n")
}
/// 「错方法」探针用(本仓**没有任何**路由注册 `PATCH` ⇒ 必然方法不匹配)。
fn patch(path: &str) -> String {
format!("PATCH {path} HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n")
}
/// 未注册的路径 ⇒ **HTTP 404** + `{code:404,msg:"接口不存在",data:null}`。
#[tokio::test]
async fn unknown_route_returns_http_404_with_envelope() {
@@ -379,6 +402,81 @@ mod tests {
assert_eq!(body["data"], Value::Null);
}
/// 🔴 **路由表钉子测试** —— 27 条路径一条都不许少、一条都不许拼错。
///
/// 用「错方法 ⇒ 405」当作「这条路径确实注册了」的探针(比逐条调真接口便宜,
/// 且不依赖鉴权 / 数据);路径没注册 ⇒ 404。
#[tokio::test]
async fn route_table_is_pinned() {
let port = serve(new_state(db().await)).await;
/// 27 条已注册路径(照抄 [`build_router`] 的注册表,逐字)。
const REGISTERED: [&str; 27] = [
"/api/health",
"/api/oauth/Login",
"/api/oauth/CurrentUser",
"/api/ssw/sys/User/List",
"/api/ssw/sys/User/Save",
"/api/ssw/sys/User/Delete",
"/api/ssw/sys/Role/List",
"/api/ssw/sys/Role/Save",
"/api/ssw/sys/Role/Delete",
"/api/ssw/sys/Role/Modules",
"/api/ssw/sys/Organize/List",
"/api/ssw/sys/Organize/Save",
"/api/ssw/sys/Organize/Delete",
"/api/ssw/sys/Module/List",
"/api/ssw/sys/Module/Save",
"/api/ssw/sys/Module/Delete",
"/api/permission/Authority/Data/any-id",
"/api/permission/Authority/RoleModules",
"/api/ssw/demo/DemoItem/List",
"/api/ssw/demo/DemoItem/Save",
"/api/ssw/demo/DemoItem/Delete",
"/api/ssw/shop/Product/List",
"/api/ssw/shop/Product/Save",
"/api/ssw/shop/Product/Delete",
"/api/ssw/books/Book/List",
"/api/ssw/books/Book/Save",
"/api/ssw/books/Book/Delete",
];
for path in REGISTERED {
let raw = raw(port, &patch(path)).await;
assert!(
raw.starts_with("HTTP/1.1 405 Method Not Allowed"),
"路由表必须包含 {path}(方法不对 ⇒ 405),实际: {raw}"
);
}
// 没注册过的路径 ⇒ 404(把「404 兜底」也钉在这条测试里)。
let raw = raw(port, &patch("/api/__nope__/xyz")).await;
assert!(
raw.starts_with("HTTP/1.1 404 Not Found"),
"未注册的路径必须是 404,实际: {raw}"
);
}
/// 🔴 **非 405 响应原样穿过改写中间件**(状态 200 + 信封 + `application/json`)。
#[tokio::test]
async fn non_405_response_passes_through_untouched() {
let port = serve(new_state(db().await)).await;
let raw = raw(port, &get("/api/health")).await;
assert!(
raw.starts_with("HTTP/1.1 200 OK"),
"健康检查必须返回 200,实际: {raw}"
);
let (head, body) = raw.split_once("\r\n\r\n").expect("响应必须有头体分隔");
assert!(
head.to_ascii_lowercase()
.contains("content-type: application/json"),
"健康检查必须返回 JSON,实际头: {head}"
);
let body: Value = serde_json::from_str(body).expect("响应体必须是合法 JSON");
assert_eq!(body["ok"], true);
}
/// panic ⇒ **HTTP 200** + `{code:400,msg:"系统异常,请联系管理员",data:null}`。
#[tokio::test]
async fn panic_is_converted_to_http_200_code_400() {