客户端生成器可以省去手动复制端点路径和请求字段到自有库的工作，还能生成模型，在请求发出前捕获不正确的输入。
在哪里获取 Bird 的规范？
Bird 的 API 参考文档和 SDK 生成器也使用该公开 bundle。将下载的文件与生成配置一起保存，以便日后重新生成客户端。
OpenAPI 规范定义了路径、参数、认证和响应结构的描述方式。生成器利用该描述为目标语言构建方法和模型。
如何生成客户端？
使用 OpenAPI Generator 从 Bird 的 JSON 规范生成客户端。在执行下载、验证和生成命令之前，先安装该工具。
以下示例在 bird-client 中生成一个 Ruby 客户端：
curl --fail --location https://bird.com/openapi.json --output bird-openapi.json
openapi-generator-cli validate -i bird-openapi.json
openapi-generator-cli generate -i bird-openapi.json -g ruby -o bird-client使用 JSON 可避免生成器的 YAML 解析器大小限制。验证通过时仍可能输出建议信息。生成前请检查错误。
将 ruby 替换为其他语言对应的受支持生成器。按照该生成器的安装要求以及生成的 README 来构建或安装输出。
将生成的文件与手写的应用代码分开存放。重新生成到同一目录时，可能会覆盖你直接对客户端所做的修改。
生成器的使用指南记录了语言选项和配置文件。
客户端会覆盖哪些操作？
客户端覆盖 Bird 公开 bundle 中包含的 HTTP 操作。其他接口上的操作不会通过公开客户端生成获得对应方法。
例如，API 密钥轮换可通过仪表盘会话或个人 CLI 或 MCP 授权完成。它不在公开 bundle 中，无法使用工作区 API 密钥调用。
免费电话验证也有位于公开 bundle 之外的 CLI 和 MCP 操作。在判定某个缺失方法需要手动实现之前，先检查这些接口。
Realtime 发布是一个公开的 HTTP 操作。订阅频道事件需要 WebSocket 连接，请为该部分使用 Realtime 客户端。
应该检查哪些请求处理？
在补充缺失的处理逻辑之前，先检查生成的运行时。不同的生成器和配置提供的行为各不相同。
| 关注点 | 需要验证的内容 |
|---|---|
| 区域 | 所选主机与密钥前缀中的区域一致。 |
| 幂等性 | 同一写操作的多次尝试复用同一个密钥。 |
| 重试 | 临时失败有有限次数的重试，并遵守 Retry-After。 |
| 分页 | 迭代沿游标进行，直到没有更多页面为止。 |
| Webhook | 验证使用未修改的请求体，并在解析前检查签名。 |
生成的参数不一定会自动管理其值。Idempotency-Key 字段仍然需要一个具有正确生命周期的密钥，除非运行时自动提供。
同样，可配置的服务器区域并不意味着客户端会从凭据中读取该区域。在发送请求之前，请设置或验证主机。
应该生成客户端还是使用 Bird SDK？
当 Bird SDK 支持的语言和依赖项适合你的应用时，使用它。当你需要其他语言或需要遵循组织的生成规范时，生成客户端。
SDK 或直接 API 调用对比了支持的语言、重试行为和超时默认值。
- Bird SDK: 使用 Bird 提供和维护的请求处理。
- Generated client: 选择你的语言，并在部署前检查其运行时处理。
- Generated types only: 在现有的 HTTP 层中保留请求处理。
简而言之
下载公开规范。
Bird 以 YAML 和 JSON 两种格式发布同一份 API 描述。JSON 格式可避免生成器的 YAML 大小限制。
为目标语言生成客户端。
OpenAPI Generator 在生成客户端之前会验证下载的 JSON。
检查生成的请求处理。
在依赖客户端之前，检查区域选择、重试、幂等性、分页和 webhook 验证。
在其他接口检查缺失的操作。
API 密钥轮换需要通过仪表盘会话或个人 CLI 或 MCP 授权完成。Realtime 订阅需要 WebSocket 客户端。