Hono Zod 校验中间件

示例说明

Hono 是多运行时框架，校验中间件是其类型安全体系的关键一环。zValidator 在路由声明处指定校验目标与 schema：请求先过校验关，失败自动回 400 与结构化错误；通过后 c.req.valid 拿到的是窄化类型，处理函数内零断言。路径参数同样可校验——UUID 格式的资源 ID 在进入逻辑前就被拦截。

技术要点

• zValidator 按目标（json/param/query）声明
• valid 返回值带 schema 推断类型
• 校验失败响应自动生成无需手写

代码解读

事件 schema 约束标题长度、ISO 时间戳、容量区间与标签数组默认值；app.request 的内存级测试调用直接发起请求验证行为——这也是 Hono 测试无需起服务器的原因。参数校验路由演示 UUID 约束对脏 ID 的拦截。

使用建议

自定义错误响应形态可传入格式化钩子。多运行时部署时确认 zod 版本兼容边缘环境。校验规则与 API 文档共享 schema 文件。

代码示例

import { Hono } from 'hono';
import { zValidator } from '@hono/zod-validator';
import { z } from 'zod';

// zValidator is the validation middleware mounted at route level
const app = new Hono();

const EventSchema = z.object({
  title: z.string().min(3).max(120),
  startsAt: z.string().datetime(),
  capacity: z.number().int().min(1).max(10_000),
  tags: z.array(z.string().min(1)).max(6).default([]),
});

app.post('/events', zValidator('json', EventSchema), (c) => {
  const event = c.req.valid('json');

  return c.json({
    created: true,
    title: event.title,
    tags: event.tags,
    startsAt: new Date(event.startsAt).toISOString(),
  });
});

app.get('/events/:id', zValidator('param', z.object({ id: z.string().uuid() })),
  (c) => c.json({ id: c.req.valid('param').id }));

const res = await app.request('/events', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ title: 'launch', startsAt: new Date().toISOString(), capacity: 50 }),
});
console.log('status:', res.status, await res.text());