From 0de161ddeffe5521f8c19a9eacf26c3a9f05f665 Mon Sep 17 00:00:00 2001 From: admin Date: Sun, 25 Oct 2026 17:31:49 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=20panic=20=E5=85=9C=E5=BA=95?= =?UTF-8?q?=E4=BF=A1=E5=B0=81=E4=B8=8E=20405=20=E4=BC=A0=E8=BE=93=E5=B1=82?= =?UTF-8?q?=E7=8A=B6=E6=80=81=E7=A0=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - R1.2 / §6.5 / §10:未捕获异常(panic / DB 报错)⇒ HTTP 200 + code=400 + msg='系统异常,请联系管理员'(对齐 react 全局 ActionResultFilter 兜底) - §6.5:405 定死为 HTTP 405 + {code:405,...},保留 Allow 头; 未知路由仍是唯一的 404 传输层例外 - §10 第 6 步:链尾加 catch-all 中间件(不能漏出 axum 默认 500 空 body) Co-Authored-By: Claude Code --- docs/contract.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/contract.md b/docs/contract.md index b56530b..d9a89b9 100644 --- a/docs/contract.md +++ b/docs/contract.md @@ -25,7 +25,10 @@ - 业务失败:`code=400`,`data=null`,`msg` 透传业务提示 - 未登录:`code=600`,`msg='未登录'` - 无菜单权限:`code=403`,`msg='无菜单权限'` +- 未捕获异常(panic / DB 报错)⇒ 同样 **HTTP 200** + `{code:400,msg:'系统异常,请联系管理员',data:null}` + (对齐 react 的全局 `ActionResultFilter` 兜底分支:真实堆栈只进服务端日志,不外泄) - **唯一例外**:未知路由 → **HTTP 404**,body 仍是 `{code:404,msg:'接口不存在',data:null}` + (404 是**传输层**例外,不是业务失败;同理 **405 保留 HTTP 405**,见 §6.5) ### R1.3 `base_*` 表名/列名逐字对齐官方 DDL 不得自创表名/列名。迁移期靠 `--data-only` 导数据,列名差一个字符就导不进去。 @@ -427,7 +430,11 @@ SELECT row_to_json(q)::text AS _row FROM () AS q ### 6.5 其它 - 未知路由 ⇒ **HTTP 404** + `{code:404,msg:'接口不存在',data:null}` -- 405 ⇒ JSON `{code:405,msg:'方法不被允许',data:null}`,**保留 `Allow` 头** +- 405(路径存在、方法不对)⇒ **HTTP 405** + `{code:405,msg:'方法不被允许',data:null}`,**保留 `Allow` 头** + (react 侧 Express 路由对错误方法其实返 404,但**前端从不发错方法** ⇒ 这条不在契约面上, + 按「传输层状态码保留」处理,别让它掉进 R1.2 的 HTTP 200 规则。) +- 未捕获异常(panic / DB 报错)⇒ **HTTP 200** + `{code:400,msg:'系统异常,请联系管理员',data:null}` + (必须装 catch-all 中间件,**不能**让 axum 的默认 500 空 body 漏出去) - `GET /api/health` ⇒ `{ok, tables, version}`(**非契约**,探活用) --- @@ -614,14 +621,16 @@ SELECT row_to_json(q)::text AS _row FROM () AS q ### 8.2 菜单守卫 `has_module(userId, isAdmin, moduleKey)` 1. `isAdmin == 1` ⇒ **放行**(不查任何 SQL) -2. 查 `base_module` 中 `f_url_address = moduleKey AND f_delete_mark=0`;**查不到 ⇒ 放行**(未映射放行) +2. 查 `base_module` 中 `f_url_address = moduleKey AND f_delete_mark=0`(取**第一条**); + **查不到 ⇒ 放行**(未映射放行) 3. 查得到 ⇒ 该菜单 `f_id` 是否在四源合并集合里;在 ⇒ 放行,否则 ⇒ `403` - ### 8.3 菜单树 `build_menu_list(userId, isAdmin)` - 取 `base_module` 中 `f_delete_mark=0` 的行,按 `f_sort_code ASC` - 非管理员:过滤成「id 在四源集合里」的子集 - 建树:`f_parent_id` 为空或 `'0'` 或父节点不在集合内 ⇒ 该节点是根;否则挂到父节点 `children` -- 节点形状:`{id, fullName, urlAddress, icon, parentId, children}`(`urlAddress`/`icon` 可为 null) +- 节点形状:`{id, fullName, urlAddress, icon, parentId, children}` + (`urlAddress` / `icon` 库里是 NULL ⇒ JSON 里就是 `null`,**不要**省略这两个键; + `parentId` 取 `f_parent_id`,为 NULL/空 ⇒ `'0'`) - 根按 `f_sort_code` 升序;同层 children 按 `f_sort_code` 升序 ### 8.4 种子菜单(8 行,`f_tenant_id='0'`,`f_enabled_mark=1`,`f_delete_mark=0`) @@ -810,7 +819,7 @@ pub struct AppState { 3. **标识符白名单自检**(不过 ⇒ 秒退 exit 1),放在开库**之前** 4. `Db::open` / `Db::open_temp` ⇒ `ensure_schema()` 5. `seed::ensure_base()` ⇒ 若用户数为 0 则 `seed::first_seed()` -6. `build_router(state)` + 404 兜底 + 405 改写中间件 + `with_state(state)`(**链尾**) +6. `build_router(state)` + 404 兜底 + 405 改写中间件 + **catch-all(panic/未捕获异常 ⇒ HTTP 200 + `code=400`)** + `with_state(state)`(**链尾**) 7. `TcpListener::bind` ⇒ 绑定失败打印人话 + exit 1(**不 panic**) **子命令**:`--enc <明文>` ⇒ 打印 hex 到 stdout,退出码 0(冒烟脚本用它自证 cipher,不依赖 node)。