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 安全设计指南》