该技能面向 TypeScript 前后端工程师,用于构建、更新或重构 oRPC 契约、服务端处理器、客户端与 React Query 集成时遵循统一的 Contract-First 开发规范。
主要能力与约束:契约定义遵循 API First;API 路径与资源名必须使用单数形式(如 /api/user,不能是 /api/users),嵌套契约键也用单数(如 user: UserContract)。需先定义实体 Schema,再定义契约,使用 oc 与 z 定义 input/output/route。服务端实现用 implement 与 handler,错误必须抛出 ORPCError 并使用标准错误码(NOT_FOUND、BAD_REQUEST、UNAUTHORIZED、FORBIDDEN、CONFLICT、INTERNAL_SERVER_ERROR)。
Schema 与错误处理约束:字符串字段必须追加 .describe('...') 以生成前端提示;日期必须用 z.coerce.date();可选性优先用 .nullish();仅当标准 Zod 校验过重时才用 oc.output(type<ComplexType>()) 绕过校验;文件上传必须用 z.instanceof(File);必须导出推断类型(如 export type User = z.infer<typeof UserSchema>)。
使用方式:客户端通过 createRpcContractClient 创建,再用 createORPCReactQueryUtils 生成工具,在 React 组件中以 useQuery(orpc.user.list.queryOptions({ input: { limit: 20 } })) 调用。协议选择规则:前端使用 RPC 协议(/api/rpc),外部或第三方 API 使用 OpenAPI 协议(/api)。
限制:涉及外部 REST API 建模、Hono 集成、文件/Blob 上传、SSE/流式传输或 AsyncIterator 转换等复杂模式时,必须先阅读 references/orpc-pattern.md,不得猜测。其他细节资料暂未提供。