前端工程化系列（一）——设计RESTful风格API

1. REST

REST(Representational State Transfer，表征性状态转移)。其与技术无关，是一种软件架构风格。

REST的六大特点：

客户端/服务器（Client/Server）

C/S架构中的关注点分离：

• 服务端专注数据存储，提升了简单性；
• 前端专注用户界面，提升了可移植性；

无状态（Stateless）

所有的用户会话信息均保存在客户端，每次请求必须包含所有信息，不能依赖上下文信息；
服务端不用保存会话信息，提升了简单性、可靠性、可见性。

缓存（Cache）

所有服务端响应都要被标记为可缓存或不可缓存。其可以减少前后端交互，提升性能。

统一接口（Uniform Interface）

接口设计尽可能统一通用，提升了简单性、可见性。

接口与实现解耦，使前后端可以独立开发迭代。

分层系统（Layered System）

每一层只能了解相邻的一层。

其他层包括：安全层、负载均衡、缓存层等等。

按需代码（Code ON Demand）

客户端可以下载运行服务端传来的代码（如JS）；

其可以减少一些功能，简化客户端。

2. 统一接口限制

REST是资源的表述，资源可以是可以命名的事物，其可以是实体，也可以是抽象的概念（均用名词形式表述）。

每一个资源都可以通过URI(Uniform Resource Identifier，统一资源标识符)被唯一标识。

通过表述操作资源

表述为REST中的Representational，即资源在外界的具体呈现，因此资源可以有多种表述形式（如：JSON、XML等等），在客户端和服务端之间传输的是资源的表述。

资源的表述通常包括数据和描述数据的元数据。例如：HTTP头中的“Content-Type”为描述数据的元数据，告知客户端资源的表述形式。

因此客户端不能直接操作（如：SQL）服务端资源，应该通过表述（如：JSON）来操作服务端资源。

自描述信息

每个消息（请求或响应）必须提供足够的信息让接受者理解。如：

• 媒体类型（application/json、application/xml）
• HTTP方法（GET进行查询、POST进行新增、DELETE进行删除）
• 是否缓存（Cache-Control）

3. RESTful API

RESTful 的核心思想就是，客户端发出的数据操作指令都是"动词 + 宾语"的结构。比如，GET /articles这个命令，GET是动词，/articles是宾语。

GitHub RESTful API 简介

设计规范：

• API与客户端的通信协议，尽量使用HTTPS协议；
• 尽量将API部署在专用域名上（存在跨域问题）；
• 可设置API版本；
• URL路径中，尽可能使用名词表示；
• 五种常见的请求方法；
• 通过URL上传递参数来传递搜索条件；
• 状态码（请求返回状态码）；
• 错误处理（请求返回错误信息）；
• 返回值（针对不同请求返回不同返回值）；
• Hypermedia API；

4. 设计请求

其中动词通常为五种HTTP方法，对应对资源进行CURD操作：

• GET：读取（Read）
• POST：新建（Create）
• PUT：更新（Update）
• PETCH：部分更新（Update）
• DELETE：删除（Delete）

URL设计：

• URI使用名词，尽量使用复数，如：用户使用/users；
• URI使用嵌套表示关联关系，如：用户admin的信息/user/admin/info；
• 避免多级URL，除第一级，其他级别用查询字符串来进行表达；
• 可以使用_或者-使URI可读性更好；
• 可以使用/来表示资源的层级关系；
• 可以使用?过滤资源；
• 可以使用,、;或者...表示同级资源的关系；

5. 设计响应

响应部分主要由三部分组成：

• 返回状态码
• 返回信息描述
• 返回值

{
	code:integer,
	message:string,
	data:object
}

code状态码

常见HTTP状态码：

• 200：请求成功
• 301：资源被永久转移到其它URL
• 404：请求的资源不存在
• 500：内部服务器错误

分类	区间	分类描述
1xx	100~199	相关信息：服务器收到请求
2xx	200~299	操作成功：操作被成功接收并处理
3xx	300~399	重定向：需要进一步操作完成请求
4xx	400~499	客户端错误，请求包含错误或无法完成请求
5xx	500~599	服务器错误，服务器在请求的过程中发生了错误

API不要1xx状态码

2xx

表示操作成功，不同方法可以返回不同的状态码：

• GET：200 OK
• POST：201 Created
• PUT：200 OK
• PATCH：200 OK
• DELETE：204 No Content

201表示生成了新的资源；204表示资源不存在；202表示服务器收到请求，但还未进行处理，会在未来再处理，通常用于异步操作。

3xx

API用不到301状态码（永久重定向）和302状态码（暂时重定向，307也是这个含义），因为它可以由应用级别返回，浏览器可以直接跳转，API级别可以不考虑这两种情况。

API主要用到的是303状态码，它与302、307的含义一样，也就是“暂时重定向”，区别在于302和307用于PUT请求，而303用于POST、PUT和DELETE请求。收到303以后，浏览器不会自动跳转，而由用户自己决定下一步选择。

4xx

客户端错误：

• 400：服务器不理解客户端的请求，未做任何处理；
• 401：用户未提供身份验证凭据，或者没有通过身份验证；
• 403：用户通过了身份验证，但不具备访问资源所需的权限；
• 404：所请求的资源不存在或不可用；
• 405：用户已通过身份验证，但是所用的HTTP方法不在他的权限范围之内；
• 410：所请求的资源，已从此地址转移，不可再用；
• 415：客户端要求返回的格式不对；
• 422：客户端上传的附件无法处理，导致请求失败；
• 429：客户端的请求次数超过限制；

5xx

API不会向用户透露服务器的详细信息，所以只需要两个状态码：

• 500：客户端请求有效，但是服务器处理时发生了意外；
• 503：服务器无法处理请求，一般用于网站维护时；

message 返回信息描述

建议将此信息与状态码进行一一对应，便于维护。

data 返回值

通常使用JSON格式，返回数据体。