Skip to content
Projects
Groups
Snippets
Help
This project
Loading...
Sign in / Register
Toggle navigation
Y
yii2
Project
Overview
Details
Activity
Cycle Analytics
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Charts
Issues
0
Issues
0
List
Board
Labels
Milestones
Merge Requests
0
Merge Requests
0
CI / CD
CI / CD
Pipelines
Jobs
Schedules
Charts
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Charts
Create a new issue
Jobs
Commits
Issue Boards
Open sidebar
PSDI Army
yii2
Commits
27d45f9b
Commit
27d45f9b
authored
Aug 04, 2014
by
yiichina
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
guide-zh-CN/rest-versioning.md translated.
parent
b7a0ee77
Show whitespace changes
Inline
Side-by-side
Showing
1 changed file
with
105 additions
and
0 deletions
+105
-0
rest-versioning.md
docs/guide-zh-CN/rest-versioning.md
+105
-0
No files found.
docs/guide-zh-CN/rest-versioning.md
0 → 100644
View file @
27d45f9b
版本
==========
你的API应该是版本化的。不像你完全控制在客户端和服务器端Web应用程序代码, 对于API,您通常没有对API的客户端代码的控制权。
因此,应该尽可能的保持向后兼容性(BC),如果一些不能向后兼容的变化必须引入
APIs,你应该增加版本号。你可以参考
[
Semantic Versioning
](
http://semver.org/
)
有关设计的API的版本号的详细信息。
关于如何实现API版本,一个常见的做法是在API的URL中嵌入版本号。
例如,
`http://example.com/v1/users`
代表
`/users`
版本1的API. 另一种API版本化的方法最近用的非常多的是把版本号放入HTTP请求头,通常是通过
`Accept`
头,
如下:
```
// 通过参数
Accept: application/json; version=v1
// 通过vendor的内容类型
Accept: application/vnd.company.myapp-v1+json
```
这两种方法都有优点和缺点, 而且关于他们也有很多争论。
下面我们描述在一种API版本混合了这两种方法的一个实用的策略:
*
把每个主要版本的API实现在一个单独的模块ID的主版本号 (例如
`v1`
,
`v2`
)。
自然,API的url将包含主要的版本号。
*
在每一个主要版本 (在相应的模块),使用
`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
v2/
controllers/
UserController.php
PostController.php
models/
User.php
Post.php
```
你的应用程序配置应该这样:
```
php
return
[
'modules'
=>
[
'v1'
=>
[
'basePath'
=>
'@app/modules/v1'
,
],
'v2'
=>
[
'basePath'
=>
'@app/modules/v2'
,
],
],
'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的用户。
使用模块, 将不同版本的代码隔离。 通过共用基类和其他类
跨模块重用代码也是有可能的。
为了处理次要版本号, 可以利用内容协商
功能通过
[
[yii\filters\ContentNegotiator|contentNegotiator
]
] 提供的行为。
`contentNegotiator`
行为可设置
[
[yii\web\Response::acceptParams
]
] 属性当它确定
支持哪些内容类型时。
例如, 如果一个请求通过
`Accept: application/json; version=v1`
被发送,
内容交涉后,
[
[yii\web\Response::acceptParams
]
]将包含值
`['version' => 'v1']`
.
基于
`acceptParams`
的版本信息,你可以写条件代码
如 actions,resource classes,serializers等等。
由于次要版本需要保持向后兼容性,希望你的代码不会有
太多的版本检查。否则,有机会你可能需要创建一个新的主要版本。
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment