# pnpm（推荐）
pnpm add @trpc/server @trpc/client zod
 
# npm
npm install @trpc/server @trpc/client zod
 
# yarn
yarn add @trpc/server @trpc/client zod

# pnpm
pnpm add @trpc/react-query @tanstack/react-query
 
# npm
npm install @trpc/react-query @tanstack/react-query

# pnpm
pnpm add @trpc/next
 
# npm
npm install @trpc/next

pnpm add superjson

// server/trpc.ts
import { initTRPC } from '@trpc/server'
import { z } from 'zod'
 
// 初始化 tRPC 实例
const t = initTRPC.create()
 
// 创建基础 router
export const router = t.router
 
// 创建基础 procedure（未认证的公共过程）
export const publicProcedure = t.procedure

// server/routers/_app.ts
import { z } from 'zod'
import { router, publicProcedure } from '../trpc'
 
export const appRouter = router({
  // 定义一个 query
  greeting: publicProcedure
    .input(z.object({ name: z.string() }))
    .query(({ input }) => {
      return `Hello, ${input.name}!`
    }),
 
  // 定义一个 mutation
  createPost: publicProcedure
    .input(z.object({
      title: z.string().min(1).max(200),
      content: z.string(),
      published: z.boolean().optional(),
    }))
    .mutation(({ input }) => {
      // 执行创建逻辑
      return { id: '1', ...input, createdAt: new Date() }
    }),
 
  // 嵌套 router
  user: router({
    getById: publicProcedure
      .input(z.string())
      .query(({ input }) => {
        return { id: input, name: 'John Doe', email: '[email protected]' }
      }),
  }),
})
 
// 导出 router 类型供客户端使用
export type AppRouter = typeof appRouter

// server/index.ts
import { createHTTPServer } from '@trpc/server/adapters/standalone'
import { appRouter } from './routers/_app'
 
const server = createHTTPServer({
  router: appRouter,
})
 
server.listen(3000)
console.log('tRPC server listening on http://localhost:3000')

// client/index.ts
import { createTRPCClient, httpBatchLink } from '@trpc/client'
import type { AppRouter } from '../server/routers/_app'
 
const trpc = createTRPCClient<AppRouter>({
  links: [
    httpBatchLink({
      url: 'http://localhost:3000',
    }),
  ],
})
 
// 使用——完整类型推断！
async function main() {
  const greeting = await trpc.greeting.query({ name: 'World' })
  console.log(greeting) // "Hello, World!"
 
  const post = await trpc.createPost.mutate({
    title: 'My First Post',
    content: 'This is my first post content.',
  })
  console.log(post)
 
  const user = await trpc.user.getById.query('user_123')
  console.log(user)
}
 
main()

// ===== 服务端 (server.ts) =====
import { initTRPC } from '@trpc/server'
import { createHTTPServer } from '@trpc/server/adapters/standalone'
import { z } from 'zod'
 
const t = initTRPC.create()
 
const appRouter = t.router({
  // 健康检查
  health: t.procedure.query(() => ({ status: 'ok', timestamp: Date.now() })),
 
  // 带输入验证的查询
  getUser: t.procedure
    .input(z.object({ id: z.string().uuid() }))
    .query(async ({ input }) => {
      // 模拟数据库查询
      return {
        id: input.id,
        name: 'Alice',
        email: '[email protected]',
        createdAt: new Date(),
      }
    }),
 
  // 带输入验证的 mutation
  createUser: t.procedure
    .input(z.object({
      name: z.string().min(2).max(50),
      email: z.string().email(),
    }))
    .mutation(async ({ input }) => {
      // 模拟创建用户
      return {
        id: crypto.randomUUID(),
        ...input,
        createdAt: new Date(),
      }
    }),
})
 
export type AppRouter = typeof appRouter
 
createHTTPServer({ router: appRouter }).listen(4000)

// ===== 客户端 (client.ts) =====
import { createTRPCClient, httpBatchLink } from '@trpc/client'
import type { AppRouter } from './server'
 
const client = createTRPCClient<AppRouter>({
  links: [httpBatchLink({ url: 'http://localhost:4000' })],
})
 
async function main() {
  // ✅ 类型安全：输入参数自动推断为 { id: string }
  const user = await client.getUser.query({ id: '550e8400-e29b-41d4-a716-446655440000' })
  console.log(user.name) // TypeScript 知道这是 string
 
  // ❌ 编译时错误：缺少 email 字段
  // const newUser = await client.createUser.mutate({ name: 'Bob' })
 
  // ✅ 正确调用
  const newUser = await client.createUser.mutate({
    name: 'Bob',
    email: '[email protected]',
  })
  console.log(newUser.id) // TypeScript 知道这是 string
 
  // ✅ 返回值类型完全推断
  const health = await client.health.query()
  console.log(health.status) // "ok"
}
 
main()

const appRouter = t.router({
  // 顶层 procedure
  health: t.procedure.query(() => 'ok'),
 
  // 嵌套 router
  post: t.router({
    list: t.procedure.query(() => []),
    byId: t.procedure.input(z.string()).query(({ input }) => input),
  }),
 
  // v11 新增：简写 router（shorthand router）
  comment: {
    list: t.procedure.query(() => []),
    create: t.procedure.mutation(() => null),
  },
})

const procedure = t.procedure
  .input(z.object({ id: z.string() }))   // 输入验证
  .use(authMiddleware)                      // 中间件
  .use(logMiddleware)                       // 链式中间件
  .query(async ({ input, ctx }) => {        // 处理器
    return await ctx.db.user.findUnique({ where: { id: input.id } })
  })

// 服务端
const getUser = t.procedure
  .input(z.object({
    id: z.string(),
    includePosts: z.boolean().optional(),
  }))
  .output(z.object({
    id: z.string(),
    name: z.string(),
    posts: z.array(z.object({ id: z.string(), title: z.string() })).optional(),
  }))
  .query(async ({ input }) => { /* ... */ })
 
// 客户端 —— 所有类型自动推断
const result = await trpc.getUser.query({
  id: '123',           // ✅ TypeScript 提示需要 string
  includePosts: true,   // ✅ TypeScript 提示 boolean | undefined
})
result.name   // ✅ string
result.posts  // ✅ { id: string, title: string }[] | undefined

// 定义 context 类型
export const createTRPCContext = async (opts: { req: Request }) => {
  const session = await getSession(opts.req)
  return {
    session,
    db: prisma,
  }
}
 
// 在中间件中使用 context
const isAuthed = t.middleware(({ ctx, next }) => {
  if (!ctx.session?.user) {
    throw new TRPCError({ code: 'UNAUTHORIZED' })
  }
  return next({
    ctx: {
      session: ctx.session, // 收窄类型：session 此时一定存在
    },
  })
})
 
// 创建需要认证的 procedure
const protectedProcedure = t.procedure.use(isAuthed)

const loggingMiddleware = t.middleware(async ({ ctx, next, rawInput }) => {
  const start = Date.now()
 
  // 执行下一个中间件或 handler
  const result = await next()
 
  const duration = Date.now() - start
  console.log(`[${result.ok ? 'OK' : 'ERR'}] ${duration}ms`)
 
  return result
})

const client = createTRPCClient<AppRouter>({
  links: [
    loggerLink(),
    httpBatchStreamLink({  // v11 推荐的流式批量 link
      url: '/api/trpc',
    }),
  ],
})

import superjson from 'superjson'
 
const t = initTRPC.create({
  transformer: superjson,
})
 
// 现在 Date 等类型可以正确序列化
const getPost = t.procedure.query(() => ({
  id: '1',
  createdAt: new Date(), // 客户端收到的是 Date 对象，不是字符串
}))

// 服务端组件 —— 直接 prefetch
export default async function Page() {
  void trpc.posts.list.prefetch()  // 在服务端立即发起请求
  return (
    <HydrateClient>
      <PostList />  {/* 客户端组件通过 React Query 缓存获取数据 */}
    </HydrateClient>
  )
}

const generateContent = t.procedure
  .input(z.object({ prompt: z.string() }))
  .query(async function* ({ input }) {
    for await (const chunk of generateAIContent(input.prompt)) {
      yield chunk  // 客户端实时接收每个数据块
    }
  })

const onNotification = t.procedure.subscription(async function* ({ ctx }) {
  for await (const event of ctx.notificationStream()) {
    yield event  // 通过 SSE 推送到客户端
  }
})

const uploadFile = t.procedure
  .input(z.instanceof(FormData))
  .mutation(async ({ input }) => {
    const file = input.get('file') as File
    // 处理文件上传
    return { name: file.name, size: file.size }
  })

// 以下 3 个查询会被自动合并为 1 次 HTTP 请求
const [user, posts, comments] = await Promise.all([
  trpc.user.getById.query('123'),
  trpc.post.list.query(),
  trpc.comment.list.query(),
])

function UserList() {
  const usersQuery = trpc.user.list.useQuery()
  const createUserMutation = trpc.user.create.useMutation({
    onSuccess: () => {
      utils.user.list.invalidate()  // 自动刷新用户列表
    },
  })
 
  if (usersQuery.isLoading) return <Spinner />
  return <List users={usersQuery.data} />
}

// 简写 router
const appRouter = t.router({
  post: {
    list: t.procedure.query(() => []),
    byId: t.procedure.input(z.string()).query(({ input }) => input),
  },
})
 
// 懒加载 router（按需加载，减少冷启动开销）
const appRouter = t.router({
  admin: t.router.lazyLoad(() => import('./admin/router')),
})

# 使用 create-t3-app 快速开始（推荐）
npx create-t3-app@latest
 
# 或手动配置
mkdir my-trpc-app && cd my-trpc-app
pnpm init
pnpm add @trpc/server @trpc/client zod
pnpm add -D typescript @types/node tsx

# 使用 tsx 运行开发服务器（支持热重载）
tsx watch server/index.ts
 
# 或使用 ts-node-dev
ts-node-dev --respawn --transpile-only server/index.ts

# 全量类型检查
tsc --noEmit
 
# 或使用项目配置的 verify 命令
pnpm typecheck

import { test, expect } from 'vitest'
import { createCallerFactory } from './trpc'
import { appRouter } from './routers/_app'
 
const createCaller = createCallerFactory(appRouter)
 
test('getUser returns user data', async () => {
  const caller = createCaller({
    session: { user: { id: 'test-user' } },
    db: mockDb,
  })
 
  const user = await caller.getUser({ id: 'test-user' })
  expect(user).toBeDefined()
  expect(user.name).toBe('Alice')
})

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm typecheck      # 类型检查——tRPC 端到端类型安全在这里验证
      - run: pnpm lint
      - run: pnpm test
      - run: pnpm build

// 自动批处理——5 个查询 → 1 次 HTTP 请求
const [a, b, c, d, e] = await Promise.all([
  trpc.query1.query(),
  trpc.query2.query(),
  trpc.query3.query(),
  trpc.query4.query(),
  trpc.query5.query(),
])

// 流式查询——客户端实时处理
for await (const chunk of trpc.generate.query({ prompt: '...' })) {
  processChunk(chunk)  // 无需等待全部数据
}

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000,     // 5 分钟内数据视为新鲜
      gcTime: 30 * 60 * 1000,       // 30 分钟后回收缓存
      refetchOnWindowFocus: false,   // 窗口聚焦时不自动重新获取
    },
  },
})

// 在 layout 中 prefetch，子组件直接使用缓存
export default async function Layout({ children }) {
  void trpc.user.me.prefetch()  // 立即发起请求
  return children
}

// ✅ 所有输入都有严格的 schema 验证
const safeProcedure = t.procedure
  .input(z.object({
    name: z.string().min(1).max(100),
    age: z.number().int().min(0).max(200),
    email: z.string().email(),
  }))
  .query(({ input }) => { /* input 类型已经过验证 */ })

// 认证中间件
const isAuthenticated = t.middleware(({ ctx, next }) => {
  if (!ctx.session?.user) {
    throw new TRPCError({ code: 'UNAUTHORIZED', message: '请先登录' })
  }
  return next({ ctx: { ...ctx, session: ctx.session } })
})
 
// 角色授权中间件
const hasRole = (role: string) =>
  t.middleware(({ ctx, next }) => {
    if (ctx.session.user.role !== role) {
      throw new TRPCError({ code: 'FORBIDDEN', message: '权限不足' })
    }
    return next()
  })
 
// 组合使用
const adminProcedure = t.procedure.use(isAuthenticated).use(hasRole('admin'))

const rateLimitMiddleware = t.middleware(async ({ ctx, next }) => {
  const key = `rate-limit:${ctx.session?.user?.id ?? ctx.ip}`
  const count = await redis.incr(key)
  if (count === 1) await redis.expire(key, 60)
  if (count > 100) {
    throw new TRPCError({ code: 'TOO_MANY_REQUESTS', message: '请求过于频繁' })
  }
  return next()
})

// 生产环境中捕获内部错误，返回通用错误信息
const t = initTRPC.create({
  errorFormatter({ error, shape }) {
    if (error.code === 'INTERNAL_SERVER_ERROR') {
      return {
        ...shape,
        message: '服务器内部错误',  // 不暴露内部细节
      }
    }
    return shape
  },
})

import superjson from 'superjson'
 
// 服务端 link 配置
const t = initTRPC.create()
 
// 客户端 link 配置
httpBatchLink({
  url: '/api/trpc',
  transformer: superjson,  // v11 在 link 中配置
})

// routers/_app.ts
export const appRouter = t.router({
  auth: t.router.lazyLoad(() => import('./auth')),
  user: t.router.lazyLoad(() => import('./user')),
  post: t.router.lazyLoad(() => import('./post')),
  admin: t.router.lazyLoad(() => import('./admin')),
})

const userSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
})
 
const getUser = t.procedure
  .input(z.string())
  .output(userSchema)  // 运行时验证输出
  .query(async ({ input }) => {
    const user = await db.user.findUnique({ where: { id: input } })
    if (!user) throw new TRPCError({ code: 'NOT_FOUND' })
    return userSchema.parse(user)  // 确保输出符合 schema
  })

// 全局默认配置
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 30_000,         // 30 秒内视为新鲜
      refetchOnWindowFocus: true, // 窗口聚焦时重新获取
      retry: 1,                   // 失败重试 1 次
    },
    mutations: {
      retry: false,               // mutation 不重试
    },
  },
})

// 定义业务错误类型
class NotFoundError extends TRPCError {
  constructor(entity: string, id: string) {
    super({
      code: 'NOT_FOUND',
      message: `${entity} ${id} 不存在`,
    })
  }
}
 
class ValidationError extends TRPCError {
  constructor(message: string) {
    super({
      code: 'BAD_REQUEST',
      message,
    })
  }
}
 
// 使用
const getUser = t.procedure
  .input(z.string())
  .query(async ({ input }) => {
    const user = await db.user.findUnique({ where: { id: input } })
    if (!user) throw new NotFoundError('用户', input)
    return user
  })

// ❌ 错误：服务端用了 superjson，客户端忘了
const t = initTRPC.create({ transformer: superjson })
// 客户端没有配置 transformer → Date 会变成字符串
 
// ✅ 正确：v11 中在 link 中配置
httpBatchLink({ url: '/api/trpc', transformer: superjson })

// ✅ 推荐：延迟初始化
export const createContext = async () => {
  const db = prisma  // Prisma Client 应该复用，不要每次新建
  return { db }
}

// ❌ 错误：直接调用，不走缓存
const data = await trpc.getUser({ id: '123' })
 
// ✅ 正确：prefetch + HydrateClient
void trpc.getUser.prefetch({ id: '123' })
return (
  <HydrateClient>
    <UserClientComponent id="123" />  {/* 客户端通过 React Query 缓存获取 */}
  </HydrateClient>
)

const handler = (req: Request) =>
  fetchRequestHandler({
    endpoint: '/api/trpc',
    req,
    router: appRouter,
    createContext,
    responseMeta({ ctx, errors }) {
      return {
        headers: {
          'Access-Control-Allow-Origin': '*',  // 生产环境应指定具体域名
          'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
          'Access-Control-Allow-Headers': 'Content-Type',
        },
      }
    },
  })