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:
1 parent
b21b9448da
commit
c906b7d8e8
2 files changed
+244
-44
No files matched your search
+122
-20
@@ -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
@@ -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() {
|
||||
|
||||
Reference in new issue
Block a user