JSON Schema 项目中的 BaseConstraint 类签名变更分析

JSON Schema 项目在从5.x升级到6.x版本时，对BaseConstraint类中的addError方法进行了重大变更。这个变更虽然符合语义化版本控制的规范，但确实给升级用户带来了需要特别注意的兼容性问题。

方法签名变更详情

在5.x版本中，addError方法的签名如下：

public function addError(?JsonPointer $path, $message, $constraint = '', ?array $more = null)

而在6.x版本中，该方法被重构为：

public function addError(ConstraintError $constraint, ?JsonPointer $path = null, array $more = []): void

变更带来的主要影响

1. 参数顺序调整：第一个参数从可选的路径变成了必须的错误对象
2. 类型约束加强：新增了ConstraintError类型约束
3. 返回值变化：新增了void返回类型声明
4. 默认值变化：$more参数从可空数组变为空数组默认值

向后兼容解决方案

对于需要同时支持5.x和6.x版本的代码，可以采用运行时检测的方式：

if (class_exists(ConstraintError::class)) {
    // 6.x版本调用方式
    $constraint->addError(new ConstraintError('message'), $path);
} else {
    // 5.x版本调用方式
    $constraint->addError($path, 'message');
}

升级建议

1. 全面检查项目中所有调用addError方法的地方
2. 考虑将相关调用封装到适配器类中
3. 对于复杂项目，建议分阶段升级，先处理兼容层
4. 测试时特别注意错误处理路径的覆盖

这个变更反映了项目向更严格类型约束和更清晰API设计方向的演进，虽然短期内带来升级成本，但从长期看有利于代码质量和可维护性。