在 API 经济日益成熟的今天，付费 API 已不再是少数云厂商的专利。从机器学习模型调用到数据查询服务，越来越多的接口开始采用按调用计费模式。然而，如何在命令行层面优雅地处理这些付费请求，一直是工程实践中的空白地带。Stripe 于近期开源的 purl CLI 正是针对这一场景的解决方案 —— 它将「支付」与「HTTP 请求」两个本应分离的 Concerns 统一在同一个 CLI 工具中，为开发者提供了一种前所未有的交互范式。

purl 的定位：从 curl 到付费 API 的演进

purl 的核心定位可以概括为「面向付费场景的 curl 替代品」。传统的 curl 工具在处理免费 API 时游刃有余，但一旦涉及计费、认证与支付验证，开发者往往需要编写额外的脚本逻辑来完成 API Key 管理、余额检查、402 状态码处理等工作。purl 在设计上将这些问题内聚到 CLI 层面，使得调用一个付费 API 的操作与调用免费 API 几乎无异。

从架构层面来看，purl 采用了典型的 CLI + HTTP Client 双层结构。外层是 Rust 编写的命令行界面，负责参数解析、子命令路由和用户交互；内层则是一个经过封装的 HTTP Client，深度集成了 Stripe 的支付生态。这意味着 purl 不仅能够发送标准的 HTTP 请求，还能理解并处理支付场景特有的 402 Payment Required 响应、Wallet 余额状态以及计费参数的透明传递。

认证 Header 的工程封装

付费 API 的安全性是首要考量因素。与传统 API 不同，付费接口不仅需要验证调用者身份，还需要确保调用者具备相应的支付能力。purl 在认证层面的工程实现体现了这一需求的精细划分。

首先是标准认证层。purl 支持通过 -H 参数显式传递自定义 Header，这与 curl 的用法完全兼容。在 Stripe 的生态中，最常见的认证方式是 Bearer Token 模式 —— 用户将 Secret Key 放在 Authorization Header 中，格式为 Authorization: Bearer sk_live_xxx。purl 原生支持这种认证方式，开发者无需额外编写认证逻辑，只需在使用前通过 purl wallet add 命令将 API Key 绑定到本地 Wallet 即可。这种设计将认证信息与请求本身分离，既保证了安全性，又简化了命令行调用的复杂度。

其次是账户级认证。Stripe 的 Connect 体系允许平台方代表 connected account 发起请求，此时需要在请求中额外携带 Stripe-Account Header 来指定目标账户。purl 同样支持这一场景，开发者可以通过环境变量或配置文件预设多个账户身份，在实际调用时快速切换。这种多账户管理能力对于同时运营多个商户的 SaaS 平台尤其有价值。

计费参数的透明传递

付费 API 的计费方式多种多样：有按请求次数计费的、有按数据量计费的，也有按计算时长计费的。如何在 HTTP 请求中传递这些计费参数，并确保它们被正确解析，是 purl 设计中的另一个关键挑战。

purl 采用了「扩展 Header + 标准化 Body」的双轨策略。在扩展 Header 层面，purl 定义了一套内部协议，用于携带计费相关的元数据。这些元数据包括但不限于：预估费用上限（用于防止意外超额）、计费模式标识（次计费、包量计费、或订阅计费）、以及货币类型。由于这些 Header 以 X-Purl- 前缀开头，开发者可以清晰地将其与业务 Header 区分开来。

在请求 Body 层面，purl 遵循 RESTful 最佳实践，将计费相关字段放入标准 JSON 结构中。例如，一个典型的付费请求可能包含 billing_type、amount 和 currency 字段。这种设计的好处在于，接收方的后端服务可以沿用已有的 API 解析逻辑，无需为 purl 客户端单独开发适配层。同时，purl 在发送请求前会自动计算并注入 Idempotency-Key，这对于防止因网络重试导致的重复扣费至关重要。

响应解析与 402 处理

HTTP 402 是一个极少被正式使用的状态码，但在付费 API 场景中，它具有特殊的语义意义 —— 它明确告知客户端「本次请求需要支付才能继续」。传统的 curl 在遇到 402 时只会返回一个错误码，开发者需要自行解析响应体、判断余额状态、发起充值操作。purl 在这一层面做了深度优化，将 402 响应转化为可操作的交互式提示。

具体来说，当 purl 收到 402 响应时，它会首先解析响应体中的错误信息，提取出当前的 Wallet 余额、所需费用以及支付方式建议。然后，CLI 会向用户展示一个交互式的补款流程，用户可以直接在命令行中完成充值操作，无需切换到浏览器或其他工具。这种「请求 — 支付 — 重试」的闭环体验，是 purl 区别于其他 HTTP 客户端的核心差异点。

此外，purl 还支持响应体的结构化输出。默认情况下，CLI 会以人类可读的方式打印响应，但通过 -o json 参数可以强制输出原始 JSON。这一设计使得 purl 能够无缝嵌入到自动化脚本中，作为更大工作流的一个环节。

工程实践中的关键参数

基于上述架构分析，落地使用 purl 时有几个关键参数值得关注。第一是超时控制，建议在生产环境中将 -m 参数设置为 30 秒以上，以应对支付网关可能出现的耗时操作；第二是重试策略，purl 默认会在遇到 5xx 错误时自动重试，但 402 错误不会被重试（因为余额不足时重试无意义），这一行为可以通过 --retry-on-402 显式覆盖；第三是日志级别，生产环境建议使用 -v 级别以便追踪每一次请求的 Header 和计费详情，而在调试阶段可以使用 -vv 打印完整的网络交互细节。

小结

purl CLI 的出现标志着付费 API 调用从「手动拼装请求」向「声明式交互」的范式转变。通过将认证、计费和响应处理统一到 CLI 层面，Stripe 为开发者提供了一种既安全又高效的工程化方案。尽管目前 purl 仍处于早期阶段，其设计理念和技术选型已经为同类工具树立了一个值得借鉴的标杆。

资料来源：purl 官方文档（https://www.purl.dev）