PHP-Code-Coverage 中值对象覆盖率的处理实践

在 PHP 项目中，随着 PHP 8.2 引入的 readonly 类特性，开发者现在可以创建非常简单的值对象（Value Objects）。这类对象通常只包含属性和构造函数，没有其他业务逻辑方法。然而，这类简单值对象在代码覆盖率报告中却经常显示为未覆盖状态，给开发者带来了困扰。

值对象覆盖率问题的本质

值对象通常采用构造函数属性提升（Constructor Property Promotion）语法，例如：

readonly class BookResult {
   public function __construct(
      string $title,
      string $author,
      int $numberOfPages,
   ) {}
}

这类类虽然代码简洁，但在代码覆盖率报告中，构造函数会被标记为可执行代码。如果测试中没有创建该类的实例，构造函数就会被报告为未覆盖。这实际上反映了代码覆盖率工具的正确行为，因为从技术角度看，构造函数确实是可执行代码。

解决方案比较

1. 使用 @codeCoverageIgnore 注解

最直接的解决方案是在值对象类上添加 @codeCoverageIgnore 注解：

/**
 * @codeCoverageIgnore 这是一个简单的值对象，无需测试
 */
readonly class BookResult {
   // ...
}

这种方法简单明了，但缺点是需要在每个值对象类上添加注解，可能会让代码显得杂乱。

2. 使用 CoversClass 属性

另一种方法是在使用该值对象的测试类上添加 #[CoversClass] 属性：

#[CoversClass(BookResult::class)]
class SomeServiceTest extends TestCase {
   // 测试中使用 BookResult
}

这种方式更符合"测试应该覆盖它们使用的代码"的理念。当值对象不再被任何测试使用时，它会被正确地报告为未覆盖代码。

3. 命名约定配置

对于大型项目，可以考虑通过配置让覆盖率工具自动忽略特定命名模式的值对象（如后缀为 DTO、Result、Data 等的类）。虽然 php-code-coverage 目前不直接支持这种配置，但可以通过自定义预处理脚本实现类似效果。

最佳实践建议

1. 明确意图：对于纯粹的数据载体类，使用 @codeCoverageIgnore 并添加注释说明这是一个值对象
2. 保持一致性：在团队中统一选择一种处理方式，避免混用不同方法
3. 定期审查：即使忽略值对象的覆盖率，也应定期检查是否真的不再需要测试某些类
4. 文档说明：在项目文档中记录团队对值对象覆盖率的处理约定

技术实现细节

从底层实现来看，代码覆盖率工具（如 Xdebug）会报告所有可执行代码的覆盖情况，包括构造函数属性提升生成的隐式代码。php-code-coverage 作为上层工具，尊重并呈现这些原始数据，而不是自行判断哪些代码"应该"被覆盖。

这种设计虽然有时会带来不便，但保持了工具的准确性和一致性。开发者可以通过上述方法在保持准确覆盖率报告的同时，避免对简单值对象的误报。

总结

处理值对象的代码覆盖率是平衡准确性和实用性的过程。在 PHP 项目中，通过合理使用现有工具提供的注解和属性，开发者可以既保持严格的覆盖率标准，又避免为简单数据结构编写无意义的测试。关键在于团队达成共识并建立一致的代码规范。