PHP项目健康度指标有啥

本文目录导读：

1. 核心工程指标（最基础）
2. 代码质量指标（可维护性）
3. 性能与资源指标（运行时）
4. 安全指标（风险底线）
5. 工程化指标（开发体验）
6. 架构演进指标（长期价值）
7. 建议的“体检”工具组合

在衡量 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。
• Fatal Error 率：
  • 指标：生产环境日志中 PHP Fatal error 的占比（如每千次请求出现 < 0.1 次）。

架构演进指标（长期价值）

这部分往往是传统 PHP 项目最缺乏的。

• 遗留代码比例：
  • 指标：没有使用 Composer 自动加载（include/require 原生引入）的代码行数占比。
  • 目标：应逐步向 PSR-4 规范升级。
• Facade 静态调用比例（针对 Laravel）：
  • 指标：业务代码中过度使用静态 Facades,导致依赖注入困难。
  • 改进：检查控制器中 use 外部类的数量，是否过分依赖 Helper 函数。

建议的“体检”工具组合

如果现在要生成一份健康度报告,可以组合这几个工具直接跑一遍：

最核心的健康度指标，简要说就是三段论：它能安全地跑多久（安全+性能）、改起来改动面大不大（耦合+复杂度）、新人接手会不会骂娘（规范+文档）。