ThinkPHP5 RESTful API开发版本控制

thinkphp5 RESTful api开发版本控制,thinkphp官方文档不是很详细，我根据个人经验分享下。

我们以一个用户信息读取的接口为例，包含两个版本V1和V2，v2版本的接口包括用户的档案信息，统一使用json格式数据输出到客户端。

在application目录下面创建api模块目录，并创建controller和model子目录，因为api接口无需视图，所以不需要创建view目录。

api版本号可以在请求头、参数、URL路由参数中传入，以下是tp5.X中使用方法。

第一种：URL路由传入方式（推荐）

在route.php路由文件中配置，如下

return [// api版本路由'api/:version/:controller'=>'api/:version.:controller/index',// 省略方法名时'api/:version/:controller/:function'=>'api/:version.:controller/:function'// 有方法名时];

不同版本的URL访问地址为：

http://tp5.com/api/v1/user/10
http://tp5.com/api/v2/user/10

版本号中不能包含.符号。

第二种：请求头传入方式

在route.php路由文件中配置，如下

$v = request()->header('version');
if($v==null) $v = "v1";
return [//api版本控制'api/:controller$'=>['api/'.$v.'.:controller/index',['method' => 'get']],'api/:controller/:function$'=>'api/'.$v.'.:controller/:function',//资源路由'__rest__'=>[//api'api/house'=>['api/'.$v.'.house',['only'=>['index','read','update','delete']]],'api/book'=>['api/'.$v.'.book',['only'=>['index','read','save','delete']]],'api/book_rent'=>['api/'.$v.'.book_rent',['only'=>['index','read','save']]],]
]

第三种：请求参数传入方式

和请求头方式类似，这里不再累述。

控制器实现

v1版本控制器（类文件位置为application/api/controller/v1/User.php）代码如下：

namespace app\api\controller\v1;use app\api\model\User as UserModel;class User
{// 获取用户信息public function read($id = 0){$user = UserModel::get($id);if ($user) {return json($user);} else {return json(['error' => '用户不存在'], 404);}}}

v2版本的控制器（类文件位置为application/api/controller/v2/User.php）代码如下：

namespace app\api\controller\v2;use app\api\model\User as UserModel;class User
{// 获取用户信息public function read($id = 0){$user = UserModel::get($id, 'profile');if ($user) {return json($user);} else {return json(['error' => '用户不存在'], 404);}}}

最后项目的目录结构（优雅的目录结构，尤其喜欢tp5这个目录结构）：

RESTFul

REST(Representational State Transfer表述性状态转移)是一种针对网络应用的设计和开发方式，可以降低开发的复杂性，提高系统的可伸缩性。REST提出了一些设计概念和准则：

1、网络上的所有事物都被抽象为资源（resource）；
2、每个资源对应一个唯一的资源标识（resource identifier）；
3、通过通用的连接器接口（generic connector interface）对资源进行操作；
4、对资源的各种操作不会改变资源标识；
5、所有的操作都是无状态的（stateless）。

REST通常基于使用HTTP，URI，和JSON以及HTML这些现有的广泛流行的协议和标准。

传统的请求模式和REST模式的请求模式区别：

作用	传统模式	REST模式
列举出所有的用户	GET /users/list	GET /users
列出ID为1的用户信息	GET /users/show/id/1	GET /users/1
插入一个新的用户	POST /users/add	POST /users
更新ID为1的用户信息	POST /users/update/id/1	PUT /users/1
删除ID为1的用户	POST /users/delete/id/1	DELETE /users/1

关于更多的REST信息，可以参考：http://zh.wikipedia.org/wiki/REST

标识	请求类型	生成路由规则	对应操作方法（默认）	描述
index	GET	`blogs`	index	显示列表
create	GET	`blogs/create`	create	新增页面
save	POST	`blogs`	save	保存内容
read	GET	`blogs/:id`	read	查看内容
edit	GET	`blogs/:id/edit`	edit	编辑页面
update	PUT	`blogs/:id`	update	更新内容
delete	DELETE	`blogs/:id`	delete	删除

上面的7个路由规则，在本示例中仅使用了5个（其中create和edit页面由于本API接口测试暂时不需要使用）。

`REST`请求测试

REST请求的测试方式有很多，下面介绍两种常用的方式：

Postman

最方便的方法就是通过Postman来测试接口，给Chrome浏览器安装一个postman扩展，访问下面地址获取官方扩展：https://www.getpostman.com/

安全建议

尽量采用HTTPS协议进行接口请求；
重要的功能加密传输；
做好接口的身份认证；
对URL中的参数做好安全过滤；
对接口请求做好请求速率限制；
重要ID不透明处理；
使用JSON格式返回数据；

详细可以参考《REST API 安全设计指南》