当前位置：首页 > news >正文

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

news 2026/8/9 23:06:39

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

Chanfana是一个功能强大的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/JSON，Chanfana从代码中提取类型信息自动生成OpenAPI 3.1规范
类型安全的数据验证：基于Zod模式的请求验证，在处理前确保数据正确性
多框架支持：原生支持Hono和itty-router等Cloudflare Workers流行框架
零运行时开销：所有验证和文档生成在构建时完成，不影响Worker性能

快速开始：5分钟搭建Chanfana项目

一键部署到Cloudflare

最简单的方式是使用官方模板直接部署到Cloudflare：

npm create cloudflare@latest -- --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的工作原理

OpenAPIRoute：API端点的基础构建块

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.getValidatedData<typeof this.schema>(); return { message: `Hello, ${data.query.name}!` }; } } // 注册端点 openapi.get('/greet', GreetingEndpoint); // 导出应用 export default app;

集成itty-router

如果你偏好itty-router，Chanfana同样提供无缝集成：

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?name=Test'); 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);