Orval 实战:Hono 后端 + Next.js fetch 客户端的 Schema-First 全栈开发示例
Orval 实战:Hono 后端 + Next.js fetch 客户端的 Schema-First 全栈开发示例
导读
本文围绕仓库中的 hono-with-fetch-client 示例 展开,讲解如何在同一个 OpenAPI 规范(petstore.yaml)驱动下,用 orval 同时生成 Hono 服务端路由与处理器骨架、以及 Next.js 侧的 fetch 类型安全客户端(含 mock),从而构建一条"规范即契约"的全栈开发流水线。读完本文,你将掌握 orval 的 client: 'hono' 与 client: 'fetch' 两种模式的核心配置、tags-split/split 输出模式的区别、运行时校验与 Mock 的生成机制,以及如何在本地同时启动 Hono 后端与 Next.js 前端完成端到端联调。
示例全景:一份规范、两端代码
hono-with-fetch-client 是一个完整的可运行示例应用,其设计目标在 示例 README 中有明确定位:
以
hono作为后端、Next.js+fetch作为前端,实现 seamless(无缝)的 schema-first 开发。
整个示例由两个独立应用组成:
hono-app:基于 Hono 的 API 后端,最终可部署为 Cloudflare Worker(使用 Wrangler);next-app:基于 Next.js App Router 的前端,通过浏览器原生fetch调用后端接口,全部请求/响应类型由 orval 生成。
两者共享同一份 OpenAPI 规范文件 petstore.yaml。该规范定义了经典的 Swagger Petstore 接口:GET /pets(listPets)、POST /pets(createPets)、PUT /pets(updatePets)、GET /pets/{petId}(showPetById),以及 Pet、Pets、Error 三个组件 Schema。这意味着后端路由的形态、前端请求的类型签名,全部由这一份 YAML 决定——改规范、重新生成、两端同步更新,即 schema-first 的核心闭环。
一键生成:orval.config.ts 双端配置
示例根目录的 orval.config.ts 是理解整套流水线的钥匙。它注册了两个生成目标(output target):petstoreClient 与 petstoreApi,共用同一个输入 ./petstore.yaml,分别产出前端客户端与后端服务端代码。
前端:petstoreClient(Next.js + fetch)
petstoreClient: {
input: {
target: './petstore.yaml',
},
output: {
mode: 'tags-split',
client: 'fetch',
target: 'next-app/app/gen/',
schemas: 'next-app/app/gen/models',
clean: true,
formatter: 'prettier',
baseUrl: 'http://localhost:8787',
mock: true,
},
},
逐项说明各配置参数的实际效果:
mode: 'tags-split':按 OpenAPI 规范中的tags拆分输出文件。本规范所有操作都挂载在petstag 下,因此生成物集中在 next-app/app/gen/pets/ 目录,例如 pets.ts 中会为每个 operationId 生成listPets、createPets等带完整类型签名的调用函数;client: 'fetch':生成基于浏览器/Node 原生fetch的客户端,不引入 axios 等第三方 HTTP 库;target与schemas:分别指定客户端代码与模型(model)代码的输出目录;clean: true:每次生成前清空目标目录,保证旧文件不残留(生成目录内的文件都带有 "Generated by orval / Do not edit manually" 头注释,直接由 orval 全量托管);formatter: 'prettier':生成后自动用 prettier 格式化;baseUrl: 'http://localhost:8787':预置后端地址。8787 正是下文 Hono 后端wrangler dev的默认监听端口,前后端约定由此建立;mock: true:同时生成 MSW mock,即 pets.msw.ts(配合 pets.faker.ts 使用 faker 生成随机数据)。
生成出的 fetch 客户端带有精细的类型化响应结构。在 pets.ts 中可以看到 listPetsResponse200 = { data: Pets; status: 200 } 这类按状态码区分的联合类型,以及 HTTPStatusCodes 等工具类型,前端在调用时可以直接用 result.status 做类型收窄,无需手动断言。
后端:petstoreApi(Hono 服务端)
petstoreApi: {
input: {
target: './petstore.yaml',
},
output: {
mode: 'split',
client: 'hono',
target: 'hono-app/src/petstore.ts',
formatter: 'prettier',
override: {
hono: {
handlers: 'hono-app/src/handlers',
},
},
},
},
与前端目标的关键差异:
client: 'hono':orval 专门为 Hono 提供的服务端生成模式;mode: 'split':将路由注册与应用入口拆分,生成物包括:- hono-app/src/petstore.ts:路由注册文件,自动将规范中的每个操作映射为 Hono 的链式调用,如
.get('/pets', ...listPetsHandlers)、.post('/pets', ...createPetsHandlers)、.get('/pets/:petId', ...showPetByIdHandlers),路径参数:petId由petstore.yaml中{petId}自动转换而来; override.hono.handlers:指定处理器(handler)骨架的输出目录,即 hono-app/src/handlers/;- 同目录下还会生成
petstore.context.ts(每个接口的类型化 Context)、petstore.schemas.ts、petstore.zod.ts(zod Schema)与petstore.validator.ts(见下文运行时校验)。
- hono-app/src/petstore.ts:路由注册文件,自动将规范中的每个操作映射为 Hono 的链式调用,如
生成之后,在示例根目录执行(见 package.json 中的 generate-api 脚本):
vp exec orval
即可一次完成前后两端代码的同步生成。
后端落地:Hono 路由与处理器骨架
生成的 petstore.ts 是一个开箱即用的 Hono 应用入口:
const app = new Hono()
.get('/pets', ...listPetsHandlers)
.post('/pets', ...createPetsHandlers)
.put('/pets', ...updatePetsHandlers)
.get('/pets/:petId', ...showPetByIdHandlers);
export default app;
每个接口的处理器骨架也由 orval 生成,例如 createPets.ts:
const factory = createFactory();
export const createPetsHandlers = factory.createHandlers(
zValidator('json', CreatePetsBody),
zValidator('response', CreatePetsResponse),
async (c: CreatePetsContext) => {},
);
这里已经能看到 orval hono 模式的三个关键产出:
- 请求校验:
zValidator('json', CreatePetsBody)自动用petstore.yaml中requestBody推导出的 zod Schema 校验入参; - 响应校验:
zValidator('response', CreatePetsResponse)对处理器返回的 JSON 响应做 Schema 校验,确保实际响应符合规范; - 类型化 Context:最后一个回调接收
CreatePetsContext,其中已推导好c.req.valid('json')等入参的类型。开发者的任务被收敛为"在空函数体内写业务逻辑"。
配套的 petstore.validator.ts 在 @hono/zod-validator 基础上扩展出 response 校验目标:当目标为 response 时,它在 next() 之后读取 c.res,解析 JSON 并用 zod safeParseAsync 校验;校验失败时以 400 状态返回错误信息,成功时则将校验后的数据重新写回响应。这一实现使 Hono 服务端也享受到与请求侧同等的运行时契约保障。
前端落地:Next.js 中的类型安全 fetch 调用
前端生成物位于 next-app/app/gen/,除了 pets/ 目录下的调用函数与 mock,还包含 models/ 目录(对应 schemas 配置项),如 pet.ts、listPetsParams.ts 等,query 参数(limit)、路径参数(petId)与响应体都被转换为精确的 TypeScript 类型。
mock: true 生成的 pets.msw.ts 使用 MSW 拦截对应 URL,配合 faker 数据生成器 pets.faker.ts,可在后端未就绪时让前端独立开发、联调页面。示例根目录 package.json 的 devDependencies 也引入了 msw,表明这是该示例的一等公民能力。
双端本地联调:安装与启动
示例 README 给出了两个应用各自的启动方式,仓库根目录使用 vp(Bun 的包管理别名)执行安装:
cd hono-app
vp install
vp run dev
cd next-app
vp install
vp run dev
其中 hono-app 的启动细节可从其 package.json 脚本确认:
"dev": "wrangler dev src/petstore.ts --ip 0.0.0.0":用 Wrangler 以开发模式启动生成的 petstore 路由,默认监听 8787 端口——这正是前端baseUrl预设的地址;--ip 0.0.0.0允许容器或局域网内访问;"deploy": "wrangler deploy --minify src/index.ts":部署为 Cloudflare Worker。
hono-app 的运行依赖为 hono、@hono/zod-validator、zod(开发依赖含 wrangler 与 @cloudflare/workers-types)。next-app 侧按 Next.js 惯例以 npm run dev(或 yarn/pnpm/bun dev)启动,默认运行于 3000 端口(详见 next-app/README.md)。
启动顺序建议:先启动 hono-app(8787 端口),再启动 next-app(3000 端口),随后在浏览器访问 Next.js 页面即可通过生成的 fetch 客户端调用真实后端。若希望前端暂不依赖后端,可切换使用 MSW mock。
快照测试:保证生成结果可回归
示例带有完整的 API 生成快照测试 api-generation.spec.ts,它基于仓库的 快照测试工具 运行 describeApiGenerationSnapshots:
- 对
hono-app/src/handlers目录与petstore.ts、petstore.context.ts、petstore.schemas.ts、petstore.validator.ts、petstore.zod.ts等文件做快照比对,快照存于 snapshots/hono-app; - 对
next-app/app/gen/pets与next-app/app/gen/models目录做快照比对,快照存于 snapshots/next-app。
这意味着 orval 生成器的任何行为变更都会在 CI 中被快照差异捕获,前后端生成物始终可回归、可审计。示例根目录的 test:snapshots 与 test:snapshots:update 脚本(package.json)分别用于运行快照测试与在有意变更后更新快照。
小结:schema-first 双端流水线的三个收益
回顾整个示例,可以提炼出这种"一份规范 + 双端生成"开发模式的核心价值:
- 契约唯一:Hono 后端的路由/校验/Context 与 Next.js 前端的 fetch 客户端/类型/Mock 均出自同一份 petstore.yaml,接口定义不会在前后端之间漂移;
- 类型贯穿全链路:请求参数、响应结构、错误类型在服务端与客户端都获得了类型签名,
zValidator在运行时(response 校验)与编译时(类型化 Context)双重把关; - 开发可并行:后端处理器骨架只需填充业务逻辑,前端可基于
mock: true生成的 MSW mock 先行开发,最后通过baseUrl无缝切换到真实后端联调。
如需深入 orval 的 Hono 与 fetch 能力细节,可继续阅读仓库 skills 目录 与 skills/orval/custom-http-clients.md,以及 orval 包源码 packages/orval/src 中对应的生成器实现。