tRPC类型安全API开发

技能简介

tRPC是一套用于构建端到端类型安全API的框架，无需代码生成或额外Schema定义。服务端与客户端共享TypeScript类型定义，实现编译时类型检查与IDE自动补全。

能做什么

• 构建零配置的类型安全API接口
• 在Next.js项目中集成全栈类型推断
• 通过React Query实现数据获取与状态管理
• 使用Zod进行运行时输入验证
• 支持查询、变更、订阅三种操作类型

使用说明

1. 安装依赖

# Core packages
npm install @trpc/server@next @trpc/client@next @trpc/react-query@next

# Peer dependencies
npm install @tanstack/react-query@latest zod

2. 初始化tRPC实例

import { initTRPC } from '@trpc/server'
const t = initTRPC.create()
export const router = t.router
export const publicProcedure = t.procedure

3. 定义路由与过程

export const appRouter = router({
  hello: publicProcedure
    .input(z.object({ name: z.string() }))
    .query(({ input }) => ({ greeting: `Hello ${input.name}!` })),
})

4. 创建API端点（Next.js App Router）

import { fetchRequestHandler } from '@trpc/server/adapters/fetch'
const handler = (req: Request) =>
  fetchRequestHandler({ endpoint: '/api/trpc', req, router: appRouter, createContext: () => ({}) })
export { handler as GET, handler as POST }

5. 配置客户端Provider

const [trpcClient] = useState(() =>
  trpc.createClient({ links: [httpBatchLink({ url: 'http://localhost:3000/api/trpc' })] })
)

6. 在组件中调用

const hello = trpc.hello.useQuery({ name: 'World' })
const createUser = trpc.createUser.useMutation()

输入与输出

见下方输入与输出表格。

项目	内容
输入	TypeScript项目基础结构、Node.js运行环境、Zod Schema定义、Next.js框架（可选）
输出	类型安全的API路由、客户端类型推断代码、React Query集成配置、端到端类型定义文件
适用人群	熟悉TypeScript的全栈开发者、使用Next.js构建全栈应用的团队、需要替代REST/GraphQL的类型安全方案
不包含	数据库ORM配置（需自行集成Prisma等）、部署与CI/CD流程、身份认证与授权实现、WebSocket传输层配置

 

风险提示

• @next版本为预发布通道，生产环境建议锁定具体版本号
• 需确保服务端与客户端TypeScript版本一致
• 批量链接（httpBatchLink）默认合并请求，调试时需关注网络面板
• 上下文（createContext）未配置认证逻辑时，所有过程均为公开访问

来源信息

原始链接：https://github.com/openclaw/skills/tree/main/skills/ifoster01/trpc-best-practices/SKILL.md
来源类型：GitHub仓库