orpc-fullstack

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

oRPC — Typesafe APIs Made Simple

oRPC — 让类型安全API变得简单

oRPC combines RPC with OpenAPI for end-to-end type-safe APIs (v1.12+). It supports Zod, Valibot, Arktype, or any Standard Schema library.

oRPC将RPC与OpenAPI相结合，打造端到端的类型安全API（v1.12+）。它支持Zod、Valibot、Arktype或任何标准Schema库。

When to Apply

适用场景

Reference these guidelines when:

Creating or modifying API procedures (contracts, routers, handlers)
Setting up middleware (auth, authorization guards, logging)
Integrating oRPC with Hono or other server frameworks
Building data fetching hooks with TanStack Query
Implementing real-time features with event iterators / SSE
Configuring client links (fetch, WebSocket, batch, retry)
Handling errors (server-side ORPCError, client-side typed errors)

参考以下场景使用：

创建或修改API过程（契约、路由、处理器）
配置中间件（认证、授权守卫、日志）
将oRPC与Hono或其他服务器框架集成
使用TanStack Query构建数据获取钩子
利用事件迭代器/SSE实现实时功能
配置客户端链接（fetch、WebSocket、批量处理、重试）
错误处理（服务器端ORPCError、客户端类型化错误）

Core Concepts

核心概念

Concept	Import	Purpose
Contract	`oc` from `@orpc/contract`	Define API shape without handlers
Procedure	`os` from `@orpc/server`	Function with validation + middleware + DI
Router	Plain object	Compose procedures into a tree
Middleware	`os.middleware()`	Intercept, inject context, guard access
Handler	`OpenAPIHandler` / `RPCHandler`	Serve procedures over HTTP/WS
Client	`createORPCClient` + link	Type-safe client from contract/router
TanStack Query	`createTanstackQueryUtils`	React hooks for queries/mutations

概念	导入方式	用途
Contract	从 `@orpc/contract` 导入 `oc`	无需处理器即可定义API结构
Procedure	从 `@orpc/server` 导入 `os`	包含验证、中间件和依赖注入的函数
Router	普通对象	将多个过程组合成树形结构
Middleware	`os.middleware()`	拦截请求、注入上下文、守卫访问权限
Handler	`OpenAPIHandler` / `RPCHandler`	通过HTTP/WS提供过程服务
Client	`createORPCClient` + link	基于契约/路由创建的类型安全客户端
TanStack Query	`createTanstackQueryUtils`	用于查询/变更的React钩子

Project Structure

项目结构

Organize by domain modules with paired contract + router files:

src/
  index.ts                    # Hono app + handler setup
  middlewares/
    auth-middleware.ts         # Session validation -> injects user
  modules/
    contract.ts               # Root barrel: all contracts
    router.ts                 # Root barrel: all routers
    health/
      health.contract.ts
      health.router.ts
    user/
      user.contract.ts
      user.router.ts

Root barrels compose modules:

export default { health, user }

按领域模块组织，每个模块对应契约+路由文件：

src/
  index.ts                    # Hono应用 + 处理器配置
  middlewares/
    auth-middleware.ts         # 会话验证 -> 注入用户信息
  modules/
    contract.ts               # 根入口：所有契约
    router.ts                 # 根入口：所有路由
    health/
      health.contract.ts
      health.router.ts
    user/
      user.contract.ts
      user.router.ts

根入口文件组合各个模块：

export default { health, user }

。

Contract-First Development

契约优先开发

Contracts define API shape. Routers implement them with TypeScript enforcement.

// Contract — define shape
import { oc } from "@orpc/contract";
import { z } from "zod/v4";

const userContract = oc
  .route({ tags: ["user"] })
  .errors({ UNAUTHORIZED: {} });

const searchUser = userContract
  .route({ method: "POST", path: "/user/search" })
  .input(z.object({ query: z.string() }))
  .output(z.array(userSchema));

export default { searchUser };

// Router — implement contract
import { implement } from "@orpc/server";
import contract from "./user.contract";

const router = implement(contract).$context<{ headers: Headers }>();

const searchUser = router.searchUser
  .use(authMiddleware)
  .handler(async ({ input, context }) => { /* ... */ });

export default { searchUser };

契约定义API结构，路由通过TypeScript约束来实现这些契约。

// Contract — 定义结构
import { oc } from "@orpc/contract";
import { z } from "zod/v4";

const userContract = oc
  .route({ tags: ["user"] })
  .errors({ UNAUTHORIZED: {} });

const searchUser = userContract
  .route({ method: "POST", path: "/user/search" })
  .input(z.object({ query: z.string() }))
  .output(z.array(userSchema));

export default { searchUser };

// Router — 实现契约
import { implement } from "@orpc/server";
import contract from "./user.contract";

const router = implement(contract).$context<{ headers: Headers }>();

const searchUser = router.searchUser
  .use(authMiddleware)
  .handler(async ({ input, context }) => { /* ... */ });

export default { searchUser };

Procedures

过程定义

import { os } from "@orpc/server";

const example = os
  .use(aMiddleware)                         // Middleware
  .input(z.object({ name: z.string() }))   // Validate input
  .output(z.object({ id: z.number() }))    // Validate output (recommended)
  .handler(async ({ input, context }) => {  // Handler
    return { id: 1 };
  });

```
.handler
```
is the only required step
Specifying
```
.output
```
improves TypeScript inference speed

Create reusable bases:

const protectedProcedure = os.$context<Ctx>().use(authMiddleware)

import { os } from "@orpc/server";

const example = os
  .use(aMiddleware)                         // 中间件
  .input(z.object({ name: z.string() }))   // 验证输入
  .output(z.object({ id: z.number() }))    // 验证输出（推荐）
  .handler(async ({ input, context }) => {  // 处理器
    return { id: 1 };
  });

```
.handler
```
是唯一必填步骤
指定
```
.output
```
可提升TypeScript推断速度

可创建可复用基础模板：

const protectedProcedure = os.$context<Ctx>().use(authMiddleware)

Middleware

中间件

Auth middleware injects user into context:

export const authMiddleware = os
  .$context<{ headers: Headers }>()
  .middleware(async ({ context, next }) => {
    const session = await auth.api.getSession({ headers: context.headers });
    if (!session) throw new ORPCError("UNAUTHORIZED");
    return next({ context: { ...context, user: session.user } });
  });

Input-aware middleware for authorization guards:

export const membershipGuard = os
  .$context<{ user: User }>()
  .middleware(async ({ context, next }, input: { uuid: string }) => {
    // Check membership using input.uuid + context.user.id
    if (!member) throw new ORPCError("FORBIDDEN");
    return next();
  });

Stack middleware left-to-right:

.use(auth).use(guard).handler(...)

Built-ins:

onStart

onSuccess

onError

onFinish

dedupeMiddleware

认证中间件将用户信息注入上下文：

export const authMiddleware = os
  .$context<{ headers: Headers }>()
  .middleware(async ({ context, next }) => {
    const session = await auth.api.getSession({ headers: context.headers });
    if (!session) throw new ORPCError("UNAUTHORIZED");
    return next({ context: { ...context, user: session.user } });
  });

感知输入的中间件用于授权守卫：

export const membershipGuard = os
  .$context<{ user: User }>()
  .middleware(async ({ context, next }, input: { uuid: string }) => {
    // 使用input.uuid + context.user.id检查成员资格
    if (!member) throw new ORPCError("FORBIDDEN");
    return next();
  });

按从左到右顺序堆叠中间件：

.use(auth).use(guard).handler(...)

。

内置中间件：

onStart

onSuccess

onError

onFinish

dedupeMiddleware

。

Error Handling

错误处理

// Server — throw errors
throw new ORPCError("NOT_FOUND");
throw new ORPCError("BAD_REQUEST", { message: "Invalid input" });

// Contract-defined typed errors
const contract = oc.errors({
  RATE_LIMITED: { data: z.object({ retryAfter: z.number() }) },
});

// Handler uses typed factory
const proc = implement(contract).handler(async ({ errors }) => {
  throw errors.RATE_LIMITED({ data: { retryAfter: 60 } });
});

// Client — handle errors
const [error, data] = await safe(client.doSomething({ id: "123" }));
if (isDefinedError(error)) { /* typed from contract */ }

// 服务器端 — 抛出错误
throw new ORPCError("NOT_FOUND");
throw new ORPCError("BAD_REQUEST", { message: "Invalid input" });

// 契约定义的类型化错误
const contract = oc.errors({
  RATE_LIMITED: { data: z.object({ retryAfter: z.number() }) },
});

// 处理器使用类型化工厂函数
const proc = implement(contract).handler(async ({ errors }) => {
  throw errors.RATE_LIMITED({ data: { retryAfter: 60 } });
});

// 客户端 — 处理错误
const [error, data] = await safe(client.doSomething({ id: "123" }));
if (isDefinedError(error)) { /* 从契约继承类型 */ }

Hono Integration

Hono集成

import { OpenAPIHandler } from "@orpc/openapi/fetch";
import { Hono } from "hono";

const handler = new OpenAPIHandler(router, { /* plugins, interceptors */ });

const app = new Hono()
  .basePath("/api")
  .use("/rpc/*", async (c, next) => {
    const { matched, response } = await handler.handle(c.req.raw, {
      prefix: "/api/rpc",
      context: { headers: c.req.raw.headers },
    });
    if (matched) return c.newResponse(response.body, response);
    await next();
  });

import { OpenAPIHandler } from "@orpc/openapi/fetch";
import { Hono } from "hono";

const handler = new OpenAPIHandler(router, { /* 插件、拦截器 */ });

const app = new Hono()
  .basePath("/api")
  .use("/rpc/*", async (c, next) => {
    const { matched, response } = await handler.handle(c.req.raw, {
      prefix: "/api/rpc",
      context: { headers: c.req.raw.headers },
    });
    if (matched) return c.newResponse(response.body, response);
    await next();
  });

TanStack Query

import { createTanstackQueryUtils } from "@orpc/tanstack-query";
const orpc = createTanstackQueryUtils(client);

// Queries
useQuery(orpc.user.search.queryOptions({ input: { query } }));

// Mutations
useMutation(orpc.vehicle.add.mutationOptions());

// Infinite queries
useInfiniteQuery(orpc.feed.list.infiniteOptions({
  input: (pageParam) => ({ cursor: pageParam, limit: 20 }),
  initialPageParam: undefined,
  getNextPageParam: (lastPage) => lastPage.nextCursor,
}));

// Keys for invalidation
orpc.vehicle.key()                           // All vehicle queries
queryClient.invalidateQueries({ queryKey: orpc.vehicle.key() });

import { createTanstackQueryUtils } from "@orpc/tanstack-query";
const orpc = createTanstackQueryUtils(client);

// 查询
useQuery(orpc.user.search.queryOptions({ input: { query } }));

// 变更
useMutation(orpc.vehicle.add.mutationOptions());

// 无限查询
useInfiniteQuery(orpc.feed.list.infiniteOptions({
  input: (pageParam) => ({ cursor: pageParam, limit: 20 }),
  initialPageParam: undefined,
  getNextPageParam: (lastPage) => lastPage.nextCursor,
}));

// 用于失效的键
orpc.vehicle.key()                           // 所有车辆相关查询
queryClient.invalidateQueries({ queryKey: orpc.vehicle.key() });

Event Iterator (SSE / Streaming)

事件迭代器（SSE/流式处理）

// Server — async generator
const live = os
  .output(eventIterator(z.object({ message: z.string() })))
  .handler(async function* ({ signal }) {
    for await (const payload of publisher.subscribe("topic", { signal })) {
      yield payload;
    }
  });

// Client — consume
for await (const event of await client.live()) {
  console.log(event.message);
}

Use

EventPublisher

for typed pub/sub between handlers.

// 服务器端 — 异步生成器
const live = os
  .output(eventIterator(z.object({ message: z.string() })))
  .handler(async function* ({ signal }) {
    for await (const payload of publisher.subscribe("topic", { signal })) {
      yield payload;
    }
  });

// 客户端 — 消费流
for await (const event of await client.live()) {
  console.log(event.message);
}

使用

EventPublisher

实现处理器之间的类型化发布/订阅。

Client Setup

客户端配置

import { RPCLink } from "@orpc/client/fetch";
import { createORPCClient } from "@orpc/client";

const link = new RPCLink({
  url: "http://localhost:3000/api/rpc",
  headers: () => ({ Authorization: `Bearer ${getToken()}` }),
});

export const client = createORPCClient(link);

WebSocket:

import { RPCLink } from "@orpc/client/websocket"

import { RPCLink } from "@orpc/client/fetch";
import { createORPCClient } from "@orpc/client";

const link = new RPCLink({
  url: "http://localhost:3000/api/rpc",
  headers: () => ({ Authorization: `Bearer ${getToken()}` }),
});

export const client = createORPCClient(link);

WebSocket链接：

import { RPCLink } from "@orpc/client/websocket"

。

Detailed Reference

详细参考

For comprehensive examples, advanced patterns, and full API coverage see:

Full Reference — Complete documentation with detailed code examples covering contracts, routers, middleware, server handlers, client setup, TanStack Query, event iterators, plugins, file uploads, WebSocket, AI SDK integration, and metadata.

如需查看完整示例、高级模式及完整API覆盖内容，请参考：

完整参考文档 — 包含详细代码示例的完整文档，覆盖契约、路由、中间件、服务器处理器、客户端配置、TanStack Query、事件迭代器、插件、文件上传、WebSocket、AI SDK集成及元数据等内容。