大概三个月前，我在本地调试一个日志清洗脚本，翻了七八个开源仓库，愣是没找到一段可以直接复用又足够精简的实现。要么是项目太老依赖一堆，要么是写得像天书，注释比代码还难懂。当时我就在想，与其每次到处翻仓库，不如自己搞一个轻量的代码片段库，把平时写过的好东西全部收进去，最好还能一键分享给同事，甚至直接在浏览器里跑一遍验证效果。于是就有了这个代号叫t3code的项目。
t3code 是一个基于T3 Stack（Next.js + TypeScript + tRPC + Prisma + TailwindCSS）构建的代码片段管理与在线分享平台。它不追求成为一个多庞大的笔记系统，只专注做三件事：快速保存代码片段、给片段打标签并全文检索、通过一个公开链接把片段发给任何人（支持匿名阅读和评论）。如果你也日常被代码复用折磨，或者想在公司内部搭一套轻量的代码沉淀工具，这篇复盘应该能帮你少踩不少坑。
1. 为什么我决定用 T3 Stack 做 t3code，而不是老一套的 REST + 独立前端
1.1 一开始我也觉得 Next.js 全家桶有点重
说实话，刚开始立项时，我心里是有犹豫的。一个代码片段工具，最传统的做法是 Express 后端 + 一个 Vue/React 前端，API 设计好，两边各写各的。这个方案我熟得很，20 分钟内就能把 CRUD 骨架搭出来。但真开始写的时候，我发现自己要维护两套类型定义：数据库模型一套，前端接口请求响应参数一套，中间还要手动保证字段名一致。项目小的时候还能靠自觉，等代码片段关联上标签、评论、用户收藏、搜索条件之后，字段一多，心智负担立刻上来。
我那时候看了一眼 T3 Stack 的推荐组合，发现它其实不是"重"，而是把类型安全这件事贯彻到了每一层。Next.js 负责页面渲染和 API 路由，tRPC 负责前端直接调用后端函数，Prisma 负责数据库 schema 和类型生成，Zod 负责在函数入口做数据校验，Tailwind 负责样式。整条链路上，只要你在 Prisma schema 里改一个字段名，前端代码里立刻就会有类型报错。这种"改一处，全线亮红灯"的体验，实际上是在帮我对冲重构风险。
1.2 t3code 要解决的核心问题
在动工之前，我先把需求收敛成了四类核心问题。
第一，保存要快。我不希望像写博客一样还要排版、起标题、配图。保存片段的交互必须是一步到位：贴进代码框，按一下快捷键，自动提取当前语言的注释作为标题，再选几个标签，搞定。
第二，检索要准。代码片段多了以后，靠人肉分类基本废了。我要的是全文搜索，包括代码内容、注释、标签名、语言。搜 "readStream" 就得把涉及文件读取流的前后端片段全列出来。
第三，分享要轻。分享出去的时候，不需要接收方注册账号，打开链接就能看到格式化后的代码，能复制，能评论。这个看起来简单，但匿名评论对权限模型、反垃圾策略都会带来额外的工作量。
第四，数据要可控。所有片段数据最终要能导出，不能被平台绑定死。至少要提供 JSON 导出和还原能力。
基于这四点，t3code 的功能边界就定了。它不做在线编辑器，不做多人实时协同，不做流程审批，也不做复杂的工作区。市面上很多类似工具死掉，就是因为把自己撑得太大。
1.3 T3 Stack 到底解决了什么，没有解决什么
我对 T3 Stack 的认知经历过一轮矫正。网上经常说 T3 是"全栈信仰"，但实际上它并没有创造新框架，只是把一个经过检验的技术栈组合固定下来。它解决的问题是开发链路中的类型断裂，而不是业务复杂度。
举个最直接的例子。老办法里，前端调后端接口时，通常要自己写fetch('/api/posts/1')，然后对响应做any断言，既丑又不安全。t3code 里用 tRPC 之后，是这样调的：
const post = trpc.post.get.useQuery({ id: 'clv123' });如果post.get的入参不是{ id: string }而是{ slug: string }，编辑器里立刻就会报错，不用等到运行时炸。这个价值在协作开发里尤其明显，新同事接手代码时，看类型定义就能大概猜出后端函数输入输出，不太需要反复看接口文档。
但 T3 Stack 没有解决 Novice 常见的那些问题：数据库索引要自己建、缓存策略要自己设计、接口鉴权要自己写，还有部署环境的 Node 版本、上传文件存储位置、图片 CDN 路径，这些全都得自己处理。后面我在部署阶段踩了几个坑，基本都和"框架没帮你做的那 20%"有关，这个到第五章细说。
2. 数据建模与存储：代码片段、标签和渲染快照
2.1 Prisma 模型设计：把 tags 放到关联表而不是 JSON 字段
第一版 schema 我偷了个懒，把tags设计成了String[]，直接放在片段表里。用起来确实快，Prisma 原生支持字符串数组，PostgreSQL 底层就是一个数组字段。但过了两周，我发现搜索"哪些代码片段用了 Node.js 标签"时，SQL 要写成WHERE 'Node.js' = ANY(tags)，如果还想统计标签使用频率，就只能全表扫描后在前端算，性能很快会出问题。
后来我改成标准的标签关联表，用一张中间表建立片段和标签的多对多关系：
model Snippet { id String @id @default(cuid()) title String language String content String @db.Text description String @default("") isPublic Boolean @default(true) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt userId String user User @relation(fields: [userId], references: [id]) tags SnippetTag[] comments SnippetComment[] @@index([userId, isPublic]) @@index([language]) } model Tag { id String @id @default(cuid()) name String @unique snippets SnippetTag[] } model SnippetTag { snippet Snippet @relation(fields: [snippetId], references: [id], onDelete: Cascade) snippetId String tag Tag @relation(fields: [tagId], references: [id], onDelete: Cascade) tagId String @@id([snippetId, tagId]) @@index([tagId]) }多对多关系带来一个好处：标签自动去重、自动补全。前端输入标签时，我可以直接查询Tag表，把已存在的标签展示为建议项，用户点一下就绑定。后面做统计报表（比如"最常用的 20 个标签"）也就是一条groupBy的事，不用再折腾解析字符串数组。
不建议把标签存成 JSON 字段的唯一例外是：你明确知道标签是"纯展示属性"，完全不参与检索、统计和关系筛选。但代码片段这种天然需要搜索场景的内容，用 JSON 存标签基本是自埋地雷。
2.2 为什么不直接把代码文本塞进 MySQL
先声明一点，t3code 用的主数据库是 PostgreSQL。原因倒没有多玄学，主要是「全文检索」和「JSONB」这两块，PostgreSQL 用起来更顺手。做代码片段搜索，MySQL 的LIKE '%keyword%'在数据量到几万条以后就会明显吃力，而 PostgreSQL 的tsvector/tsquery配合 GIN 索引可以把中文和代码检索压到几十毫秒。
不过「全文搜代码」这个需求，我一开始就知道数据库全文索引只是及格线，不是满分答案。原因很简单：代码里全是符号，=>、::、?.,这些 token 会被分词器拆得乱七八糟。所以 t3code 的搜索方案是双轨制：标题、描述、标签走 PostgreSQL 的tsvector索引；代码内容走一个轻量级的倒排索引服务。
我一开始试过直接把代码content字段丢进 Postgres GIN 索引，结果搜useEffect(() => {这种带括号的字符串时，查出来的内容根本不相关。后来我做了折中：将代码内容清洗一遍，提取出字符串、标识符、函数名，生成一份"搜索快照"字段。搜索时同时查内容快照和原始内容，相关性权重向标题和标签倾斜。实测下来，日常查询的响应时间稳定在 100ms 以内，完全够用。
2.3 导入导出与快照渲染
代码片段除了有原文本，我还额外存了一份htmlSnapshot。为什么存这个？因为分享页要支持多种代码主题高亮，而浏览器端做高亮（比如用 Shiki 或 Prism）需要时间。每次有人打开分享链接，如果都要在浏览器里重新跑一遍 tokenize，一百个并发访客就会吃掉不少 CPU。
做法是这样：保存片段时在后端用 Shiki 按当前语言做一次代码高亮，生成静态 HTML 字符串存入字段；前端展示时直接用dangerouslySetInnerHTML渲染。高亮逻辑变了就全量重跑刷新快照。代价是每次代码更新时多一次渲染计算，换来阅读端"零计算打开"，这笔账非常划算。
下面是 Prisma schema 里快照相关字段：
model Snippet { // ... searchSnapshot String @default("") @db.Text htmlSnapshot String @default("") @db.Text highlightTheme String @default("github-light") }导入导出方面，我提供了一个"工作区 JSON"格式，包含片段正文、标签、语言、创建时间。导出按钮在后端直接把查询结果序列化成一个 JSON 文件下发。导入时则是一个事务：先按tagName批量 upsert 标签，再插入片段记录，最后在中间表里绑定关系。如果中间某一步失败，整个导入事务回滚，避免出现"片段进来了但标签丢了一半"的脏数据。
经验：代码片段的"原文"一定要用
Text类型，不要用Varchar(255)。我见过有人把长日志处理函数硬塞进 255 字符字段，直接截断，导致复制出去的代码根本无法运行。
3. tRPC 的一体化查询，让前后端类型真正共用
3.1 Router 划分与类型推导
t3code 的 tRPC 路由我划分成五块：snippet、tag、comment、user、stats。每个文件里放一个独立 router，然后在根 router 里合并。
import { createTRPCRouter } from "~/server/api/trpc"; import { snippetRouter } from "./routers/snippet"; import { commentRouter } from "./routers/comment"; import { tagRouter } from "./routers/tag"; import { statsRouter } from "./routers/stats"; import { userRouter } from "./routers/user"; export const appRouter = createTRPCRouter({ snippet: snippetRouter, comment: commentRouter, tag: tagRouter, stats: statsRouter, user: userRouter, });前端调用时，最理想的状态是连"类型导入"都不用写。t3code 里我把类型导出集中到~/utils/api，页面组件里这么用：
import { api } from "~/utils/api"; const snippets = api.snippet.getMine.useQuery({ page, pageSize, query });如果你是从 REST 走过来的，第一次见到这个 API 会有点恍惚：没有axios、没有fetch、没有try/catch，代码看起来像是在调用一个本地函数。实际上 tRPC 底层还是 HTTP 请求（默认走 POST + JSON），只是把类型信息通过 TypeScript 推导串起来了。它不产生额外运行时开销，类型文件在编译期就被擦除了。
3.2 Zod 校验在服务端入口
t3code 的每一个 mutation 入参都经过 Zod 校验。这其实是 T3 社区约定俗成的做法：Schema 既用来做运行时校验，又用来做类型推导。
import { z } from "zod"; const snippetInput = z.object({ title: z.string().min(1).max(200), content: z.string().min(1).max(500_000), language: z.string().max(50), tags: z.array(z.string().max(50)).min(0).max(10), isPublic: z.boolean().default(true), }); export const snippetRouter = createTRPCRouter({ create: protectedProcedure .input(snippetInput) .mutation(async ({ ctx, input }) => { // ... }), });相同的一条输入定义可以用在前端表单上，直接用z.infer<typeof snippetInput>就能拿到表单类型。这样表单校验和后端校验用的是同一套规则，不会出现前端允许空标题、后端拒绝空标题这种撕裂情况。
我后来把校验规则从函数体内独立出来，放到一个schema.ts文件里统一维护。因为 Zod 对象是引用类型，在 Server 和 Client 同时引入时要留意打包边界。t3code 的做法是：包含 Zod 的 schema 文件放到src/shared/schemas.ts，这个目录下的代码可被前后端同时引用，而包含prisma、jwt、bcrypt之类的服务端代码，不导出给前端。
3.3 SSR 下的缓存策略：实际踩过的一个坑
T3 默认页面渲染有两种模式：服务端渲染（SSR）和静态生成（SSG）。t3code 的首页是"我的最近代码片段"，按理说应该用 SSR，这样打开页面时数据已经注入了，首屏看不到 loading，SEO 也好。
但问题来了：tRPC 在 SSR 时会把查询结果序列化到 React Query 的 hydration 数据里。如果这个结果包含Date类型，Next.js 在serialize阶段会直接抛错——不是JSON.stringify的报错，而是"未能序列化数据"的晦涩异常。第一次遇到的时候我排查了很久，最后发现是createdAt是DateTime类型，返回给前端的时候是一个 Date 对象，React Query 的官方推荐做法是将日期统一转成 ISO 字符串。
所以我定了一个规矩：tRPC 的 output 里不允许直接返回数据库的 Date 对象。要么在 select 阶段用format: 'iso'处理，要么在 router 返回前统一toISOString()。宁可多写一行转换，也不让类型推导把 Date 偷偷带到前端。
另外，SSR 模式下的缓存也让我措手不及。Next.js 默认会缓存部分没有cookies()或headers()读取的页面渲染结果。t3code 有的页面数据跟当前用户绑定，就必须显式声明export const dynamic = 'force-dynamic'，否则会出现用户 A 看到用户 B 片段这种低概率但极其糟糕的线上事故。我排查这个问题时翻了很多文档，最后总结出来的经验是：只要页面读取了 tRPC 中依赖 session 的查询，就一定要加动态渲染标记，别指望框架自动判断。
4. 权限、协作和限流：公开分享容易，防滥用很难
4.1 公开链接 vs 私有可见性
t3code 的核心场景是分享，所以可见性设计我拆成了三档：public、unlisted、private。public会出现在社区的公开列表里；unlisted生成一个不可猜测的长链接，知道地址的人可以看，但不会公开展示；private只有自己和管理员能看到。
unlisted这个档位是我仔细想过后才加的。很多人只想发给同事或朋友看，并不想让所有路过首页的人都看到，但也不想登录注册产生账号门槛。一个 128 位随机字符串的链接，在没有被人转发的情况下，几乎不可能被恶意枚举。配合后面的限流，这个方案在防滥用方面够用了。
权限判断的逻辑很简单，但容易写错。核心就一条规则：
function canViewSnippet(snippet: Snippet, user: User | null): boolean { if (snippet.isPublic) return true; if (snippet.visibility === "private") { return user !== null && (snippet.userId === user.id || user.role === "ADMIN"); } // unlisted return true; }注意unlisted不校验任何权限，因为安全模型的基础是"链接不可猜测"。如果你在unlisted情况下还需要校验分享人身份，那就是走传统的密码链接分享了，复杂度会指数级上升。
4.2 编辑权限设计：owner / editor / viewer
单用户工具的本义是有私密收藏，但为了让公司内部使用更顺畅，我加了"编辑者"角色。协作关系的粒度没有做得很细，就三个角色：owner 可以编辑、删除、转移所有权；editor 可以编辑内容但不能删除；viewer 只能看。
我用一张单独的SnippetMember表来存权限关系，而不是直接给 snippet 表加ownerId+editorId。原因是一段 snippet 未来很可能被多个人同时收藏、转发，如果权限成员直接堆在 snippet 里，查询逻辑会变成数组比较，很难写索引。
model SnippetMember { snippetId String userId String role Role @default(VIEWER) @@id([snippetId, userId]) @@index([userId, role]) }服务端做一次联合查询：先查SnippetMember里用户对片段的角色，再合并用户自身的 owner 权限。整个判断逻辑不超过 20 行，但注意要在数据库层面做唯一性约束@@id([snippetId, userId])，防止重复插入造成权限混乱。
4.3 匿名评论与滥用防护
匿名评论是 t3code 分享功能里最让人纠结的设计。好处是降低反馈门槛，坏处是垃圾广告、辱骂、脚本刷屏全靠自己挡。我的方案分三层。
第一层是频率限制。用 Upstash Redis 存一个计数器，IP + snippetId维度下，10 分钟最多评论 10 条。对正常用户完全无感，但脚本刷屏会被卡死。
const key = `rate:comment:${snippetId}:${ip}`; const count = await redis.incr(key); if (count > 10) { throw new TRPCError({ code: "TOO_MANY_REQUESTS" }); } await redis.expire(key, 600);第二层是内容过滤。简单关键词列表直接拦截，比如明显广告词、色情词。这块不追求完美，能挡住 90% 的无脑广告就行。注意不要对中文关键词做严格的全词匹配，中文分词和变体太复杂，宁可多误杀一点。
第三层是举报机制。任何评论都可以点举报，二次确认后标记spam，用户自己可以选择隐藏垃圾评论。我不会直接删帖，因为误判也是一次弱权力行为，留出申诉通道更稳妥。
再往上的方案是接入第三方内容安全服务，很多企业级工具都这么干。但 t3code 的核心是非营利小项目，我用频率限制 + 关键词 + 举报三层已经足够。这一点我认为是个人独立项目最务实的做法。
5. 部署与后期运维：Vercel 不适合一切
5.1 部署方案：Docker + 云服务器
t3code 刚完成时，我毫不犹豫就部署到了 Vercel，因为它和 Next.js 配合确实简单。跑了不到一周就发现问题：Vercel 的 serverless 函数冷启动对于 tRPC 这种高频小请求太不友好了。代码片段保存、评论、查询，这些都是毫秒级的小接口，但冷启动动不动就 300ms 甚至到 1s，体验直接崩坏。
于是我把 t3code 迁到一台 2C4G 的云服务器上，用 Docker Compose 跑三个容器：应用、PostgreSQL、Redis。配置文件大概是这个样子：
services: web: build: . ports: - "3000:3000" environment: DATABASE_URL: postgres://user:pass@postgres:5432/t3code REDIS_URL: redis://redis:6379 depends_on: - postgres - redis restart: unless-stopped healthcheck: test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"] interval: 30s retries: 3 postgres: image: postgres:16-alpine volumes: - pgdata:/var/lib/postgresql/data restart: unless-stopped redis: image: redis:7-alpine restart: unless-stopped最让我意外的是，Docker 部署过程中最大的坑不是容器网络，而是Node.js 原生模块在 Alpine 镜像下的编译。bcrypt、sharp这些带原生 binding 的依赖，在node:20-alpine里经常没有预编译二进制，需要现场编译，没有 build tools 就直接失败。我最后直接用 Debian 版本的 node 镜像，虽然镜像体积大了两百兆，但省了无数折腾时间。如果只是小项目自己用，别跟 Alpine 硬刚，性价比不高。
5.2 监控数据、错误上报
应用的监控我分两层：基础设施层和应用层。基础设施层用uptime-kuma做 HTTP 探活，每 60 秒探测一次/api/health，服务挂了就推送到 Telegram。应用层用 Sentry，前后端都接。这个组合基本无需花钱，个人项目承载一两万日活没什么压力。
Sentry 的接入需要注意一个点：sourcemap 上传要做隐私过滤。因为 t3code 的客户端产物包含源码映射，直接上传会把后端路由路径、注释、环境变量名都暴露出来。我在sentry.client.config.ts里限制了上传范围，只保留src/pages和src/components等前端代码，不让服务端 router 的源码 map 泄漏到前端。
还有，数据库连接池大小要单独说。我一开始没配Prisma的连接池上限，默认连接池是 CPU 核数的num_cpus * 2 + 1，这台 2C4G 的机器的默认值是 5。并发一旦上来，连接池满了，就直接导致应用假死。后来我把DATABASE_URL换成pgbouncer中转，同时把 Prisma 连接池大小设为 3。注意这个数字不是越大越好，PostgreSQL 默认最大连接数才 100，每个应用实例分太多，多个服务一挤就挂了。
5.3 迁移、备份、SEO 静态生成细节
数据备份我写了个 cron 任务，每天凌晨 3 点执行pg_dump备份全库，压缩后传到对象存储，保留最近 30 份。第一次做数据恢复演练时我才发现备份能不能用全靠演练，所以又加了一条自动化脚本：每月 1 号自动把最新备份恢复到本地测试库，如果恢复失败就发告警通知。
SEO 方面，公开的 snippet 页面向搜索引擎开放，unlisted和private页面在robotsmeta 里禁止索引。这个不要写在robots.txt里，因为robots.txt是站点级别的，如果 unlisted 链接避免了搜索引擎爬虫，那么所有页面都会被禁。正确做法是在页面渲染时的metadata里动态设置robots: noindex：
export const metadata: Metadata = { robots: { index: false, follow: false, }, };另外，Next.js 14 之后metadata是异步解析接口，如果直接在 Server Component 里 return 普通对象会丢。我因为这个在 t3code 的 snippet 详情页折腾了大半个晚上，最后看类型定义才发现metadata需要返回Promise<Metadata>或直接同步Metadata，但访问动态路由参数时要用generateMetadata。这是框架细节，但它直接影响 SEO 效果，值得记一笔。
注意：不要把
/api前缀路径交给 Next.js 的默认缓存。tRPC 的请求都走这个前缀，如果需要缓存，请在 tRPC 调用层用 React Query 的staleTime控制，而不是去开 HTTP 层缓存，否则用户登录态会非常容易串。
6. 上线三个月，我复盘出的几条经验
t3code 从动工到上线差不多用了两周，前两周数据增长不快，但后面慢慢在公司内部有了二十几个活跃用户。这个过程让我对"独立开发全栈工具"有了几层新的认知。
第一，类型安全不是银弹，但它能帮你砍掉一整类 bug。t3code 上线三个月，前后端接口字段不一致导致的线上故障基本为零。这在 REST 时代几乎不可能，尤其是像"片段标签""评论用户"这种嵌套结构，光手写类型就容易错到怀疑人生。
第二，数据库 schema 改起来远比功能新增痛苦。我前面说的tags从数组改关联表，就让我重写了搜索逻辑、导入导出逻辑、统计逻辑三块代码。如果你的工具也涉及代码片段这种天然多标签的数据，一开始就老老实实建关联表，别图省事。
第三，没有所谓的最佳实践，只有对场景的取舍。T3 Stack 教会我的不是框架用法，而是"把什么放在哪一层"的判断力。代码高亮放到后端渲染成快照、搜索双轨制、频率限制放 Redis 而不是数据库、匿名评论配合举报机制……这些东西没写在任何官方文档里，但在真实跑完流量之后，你自然会知道哪里需要加固。
如果你也想做一个类似的代码片段管理工具，我的建议是：先按照 t3code 的最小链路跑通一条，再回头去补权限、索引和监控。把公开分享、搜索、标签这三件事做好，就已经超越了大多数满地跑的"代码笔记"应用。剩下的，就让时间和真实用户帮你做决策吧。
