Restful API实践（一）设计要点

1 概述

针对目前项目中使用的前后端分离开发，越来越感觉到API设计的重要性，而不好的API设计通常让使用者通过URL无法明确知道这个URL到底是干什么用的，并且会显得设计混乱，在此将使用Restful风格设计API进行总结，并对在SpringBoot中具体实现Restful API的设计给出一定示例。

2 Restful API设计

使用Restful API是一种面向资源的设计风格，因此我们每一个URL对应的都是一个资源。从而针对资源的操作我们就可以使用HTTP的相应的请求方式来进行体现。

2.1 版本

应该将API的版本号放入URL中，例如http://localhost:8080/v1/。

2.2 URL定义为名词

在之前我们通常看见/addUser、/editUser这样的URL定义，那么如果我们使用这样的定义就相当于我们放弃了HTTP请求方式（GET,POST,PUT,PATCH,DELETE）等的表达作用。并且我们也知道Restful提倡面向资源的URL路径，所以URL使用名词来进行定义，并且URL路径都是小写。例如：

操作用户资源：http://localhost:8080/v1/user，

操作多个用户资源：http://localhost:8080/v1/users，

操作财务部下的用户资源：http://localhost:8080/v1/accounting-department/user，从这里我们可以学到一点，针对某个资源需要两个单词来进行表达的时候我们可以使用“-”将两个单词连接起来。

2.3 使用HTTP请求方法来表达对资源的操作

上面我们知道了Restful API的URL定义是面向资源的，也就是每一个URL表示的是一种资源，那我我们要表达对资源的相关操作怎么办呢？而且Restful风格也强调了URL必须为名词构成。

这里我们就可以使用HTTP的请求方式来表达对资源的操作了。

GET：获取资源。

POST:创建资源。

PUT:修改资源。

PATCH:修改资源，这里的修改资源和PUT的区别在于这里只向后台传递了修改资源的部分内容，而PUT传递的是全部内容。

DELETE：删除资源。

还有两个不常用的HTTP动词。
HEAD：获取资源的元数据。
OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

2.4 数据传递格式

JSON阅读性更高，扩展性更强，适合各种环境和语言进行解析，现在大的互联网公司，对外提供的API基本都使用JSON。

2.5 使用HTTP状态码

针对请求的响应，我们可以直接利用Http的状态码来表达错误信息，这样也可以很形象地得知每次请求的结果，而不是每次请求都是200，然后再去响应体中获取是否有错误信息，这样响应体没有结果封装，没有额外的传输负担。

针对Http状态码无法表示的异常信息，我们可以增加自定义异常码。增加自定义头字段，Error-Message 表示错误信息，只在出现异常的时候返回。下面的表格内容参考自菜鸟教程。

HTTP状态码共分为5种类型：

分类	分类描述
1**	信息，服务器收到请求，需要请求者继续执行操作
2**	成功，操作被成功接收并处理
3**	重定向，需要进一步的操作以完成请求
4**	客户端错误，请求包含语法错误或无法完成请求
5**	服务器错误，服务器在处理请求的过程中发生了错误

HTTP状态码列表:

状态码	状态码英文名称	中文描述
100	Continue	继续。客户端应继续其请求
101	Switching Protocols	切换协议。服务器根据客户端的请求切换协议。只能切换到更高级的协议，例如，切换到HTTP的新版本协议
200	OK	请求成功。一般用于GET与POST请求
201	Created	已创建。成功请求并创建了新的资源
202	Accepted	已接受。已经接受请求，但未处理完成
203	Non-Authoritative Information	非授权信息。请求成功。但返回的meta信息不在原始的服务器，而是一个副本
204	No Content	无内容。服务器成功处理，但未返回内容。在未更新网页的情况下，可确保浏览器继续显示当前文档
205	Reset Content	重置内容。服务器处理成功，用户终端（例如：浏览器）应重置文档视图。可通过此返回码清除浏览器的表单域
206	Partial Content	部分内容。服务器成功处理了部分GET请求
300	Multiple Choices	多种选择。请求的资源可包括多个位置，相应可返回一个资源特征与地址的列表用于用户终端（例如：浏览器）选择
301	Moved Permanently	永久移动。请求的资源已被永久的移动到新URI，返回信息会包括新的URI，浏览器会自动定向到新URI。今后任何新的请求都应使用新的URI代替
302	Found	临时移动。与301类似。但资源只是临时被移动。客户端应继续使用原有URI
303	See Other	查看其它地址。与301类似。使用GET和POST请求查看
304	Not Modified	未修改。所请求的资源未修改，服务器返回此状态码时，不会返回任何资源。客户端通常会缓存访问过的资源，通过提供一个头信息指出客户端希望只返回在指定日期之后修改的资源
305	Use Proxy	使用代理。所请求的资源必须通过代理访问
306	Unused	已经被废弃的HTTP状态码
307	Temporary Redirect	临时重定向。与302类似。使用GET请求重定向
400	Bad Request	客户端请求的语法错误，服务器无法理解
401	Unauthorized	请求要求用户的身份认证
402	Payment Required	保留，将来使用
403	Forbidden	服务器理解请求客户端的请求，但是拒绝执行此请求
404	Not Found	服务器无法根据客户端的请求找到资源（网页）。通过此代码，网站设计人员可设置"您所请求的资源无法找到"的个性页面
405	Method Not Allowed	客户端请求中的方法被禁止
406	Not Acceptable	服务器无法根据客户端请求的内容特性完成请求
407	Proxy Authentication Required	请求要求代理的身份认证，与401类似，但请求者应当使用代理进行授权
408	Request Time-out	服务器等待客户端发送的请求时间过长，超时
409	Conflict	服务器完成客户端的PUT请求是可能返回此代码，服务器处理请求时发生了冲突
410	Gone	客户端请求的资源已经不存在。410不同于404，如果资源以前有现在被永久删除了可使用410代码，网站设计人员可通过301代码指定资源的新位置
411	Length Required	服务器无法处理客户端发送的不带Content-Length的请求信息
412	Precondition Failed	客户端请求信息的先决条件错误
413	Request Entity Too Large	由于请求的实体过大，服务器无法处理，因此拒绝请求。为防止客户端的连续请求，服务器可能会关闭连接。如果只是服务器暂时无法处理，则会包含一个Retry-After的响应信息
414	Request-URI Too Large	请求的URI过长（URI通常为网址），服务器无法处理
415	Unsupported Media Type	服务器无法处理请求附带的媒体格式
416	Requested range not satisfiable	客户端请求的范围无效
417	Expectation Failed	服务器无法满足Expect的请求头信息
500	Internal Server Error	服务器内部错误，无法完成请求
501	Not Implemented	服务器不支持请求的功能，无法完成请求
502	Bad Gateway	充当网关或代理的服务器，从远端服务器接收到了一个无效的请求
503	Service Unavailable	由于超载或系统维护，服务器暂时的无法处理客户端的请求。延时的长度可包含在服务器的Retry-After头信息中
504	Gateway Time-out	充当网关或代理的服务器，未及时从远端服务器获取请求
505	HTTP Version not supported	服务器不支持请求的HTTP协议的版本，无法完成处理

接下来的文章我们会对SpringBoot中API常用示例进行总结，请参考Restful API实践（二）SpringBoot项目接口设计示例

详尽地设计及使用实例可以参考SpringBoot--Restful API设计示例