最近整理代码的时候发现自己有个很没效率的习惯写一个稍微复杂一点的函数总忍不住跑到旧项目里翻半天“我记得这个分页查询之前写过”“那个防抖的 hook 好像在某次重构里”。找是找到了复制过来还得改参数、改类型、改命名一顿操作下来时间全浪费在“找东西”和“改东西”上。后来我干脆动手做了个小项目专门把这些反复用到的代码收拢起来做成可检索、可参数化生成的模板库名字就叫 t3code。技术底座选了 T3 StackNext.js、TypeScript、Tailwind CSS、tRPC、Prisma再加 NextAuth。这套组合让我在很短时间里搭出了一个能存、能搜、能生成代码片段的完整闭环项目本身也成了我后续开发里离不开的一个内部工具。这篇文章会把 t3code 从思路到落地的全过程拆开讲包括为什么选这套技术栈、数据模型怎么设计、类型链路怎么打通、部署会踩哪些坑以及我在实际使用中总结的一些排查经验。想搭一套私有代码片段库或者想完整走一遍 T3 Stack 全栈项目的朋友可以照着我这个思路往下走大部分代码都是可以直接抄过去的。1. 项目为什么是“t3code”从痛点出发的思路拆解1.1 我真正想解决的问题t3code 这个名字t3 指的就是 T3 Stackcode 则是这个项目的核心对象代码片段。做之前我列了一下自己最消耗时间的场景发现集中在几类常用但记不全的代码比如 Prisma 的分页查询、tRPC Router 的标准写法、NextAuth 的回调处理。每次都要“重新设计”一遍的通用逻辑比如防抖、节流、数组分组、URL 参数解析。团队内部约定俗成的模板代码比如新模块的目录结构、统一的 API 返回格式。这些代码不是不会写是每次写都很烦而它们往往藏在一个又一个旧仓库的深处搜不到、也不好整理。t3code 要解决的就是让这些代码变成可以随时检索、一键复用的“资产”而不是散落在各个项目里的“遗迹”。所以我给它的定位很简单一个私有的、快速响应的、以模板生成为核心的代码片段管理工具。我没有把它做成一个公开的社区平台原因也很实际代码片段这玩意儿主观性极强每个人的风格和规范都不一样搞一个公共平台反而会淹没个人真正需要的那一小部分内容。私有部署、本地优先这才是贴合开发者真实工作流的形态。所以 t3code 本质上是一个“个人生产力工具”的定位而不是一个“内容社区”的定位。1.2 为什么技术栈选择了 T3 Stack选择 T3 Stack 不是拍脑袋。我之前用传统 Next.js REST API 的模式写过东西最大的问题只有一个类型不安全。前端定义一个类型后端再定义一个类型数据库再定义一套三套类型全靠人肉同步字段一多就难免对不上改个字段名要全局搜替换跑起来才发现某处类型已经过时了。T3 Stack 的核心思路是用 TypeScript 把数据库、API、前端 UI 这三层串成一条类型安全的链路。tRPC 让前端调用后端接口时能直接获得完整的类型推导Prisma 让数据库模型成为类型定义的唯一来源Next.js 负责页面渲染和路由Tailwind 解决样式NextAuth 搞定认证。这套组合里我几乎不需要重复定义任何类型改一个 schema 字段全链路都会自动感知。有人可能会问为什么不用 NestJS 或者单独搞一个 Express 后端其实对于 t3code 这种规模的项目来说一个独立的 REST API 层带来的只有增加工作量和增加类型断裂风险。tRPC 的优势就是没有多余的学习成本和配置成本定义好 Router前端立刻就能拿到对应的类型写起来跟调用本地函数一样。对于这种工具型项目开发效率就是第一位的。另外 Tailwind 在这个项目里的存在感也很重要。我只需要几个简单的页面列表页、详情页、编辑页以及一个全局搜索框。Tailwind 让我不用在 CSS 文件里反复折腾类名和作用域直接在 JSX 里完成样式配合 Dark Mode 的暗色主题整个界面做下来花了不到半天。1.3 项目范围如何收敛任何一个项目如果一开始就想做“大而全”大概率会烂尾。t3code 在立项的时候我就把范围收敛到了三条核心能力上片段管理增删改查基础能力每个片段必须有标题、语言、内容、标签。快速检索通过关键字和标签组合筛出目标片段响应速度要快。模板生成部分片段支持参数化填入变量后自动生成最终代码。至于评论、点赞、多人协作、团队空间这些都排除了。不是说这些没用而是对于第一版来说做一个能每天用的工具比做一个到处是半成品功能的平台有意义的得多。事实也证明MVP 跑通之后我再往里面加任何功能都有清晰的判断依据这是我自己会用到的吗2. 核心设计与关键细节解析2.1 数据模型设计片段、标签、模板的关系数据模型是 t3code 的地基。我花了比较多的时间在 Prisma Schema 上因为一旦模型设计得不好后面改起来非常痛苦。我最终设计了四个核心模型User、Tag、Snippet 和 Template。model User { id String id default(cuid()) name String? email String? unique emailVerified DateTime? image String? accounts Account[] sessions Session[] snippets Snippet[] } model Tag { id String id default(cuid()) name String userId String snippets SnippetTag[] user User relation(fields: [userId], references: [id], onDelete: Cascade) } model Snippet { id String id default(cuid()) title String language String content String summary String? createdAt DateTime default(now()) updatedAt DateTime updatedAt userId String user User relation(fields: [userId], references: [id], onDelete: Cascade) tags SnippetTag[] templates Template[] } model Template { id String id default(cuid()) name String description String? variables Json template String snippetId String snippet Snippet relation(fields: [snippetId], references: [id], onDelete: Cascade) }这里面有几个设计决策值得展开说。第一为什么 Tag 不直接和 Snippet 做多对多而是引入了一个中间模型 SnippetTag原因是在 Prisma 里隐式的多对多关系虽然也能用但如果你想在关联关系上存额外信息比如“加标签的时间”隐式关系就没办法扩展了。而且显式中间模型在删除、去重、批量操作时SQL 语义更清晰。这里我先用 SnippetTag 来连接 Snippet 和 Tag后面如果要给标签加“收藏次数”“最近使用时间”之类的字段直接在这个模型上加就行。第二Template 模型单独拆出来而不是直接塞进 Snippet 里是为了把“代码片段”和“可生成模板”这两个概念分开。有些片段只是用来参考的不需要参数化有些片段则要生成多个变体比如一个 Prisma 分页查询模板页大小、排序字段、是否返回总数这些都可以作为变量。如果一个 Snippet 里既有原版代码又有模板语法维护起来会非常混乱。拆分之后一个 Snippet 可以对应多个 Template每个 Template 可以有不同的参数组合和生成逻辑。第三所有数据模型都加上了 userId 作为外键。t3code 虽然是我自己的工具但我也没排除以后让身边几个朋友一起用的可能。增加 userId 之后数据的权限隔离就非常自然所有查询都加一层 where: { userId }每个用户只能看到自己的片段。反正这个成本在开发阶段很低但回避了以后“数据混在一起”的迁移痛苦。2.2 类型安全链路从数据库到 UI 的单一来源T3 Stack 最爽的一点在于你不需要在 API 层重复定义类型。Prisma Schema 写完之后运行一次 prisma generate所有的模型类型都会自动输出到 node_modules/.prisma/client 里。tRPC Router 里直接引用 Prisma 返回类型前端调用时又直接从 tRPC 的 output 推断出类型这中间没有任何手写的 interface从数据库到 UI 的整个数据链路是“同源”的。举个例子我的 snippets 列表接口长这样export const snippetRouter createTRPCRouter({ list: protectedProcedure .input( z.object({ keyword: z.string().optional(), page: z.number().int().default(1), pageSize: z.number().int().min(1).max(50).default(20), }) ) .query(async ({ ctx, input }) { const where: Prisma.SnippetWhereInput { userId: ctx.session.user.id, }; if (input.keyword) { where.OR [ { title: { contains: input.keyword } }, { summary: { contains: input.keyword } }, { content: { contains: input.keyword, mode: insensitive } }, ]; } const [items, total] await Promise.all([ ctx.prisma.snippet.findMany({ where, include: { tags: { include: { tag: true } } }, orderBy: { updatedAt: desc }, skip: (input.page - 1) * input.pageSize, take: input.pageSize, }), ctx.prisma.snippet.count({ where }), ]); return { items: items.map((item) ({ ...item, tags: item.tags.map((t) t.tag.name), })), total, page: input.page, pageSize: input.pageSize }; }), });这段代码里有几个值得注意的点我在查询里用了 Promise.all 同时执行 findMany 和 count避免串行等待。Prisma 这两个查询之间没有依赖并行执行能把接口响应时间压缩不少。where 条件直接用 Prisma.SnippetWhereInput 这个类型来声明保证拼接查询条件时不会被 TypeScript 挑错。include 了 tags 的中间表再映射成纯字符串数组返回给前端。前端拿到的 tags 就是 string[]而不是一堆嵌套对象渲染起来省心很多。前端调用的时候更简单React Query 配合 tRPC 的 useQuery类型自动跟随const { data, isPending } api.snippet.list.useQuery({ keyword, page: currentPage, pageSize: 20, });这里 data 的类型就是后端返回的 { items, total, page, pageSize }并且 items 里的字段全部是 Prisma Schema 里定义好的。如果我在后端改了返回结构前端的 TypeScript 立刻会报错这种“编译期就能发现问题”的体验是传统 REST API 完全给不了的。2.3 模板生成逻辑与参数化方案t3code 的另一半核心在“模板生成”。模板生成的思路很像邮件模板正文里定义占位符用户填入变量最终渲染出结果。我采用的占位符语法是常见的双大括号格式{{variableName}}。变量除了默认值还可以带校验规则和可选项。我设计的模板变量格式大概是这样存成一个 JSON{ pageSize: { type: number, label: 每页数量, default: 20, min: 1, max: 100 }, sortField: { type: select, label: 排序字段, options: [createdAt, updatedAt, title], default: updatedAt } }生成逻辑的核心函数是一个简单的 replace 校验流程这里我给出了完整实现import z from zod; export function renderTemplate(template: string, variables: Recordstring, unknown, variableSchema: Recordstring, unknown): string { let result template; for (const [key, rawSchema] of Object.entries(variableSchema)) { const config rawSchema as { type: string | number | select | boolean; default?: unknown; min?: number; max?: number; options?: unknown[]; }; let baseSchema: z.ZodTypeAny; if (config.type number) { baseSchema z.coerce.number(); if (config.min ! undefined) baseSchema baseSchema.min(config.min); if (config.max ! undefined) baseSchema baseSchema.max(config.max); } else if (config.type select) { baseSchema z.enum(config.options as [string, ...string[]]); } else if (config.type boolean) { baseSchema z.boolean(); } else { baseSchema z.string(); } const parsed baseSchema.safeParse(variables[key] ?? config.default); if (!parsed.success) { throw new Error(变量 ${key} 校验失败: ${parsed.error.message}); } result result.replaceAll({{${key}}}, String(parsed.data)); } return result; }模板正文里可以混入条件片段。比如某些变量为空时不渲染对应的行这个我暂时用简单的“在模板里写死默认值”来处理更复杂的条件语法留到了 v2。整体来说这套模板方案不追求高度抽象但做代码片段生成已经非常够用了。模板渲染的结果会实时显示在页面上用户还可以一键复制整个链路非常顺。3. 从零到一实操搭建 t3code 的核心流程3.1 初始化项目与目录结构t3code 的初始化非常快直接用了官方脚手架npx create-t3-applatest t3code交互式选项里我选择的是Next.js App Router、TypeScript、Tailwind CSS、Prisma、tRPC、NextAuth。后面 lint 和 prettier 我也都选了统一代码风格这种事早期做比后期再补要轻松得多。创建完成之后的目录结构大概是这样的t3code/ ├── prisma/ │ ├── schema.prisma │ └── seed.ts ├── src/ │ ├── pages/ # App Router 之前是 pages新版用 app │ ├── app/ │ │ ├── api/ │ │ ├── (main)/ │ │ │ ├── snippets/ │ │ │ └── templates/ │ │ ├── layout.tsx │ │ └── page.tsx │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ │ │ │ │ ├── snippet.ts │ │ │ │ ├── tag.ts │ │ │ │ └── template.ts │ │ │ └── root.ts │ │ ├── db.ts │ │ └── auth.ts │ ├── trpc/ │ │ ├── server.ts │ │ └── client.ts │ └── styles/ │ └── globals.css └── .env这个结构是 create-t3-app 的默认结构。需要特别注意的是新版脚手架默认使用 App Router所以页面放在 app 目录下tRPC 相关的 server 代码在 server/api 下客户端封装在 trpc 下。不要自己手动乱挪这些目录t3 脚手架的按约定组织目录是有道理的迁移时容易出错的就是 router 的导入路径。3.2 配置 Prisma 数据模型与数据库连接在 .env 文件里配置数据库连接。我本地开发用的是 SQLite部署到 Vercel 时换成 PostgreSQL所以连接串要做区分# 本地开发 DATABASE_URLfile:./dev.db # Vercel 部署时替换为 PostgreSQL 连接串 # DATABASE_URLpostgresql://user:passwordhost:5432/t3code这里有个小经验SQLite 和 PostgreSQL 在 Prisma 层面大部分能力是通用的比如基础的 CRUD、分页、过滤都没问题。但要注意 SQLite 不支持mode: insensitive的不区分大小写查询这条我在联调时踩过坑在 t3code 里我对 SQLite 环境做了降级如果检测到 dialect 是 sqlite就直接用 contains不做 insensitive。后续部署到生产再用 PostgreSQL搜索体验会更好代码也不受影响。Schema 定义好之后执行数据库迁移npx prisma migrate dev --name init npx prisma generate关于prisma generate我多说一句每次修改 schema 之后必须重新运行否则 Prisma Client 不会包含最新的模型定义。开发中如果发现 TS 类型还是旧结构第一反应就应该是重新 generate而不是检查代码。3.3 实现 tRPC Router列表、搜索与模板生成Router 是 t3code 的后端核心。我在 src/server/api/routers/snippet.ts 里实现了 snippet 增删改查和搜索在 template.ts 里实现了模板的渲染。核心代码在上面类型链路一节已经展示过这里补充一个关键点如何把模板渲染和授权校验结合起来。import { z } from zod; import { createTRPCRouter, protectedProcedure } from ~/server/api/trpc; import { renderTemplate } from ~/utils/render-template; export const templateRouter createTRPCRouter({ render: protectedProcedure .input( z.object({ templateId: z.string(), variables: z.record(z.string(), z.unknown()), }) ) .query(async ({ ctx, input }) { const template await ctx.prisma.template.findFirst({ where: { id: input.templateId, snippet: { userId: ctx.session.user.id }, }, }); if (!template) { throw new Error(模板不存在或无权访问); } const variablesSchema (template.variables ?? {}) as Recordstring, unknown; return { content: renderTemplate(template.template, input.variables, variablesSchema), }; }), });查询模板时我特意通过snippet: { userId: ctx.session.user.id }来连带校验归属关系这样就算有人拿着别人的 templateId 来请求也会因为关联不到数据而被拒绝。这一步是很多人容易忽略的只校验了模板存在没有校验模板归属会导致越权读取。这里还有个更安全的做法在 tRPC 的 procedure 上定义一个中间件统一做“资源属主”校验。不过 t3code 规模不大直接在查询条件里带上 userId 已经足够代码也简洁。3.4 前端界面从列表到检索再到复制前端页面我用的方案是服务端渲染加客户端交互混合。因为 t3code 的核心操作是快速检索和复制所以我把列表页做成了“服务端渲染列表 客户端搜索”的组合。顶部搜索框是关键交互点。我给搜索框绑定了 CmdK 快捷键打开页面焦点直接落在输入框输入关键字后通过 tRPC 的api.snippet.list.useQuery自动请求并更新列表。React Query 的缓存让重复搜索的响应非常快配合 debounce 300ms输入体验几乎无延迟。前端列表的一个核心组件use client; import { api } from ~/trpc/client; import { SnippetCard } from ./snippet-card; import { useDebouncedValue } from ~/hooks/use-debounced-value; export function SnippetList({ initialKeyword }: { initialKeyword?: string }) { const [keyword, setKeyword] useState(initialKeyword ?? ); const debouncedKeyword useDebouncedValue(keyword, 300); const [page, setPage] useState(1); const { data, isPending } api.snippet.list.useQuery({ keyword: debouncedKeyword, page, pageSize: 20, }); return ( div div classNamemb-6 flex items-center justify-between input autoFocus typetext value{keyword} onChange{(e) { setKeyword(e.target.value); setPage(1); }} placeholder搜索代码片段支持标题、摘要、内容... classNamew-full rounded-md border border-gray-300 px-4 py-2 focus:outline-none focus:ring-2 focus:ring-blue-500 / span classNameml-2 rounded bg-gray-100 px-2 py-1 text-xs text-gray-500⌘K/span /div {isPending ? ( div classNamepy-10 text-center text-gray-500加载中.../div ) : ( div classNamegrid gap-4 md:grid-cols-2 lg:grid-cols-3 {data?.items.map((snippet) ( SnippetCard key{snippet.id} snippet{snippet} / ))} /div )} /div ); }代码本身不复杂但有个细节值得分享useDebouncedValue是自定义 hook实现用了useEffectsetTimeout300ms 的延迟对搜索体验是折中得最好的一个值。太短会导致输入过程中的中间态请求太多太长则会明显感受到“卡一下”。300ms 是输入类搜索的常见经验值你可以根据实际感知微调。复制功能我用了浏览器原生的navigator.clipboard.writeText没有额外引入 clipboard 库。给复制成功加一个 2 秒的 Toast 反馈这个小交互看着简单但实际体验提升非常大至少你不会每次复制完都要怀疑到底复制成功没有。3.5 部署到 Vercel 的步骤与环境变量配置部署到 Vercel 前需要做两件事把数据库从 SQLite 换成 PostgreSQL并配置环境变量。我直接用 Vercel 集成的 Postgres 服务也可以使用任何其他 PG 兼容的数据库服务无外乎都是把DATABASE_URL换成对应的连接串。部署时要注意的配置项AUTH_SECRET必须重新生成一个等价于令牌本地开发时用的值不能直接搬到线上。DATABASE_URL对应生产数据库连接串注意加上连接池参数才比较稳比如?sslmoderequire。环境变量在 Vercel 的 Project Settings Environment Variables 里配置。配置之后重新部署才会生效。部署之前还需要先在本地跑一次数据库迁移或者直接在 Vercel 的后置脚本里执行npx prisma migrate deploy这一点尤其重要prisma migrate deploy和开发时的migrate dev不一样migrate dev会生成新的迁移文件而migrate deploy只执行已有迁移不生成新文件。在 CI/CD 或 Vercel 构建环境中一般用migrate deploy比较安全。最后因为 Vercel 的 Serverless 环境是无状态短时运行的连接数据库时尽量使用连接池配置具体做法是在连接串里带上连接池参数或者通过 Prisma 的加速能力来管理连接。SQLite 只能在本地开发用线上请务必切 PostgreSQL。4. 常见问题与排查技巧实录4.1 Prisma 模型修改后没有生效这个问题大概率发生在两种场景改完 schema 忘记重新prisma generate或者改了 schema 但没有执行数据库迁移。前者的表现是 TypeScript 类型提示还是老结构后者的表现是运行时查询报“表不存在”或“列不存在”。排查顺序是先跑npx prisma generate看是否能自动修复类型错误。再跑npx prisma migrate dev确认数据库结构是否和 schema 一致。如果线上环境报错登录数据库终端查一下表结构比对是否和最新迁移一致。还有一个容易忽略的坑开发环境里常见的node_modules/.prisma/client如果被某些工具重置了也要重新 generate 一次。另外如果你用seed脚本跑数据seed 脚本里的代码也必须依赖最新的 Client 类型否则同样要重新 generate。4.2 tRPC 类型不一致问题排查思路t3code 开发过程中最常见的 TS 报错是“类型不匹配”大多发生在 Router 输出结构变更以后前端查询代码没有跟随更新。比如某次我把tags从对象数组改成了字符串数组前端代码里还在用item.tags.map(t t.tag.name)来渲染就会立刻报错。遇到这类问题统一的做法是先打开 tRPC Router 的返回语句确认字段实际结构再去前端看使用的地方。因为类型是自动推断的你不需要手动修改任何 interface关键是要让代码“遵循类型”而不是强行用as断言把类型绕过去。我见过很多人遇到类型问题就用as any一次两次无所谓但 t3code 这种以类型安全为最大卖点的项目任何as any都是在自毁优势。真遇到搞不定的类型问题宁可多花十分钟把 Router 的返回结构调整好也不要直接绕过类型检查。4.3 NextAuth 登录后 Session 获取不到t3code 的搜索和列表接口都用到了protectedProcedure如果 Session 获取失败前端会直接报 401。最常见的三个原因环境变量AUTH_SECRET没有设置或设置不一致。本地和线上必须各自生成独立的 AUTH_SECRET不能把本地的直接搬到线上。Provider 配置有问题。我初期只用了 GitHub Provider回调地址要填对比如本地是http://localhost:3000/api/auth/callback/github线上要换成你的 Vercel 域名。填错回调地址会报redirect_uri错误。session.user.id拿不到。t3 脚手架的默认 session 里只有user.name和user.email没有user.id。如果你想在 Router 里直接用ctx.session.user.id必须在src/server/auth.ts里扩展 session 类型手动把 user id 注入进去。第三个坑可以说非常经典了。我一开始直接写ctx.session.user.idTypeScript 一直报“Property id does not exist on type Session”后来才意识到需要自定义 session 回调。在[...nextauth].ts的 callbacks 里加上callbacks: { session({ session, user }) { if (session.user) { session.user.id user.id; } return session; }, }然后类型扩展可以写在src/types/next-auth.d.ts里import { DefaultSession } from next-auth; declare module next-auth { interface Session { user: { id: string; } DefaultSession[user]; } }这一步做完ctx.session.user.id就不会再报错了。这个问题如果没人提醒自己排查可能要花不少时间建议看到这里的同学直接加到你自己的 T3 项目里。4.4 列表接口性能优化与缓存细节t3code 数据量不大但搜索接口在模糊查询时会有一定的 CPU 开销。为了体验更好我在前端做了两件小事debounce 和 staleTime。debounce 前面已经讲了staleTime 是 React Query 的参数表示“在这段时间内认为数据不过期直接使用缓存不重新请求”。列表查询我设置的 staleTime 是 10 秒api.snippet.list.useQuery( { keyword: debouncedKeyword, page, pageSize: 20 }, { staleTime: 10_000 } );这个值的意思是同一个关键字、同一页的数据10 秒内再次访问不会触发后台请求直接读缓存。对于 t3code 这种终端使用很密集的工具能明显减少 loading 闪烁。后端层面模糊搜索目前用的是 SQLcontains。PostgreSQL 下如果数据量变得很大建议后续换成全文索引或者 trigram 索引目前阶段加索引就够了index([title, content])另外还有一个容易被忽略的性能点列表页返回的 items 里包含了content字段即完整的代码内容。卡片预览页如果只是展示摘要完全可以不返回 content 这个重字段。我在列表接口里做了裁剪通过select只返回卡片需要的字段详情页再通过单独的接口拿完整 contentfindMany({ select: { id: true, title: true, summary: true, language: true, updatedAt: true, tags: { select: { tag: { select: { name: true } } } }, // 不包含 content减少网络体积 }, })这个优化在本地数据量小的时候看不出来但在云数据库的场景下每次减少读 payload 都是在实打实地降低响应时间。写在最后的小经验t3code 从动手到上线满打满算只花了一个周末多一点的时间这完全归功于 T3 Stack 把类型链路打通之后所有精力都能集中在业务逻辑上而不是耗在前后端对接和类型维护上。做完这个项目之后我写新代码的第一选择不再是去旧仓库里翻来找去而是打开 t3code 按一下 CmdK把模板调出来改几个参数就直接用。这种工作流的改变是实打实用出来的。最后再分享一个小技巧如果你的代码片段库越来越庞大搜索的关键不在于“搜得有多准”而在于标签和摘要是否写得够好。我在 t3code 里给每个片段强制要求写 summary刚开始觉得多一道工序用起来才发现摘要写得好不好直接决定了搜索时能不能一眼认出“这就是我要找的那段代码”。这个习惯比任何技术优化都重要。