RESTful 接口设计规范-个人总结

RESTful 接口设计规范-个人总结

以下接口规范为个人收集并总结，仅供参考。欢迎提供建议

使用名词，使用HTTP 请求方法

接口中不要出现动词，以及动作。

使用HTTP 请求方法作为动作的表达。常见的CRUD，在HTTP 中都有对应的方法，可参考https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Methods

HTTP 请求方法

表格来自：https://www.runoob.com/http/http-methods.html

方法	描述
GET	请求指定的页面信息，并返回实体主体。
HEAD	类似于 GET 请求，只不过返回的响应中没有具体的内容，用于获取报头
POST	向指定资源提交数据进行处理请求（例如提交表单或者上传文件）。数据被包含在请求体中。POST 请求可能会导致新的资源的建立和/或已有资源的修改。
PUT	从客户端向服务器传送的数据取代指定的文档的内容。
DELETE	请求服务器删除指定的页面。
CONNECT	HTTP/1.1 协议中预留给能够将连接改为管道方式的代理服务器。
OPTIONS	允许客户端查看服务器的性能。
TRACE	回显服务器收到的请求，主要用于测试或诊断。
PATCH	是对 PUT 方法的补充，用来对已知资源进行局部更新 。

有以下几种：GET、POST、PUT、DELETE和PATCH。与资源相关联的端点的名称必须与应用的操作相关的HTTP方法对应。

// bad case
GET /get_users
POST /insert_users
PUT /modify_users
DELETE /delete_users

// good case
GET /users
POST /users
PUT /users
DELETE /users

日常开发中不一定能保证完全按照HTTP 请求方法的规范，但至少要保证请求方法使用GET，其他使用POST

全部小写

RFC 3986 将 URI 定义为区分大小写，对于不同环境，大小写 URI 代表不同的路径，为了避免混淆，建议在 URI 中应始终使用小写字母。

// bad case
/Users/12345

// good case
/users/12345

使用斜杠 / 表示层次关系

斜杠/ 通常用于资源的所属关系，后面的属于前面的。这点类似面相对象语言中的.

例如:/users/{userId}/address/ ，{userId}属于users，address属于{userId}

使用连字符 - 提高可读性

如果有多个单词，首先建议是使用/来区分层级关系，如果无法做到，则建议使用-区分

// bad case
/users/{userId}/pendingorders

// good case
/users/{userId}/pending-orders

不要使用下划线_

虽然可以用下划线_ 代替连字符 - 作为分隔符，但有些应用程序的字体，下划线 _ 字符可能会在某些浏览器或屏幕中部分被遮住或完全遮住。

为避免这种混淆，建议使用连字符 - 而不是下划线 _ 。

// bad case
/users/{userId}/pending_orders

// good case
/users/{userId}/pending-orders

不用扩展名

除非直接访问文件，或者下载文件，否则不要使用文件扩展名（例如.xlsx）

如果需要指定内容的格式，建议使用Content-Type。

// bad case
/users/{userId}/pending-orders.xlsx

// good case
/users/{userId}/pending-orders
Content-Type:application/vnd.ms-excel;charset=utf-8;

单数还是复数

如果能唯一确定的资源，则用单数，如果不能，则用复数。

如果单复数都行的，则用复数，因为单数也是复数的特殊形式，为了保持兼容与统一，所以建议复数。

// bad case
GET /user/{userId}
GET /users?sex=man

// good case
GET /users/{userId}
GET /users/{userId}/address

精简

减少无用信息，提高信息密度，

// bad case
GET /service/api/search

// good case
GET /search

不要暴露服务器的技术栈

技术栈包括使用了服务器、中间件、开发语言以及目录和系统结构等。这些建议不要暴露出来，一方面是有安全隐患，另一方面接口使用方也不关心，冗余不符合精简原则

// bad case
/cgi-bin/get_user.php?user=100

// good case
/users?user=100

多条件查询（搜索）

多条件查询时，要求使用?拼接参数查询

例如：/users?location=shenzhen&sex=man 查找位于 shenzhen 的并且sex=man的所有用户

到底用时/还是?

• 只有一个筛选条件，并且能唯一确定对象，则用/，比如/users/{userId}
• 有多个筛选条件，并且不能唯一确定对象，尤其是多条件搜索的情况，就用?比如/users?sex=man

注意：只有一个筛选条件时，这里说的唯一，不仅包括单一对象，也包括集合

比如

• URL“/users/2023/”返回的页面为2023年的存档
• URL“/users/2023/10/”返回的页面为2023年10月的存档

// bad case
GET /users/id={userId}
GET /users/{userId}?sex=man

// good case
GET /users/{userId}
GET /users?localtion=shenzhen&sex=man

例子

// 单个条件，唯一确定
https://www.zhihu.com/people/zhihusucks
https://space.bilibili.com/11083481
https://weibo.com/3266943013

// 多个条件（搜索）
https://www.zhihu.com/search?q=123&type=content
https://www.zhihu.com/search?q=123&type=people

分页与排序支持

分页与排序也当做筛选条件放在?后面

• GET /users?limit=10&offset=0 ：分页，从0行开始返回10条。
• GET /users?limit=10&offset=0&sort=asc&order=title ：排序，返回按名称升序排列的文章记录。

如何表示列表

当没有层次关系时（如在列表中），应该使用分号之类的标点符号或者常见的逗号。

例如：/users/{id1},{id2} 访问多个用户资源。

前端路由与域名相同问题

有时候前端的路由地址会与后端的接口相同，会造成困扰、无法区分到底是前端路由还是后端的接口，调试的时候也会很麻烦。

所以建议有两种方案，后端接口后者统一加/api/，或者后端提供的接口统一使用二级域名api.xx.com

状态码

众所周知，HTTP有自己的状态码，比如下述列表，那我们自己的业务的错误码或者状态码，应该直接复用HTTP的状态码，还是自定义呢？

HTTP 状态码分类

表格来源：https://www.runoob.com/http/http-status-codes.html

HTTP 响应状态码由三个数字组成，第一个数字定义了状态码的类型。

响应分为五类：信息响应(100–199)，成功响应(200–299)，重定向(300–399)，客户端错误(400–499)和服务器错误 (500–599)：

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

结论：业务异常不要使用HTTP的状态码，而要统一放在HTTP 200状态码下面，使用自定义的业务状态码。原因如下

下述结论大部分来自：

https://www.zhihu.com/question/513865370/answer/2643896815

https://www.zhihu.com/question/310737821/answer/585641618

如果业务状态码使用HTTP的状态码，那么会有如下问题

排查困难、分工混乱：一般HTTP的错误码（比如404）都是由服务器或者框架层面抛出的，并且大部分公司的运维与业务开发是分开的，运维只关心服务器层面的异常，业务开发只关心业务异常。如果不区分状态码，那么出现一个404的异常，就无法一眼看出来到底是谁的职责，还得进一步爬log，看错误信息才能确定问题，排查问题困难。如果区分的很清楚，则HTTP状态码的问题直接找运维，自定义的业务异常则直接找业务开发，再具体点就是HTTP200的异常去找业务开发，非HTTP200找运维。

扩展性差：HTTP那点状态码支撑不起众多的业务场景，比如404表示找不到，业务中存在多种找不到的情况，比如“用户找不到”、“订单找不到”、“商品找不到”等情况，如果都用404，那排查问题还是很困难。

运营商劫持：非200状态码（比如404、500）可能会被运营商劫持。或者其他开发人员除了200之外的状态码不认识，还有反向代理或者CDN都有可能有问题

接口出参格式

这里可参考Ant Design Pro的统一规范，这里截取一部分

{
    "success": true,
    "data": {},
    "errorCode": "1001",
    "errorMessage": "error message",
    "showType": 2,
    "traceId": "someid",
    "host": "10.1.1.1"
}

参考

https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Status

https://restfulapi.net/resource-naming/

https://www.runoob.com/http/http-tutorial.html

https://pro.ant.design/zh-CN/docs/request/#%E7%BB%9F%E4%B8%80%E8%A7%84%E8%8C%83

https://www.zhihu.com/question/31363461

https://www.zhihu.com/question/513865370

https://www.zhihu.com/question/310737821