关于RESTful一些注意事项,和自己整理的接口开发规范

本文档详细介绍了RESTful API的设计规范,包括URI规范、版本管理、请求与响应的处理方式、错误处理等方面,旨在帮助开发者更好地理解和应用RESTful原则。

摘要生成于 C知道 ,由 DeepSeek-R1 满血版支持, 前往体验 >

最近在研究restful,公司开发要使用,所以自己就去网上找了好些资料,并整理了一套公司开发的接口规范。当然,我也只是刚刚入坑。还不是很全面。但是这就是一个过程。一点点,总会好起来的。以下是就是RESTful接口规范:

一、   URI

URI规范

1.不用大写;

2.用中杠 - 不用下杠 _ ;

3.参数列表要encode;

4.URI中的名词表示资源集合,使用复数形式。

5.在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词(特殊情况可以使用动词),而且所用的名词往往与数据库的表格名对应。

 

资源集合 vs单个资源

URI表示资源的两种方式:资源集合、单个资源。

资源集合:

       /zoos //所有动物园

       /zoos/1/animals //id1的动物园中的所有动物

单个资源:

       /zoos/1//id1的动物园

       /zoos/1;2;3//id123的动物园

 

避免层级过深的URI

在url中表达层级,用于 按实体关联关系进行对象导航 ,一般根据id导航。

过深的导航容易导致url膨胀,不易维护,如 GET /zoos/1/areas/3/animals/4 ,尽量使用查询参数代替路径中的实体导航,如 GET/animals?zoo=1&area=3 ;

 

 

二、   版本

应该将API的版本号放入到URI中

           https://api.example.com/v1/zoos

 

 

三、 Request

HTTP方法

通过标准HTTP方法对资源CRUD:

GET:查询(从服务器取出资源一项或多项)

GET /zoos

GET /zoos/1

GET/zoos/1/employees

POST:创建单个新资源。 POST一般向“资源集合”型uri发起

POST/animals  //新增动物

POST/zoos/1/employees //为id为1的动物园雇佣员工

PUT:更新单个资源(全量),客户端提供完整的更新后的资源。与之对应的是 PATCH,PATCH负责部分更新,客户端提供要更新的那些字段。 PUT/PATCH一般向“单个资源”型uri发起

PUT/animals/1

PUT /zoos/1

DELETE:删除

DELETE/zoos/1/employees/2

DELETE/zoos/1/employees/2;4;5

DELETE/zoos/1/animals  //删除id为1的动物园内的所有动物

HEAD / OPTION/ PATCH用的不多,就不多解释了。

HEAD:获取资源的元数据

OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的

PATCH:在服务器更新资源(客户端提供改变的属性)

 

安全性和幂等性

1.     安全性 :不会改变资源状态,可以理解为只读的;

2.     幂等性 :执行1次和执行N次,对资源状态改变的效果是等价的。

.

安全性

幂等性

GET

POST

×

×

PUT

×

DELETE

×

安全性和幂等性均不保证反复请求能拿到相同的response。以 DELETE为例,第一次DELETE返回200表示删除成功,第二次返回404提示资源不存在,这是允许的。

复杂查询

查询可以捎带以下参数:

.

示例

备注

过滤条件

?type=1&age=16

允许一定的uri冗余,如 /zoos/1 与 /zoos?id=1

排序

?sort=age&order=asc

指定返回结果按照哪个属性排序,以及排序顺序

投影

?whitelist=id,name,email

分页

? page=2&per_page=100

指定第几页,以及每页的记录数

Bookmarker

经常使用的、复杂的查询标签化,降低维护成本。

如:GET /trades?status=closed&sort=created,desc

快捷方式:GET /trades#recently-closed或者GET /trades/recently-closed

状态码

    服务器向用户返回的状态码和提示信息,常见的有以下一些(方括号中是该状态码对应的HTTP动词)。

§200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。

§201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。

§202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)

§204 NO CONTENT - [DELETE]:用户删除数据成功。

§400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。

§401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。

§403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。

§404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。

§406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。

§410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。

§422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。

§500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。

状态码的完全列表参见这里

 

URI失效

随着系统发展,总有一些API失效或者迁移,对失效的API,返回404 not found 或 410 gone;对迁移的API,返回301重定向。

 

四、Response

1.    不要包装:

response的 body 直接就是数据,不要做多余的包装。错误示例:

{

   "success":true,

   "data":{"id":1,"name":"xiaotuan"},

}

2.    各HTTP方法成功处理后的数据格式:

·

response 格式

GET

单个对象、集合

POST

新增成功的对象

PUT/PATCH

更新成功的对象

DELETE

 

五、错误处理

1.     不要发生了错误但给2xx响应,客户端可能会缓存成功的http请求;

2.     正确设置http状态码,不要自定义;

3.     Response body提供

即:返回的信息中将error作为键名,出错信息作为键值即可

1)错误的代码(日志/问题追查);

2)错误的描述文本(展示给用户)。

 

对第三点的实现稍微多说一点:

Java服务器端一般用异常表示 RESTful API的错误。API 可能抛出两类异常:业务异常和非业务异常。 业务异常 由自己的业务代码抛出,表示一个用例的前置条件不满足、业务规则冲突等,比如参数校验不通过、权限校验失败。 非业务类异常 表示不在预期内的问题,通常由类库、框架抛出,或由于自己的代码逻辑错误导致,比如数据库连接失败、空指针异常、除0错误等等。

业务类异常必须提供2种信息:

1.     如果抛出该类异常,HTTP响应状态码应该设成什么;

2.     异常的文本描述;

在Controller层使用统一的异常拦截器:

1.     设置 HTTP响应状态码:对业务类异常,用它指定的 HTTPcode;对非业务类异常,统一500;

2.     Response Body的错误码:异常类名

3.     Response Body的错误描述:对业务类异常,用它指定的错误文本;对非业务类异常,线上可以统一文案如“服务器端错误,请稍后再试”,开发或测试环境中用异常的 stacktrace,服务器端提供该行为的开关。

常用的http状态码及使用场景:

状态码

使用场景

400 bad request

常用在参数校验

401 unauthorized

未经验证的用户,常见于未登录。如果经过验证后依然没权限,

应该 403(即 authentication和 authorization的区别)。

403 forbidden

无权限

404 not found

资源不存在

500 internal server error

非业务类异常

503 service unavaliable

由容器抛出,自己的代码不要抛这个异常

 

六、其他

1API的身份认证应该使用OAuth2.0框架

2)服务器返回的数据格式,应该尽量使用JSON,避免使用XML

3)比较复杂的接口不能确定是使用POST还是PUT时,要看具体的业务层代码,看看接口产生的结果是否幂等,如果幂等用PUT,相反用POST

      如:接口接收到一资源,资源存在更新,不存在插入新数据,这个接口就要用PUT

<think>嗯,用户想了解如何用Postman测试他们自己写的RESTful API接口。首先,我需要回忆一下Postman的基本用法,以及测试API的一般流程。可能用户是刚接触API开发或者测试的新手,所以需要从基础开始讲起。 首先,用户可能已经写好了API,但不知道如何正确使用Postman发送请求。我应该先介绍Postman的安装界面,然后分步骤说明如何创建请求、设置方法、填写URL、添加HeadersBody等。可能还需要提到环境变量测试脚本,这些对自动化测试很有帮助。 然后,用户可能不太清楚不同的HTTP方法(GET、POST等)在Postman中如何选择,所以需要详细说明每个步骤,比如选择POST方法时需要设置Body的内容类型,比如JSON格式。可能还要提醒常见的错误,比如忘记设置Content-Type头,或者JSON格式不正确。 接下来,用户可能想了解如何验证响应是否正确。这时候需要解释如何查看状态码、响应体响应头,以及使用Postman的测试脚本来编写断言,自动检查结果。比如检查状态码是否为200,或者响应体中是否包含某个字段。 另外,用户可能希望知道如何保存整理请求,方便以后再次测试,或者分享给团队成员。这时候可以介绍Collections的用法,以及如何导出导入集合。 还有,环境变量的设置对于不同环境(开发、测试、生产)的切换很重要,应该举例说明如何创建环境变量,并在请求中使用变量,比如{{base_url}}来代替基础URL,提高灵活性。 最后,可能需要提到一些高级功能,比如自动化测试、持续集成中的使用,或者监控API性能,但根据用户的问题,可能暂时不需要深入,但可以简要提及作为扩展知识。 需要确保步骤清晰,避免使用专业术语过多,用简单的中文解释每个步骤,并给出具体的例子,比如发送POST请求时如何填写JSON数据。同时,注意用户提到的系统级指令,确保数学公式正确,但在这个问题中可能用不上,但还是要检查是否有其他格式要求,比如列表、代码块等是否符合规范。 可能还需要提醒用户注意安全,比如不要在Postman中保存敏感信息,或者使用环境变量来管理密钥等。此外,常见问题如跨域问题、身份验证(如Bearer Token)的设置方法也应该提到,帮助用户解决实际测试中可能遇到的障碍。 总结一下,回答的结构应该是:安装Postman、创建请求、设置请求参数、发送请求并查看响应、使用集合环境变量、编写测试脚本,最后是一些注意事项高级功能的简介。这样逐步引导用户完成整个测试流程,确保他们能够顺利测试自己的RESTful API接口。</think>使用Postman测试RESTful API接口的步骤如下: --- ### 一、安装与启动 1. **下载Postman** - 访问 [Postman官网](https://www.postal.com),下载对应操作系统的安装包 - 安装后注册账号(可选,但建议注册以同步数据) --- ### 二、创建请求 1. **新建请求标签页** - 点击左上角 `+` 或 `New` → `HTTP Request` - 输入API的 **URL**(如 `http://localhost:8080/api/users`) 2. **选择HTTP方法** - 在URL输入框左侧下拉选择方法:`GET`/`POST`/`PUT`/`DELETE` 等 --- ### 三、配置请求参数 1. **Headers设置** - 点击 `Headers` 标签 - 添加必要请求头,例如: ```plaintext Content-Type: application/json Authorization: Bearer <token> ``` 2. **Body设置(仅POST/PUT)** - 选择 `Body` → `raw` → `JSON` - 输入请求体数据,例如: ```json { "name": "张三", "email": "zhangsan@example.com" } ``` 3. **Query Params(URL参数)** - 点击 `Params` 标签 - 添加键值对(如 `?page=1&size=10`) --- ### 四、发送请求并查看响应 1. **点击 `Send` 按钮** - 观察响应状态码(如 `200 OK` 或 `404 Not Found`) 2. **解析响应内容** - `Body` 标签:查看JSON/XML格式的响应数据 - `Headers` 标签:查看服务器返回的响应头 - `Cookies` 标签:查看设置的Cookie信息 --- ### 五、高级功能 1. **环境变量** - 创建环境(如开发、测试环境) - 定义变量(如 `{{base_url}} = http://localhost:8080`) - 在请求中使用变量:`{{base_url}}/api/users` 2. **自动化测试** - 在 `Tests` 标签中编写JavaScript断言: ```javascript pm.test("Status code is 200", () => { pm.response.to.have.status(200); }); pm.test("Response contains name", () => { pm.expect(pm.response.json().name).to.eql("张三"); }); ``` 3. **保存请求到集合** - 点击 `Save` → 选择/新建集合(Collection) - 方便后续复用管理接口用例 --- ### 六、调试技巧 1. **查看历史记录** - 左侧边栏 `History` 可回溯所有请求 2. **导出代码** - 点击 `Code`(右上角)生成对应语言的请求代码(如Python、JavaScript) 3. **Mock Server** - 创建模拟服务器,在API未完成时快速测试前端逻辑 --- ### 常见问题排查 - **404错误**:检查URL拼写服务器是否运行 - **401/403错误**:验证身份认证头(如Token) - **500错误**:查看服务器日志定位后端异常 - **JSON解析失败**:检查请求体格式是否符合标准 通过以上步骤,您可以系统性地验证API的功能、性能安全性。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值