From c906b7d8e8cd84feeb9bf6df246056a7773c08e2 Mon Sep 17 00:00:00 2001 From: admin Date: Mon, 26 Oct 2026 02:05:48 +0800 Subject: [PATCH] =?UTF-8?q?refactor(routes):=20=E8=A3=85=E9=85=8D=E9=93=BE?= =?UTF-8?q?=E5=8D=95=E4=B8=80=E7=9C=9F=E6=BA=90=20+=20405=20=E6=97=A0?= =?UTF-8?q?=E6=9D=A1=E4=BB=B6=E6=94=B9=E5=86=99=20+=20=E5=AD=90=E5=91=BD?= =?UTF-8?q?=E4=BB=A4=E9=80=80=E5=87=BA=E7=A0=81=E5=8F=AF=E6=B5=8B=20+=20?= =?UTF-8?q?=E8=B7=AF=E7=94=B1=E8=A1=A8=E9=92=89=E5=AD=90=E6=B5=8B=E8=AF=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 必改 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)。 必改 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 --- src/backend/src/main.rs | 142 ++++++++++++++++++++++++++++++------ src/backend/src/routes.rs | 146 +++++++++++++++++++++++++++++++------- 2 files changed, 244 insertions(+), 44 deletions(-) diff --git a/src/backend/src/main.rs b/src/backend/src/main.rs index bc0b367..10847b3 100644 --- a/src/backend/src/main.rs +++ b/src/backend/src/main.rs @@ -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 = 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::open(&config.pg_dir).await } } + +#[cfg(test)] +mod tests { + use super::*; + + fn args(list: &[&str]) -> Vec { + 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())); + } +} diff --git a/src/backend/src/routes.rs b/src/backend/src/routes.rs index 231ae72..24e3e35 100644 --- a/src/backend/src/routes.rs +++ b/src/backend/src/routes.rs @@ -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 { /// 装配全部路由(27 条,见 S15 的路由表)。 /// /// 🔴 **不在这里终结状态** —— 契约 §9 的括注与 §10 第 6 步都要求 -/// `with_state` 由 `main.rs` 在**链尾**调用(axum 0.8 的 `Router` 的 `S` +/// `with_state` 由调用方在**链尾**调用(axum 0.8 的 `Router` 的 `S` /// 是「还缺什么状态」,`with_state` 必须是**链条最后一步**)。 +/// ⇒ **完整的装配链只有一份**,在 [`build_app`](生产与单测都调它)。 /// -/// 这里末尾的 `.with_state(state)` 只是为了让契约 §9 的 `state` 参数**有去处** -/// (否则 `unused_variables` warning ⇒ 验收门① 破);`S2` 显式落在 `AppState` -/// ⇒ 返回类型仍是 `Router`,**没有**终结状态。 +/// 这里末尾的 `.with_state(state)` 是**类型层面**的 no-op(`S2` 显式落在 `AppState` +/// ⇒ 返回类型仍是 `Router`):它只是让契约 §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 { let router = Router::new() // ---- 探活(§6.5 末条,非契约)---- @@ -120,6 +126,23 @@ pub fn build_router(state: AppState) -> axum::Router { 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 { @@ -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() {