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

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

原文: https://fdetimes.net/zh/tools/test-customer-apis-curl-postman/

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 处理。今天发现要好得多，因为被清空的只是测试数据。

## 第一天常见的三个错误

第一个错误是看到 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 真实行为的集合。这样，此后写下的每一行代码都建立在经过验证的行为之上。

**本周动手试试:**

- 挑一个使用 token 认证的公开 API。用 curl 加 -H 参数调用一个 GET 接口，再去掉 header 调用一次，看 API 如何报错。
- 为同一个资源搭建一个包含四个请求（创建、读取、更新、删除）的 Postman 集合，用 Collection Runner 运行整条链路。
- 阅读 curl 的 man page，找到指定请求方法和发送请求体的参数。然后分别发一个 PATCH 请求和一个 PUT 请求，比较两次之后留下的数据。

## 信源

- [What is API Testing? A Guide to Testing APIs | Postman](https://www.postman.com/api-platform/api-testing/)

- [Automated API Documentation | Postman API Platform](https://www.postman.com/api-documentation-tool/)

- [curl - How To Use](https://curl.se/docs/manpage.html)

- [What Is API Testing? How to Do It Right and Best Practices](https://testsigma.com/guides/api-testing/)

- [An expert's guide to CRUD APIs: designing a robust one](https://forest.app/blog/an-experts-guide-to-crud-apis-designing-a-robust-one/)

- [How to Build a CRUD API Using Node.js and Express: Complete Tutorial | Harness Blog](https://harness.io/blog/introduction-to-building-a-crud-api-with-node-js-and-express)
