代码审查标准与流程
适用范围:仅后端 ——
src/、migrations/、scripts/、docs/。 (前端工程oauth21/posecraft/admin/poseadmin/firewall/phonecopy已于 2026-10-31 迁出本仓,各自独立审查。) 配套制品:PR 模板.github/PULL_REQUEST_TEMPLATE.md、审查归属.github/CODEOWNERS。
一、先看诊断:为什么现在"参差不齐"
制定标准之前先把病因说清楚,否则这又是一份没人看的文档。以下是 2026-09-20 对本仓库的实测结论。
问题不是"没人审查代码",而是审查没有分层。 后果是三件事同时发生:
1. 规则有,但入口七零八落
同一条"导出必须收拢到文件末尾",同时存在于三个地方:eslint.config.js 的 no-restricted-syntax、 一份 conventions 守卫、以及 开发规范 的一节。新人面对的真实体验不是"规则太松", 而是"不知道有哪些规则"—— 规则散落在 6 处,没有任何一处是权威入口。
2. 第一道闸门被人为关闭
$ cat .husky/pre-commit
# npx lint-staged
# 需要检查代码时手动运行: npx lint-staged本地提交不做任何检查。这意味着所有问题只能在两个更贵的时刻暴露:评审时人眼找,或者 CI 跑完。
3. 已有的文档在说谎(最隐蔽的一条)
| 文档里的说法 | 实测情况 |
|---|---|
| 「编码乱码」列为 P0(后端检查规划) | 全量扫描 src/ 已扫不到乱码,该项已修复 |
路径写作 src/auth/、src/db/、src/redis/、src/loader/registry/ | 实际已是 src/framework/security/auth/、src/framework/persistence/db/ 等,文件系统层已重组 |
package.json 的 version = 最新版本 | 停在 2.6.0,而最近 tag 是 v2.9.0 |
文档失真的代价很具体:审查者拿旧地图挑错,作者拿旧地图辩解,最后谁都不信文档。
由此得出本标准的第一原则:能自动化的绝不写进人工清单;写进人工清单的,必须是机器结构上抓不到、且人真的会看的东西。
二、分级:按爆炸半径,不按主观严重度
多数团队的评审退化成人身攻击或格式争论,根因是所有问题被当成同等重要。这里改用一个客观判据: 这个缺陷出事了,会炸多远?
| 级别 | 判据(满足其一即算) | 处置 | 谁有权判定 |
|---|---|---|---|
| L0 阻断 | 数据丢失/越权/凭据泄露/资金相关;协议或契约破坏且无兼容路径;并发下不确定的写入 | 必须修改,禁止合并。作者无裁量权 | 领域 owner + 安全面 owner |
| L1 整改 | 逻辑在边界条件出错;降级路径未覆盖;缺 schema 校验;迁移不可回滚 | 合并前必须改,或给出带期限的 follow-up issue | 任一审查者 |
| L2 建议 | 可维护性、命名、拆分时机、重复实现 | 可合并,记入 issue;反驳有效则撤销 | 任一审查者 |
| L3 风格 | 缩进、引号、空格、import 顺序 | 禁止人工提出 —— 工具已覆盖 | 工具(不是人) |
L3 由本规范明令禁止人工提出,这是刻意的:格式问题 eslint/prettier 已经管住了, 在 PR 里提缩进只会消耗双方的注意力预算,而这些预算本该花在 L0 上。
三、分工:机器管机器能管的
现有自动化闸门(不要重复人工检查同样的东西)
| 检查项 | 承载者 | 命令 |
|---|---|---|
| 语法/未定义变量/行内导出 | eslint.config.js | npm run lint |
| 导出位置(跨文件一致性) | src/__tests__/conventions/export-placement.test.js | npm test |
src 反向 import scripts | conventions/no-scripts-import.test.js | npm test |
| 测试是否真实加载被测代码(禁虚假覆盖) | conventions/test-effectiveness.test.js | npm test |
跨应用隔离(app/<A> 不得 import app/<B>) | conventions/app-isolation.test.js | npm test |
| firewall 分层单向依赖 | conventions/firewall-layering.test.js | npm test |
| node-redis 命令名合法性(v5 / v6 驼峰) | conventions/node-redis-v5-commands.test.js | npm test |
| 终端颜色/日志规范 | conventions/terminal-colors.test.js | npm test |
| 回归测试 | Jest | npm test |
| 跨进程验收 | scripts/verify/run-all.mjs | npm run verify:all |
| 依赖漏洞 | npm audit | npm run audit |
| 文档死链 | VitePress build | npm run docs:build |
共 7 个 conventions 守卫 + ESLint + 两套关卡,覆盖
src/下约 380 个 JS 文件。 凡是被上表覆盖的项,人工审查不再单独提 —— 提了也是重复劳动,而且守卫会漏、人会疲劳。
但必须记住:守卫全绿 ≠ 代码正确
这不是理论,是本仓库刚发生的实证:
connectStandalone()的有界性修复中,新写的测试锁的是外层超时,而不是"重试策略本身"。 用毒丸法把策略改回「永不放弃」,测试照样全绿 —— 一个通过了的、却在验证错误东西的测试。 只有把策略决策抽成纯函数单独测,毒丸才变红。
所以人工审查的靶心永远是:守卫在结构上抓不到的东西——语义是否正确、不变量是否真的被锁住、 降级路径是否真的走过。第四节就是这份靶心清单。
各闸门负责的层级
本地 → L3 全部(工具)+ L1 的一部分(自检清单)
CI → L3 全部 + L1 的机械部分(守卫/回归/关卡)
人工 → L0 全部 + L1 的语义部分 + L2 全部四、人工审查清单
按六个维度组织。每条都写成可以直接回答"是/否"的问题,而不是"要注意安全"这类空话。
A. 正确性与边界
- [ ] 空值、空数组、0、负数、超长字符串走一遍 —— 会不会
NaN参与运算?会不会undefined拼进 URL? - [ ] 分页/时间窗口的边界(第 1 页、最后一页、恰好等于上限)行为是否符合预期?
- [ ]
try/catch是否吞掉了错误?特别注意包住大段的 try —— 里面的每个 await 失败都会走同一个分支。 - [ ] 是否存在「空 catch 或只写
throw err的 catch」?后者是no-useless-catch,应直接删除(保留注释里的信息)。 - [ ] 循环里是否有
await顺序执行、本该并发的地方?(以及反过来:无上限的Promise.all会不会打爆连接池) - [ ] 异步函数是否漏了
await?(return一个 Promise 和return await在 try 内语义不同)
B. 安全与权限(本仓库高危面,按优先级)
- [ ] 路由是否走
registerSecureRoute()?是否显式声明了requireLogin与permission(或明确说明无需权限)? - [ ] 签名
freshPermission与持久化字段的边界是否被破坏?guard_configs表只允许enabled/requireLogin/allowIps/allowRoles进 DB;requirePermission、freshPermission属于代码级声明,一旦被写进 DB 就会产生"改了配置却依赖旧代码"的静默失效。 - [ ] 是否存在开放重定向?任何跳转目标必须是已校验的 session 里的地址,绝不能用
request.query.redirect_uri这类未校验入参(oauth21授权流程对此有明确约定)。 - [ ] 未登录也能访问的端点(尤其
/health/*)新增的字段,给外人看合适吗?(历史上曾回显内网 IP:port) - [ ] 进入
timingSafeEqual/.length比较 /Buffer.from(x, 'hex')/new Date(x)之前, 外部输入是否已归一化? - [ ] 日志与错误信息中是否含密码、Token、验证码、完整 Cookie、密钥?
- [ ] 权限点命名是否符合
{app}:{resource}:{action}?是否有allowRoles: []被误当成"禁止所有"(实际语义是不限角色)? - [ ] 涉及
guard-config.dao.js的restore()时:它是 truncate 全表 + 回填, 空快照会清空guard_configs—— 任何备份/回滚脚本必须先断言快照非空。
C. 接口契约与兼容性
- [ ] 响应是否统一走
reply.result.*?业务接口不得手写{ success: true }或裸reply.send({ code, message })。 既有白名单例外:OAuth / OIDC 标准协议接口({ error, error_description })合法,但必须在路由注释或文档中注明。 - [ ] 分页是否用
reply.result.paginated(data, total, page, pageSize)? ⚠️ 它是四个位置参数,调用点极易把total和page写反 —— 请逐个核对实参顺序。 - [ ] 新增/改动的路由是否提供了
schema(params/query/body)? 分页必须限制page >= 1、1 <= pageSize <= 100;状态字段用 enum 而非裸integer。 - [ ] DAO 是否与 Fastify 的
request/reply解耦(只接收普通参数、只返回普通数据)? - [ ] 是否有破坏性变更?如有,commit footer 必须写成
BREAKING CHANGE:的行首 + 冒号形式 —— 发版脚本只认这个形式,写进正文会被降级成 minor。 - [ ] 表结构变更是否走了
migrations/?模型字段与迁移是否同步?删字段是否分了两步(先停用、再删)? - [ ] 生产路径是否出现
DB_SYNC=true或脚本里的sequelize.sync()?(存量见第九节)
D. 并发、降级与故障
- [ ] Redis 未配置(走
MapStore)时,这段代码还成立吗?MapStore不支持zAdd/zRangeByScore, 依赖有序集合的限流/排行榜在无 Redis 的开发与测试环境会静默失效 —— 是否有兜底或明确的失败? 注意别把它和"运行期降级"混为一谈:配了 Redis 却连不上不会退回 MapStore,操作抛RedisRequiredError(503),所以异常路径也要能优雅收场。 - [ ] 所有"等外部依赖就绪"的地方是否有界?客户端库的重连策略默认"永不放弃",
await client.connect()可能永远不 reject,外层try/catch和 timeout 选项根本轮不到触发。 必须三段式:有界 TCP 预检 + 有界重试策略 + 外层硬超时。(详见 Docker 部署 的依赖等待设计) - [ ] 请求路径上是否调用了
*Sync(系列 API(existsSync、readFileSync等)?会阻塞事件循环。 - [ ] 是否有模块级
process.exit?它会让测试汇总恒报 0 失败 —— 伪装成绿色。必须加!isTestEnv守卫。 - [ ] 新增的导出面是否真实
import过上层入口一次?(否则unstable_mockModule替身会失真) - [ ] 缓存是否有击穿/雪崩风险?是否需要
cacheThrough的 singleflight? - [ ] 定时任务/后台循环是否在异常时会静默停止(没有
.catch)。 - [ ] WebSocket / 长连接的优雅停机:改
preClose了吗?(keepAliveTimeout、forceCloseConnections对已 upgrade 的连接无效)
E. 可运维性
- [ ] 日志是否走统一出口(
src/framework/support/log)?业务代码禁止console.*(eslint 已强制)。 注意logStdout不落盘、log.info会被丢弃 —— 脚本要输出结果别用log.info。 - [ ] 关键失败路径是否有可定位的日志(含足够的上下文、但不含敏感信息)?
- [ ] 这个改动出问题怎么回滚?回滚是否只需回退代码,还是也涉及数据/配置?
- [ ] 是否新增了环境变量?是否同步更新了
.env.docker.example与文档? - [ ] 启动期新增的 loader/依赖是否声明了失败语义?(
loader/engine.js的OPTIONAL_LOADERS是带伤启动白名单, 未列入者 fail-fast,不声明=关键,这是有意的)
F. 测试质量
- [ ] 测试是否真实加载被测代码(相对
import/ 动态import)? 只 import 常量的测试在删除被测模块后仍会全绿,属于虚假覆盖。 - [ ] 是否内联复制了被测逻辑?副本会与真身各自演化,"测试通过"不代表真身正确。
- [ ] 断言是否锁在真正的不变量上,而不是锁在一个恰好也会通过的代理指标上? (回顾第三节的实证:锁外层超时 ≠ 锁住重试策略)
- [ ] 毒丸试验:把被测模块覆写成
throw new Error('__QUARANTINE__'), 相关测试必须变红。照绿 = 该测试没在验证这个东西。实验后务必恢复。 - [ ] 是否覆盖了降级路径(无 Redis / 无 DB)与边界,而不是只覆盖 happy path?
- [ ] 一个测试文件是否只注册了一组路由?(
registerSecureRoute的_routeRegistry是模块级全局状态且无重置入口) - [ ] 新增测试是否真的加载了生产实现?(判据见
src/__tests__/conventions/test-effectiveness.test.js: AST 解析 + 仓库内路径解析 —— 注释里写from '../x'、夹具字符串、import('crypto')一律不算)
五、按变更类型的差异化审查
不同改动风险差异巨大。下表规定每类变更的额外必查项,避免"改个文案"和"改权限判定"走同一条审查流水线。
| 变更类型 | 额外必查 | 必须第二人 | 配套产物 |
|---|---|---|---|
| 数据库迁移 | 是否可回滚(down 真的能跑)?大表 DDL 是否锁表?是否与模型同步? | ✅ | 迁移文件 + 模型 + 测试 |
| 权限 / 守卫 | 是否误把代码级声明写进 DB?deny 优先是否仍成立?新旧权限兼容期? | ✅ 安全面 owner | 权限字典 + 前端按钮同步 |
| OAuth / 签名 / 加密 | 开放重定向?时序安全比较是否归一化?密钥是否泄露进日志? | ✅ | 协议例外说明 |
| Redis / 缓存 / 锁 | 降级到 MapStore 后行为?是否有界超时?锁释放是否安全(Lua 原子)? | ✅ | 降级路径测试 |
| 路由 / 契约 | schema 是否齐?响应是否统一?分页参数顺序是否正确?是否破坏前端? | ⬜ | 前端类型同步 |
| 鉴权失败路径 | 失败时是否默认拒绝(fail-closed)而不是默认放行? | ✅ | 测试 |
| 依赖升级 / 大版本 | lock 是否同步?link: 协议依赖是否受影响?是否有破坏性 API 变更? | ⬜ | 变更说明 |
| 前端工作区 | 是否接入 stable-deviceid?组件目录三层结构?类型检查是否过? | ⬜ | 类型检查 |
| 纯文档 / 注释 | 链接是否可达(docs:build 会拦死链)?是否与实现一致(别写没实现的)? | ⬜ | — |
「必须第二人」的目的是避免作者自我确认,不是走形式。单人项目可标注"自我审查 + 延迟合并(隔日再看)"作为替代。
六、流程:五道闸
闸 ① 本地自检(提交前)
- 恢复 pre-commit(见第八节 Phase 1)—— 目前它是注释状态,等于这道闸不存在。
- 按「变更类型」查第五节的额外必查项。
- 跑与本改动相关的测试;涉及
src/结构性改动时跑全量。
闸 ② CI 自动闸门
推分支即触发(三步全绿才有资格进入人工评审):
npm run lint # 零 error(warning 允许,但要递减)
npm test # 全量回归
npm run verify:all # 跨进程验收(退出码 0/1/2/3)涉及容器/部署改动时额外跑 docker compose 端到端冒烟。
⚠️ 退出码语义:
0通过 /1断言失败(看代码)/2回滚不完整(需人工介入)/3环境不可用(修环境,不是改代码)。 混淆3和1会导致"代码没问题却被人乱改"。
闸 ③ 人工评审
- 作者:开 PR 前填完模板(含验证证据与回滚方案);自证比让审查者猜要高效得多。
- 审查者:
- 先看 CI 是否全绿 —— 红的不审。
- 先看 diff 的意图,再看实现。读完标题与描述后,先自己回答"如果是我会怎么做"。
- 按第四节六个维度过,按第五节补该类型的必查项。
- 提意见必须带级别前缀(见第七节)。
- 响应时限:L0/L1 类 PR 建议 1 个工作日内给出首轮意见;超时未审视为默认同意(除非标注为阻塞)。
闸 ④ 合并条件(全部满足才可合并)
- [ ] CI 三步全绿(含
verify:all退出码 0) - [ ] 无未解决的 L0 / L1 意见
- [ ] L2 意见已转为 issue 或已说明不修的理由
- [ ] 涉及第五节的"必须第二人"类型,已有第二人明确批准
- [ ] 破坏性变更为 footer 形式,且已在版本说明中体现
- [ ] 新增/修改的行为有对应测试;新增的失败模式有人知道怎么排查
闸 ⑤ 事后
- 发版:按
AGENTS.md的判据发版(含feat→ minor;仅fix/perf→ patch;破坏性 → major), 顺手把package.json的version对齐 —— 版本源是 git tag。 - 事故复盘:任何漏到生产的 L0/L1 缺陷,必须回答一个问题: "这个缺陷能否被某条自动化规则拦住?" 能 → 就加那条规则(把人工经验沉淀成守卫,这才是审查机制的复利)。
七、意见怎么写、作者怎么回
提意见的格式
[级别] 位置:问题 —— 证据/后果 —— 建议✅ 好的写法:
[L0] src/api/oauth21/v1/auth/authorize.js:42
用的是 request.query.redirect_uri 直接跳转,未校验入参 → 开放重定向,攻击者可借你的域投递任意链接。
建议改为只使用已校验 session 中保存的 redirect_url。❌ 坏的写法:
这里不太好吧—— 无级别、无证据、无建议,作者无法行动建议改成 const—— L3,本规范禁止人工提你之前也老犯这个错—— 对人不当事,且毫无信息量
作者如何回应
| 情况 | 正确做法 |
|---|---|
| 同意 | 改掉即可,不必逐条回复"已改",用 resolve 标记 |
| 不同意 | 必须给出理由或反证(测试、文档、实测输出)—— 沉默或"我觉得没问题"不构成回应 |
| 认为级别定高了 | 可以争取降级,但要针对判据(爆炸半径)讨论,而不是针对语气 |
| 属于 L3 | 直接指出"这条属于 L3,工具已覆盖",双方都不必纠缠 |
争议裁决
- L0/L1:由变更所属领域的 owner 裁决;跨领域(如同时涉及权限与数据)由安全面 owner 参与。
- L2:作者有权不修,但必须在 PR 里写明理由,并转为 issue。
- L3:不存在争议 —— 交给 formatter,人不参与。
八、落地路线
不要一次上齐。分三步,每步都可独立验收。
Phase 1:让闸门真实存在(零成本,立刻可做)
- 恢复 pre-commit 钩子:把
.husky/pre-commit的两行注释改为实际执行npx lint-staged,让 L3 在提交时就自动修掉,不再流入评审。 - 统一入口:本文件作为审查的单一权威入口,其余规范文档在开头互链,避免"六处各说各话"。
- PR 模板 + CODEOWNERS 上线:作者自证 + 审查归属明确。
- 清理文档失真:修正第九节里"文档说谎"的三条(这是最便宜的公信力修复)。
Phase 2:补齐自动闸门(本季度)
对齐 后端检查规划 的 Phase 4,把仍靠人眼的三项交给机器:
- 乱码扫描进 CI —— 存量虽已清干净,但需要守卫防止回流(扫
鍓、鎼、闁等异常区段)。 - 接口契约测试 —— 断言响应统一走
reply.result、分页字段齐全,把第三节的白名单例外显式登记。 - 前端类型检查进 CI ——
vue-tsc当前不在闸门里。 - 给出 L3 的可执行自动修复:
npm run lint已支持--fix,在 CI 里则以只读模式运行,防止"CI 偷偷改代码"。
Phase 3:清偿存量(持续)
见第九节台账。原则:每一项都必须有 owner 和期限,否则台账会变成第二份"说谎的文档"。
九、存量债务台账(2026-09-20 首测 · 2026-10-31 复核)
本表只记录已实测确认的项。改完之后请更新本表——一份诚实的台账比一份完美的规划有用得多。 状态列:✅ 已修 / ⏳ 仍在 / — 不再适用。
| # | 项 | 实测证据 | 状态 |
|---|---|---|---|
| 1 | .husky/pre-commit 钩子被注释,本地无任何检查 | 文件内容为两行注释 | ⏳ L1(Phase 1 第 1 条) |
| 2 | 脚本仍用 sequelize.sync() | scripts/initSuperAdmin.js(sync({ alter: true }))scripts/setup-superadmin.js(sync())仍在 | ⏳ L1(仅剩 1 处) |
| 3 | 部分业务接口绕过 reply.result | src/api/** 多处裸 reply.send({ code, message }),缺 data/timestamp/requestId;另有 OAuth 协议例外(合法,需登记) | ⏳ L1 |
| 4 | package.json 版本与 tag 不一致 | 2026-09-20 时 2.6.0 vs v2.9.0;现为 2.29.2 且 tag v2.29.2 对齐,发版脚本已同步 lock 根版本 | ✅ |
| 5 | 文档路径过时 | AGENTS.md 的 src/loader/registry/ 已改为 src/framework/...;2026-10-31 又批量修正 docs(路径/端点/脚本名/环境变量) | ✅ |
| 6 | 后端检查规划 中"编码乱码 P0"已不成立 | 全量扫 src/ 已无乱码字符 | — 归档文档不再维护 |
| 7 | 存量伪测试清单仍挂 14 条 | 清单已清零并改为 AST 判据;四份假覆盖测试(dao / service / signature / guard)已重写为真身驱动 | ✅ |
| 8 | session.js 拆分评估未开始 | 见 架构评估 P2 项 | ⏳ L2 |
| 9 | 前端类型检查未进 CI | 前端工程 2026-10-31 全部迁出本仓,CI 只跑后端 | — 不再适用 |
附:一页速查
审查者只需记住三句话
- L3 不提 —— 格式交给工具。
- 守卫已覆盖的不提 —— 重复劳动没有收益。
- 只盯守卫结构上抓不到的 —— 语义、边界、降级、契约、可回滚性、测试是否真的在验证东西。
作者只需记住三句话
- 先跑 CI 再请人 —— 红的 PR 没人审。
- 自证优于被问 —— 验证证据和回滚方案写进 PR 描述。
- 毒丸试验一次 —— 新写的守卫/测试,把它测的东西改坏,必须变红。