T3技术栈实战：用tRPC+Prisma打造代码片段管理工具-北京尧图网络

如果你常刷全栈圈对“T3”这个词应该不陌生——Next.js、TypeScript、Tailwind 和 tRPC 的组合拳。t3code 这个项目名字里就写了一半答案T3 技术栈 code 管理。简单说这是一个用 T3 全家桶搭建的个人代码片段管理工具用来解决我日常开发里最烦的一个问题代码片段散落各处真到要用的时候找不到。这个项目麻雀虽小但五脏俱全GitHub 登录、数据库建模、服务端接口、前端页面、部署上线全走了一遍。它是全栈新手快速理解 T3 技术栈如何端到端打通的最佳示例也是老手用于沉淀内部小工具的高效模板。下面我把整个从零到跑通的过程包括选型逻辑、目录结构、核心实现和踩坑记录都拆开讲。1. t3code 是个什么项目需求与定位1.1 一个非常具体的痛点代码片段去哪了很多项目做不起来不是技术不行是需求太虚。t3code 这个项目恰恰相反需求是我自己实实在在踩过的坑。我的日常开发横跨好几个仓库再加上临时排查问题时写的调试脚本代码片段分散得很厉害。浏览器收藏夹存一段、公司 Wiki 贴一段、本地笔记塞一段真要找的时候一片混乱。比如某种特定格式的正则、一段处理时区的 SQL、一份 Docker Compose 模板三个月后回头找至少要翻十来分钟历史记录。这个频率一高人就烦了。所以 t3code 的目标很朴素一个自己能随时访问的代码片段仓库。支持登录、增删改查、按语言和标题过滤最好还能用 Markdown 加一些使用说明。这个需求用商业产品也能解决但我有自己的坚持——不想把内部代码片段放到第三方平台也不希望数据被格式化和广告绑架。自己做一个自托管的版本一劳永逸。1.2 为什么要做成一个“全栈应用”而不是脚本第一反应可能是存个代码片段而已写个 Node 脚本加 JSON 文件不就行了我一开始也这么想但很快就放弃了。因为代码片段不是写完就完的静态数据它有高频的检索、更新、删除需求还要区分私有和公共展示。纯文件方案在单机条件下可以一旦想多设备访问、想支持多人协作或者团队内部共享就得补大量的同步逻辑最终还是要被迫写一套 Web 应用。选择全栈应用还意味着可以顺便验证一个我一直想确认的技术问题T3 这套组合到底能不能在一个周末内支撑起完整的 CRUD 认证部署闭环。事实证明确实能而且过程比传统前后端分离方案清爽太多。1.3 项目边界哪些功能做了哪些故意不做做一个项目最怕的就是无限加需求。t3code 第一版的功能列表我很克制GitHub OAuth 登录免密进入代码片段的创建、编辑、删除、列表查看按编程语言和标题关键字过滤Markdown 格式的备注说明支持预览私有片段只对自己可见故意没做的也列一下团队协作、公共广场、富文本编辑器、AI 代码总结。这些听起来很香但每一项都会极大拉长工期。个人工具的核心价值是聚焦先把主链路跑通后续真要扩展再往上叠。2. 技术选型为什么是这四个组件而不是其他组合2.1 核心矛盾API 层的重复代码到底怎么消掉最开始我也考虑过传统方案Next.js 只当展示层后端单独起一个 Express 或 Fastify 服务两边通过 REST 接口通信。这种模式成熟但有个绕不开的问题——类型定义要维护两份。前端一份后端一份API 文档又是一份改一个字段要同步改三处漏一处就是运行时才暴露的 bug。tRPC 解决的就是这个核心矛盾让前端直接调用后端函数类型从服务端自动推导到客户端。后端 Router 里定义好的create、list、delete前端引进来就是类型完整的方法。接口层的事实来源只有一个Router 定义本身。我当时做过一个直观对比这也是我最终确定技术路线的参考依据维度传统 REST 手写类型tRPC类型共享靠手写 d.ts 或 codegen服务端自动推导接口文档额外维护 OpenAPIRouter 即文档前端调用体验fetch 封装手动处理错误头像调用本地异步函数内部小工具效率高但繁琐非常高如果你做的是开放平台、需要大量外部客户端接入的 B 端 APIREST OpenAPI 依然是更稳妥的选择。但 t3code 定位是内部工具tRPC 的优势完美贴合。2.2 数据库层Prisma 让表结构成为编译期事实数据库选型没有悬念就是 Prisma。真正让我下决心的不是 ORM 本身的便利而是它把数据库结构变成了“单一事实来源”。在 Prisma 里prisma/schema.prisma一个文件描述了所有表结构、字段类型、关联关系。改了 schema 之后执行npx prisma migrate dev它会生成对应的 SQL 迁移文件同时重新生成类型安全的客户端。写代码的时候ctx.db.snippet.findMany()的返回值类型是完全可推导的字段写错了 IDE 直接标红根本轮不到运行时再炸。这一点对个人项目的意义很大——没有专职 DBA也没有专门的联调环境越早暴露错误越好。编译期能发现的问题绝不让它拖到部署后。2.3 认证选型为什么直接用 NextAuth 而不是自己写 Session很多教程喜欢教你手写 JWT、Redis Session看起来高深实际项目里纯属自找麻烦。t3code 选择 NextAuth.js核心原因是它把这套链路整个包好了OAuth 登录、Session 管理、CSRF 防护、Callback 转发都是开箱即用的。GitHub OAuth 是我们最顺手的登录方式。程序员群体基本人手一个 GitHub 账号授权登录点一下就结束用户价值很高也省去了邮箱注册、密码找回这一整套复杂度。2.4 样式与客户端状态能省则省样式上 Tailwind CSS 是 T3 标准配置原因很实际——内部工具的页面通常不追求视觉效果但要求快速迭代。Tailwind 的原子类方式让我不用在 CSS 文件里反复切来切去直接改 className 就能调样式。客户端状态管理没有额外引入 Redux 或 Zustand。tRPC 底层自带 TanStack Query服务端数据天然有缓存、失效、重试机制。局部 UI 状态比如弹窗开关直接 useState 就够了。少一个依赖就少一个心智负担这是个人项目的生存法则。3. 从 create-t3-app 到能跑的骨架初始化全过程3.1 初始化命令与交互选项T3 技术栈的官方脚手架是 create-t3-app它会自动生成一个包含所有核心约定的基础工程。初始化命令很简单npm create t3-applatest t3code cd t3code npm install执行时它会用交互式问答确认要启用哪些能力。我建议你这样选App Router选 Yes这是 Next.js 目前的主推方向TypeScript选 Yes不用犹豫Tailwind CSS选 Yes配合样式处理tRPC选 Yes本项目的核心Prisma选 Yes数据库层需要它NextAuth.js选 Yes登录认证离不开它ESLint选 Yes保持代码规范性Prettier 项看个人偏好我一般也会带上省得格式化问题引发无意义的代码争执。脚手架生成的项目不是一个空 Hello World而是一个已经跑通 tRPC 回合、NextAuth 回调和数据库连接的完整骨架。这对新手极其友好你有一条已知可用的基线再往上叠业务逻辑出问题时知道是自己引入的不是环境问题。3.2 生成后的目录结构逐层拆解初始化完成后目录结构大致长这样。我挑几个关键路径解释理解了它们后面写业务就很顺t3code/ ├─ prisma/ │ └─ schema.prisma # 所有数据模型和数据库连接配置 ├─ src/ │ ├─ app/ │ │ ├─ api/ │ │ │ ├─ trpc/[trpc]/route.ts # tRPC HTTP 入口 │ │ │ └─ auth/[...nextauth]/route.ts # NextAuth 路由入口 │ │ ├─ _trpc/ │ │ │ ├─ client.ts # 前端 tRPC 客户端实例 │ │ │ └─ Provider.tsx # SessionProvider tRPCProvider 包裹 │ │ └─ layout.tsx │ ├─ server/ │ │ ├─ api/ │ │ │ ├─ routers/ # 业务 Router按模块拆分 │ │ │ ├─ root.ts # 聚合所有业务 Router │ │ │ └─ trpc.ts # tRPC 服务端上下文和初始化逻辑 │ │ ├─ auth.ts # NextAuth 配置providers、callbacks │ │ └─ db.ts # Prisma Client 单例 │ ├─ trpc/ │ │ ├─ server.ts # 服务端 tRPC 封装供 RSC 调用 │ │ └─ react.tsx # 前端 React 封装供组件调用 │ └─ env.js # 环境变量校验 ├─ .env # 本地环境变量 └─ next.config.js这个结构最大的特点是职责分明server目录里全是后端逻辑app目录里全是界面和路由trpc目录是连接前后端的类型安全通道。新写一个功能模块时你只需要新增一个 router 文件一个页面组件其他都是约定俗成的路径。3.3 环境变量与校验逻辑环境变量这个环节经常被轻视直到部署后才开始折磨人。create-t3-app 默认通过t3-oss/env-nextjs做运行时校验配置写得很直观import { createEnv } from t3-oss/env-nextjs; import { z } from zod; export const env createEnv({ server: { DATABASE_URL: z.string().url(), NEXTAUTH_SECRET: z.string().min(1), NEXTAUTH_URL: z.string().url().optional(), GITHUB_CLIENT_ID: z.string().min(1), GITHUB_CLIENT_SECRET: z.string().min(1), }, runtimeEnv: { DATABASE_URL: process.env.DATABASE_URL, NEXTAUTH_SECRET: process.env.NEXTAUTH_SECRET, NEXTAUTH_URL: process.env.NEXTAUTH_URL, GITHUB_CLIENT_ID: process.env.GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET: process.env.GITHUB_CLIENT_SECRET, }, });它的好处很直接环境变量缺失时应用启动阶段就报错而不是等到某个 API 被调用时才报一个莫名其妙的连接错误。我第一次配置时忘记填NEXTAUTH_SECRET页面一打开立刻被拦截省了很多排查时间。本地开发时把DATABASE_URL指向 SQLite 文件即可零成本起跑DATABASE_URLfile:./db.sqlite4. 核心功能链路从 Prisma 表结构到 tRPC Router 再到页面4.1 数据模型设计先定表结构后写业务t3code 的数据模型很直接。除了 NextAuth 需要的User、Account、Session这些模型之外业务核心是Snippet。我把它定义成下面这样model Snippet { id String id default(cuid()) title String content String language String default(plaintext) isPublic Boolean default(false) userId String user User relation(fields: [userId], references: [id], onDelete: Cascade) createdAt DateTime default(now()) updatedAt DateTime updatedAt index([userId]) index([language]) }几个细节说明一下。主键用的是cuid()而不是自增数字因为自增 ID 会暴露用户量和插入顺序cuid 没有这个顾虑而且分布式环境下不需要中心协调。index([userId])是给外键加索引否则随着 snippet 数量增长按用户查询会逐渐变慢。onDelete: Cascade保证用户注销时关联数据一并清理。定义好之后执行迁移命令生成本地数据库npx prisma migrate dev --name init-snippet这条命令会创建一个迁移记录同时重新生成 Prisma Client。之后每次改 schema流程都是先改文件再执行迁移保持表结构和代码模型一致。4.2 服务端tRPC Router 的编写思路有了数据模型接下来就是服务端接口层。在routers/snippet.ts里写业务 Router核心代码大概是这样的import { z } from zod; import { createTRPCRouter, protectedProcedure } from ~/server/api/trpc; export const snippetRouter createTRPCRouter({ list: protectedProcedure .input( z .object({ language: z.string().optional(), keyword: z.string().optional(), }) .optional() ) .query(async ({ ctx, input }) { return ctx.db.snippet.findMany({ where: { userId: ctx.session.user.id, ...(input?.language ? { language: input.language } : {}), ...(input?.keyword ? { title: { contains: input.keyword } } : {}), }, orderBy: { updatedAt: desc }, }); }), create: protectedProcedure .input( z.object({ title: z.string().min(1).max(100), content: z.string().min(1), language: z.string().default(plaintext), isPublic: z.boolean().default(false), }) ) .mutation(async ({ ctx, input }) { return ctx.db.snippet.create({ data: { ...input, userId: ctx.session.user.id, }, }); }), delete: protectedProcedure .input(z.object({ id: z.string() })) .mutation(async ({ ctx, input }) { await ctx.db.snippet.deleteMany({ where: { id: input.id, userId: ctx.session.user.id, }, }); return { success: true }; }), });注意三个点。第一每个 Procedure 都用了protectedProcedure而不是publicProcedure这意味着未登录用户会被直接拒绝。第二输入参数全部用 zod 校验前端传的字段在服务端会再次验证不依赖前端的自觉。第三delete操作我刻意用了deleteMany加userId条件防止越权删掉别人的 snippet——这类安全问题在个人项目里也很重要养好习惯成本很低。写完 Router 之后还要在root.ts里注册一下import { createTRPCRouter } from ~/server/api/trpc; import { snippetRouter } from ~/server/api/routers/snippet; export const appRouter createTRPCRouter({ snippet: snippetRouter, }); export type AppRouter typeof appRouter;AppRouter这个类型是前后端共享的关键前端所有类型推导都来源于它。4.3 前端页面类型贯通后的调用体验前端组件里tRPC 的调用体验接近于“直接的本地调用”。因为AppRouter类型已经推到了前端api.snippet.list.useQuery()的返回值、参数、错误类型全部自动推导不需要手写任何接口类型。use client; import { api } from ~/trpc/react; export function SnippetList() { const { data, isLoading } api.snippet.list.useQuery(); if (isLoading) return div加载中.../div; return ( div classNamespace-y-4 {data?.map((snippet) ( div key{snippet.id} classNamerounded border p-4 div classNametext-lg font-semibold{snippet.title}/div pre classNamemt-2 overflow-x-auto text-sm code{snippet.content}/code /pre /div ))} /div ); }新增或删除数据后需要让列表重新拉取。tRPC 底层是 TanStack Query所以缓存失效也走它的标准模式const utils api.useUtils(); const createMutation api.snippet.create.useMutation({ onSuccess: () { utils.snippet.list.invalidate(); }, });invalidate会在操作成功后让相关 query 的缓存变 stale下次渲染自动重新请求。整个过程不需要手动管理 loading 状态、不需要手写请求失败处理代码量比传统 fetch 方案少了一半不止。4.4 认证保护链路从 OAuth 到 Session 再到 Router前面用了protectedProcedure很多人可能好奇它是怎么工作的。T3 默认模板给了标准实现export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { session: { ...ctx.session, user: ctx.session.user }, }, }); });这里的关键在于服务端上下文。每次 tRPC 请求进来都会先调用createTRPCContext它读取当前的 Session 信息挂到上下文里后续所有 Procedure 可以通过ctx.session拿到用户身份。换句话说认证不是每个接口自己去判断的而是收敛到中间件层。新写一个接口时只要选对 Procedure 类型认证规则就自动生效。这个抽象非常舒服写业务的人不需要关心“这个接口要不要验证登录”这种重复问题。5. 开发踩坑与调试实录5.1 改了 Router 类型前端死活不更新这是 tRPC 开发里最容易撞上的坑。你明明在服务端 Router 里加了一个新查询前端api.snippet.xxx却提示不存在或者类型还是旧的。原因是 Next.js 的 dev server 对.next目录里的类型缓存处理没有 tRPC 敏感。改了root.ts或 router 文件后tRPC 的类型信息要经过 TS 编译再同步到前端这一步经常会被增量编译缓存住。解法很简单按顺序试rm -rf .next npm run dev清掉.next缓存后重新启动类型一定是最新的。后来我养成习惯改完 router 结构先停 dev server 再重启省得被怪异报错浪费十分钟。你要是遇到“代码看起来没问题但类型就是不对”优先想到这个坑。5.2 Prisma 客户端多实例警报开发模式下Next.js 的热更新会反复加载模块。如果 Prisma Client 在每次加载时都new一个实例跑一段时间后终端会飘出经典报错Already 10 Prisma Clients are actively running原因就是模块热更新生成了太多 PrismaClient 实例而每个实例都占着数据库连接。解决方式是全局单例模式create-t3-app 默认生成的server/db.ts也是这么处理的import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma: PrismaClient | undefined; }; export const db globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV ! production) { globalForPrisma.prisma db; }这段代码利用globalThis在模块热更新时保留同一个实例生产环境每次冷启动也只建一次。个人项目可能不常遇到这个报错但团队里多人开发时就很容易触发先记住这个写法。5.3 NextAuth 回调地址与 CSRF 的隐藏要求集成 GitHub OAuth 时最磨人的不是代码而是配置。你需要在 GitHub 的 OAuth Apps 设置里把 Authorization callback URL 精确填成http://localhost:3000/api/auth/callback/github漏掉/api/auth/callback/github这一截或者域名用了127.0.0.1而不是localhost登录时就会在 GitHub 那一跳之后回不来。还有一个容易被忽略的 NEXTAUTH 环境变量。在本地开发时NEXTAUTH_URL最好显式设置为http://localhost:3000。有些教程说可以不设但我实测下来不设它会在某些版本的 NextAuth 下出现登录回调 URL 拼接错误报一个很晦涩的 CSRF 相关异常。填上之后世界安静了。另外新版 NextAuth 在 App Router 下必须提供app/api/auth/[...nextauth]/route.ts不能再走旧的 pages API 方式import NextAuth from next-auth; import { authOptions } from ~/server/auth; const handler NextAuth(authOptions); export { handler as GET, handler as POST };5.4 从 SQLite 到 PostgreSQL部署前的必修课本地用 SQLite 开发非常舒服零配置文件即数据库。但上线部署到 Vercel 时SQLite 就成了烫手山芋——serverless 函数是临时环境文件系统不可持久化写在磁盘上的db.sqlite随时可能被回收。所以在部署前我把数据库换成了 Neon 的 PostgreSQL Serverless 服务。连接串类似这样DATABASE_URLpostgresql://user:passwordep-xxx.us-east-2.aws.neon.tech/t3code?sslmoderequire切库的步骤并不复杂核心是改一行schema.prismadatasource db { provider postgresql url env(DATABASE_URL) }然后重新生成客户端npx prisma generate npx prisma migrate deployVercel 部署时还有两个小细节值得注意。第一在项目 Settings 的 Root Directory 或者 Build Command 里确保安装依赖后执行了prisma generate否则 Serverless 环境里找不到 Prisma Client。通常的做法是在 package.json 里加一个postinstall{ scripts: { postinstall: prisma generate } }第二所有环境变量DATABASE_URL、NEXTAUTH_SECRET、GITHUB_CLIENT_ID等都要在 Vercel 的项目设置里配置本地.env不会自动同步到云端这是新手最容易漏掉的一环。5.5 调试效率善用 tRPC 的错误格式化和日志tRPC 默认的错误信息已经够用但实际开发时我更推荐在服务端上下文里加上一个自定义的errorFormatter把 zod 的校验错误结构化输出。这样前端拿到的不再是一句笼统的 “Internal Server Error”而是精确到哪个字段格式不对。export const t initTRPC.contexttypeof createTRPCContext().create({ transformer: SuperJSON, errorFormatter({ shape, error }) { return { ...shape, data: { ...shape.data, zodError: error.cause instanceof ZodError ? error.cause.flatten() : null, }, }; }, });这个格式化的价值在前后端联调时体现得最明显。前端传错参数后端返回的错误信息直接告诉你title字段哪一项不满足min(1)而不是让你对着 500 状态码猜半天。再分享一个调试习惯不要只盯着网络面板看请求结果配合 TanStack Query 的 devtools 面板观察缓存状态更有帮助。tRPC 自带 React Query 能力数据有没有命中缓存、invalidate 是否生效开发者工具里一眼就能看清比盲猜“为什么页面没刷新”高效得多。6. 最后一公里部署上线和持续演进我一直认为一个项目只有真正部署上线、跑在自己随时可访问的域名下才算完成闭环。t3code 的部署流程走的是 Vercel Neon 的组合整个过程大概半小时。部署完成之后我给自己定了一个顺手的使用约定能放进 t3code 的片段绝不留在浏览器收藏夹每条片段尽量附带一段“为什么这样写”的说明而不是只贴代码。这样积累下来的片段半年后翻出来依然能秒懂。做完这个项目之后我最大的体感是全栈 TypeScript 的收益不在于“少写了几个字节”而在于重构时可以非常自信地下手。改了 Prisma 模型TS 会立刻把所有用到旧字段的地方标红改了 tRPC Router 签名前端所有调用点同步报错。这种跨端反馈是单独写前端或单独写后端时完全体会不到的。如果你也想跑一遍这套流程我个人的建议是别找太复杂的业务需求就用一个自己真正需要的内部小工具开刀。从 create-t3-app 初始化到添加第一个数据模型再到部署上线整个过程本身就是最好的全栈实战课。踩过的坑我已经帮你垫平了剩下的就剩动手。最后再分享一个小习惯每次改完 Router 或 Prisma schema我都先看 TS 有没有红色波浪线再看运行时页面按这个顺序排查速度会快很多。

T3技术栈实战：用tRPC+Prisma打造代码片段管理工具

相关推荐

MATLAB 2021a 实现小球弹射强化学习控制

SpringBoot蛋糕店系统：入门级可交付业务闭环实践

SpringBoot 三层架构里 DTO 该放哪一层：从鸿蒙登录接口返回密码说起

更多资讯

RV32I五级流水线处理器设计：数据前推、冒险检测与分支预测实践

本地部署声音克隆+工作流引擎：开源语音工作室实操指南

SpringBoot与小程序开发睡眠健康管理系统实践

智能物流系统：AGV与数字孪生技术驱动制造业转型

IDEA 2025.3新特性解析：AI编程助手与性能优化

Django+MySQL银行信贷系统实战源码：多角色审批与风控流程落地

今日更新

Agent-Reach：打通大模型触达外部系统的最后一公里

深度学习图像隐写分析实战：从CNN原理到毕设源码全解析

AI赋能知识产权供需匹配：专利评估、需求挖掘与多路召回工程实践

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？