Next.js 使用 Hono 接管 API

import { Hono } from 'hono'
import { handle } from 'hono/vercel'

const app = new Hono().basePath('/api')


app.get('/hello', (c) => {
return c.json({

    message: 'Hello Next.js!',

  })

})

export const GET = handle(app)
export const POST = handle(app)
export const PUT = handle(app)
export const DELETE = handle(app)

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

const paramSchema = z.object({

  id: z.string().cuid(),

})

const jsonSchema = z.object({

  status: z.boolean(),

})

const app = new Hono().put(
'/users/:id',
zValidator('param', paramSchema),
zValidator('json', jsonSchema),

  (c) => {
const { id } = c.req.valid('param')
const { status } = c.req.valid('json')

// 逻辑代码...

return c.json({})

  },

)

export default app

   if (!result.success) {
-    return c.json(result, 400)

   }

if (!result.success) {
+    throw result.error

   }

import { z } from 'zod'
import type { Context } from 'hono'
import { HTTPException } from 'hono/http-exception'

export function handleError(err: Error, c: Context): Response {
if (err instanceof z.ZodError) {
const firstError = err.errors[0]

return c.json(

      { code: 422, message: `\`${firstError.path}\`: ${firstError.message}` },
422,

    )

  }

// handle other error, e.g. ApiError

return c.json(

    {

      code: 500,

      message: '出了点问题, 请稍后再试。',

    },

    { status: 500 },

  )

}

3. 在 server/api/index.ts ，也就是 hono app 对象中绑定错误捕获。

const app = new Hono().basePath('/api')


app.onError(handleError)

4. 更改 zValidator 导入路径。

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

+ import { zValidator } from '@/server/api/validator'

这样就将错误统一处理，且后续自定义业务错误也同样如此。

:::note 顺带一提

如果需要让 zod 支持中文错误提示，可以使用 zod-i18n-map

:::

RPC

Hono 有个特性我很喜欢也很好用，可以像 TRPC 那样，导出一个 client 供前端直接调用，省去编写前端 api 调用代码以及对应的类型。

这里我不想在过多叙述 RPC(可见我之前所写有关 TRPC 的使用)，直接来说说有哪些注意点。

链式调用

还是以 User CRUD 的代码为例，不难发现 .get .post .put 都是以链式调用的写法来写的，一旦拆分后，此时接口还是能够调用，但这将会丢失此时路由对应的类型，导致 client 无法使用获取正常类型，使用链式调用的 app 实例化对象则正常。

替换原生 Fetch 库

hono 自带的 fetch 或者说原生的 fetch 非常难用，为了针对业务错误统一处理，因此需要选用请求库来替换，这里我的选择是 ky，因为他的写法相对原生 fetch 更友好一些，并且不会破坏 hono 原有类型推导。

在 lib/api-client.ts 编写以下代码

import { AppType } from '@/server/api'
import { hc } from 'hono/client'
import ky from 'ky'

const baseUrl =

  process.env.NODE_ENV === 'development'

    ? 'http://localhost:3000'

    : process.env.NEXT_PUBLIC_APP_URL!

export const fetch = ky.extend({

  hooks: {

    afterResponse: [
async (_, __, response: Response) => {
if (response.ok) {
return response

        } else {
throw await response.json()

        }

      },

    ],

  },

})

export const client = hc<AppType>(baseUrl, {

  fetch: fetch,

})

这里我是根据请求状态码来判断本次请求是否为异常，因此使用 response.ok，而响应体正好有 message 字段可直接用作 Error message 提示，这样就完成了前端请求异常处理。

至于说请求前自动添加协议头、请求后的数据转换，这就属于老生常谈的东西了，这里就不多赘述，根据实际需求编写即可。

请求体与响应体的类型推导

配合 react-query 可以更好的获取类型安全。此写法与 tRPC 十分相似，相应代码 → Inferring Types

// hooks/users/use-user-create.ts

import { client } from '@/lib/api-client'
import { InferRequestType, InferResponseType } from 'hono/client'
import { useMutation } from '@tanstack/react-query'
import { toast } from 'sonner'
const $post = client.api.users.$post

type BodyType = InferRequestType<typeof $post>['json']

type ResponseType = InferResponseType<typeof $post>['data']

export const useUserCreate = () => {
return useMutation<ResponseType, Error, BodyType>({

    mutationKey: ['create-user'],

    mutationFn: async (json) => {
const { data } = await (await $post({ json })).json()

return data

    },

    onSuccess: (data) => {

      toast.success('User created successfully')

    },

    onError: (error) => {

      toast.error(error.message)

    },

  })

}

在 app/users/page.tsx 中的使用

'use client'

import { useUserCreate } from '@/features/users/use-user-create'

export default function UsersPage() {
const { mutate, isPending } = useUserCreate()

const handleSubmit = (e: React.FormEvent) => {

    e.preventDefault()
const formData = new FormData(e.currentTarget)
const name = formData.get('name') as string
const email = formData.get('email') as string
mutate({ name, email })

  }

return (
<form onSubmit={handleSubmit}>
<div>
<label htmlFor='name'>Name:label>
<input type='text' id='name' name='name' />
div>
<div>
<label htmlFor='email'>Email:label>
<input type='email' id='email' name='email' />
div>
<button type='submit' disabled={isPending}>

        Create User
button>
form>

  )

}

OpenAPI 文档

这部分我已经弃坑了，没找到一个很好的方式为 Hono 写 OpenAPI 文档。不过对于 TS 全栈开发者，似乎也没必要编写 API 文档（接口自给自足），更何况还有 RPC 这样的黑科技，不担心接口的请求参数与响应接口。

如果你真要写，那我说说几个我遇到的坑，也是我弃坑的原因。

首先就是写法上，你需要将所有的 Hono 替换成 OpenAPIHono (来自 @hono/zod-openapi， 其中 zod 实例 z 也是)。以下是官方的示例代码，我将其整合到一个文件内

import { createRoute, OpenAPIHono, z } from '@hono/zod-openapi'
import { swaggerUI } from '@hono/swagger-ui'

const app = new OpenAPIHono()

const ParamsSchema = z.object({

  id: z

    .string()

    .min(3)

    .openapi({

      param: {

        name: 'id',
in: 'path',

      },

      example: '123',

    }),

})

const UserSchema = z

  .object({

    id: z.string().openapi({ example: '123' }),

    name: z.string().openapi({ example: 'John Doe' }),

  })

  .openapi('User')

const route = createRoute({

  method: 'get',

  path: '/api/users/{id}',

  request: {
params: ParamsSchema,

  },

  responses: {
200: {

      content: {
'application/json': {

          schema: UserSchema,

        },

      },

      description: 'Retrieve the user',

    },

  },

})


app.openapi(route, async (c) => {
const { id } = c.req.valid('param')

// 逻辑代码...
const user = {

    id,

    name: 'Ultra-man',

  }

return c.json(user)

})

从上述代码的可读性来看，第一眼你很难看到清晰的看出这个接口到底是什么请求方法、请求路径，并且在写法上需要使用 .openapi 方法，传入一个由 createRoute 所创建的 router 对象。并且写法上不是在原有基础上扩展，已有的代码想要通过代码优先的方式来编写 OpenAPI 文档将要花费不小的工程，这也是我为何不推荐的原因。

定义完接口(路由)之后，只需要通过 app.doc 方法与 swaggerUI 函数，访问 /api/doc 查看 OpenAPI 的 JSON 数据，以及访问 /api/ui 查看 Swagger 界面。

import { swaggerUI } from '@hono/swagger-ui'


app.doc('/api/doc', {

  openapi: '3.0.0',

  info: {

    version: '1.0.0',

    title: 'Demo API',

  },

})


app.get('/api/ui', swaggerUI({ url: '/api/doc' }))

从目前来看，OpenAPI 文档的生成仍面临挑战。我们期待 Hono 未来能推出一个功能，可以根据 app 下的路由自动生成接口文档（相关Issue已存在）。

仓库地址

附上本文中示例 demo 仓库链接（这个项目就不搞线上访问了）

github.com/kuizuo/next…

后记

其实我还想写写 Auth、DB 这些服务集成的(这些都在我实际工作中实践并应用了)，或许是太久未写 Blog 导致手生了不少，这篇文章也是断断续续写了好几天。后续我将会出一版完整的我个人的 Nextjs 与 Hono 的最佳实践模版。

也说说我为什么会选用 Hono.js 作为后端服务, 其实就是 Next.js 的 API Route 实在是太难用了，加之轻量化，你完全可以将整个 Nextjs + Hono 服务部署在 Vercel 上，并且还能用上 Edge Functions 的特性。(就是有点小贵)

但不过从我的 Nest.js 开发经验来看（也可能是习惯了 Spring Boot 那套三层架构开发形态），总觉得 Hono 差了点意思，说不出来的体验，可能这就是所谓的全栈框架的开发感受吧。