学完这篇，你能为团队搭起一套"规范可执行、评审有重点"的 PHP 协作流程——不再靠口头约定和人情面子维持代码质量。
第一步：规范先定基线，别定洁癖
不要一上来抄几百页大厂手册，团队没人看得完。做法是三层：
- 基线直接用 PSR 系列：PSR-1（基础编码标准）、PSR-4（自动加载）、PSR-12（扩展编码风格）。这三份是公开的、有工具支持的，直接声明"本项目遵循 PSR-12"就够了。
- 团队补充条款写成一页纸，只写 PSR 没覆盖的：目录约定、类名后缀、注释语言、常量定义位置、异常处理口径。
- 无框架项目额外补目录约定。像 Clara BBS 这类无框架纯 PHP 系统，靠的是目录结构 + 单一入口维持秩序，所以规范里要写清楚"哪个目录放控制器、哪个放模型、插件代码放哪"。
注意：规范里凡是能用工具查的（缩进、括号、行宽），就不要写进文档靠人记——写进文档的应该是工具查不出来的东西（命名语义、分层职责）。
第二步：把规范变成机器能查的东西
文档靠自觉，工具靠强制。在开发机和 CI 上装这几个：
composer global require squizlabs/php_codesniffer
composer global require phpstan/phpstan
# 查风格
phpcs --standard=PSR12 app/
phpcbf --standard=PSR12 app/
# 静态分析，等级从 5 起步，别一上来就 9
phpstan analyse app/ --level=5
再补一个 .editorconfig 统一换行符和缩进，避免 Windows/Linux 混开时整文件 diff。
注意：第一次接入 phpcbf 时，单独提一个"纯格式化"提交，不要和业务改动混在一起。否则代码评审时 3000 行 diff 里全是空格变化，真正的逻辑改动根本看不见。
注意：像 Clara BBS 这样无需 Composer 运行的项目，把 phpcs/phpstan 只装在开发机与 CI，当成开发期检查工具，不要引入运行时依赖，也就不影响生产部署。
第三步：让 PR 自己说话
评审效率低，八成是提交本身没做好准备：
- 控制体积：单个 PR 尽量 400 行以内、单一目的。改 bug 就别顺手重构。
- 描述模板固定三问：改了什么 / 为什么改 / 怎么验证。有复现步骤就贴。
- CI 必须先绿：phpcs、phpstan、单元测试三道关，没过不进人工评审。
- 作者先自审 diff：自己看一遍，能删掉调试代码、注释掉的旧逻辑。
第四步：评审时只看工具看不见的部分
机器能查的（风格、语法、明显未定义变量）交给工具，人只看这些：
- 逻辑正确性与边界：空数组、零值、null、超大输入、并发写入。
- 安全：SQL 是否参数化、输出是否转义、表单是否校验 CSRF token、密码是否用
password_hash（bcrypt）、上传是否走白名单 + 类型二次校验。
- 性能：循环里查库（N+1）、缺索引的 WHERE、无上限的查询。
- 可读性：函数是否只做一件事、命名能否自解释。
- 可测试性：耦合是否过死，硬编码路径/时间/随机数是否抽出来。
评论要分级，别让作者猜轻重：
must: 必须改，阻塞合并should: 建议改，可后续跟进nit: 吹毛求疵，改不改都行
注意：评审不是重写。把别人的实现改成"你更喜欢的写法"是最伤士气的行为——除非原写法确实有正确性、安全性或明显可维护性问题，否则放行。
注意：用提问代替命令。"这里如果 $id 是字符串会怎样？"比"这里必须加 intval"更容易被接受，也更容易发现作者其实已经处理过。
第五步：评审后要闭环
- 同一处讨论超过三轮就直接拉语音或当面说，文字来回成本太高。
- 每条被反复提出的意见，沉淀成规则：能工具化的写进 phpcs 规则集，不能工具化的写进那一页纸补充条款。
- 合并后作者回一句"已按 X 调整"，避免评论挂着没人管。
小结
- 规范基线用 PSR-12，团队只补一页纸的"工具查不到的部分"。
- phpcs 管风格、phpstan 管类型与明显缺陷，CI 必须先绿再进人工评审。
- 首次接入格式化工具要单独提交，别污染业务 diff。
- 人工评审聚焦四件事：逻辑边界、安全、性能、可读性，风格问题交回给工具。
- 评论分级 must/should/nit，用提问代替命令，不做"改写成我的风格"式评审。
- 反复出现的评审意见要沉淀成规则或 lint，否则同一个问题会一直吵。
正式会员
认证极客
见习用户
