RPC

RPC 功能允许在服务端和客户端之间共享 API 规范。

你可以导出 Validator 指定的输入类型以及 json() 发射的输出类型。并且 Hono Client 将能够导入它。

NOTE

为了使 RPC 类型在 monorepo 中正常工作，请在客户端和服务器端的 tsconfig.json 文件中，将 compilerOptions 中的 "strict" 设置为 true。阅读更多。

服务端

在服务端，你所需要做的就是编写一个 validator 并创建一个 route 变量。以下示例使用了 Zod Validator。

const route = app.post(
  '/posts',
  zValidator(
    'form',
    z.object({
      title: z.string(),
      body: z.string(),
    })
  ),
  (c) => {
    // ...
    return c.json(
      {
        ok: true,
        message: 'Created!',
      },
      201
    )
  }
)

然后，导出类型以与客户端共享 API 规范。

export type AppType = typeof route

客户端

在客户端，首先导入 hc 和 AppType。

import { AppType } from '.'
import { hc } from 'hono/client'

hc 是一个创建客户端的函数。传入 AppType 作为泛型，并指定服务器 URL 作为参数。

const client = hc<AppType>('http://localhost:8787/')

调用 client.{path}.{method} 并传入你希望发送到服务器的数据作为参数。

const res = await client.posts.$post({
  form: {
    title: 'Hello',
    body: 'Hono is a cool project',
  },
})

res 与 "fetch" Response 兼容。你可以使用 res.json() 从服务器检索数据。

if (res.ok) {
  const data = await res.json()
  console.log(data.message)
}

文件上传

目前，客户端不支持文件上传。

状态码

如果你在 c.json() 中显式指定了状态码，例如 200 或 404。它将被添加为传递给客户端的类型。

// server.ts
const app = new Hono().get(
  '/posts',
  zValidator(
    'query',
    z.object({
      id: z.string(),
    })
  ),
  async (c) => {
    const { id } = c.req.valid('query')
    const post: Post | undefined = await getPost(id)

    if (post === undefined) {
      return c.json({ error: 'not found' }, 404) // 指定 404
    }

    return c.json({ post }, 200) // 指定 200
  }
)

export type AppType = typeof app

你可以通过状态码获取数据。

// client.ts
const client = hc<AppType>('http://localhost:8787/')

const res = await client.posts.$get({
  query: {
    id: '123',
  },
})

if (res.status === 404) {
  const data: { error: string } = await res.json()
  console.log(data.error)
}

if (res.ok) {
  const data: { post: Post } = await res.json()
  console.log(data.post)
}

// { post: Post } | { error: string }
type ResponseType = InferResponseType<typeof client.posts.$get>

// { post: Post }
type ResponseType200 = InferResponseType<
  typeof client.posts.$get,
  200
>

Not Found

如果你想使用客户端，则不应将 c.notFound() 用于 Not Found 响应。客户端从服务器获取的数据无法被正确推断。

// server.ts
export const routes = new Hono().get(
  '/posts',
  zValidator(
    'query',
    z.object({
      id: z.string(),
    })
  ),
  async (c) => {
    const { id } = c.req.valid('query')
    const post: Post | undefined = await getPost(id)

    if (post === undefined) {
      return c.notFound() // ❌️
    }

    return c.json({ post })
  }
)

// client.ts
import { hc } from 'hono/client'

const client = hc<typeof routes>('/')

const res = await client.posts[':id'].$get({
  param: {
    id: '123',
  },
})

const data = await res.json() // 🙁 data 是 unknown

请使用 c.json() 并为 Not Found 响应指定状态码。

export const routes = new Hono().get(
  '/posts',
  zValidator(
    'query',
    z.object({
      id: z.string(),
    })
  ),
  async (c) => {
    const { id } = c.req.valid('query')
    const post: Post | undefined = await getPost(id)

    if (post === undefined) {
      return c.json({ error: 'not found' }, 404) // 指定 404
    }

    return c.json({ post }, 200) // 指定 200
  }
)

路径参数

你还可以处理包含路径参数的路由。

const route = app.get(
  '/posts/:id',
  zValidator(
    'query',
    z.object({
      page: z.string().optional(),
    })
  ),
  (c) => {
    // ...
    return c.json({
      title: 'Night',
      body: 'Time to sleep',
    })
  }
)

使用 param 指定你想要包含在路径中的字符串。

const res = await client.posts[':id'].$get({
  param: {
    id: '123',
  },
  query: {},
})

Headers

你可以将 header 附加到请求中。

const res = await client.search.$get(
  {
    //...
  },
  {
    headers: {
      'X-Custom-Header': 'Here is Hono Client',
      'X-User-Agent': 'hc',
    },
  }
)

要为所有请求添加通用 header，请将其指定为 hc 函数的参数。

const client = hc<AppType>('/api', {
  headers: {
    Authorization: 'Bearer TOKEN',
  },
})

init 选项

你可以将 fetch 的 RequestInit 对象作为 init 选项传递给请求。以下是中止 Request 的示例。

import { hc } from 'hono/client'

const client = hc<AppType>('http://localhost:8787/')

const abortController = new AbortController()
const res = await client.api.posts.$post(
  {
    json: {
      // Request body
    },
  },
  {
    // RequestInit object
    init: {
      signal: abortController.signal,
    },
  }
)

// ...

abortController.abort()

INFO

由 init 定义的 RequestInit 对象具有最高优先级。它可以用于覆盖由其他选项（如 body | method | headers）设置的内容。

$url()

你可以使用 $url() 获取用于访问端点的 URL 对象。

WARNING

你必须传入绝对 URL 才能使其工作。传入相对 URL / 将导致以下错误。

Uncaught TypeError: Failed to construct 'URL': Invalid URL

// ❌ 会抛出错误
const client = hc<AppType>('/')
client.api.post.$url()

// ✅ 会按预期工作
const client = hc<AppType>('http://localhost:8787/')
client.api.post.$url()

const route = app
  .get('/api/posts', (c) => c.json({ posts }))
  .get('/api/posts/:id', (c) => c.json({ post }))

const client = hc<typeof route>('http://localhost:8787/')

let url = client.api.posts.$url()
console.log(url.pathname) // `/api/posts`

url = client.api.posts[':id'].$url({
  param: {
    id: '123',
  },
})
console.log(url.pathname) // `/api/posts/123`

自定义 fetch 方法

你可以设置自定义 fetch 方法。

在以下 Cloudflare Worker 的示例脚本中，使用了 Service Bindings 的 fetch 方法来代替默认的 fetch。

# wrangler.toml
services = [
  { binding = "AUTH", service = "auth-service" },
]

// src/client.ts
const client = hc<CreateProfileType>('/', {
  fetch: c.env.AUTH.fetch.bind(c.env.AUTH),
})

Infer

使用 InferRequestType 和 InferResponseType 来了解要请求的对象的类型和要返回的对象的类型。

import type { InferRequestType, InferResponseType } from 'hono/client'

// InferRequestType
const $post = client.todo.$post
type ReqType = InferRequestType<typeof $post>['form']

// InferResponseType
type ResType = InferResponseType<typeof $post>

使用 SWR

你还可以使用 React Hook 库，例如 SWR。

import useSWR from 'swr'
import { hc } from 'hono/client'
import type { InferRequestType } from 'hono/client'
import { AppType } from '../functions/api/[[route]]'

const App = () => {
  const client = hc<AppType>('/api')
  const $get = client.hello.$get

  const fetcher =
    (arg: InferRequestType<typeof $get>) => async () => {
      const res = await $get(arg)
      return await res.json()
    }

  const { data, error, isLoading } = useSWR(
    'api-hello',
    fetcher({
      query: {
        name: 'SWR',
      },
    })
  )

  if (error) return <div>failed to load</div>
  if (isLoading) return <div>loading...</div>

  return <h1>{data?.message}</h1>
}

export default App

在大型应用程序中使用 RPC

对于较大的应用程序，例如 构建大型应用程序 中提到的示例，你需要注意类型推断。 一种简单的方法是链式处理 handler，以便始终推断类型。

// authors.ts
import { Hono } from 'hono'

const app = new Hono()
  .get('/', (c) => c.json('list authors'))
  .post('/', (c) => c.json('create an author', 201))
  .get('/:id', (c) => c.json(`get ${c.req.param('id')}`))

export default app

// books.ts
import { Hono } from 'hono'

const app = new Hono()
  .get('/', (c) => c.json('list books'))
  .post('/', (c) => c.json('create a book', 201))
  .get('/:id', (c) => c.json(`get ${c.req.param('id')}`))

export default app

然后你可以像往常一样导入子路由，并确保你也链式处理它们的 handler，因为在这种情况下，这是应用程序的顶层，这是我们想要导出的类型。

// index.ts
import { Hono } from 'hono'
import authors from './authors'
import books from './books'

const app = new Hono()

const routes = app.route('/authors', authors).route('/books', books)

export default app
export type AppType = typeof routes

现在你可以使用注册的 AppType 创建一个新的客户端，并像往常一样使用它。

已知问题

IDE 性能

当使用 RPC 时，路由越多，你的 IDE 就会变得越慢。其中一个主要原因是执行了大量的类型实例化来推断你的应用程序的类型。

例如，假设你的应用程序具有如下路由：

// app.ts
export const app = new Hono().get('foo/:id', (c) =>
  c.json({ ok: true }, 200)
)

Hono 将按如下方式推断类型：

export const app = Hono<BlankEnv, BlankSchema, '/'>().get<
  'foo/:id',
  'foo/:id',
  JSONRespondReturn<{ ok: boolean }, 200>,
  BlankInput,
  BlankEnv
>('foo/:id', (c) => c.json({ ok: true }, 200))

这是一个单路由的类型实例化。虽然用户不需要手动编写这些类型参数（这是一件好事），但众所周知，类型实例化非常耗时。你 IDE 中使用的 tsserver 每次你使用应用程序时都会执行这个耗时的任务。如果你有很多路由，这会显着降低你的 IDE 速度。

但是，我们有一些技巧可以缓解这个问题。

Hono 版本不匹配

如果你的后端与前端分离并且位于不同的目录中，则需要确保 Hono 版本匹配。 如果你在后端使用一个 Hono 版本，而在前端使用另一个版本，则会遇到诸如 “Type instantiation is excessively deep and possibly infinite” 之类的问题。

TypeScript 项目引用

与 Hono 版本不匹配 的情况一样，如果你的后端和前端是分开的，你也会遇到问题。 如果你想在前台访问来自后端（例如 AppType）的代码，则需要使用 项目引用。 TypeScript 的项目引用允许一个 TypeScript 代码库访问和使用来自另一个 TypeScript 代码库的代码。（来源：Hono RPC And TypeScript Project References）。

在使用代码之前编译它（推荐）

tsc 可以在编译时执行类型实例化等繁重任务！ 这样，tsserver 就不需要在每次使用它时都实例化所有类型参数。这将使你的 IDE 快得多！

编译你的客户端（包括服务端应用）可以提供最佳性能。将以下代码放在你的项目中：

import { app } from './app'
import { hc } from 'hono/client'

// this is a trick to calculate the type when compiling
const client = hc<typeof app>('')
export type Client = typeof client

export const hcWithType = (...args: Parameters<typeof hc>): Client =>
  hc<typeof app>(...args)

编译后，你可以使用 hcWithType 而不是 hc 来获取类型已计算的客户端。

const client = hcWithType('http://localhost:8787/')
const res = await client.posts.$post({
  form: {
    title: 'Hello',
    body: 'Hono is a cool project',
  },
})

如果你的项目是 monorepo，此解决方案非常适用。使用像 turborepo 这样的工具，你可以轻松地分离服务端项目和客户端项目，并在它们之间获得更好的集成来管理依赖关系。这是一个可行的示例。

你还可以使用 concurrently 或 npm-run-all 等工具手动协调你的构建过程。

手动指定类型参数

这有点麻烦，但是你可以手动指定类型参数以避免类型实例化。

const app = new Hono().get<'foo/:id'>('foo/:id', (c) =>
  c.json({ ok: true }, 200)
)

仅指定单个类型参数就可以在性能上有所不同，但是如果你有很多路由，则可能需要花费大量时间和精力。

将你的应用程序和客户端拆分为多个文件

如 在大型应用程序中使用 RPC 中所述，你可以将你的应用程序拆分为多个应用程序。你还可以为每个应用程序创建一个客户端：

// authors-cli.ts
import { app as authorsApp } from './authors'
import { hc } from 'hono/client'

const authorsClient = hc<typeof authorsApp>('/authors')

// books-cli.ts
import { app as booksApp } from './books'
import { hc } from 'hono/client'

const booksClient = hc<typeof booksApp>('/books')

这样，tsserver 就不需要一次实例化所有路由的类型。