本文目录导读：
这是一个非常专业且具有实操价值的问题，在PHP项目中，技术债务的度量不仅是代码质量的问题,更是项目管理和风险控制的关键。
技术债务难以用一个绝对的数字来衡量，通常需要从多个维度加权综合评估，以下是一套适用于PHP项目的技术债务度量体系，分为量化指标、代码异味检测和综合评估模型三个层面。
核心量化指标（可自动化采集）
这些指标可以通过工具（如 PHPStan, Psalm, PHPMD, PHP_CodeSniffer, PhpMetrics）直接计算出来。
代码复杂度（最具代表性的“利息”）
- 圈复杂度（Cyclomatic Complexity）：衡量代码中独立路径的数量。
- 阈值：方法 ≤ 10，类 ≤ 50。
- 计算方法：
M = E - N + 2P（E为边数，N为节点数，P为连通分量数）。 - 风险等级：函数/方法 > 20 为高风险债务,极难测试和维护。
- 认知复杂度（Cognitive Complexity）：PhpMetrics 等工具可计算，它比圈复杂度更强调代码的“可读性”,对嵌套深度的惩罚更重。
- 类耦合度（Coupling Between Objects - CBO）：一个类依赖的其他类的数量。
- 阈值：CBO > 14 通常意味着高耦合,修改成本高。
重复代码（代码克隆 - Code Clones）
- 度量单位：重复代码行数占总代码行数的百分比。
- 工具：
PHP Copy/Paste Detector (phpcpd)。 - 风险：修复一个 bug 时漏掉另一个重复片段，导致 Bug 复现。
代码覆盖率（债务的“防火墙”）
- 核心指标：
- 行覆盖率：无债务的理想情况应 ≥ 80%。
- 分支覆盖率：远比行覆盖率重要，如果分支覆盖率 < 60%，说明代码的“未知路径”很多,是隐藏债务。
- 公式：未被测试覆盖的复杂代码量 =
圈复杂度总和 * （1 - 分支覆盖率），这个值越高，未来修复 Bug 的风险越大。
代码异味（Code Smell）密度
- 指标：每千行代码中的代码异味次数。
- 工具：
PHPMD(PHP Mess Detector)。 - 常见异味：
TooManyFields（过多的字段）、LongClass、GodClass（上帝类）、SwitchStatements（未使用多态的switch）、EmptyCatchBlock（空的 catch 块）。
类型安全与静态分析（PHP 特有的核心债务）
- 指标：PHPMD 或 PHPStan/Psalm 在最高级别下检测出的错误数。
- 级别：
- PHPStan Level 0-9：目标是达到 Level 6 以上。
- 具体检测项：
Possibly null argument（潜在的空值传递）Call to undefined method（调用未定义的方法）Missing return type（缺少返回类型声明）
- 计算：
（总行数 / 发现的类型错误数），值越小,债务越重。
维度加权综合评估（SIG模型实战）
借鉴 Software Improvement Group (SIG) 的模型，它非常适用于评估PHP项目的“可维护性”。
SIG 评估模型（权重预设）：
| 维度 | 权重 | PHP 具体度量指标 | 低风险阈值 |
|---|---|---|---|
| 体积 | 1 | 项目总代码行数 (LOC) | < 500,000 (过大则测试成本高) |
| 复杂度 | 25 | 圈复杂度 > 10 的方法占比 | < 10% |
| 重复 | 2 | 重复代码行比例 | < 5% |
| 单元测试 | 3 | 分支覆盖率 | > 70% |
| 静态分析 | 15 | PHPStan Level 6+ 的通过率 | 100% 无错误 |
计算公式：
技术债务指数 = 1 - (0.1 * 体积分 + 0.25 * 复杂度分 + 0.2 * 重复分 + 0.3 * 测试分 + 0.15 * 静态分析分)
指数越接近 1，债务越重；越接近 0,代码越健康。
针对PHP项目的特殊债务点
PHP 特有的历史和技术演进决定了其技术债务有其特殊性：
-
版本兼容性：
- 指标：仍使用
mysql_*函数、ereg（弃用）、each、__autoload的代码行数。 - 风险：这类代码在 PHP 8.x 中已经移除，是硬性债务,必须尽快偿还。
- 指标：仍使用
-
全局状态与全局变量：
- 指标：
global关键字使用次数、$_GET,$_SESSION在非控制器层的直接调用次数。 - 风险：这是导致 PHP 项目“意大利面条式代码”的头号敌人,带来极高的耦合度。
- 指标：
-
框架依赖锁定：
- 指标：
composer.json中require的过时且无安全支持的框架版本（如 Laravel 5.x, ThinkPHP 3.x, CodeIgniter 2.x）。 - 风险：无法利用新特性，且面临安全漏洞（CVE）风险。
- 指标：
-
隐式依赖与函数式编程缺失：
- 指标：未使用 Composer Autoloading 的
require_once数量。 - 风险：难以进行单元测试和依赖注入。
- 指标：未使用 Composer Autoloading 的
推荐工具与流程
| 工具 | 功能 | 集成方式 |
|---|---|---|
| PHPStan / Psalm | 静态分析，发现类型和逻辑错误（Level 9） | 必选，CI 流程强制 Pipeline 阻断 |
| PHPMD | 检查代码异味、复杂性 | 可选，建议加入 Code Review |
| phpcpd | 检测重复代码 | 定期执行（如每次大版本发布前） |
| PhpMetrics | 生成完整的代码质量报告（含圈复杂度、CBO等） | 用于月度复盘 |
| SonarQube | 集成了所有上述功能，能通过“保活时间”估算偿还工期 | 团队级 DevOps 平台 |
| Inspect (PhpStorm) | IDE 内置静态分析，实时显示未被使用的变量、函数、参数 | 开发者本地使用 |
如何解读与行动？
不要只追求一个数字，需要关注债务的严重等级：
-
红区（危险）：
- PHPStan Level 6 错误数 > 100。
- 圈复杂度 > 15 的方法数 > 50。
- 行动：立即停止新功能开发，成立“技术债偿还突击小组”,优先修复静态分析报错和重构复杂函数。
-
黄区（警告）：
- 存在大量“重复代码”（> 10%）。
- 分支覆盖率在 40%-60% 之间。
- 行动：通过 Code Review 逐步引导，将重复代码抽取为 Trait 或 Helper 类，为新功能要求必须写 Unit Test。
-
绿区（健康）：
- 所有 Level 9 错误归零。
- 分支覆盖率 > 80%。
- 行动：持续监控,重点关注新加入的代码是否引入新的债务。
对于 PHP 项目，最核心的度量公式是：
$$技术债务 = \frac{\sum (修复现有问题所需的人天)}{\sum (团队在现有债务下增加新功能所额外消耗的人天)}$$
如果这个比值 > 1，说明还债的 ROI 是正面的,值得去还。
建议：从 PHPStan 或 Psalm 的最高级别开始作为“红线”，一旦 CI 通不过就拒绝合并，这是一个最有效、最清晰的“技术债务还清”起点。
