本文目录导读：
在衡量 PHP 项目的健康度时，不应该只看“代码能不能跑”，而是要从可维护性、安全性、性能、团队协作和工程化水平等多个维度综合评估。
以下是 PHP 项目健康度核心指标的分类清单,按优先级排序：
核心工程指标（最基础）
这些指标直接反映项目的“生存能力”，如果这些不合格，项目基本是“亚健康”状态。
- 依赖陈旧度：
- 指标：
composer.lock中依赖的PHP 版本要求与已安装版本的差距；是否有依赖包年久失修（超过 2 年未更新）。 - 风险：旧依赖 = 安全漏洞 + 与新版 PHP 不兼容。
- 指标：
- PHP 版本使用率：
- 指标：生产环境运行的 PHP 版本（如 7.4 / 8.0 / 8.2+）。
- 建议：应使用官方仍在安全维护的版本（当前推荐 >= 8.2）。
- 代码覆盖率：
- 指标：PHPUnit 或 Pest 报告的测试覆盖率百分比（行覆盖/分支覆盖）。
- 理想值：核心业务逻辑 > 80%，整体项目 > 60%。
代码质量指标（可维护性）
这部分决定了“改代码会不会引发雪崩”。
- 圈复杂度：
- 指标：代码中分支（if/else/switch）的密集程度。
- 工具：PHP Mess Detector (PHPMD)，若单个函数复杂度 > 10，说明可读性差,需重构。
- 代码动态指标（Stability）：
- 指标：引用外部类的数量（Fan-In）和被外部引用的数量（Fan-Out）。
- 健康状态：高层模块不应依赖底层模块,类间耦合度应保持低水平。
- 重复代码率（Copy/Paste Detector）：
- 指标：使用
phpcpd检测,重复代码块占比。 - 风险：重复代码意味着修 bug 时容易漏改。
- 指标：使用
性能与资源指标（运行时）
这些指标直接决定用户体验和服务器成本。
- 响应时间（百分位数）：
- 指标：apdex（应用性能指数），关注 P95 和 P99 的接口响应时间。
- 健康值：根据业务类型不同，一般 P95 应 < 2s（API 应 < 500ms）。
- 内存泄漏：
- 指标：长时间运行（如队列 Worker、Swoole 常驻进程）的内存增幅趋势。
- 检测：通过
memory_get_peak_usage()或监控工具（如 Blackfire）查看。
- 慢查询与 N+1 问题：
- 指标：ORM（如 Eloquent/Doctrine）触发的 SQL 数量。
- 健康状态：单页面请求 SQL 查询次数不应过高（列表页建议 < 20 次）。
安全指标（风险底线）
PHP 项目是黑客攻击的重灾区，安全是“一票否决”项。
- 漏洞扫描状态：
- 指标：使用
composer audit或psalm（安全审计模式）检查依赖包是否有已知 CVE（通用漏洞披露）。
- 指标：使用
- 输入校验强度：
- 指标：所有 HTTP 参数（GET/POST/Header）是否经过 Filter/Sanitizer 处理。
- SQL 注入防护：
- 指标：所有 SQL 是否使用 PDO 预处理参数（绑定参数），严禁字符串拼接 SQL。
- 敏感信息泄露：
- 指标：
git log中是否泄露过.env文件；phpinfo()是否在运行环境可访问。
- 指标：
工程化指标（开发体验）
决定团队协作效率和发布质量的软实力。
- CI/CD 构建时长：
- 指标：从
git push到测试完成所需时间（如 15 分钟内）。
- 指标：从
- 静态分析结果：
- 指标：PHPStan / Psalm 的解析级别（如 Level 5/Level 6）。
- 健康值：0 个错误，且级别设置为最高级（Level Max）而无大量
@phpstan-ignore（忽略标注）。
- 代码规范统一度：
- 指标：项目是否安装了 PHP-CS-Fixer 或 PHP CodeSniffer，
CI中强制检查违规数是否为 0。
- 指标：项目是否安装了 PHP-CS-Fixer 或 PHP CodeSniffer，
- Fatal Error 率：
- 指标：生产环境日志中
PHP Fatal error的占比（如每千次请求出现 < 0.1 次）。
- 指标：生产环境日志中
架构演进指标（长期价值）
这部分往往是传统 PHP 项目最缺乏的。
- 遗留代码比例：
- 指标：没有使用 Composer 自动加载（
include/require原生引入）的代码行数占比。 - 目标：应逐步向 PSR-4 规范升级。
- 指标：没有使用 Composer 自动加载（
- Facade 静态调用比例（针对 Laravel）：
- 指标：业务代码中过度使用静态
Facades,导致依赖注入困难。 - 改进：检查控制器中
use外部类的数量，是否过分依赖Helper函数。
- 指标：业务代码中过度使用静态
建议的“体检”工具组合
如果现在要生成一份健康度报告,可以组合这几个工具直接跑一遍：
| 维度 | 工具 | 命令（例） |
|---|---|---|
| 安全漏洞 | Composer | composer audit |
| 代码质量 | PHPMD | vendor/bin/phpmd ./src text cleancode,codesize,design |
| 架构硬核 | PHPStan | vendor/bin/phpstan analyse src --level=6 |
| 重复代码 | PhpCPD | vendor/bin/phpcpd ./src |
| 测试覆盖 | PHPUnit | vendor/bin/phpunit --coverage-html ./coverage |
| 运行性能 | Blackfire | 压测接口，查看火焰图 |
最核心的健康度指标，简要说就是三段论：它能安全地跑多久（安全+性能）、改起来改动面大不大（耦合+复杂度）、新人接手会不会骂娘（规范+文档）。
