API 常见陷阱

# 陷阱与故障排除 ## 速率限制与 429 错误 **实际限制：** - **1200 次请求 / 5 分钟** (每个用户/Token，全局) - **200 次请求 / 秒** (每个 IP 地址) - **GraphQL: 320 / 5 分钟** (基于成本) **SDK 行为：** - 自动进行指数退避重试（默认重试 2 次，Go 为 10 次） - 遵循 `Retry-After` 响应头 - 重试耗尽后抛出 `RateLimitError` **解决方案：** typescript // 为高频速率限制的工作流增加重试次数 const client = new Cloudflare({ maxRetries: 5 }); // 添加应用级限流 import pLimit from 'p-limit'; const limit = pLimit(10); // 最大 10 个并发请求 ## SDK 特定问题 ### Go: 必填字段包装器 **问题：** Go SDK 要求对可选字段使用 `cloudflare.F()` 包装器。 go // ❌ 错误 - 无法编译或发送字段 client.Zones.New(ctx, cloudflare.ZoneNewParams{ Name: "example.com", }) // ✅ 正确 client.Zones.New(ctx, cloudflare.ZoneNewParams{ Name: cloudflare.F("example.com"), Account: cloudflare.F(cloudflare.ZoneNewParamsAccount{ ID: cloudflare.F("account-id"), }), }) **原因：** 用于区分零值、null 和省略字段。 ### Python: 异步与同步客户端 **问题：** 在异步上下文中使用同步客户端，或反之。 python # ❌ 错误 - 无法 await 同步客户端 from cloudflare import Cloudflare client = Cloudflare() await client.zones.list() # TypeError # ✅ 正确 - 使用 AsyncCloudflare from cloudflare import AsyncCloudflare client = AsyncCloudflare() await client.zones.list() ## Token 权限错误 (403) **问题：** 尽管 Token 有效，API 仍返回 403 Forbidden。 **原因：** Token 缺少所需的权限（范围）。 **所需范围：** | 操作 | 所需范围 | |-----------|----------------| | 列出区域 | Zone:Read (区域级或账户级) | | 创建区域 | Zone:Edit (账户级) | | 编辑 DNS | DNS:Edit (区域级) | | 部署 Worker | Workers Script:Edit (账户级) | | 读取 KV | Workers KV Storage:Read | | 写入 KV | Workers KV Storage:Edit | **解决方案：** 在控制面板 → 我的个人资料 → API Tokens 中重新创建具有正确权限的 Token。 ## 分页截断 **问题：** 仅获取前 20 条结果（默认页面大小）。 **解决方案：** 使用自动分页迭代器。 typescript // ❌ 错误 - 仅第一页 (20 条) const page = await client.zones.list(); // ✅ 正确 - 所有结果 const zones = []; for await (const zone of client.zones.list()) { zones.push(z