用途
中文代码审查规范技能,用于帮助国内团队在 Code Review 中找到表达平衡点——既不回避问题,又让人愿意接受反馈。它针对国内团队常见的两个极端:过度客气导致关键问题被放过,或照搬西方直白风格让同事下不来台。核心原则是:用"建议"代替"命令",用"提问"代替"否定",但绝不因为面子而放过 bug。
调用方式上,该技能仅在用户显式输入 /chinese-code-review 时调用,不要根据上下文自动触发。
审查反馈的表达方式
用建议代替命令,例如将"你必须改成 X"改为"建议考虑用 X,因为 Y";将"这里写错了"改为"这里可能存在一个问题,是否考虑过 Z 的情况?";将"不要用这个方法"改为"这个方法在 A 场景下可能有性能问题,可以看看 B 方案";将"这段代码不行"改为"这段逻辑我理解得对吗?如果输入为空的话会怎样?"。
用提问代替否定。当不确定对方意图时,先问再评。例如:"这里用 sync 方式读文件是出于什么考虑?如果并发量上来,可能会阻塞事件循环。"而非"这里不应该用 sync 方式读文件。"
分级标注
统一使用优先级标记,让作者快速判断轻重缓急:
- [必须修复] — 安全漏洞、数据丢失风险、逻辑错误(不修不能合)
- [建议修改] — 性能问题、可维护性、缺少校验(本次或下次迭代修复)
- [仅供参考] — 命名优化、风格建议、替代方案(不改也行)
- [问题] — 不确定的地方,需要作者解释意图
审查评论模板
以 SQL 注入风险为例,模板包含问题定位、原因说明、修复建议与参考链接:
[必须修复] SQL 注入风险
第 42 行:用户输入直接拼接到 SQL 语句中。
原因:攻击者可以通过 name 参数注入 '; DROP TABLE users; --。
建议:使用参数化查询:
db.query('SELECT * FROM users WHERE name = $1', [name])
参考:https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html
中英混排代码注释规范
何时用中文:业务逻辑说明(解释业务背景和需求来源)、复杂算法注释(写思路)、TODO / FIXME(描述待办事项,方便搜索和追踪)、文档注释(内部项目 JSDoc / Javadoc 中的描述文字)。资料给出了计算会员等级折扣的 JSDoc 示例,包含业务规则说明与 @param、@returns 标注。
何时用英文:变量名、函数名、类名始终用英文命名;Git commit message;开源项目注释;错误信息和日志(生产环境 error message 用英文,避免编码问题);对外暴露的 API 接口文档。
混排格式要求:中英文之间加空格,例如"使用 Redis 缓存来减少 MySQL 的查询压力",而非无空格写法;技术术语保留英文,例如"这里用 debounce 防抖处理",不强行翻译为"防抖动"和"应用程序接口"。
Commit Message 中英双语格式
推荐格式为约定式提交(Conventional Commits)的中文版:<类型>(<范围>): <简要描述>,后接可选的详细说明与关联信息。
类型对照表包括:feat(新功能)、fix(修复 Bug)、docs(文档变更)、style(代码格式)、refactor(重构)、perf(性能优化)、test(测试)、chore(构建/工具),并附各类示例。
示例:fix(支付): 修复支付宝异步回调签名校验失败的问题,说明原因(升级 SDK 后签名算法从 RSA 变为 RSA2,回调校验仍使用旧算法)与方案(兼容 RSA 和 RSA2 签名校验),并关联 Closes #1234。
面向国际社区的项目:commit message 用英文,PR 描述中可附加中文说明。
常见反模式与对策
反模式一:过度客气。表现是所有评论都是委婉语,后果是关键 bug 被隐藏,作者不知道哪些必须改。对策是使用分级标注,语气可以温和但级别必须准确。
反模式二:不敢给高级开发者提意见。表现是对高级开发者或 Leader 的代码直接 Approve。后果是代码质量双标,团队对 Code Review 失去信任。对策是对事不对人,可用提问式或学习式表达。
反模式三:审查变成风格之争。表现是大量评论纠结缩进、空格、花括号位置。对策是风格问题交给 ESLint / Prettier / gofmt 等工具自动处理,Code Review 聚焦逻辑、安全、性能。
反模式四:只写"LGTM"。对策是即使代码质量很好,也要写出关注了哪些方面,并附上仅供参考的小建议。
审查流程建议
开始审查前:先看 PR 描述理解改动背景和目的,看关联的 Issue 或需求文档,先整体浏览再逐文件细看。
审查顺序:架构层面(方案是否合理)→ 正确性(逻辑、边界条件)→ 安全性(注入、越权、信息泄露)→ 性能(N+1 查询、内存泄漏、不必要循环)→ 可维护性(半年后能否看懂、测试覆盖)→ 风格(只关注工具无法自动处理的部分)。
给出总结:审查结束后给出整体评价(一句话)、值得学习的地方(先扬后抑)、主要问题列表(按优先级)、建议的修改方向。
检查清单
在提交审查意见前确认:每条评论都标注了优先级;[必须修复] 的问题都给出了具体修复建议;没有因为面子跳过关键问题;没有纠结于工具能自动处理的风格问题;对好的代码给予了肯定;给出了整体总结。
限制
该技能为沟通风格与规范参考,不包含自动化审查功能;未提供具体安装命令、平台支持范围及收费信息,资料中暂未提供。