用 Hono + Zod 在 Next.js 中构建端到端类型安全的 RPC API 路由

前端 React 组件 (或 TanStack Query)
  │
  ▼ hc<AppType> 客户端调用 (享受 IDE 强类型自动补全与入参检查)
HTTP 请求 /api/posts/create
  │
  ▼ Next.js Catch-all: app/api/[[...route]]/route.ts
Hono 路由中心
  │
  ├── zValidator('json', schema) 运行时入参强校验
  ├── 业务 Handler 处理
  └── 返回 c.json(data) 并自动向前端推导响应类型

pnpm add hono @hono/zod-validator zod @tanstack/react-query

// app/api/[[...route]]/route.ts
import { Hono } from 'hono';
import { handle } from 'hono/vercel';
import { zValidator } from '@hono/zod-validator';
import { z } from 'zod';
 
const app = new Hono().basePath('/api');
 
// 1. 定义入参验证 Schema
const createPostSchema = z.object({
  title: z.string().min(3, '标题至少 3 个字符'),
  content: z.string().min(10, '内容至少 10 个字符'),
  tags: z.array(z.string()).default([]),
});
 
// 2. 链式定义路由（必须链式调用以便 TypeScript 提取 AppType）
const routes = app
  .get('/hello', (c) => {
    return c.json({ message: 'Hello from Type-Safe Hono!' });
  })
  .post('/posts', zValidator('json', createPostSchema), async (c) => {
    // validData 自动获得准确的 TypeScript 类型
    const validData = c.req.valid('json');
 
    // 模拟数据库保存
    const post = {
      id: crypto.randomUUID(),
      ...validData,
      createdAt: new Date().toISOString(),
    };
 
    return c.json({ success: true, data: post }, 201);
  });
 
// 导出 Next.js 请求处理器
export const GET = handle(app);
export const POST = handle(app);
export const PUT = handle(app);
export const DELETE = handle(app);
 
// 3. 导出整个 API 的类型定义供前端使用
export type AppType = typeof routes;

// lib/rpc-client.ts
import { hc } from 'hono/client';
import type { AppType } from '@/app/api/[[...route]]/route';
 
// 获得拥有完整路径补全与入参检查的强类型客户端
export const client = hc<AppType>(process.env.NEXT_PUBLIC_APP_URL || 'http://localhost:3000');

// components/CreatePostForm.tsx
'use client';
 
import { useMutation } from '@tanstack/react-query';
import { client } from '@/lib/rpc-client';
import type { InferRequestType, InferResponseType } from 'hono';
 
// 提取指定接口的请求与响应类型
type ReqType = InferRequestType<typeof client.api.posts.$post>['json'];
type ResType = InferResponseType<typeof client.api.posts.$post, 201>;
 
export function CreatePostForm() {
  const mutation = useMutation<ResType, Error, ReqType>({
    mutationFn: async (json) => {
      // client.api.posts.$post 享受完整类型检查，输错字段在 IDE 中直接标红
      const res = await client.api.posts.$post({ json });
      if (!res.ok) {
        throw new Error('创建文章失败');
      }
      return await res.json();
    },
    onSuccess: (data) => {
      console.log('创建成功，返回文章 ID:', data.data.id);
    },
  });
 
  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    mutation.mutate({
      title: '端到端类型安全实践',
      content: '本文详细记录了 Hono + Zod 在 Next.js 中的全流程打通...',
      tags: ['TypeScript', 'Next.js', 'Hono'],
    });
  };
 
  return (
    <form onSubmit={handleSubmit} className="space-y-4">
      <button
        type="submit"
        disabled={mutation.isPending}
        className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700"
      >
        {mutation.isPending ? '提交中...' : '创建文章'}
      </button>
    </form>
  );
}