Restful Api 路径定义规则

Posted 2023-05-04

参考技术A

前言

目前网站上已经有很多关于如何去写restful风格的api的文章，主要说明下我接下来写的关于api写法的连载文章的目的，一个是主要把自己在这方面的心得分享给大家，二是希望大家也能给出更好的意见、建议，欢迎在看文章后讨论。

本篇文章主要说下接口路径该怎么定义，一个URL地址的可读性对于调用者和维护者都是很重要的，当你规划好URL该怎么定义后，这也决定了java项目中你的controller类的划分，我们知道一个HTTP接口通常主要结构为： 协议://域名/应用content path/自定义路径?查询参数，例如： https://api.zhuma.com/zm-back/users?pageSize=10&pageNum=1 代表筑码网后台管理用户功能的API。

那我们到底该怎么定义我们的API URL会更好一些呢？下面给出几点建议。

若域名无法区分出是api还是页面功能的时候，api路径后面统一加/api用于区分是接口服务。

1. https://back.zhuma.com/api/login

2. https://api-back.zhuma.com/login

上面举例中back代表着后台管理的意思，所以想要进入后台管理页面路径应该为： https://back.zhuma.com 前台当然要留给 https://www.zhuma.com ，在域名使用中我们可以利用三级域名对我们整体系统大的功能或应用进行很好的划分，正是因此，我们看到举例中路径上并没有加上应用的content path。

★ 备注

建议通过域名去区分api，也就是举例中2的方式

在开发中对于多环境开发我们也可以通过域名来区分，例如：

https://fe-api-back.zhuma.com 为联调环境，

https://qa-api-back.zhuma.com 为QA测试环境，

https://stg-api-back.zhuma.com 为仿真环境，

https://api-back.zhuma.com 为生产环境等。

定义自定义路径部分时，使用名词的复数形式定义一个资源，如若有动词词性在url中考虑以下划线区分。

基本操作

GET /users # 获取用户列表

GET /users/userId # 查看某个具体的用户信息

POST /users # 新建一个用户

PUT /users/userId # 全量更新某一个用户信息

PATCH /users/userId # 选择性更新某一个用户信息

DELETE /users/userId # 删除某一个用户

批量操作

POST /users/_mget # 批量获取多个用户

POST /users/_mcreate # 批量创建多个用户

POST /users/_mupdate # 批量更新多个用户

POST /users/_mdelete # 批量删除多个用户

POST /users/_bulk # 批量功能组装（后面会讲到）

动词词性加入url （原则上此种情况是不被推荐的）

GET /users/_search # 搜索用户

POST /users/_init # 初化所有用户

★ 备注

这里可能有人会纠结路径参数/users/userId 是使用userId还是id，毕竟当前资源只有一级，此处不必纠结，原因是：这仅仅是一个后端使用变量而已，不会影响前端的使用，所以我们统一使用userId这种形式定义变量

批量操作时，统一使用POST作为HTTP METHOD，原因是 批量操作参数的数据大小不可控，使用request param可能超过某些浏览器对参数的长度限制，实际上，URL不存在参数长度上限的问题，HTTP协议规范没有对URL长度进行限制，这个限制是特定的浏览器及服务器对它的限制。

这里注意一个小点，URL路径是对大小写敏感的，例如：/users 和 /Users 是两个接口哦，但是我们规定URL全部小写。

URL区分功能（管理、我的 功能）

上面我们提到的 关于/users 用户功能的举例，通常情况下，这其实是一个管理用户资源的功能的接口，用于表示对用户这个资源的增删改查等管理功能。

那 我的 功能是指的什么呢？

通常来说，是对于前端用户下的某某资源的说明，我们通常定义为my-开头。

举例

GET /my-orders 我的订单列表

GET /users/userId/orders 管理查看某一个用户下的订单列表

1. 路径中多个单词时，使用中划线 - 来连接

2. 不允许在路径中出现大写字母（查询参数名称除外）

3. 接口后省略xxx.do（很多人愿意加上.do这种形式，注意我们的每一个url代表的是一个资源哦）

举例

GET /my-account/profile 获取我的账户的简要信息

GET /my-notifications 获取我的消息列表

★ 备注

上面的举例我们看到，my-account是单数而不是复数形式，这里说明下，在系统中如果明确该信息就是单数，那我们在url定义时也应该使用单数表示。

参考：

Restful Api写法心得之一《路径定义篇》

RESTful API

什么是RESTful?

Representational State Transfer(表象层状态转变),是一种架构方式的约束和规则。在实际应用中，API开发可以参考RESTful的标准但是也没必要完全遵守。

在实际工作中，RESTful对api接口规范，命名规则，返回值，授权验证等做了一定的约束，一般的项目， api只要易测试，足够安全，风格一致，可读性强，没有歧义，方便调用就足够了。

RESTFUL特点包括：

1、每一个URI（Uniform Resource Identifier）代表1种资源；（服务器上所有的东西都抽象成一个资源）

2、客户端使用GET、POST、PUT、DELETE4个表示操作方式的动词对服务端资源进行操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源；（客户端不直接对服务器端的资源进行操作，而是通过前端服务器视图，然后前段视图再调用服务器资源）

3、通过操作资源的表现形式来操作资源；(资源的表述就是资源的格式，是HTML、XML、JSON、纯文本、图片等等，可以用各种各样的格式来表述你获取到的资源)

4、REST必须通过统一的接口对资源进行操作

HTTP1.1协议定义了资源的统一接口：

·GET/POST/PUT/DELETE/PATCH/HEAD/OPTIONS

`HTTP  HEAD可以自定义

·HTTP STATUS响应状态 可自定义

·一套标准的内容协商机制

·一套标准的缓存机制

·一套标准的客户端身份认证机制

5、客户端与服务端之间的交互在请求之间是无状态的，从客户端到服务端的每个请求都必须包含理解请求所必需的信息。