[Yii2笔记]074 RESTful的版本控制(Versioning) [ 技术分享 ]

说明

学习Yii Framework 2（易2框架）的过程是漫长的，也是充满乐趣的，以下是我学习Yii2框架时对官网英文资料(请参见原文网址)的翻译和代码实现，提供了较完整的代码，供你参考。不妥之处，请多多指正！

原文网址：

http://www.yiiframework.com/doc-2.0/guide-rest-versioning.html

本文主题：RESTful的版本控制(Versioning)

一个好的API是版本化的：变更或新特性都在API新版本中实现，而不是在同一个版本上不断修改。与Web应用对客户端和服务器端全程控制不同，API仅控制客户端使用的部分。正因如此，应尽可能的保持API向后兼容（BC,backward compatibility）。如果一个变更必须打破向后兼容，你应将其引入API的新版本中，并提升版本号。现存的客户端可以继续使用老版本，API正在工作的版本，新升级的客户端可以使用新API版本中的新功能。

小贴士：关于设计API版本号请参考Semantic Versioning： http://semver.org/

实现API版本化的一个通用方法是将版本号嵌入到API的URL中，例如，http://example/com/v1/users表示1版本的/users端点（endpoint）。 API版本化的另一个方法是，也是最近增长势头很好的一个方法，将版本号放在HTTP请求头中，比较典型的作法是通过Accept头信息实现：

//使用一个参数
Accept:application/json;version=v1
//使用一个供应商内容类型（vendor content type）
Accept:application/vnd.company.myapp-v1+json

两种方法各有利弊，对每种方法都有很多争论。接下来你会看到一些API版本策略，它们是两种方法的综合： 1、在不同的模块中存放API实现的主版本，模块的ID是主版本号（如:v1、v2）。这样，API的URL将包含主版本号。 2、在每个主版本中（也就是在对应的模块中），使用Accept的HTTP请求头信息来决定次版本号，并编写条件代码来响应相应的次版本。

因为每个模块服务一个主版本，模块将包含资源和控制器类为相应的版本服务。为了更好的分离代码职责，你可以保留一组通用的基础资源和控制器类，然后在每个独立的版本模块中编写子类，在这些子类中，完成实际的代码，如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
			Modules.php
		v2/
			controllers/
				UserController.php
				PostController.php
			models/
				User.php
				Post.php
			Modules.php

应用配置：

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']],
			],
		],
	],
];

由上述代码，http://example.com/v1/users将返回版本1中的用户列表，http://example.com/v2/users将返回版本2的用户列表。

因为模块设计，不同的主版本可以被完全分离。但各模块之间仍然可以使用公共基础类或其他共享资源实现代码复用。

要处理次版本号，你可以使用contentNegotiator行为提供的内容协商特性。当要确定提供哪种类型的内容时，内容协商行为将设置yii\web\Response::$acceptParams属性 。

例如，如果发送一个请求附带的头信息是Accept:application/json;version=v1，经过内容协商后，yii\web\Response::$acceptParams 将被赋值['version'=>'v1']。 基于acceptParams中的版本信息，你可以在需要的位置（如动作、资源类、序列化器等）编写条件代码，以提供恰当的功能。 因为定义的次版本号需要向后兼容，所以并不希望在代码中有太多的版本检测，否则，太多的修改使你不得不创建一个新的主版本。

（全文完）