Yii 2 后向兼容性（BC）承诺解读：从补丁发布到类、接口与常量变更的完整兼容性清单

Yii 2 后向兼容性BC承诺解读从补丁发布到类、接口与常量变更的完整兼容性清单【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址: https://gitcode.com/gh_mirrors/yi/yii2Yii 2 以「快速、安全、专业」著称而其长生命周期框架的另一项核心承诺便是后向兼容性Backwards CompatibilityBC。本文基于仓库内 docs/internals-ja/bc.md即官方 docs/internals/bc.md 的日文版展开系统整理 Yii 2 在补丁、次要、主要三种发布级别下的 BC 策略并以表格形式给出「使用方视角」与「开发方视角」下各类接口、类、方法、属性、常量变更的兼容性判定同时结合仓库源码与发布文档UPGRADE.md、CHANGELOG.md印证这些规则的落地方式。读完本文你将能判断一次 API 变更是否会破坏既有应用也能在升级或贡献代码时遵循 Yii 官方的 BC 纪律。一、BC 承诺的总体原则Yii 2 的 BC 承诺分为两个层次原文的表述非常清晰我们严格保证补丁发布patch releases形如2.x.y.Z不破坏后向兼容性同时努力避免次要发布minor releases形如2.x.Y中出现需要用户修复代码的不兼容变更。换句话说补丁发布只含 bug 修复必须 100% 后向兼容用户可以放心升级次要发布以 bug 修复和功能增强为主要求“几乎后向兼容”允许极少数例外但必须在UPGRADE.md中记录主要发布如2.1.0允许破坏 BC但必须提供完整升级指南UPGRADE-2.X.md。版本编号与发布流程的完整约定见 docs/internals/versions.md其中明确指出 Yii 的版本策略是 Semantic Versioning 的一个变体版本号格式为2.x.y.z当z为0时可省略。当前仓库framework/composer.json中dev-master的branch-alias为2.0.x-dev印证了 master 分支正是 2.0.x 系列这一事实。二、使用方视角你的代码在升级后还安全吗这一部分面向应用开发者——你只是“使用”框架通过类型提示、继承、调用等方式消费框架的 API。下表是 bc.md 原文的完整整理Yes表示该用法受 BC 保护No表示不承诺兼容升级时可能被破坏。2.1 接口Interface的使用使用场景是否后向兼容用接口做类型提示type hintYes调用接口方法Yes实现该接口并且……实现接口方法Yes给已实现的方法新增参数Yes给参数添加默认值Yes对使用方而言只要你不是直接以“实现接口”的方式与框架耦合接口层面的变更几乎不会影响你。真正危险的是下面要讲的类继承。2.2 类Class的使用使用场景是否后向兼容用类做类型提示Yes创建新实例newYes继承该类Yes访问公有public属性Yes调用公有方法Yes继承该类并且……访问受保护protected属性Yes调用受保护方法Yes覆盖公有属性Yes覆盖受保护属性Yes覆盖公有方法Yes覆盖受保护方法Yes新增属性与父类同名冲突No新增方法与父类同名冲突No给覆盖的方法新增参数Yes给参数添加默认值Yes通过反射Reflection调用私有方法No通过反射访问私有属性No理解这张表的关键在于**“覆盖override”与“新增add”的语义区别**当你覆盖一个公有/受保护方法或属性时只要不改变签名与可见性升级是安全的当你“新增”的属性或方法与框架未来版本中新引入的成员同名时就会产生冲突——这就是标No的原因通过反射触碰private成员属于框架明确不承诺的边界一旦框架内部重构私有实现你的反射代码就会失效。从源码结构看Yii 2 大量依赖继承机制例如yii\base\Component、yii\base\Model是绝大多数框架类与用户模型类的祖先因此这套“覆盖安全、新增有风险、反射不承诺”的边界划分正是框架能够在 2.0.x 系列上长期演进而不破坏用户应用的设计基石。三、开发方视角框架维护者如何修改 API 而不破坏世界这一部分面向框架贡献者与扩展开发者——你负责修改框架或扩展的公共 API。表格中Yes表示该变更被允许且不破坏 BCNo表示会破坏 BC、应避免或在主要版本中才能实施。3.1 接口Interface的变更变更类型是否后向兼容删除接口No修改名称或命名空间No新增父接口若未新增方法则 Yes删除父接口No接口方法新增方法No删除方法No重命名方法No移动到父接口Yes新增无默认值参数No新增带默认值参数No删除参数Yes仅限末尾一个或多个给参数添加默认值No删除参数的默认值No给参数添加类型提示No删除参数的类型提示No改变参数类型No改变返回类型No常量新增常量Yes删除常量No修改常量值除“可能被序列化的对象”外 Yes且必须在 UPGRADE.md 中记录注意接口方法与类方法的规则并不完全一致对接口方法即使带默认值也不允许新增参数因为接口契约要求所有实现类同步修改而类方法则要看场景见下文。3.2 类Class的变更变更类型是否后向兼容删除类No改为finalNo改为abstractNo修改名称或命名空间No修改父类Yes但原父类必须保留为该类的祖先类新增接口Yes删除接口No公有属性新增公有属性Yes删除公有属性No降低可见性No移动到父类Yes受保护属性新增受保护属性Yes删除受保护属性No降低可见性No移动到父类Yes私有属性新增私有属性Yes删除私有属性Yes构造函数删除构造函数No降低公有构造函数可见性No降低受保护构造函数可见性No移动到父类Yes公有方法新增公有方法Yes删除公有方法No重命名No降低可见性No移动到父类Yes新增无默认值参数No新增带默认值参数No删除参数Yes仅限末尾一个或多个给参数添加默认值No删除参数的默认值No给参数添加类型提示No删除参数的类型提示No改变参数类型No改变返回类型No受保护方法新增受保护方法Yes删除受保护方法No重命名No降低可见性No移动到父类Yes新增无默认值参数No新增带默认值参数No删除参数Yes仅限末尾一个或多个给参数添加默认值No删除参数的默认值No给参数添加类型提示No删除参数的类型提示No改变参数类型No改变返回类型No私有方法新增私有方法Yes删除私有方法Yes重命名Yes新增参数无论有无默认值Yes删除参数Yes添加/删除参数的默认值Yes添加/删除参数的类型提示Yes改变参数类型Yes改变返回类型Yes静态方法非静态改为静态No静态改为非静态No常量新增常量Yes删除常量No修改常量值除“可能被序列化的对象”外 Yes且必须在 UPGRADE.md 中记录这张表传达出 Yii 2 的兼容性设计哲学可见性是一种契约任何“降低可见性”的操作public → protected → private都是破坏性变更私有成员是自由的private 属性与方法属于实现细节可以随意增删改这也是框架内部重构的主要空间参数与返回类型不可收紧新增参数即使带默认值、添加类型提示、改变返回类型都会被标记为No因为这会破坏覆盖override该方法的用户子类删除参数只允许“末尾”的PHP 允许调用方传入多余参数而不报错因此删除末尾参数相对安全但删除中间参数会打乱位置传参静态/非静态切换绝不允许调用方式完全不同会直接导致致命错误常量值变更需谨慎只有当常量值会被序列化例如用于持久化存储时才禁止修改否则允许但必须在UPGRADE.md中注明。四、BC 规则的落地证据UPGRADE.md 与 CHANGELOG.mdBC 政策不是空谈它通过仓库中的两份文档制度化地落地framework/UPGRADE.md逐版本记录“可能破坏应用的变更”例如从 2.0.53 起最低 PHP 版本提升到 7.4、移除XCache与ZendDataCache缓存组件从 2.0.55 起查询构造器会对同名参数重命名、ActiveForm的客户端校验不再延迟 200 毫秒、AttributeTypecastBehavior不再自动识别带when条件的验证器等。这些都是 bc.md 中“例外必须在 UPGRADE.md 记录”规则的直接体现framework/CHANGELOG.md按发布版本与 issue 编号组织变更条目Bug/Enh配合 docs/internals/pull-request-qa.md 中“PR 必须包含 CHANGELOG 条目”的要求保证每次 API 变更都有迹可循。UPGRADE.md 还给出了用户侧的实际升级操作修改composer.json后执行composer update yiisoft/yii2或composer require yiisoft/yii2:~2.0.x --update-with-dependencies升级完成后应运行测试验证应用行为。五、BC 与版本、分支、发布流程的配合bc.md 开篇即指向 docs/internals/versions.md两者共同构成 Yii 2 的版本治理体系补丁发布2.x.y.Z只含 bug 修复、必须 100% BC、周期 12 周、无需预发布版本发布过程基本自动化唯一允许破坏 BC 的例外是安全问题的修复次要发布2.x.Y以 bug 修复与增强为主、应保持“几乎 BC”极少数例外记入 UPGRADE.md周期 12 个月无预发布主要发布2.X.0可破坏 BC需UPGRADE-2.X.md升级指南与 alpha/beta/rc 预发布周期约 12 个月以上分支策略master承载当前稳定版2.0.x新主版本在2.n分支开发稳定后从 master 切出2.(n-1).x维护分支维护分支变更持续合并回 master。发布流程本身已由build目录下的发布控制命令自动化详见 docs/internals/release.md 中对release framework/release app-basic等命令的描述从而在工程上保证“补丁发布自动、主版本谨慎”的节奏与 BC 承诺一致。六、常见误用与避坑要点不要在用户子类中新增可能与框架未来成员重名的属性/方法bc.md 明确标注“新增属性/新增方法”为No因此框架开发者给类新增公有/受保护成员是安全的Yes但用户自定义子类反过来却可能因此产生命名冲突——这是 BC 规则不对称性的典型体现不要依赖反射访问私有成员框架重构私有实现是允许且常见的这类代码必然随升级而失效不要指望带默认值的新增参数是安全的对接口与类方法新增参数即便带默认值都会破坏覆盖该方法的所有实现升级前阅读 UPGRADE.md 的累积说明其说明是累积式的——从 A 升级到 C 若中间经过 B需要同时遵循 A、B 两段的指引。七、总结Yii 2 的后向兼容性策略可以用三句话概括补丁发布 100% 兼容、次要发布几乎兼容、主要发布才允许破坏使用方只要避免“新增成员命名冲突”与“反射触碰私有成员”两类高风险用法就能平稳跟随 2.0.x 的演进开发方则须严守“可见性不降低、签名不收紧、私有成员可自由重构、破坏性变更必记入 UPGRADE.md”的纪律。这套规则既是框架长寿的保障也是所有 Yii 应用与扩展升级无痛的前提。【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址: https://gitcode.com/gh_mirrors/yi/yii2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考