Chanfana完全指南：如何在Cloudflare Workers上构建OpenAPI 3.1规范的API

Chanfana完全指南如何在Cloudflare Workers上构建OpenAPI 3.1规范的API【免费下载链接】chanfanaOpenAPI 3 and 3.1 schema generator and validator for Hono, itty-router and more!项目地址: https://gitcode.com/gh_mirrors/ch/chanfanaChanfana是一个功能强大的OpenAPI 3和3.1规范生成器与验证器专为Hono、itty-router等框架设计特别适合在Cloudflare Workers环境中构建API。本指南将帮助你快速掌握Chanfana的核心功能从零开始创建一个符合OpenAPI 3.1标准的API服务。图Chanfana项目logo象征着为Cloudflare Workers烹饪API的强大能力为什么选择Chanfana构建Cloudflare Workers API在Cloudflare Workers环境中开发API时开发者常常面临两大挑战确保API符合行业标准规范以及在边缘环境中实现高效的数据验证。Chanfana通过以下特性完美解决这些问题自动OpenAPI文档生成无需手动编写YAML/JSONChanfana从代码中提取类型信息自动生成OpenAPI 3.1规范类型安全的数据验证基于Zod模式的请求验证在处理前确保数据正确性多框架支持原生支持Hono和itty-router等Cloudflare Workers流行框架零运行时开销所有验证和文档生成在构建时完成不影响Worker性能快速开始5分钟搭建Chanfana项目一键部署到Cloudflare最简单的方式是使用官方模板直接部署到Cloudflarenpm create cloudflarelatest -- --template https://github.com/cloudflare/chanfana/tree/main/template该模板包含完整的任务API示例包括CRUD端点、D1数据库集成和自动生成的API文档。本地开发环境设置如果你更喜欢本地开发按照以下步骤操作克隆仓库git clone https://gitcode.com/gh_mirrors/ch/chanfana cd chanfana安装依赖npm install运行开发服务器npm run dev访问http://localhost:8787/api/docs即可查看自动生成的Swagger UI文档。核心概念Chanfana的工作原理OpenAPIRouteAPI端点的基础构建块Chanfana的核心是OpenAPIRoute类所有API端点都通过继承这个类来实现class HelloEndpoint extends OpenAPIRoute { schema { responses: { 200: { description: Successful response, ...contentJson(z.object({ message: z.string() })), }, }, }; async handle(c: AppContext) { return { message: Hello, Chanfana! }; } }这个类包含两个关键部分schema属性定义OpenAPI规范包括请求和响应结构handle方法实现业务逻辑接收验证后的请求数据自动请求验证流程Chanfana的请求验证流程完全自动化请求到达时Chanfana拦截并根据schema定义进行验证使用Zod验证请求数据body、query、params、headers验证通过执行handle方法并传入验证后的数据验证失败自动返回400错误响应包含详细的验证信息这种机制确保只有符合规范的数据才能到达你的业务逻辑。实战教程构建你的第一个OpenAPI 3.1 API使用Hono框架创建端点以下是使用Hono和Chanfana创建API端点的完整示例import { Hono } from hono; import { fromHono, OpenAPIRoute, contentJson } from chanfana; import { z } from zod; // 定义环境类型 export type Env { DB: D1Database; } // 创建Hono应用 const app new Hono{ Bindings: Env }(); // 初始化Chanfana const openapi fromHono(app); // 定义端点 class GreetingEndpoint extends OpenAPIRoute { schema { request: { query: z.object({ name: z.string().min(1).describe(The name to greet) }) }, responses: { 200: { description: A friendly greeting, ...contentJson(z.object({ message: z.string() })) } } }; async handle(c) { const data await this.getValidatedDatatypeof this.schema(); return { message: Hello, ${data.query.name}! }; } } // 注册端点 openapi.get(/greet, GreetingEndpoint); // 导出应用 export default app;集成itty-router如果你偏好itty-routerChanfana同样提供无缝集成import { Router } from itty-router; import { fromIttyRouter, OpenAPIRoute, contentJson } from chanfana; import { z } from zod; // 创建路由器 const router Router(); // 初始化Chanfana const openapi fromIttyRouter(router); // 定义端点与Hono示例相同 class GreetingEndpoint extends OpenAPIRoute { // ... 同上 ... } // 注册端点 openapi.get(/greet, GreetingEndpoint); // 导出fetch处理函数 export const fetch router.handle;高级功能释放Chanfana全部潜力自动CRUD端点生成Chanfana提供了自动生成CRUD端点的能力特别适合与D1数据库配合使用// 定义数据模型 const TaskSchema z.object({ id: z.string().uuid(), title: z.string().min(3), completed: z.boolean().default(false) }); // 创建基础D1端点 class TaskBaseEndpoint extends D1BaseEndpoint { schema { tags: [Tasks], modelSchema: TaskSchema, table: tasks, primaryKey: id }; } // 自动生成CRUD端点 openapi.get(/tasks, class extends TaskBaseEndpoint {}); openapi.get(/tasks/:id, class extends TaskBaseEndpoint {}); openapi.post(/tasks, class extends TaskBaseEndpoint {}); openapi.put(/tasks/:id, class extends TaskBaseEndpoint {}); openapi.delete(/tasks/:id, class extends TaskBaseEndpoint {});这段代码自动创建了完整的任务管理API包括所有CRUD操作和对应的OpenAPI文档。自定义OpenAPI文档Chanfana允许深度定制生成的OpenAPI文档const openapi fromHono(app, { openapi: { info: { title: My Awesome API, version: 1.0.0, description: Built with Chanfana on Cloudflare Workers }, servers: [ { url: https://api.example.com/v1 } ] } });部署与测试将API推向生产使用Wrangler部署部署到Cloudflare Workers只需简单几步配置wrangler.toml模板项目已包含执行部署命令npm run deploy访问https://your-worker-name.cloudflareworkers.com/api/docs查看实时API文档测试端点Chanfana提供了集成测试工具确保你的API按预期工作// tests/integration/endpoints.test.ts import { test } from vitest; import { createTestServer } from ../utils; test(GET /greet returns greeting, async () { const server createTestServer(); const response await server.fetch(/greet?nameTest); const data await response.json(); expect(response.status).toBe(200); expect(data.message).toBe(Hello, Test!); });常见问题与最佳实践如何处理部分更新使用Zod 4时可以通过getUnvalidatedData()方法区分未发送的字段和默认值async handle() { const validated await this.getValidatedData(); const raw await this.getUnvalidatedData(); // 检查字段是否实际发送 if (status in raw.body) { // 用户显式更新了status字段 } }如何添加认证Chanfana可以与Hono的认证中间件无缝集成import { basicAuth } from hono/basic-auth; // 应用认证中间件 app.use(/admin/*, basicAuth({ username: admin, password: secret })); // 受保护的端点 openapi.get(/admin/metrics, AdminMetricsEndpoint);总结使用Chanfana构建现代APIChanfana为Cloudflare Workers提供了完整的API开发解决方案通过自动化OpenAPI文档生成和类型安全的数据验证让开发者能够专注于业务逻辑而非样板代码。无论是构建简单的微服务还是复杂的企业级APIChanfana都能显著提高开发效率并确保API质量。想要深入了解更多功能查看官方文档docs/introduction.md 和 docs/advanced-topics-patterns.md。开始使用Chanfana体验在Cloudflare Workers上构建OpenAPI 3.1规范API的简单与高效 【免费下载链接】chanfanaOpenAPI 3 and 3.1 schema generator and validator for Hono, itty-router and more!项目地址: https://gitcode.com/gh_mirrors/ch/chanfana创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考