# 一份 OpenAPI 文件，上线前揪出 500 错误

> Schemathesis 依据客户的 schema 生成请求、排查服务端错误，但它发的是真实流量，只能对准预发布环境。

原文: https://fdetimes.net/zh/guides/schemathesis-openapi-staging-500-errors/

客户发来一份 `openapi.json` 文件，附言说下周上线。你可以相信每个端点都扛得住意外输入；也可以让工具直接用这份文件生成请求，看服务器会不会返回 500。

第二种做法叫基于属性的测试（property-based testing），Schemathesis 做这件事时不需要你为每个端点写测试。项目文档说得很直白：把工具指向 schema 运行，它就能发现手写测试容易漏掉的服务端错误、schema 违规和校验漏洞。

这项技能和前线部署工程师（FDE）的日常工作很贴近。你经常要对接不是自己写的 API，文档不全，而真实用户碰到的第一个 500 会算到你头上。本指南从安装讲起，一直到产出一份可以发给客户的报告。

## 要做出什么，需要准备什么

最终成果是一条命令，在笔记本和 CI 中都能运行。它读取客户的 OpenAPI 文件，带着 token 向预发布（staging）环境发送请求，返回清晰的退出码，并导出报告。

你需要四样东西。首先是 Python 3.11 或更高版本，这是 PyPI 上列出的 Schemathesis 运行要求；该工具基于 Python 的属性测试库 Hypothesis 构建。其次是 `uv`，用来运行工具而不必装进项目；然后是客户的 OpenAPI 文件；最重要的是一个**不是生产环境**的基础 URL。

最后这个条件不是走形式。Schemathesis 的 README 明确警告：工具发送的是真实请求，可能创建、修改和删除数据。运行任何测试之前，先让客户以书面形式提供开发或预发布环境。

**要点:** 模糊测试工具发送的是真实请求：只对准那些丢了数据也无妨的环境。

## 第 1 步：用客户的文件跑第一次

README 给出了最基本的调用方式，直接指向 schema 的 URL：

```bash
uvx schemathesis run https://your-api.com/openapi.json
```

但实际工作中，客户通常发来的是文件而不是 URL。根据 CLI 文档，schema 是本地文件时，必须用 `--url` 指定被测 API 的基础 URL：

```bash
uvx schemathesis run ./openapi.json \
  --url https://staging.customer.example
```

这一步完成后，确认命令确实向预发布环境发出了请求。如果忘了 `--url`，Schemathesis 无法运行，会返回退出码 2，这个退出码专门表示配置错误。这还算不上 API 的 bug。

## 第 2 步：附上 token，通过认证

第一次运行往往返回一大片 401。原因很简单：大多数客户的 API 都在认证之后，没有 token 的请求根本到不了真正的业务逻辑。`--header` 选项会给每个请求加上一个请求头，可以重复使用：

```bash
uvx schemathesis run ./openapi.json \
  --url https://staging.customer.example \
  --header "Authorization: Bearer $STAGING_TOKEN" \
  --header "X-Tenant-Id: test-tenant"
```

这里的第二个请求头只是假设的例子，请换成客户 API 实际要求的请求头。token 放在环境变量里，不要直接粘进命令，否则它会留在 shell 历史或 CI 日志中。

检查：401/403 响应的比例应该大幅下降。如果仍然很多，先确认 token 是否有权限访问所有端点，再下结论说 API 有问题。

## 第 3 步：像工程师一样读 500，而不是像记分员

最关键的检查是 `not_a_server_error`，它会捕获包括 500 在内的所有 5xx 状态码。这项检查不需要手动开启：根据文档，除 `max_response_time` 外，所有检查默认都已启用。

设想一个典型结果：`POST /orders` 端点在 `quantity` 字段为负数时返回 500，而 schema 并没有设下限。这是两个问题，不是一个：服务端缺少校验，schema 也没有如实描述真实的接口契约。

所以，每发现一个失败，都记录三件事：能复现的请求、受影响的端点，以及修复应该落在代码还是 schema。比起一句“发现 37 个 bug”，客户会更看重这样一份清单。

## 第 4 步：缩小阶段范围，加快迭代

`--phases` 选项可以从四个阶段中选择要运行的部分：`examples`、`coverage`、`fuzzing` 和 `stateful`。默认会全部运行，这对首次扫描和上线前的最后一次扫描都是正确的选择。

修某个具体 bug、只想快速复查时，把 `--phases` 限定为一两个阶段就够了。但完整运行时不要去掉 `stateful`：PyPI 上的说明指出，有状态测试会从 schema 推断操作之间的关联。

比如一个先创建订单、再读取同一订单的流程：单独测试每个端点永远走不通这条链路，而 `stateful` 阶段正是为了把这样的步骤串起来。

## 第 5 步：把测试变成 CI 关卡

退出码让 Schemathesis 能够接入流水线。退出码 1 表示至少一项检查失败或报告了错误；退出码 2 表示 Schemathesis 本身因为配置错误无法运行。

项目的 CI/CD 指南建议：只要退出码非零，就让任务失败。指南还指出一个陷阱：什么都没测到的运行同样返回退出码 2。这样，空的 schema 文件或写错的过滤条件就不会悄悄让构建变绿。

为了有东西发给客户，工具可以同时导出多种格式的报告，用逗号分隔：`junit`、`vcr`、`har`、`json`、`html`。一个实用建议：按接收方选格式。机器可读的格式给 CI 流水线用；HTML 版本最适合在上线前作为邮件附件发给客户。

## 让客户失去信任的错误

代价最高的错误是对生产环境运行。一次模糊测试就可能制造大量垃圾记录或删掉真实数据，找到再多 500 也弥补不了。

其次是以为自己测过了延迟。`max_response_time` 是唯一默认不启用的检查，如果客户有响应时间方面的 SLA，必须自己打开它。最后一个错误是把退出码 2 当成“API 坏了”，惊动了客户，而实际上只是你忘了 `--url` 或配置有误。

## 这项技能在 FDE 工作中的位置

在客户现场，价值在于时机。在集成的第一周运行 Schemathesis，能在你往上搭建逻辑之前，摸清哪些端点脆弱。上线前再跑一次，就能向客户证明 API 契约成立。

就职业发展而言，阅读 FDE 岗位描述时，留意“integrate with customer APIs”或“production readiness”这类说法：这项技能正用在那里。简历上不要只写“API 测试”，要写成果，例如：将基于 schema 的测试引入 CI，在上线前发现并复现 5xx 错误，并为客户团队提供报告。

下次客户发来 OpenAPI 文件和上线日期时，你不必猜 API 能否应对意外输入。运行一条命令，产出一份报告，就能准确指出它在哪里出问题。

**本周动手试试:**

- 找一个有 OpenAPI 文件的内部 API，运行 uvx schemathesis run 并用 --url 指向开发环境，记录发现了多少个 5xx 错误
- 把这次运行加入 CI 流水线，配置为退出码非零时任务失败
- 写一页失败汇总，附上可复现的请求，就当是上线前发给客户的材料

## 信源

- [Schemathesis documentation (stable)](https://schemathesis.readthedocs.io/en/stable/)

- [schemathesis/schemathesis (GitHub README)](https://github.com/schemathesis/schemathesis)

- [Schemathesis reference: Checks](https://schemathesis.readthedocs.io/en/stable/reference/checks/)

- [Schemathesis reference: CLI](https://schemathesis.readthedocs.io/en/stable/reference/cli/)

- [Schemathesis guide: CI/CD](https://schemathesis.readthedocs.io/en/stable/guides/cicd/)

- [schemathesis · PyPI](https://pypi.org/project/schemathesis/)
