SuperAPI AI 工具集

orpc-contract

编程与开发

查看项目

更新于 10-16 01:14

技能介绍

用途:把 oRPC v2 API 拆成契约与实现两部分,契约用 @orpc/contract 的 oc 定义(仅 schema、错误、元数据,无业务逻辑),实现用 @orpc/server 的 implement 构建。服务端与客户端都依赖契约而非彼此,便于独立评审和发布为类型安全 SDK。适用于服务端与客户端分属不同包或团队、形状源自已有 OpenAPI 规范、或需要发布 npm 客户端的场景;同一代码库能直接导入 router 类型时可继续 os 优先。

主要能力:契约中可定义 .output(不定义则客户端推断为 unknown)、.errors 类型安全错误、.meta 共享元数据,并支持 Zod、Valibot、ArkType 等 Standard Schema 库及无库的 type 工具;重复 .input/.output 会叠加 schema。implement 会镜像契约形状并做类型检查,支持 .$context、逐过程 .use(mw) 中间件,产出普通 router 后可用 RPCHandler、OpenAPIHandler 服务或用 call/createRouterClient 进程内调用。

客户端:RPCLink 只需契约类型;OpenAPILink 需把契约作为运行时值读取路由,类型应用 JsonifiedClient。可用 RouterContractClient<typeof contract, ClientContext> 传每次调用上下文。契约可从 router 用 minifyRouterContract 压缩导出 JSON。

用法与生成:从已有 OpenAPI 规范生成契约时可装 @hey-api/openapi-ts@next 并配置 orpc 插件(compatibilityVersion: '2'、validator: 'zod'),运行 npx @hey-api/openapi-ts 生成 orpc.gen.ts 等。发布 npm 客户端可用 tsdown --dts src/index.ts 打包。

限制:该技能针对 oRPC v2,预训练知识多为 v1,API 不确定时先查文档(https://orpc.dev/llms.txt、单页 .md)。契约里避免 then、bind、valueOf、toString、toJSON 等键。Router 级与过程级 .use 可能重复执行同一中间件,需去重。若技能与文档页冲突,以文档页为准。