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协议的版本，无法完成处理

---

作者：ONROAD0612
来源：CSDN
原文：https://blog.csdn.net/ONROAD0612/article/details/82216015
版权声明：本文为博主原创文章，转载请附上博文链接！