Orval 实战:Hono 后端 + Next.js fetch 客户端的 Schema-First 全栈开发示例

原创2026-10-07 12:45:101,635 阅读
文章标签:代码生成开发工具

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 拆分输出文件。本规范所有操作都挂载在 pets tag 下,因此生成物集中在 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(见下文运行时校验)。

生成之后,在示例根目录执行(见 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 模式的三个关键产出:

  1. 请求校验:zValidator('json', CreatePetsBody) 自动用 petstore.yaml 中 requestBody 推导出的 zod Schema 校验入参;
  2. 响应校验:zValidator('response', CreatePetsResponse) 对处理器返回的 JSON 响应做 Schema 校验,确保实际响应符合规范;
  3. 类型化 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 双端流水线的三个收益

回顾整个示例,可以提炼出这种"一份规范 + 双端生成"开发模式的核心价值:

  1. 契约唯一:Hono 后端的路由/校验/Context 与 Next.js 前端的 fetch 客户端/类型/Mock 均出自同一份 petstore.yaml,接口定义不会在前后端之间漂移;
  2. 类型贯穿全链路:请求参数、响应结构、错误类型在服务端与客户端都获得了类型签名,zValidator 在运行时(response 校验)与编译时(类型化 Context)双重把关;
  3. 开发可并行:后端处理器骨架只需填充业务逻辑,前端可基于 mock: true 生成的 MSW mock 先行开发,最后通过 baseUrl 无缝切换到真实后端联调。

如需深入 orval 的 Hono 与 fetch 能力细节,可继续阅读仓库 skills 目录 与 skills/orval/custom-http-clients.md,以及 orval 包源码 packages/orval/src 中对应的生成器实现。

登录后查看全文
orval