Balanov/equal

项目介绍

EQUAL 位于应用与真实 HTTP API 之间，捕获请求和响应，产出三样东西：本地回放服务器、可提交到 Git 的 JSONL 磁带文件，以及 OpenAPI 3.1 文档。它面向上游 API 不可用、限流、按次计费或在 CI 中不宜反复调用的开发与测试场景。应用只要能配置 HTTP base URL，就能接入，与语言和 SDK 无关。

项目以单个静态 Go 二进制分发，支持 Linux、macOS、Windows 的 amd64 和 arm64（README 标注约 7.4 MB），许可证为 MIT。

快速使用

按 README 提供的 Unix 或 PowerShell 安装脚本安装，或使用 Go 1.26+ 从源码构建：

go install github.com/Balanov/equal/cmd/equal@latest
equal --version

启动录制代理：

equal record --target https://api.example.com --cassette account.jsonl

录制器监听 127.0.0.1:8080，把应用的 API base URL 指到该地址，按正常流程跑一遍。Ctrl+C 停止后检查磁带中的敏感数据：

equal inspect --cassette account.jsonl

之后离线回放，不再访问原服务：

equal replay --cassette account.jsonl

导出 OpenAPI：

equal export --cassette account.jsonl --out openapi.json --title 'Account API'

仓库附带一份合成的磁带示例及其生成的 OpenAPI 文档。做迁移或替换时，可用 equal verify --target http://127.0.0.1:9000 --cassette account.jsonl 把录下的请求发给另一套实现，比较状态码、响应头、JSON 和二进制响应差异。

使用约束

• 它是开发与测试工具，不是生产代理，只能证明它实际录制过的那部分流量。
• 内置脱敏是防护措施而非隐私保证，分享前必须逐条检查磁带。实时调用方仍会收到原始响应，只有存储副本会被脱敏。
• 回放不支持 live passthrough，未录制的请求返回明确的 404；--strict 会强制全局交互顺序。
• 匹配依据是方法、转义路径、规范化查询参数和请求体；JSON 键顺序与空白会被归一化，但数组顺序有意义。
• 导出的 OpenAPI 是示例驱动的不完整规范：未观察到的端点和字段不会出现，JSON 数组元素 schema 只取第一个观察样本，非 JSON 请求体不会被描述。
• verify 可能对候选服务产生真实副作用，应使用一次性测试租户。
• 已存在的磁带需显式加 --overwrite 才能覆盖；回放单条消息体默认上限为 16 MiB。
• 发布二进制尚未代码签名，每个 release 附带 SHA-256 校验和。

HotRepo 点评

该项目于 2026-11-04 进入 HotRepo 新项目榜，在当日约四小时的观察窗口内新增 114 Star，总 Star 为 114、Fork 为 0。没有记录到全部语言日榜名次，也没有 Hacker News 讨论可交叉印证，因此这是全新仓库上的一次短时增长，而非持续趋势。README 附带了端到端验证脚本，并公开了与 Hoverfly 对比的基准方法，读者可以按给出的命令自行复现这些数字，而不只是看到性能结论。