# 类型安全-rpc ## 概述该存储库是一个类型安全的 RPC 库。服务器接受 POST 主体“{实体，操作，参数}”并运行匹配的处理程序。客户端是一个类型化代理：`client.entity.operation(params, signal?, context?)`。类型是共享的，因此客户端调用是从架构中推断出来的。 ## 核心类型（共享） * **BaseContext** ： `{ 请求：请求 |快递.请求}` * **Args **: `{ params: Params;上下文：上下文}` * **Handler **: `(args: Args) => Promise` * **RpcSchema** : `{ [实体: 字符串]: { [操作: 字符串]: Handler<任何, 任何, 任何> } }` 处理程序仅接收“params”和“context”（没有 ExtraParams）。扩展“BaseContext”以获取特定于应用程序的上下文。 ## 架构和处理程序模式是一个嵌套对象：实体→操作→处理程序。使用“as const”，以便客户端获取文字类型。从 'typesafe-rpc' 导入类型 { BaseContext, Handler }; 类型 Ctx = BaseContext & { userId?: string }; const getItem: Handler<{ id: string }, Ctx, { name: string }> = async ({ params, context }) => { return { name: 'Item' + params.id }; }; 导出 const apiSchema = { 项目：{ getById：获取项目， }, 作为常量； ## 服务器：createRpcHandler 来自`typesafe-rpc/server`：从'typesafe-rpc/server'导入{createRpcHandler}； const 结果 = 等待 createRpcHandler({ context: { request }, // 必须包含 request 操作：apiSchema， errorHandler: (错误) => 新响应(JSON.stringify({ 错误: '...' }), { 状态: 500 }), 钩子：{ 预调用：(args) => {}, postCall：（参数，性能）=> {}，错误：（参数、性能、错误）=> {}， }, }); * 需要 `context.request.method === 'POST'`;主体必须是 JSON `{实体，操作，参数}`。 * 挂钩参数：`{ 实体、操作、参数、上下文 }`。 * 直接返回处理结果；出错时抛出“Response”。 * 如果没有 `errorHandler`，则抛出通用 500 响应。 ## 客户端：createRpcClient 来自“typesafe-rpc/client”：从“typesafe-rpc/client”导入{createRpcClient}；从 './api-schema' 导入类型 { apiSchema }； // 静态标头 const client = createRpcClient('/api/rpc', { 授权: '承载...' }); // 通过函数动态标头（接收传递给调用的上下文） const client = createRpcClient('/api/rpc', (ctx) => ({ 授权：ctx.token， })); const result = wait client.items.getById({ id: '1' }); const withAbort = wait client.items.getById({ id: '1' }, signal); const withContext = wait client.items.getById({ id: '1' }, undefined, context); 客户端签名：`client.entity.operation(params, signal?, context?)`。使用主体“{实体，操作，参数}”调用“POST端点？实体::操作”。使用相同的模式类型（`typeof apiSchema`）进行完整推理。 ## 路由和中间件来自“typesafe-rpc/server”：“Route”、“Middleware”、“orMiddleware”。 * **中间件 **: `(args: Args) => Promise` （抛出异常中止）。 * **路线** ：链 `.middleware(...fns)` 然后链 `.handle(handler)`。 * 多个 `.middleware(a, b, c)`：**OR** — 第一个成功获胜（通过 `orMiddleware`）。 * 链接 `.middleware(a).middleware(b)`：**AND** — 全部按顺序运行。 * **orMiddleware(...middlewares)** ：按顺序运行中间件；返回第一个不抛出的情况；如果全部抛出，则重新抛出第一个错误。 * **OverridableHandler** ： `.handle()` 返回的处理程序有一个 `overrideMiddlewares(...middlewares)` 方法来替换中间件（对于测试有用）。从'typesafe-rpc/server'导入{路由}； const handler = new Route<{ id: string }, BaseContext>() .middleware(authOrAnonymous) .middleware(需要ReadPermission) .handle(async ({ params, context }) => ({ name: '...' })); // 用于测试：绕过中间件 handler.overrideMiddlewares(mockAuth); 使用生成的处理程序作为存储在模式中的函数（例如“getById：处理程序”）。 ## 请求/响应和错误 * 服务器通过 `request.json()` (Fetch) 或 `request.body` (Express) 读取正文。 * 客户端发送 JSON 并使用“response.json()”解析响应。不正常的响应会抛出“FetchError”。 ### 获取错误来自“typesafe-rpc/client”：从'typesafe-rpc/client'导入{FetchError}；类 FetchError 扩展错误 { 只读键：字符串； // 来自响应 JSON 的错误键，或“internalError” 只读状态：数量； // HTTP 状态码只读数据？：任何； // 来自响应 JSON 的可选数据 } 客户端将错误响应解析为 JSON `{ key, message, data }`。如果解析失败，“key”默认为“internalError”，“message”是原始响应文本。 ## 本仓库中的约定 * 模式和共享类型位于“shared/”中；服务器在“server/”中，客户端在“client/”中。 * 实现遵循 `libs/typesafe-rpc/src/shared/rpc-types.ts` 中的类型。如果它们不同（例如处理程序中没有 ExtraParams），则优先选择它们而不是 README。 * 有关完整的 API 和示例，请参阅项目 [README]()。

类型安全的远程过程调用

包含技能