RestFul接口设计

1、背景

随着互联网的发展, 尤其是移动互联为代表的Web3.0时代. 客户端层出不穷, 以APP、微信、PC浏览器为代表, 服务端业务逻辑是基本一致的。那么有没有一种方式可以做到”服务端一次编写, 客户端随时接入”呢?

流行的方案就是"接口编程"

2、接口编程

API（Application Programming Interface,应用程序编程接口），程序之间交互数据的一种方式。

以 浏览器和服务器之间的数据交互（ajax请求） 为例：

请求方式：get方式 post方式

请求协议：http协议 https协议

返回参数格式：普通字符串、json格式、xml格式，现在通用的是json格式

这里的接口，不是面向对象中的interface接口。

数据交互中的接口：实际上，就是通过url请求到的地址中的代码（框架中就是一个控制器的方法）

二、

RESTFul设计风格

1、Rest与RestFul

REST（英文：Representational State Transfer，简称REST），表述性状态转移，指的是一组架构原则。

Restful: 遵守了rest 原则 的web服务或web应用。

2、API设计六要素

资源路径(URI)、HTTP动词(Method)、过滤信息(query-string)、状态码(Status-code)、错误信息(Error)、返回结果(Result)

1）资源路径URI

资源：所有在服务器保存的数据(如:音乐/视频/文章/个人信息...)都是服务器端资源.（项目中资源通常都是指的数据表的一条数据）

URI（Uniform Resource Identifier）：统一资源标志符，包含URL和URN。

URL（Uniform Resource Locator）：统一资源定位符

URN（Uniform Resource Name）：统一资源命名

在HTTP协议中, URI的组成如下：Schema://host[:port]/path[?query-string]

Schema: 使

用的协议类型, 如http/https/ftp等host: 主机域名或IP

port: 端口号(可选)

path: 路径

query-string: 查询参数(可选)

例子:

http://www.tpshop.com/users

https://www.tpshop.com:8080/users?id=100

2）HTTP动词（请求方式）

对于资源, 一般有4个操作, CURD(增/删/改/查)

GET: 从服务器获取资源(一

项或多项)

POST: 在服务器新建一个资源

PUT: 在服务器更新资源, 服务器返回完整的属性

DELETE: 从服务器删除资源

3）过滤信息

通常也叫做请求参数或查询字符串。

4）响应状态码

服务端返回的信息, 用来告诉客户端操作结果。

常见状态码：

GET

200（OK） - 表示已在响应中发出 
204（无内容） - 资源有空表示 
301（Moved Permanently） - 资源的URI已被更新 
303（See Other） - 其他（如，负载均衡） 
304（not modified）- 资源未更改（缓存） 
400 （bad request）- 指代坏请求（如，参数错误） 
404 （not found）- 资源不存在 
406 （not acceptable）- 服务端不支持所需表示 
500 （internal server error）- 通用错误响应 
503 （Service Una

vailable）- 服务端当前无法处理请求

POST

200（OK）- 如果现有资源已被更改 
201（created）- 如果新资源被创建 
202（accepted）- 已接受处理请求但尚未完成（异步处理） 
301（Moved Permanently）- 资源的URI被更新 
303（See Other）- 其他（如，负载均衡） 
400（bad request）- 指代坏请求 
404 （not found

）- 资源不存在 
406 （not acceptable）- 服务端不支持所需表示 
409 （conflict）- 通用冲突 
412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突） 
415 （unsupported media type）- 接受到的表示不受支持 
500 （internal server error）- 通用错误响应 
503 （Service Unavailable）- 服务当前无法处理请求

PUT

200 （OK）- 如果已存在资源被更改 
201 （created）- 如果新资源被创建 
301（Moved Permanently）- 资源的URI已更改 
303 （See Oth

er）- 其他（如，负载均衡） 
400 （bad request）- 指代坏请求 
404 （not found）- 资源不存在 
406 （not acceptable）- 服务端不支持所需表示 
409 （conflict）- 通用冲突 
412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突） 
415 （unsupported media type）- 接受到的表示不受支持 
500 （internal server error）- 通用错误响应 
503 （Service Unavailable）- 服务当前无法处理请求

DELETE

200 （OK）- 资源已被删除 
301 （Moved Permanently）- 资源的URI已更改 
303 （See Other）- 其他，如负载均衡 
400 （bad request）- 指代坏请求 
404 （not found）- 资源不存在 
409 （conflict）- 通用冲突 
500 （internal server error）- 通用错误响应 
503 （Service Unavailabl

e）- 服务端当前无法处理请求

5）错误信息

如果状态码是4xx或者5xx, 需要告诉客户端对应的错误信息. 通常以Json格式返回：

{

    "error": "错误信息",

}

6）返回结果

针对不同的操作, 服务需要返回的结果应该符合这样的规范

GET /collections -- 返

回资源列表(数组)GET /collections/:id -- 返回单个资源 eg. /collections/1

POST /collections -- 返回新生成的资源

PUT /collections/:id -- 返回资源的完整属性

DELETE /collections/:id -- 返回204状态码+空文档

实际开发中，通常会将 状态码、错误信息、返回数据，都放到返回结果中。比如

{"code":200, "msg":"success", "data":{"id":1,"goods_name":"tp"}}

3、RestFul接口设计风格

RESTFul是一种软件设计风格,

主要用于有客户端与服务端交互的软件.

RESTFul 是目前最流行的 API 设计规范，用于 Web 数据接口的设计。

RESTFul风格的数据接口示例：

以新闻资源为例：URI及HTTP动词设计如下

我们thinkphp里面就充分体现了RestFul接口的设计