Yii 2 REST API 版本化实战指南主版本模块隔离与 Accept 头次版本协商【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址: https://gitcode.com/gh_mirrors/yi/yii2本指南以 Yii 2 官方文档《REST 版本化》对应仓库 docs/guide-ru/rest-versioning.md英文原版见 docs/guide/rest-versioning.md为核心骨架结合框架源码展开。REST API 面向不受你控制的客户端因此版本化是保障向后兼容Backward Compatibility简称 BC的必修课。读完本文你将掌握 Yii 2 推荐的双层版本化策略用独立模块承载每个主版本如v1、v2用Accept请求头协商次版本并学会如何在控制器、资源模型与序列化器中读取版本信息编写条件逻辑。为什么 API 必须版本化Yii 官方文档开宗明义地指出好的 API 必须是版本化的——新功能与变更应当通过新的 API 版本引入而不是在同一个版本上不断改动。原因在于Web 应用的后端与前端代码都在你的掌控之中可以随时同步升级而 API 的消费方是你无法控制的客户端第三方应用、移动端、外部集成方它们可能长期停留在旧版本上。因此API 的向后兼容性应当尽可能保持。如果必须做出破坏兼容性的变更正确做法是把它放进一个新版本的 API中并提升版本号。既有客户端可以继续使用旧版本新客户端则切换到新版本获取新能力。设计版本号时可以参考业界通行的语义化版本Semantic Versioning即 Major.Minor.Patch 三段式思路来规划主版本、次版本与补丁版本的语义边界。两种主流版本化方式的对比文档梳理了业界最常见的两种 API 版本化实现方式它们各有拥趸也各有取舍。方式一URL 路径内嵌版本号将版本号直接嵌入调用 URL例如https://example.com/v1/users即请求 API 版本 1 的/users端点。这种方式直观、易调试、便于缓存与日志分析是历史最悠久也最普及的做法。方式二HTTP 请求头携带版本号把版本号放进 HTTP 请求头通常是Accept头常见有两种写法// 作为参数传递 Accept: application/json; versionv1 // 作为供应商自定义内容类型vendor content type Accept: application/vnd.company.myapp-v1json第一种通过Accept头的参数versionv1声明版本第二种则把版本号编入 MIME 类型形如application/vnd.厂商.应用-v版本格式由 API 供应商自定义。这种方式保持了 URL 的纯净但调试与缓存配置相对复杂。两种方式都有各自的优缺点社区对此争论已久。Yii 官方文档给出的结论是不要二选一而是取二者之长采用一种混合策略。Yii 2 推荐的混合版本化策略Yii 2 官方推荐的实践是把两种方式组合为两层主版本Major放进 URL通过模块隔离将每个主版本的 API 实现放进一个独立模块中模块 ID 就是主版本号例如v1、v2。这样 API 的 URL 天然包含主版本号。次版本Minor放进Accept头通过条件代码响应在每个主版本模块内部用Accept请求头确定次版本号并针对不同次版本编写条件逻辑。这个分层思路的关键在于主版本的隔离是物理级的独立目录、独立类因为主版本之间允许破坏性变更而次版本必须保持 BC因此差异往往只是一些字段或行为上的细微条件判断用Accept头协商即可不需要复制整套代码。按主版本组织代码模块隔离的目录结构针对每个服务主版本的模块模块内应包含服务于该版本的资源类Resource与控制器类。为了更好的职责分离文档建议维护一套公共的基类然后在每个版本模块内对其子类化在子类中实现该版本特有的具体代码例如覆写Model::fields()来定制输出字段。推荐的代码组织方式如下api/ common/ controllers/ UserController.php PostController.php models/ User.php Post.php modules/ v1/ controllers/ UserController.php PostController.php models/ User.php Post.php Module.php v2/ controllers/ UserController.php PostController.php models/ User.php Post.php Module.php要点解读common/存放跨版本共享的基类如UserController、User的基础实现modules/v1/与modules/v2/分别存放两个主版本的控制器与资源模型子类每个版本模块拥有自己的Module.php入口类由于主版本之间代码物理隔离v1 的破坏性改动不会影响 v2同时通过公共基类仍能跨模块复用逻辑。关于fields()方法它是 Yii 资源模型输出字段的开关framework/base/ArrayableTrait.phpframework/base/ArrayableTrait.php中默认实现返回所有公共对象成员变量而framework/base/Model.phpframework/base/Model.php同样声明了该方法。在版本子类中覆写它即可让 v2 输出比 v1 更多的字段或改名后的字段而不影响 v1 的既有输出——这正是版本化资源模型的典型用法。应用配置注册版本模块与 REST 路由规则有了目录结构还需要在应用配置中注册模块并配置urlManager的路由规则才能让https://example.com/v1/users这类 URL 真正路由到对应模块。文档给出的完整配置如下return [ modules [ v1 [ class app\modules\v1\Module, ], v2 [ class app\modules\v2\Module, ], ], components [ urlManager [ enablePrettyUrl true, enableStrictParsing true, showScriptName false, rules [ [class yii\rest\UrlRule, controller [v1/user, v1/post]], [class yii\rest\UrlRule, controller [v2/user, v2/post]], ], ], ], ];关键点拆解modules段声明v1、v2两个模块class指向各自的Module类模块 ID 即 URL 中的主版本段。enablePrettyUrl与enableStrictParsing启用美化 URL 与严格解析保证/v1/users形式的路由能被正确解析而不是落到index.php查询串。yii\rest\UrlRule这是 REST 路由的核心。规则中的controller数组[v1/user, v1/post]中控制器 ID 以模块 ID 为前缀v1/这正是framework/rest/UrlRule.phpframework/rest/UrlRule.php所要求的写法——其文档注释明确说明控制器位于模块内时ID 必须以模块 ID 作为前缀。UrlRule 底层机制自动生成整组 REST 路由从源码看UrlRule继承自CompositeUrlRule并内置了一套 REST 端点模式$patterns属性见 framework/rest/UrlRule.phpHTTP 动词模式路由动作PUT, PATCH{id}update更新DELETE{id}delete删除GET, HEAD{id}view查看详情POST无create创建GET, HEAD无index列表任意{id}options预检任意无options预检同时它还具备两项重要行为自动复数化$pluralize默认trueinit()中通过Inflector::pluralize()把user变为users、post变为posts见 framework/rest/UrlRule.php所以 URL 呈现为复数名词按动词拆分规则createRule()会解析模式中的 HTTP 动词前缀为每个动作生成独立的yii\web\UrlRule实例并绑定对应的路由如v1/user/index。因此上述配置最终产生的效果正如文档所言https://example.com/v1/users返回版本 1 的用户列表https://example.com/v2/users返回版本 2 的用户列表对应地POST /v1/users创建、GET /v1/users/123查看详情等 REST 语义端点也一并生效。得益于模块机制不同主版本的代码得以良好隔离同时通过公共基类与其他共享类模块间依然可以复用代码。仓库中的单元测试 tests/framework/rest/UrlRuleTest.php 对 UrlRule 的路由生成与匹配行为有系统性覆盖可作为深入理解其行为的参考。次版本处理ContentNegotiator 与 acceptParams主版本交给模块隔离后次版本的处理依赖 Yii 的内容协商Content Negotiation能力——即yii\filters\ContentNegotiator行为源码见 framework/filters/ContentNegotiator.php。它有两种挂载方式作为引导组件bootstrap作用于整个应用或作为行为behavior挂在控制器/模块上。在 REST 场景中yii\rest\Controller已经在behaviors()里默认配置了contentNegotiator见 framework/rest/Controller.php支持application/json与application/xml两种格式。ContentNegotiator在判定支持的响应格式时会顺带解析Accept头中的参数并把它们写入响应对象的属性。相关属性定义在 framework/web/Response.php$acceptMimeType从请求Accept头选中的 MIME 类型$acceptParams与该 MIME 类型关联的参数名值对数组例如[q 1, version 1.0]。结合源码中的negotiateContentType()framework/filters/ContentNegotiator.php可以还原完整流程若配置了formatParam默认_format且请求携带该 GET 参数则直接以该参数决定格式否则遍历$request-getAcceptableContentTypes()在formats中查找匹配的 MIME 类型命中后设置$response-format、$response-acceptMimeType $type并把解析出的参数如versionv1赋给$response-acceptParams。于是文档中的示例得到了源码层面的印证如果请求携带Accept: application/json; versionv1内容协商完成后yii\web\Response::acceptParams将包含[version v1]。在业务代码中消费版本信息拿到acceptParams后就可以在动作action、资源类resource class、序列化器serializer等位置编写条件代码。例如在控制器动作中use Yii; public function actionIndex() { $params Yii::$app-response-acceptParams; $version $params[version] ?? v1; // 针对不同次版本返回不同字段或行为 // ... }若需要定制响应序列化方式可以覆写yii\rest\Serializerframework/rest/Serializer.php的serialize()在其中读取acceptParams按版本输出不同的数组结构资源模型层面则可以像上文所述通过覆写fields()实现字段差异。这三个落点动作、资源类、序列化器也正是文档明确列举的条件代码写入位置。版本检查的度何时该开新的主版本文档最后给出了一条重要的工程经验次版本按定义必须保持向后兼容因此期望你的代码中版本号检查不会太多。如果发现代码里充斥着大量版本判断分支那么大概率意味着这些变更实际上已经破坏了 BC——此时正确的做法不是继续在acceptParams里堆条件而是开启一个新的主版本模块。这条建议背后是成本考量次版本协商只需要写少量条件代码维护成本低但条件分支过多会让代码难以阅读和维护。主版本模块隔离虽然成本更高需要复制/子类化控制器与资源类却换来了清晰的边界与绝对的兼容保障。在少量条件判断与新开主版本之间文档给出的取舍标准就是检查过多就该升级主版本了。延伸阅读REST 路由规则详解docs/guide/rest-routing.md俄文版 docs/guide-ru/rest-routing.mdREST 控制器与动作体系docs/guide/rest-controllers.mdREST 资源与字段定制docs/guide/rest-resources.md响应格式协商与序列化docs/guide/rest-response-formatting.md核心实现UrlRuleframework/rest/UrlRule.php、ContentNegotiatorframework/filters/ContentNegotiator.php、Response::acceptParamsframework/web/Response.php【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址: https://gitcode.com/gh_mirrors/yi/yii2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
