FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

工具

写代码之前,先用 curl 调一遍客户的 API

文档写的是 API 应该怎样工作,最初几次请求,尤其是不带 token 的那次,才说明它实际怎样工作。

分享微博

要点速览

  • 到客户现场第一天,先用 curl 确认 API 实际返回什么,再决定是否相信文档。
  • 需要保存请求、串联请求并与团队共享时,改用 Postman 集合和 Collection Runner。
  • 集合可以通过 Newman 或 Postman CLI 在 CI/CD 中运行,手工做过的检查就变成了回归测试。
一个 4 行 3 列的网格,展示 Postman 集合中的 12 个请求:创建、读取、更新、删除四种操作,每种都测试三种情况,即合法请求、不带 token 的请求和数据有误的请求。不带 token 的一列以橙色标出,并注明常被遗漏。
订单资源的一个集合:四种操作乘以三种情况,足以看清客户 API 的真实响应。不带 token 的一列展示了认证错误如何返回。来源:FDE Times。

Harness 博客上有一篇用 Node.js 和 Express 构建 CRUD API 的教程,推荐用 Postman 手动测试接口、用 Jest 做自动化测试,全文没有提到 curl。对教程来说这很合理:API 是你自己写的。

到了客户那里,情况正好相反。API 是别人写的,可能已经跑了好几年,文档也可能早已和代码对不上。

所以,在客户现场要做的第一件有用的事,是在写下任何一行代码之前,用对方刚发给你的 token 敲一条 curl 命令,看看他们的 API 是否真的返回文档里描述的内容。这项检查是实打实的工作,不是走过场。在弄清 API 实际返回什么之前,对这次部署的任何估算都只是猜测。

curl 回答“它还活着吗?”

curl 的官方 man page 把它描述为一个通过 URL 向服务器传输数据或从服务器获取数据的工具。这句简短的描述也说明了它为什么适合第一天上午:有一个终端和一个 URL 就能开始。

第一个要学的参数是 -H(或 --header)。它为请求添加一个 header,比如认证 token。假设客户是一家物流公司,给了你一个查询订单的接口:

curl -H "Authorization: Bearer $TOKEN" https://api.customer.example/orders/123

马上记下三件事:请求是否成功,返回的字段是否和文档一致,去掉 header 之后 API 如何报错。最后一步常被跳过,但它决定了你即将编写的集成代码要如何处理认证失败。

Postman 把这称为 API 单元测试:确认某个接口对特定请求返回正确的响应。curl 把这一件事做得很好。但到第五个请求、每次都要手动粘贴 token 时,就开始显得笨拙了。

Postman 保存请求,并把请求串起来

确认 API 活着之后,下一个问题是各个操作能否配合起来。Solène Lanchec 在 Forest Admin 博客上把 CRUD 四种操作对应到 HTTP 方法:PUT 用于替换整个资源,PATCH 只修改其中一部分。客户的 API 并不总是遵循这个约定。

在写依赖这一行为的代码之前,你需要先弄清楚。

这时就轮到 Postman 了。为订单资源建一个集合,包含四种操作:创建、读取、更新、删除。每种操作测三种情况:合法请求、不带 token 的请求、数据有误的请求。四乘三共十二个请求,足以在一个上午内看清 API 的真实响应。

据 Postman 介绍,Collection Runner 可以把请求串成一个工作流。先创建一个订单,读回来,用 PATCH 修改其中一个字段,再读一次。如果 PATCH 之后其他字段变成了空值,说明客户的 API 把 PATCH 当成了 PUT 处理。今天发现要好得多,因为被清空的只是测试数据。

curl

  • 一次一个请求,只需要终端
  • 用 -H 添加认证 header
  • 适合快速确认单个接口

Postman

  • 把请求保存为可复用的集合
  • Collection Runner 把请求串成工作流
  • 通过 Newman 或 Postman CLI 在 CI/CD 中运行

第一天常见的三个错误

第一个错误是看到 200 状态码就放心了。成功状态码并不能说明响应体与文档一致:200 响应照样可能缺字段、改了数据类型,或者字段名和文档不同。要逐个字段读完整个响应体。

第二个错误是只带着 token 调用 API。这样你只知道正常路径是什么样,却不知道认证错误会返回什么。等生产环境里 token 过期,你的代码只能靠猜。

第三个错误是第一天上午过后,就把集合留在自己的笔记本上。集合只有被反复运行、团队里其他人也能运行,才有价值。

两个工具都不替你做的事

两个工具都只负责发送请求,检查什么仍然是你的事。Testsigma 的指南把契约测试列为一种独立的 API 测试类型:验证 API 是否遵循其定义的规范。如果客户有规范,就把每个响应都系统地与之比较。

Testsigma 还建议定期检查 SQL 注入、跨站脚本(XSS)和认证失效等漏洞。这需要一份有针对性的测试用例清单,随手多发几个请求是不够的。上面集合里那个不带 token 的请求只是起点,算不上安全测试。

为了不让集合被遗忘,Postman 表示可以用 Newman 或 Postman CLI 在 CI/CD 流水线中运行集合和测试;Testsigma 也建议把回归测试和关键流程一起自动化。今天写的十二个请求,应该在客户每次部署时自动运行。

Postman 还在推广自动生成的文档,这类文档会随着集合或规范的变化保持同步。对前线部署工程师(FDE)来说,这有实际价值:根据真实运行过的请求生成的文档,在你离开项目后客户团队仍然用得上。

先学什么

先学 curl。它逼着你弄懂请求的每个部分:URL、方法、header。等你清楚自己想保存和自动化什么,再转向 Postman。在学这两个工具的同时,要吃透 CRUD 与 HTTP 方法的对应关系,尤其是 PUT 和 PATCH 的区别。

阅读 FDE 或解决方案工程师岗位的职位描述时,留意“integrate with customer APIs”或“debug integrations”这类表述。这些工作就发生在终端和 Postman 里。简历上不要写“精通 Postman”,而要描述一个你搭建的具体集合,比如它发现了某个 API 错误处理 PATCH,或者它被放进了 CI。

在客户那里,第一天的产出不是代码,而是一个记录 API 真实行为的集合。这样,此后写下的每一行代码都建立在经过验证的行为之上。

这篇文章对你有帮助吗?

6 个信源
路线图上的下一篇 · 阶段 2: 全栈工程能力百万条记录、一万次请求,一行都不能丢offset 分页翻到末页几乎要扫全表,游标、键集和检查点让大批量拉取又快又不会悄悄重复。