告别散落的 curl：用 Hurl 把 API 回归测试写成可读、可进 CI 的纯文本用例
接口联调刚开始时，一条 curl 往往足够：请求能通、返回 JSON，看一眼就算完成。但接口逐渐增多后，验证条件会散落在 shell 历史、Postman Collection、临时脚本与人工记忆里。更麻烦的是，团队很难回答一个基础问题：这次改动到底验证了哪些 HTTP 契约？
Hurl 是 Orange Open Source 维护的 Apache-2.0 开源命令行工具。它把 HTTP 请求、响应断言、数据捕获和后续请求的变量引用放入一个纯文本 .hurl 文件。它不是为了取代浏览器端到端测试，也不主张替代所有 API 客户端；它解决的是“把可版本化的 HTTP 检查写进仓库，并让本地与 CI 执行同一份用例”这件事。
这篇文章用公开 GitHub API 做演示，重点不在测试某个业务接口，而在于建立一种可迁移的用例结构：请求描述、契约断言、性能边界与 CI 输出各自清晰，失败时能快速定位。
为什么单条 curl 难以变成回归测试
curl 很适合探索接口，但它的默认输出面向人阅读，不会自动表达“哪些字段必须保持不变”。当然可以继续叠加 jq、状态码判断和 shell 条件分支；代价是请求、提取、断言、错误输出慢慢被拆进多处脚本。代码审查时，读者也要在命令参数与 shell 控制流之间来回切换。
另一个常见误区是把 HTTP 检查等同于“200 就通过”。状态码只说明本次请求获得了某类响应，并不能保证响应头、内容类型和关键业务字段仍遵守调用方的约定。比如一个接口仍返回 200，却把 JSON 改成 HTML 错误页；或返回对象还在，但许可证、状态、分页字段被悄悄改名。对依赖该接口的服务而言，这仍是回归。
Hurl 的文本格式将这些判断放在请求紧邻的位置。一个文件可以纳入 Git diff、接受代码审查，也能在本机和流水线中原样运行。它还支持 JSONPath、XPath、响应头和状态码等查询与谓词；官方 README 也给出了 REST、SOAP、GraphQL 与 HTML 场景的示例。因此，适合先把它当作 HTTP 契约与烟雾测试工具，而不是万能的 UI 自动化平台。
安装：优先使用已发布版本
Hurl 当前最新 release 是 8.0.1。对于 Debian 12 及 Ubuntu 22.04/24.04，官方 README 给出了下载 .deb 并交给 apt 安装的方式。版本号写成变量的好处是升级时只有一个位置需要改动：
VERSION=8.0.1
curl --location --remote-name \
https://github.com/Orange-OpenSource/hurl/releases/download/$VERSION/hurl_${VERSION}_amd64.deb
sudo apt update
sudo apt install ./hurl_${VERSION}_amd64.deb
hurl --version
如果团队已经以 Rust 工具链管理开发机，也可以按官方说明使用 cargo install --locked hurl。容器化流水线则可使用官方 GHCR 镜像。选择哪一种不是关键；关键是把版本固定在团队可复现的环境里，避免某位成员的本地二进制升级后让断言语法或输出行为发生漂移。
第一个用例：验证公开 API 的最小契约
创建 checks/hurl-repo.hurl，内容如下。示例不需要 Token，目标是 GitHub 的公开仓库元数据接口。HTTP 200 检查状态码；header 确认不是被网关替换成其他内容；两个 jsonpath 断言则把工具身份和许可证写成明确的契约；duration 是以毫秒为单位的上限。
GET https://api.github.com/repos/Orange-OpenSource/hurl Accept: application/vnd.github+json User-Agent: hurl-regression-demo HTTP 200 [Asserts] header "content-type" contains "application/json" jsonpath "$.full_name" == "Orange-OpenSource/hurl" jsonpath "$.license.spdx_id" == "Apache-2.0" duration < 10000
以测试模式执行：
hurl --test checks/hurl-repo.hurl
测试模式的价值在于，它把成功与失败当作测试结果呈现，而非默认将最后一个响应体直接输出。10 秒阈值只是对公共网络的宽松示范，并不是建议把它照搬到生产 SLO。内部服务应根据部署区域、历史延迟和重试策略制定阈值；外部公共 API 也应避免把偶发网络抖动误判为功能故障。
这个例子还说明了断言粒度的取舍。不要断言整个 JSON 文本，因为字段顺序、非关键字段或统计数字变化都会造成无价值的失败；也不要只断言状态码。优先选择调用方确实依赖、语义稳定且能解释业务意图的字段。对自有 API，通常是 schema 版本、订单状态、分页游标、权限边界或错误码，而不是临时展示文案。
从“能请求”到“能串联”
真实回归通常不止一个 GET。Hurl 的核心能力之一是捕获上一个响应中的值，再在后续请求中通过 {{变量名}} 引用。官方的示例展示了先从页面响应中以 XPath 捕获 CSRF token，再把 token 放入登录表单的链路。这种写法比在 shell 中手工拼接变量更贴近 HTTP 会话本身：请求、捕获来源和下一步使用位置都在同一个文件中。
迁移现有接口检查时，可以按三个层次拆分。第一层是健康检查：服务可达、状态码与内容类型正确；第二层是单接口契约：关键字段、响应头、错误响应和权限边界正确；第三层才是链路场景：创建资源、读取资源、再验证状态变化。不要急于把所有路径塞进一个超长文件。按业务域拆成多个 .hurl 文件，失败时更容易定位，也更适合并行维护。
涉及登录、支付或第三方服务时，最重要的规则不是语法，而是密钥边界。Token、密码和生产标识不应写入 .hurl 文件或提交进仓库。将敏感值由 CI 的 Secret 或运行环境注入，并给测试账号设置最小权限。对于会写入数据的场景，还应使用专用测试环境、带前缀的测试数据和可重复的清理策略；否则“回归测试”本身可能制造难以追踪的脏数据。
放进 CI：让失败成为可审查的信息
Hurl 可以接收单个文件，也可以对目录递归寻找 .hurl 文件。项目把用例放入独立目录后，本地和流水线可以共用同一条入口命令：
hurl --test integration/
官方说明 Hurl 可生成文本、JUnit、TAP 和 HTML 报告。实际接入时，应先决定 CI 系统消费哪一种格式：若平台能展示 JUnit 测试结果，就将报告接入测试页；若团队更重视人工排查，可同时保留 HTML 报告作为构件。无论格式如何，日志中至少应能看到失败的用例文件、请求步骤和断言位置，而不是只剩一个笼统的非零退出码。
建议把检查分成两类门槛。轻量烟雾测试在每次提交或 PR 上运行，覆盖健康接口和最关键的读路径；涉及多个依赖、较慢或会创建数据的链路测试放在合并后、定时任务或专用环境执行。这样既能让反馈保持快速，也不会为了追求“全量”而让每个 PR 都等待不稳定的外部依赖。
Hurl 的边界与适用场景
Hurl 的强项是 HTTP 请求及其响应的可读声明和断言。它适合 API 契约回归、部署后的烟雾检查、Webhook 接收端验证，以及需要以 Git 管理的外部服务连通性检查。它由 Rust 编写、底层 HTTP 引擎使用 libcurl；这使它保持为一个无需运行时的单二进制 CLI，而非一个需要维护应用服务器的测试平台。
相应地，浏览器布局、点击路径、前端渲染和真实用户交互仍应交给专门的浏览器自动化工具；复杂的数据构造、跨系统异步最终一致性，也可能需要配套的 fixture、轮询和环境编排。把这些边界说清楚，反而能让 Hurl 在自己擅长的位置更可靠。
从一条被复制粘贴的 curl 命令开始，将“请求是否成功”升级为“契约是否仍成立”，不需要先引入一套庞大的测试平台。先挑选一个最关键的读接口，将请求、断言和执行命令提交进仓库；等这条链路稳定后，再按领域扩展用例。可审查的纯文本，往往正是接口回归测试最容易被团队长期维护的起点。
一个实用的推进顺序是：先为已有线上事故补一条能复现问题的断言，再为每个新接口在开发完成时留下最小用例。这样测试文件不再只是发布前的临时检查，而会逐步成为接口演进的可执行说明；当字段、权限或错误码必须调整时，修改用例与修改服务代码会同时出现在评审中。