告别手写 fetch 拼参数cloudflare-typescript 全类型化 Cloudflare API 请求与响应体验指南【免费下载链接】cloudflare-typescriptThe official TypeScript library for the Cloudflare API项目地址: https://gitcode.com/gh_mirrors/cl/cloudflare-typescriptcloudflare-typescriptnpm 包名cloudflare是 Cloudflare 官方出品的 TypeScript SDK它为 Cloudflare REST API 的所有请求参数与响应字段都提供了完整的类型定义。你不再需要手写fetch、手工拼接 URL 和查询串、再手动解析 JSON——调用client.zones.create({...})时编辑器的自动补全会告诉你每个字段该填什么返回值也带精确类型。下面用最短的路径带你跑通它。 为什么值得换掉手写 fetch手写 fetch使用 cloudflare-typescriptURL 靠字符串拼接拼错无提示client.资源名.方法()全量自动补全参数、响应字段全是any或手写 interface请求参数与响应字段均有类型定义错误需自己判断状态码4xx/5xx 自动抛出细分异常类分页要手动处理 token/offset原生for await...of自动翻页重试、超时、日志全部自己实现默认 2 次指数退避重试、1 分钟超时、可插拔日志库基于 Stainless 从 OpenAPI 规范自动生成与官方 API 文档保持同步完整接口清单见 api.md。 快速安装3 步完成首次 API 调用第一步安装依赖无任何第三方运行时依赖dependencies为空npm install cloudflare第二步准备一个 API TokenCloudflare 后台创建通过环境变量注入。第三步发出第一个全类型化请求import Cloudflare from cloudflare; const client new Cloudflare({ apiToken: process.env[CLOUDFLARE_API_TOKEN], // 默认读取该环境变量可省略 }); const zone await client.zones.create({ account: { id: 023e105f4ecef8ad9ca31a8372d0c353 }, name: example.com, type: full, }); console.log(zone.id); // 返回的是带类型的 Zone 对象环境要求TypeScript ≥ 4.9支持 Node.js 20、Deno 1.28、Bun 1.0、Cloudflare Workers、浏览器、Vercel Edge Runtime 等主流运行时。 请求与响应类型随写随补全所有参数和响应字段都以命名空间类型导出可以在自己的代码里显式标注const params: Cloudflare.ZoneCreateParams { account: { id: 023e105f4ecef8ad9ca31a8372d0c353 }, name: example.com, type: full, }; const zone: Cloudflare.Zone await client.zones.create(params);每个方法、参数、响应字段都带有 docstring 注释在主流编辑器中悬停即可看到文档说明。类型与 HTTP 端点的完整映射收录在 api.md 中共覆盖数百个资源。⚠️ 错误处理状态码自动映射为异常类API 返回非成功状态码或无法连接时库会抛出APIError的子类无需再手写if (res.status 401)const zone await client.zones .get({ zone_id: 023e105f4ecef8ad9ca31a8372d0c353 }) .catch(async (err) { if (err instanceof Cloudflare.APIError) { console.log(err.status); // 400 console.log(err.name); // BadRequestError console.log(err.headers); // 完整响应头 } else { throw err; } });错误类与状态码的对应关系状态码异常类型400BadRequestError401AuthenticationError403PermissionDeniedError404NotFoundError422UnprocessableEntityError429RateLimitError≥500InternalServerError连接失败APIConnectionError连接错误、408、409、429 与 5xx 会默认自动重试 2 次指数退避可用maxRetries全局或按请求调整请求默认1 分钟超时可用timeout配置。异常类定义见 src/core/error.ts。 自动分页一行for await拉完所有数据Cloudflare API 的列表接口都有分页SDK 把翻页细节完全封装掉了// 方式一自动翻页跨页迭代 for await (const account of client.accounts.list()) { console.log(account); } // 方式二逐页手动控制 let page await client.accounts.list(); while (page.hasNextPage()) { page await page.getNextPage(); }分页实现位于 src/core/pagination.ts兼容 offset、cursor、cursorlimit 等多种分页风格。 文件上传四种传法任选对应文件上传的参数接受File、fetch的Response、fs.ReadStream或toFile辅助函数的返回值import fs from fs; import Cloudflare, { toFile } from cloudflare; const client new Cloudflare(); // Node 环境推荐文件流 await client.kv.namespaces.values.update(My-Key, { account_id: 023e105f4ecef8ad9ca31a8372d0c353, namespace_id: 0f2ac74b498b48028cb68387c421e279, value: fs.createReadStream(/path/to/file), }); // Web 环境可用 File / Response兜底用 toFile // value: new File([my bytes], file) // value: await toFile(Buffer.from(my bytes), file)上传核心逻辑在 src/core/uploads.ts部署 Worker 脚本的完整示例见 examples/workers/script-upload.ts。 进阶技巧按需裁剪、原始响应与日志 树摇减包Tree Shaking——只打包你真正用到的资源且客户端类型精确到未注册的字段会被编译器拒绝import { createClient } from cloudflare/tree-shakable; import { Zones } from cloudflare/resources/zones/zones; import { BaseAccounts } from cloudflare/resources/accounts/accounts; const client createClient({ resources: [Zones, BaseAccounts] }); const zone await client.zones.create({ account: {}, name: example.com }); 拿到原始 Response——每个方法返回APIPromise可.asResponse()只取原始响应不消费 body适合流式处理或.withResponse()同时取解析数据与原始响应如自定义响应头const { data: zone, response: raw } await client.zones.create({ ... }).withResponse(); console.log(raw.headers.get(X-My-Header)); console.log(zone.id); 结构化日志——支持debug / info / warn / error / off五级可通过CLOUDFLARE_LOG环境变量或logLevel选项设置也能接入 pino、winston 等任意日志库。 调用未公开端点——用client.post(/some/path, { query, body })直接发请求或借助// ts-expect-error传递未公开参数请求体不会被运行时裁剪原样发出。 自定义 fetch 与代理——可传入自定义fetch兼容 Node、Bun、Deno 的代理配置也可用fetchOptions透传任意RequestInit选项。 项目结构与学习路径路径说明README.md官方使用文档本文所有示例的出处api.md全量 API 方法与类型索引src/index.ts公共入口src/client.ts客户端核心请求构造、重试、超时src/core/分页、异常、APIPromise、上传等基础模块src/tree-shakable.ts按需创建裁剪版客户端src/version.ts版本常量tests/880 个测试文件每个 API 资源的调用范式都可参考examples/workers/部署 Worker 的端到端示例MIGRATION.md版本升级迁移指南CONTRIBUTING.md贡献与生成机制说明资源代码按 src/client.ts 中Zones、LoadBalancers、KV、Workers等数百个资源类组织每个资源一个目录、一个 api.md按图索骥即可。✅ 小结用cloudflare-typescript换取的是全类型化参数与响应、异常细分、自动重试/超时/分页以及零运行时依赖一行client.xxx.yyy()即可替代手写的 URL 拼接 头设置 JSON 解析 状态码判断需要减包用tree-shakable需要原始响应用withResponse需要自定义端点用client.post。从手写fetch迁移到这套官方 SDK改动量通常只有几行 import换来的却是整条调用链的类型安全——对长期维护 Cloudflare 自动化脚本的团队来说这笔账非常划算。【免费下载链接】cloudflare-typescriptThe official TypeScript library for the Cloudflare API项目地址: https://gitcode.com/gh_mirrors/cl/cloudflare-typescript创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考