Skip to content

代码审查标准与流程 ​

适用范围:仅后端 —— 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.jsnpm run lint
导出位置(跨文件一致性)src/__tests__/conventions/export-placement.test.jsnpm test
src 反向 import scriptsconventions/no-scripts-import.test.jsnpm test
测试是否真实加载被测代码(禁虚假覆盖)conventions/test-effectiveness.test.jsnpm test
跨应用隔离(app/<A> 不得 import app/<B>)conventions/app-isolation.test.jsnpm test
firewall 分层单向依赖conventions/firewall-layering.test.jsnpm test
node-redis 命令名合法性(v5 / v6 驼峰)conventions/node-redis-v5-commands.test.jsnpm test
终端颜色/日志规范conventions/terminal-colors.test.jsnpm test
回归测试Jestnpm test
跨进程验收scripts/verify/run-all.mjsnpm run verify:all
依赖漏洞npm auditnpm run audit
文档死链VitePress buildnpm 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 会拦死链)?是否与实现一致(别写没实现的)?⬜—

「必须第二人」的目的是避免作者自我确认,不是走形式。单人项目可标注"自我审查 + 延迟合并(隔日再看)"作为替代。


六、流程:五道闸 ​

闸 ① 本地自检(提交前) ​

  1. 恢复 pre-commit(见第八节 Phase 1)—— 目前它是注释状态,等于这道闸不存在。
  2. 按「变更类型」查第五节的额外必查项。
  3. 跑与本改动相关的测试;涉及 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 前填完模板(含验证证据与回滚方案);自证比让审查者猜要高效得多。
  • 审查者:
    1. 先看 CI 是否全绿 —— 红的不审。
    2. 先看 diff 的意图,再看实现。读完标题与描述后,先自己回答"如果是我会怎么做"。
    3. 按第四节六个维度过,按第五节补该类型的必查项。
    4. 提意见必须带级别前缀(见第七节)。
  • 响应时限: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:让闸门真实存在(零成本,立刻可做) ​

  1. 恢复 pre-commit 钩子:把 .husky/pre-commit 的两行注释改为实际执行 npx lint-staged,让 L3 在提交时就自动修掉,不再流入评审。
  2. 统一入口:本文件作为审查的单一权威入口,其余规范文档在开头互链,避免"六处各说各话"。
  3. PR 模板 + CODEOWNERS 上线:作者自证 + 审查归属明确。
  4. 清理文档失真:修正第九节里"文档说谎"的三条(这是最便宜的公信力修复)。

Phase 2:补齐自动闸门(本季度) ​

对齐 后端检查规划 的 Phase 4,把仍靠人眼的三项交给机器:

  1. 乱码扫描进 CI —— 存量虽已清干净,但需要守卫防止回流(扫 鍓、鎼、闁 等异常区段)。
  2. 接口契约测试 —— 断言响应统一走 reply.result、分页字段齐全,把第三节的白名单例外显式登记。
  3. 前端类型检查进 CI —— vue-tsc 当前不在闸门里。
  4. 给出 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.resultsrc/api/** 多处裸 reply.send({ code, message }),缺 data/timestamp/requestId;另有 OAuth 协议例外(合法,需登记)⏳ L1
4package.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)已重写为真身驱动✅
8session.js 拆分评估未开始见 架构评估 P2 项⏳ L2
9前端类型检查未进 CI前端工程 2026-10-31 全部迁出本仓,CI 只跑后端— 不再适用

附:一页速查 ​

审查者只需记住三句话

  1. L3 不提 —— 格式交给工具。
  2. 守卫已覆盖的不提 —— 重复劳动没有收益。
  3. 只盯守卫结构上抓不到的 —— 语义、边界、降级、契约、可回滚性、测试是否真的在验证东西。

作者只需记住三句话

  1. 先跑 CI 再请人 —— 红的 PR 没人审。
  2. 自证优于被问 —— 验证证据和回滚方案写进 PR 描述。
  3. 毒丸试验一次 —— 新写的守卫/测试,把它测的东西改坏,必须变红。

基于 GPL-3.0 许可发布