跳到主要内容

Hono 接管 Next API

  • 可使用Hono接管Next Route
  • Next.js自带的api路由比较难用，通过hono接管Next API
  • Next.js会将所有/api/*请求的路由让hono来接管处理
    • hono的路由，嵌入在Next所在的api路径下
    • 通过hono/vercel来负责接管，接管之后，按照hono的方式来写api

路由解析、中间件、响应有hono接管

好处：

  • 统一 API 组织方式：把后端按 Hono 子路由模块化管理，而不是分散很多 Next route 文件
  • 端到端类型安全：AppType -> hc<AppType>，前后端共享路由类型，减少手写 URL 和类型不一致问题
  • 保留 Next 生态能力（部署、App Router、前端 SSR/CSR），同时用 Hono 提升 API 层开发体验

接管API路由​

当使用hono/vercel适配器时，Hono通过Next.js的动态捕获路由机制（如app/api/[...hono]/route.ts）拦截所有/api/*请求路径，将这些请求的处理权从Next.js原生路由系统转移到Hono的路由引擎。这种接管包含三个关键特征：

  1. 路径映射保留 前端调用的接口地址（如/api/users/123）在视觉上与Next.js原生API路由完全一致，但底层处理逻辑已切换为Hono的路由匹配规则。
  2. 运行时控制权转移 Next.js仅作为请求代理，实际路由解析、中间件执行、响应生成均由Hono完成。例如：
typescript
   // Next.js路由文件仅作为转发入口
   export const GET = handle(app); // 将GET请求交给Hono实例处理
  1. 兼容性隔离层 Vercel适配器（hono/vercel）负责处理Next.js的Request/Response对象与Hono的Context对象之间的转换，确保两者运行时模型的无缝衔接。

相关实现​

  • src/app/api/[[...route]]/route.ts
    • 是服务端api桥接层
    • 通过new Hono().basePath('/api') 统一 API 根前缀
js
import { chat, sse, user } from '@/server/routes'
import { Hono } from 'hono'
import { handle } from 'hono/vercel'

# 统一 API 根前缀
const app = new Hono().basePath('/api')

export const runtime = 'edge'

# 把各业务路由挂到 /api/chat、/api/user、/api/sse
const routes = app.route('/chat', chat).route('/user', user).route('/sse', sse)

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

# 来自服务端路由类型
export type AppType = typeof routes

  • src/lib/client.ts

    • hc 是 Hono 提供的客户端生成器（hono/client）

    • 服务端路由类型（AppType）变成一个可直接调用的前端 API 对象

    • 生成前端 API 客户端，自动继承当前域名并获得类型提示

    • 调用api：client.api.xxx使用

      • 如 await client.api.user.list.$get()
ts
import type { AppType } from '@/app/api/[[...route]]/route'
import { hc } from 'hono/client'

// 自动会继承当前域名作为api接口地址
export const client = hc<AppType>('/')

参考系列​