# oRPC 指南 oRPC 是一个类型安全的 RPC 框架，它将端到端类型安全性与 OpenAPI 合规性相结合。它支持跨 20 多个框架适配器的过程、路由器、中间件、上下文注入、错误处理、文件上传、流式传输 (SSE)、服务器操作和合约优先开发。 **范围**：本指南专门针对 oRPC 库（`@orpc/*` 包）。它不是通用的 RPC/gRPC 指南，不适用于仅 tRPC 的项目（除非迁移到 oRPC），也不适用于没有 oRPC 的通用 TypeScript API 开发。有关 tRPC 到 oRPC 的迁移，请参阅“references/contract-first.md”。 ## 快速入门 ### 安装 npm install @orpc/server@latest @orpc/client@latest 对于 OpenAPI 支持，还需安装： npm 安装@orpc/openapi@latest ### 先决条件 * Node.js 18+（推荐20+）|包子|德诺 | Cloudflare 工人 * 推荐使用严格模式的TypeScript项目 * 支持 Zod、Valibot、ArkType 和任何标准架构库 ### 定义过程和路由器从 '@orpc/server' 导入 { ORPCError, os } 从 'zod' 导入 * as z const PlanetSchema = z.object({ id: z.number().int().min(1), 名称： z.string(), 描述：z.string().可选(), }) 导出 const listPlanet = os .input(z.object({ 限制：z.number().int().min(1).max(100).Optional(), 光标：z.number().int().min(0).default(0), }）） .handler(async({ 输入}) => { 返回 [{ id: 1, name: '地球' }] }) 导出 const findPlanet = os .input(PlanetSchema.pick({ id: true })) .handler(async({ 输入}) => { 返回 { id: 1, name: '地球' } }) 导出 const createPlanet = os .$context<{ headers: headers }>() .use(({ 上下文, 下一个 }) => { const user = parseJWT(context.headers.get('授权')?.split(' ')[1]) 如果（用户）返回下一个（{上下文：{用户}}）抛出新的 ORPCError('未经授权') }) .input(PlanetSchema.omit({ id: true })) .handler(async ({ 输入, 上下文 }) => { 返回 { id: 1, 名称: input.name } }) 导出常量路由器= { 星球：{ 列表：listPlanet，查找：findPlanet，创建：createPlanet }， } ### 创建服务器 (Node.js) 从 'node:http' 导入 { createServer } 从 '@orpc/server/node' 导入 { RPCHandler } 从 '@orpc/server/plugins' 导入 { CORSPlugin } 从 '@orpc/server' 导入 { onError } const 处理程序 = new RPCHandler(路由器, { 插件：[新的 CORSPlugin()]，拦截器：[onError((error) => console.error(error))], }) const 服务器 = createServer(async (req, res) => { const { 匹配 } = wait handler.handle(req, res, { 前缀：'/rpc'， context: { headers: new Headers(req.headers as Record) }, }) 如果（！匹配）{ res.statusCode = 404 res.end('未找到') } }) 服务器.听(3000) ### 创建客户端从 '@orpc/server' 导入类型 { RouterClient } 从 '@orpc/client' 导入 { createORPCClient } 从 '@orpc/client/fetch' 导入 { RPCLink } const 链接 = 新 RPCLink({ url: 'http://127.0.0.1:3000/rpc', headers: { 授权: '不记名令牌' }, }) const client: RouterClient<路由器类型> = createORPCClient(link) // 完全类型化调用 const 行星 = 等待 client.planet.list({ limit: 10 }) const 行星 = 等待 client.planet.find({ id: 1 }) ### 服务器端客户端（无 HTTP）直接调用过程，无需 HTTP 开销——这对于 Next.js、Nuxt、SvelteKit 等中的 SSR 至关重要。从 '@orpc/server' 导入 { call, createRouterClient } // 单个过程调用 const 结果 = 等待调用(router.planet.find, { id: 1 }, { context: {} }) // 路由器客户端（多个过程） const serverClient = createRouterClient(路由器, { 上下文： async () => ({ headers: wait headers() }), }) const Planets = 等待 serverClient.planet.list({ limit: 10 }) 对各个过程使用`.callable()`： const getPlanet = 操作系统 .input(z.object({ id: z.string() })) .handler(async ({ input }) => ({ id: input.id })) .callable({ 上下文: {} }) const 结果 = 等待 getPlanet({ id: '123' }) 有关完整的服务器端调用模式，请参阅“references/api-reference.md”。 ## 核心概念 ### 程序链 const 示例 = 操作系统 .use(middleware) // 应用中间件 .input(z.object({...})) // 验证输入 (Zod/Valibot/ArkType) .output(z.object({...})) // 验证输出（推荐用于性能） .handler(async ({ input, context }) => { ... }) // 必需 .callable() // 使可调用函数成为常规函数 .actionable() // 服务器操作兼容性仅需要`.handler()`。所有其他链方法都是可选的。 ### 路由器路由器是过程的普通对象。它们可以嵌套并支持延迟加载：常量路由器= { ping: os.handler(async () => 'pong'), Planet: os.lazy(() => import('./planet')), // 代码分割 } 将中间件应用于路由器中的所有过程： const router = os.use(authMiddleware).router({ ping, pong }) ### 中间件 const authMiddleware = 操作系统 .$context<{ headers: headers }>() .middleware(async ({ context, next }) => { const user = 等待 getUser(context.headers) if (!user) 抛出 new ORPCError('UNAUTHORIZED') 返回下一个（{上下文：{用户}}） }) 内置生命周期中间件：`onStart`、`onSuccess`、`onError`、`onFinish`。 ### 上下文两种类型：**初始上下文**（在创建处理程序时提供）和**执行上下文**（在运行时由中间件注入）。请参阅“references/api-reference.md”。 ### 错误处理 // 正常方法 throw new ORPCError('NOT_FOUND', { message: '找不到行星' }) // 类型安全方法 const 基 = os.errors({ NOT_FOUND: { message: '未找到' }, RATE_LIMITED: { data: z.object({ retryAfter: z.number() }) }, }) **警告**：`ORPCError.data` 被发送到客户端。切勿包含敏感信息。 ### 事件迭代器（SSE/流）常量流 = 操作系统 .output(eventIterator(z.object({ message: z.string() }))) .handler(异步函数* ({ 输入, lastEventId }) { 而（真）{ 产量 { 消息： '你好！' } 等待新的 Promise(r => setTimeout(r, 1000)) } }) ### 文件上传/下载常量上传=操作系统 .input(z.file()) .handler(async({ 输入}) => { console.log(input.name) // 文件名返回 { 成功：真 } }) 对于大于 100MB 的上传，请使用专用上传解决方案或扩展正文解析器。 ### 内置助手 oRPC 为常见服务器任务提供内置帮助程序： * **Cookies** : `getCookie`, `setCookie`, `deleteCookie` from `@orpc/server/helpers` * **Cookie 签名** : `sign`, `unsign` 用于防篡改 cookie * **加密** ：敏感数据的“加密”、“解密”（AES-GCM 和 PBKDF2） * **速率限制** ：带有 Memory、Redis、Upstash 和 Cloudflare 适配器的“@orpc/experimental-ratelimit” * **事件发布** ：`@orpc/experimental-publisher` 用于具有恢复支持的分布式发布/订阅有关完整的 API 和示例，请参阅“references/helpers.md”。 ## 关键规则和限制 1. **需要 Handler** \- `.handler()` 是过程中唯一需要的方法 2. **推荐输出模式** \- 显式指定 `.output()` 以获得更好的 TypeScript 性能 3. **中间件重复数据删除** \- oRPC 自动重复数据删除领先的中间件；使用上下文防护进行手动重复数据删除 4. **错误数据是公开的** \- 切勿将敏感信息放入`ORPCError.data`中 5. **主体解析器冲突** \- 在 oRPC 中间件（Express、Fastify、Elysia）之后注册框架主体解析器 6. **RPCHandler 与 OpenAPIHandler** \- RPCHandler 使用专有协议（仅适用于 RPCLink）； OpenAPIHandler 与 REST/OpenAPI 兼容 7. **惰性路由器** \- 使用 `os.lazy(() => import('./module'))` 进行代码分割；使用独立的“lazy()”进行更快的类型推断 8. **SSE 自动重新连接** \- 标准 SSE 客户端自动重新连接；使用“lastEventId”恢复流 9. **文件限制** \- 没有分块/可恢复上传； AsyncIteratorObject 中不支持文件/Blob 10. **React Native** \- Fetch API 有限制（没有文件/Blob，没有事件迭代器）；使用“expo/fetch”或 RPC JSON Serializer 解决方法 ## 处理程序设置模式所有适配器都遵循以下模式： import { RPCHandler } from '@orpc/server/fetch' // 或 /node、/fastify 等。 const 处理程序 = new RPCHandler(路由器, { 插件：[新的 CORSPlugin()]，拦截器：[onError((error) => console.error(error))], }) // 处理带有前缀和上下文的请求 const { 匹配，响应 } = wait handler.handle(request, { 前缀：'/rpc'，上下文：{}， }) ## 客户端设置模式 import { RPCLink } from '@orpc/client/fetch' // HTTP import { RPCLink } from '@orpc/client/websocket' // WebSocket import { RPCLink } from '@orpc/client/message-port' // 消息端口 ## 常见错误错误代码 | HTTP 状态 |当 ---|---|--- `BAD_REQUEST` | 400 |输入验证失败 `未经授权` | 401 | 401身份验证缺失/无效 `禁止` | 403 | 403权限不足 `NOT_FOUND` | 404 | 404找不到资源 `超时` | 408 | 408请求超时 `太多的请求` | 429 | 429速率有限 `内部服务器错误` | 500 | 500未处理的错误非 ORPCError 异常会自动转换为“INTERNAL_SERVER_ERROR”。 ## 参考文件 * **[API 参考]()** \- 过程、路由器、中间件、上下文、错误、元数据、事件迭代器、服务器操作、文件处理 * **[适配器]()** \- 所有 20 多个框架适配器以及设置代码（Next.js、Express、Hono、Fastify、WebSocket、Electron 等） * **[Plugins]()** \- 所有内置插件（CORS、批处理、重试、压缩、CSRF、验证等） * **[OpenAPI]()** \- OpenAPI 规范生成、处理程序、路由、输入/输出结构、标量 UI、OpenAPILink * **[集成]()** \- TanStack 查询、React SWR、Pinia Colada、Better Auth、AI SDK、Sentry、Pino、OpenTelemetry * **[高级]()** \- 测试、序列化、TypeScript 最佳实践、发布客户端、正文解析、游乐场、生态系统 * **[Contract-First]()** \- 合约优先开发、tRPC 迁移指南、与替代方案的比较 * **[Helpers]()** \- Cookie 管理、签名、加密、速率限制、带有事件恢复的发布者 * **[NestJS]()** \- NestJS 与装饰器集成、依赖注入、契约优先

兽人指南

包含技能