Postman 最基本的功能用来重放请求,并且配合良好的 response 格式化工具。
高级点的用法可以使用 Postman 生成各个语言的脚本,还可以抓包,认证,传输文件。
仅仅做到这些还不能够满足一个系统的开发,或者说过于琐碎,你仍需要频繁地在开发环境,测试环境,生产环境中来回切换。单一的请求也不够,你需要维护系统所有 API 的请求,并且每个请求还带有不同的 querystring 和 body。
Collection
对服务器端的所有请求按功能或者业务模块进行组织,使用 markdown 对所有请求和示例添加适当的描述,这时候就用到了 Collection。以下是 postman 的一些术语以及组织请求的建议。
-
Collection 对应一个Application,组内各个成员(server, client, QA)共享一个 Collection。可以对整个Collection 添加测试,文档。 对于一开始未在 postman 组织请求的应用,可以设置 Proxy,跑一遍应用,对应用的所有请求进行抓包。
-
Folder (ItemGroup) 对应一个模块,或者各层级子路由。如
router.use('/users')
所有的请求都在一个 Folder,可以根据路由互相嵌套 Folder。 -
Request (Item) 对应一个请求,可以添加认证信息。也可以设置代理,进行抓包。
-
Example 对应一个请求不同的参数以及响应,用于Mock Server 以及文档。
postman 可以根据 Collection 的结构生成文档与Mock Server。不过都是付费功能,免费版有次数限制。
文档
postman 自动生成文档有助于团队协作,解决了手动写文档,以及更新不及时的重大bug。
对于 GET 请求,Postman 上可以添加对该字段的描述,生成文档。
对于 POST 以及 PUT 请求,如果 Content-Type 是 form-data
或者 x-www-form-urlencoded
可以添加描述生成文档。不过如今传递 json 更方便灵活,所以 application/json
也会有很多,而且 json 又是不能添加注释的。如果需要对 json 添加文档说明的话,可以添加冗余字段 _{key}.comment
标明注释
{
"id": 128,
"_id.comment": "id",
"page": 10,
"_page.comment": "页数"
"pageSize": 15,
"_pageSize.comment": "每页条数"
}
不过这样冗余字段过多,更好的解决方案是在测试中对请求进行 json 校验,同时充当了一部分文档的功能。毕竟 json-schema 就是用来描述数据使数据更加可读。
以上说到请求,对于响应的文档,可以 json-schema 校验或者每个字段的描述,以及更多的测试用例代表更多的细节。
Mock
当服务器端还没有写好 API 时,客户端可以根据 Examples 来生成 Mock Server。
建议客户端端自己做 Mock,与项目集成在一起,纳入版本控制,方便灵活。