★ FEATURED ARTICLE 最近在折腾一个全栈项目的时候顺手把“t3code”这套命名下的代码仓库整理成了一个相对完整的实践样板。我给它定的定位很简单一个基于 T3 Stack 的类型安全全栈示例项目用 Next.js 做应用框架、TypeScript 贯穿前后端、tRPC 打通 API 层、Prisma 管数据库、Tailwind 快速出界面。这份博文会把这套东西从设计思路到落地部署完完整整拆开讲适合打算入坑全栈、又不想在前后端接口对接上反复折腾的开发者参考。很多人第一次看到 T3 Stack 会觉得“这不就是几个流行库堆一起么”。但真正用过之后你会发现它最大的价值不是某个单一技术而是把“类型安全”这件事从前端组件一路延伸到数据库查询把开发者的心智负担降了一个量级。我自己在写 t3code 的过程中最大的感受是大部分时间不是在调接口而是在写业务逻辑本身。这个体验差异只有真正跑起来一个项目才能体会。1. 项目整体设计与思路拆解1.1 为什么叫 t3code它解决什么问题先解释一下名字。“t3code”这个命名思路来源于 T3 StackTypeScript、Tailwind、tRPC 的技术组合但我不想把它做成一个纯“Hello World”演示而是想用一个相对完整的业务场景去验证这套技术栈在实际开发中的表现。最后定的需求很简单一个代码片段管理工具用户可以注册登录把自己的代码片段按语言分类保存下来支持公开/私有切换也支持按关键词搜索。这个需求看起来不起眼但它覆盖了一个全栈应用最常见的几个核心环节用户认证、数据库建模、列表查询、详情展示、增删改操作、权限控制。任何全栈项目基本都逃不开这些事用它来作为 t3code 的载体比做一个抽象的技术演示要更贴近真实开发场景。技术选型上我坚持用 T3 Stack 的默认组合而不是自己乱搭原因是这套组合解决了一个非常实在的问题端到端类型安全。传统的全栈项目通常是前端定义 API 请求、后端写路由和响应模型、数据库单独建表每层之间的类型定义是割裂的改一个字段可能要同步改四五处。t3code 里面从 tRPC 路由的输入输出类型到 Prisma 的数据库模型再到 React 组件的 props整个链路是连通的。改一处类型定义编译器立刻告诉你哪边需要跟着调整这种确定性让项目大了以后依然能保持可维护性。1.2 T3 Stack 的核心组成与协作方式简单过一下 t3code 用到的几个核心成员以及它们各自负责什么Next.js应用框架负责页面路由、服务端渲染、API 能力支撑。我用的是 App Router 模式页面和路由边界更清晰。TypeScript全链路类型系统贯穿前后端。它是 t3code 的“胶水”所有跨端数据都靠类型约束保证一致。tRPC替代传统 REST API 的 RPC 方案。前端调用后端函数就像调用本地函数一样输入输出类型自动推导。PrismaORM 层负责数据库表结构定义、迁移、查询。配合 SQLite 做本地开发非常顺手部署时可以切换 PostgreSQL。Tailwind CSS样式方案。用原子类快速搭建 UI配合深色模式做了个类似代码编辑器的界面风格。NextAuth.js认证方案t3code 里接了 GitHub OAuth也保留了下拉登录方式。这几个库不是各干各的它们的协作方式很有意思。tRPC 的 router 直接挂在 Next.js 的 API 路由上Prisma 的模型类型可以直接被 tRPC 的 procedure 引用前端组件拿到的是强类型的响应数据不需要任何手写的接口定义文件。这也是 t3code 代码量能保持精简的根本原因。1.3 目录结构与横向扩展思路t3code 的仓库结构基本是 create-t3-app 的标准布局但我在组织上做了一点调整方便后续扩展src/ app/ # Next.js App Router 页面 (auth)/ # 登录相关路由 dashboard/ # 代码片段列表 snippets/[id]/ # 详情页 new/ # 新建/编辑页 server/ api/ # tRPC 路由入口 db/ # Prisma client 实例 trpc/ router/ # tRPC query/mutation 定义 caller.ts # 服务端调用入口这个结构的好处是把“服务端逻辑”和“页面展示”分开。如果以后想把 t3code 扩展成多语言版本或者加一个移动端接口只需要在 server 层加新的 router前端页面通过 tRPC hook 按需引用即可不需要重写核心逻辑。项目规模不大但这种分层习惯需要在一开始就养成。2. 核心细节解析与实操要点2.1 数据库模型设计代码片段表与用户表的关系t3code 的数据模型非常精简总共就三张表User、Snippet、Tag。User 表是 NextAuth 自动管理的基础模型Snippet 是核心业务表。我最初设计字段时特意做了取舍不把标签做成关联表而是用逗号分隔的字符串存一个 tags 字段。原因是标签只需要在列表页做展示和筛选性能和灵活性的平衡点在“够用”的位置。Prisma schema 的核心部分长这样model User { id String id default(cuid()) name String? email String? unique emailVerified DateTime? image String? snippets Snippet[] accounts Account[] sessions Session[] } model Snippet { id String id default(cuid()) title String content String db.Text language String default(typescript) isPublic Boolean default(true) tags String default() createdAt DateTime default(now()) updatedAt DateTime updatedAt author User relation(fields: [authorId], references: [id], onDelete: Cascade) authorId String }这里有一个值得注意的细节onDelete: Cascade。用户注销账号时他名下的代码片段会一并删除避免了孤儿数据。但如果你做了“保留匿名作品”之类需求这里应该改成SetNull并让 authorId 可空。我在写 t3code 时一开始没有考虑到这个关联行为后来测试删除用户时发现 Prisma 直接报外键约束错误才意识到关联操作策略必须显式声明。2.2 服务端认证与路由保护机制t3code 的权限控制逻辑很清晰查询类操作分“公开数据”和“私有数据”修改类操作必须校验当前登录用户是不是资源所有者。这套逻辑在传统 REST API 里通常要靠中间件 路由判断来做写起来不难但容易漏。tRPC 里直接用 middleware 处理会优雅很多。核心的 protected procedure 定义如下const isAuthed t.middleware(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { userId: ctx.session.user.id }, }); }); export const protectedProcedure t.procedure.use(isAuthed);之后所有需要登录的操作只需要把publicProcedure换成protectedProcedure入参和返回值类型照常推导不需要写第二遍鉴权逻辑。我在实现“编辑代码片段”功能时就是靠这个中间件 在业务代码里比较snippet.authorId ctx.userId两道防线来保证安全的。2.3 tRPC 输入校验策略与错误处理tRPC 的一个容易被低估的功能是输入校验。它原生支持 zod schema而 zod 的类型推断结果可以直接作为 TypeScript 类型使用。这意味着你在写输入校验时其实同时在做类型定义不需要单独维护一份 DTO 类。看一下 t3code 里新建代码片段的 mutation 实现import { z } from zod; const snippetInput z.object({ title: z.string().min(1, 标题不能为空).max(100), content: z.string().min(1, 代码内容不能为空), language: z.string().min(1), tags: z.string().default(), isPublic: z.boolean().default(true), }); export const createSnippet protectedProcedure .input(snippetInput) .mutation(async ({ ctx, input }) { return ctx.db.snippet.create({ data: { ...input, authorId: ctx.userId, }, }); });前端 useForm 提交时直接复用同一个 zod schema 做客户端校验前端和后端用的是同一套规则不存在“前端校验通过但后端报错”的落差。我这里特意给 title 和 content 加了最小长度限制避免有人往数据库塞超长文本导致页面渲染卡顿。实际项目里你可能还需要防 XSS 处理但作为示例项目目前只在前端展示时对内容做了基本的转义展示。2.4 代码高亮与编辑器集成的实现方案既然项目定位是代码片段管理工具代码展示体验就不能忽视。t3code 没有自研编辑器而是直接集成了 CodeMirror 6。选择它的主要原因是体积可控、React 集成好、支持超过 150 种语言的高亮而且语法高亮是流式的长代码性能不会崩。在“新建/编辑”页面CodeMirror 作为受控组件接入use client; import CodeMirror from uiw/react-codemirror; import { javascript } from codemirror/lang-javascript; import { python } from codemirror/lang-python; import { cpp } from codemirror/lang-cpp; function SnippetEditor({ value, onChange, language }) { const extensions getLanguageExtension(language); return ( CodeMirror value{value} height400px extensions{[extensions]} onChange{onChange} themedark / ); }详情展示页则用的是另一种方案——react-syntax-highlighter。这个库体积比 CodeMirror 大不少但服务端渲染支持更好适合放在 SSR 页面直接输出带Prism风格的高亮 HTML首屏体验更快。一个项目内同时用两套高亮方案听起来有点“重复造轮子”但它们的适用场景确实不同编辑交互选 CodeMirror、只读展示选 Prism 风格的静态高亮是我实测后觉得性能体验最均衡的组合。3. 实操过程与核心环节实现3.1 从 create-t3-app 到项目初始化完整流程t3code 从头初始化其实并不复杂因为 create-t3-app 已经把脚手架的大部分工作做完了。我实际操作的步骤是npx create-t3-applatest t3code进入交互式提示后我按以下选项选择TypeScript 选YesTailwind CSS 选YestRPC 选YesPrisma 选YesNextAuth 选YesESLint / Prettier 都选Yes包管理器选择pnpm这里有一个建议如果项目要部署到 Node 环境且对外提供接口记得在.env里把DATABASE_URL和NEXTAUTH_SECRET设置好。之前看到不少人初始化完直接启动然后卡在数据库迁移和 session 校验上其实都是环境变量没配齐。t3code 的.env我是在初始化之后第一时间补齐的# t3code/.env DATABASE_URLfile:./db.sqlite NEXTAUTH_SECRET随便生成一段足够长的随机字符串 NEXTAUTH_URLhttp://localhost:3000 GITHUB_ID你的GitHub OAuth App ID GITHUB_SECRET你的GitHub OAuth App SecretNEXTAUTH_SECRET可以用openssl rand -base64 32生成。千万别用弱密钥否则线上环境会直接报 session 错误。GitHub OAuth 需要在 GitHub Developer Settings 里新建一个 OAuth App回调地址填http://localhost:3000/api/auth/callback/github。初始化完成后先跑一遍数据库迁移cd t3code npx prisma migrate dev --name init npx prisma db push npx prisma studio # 可选可视化查看数据表然后pnpm dev启动开发环境默认地址是http://localhost:3000。3.2 配置 Prisma 数据源与 NextAuth 联动的实际选择t3code 在数据源上做了一个小改动本地开发用 SQLite生产环境用 PostgreSQL。这样做的理由很实际——SQLite 零配置、随项目走适合快速跑通业务逻辑PostgreSQL 部署在云数据库上适合真正的线上流量。Prisma 对两者的切换只是改一行provider和DATABASE_URL的问题迁移文件可以共用绝大部分。如果你也想这么做注意两点一是 SQLite 的DATABASE_URL是文件路径PostgreSQL 的 URL 格式是postgresql://user:passwordhost:port/dbname两者不能混用二是 Prisma 的 migration 里如果你的 schema 模型用了 SQLite 不支持的类型或函数迁移文件可能没法直接通用。我在 t3code 里特意避开了 SQLite 不支持的功能保证切换数据源时迁移能一次通过。NextAuth 的 Provider 配置放在src/server/auth.ts。为了支持本地没有 GitHub 账号的场景我额外加了 Credentials Provider用邮箱密码登录。当然这个方案的安全级别不如 OAuth所以我在代码里加了注释提醒自己——t3code 仅为技术演示生产环境建议使用 OAuth 或更成熟的认证方案。3.3 核心页面与前端组件的调用链路t3code 的前端组件大量使用 tRPC 的 React Query 封装。列表页的写法基本是“读接口 状态展示”两层use client; import { api } from ~/trpc/react; export function SnippetList() { const { data: snippets, isLoading, error } api.snippet.list.useQuery(); if (isLoading) return SnippetSkeleton /; if (error) return ErrorMessage error{error} /; return ( div classNamegrid gap-4 {snippets?.map((s) ( SnippetCard key{s.id} snippet{s} / ))} /div ); }这段代码里没有任何手动定义的类型注解但snippet.title、snippet.language的字段类型是由 tRPC router 的返回值自动推导的。我最初切到这种写法时最不习惯的一点是“太顺了”之前做全栈项目时总要花很多时间对接口字段现在字段一错编译期就报红基本不可能把错误的字段传到数据库查询层。详情页的 SSR 版本则区分了服务端组件和客户端组件。服务端直接调用 tRPC 的 caller 去数据库拿数据客户端只负责展示和点赞/收藏等交互。两者通过 props 传递初始数据这样首屏内容是静态 HTML搜索引擎和分享预览都能拿到完整信息。3.4 搜索、筛选与分页的落地实现代码片段一多列表页就需要搜索和筛选。t3code 的搜索逻辑很简单输入关键词后调 tRPC query 传keyword、language、page三个参数。后端用一个 Prismawhere条件组合查询const listSnippets publicProcedure .input( z.object({ keyword: z.string().optional(), language: z.string().optional(), page: z.number().default(1), pageSize: z.number().default(12), }) ) .query(async ({ ctx, input }) { const where { isPublic: true, ...(input.keyword ? { OR: [ { title: { contains: input.keyword } }, { content: { contains: input.keyword } }, ], } : {}), ...(input.language ? { language: input.language } : {}), }; const [total, items] await Promise.all([ ctx.db.snippet.count({ where }), ctx.db.snippet.findMany({ where, skip: (input.page - 1) * input.pageSize, take: input.pageSize, orderBy: { createdAt: desc }, }), ]); return { items, total, page: input.page, pageSize: input.pageSize, totalPages: Math.ceil(total / input.pageSize), }; });SQLite 里的contains默认不区分大小写但 PostgreSQL 则区分。如果你要跨数据库保持一致行为建议统一用mode: insensitive。但注意这个参数在不同数据库下性能差异较大索引策略也不同。t3code 目前数据量小没有优化太多真要上线的话可以直接考虑全文检索方案来替代contains这种模糊匹配。4. 常见问题与排查技巧实录4.1 tRPC 请求跨端类型不匹配的排查思路我遇到最多的问题不是“写得不对”而是“服务端类型更新后前端没有重新拉取到最新类型”。tRPC 的类型推导是构建期完成的开发环境一般还好但在部署到生产环境时如果前后端代码不是一次构建完成的容易出现某个 mutation 的入参类型不一致。我的排查套路是三步走在src/trpc/router里加一个临时 query返回希望用于调试的数据。前端用api.useUtils()调用invalidate()主动刷新缓存排除 React Query stale data 导致的旧数据。如果类型还是不对直接重新执行pnpm dev清除.next目录缓存再试。实际上绝大多数类型报错都停留在编译阶段比传统接口联调时“线上跑着跑着才崩”要容易定位得多。这也是我推荐新手优先尝试 tRPC 的原因——编译器就是你的联调工具。4.2 Prisma 查询中的 N1 问题与 include 策略最开始写列表页时我图方便直接用snippet.findMany()然后在组件里遍历snippet.author.name。前台数据量小没什么感觉但等测试数据加到几百条后页面明显变卡。原因是 Prisma 的懒加载模式逐条查 user 表产生了 N1 查询问题。正确做法是在一次查询里显式include关联数据ctx.db.snippet.findMany({ where, include: { author: { select: { id: true, name: true, image: true }, }, }, });同时给authorId字段建索引也能显著提升关联查询性能。Prisma 的 schema 里我用index([authorId])给 Snippet 表加了索引。虽然 SQLite 在数据量小的时候感觉不到差异但切换到 PostgreSQL 后这类索引收益会非常明显。4.3 NextAuth Session 偶尔失效的排查实录t3code 上线跑测试时遇到一个诡异问题用户登录后页面刷新偶尔就会跳回登录页控制台也没有明确报错。排查过程很曲折最后定位到是NEXTAUTH_URL和实际访问域名不一致导致的 session cookie 校验失败。如果你也遇到 Session 失效问题按优先级检查这几项.env中的NEXTAUTH_SECRET是否跨部署环境一致NEXTAUTH_URL是否和线上访问地址完全一致包括https://或http://前缀NextAuth的 session 策略选的 database 还是 jwt。t3code 用的是 jwt因为省去了数据库 session 表查询更适合服务端渲染场景。实际最容易被忽略的是反向代理或容器端口转发的场景外部访问https://example.com但应用内部看到的NEXTAUTH_URL是http://localhost:3000cookie 的作用域自然就不对了。解决办法是设置NEXTAUTH_URL为最终对外暴露的公网地址。4.4 常见问题速查表问题现象原因解决方法启动报DATABASE_URL缺失.env未配置或命名错误检查.env文件确保DATABASE_URL存在GitHub 登录跳转 404OAuth 回调地址不对在 GitHub Settings 里核对 callback URL首屏代码不高亮SSR 渲染时 Prism 主题未加载在布局中引入高亮样式或改用动态加载列表接口响应慢缺少关联索引给authorId等外键字段添加index修改代码片段后不刷新React Query 缓存未失效调用api.useUtils().snippet.list.invalidate()多语言高亮不生效language 参数未映射到 CodeMirror extension需要维护一份 language 到 extension 的映射表这张表是我把真实踩过的坑整理出来的浓缩版。项目本身不复杂但如果从零开始把这些坑都趟一遍至少会花掉一两个晚上。对照表格排查能省不少时间。5. 部署、性能优化与后续扩展方向5.1 部署到 Vercel 与使用 Docker 自行托管的对比t3code 的部署我做了一次双路线验证一条路线是 Vercel 托管一条是 Docker 自托管。Vercel 的体验是“开箱即用”对 Next.js 支持最完整连接 PostgreSQL 云数据库后DATABASE_URL配置到环境变量即可。缺点也很明显在国内网络环境下访问 Vercel 域名不稳定而且如果你有长时间运行的服务端逻辑Serverless 函数超时限制会带来麻烦。Docker 自托管则适合部署在自己的服务器上。我准备了一份Dockerfile用多阶段构建把 Next.js 应用打包成独立镜像FROM node:20-alpine AS deps RUN apk add --no-cache libc6-compat WORKDIR /app COPY package.json pnpm-lock.yaml ./ RUN corepack enable pnpm install --frozen-lockfile FROM node:20-alpine AS builder WORKDIR /app COPY --fromdeps /app/node_modules ./node_modules COPY . . RUN npx prisma generate RUN pnpm build FROM node:20-alpine AS runner WORKDIR /app ENV NODE_ENV production COPY --frombuilder /app/.next ./.next COPY --frombuilder /app/node_modules ./node_modules COPY --frombuilder /app/package.json ./package.json COPY --frombuilder /app/prisma ./prisma EXPOSE 3000 CMD [sh, -c, npx prisma migrate deploy node_modules/.bin/next start]这里特别留意prisma generate必须在编译前执行因为 tRPC 路由的代码里用到了PrismaClient类型。如果漏掉这一步build 过程会报一堆莫名其妙的类型错误。Docker 方案下数据库走DATABASE_URL连接外部 PostgreSQL不会把数据塞进容器里避免容器重建丢失数据。5.2 性能优化静态生成、ISR 与缓存策略t3code 里公开的代码片段列表页我尝试用 Next.js 的 ISR 做增量静态再生把访问热度高但变化不频繁的公开片段页面预渲染成静态 HTML每次请求直接从 CDN 边缘返回大幅降低源站压力。实现方式很简单export const revalidate 60;在 App Router 的页面级配置里加这一行就能让 Next.js 在客户端访问时触发重新校验。需要注意的是ISR 不适合需要实时准确的个性化数据场景比如“我的代码片段”页面所以 t3code 只在公开读物场景里用了 ISR。React Query 侧的缓存策略也很重要。列表页默认会 stale但如果你希望数据尽量保持新鲜可以在 useQuery 里传入较短的staleTime。t3code 的公开列表页我设置的是staleTime: 30_000既不会每次切页都打后端又能保证半分钟内能看到新内容。这个值可以根据自己业务调整没有“最佳”只有“合适”。5.3 从 t3code 到多用户协作平台的扩展路径写到这里有人可能会问“t3code 除了展示和增删改查还有什么值得深挖的空间”。我自己的判断是它很适合作为协作平台的底座。往这个方向扩展时最重要的几步是引入工作区Workspace概念代码片段归属从“用户”升级为“团队”在现有 Snippet 表上增加workspaceId外键把所有查询逻辑从单用户条件扩展到多租户条件增加评论和版本历史两张表配合 Prisma 多对多关系就能做成一个轻量级 Confluence 或 Notion 类的知识库雏形权限系统需要更完整的角色模型不能只靠isPublic字段得引入Member关联表和角色枚举。技术上 tRPC 的横向扩展能力很强每个新功能只需要新增一个 router 文件不会影响已有的代码结构。数据库改动相对多一些但因为 Prisma 的迁移机制很成熟加表加列的流程也比较可控。唯一需要谨慎的是权限判断逻辑要跟着模型变化不能继续沿用“看作者 ID”这种简单判断否则协作场景下会出现越权访问的风险。6. 开发体验复盘与独家经验分享6.1 类型安全带来的实际心态变化我在写 t3code 的过程中有一个非常明显的感受以前做全栈项目前后端联调要么靠写接口文档、要么自己记数据形状改字段时最怕忘了同步因此心理压力集中在对接口的不确定性上。tRPC Prisma 这套体系直接把这层不确定性磨平了改完 schema 跑一次prisma generate所有用到该字段的代码在编译期就会告诉你哪里红了。这种体验说玄一点是真的会“上瘾”的。它把开发者的精力从“应付类型漂移”拉回到“专注业务”上。不过我也要如实说类型安全带来的收益在大团队、大项目里可能会被协作摩擦抵消一部分因为频繁改类型会导致全员代码同步成本上升。t3code 这种中小型项目类型收益是最大的。如果你维护的是大项目建议在引入 tRPC 之前先把团队对 PHP 数组、any 类型、手写 interface 的容忍度聊清楚否则很容易出现一半人写防御性代码、一半人靠类型断言的割裂局面。6.2 开发期效率工具与工作流搭配t3code 的开发流程里有几个工具我非常依赖可以说离了它们效率会打对折Prisma Studio可视化浏览和修改数据库数据调试 seed 数据时特别省事。直接在浏览器里看表关系比查 API 文档快得多。eslint-plugin-t3-env校验环境变量对.env的拼写错误和类型错误能提前暴露。t3code 用的环境变量不多但这个插件保障了问题不会留到部署阶段才炸。GitHub Copilot写重复性的 CRUD 代码时它能猜到你想写什么配合 tRPC 的强类型生成的代码基本不用改。但推测性代码也要人工过一遍尤其是 Prisma 嵌套查询这种复杂场景。pnpm依赖安装速度快磁盘占用小对 t3code 这种需要频繁切换依赖版本的开发体验提升明显。我个人的工作流是先在 Prisma Studio 里确认数据形状 → 用 tRPC router 写查询/变更逻辑 → 前端联调遇到问题通过类型报错反推修复。三个环节之间跳转很顺不需要离开编辑器太久。6.3 最后分享一个小技巧用 tRPC caller 解决服务端组件数据获取这个小技巧我觉得值得单独拎出来说。Next.js App Router 里服务端组件无法直接调用 React Query 的 hooks但你可以通过 tRPC 的createCaller在服务端直接执行 router 查询完全复用客户端同样的逻辑而不需要自己额外写一遍数据获取代码。import { createCaller } from ~/trpc/server; export default async function SnippetDetailPage({ params }: { params: { id: string } }) { const caller createCaller(); const snippet await caller.snippet.byId({ id: params.id }); return SnippetView initialData{snippet} /; }这个模式最大的价值是同一个 router 逻辑同时服务客户端交互和服务端渲染。首屏数据从服务端拿后续交互收藏、评论走客户端 query两者不会出现重复代码。唯一的坑是你要确保 caller 创建时的ctx里有 session 信息否则受保护的路由不会识别当前用户身份。t3code 里我用headers()解析 session cookie 来解决这个问题。需要提醒的是这个操作对服务端缓存不太友好动态页面会跳过静态优化所以只推荐在需要个性化数据的页面使用公开列表页还是老老实实走 ISR 或静态生成。开发 t3code 这大半周里我最大的体会是现代全栈开发的效率提升并不只是某个框架多方便的问题而是整套工具链互相咬合之后把“上下文切换”的代价降到了极低。你不用再去记忆后端接口返回了哪些字段不用为了一个小改动重新理一遍数据流也不用担心把生产环境弄崩。工具链的选择很重要但比工具链更重要的是清楚自己在每个环节为什么要这么选。希望这篇拆解能给你一些参考少走几个我踩过的弯路。
阅读完成 · 觉得有帮助？
