：構建類型安全的代碼片段管理工具與Serverless部署)
我最近在維護一個叫 t3code 的小項目最初真的只是圖自己查代碼方便寫過的訂單狀態(tài)機、文件上傳分片、SSE 重連邏輯散落在三四個倉庫、幾百個 Markdown 筆記里還有不少躺在聊天記錄中。等下次要用的時候翻聊天記錄比重新寫一遍還痛苦。后來我干脆用 T3 Stack 把它做成一個代碼片段管理工具后端、前端、鑒權、數(shù)據庫全走一套 TypeScript 類型系統(tǒng)從錄入到檢索再到分享形成閉環(huán)。t3code 這個名字沒啥花哨含義技術棧是 T3業(yè)務是做 code snippet 的管理合在一起就是它。如果你也在做類似的全棧工具或者想找一個能真正練手 T3 Stack 的場景這篇文章比較適合你。我會把項目從立項到上線的完整思路寫清楚包括技術選型為什么這么定、數(shù)據庫模型怎么設計、tRPC 接口怎么組織以及部署到 Serverless 環(huán)境后踩過的幾個坑。項目本身不大但覆蓋的點很全很多問題都是真實跑過之后才發(fā)現(xiàn)的。1. 為什么做 t3code團隊里缺的不是代碼是能檢索到的代碼1.1 需求的起點片段散落在飛書、IDE、聊天記錄里先說背景。我所在的小組經常處理相似的業(yè)務邏輯比如根據用戶等級計算折扣、導出大 Excel 時控制內存峰值、定時任務里做冪等去重。這些邏輯每個項目都略有不同但核心思路一致。按道理應該沉淀成公共代碼片段但實際情況是老項目的代碼還在倉庫里但沒人記得具體是哪個文件有人把片段貼到飛書文檔里文檔權限混亂沒做過全文索引個人 IDE 的 snippet 只能自己用換個電腦就沒了偶爾有人分享 Gist但 Gist 默認是公開的稍微帶點內部邏輯就沒人敢發(fā)。所以我希望 t3code 能解決幾個很具體的問題錄入一個片段后一秒鐘之內能按語言、標簽、關鍵詞定位到它片段可以標記為私有也可以生成分享鏈接給同事每個片段附帶簡述和使用注意點這樣半年后看也不會一臉懵。做產品的人會立刻想到這不就是又一個 Gist 嗎對也不對。Gist 更適合公開小代碼團隊內部用有兩個硬傷一是沒有“代碼片段庫”的目錄感二是搜索能力很弱。我要做的是面向團隊內部少量人使用的私有工具核心不是“發(fā)出去”而是“存下來、找得到”。需求定位清楚后項目邊界也順勢定了暫不做代碼運行評測、不做多端離線同步、不做復雜的權限體系先把“增刪改查 全文檢索 分享”這條主鏈路打穿。1.2 為什么項目要叫 t3codeT3 Stack 這個組合在 TypeScript 圈子里不算陌生Next.js 做應用框架tRPC 做端到端類型安全的 API 層Tailwind 管樣式Prisma 管數(shù)據庫NextAuth 做鑒權底層全部由 TypeScript 串起來。因為 t3code 本質上服務于“代碼”而且所有數(shù)據都是純文本非常適合用這套技術棧快速驗證。在正式動手之前我也考慮過其他方案純 Next.js REST API需要在前后端各寫一套類型定義接口一多很容易兩邊不同步Next.js GraphQL類型安全很爽但 GraphQL 的學習成本和服務器復雜度對這個體量的項目偏高用現(xiàn)成的開源服務如 Outline、Docmost功能確實強但定制成本不低而且很多都假設你有自建基礎設施的前提。t3code 選擇 T3 Stack 的核心邏輯其實只有一句話讓類型從數(shù)據庫一路流到 UI中間不需要我手動維護任何 API 契約。這個“不手動維護”在幾十個片段的時候感受不明顯一旦接口數(shù)量膨脹到幾十上百個優(yōu)勢非常明顯。后面我會具體講 tRPC 是怎么做到這一點。2. t3code 的核心選型T3 Stack 五件套怎么搭才不浪費2.1 用 create-t3-app 一分鐘初始化項目T3 Stack 的官方腳手架是 create-t3-app它和別的腳手架最大區(qū)別是會讓你交互式勾選組件而不是一股腦全裝。我初始化 t3code 的命令是pnpm dlx create-t3-applatest t3code接下來選擇時我勾了 Next.js App Router、TypeScript、Tailwind CSS、tRPC、Prisma、NextAuth.js、ESLint 和 Prettier。這里有兩個選擇值得說明第一App Router 是 Next.js 近兩年的主線方向雖然服務端組件和客戶端組件的邊界需要一點時間適應但新項目沒有歷史包袱直接用是最省的。第二數(shù)據庫層面我建議先用 SQLite 起步。t3code 在開發(fā)階段數(shù)據量很小SQLite 不需要額外起服務file:./db.sqlite就能跑。等需要部署到 Serverless 環(huán)境時再切換到 PostgreSQL這個切換我在后面部署章節(jié)詳細說。腳手架初始化完以后目錄結構大概是這樣的t3code/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── app/ │ ├── server/ │ │ ├── api/ │ │ │ ├── root.ts │ │ │ └── routers/ │ │ └── db.ts │ └── trpc/ │ ├── server.ts │ └── react.tsx ├── .env ├── package.json └── next.config.jscreate-t3-app 默認已經幫你配好了 Prisma Client 單例在src/server/db.ts、tRPC 的 server 和 react 兩套入口、NextAuth 的初始化骨架。所以第一分鐘你不需要理解所有細節(jié)只需要知道每個文件是干什么的然后往里填業(yè)務即可。2.2 五件套各自的職責與取舍很多初學者會問tRPC 和 REST、GraphQL 到底差在哪用一句話概括REST 是“接口即約定”GraphQL 是“查詢即約定”tRPC 是“函數(shù)即約定”。你不需要寫 OpenAPI 文檔不需要手寫請求類型前端拿到的就是和后端定義一致的 TypeScript 類型。我整理了 t3code 用到的五個核心組件以及它們各自承擔的職責組件在 t3code 里的角色我為什么選它Next.js App Router頁面結構、路由、服務端渲染一個框架同時覆蓋前端和后端接口部署模型簡單TypeScript全鏈路類型檢查數(shù)據庫返回類型可以一直穿透到組件減少低級錯誤tRPC前后端 API 層無需維護接口文檔新增查詢就自動暴露給前端Prisma數(shù)據庫訪問層schema 即文檔遷移和改表都很直觀NextAuth登錄與會話和 tRPC context 融合度高Google/GitHub 登錄開箱即用Tailwind CSSUI 樣式寫小工具類不需要切到 css 文件找樣式上下文這里我想特別強調一下 tRPC 的一個使用原則不要為了 tRPC 把所有邏輯都塞到 API 層。在 t3code 里list、create、update、delete這些需要持久化的操作走 tRPC mutation/query 沒問題但像“把 Markdown 轉成 HTML”“高亮代碼”這類純計算應該放在服務端渲染階段或者獨立工具函數(shù)里不要讓客戶端每次都調一次接口。這樣能讓 tRPC 接口保持精簡也不容易產生額外網絡請求。2.3 環(huán)境準備里最容易被忽略的版本問題如果你打算照著復現(xiàn) t3code環(huán)境版本最好先固定一批Node.js 20 LTS 及以上 pnpm 8 及以上 Prisma 6.x Next.js 14.2 及以上 TypeScript 5.x最容易翻車的是兩個地方。一個是pnpm版本和 Next.js 的依賴解析方式偶發(fā)會出現(xiàn).pnpm目錄下包路徑不對的問題最常見的解決辦法是rm -rf node_modules pnpm install重新裝一遍不要盲目升級大版本。另一個是 Tailwind CSS 和 PostCSS 的兼容如果你拉到的腳手架版本比較舊注意看tailwind.config.ts里的content是否把src/**/*.tsx和src/**/*.ts都包含進去漏掉某一個目錄很可能導致樣式時有時無。環(huán)境變量方面create-t3-app 會生成一份.env.example我復制成.env后做了這樣幾項配置# 開發(fā)數(shù)據庫 DATABASE_URLfile:./db.sqlite # NextAuth 相關本地隨便填個足夠長的隨機字符串 NEXTAUTH_SECRETlocal-dev-secret-change-me NEXTAUTH_URLhttp://localhost:3000這兩行看起來簡單但它們決定了后續(xù)很多坑的方向NEXTAUTH_SECRET 不一致會導致生產環(huán)境登錄會話失效DATABASE_URL 不區(qū)分開發(fā)和生產會導致誤操作到真實數(shù)據庫。建議從開發(fā)第一天就把環(huán)境變量按環(huán)境切分不要圖省事只用一個。3. 數(shù)據庫模型與 tRPC 接口端到端類型安全的完整落地過程3.1 schema.prisma 設計片段、標簽、用戶的關系t3code 的業(yè)務對象其實不復雜用戶、代碼片段、標簽、收藏夾。但關系設計上我做了幾個刻意選擇寫出來給你參考。model User { id String id default(cuid()) name String? email String? unique snippets Snippet[] collections Collection[] } model Snippet { id String id default(cuid()) title String content String db.Text language String description String? isPublic Boolean default(false) createdAt DateTime default(now()) updatedAt DateTime updatedAt authorId String author User relation(fields: [authorId], references: [id], onDelete: Cascade) tags Tag[] collections Collection[] } model Tag { id String id default(cuid()) name String unique snippets Snippet[] } model Collection { id String id default(cuid()) name String userId String user User relation(fields: [userId], references: [id], onDelete: Cascade) snippets Snippet[] }幾個設計點解釋一下主鍵我沒有用自增整數(shù)而是用cuid()。原因有兩個一是避免通過 ID 猜測系統(tǒng)里有多少條片段二是未來要擴展多節(jié)點寫入時cuid 沖突概率遠低于自增 IDSnippet的isPublic默認是false也就是說默認所有片段都只有自己可見分享是主動行為。這個設計保證了“貼代碼”這個行為的心理門檻足夠低不會因為怕泄露而干脆不記Tag的 name 設置成unique新建片段時如果是已有標簽就直接關聯(lián)不重復建標簽Collection相當于用戶自建的文件夾和Tag的區(qū)別在于它有明確的用戶歸屬只有自己能增刪里面放了哪些片段。寫完 schema 后執(zhí)行npx prisma migrate dev --name init npx prisma generatemigrate dev會生成遷移文件并同步更新數(shù)據庫generate會生成 TypeScript 客戶端類型。這一步做完你就能在編輯器里體會到 Prisma 類型提示的好處——比如寫錯了字段名保存的瞬間就會標紅。3.2 tRPC Router 的代碼骨架t3code 的接口層主要分成兩部分一部分處理片段列表和詳情一部分處理片段的新增、修改、刪除。以新增片段為例我的snippetrouter 是這樣的// src/server/api/routers/snippet.ts import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure, } from ~/server/api/trpc; const createSnippetSchema z.object({ title: z.string().min(1, 標題不能為空), content: z.string().min(1, 代碼內容不能為空), language: z.string().min(1), description: z.string().optional(), tagNames: z.array(z.string()).default([]), isPublic: z.boolean().default(false), }); export const snippetRouter createTRPCRouter({ list: publicProcedure .input( z.object({ language: z.string().optional(), tag: z.string().optional(), keyword: z.string().optional(), }) ) .query(async ({ ctx }) { return ctx.db.snippet.findMany({ where: { OR: [{ isPublic: true }, { authorId: ctx.session?.user?.id }], }, include: { tags: true, author: { select: { name: true } }, }, orderBy: { createdAt: desc }, }); }), create: protectedProcedure .input(createSnippetSchema) .mutation(async ({ ctx, input }) { const tagNames [...new Set(input.tagNames.map((t) t.trim()))]; const tagConnections tagNames.map((name) ({ name })); return ctx.db.snippet.create({ data: { title: input.title, content: input.content, language: input.language, description: input.description, isPublic: input.isPublic, authorId: ctx.session.user.id, tags: { connectOrCreate: tagConnections.map((tag) ({ where: { name: tag.name }, create: { name: tag.name }, })), }, }, }); }), });這里最有價值的部分是connectOrCreate。它做的事是如果標簽已存在就直接關聯(lián)如果不存在就順便創(chuàng)建一條。這比“先查標簽再創(chuàng)建”少了一次網絡往返而且代碼更簡潔。再解釋一下publicProcedure和protectedProcedure的差別publicProcedure允許未登錄用戶訪問列表里公開的片段protectedProcedure要求必須有登錄會話在中間件里會校驗ctx.session拿不到就拋UNAUTHORIZED。t3code 里所有寫操作都應該是登錄后行為所以統(tǒng)一用protectedProcedure。3.3 前端組件怎么調用 tRPCt3code 的前端采用“列表頁用服務端組件交互區(qū)用客戶端組件”的混合模式。這樣做的原因是列表數(shù)據對 SEO 要求不高但首屏希望盡快看到內容而新增、編輯這種交互必須由客戶端觸發(fā)。在客戶端組件里調用 tRPC 的寫法是use client; import { api } from ~/trpc/react; export function SnippetList() { const [list] api.snippet.list.useSuspenseQuery({}); return ( ul {list.map((item) ( li key{item.id} code{item.language}/code p{item.title}/p /li ))} /ul ); }如果你使用useSuspenseQuery需要配合Suspense邊界使用否則頁面會一直轉圈。如果不想用 Suspense也可以換成useQuery但就要自己處理 loading 和 error 狀態(tài)。新增片段之后想讓列表刷新不必去 reload 頁面tRPC 提供了緩存失效機制const utils api.useUtils(); await api.snippet.create.mutateAsync({ title: form.title, content: form.content, language: form.language, tagNames: form.tags, }); utils.snippet.list.invalidate();invalidate會把 tRPC 內部緩存的list查詢標記為過期下次渲染時自動重新請求。這里有個常見誤解invalidate是異步的但你不一定要await它。如果不關心列表是否立刻刷新就讓它自己跑如果你希望列表馬上是最新建議await utils.snippet.list.invalidate()等它會話再給用戶反饋。4. 真實踩坑復盤連接池、緩存與中間件的三連擊4.1 坑一開發(fā)環(huán)境一切正常部署后偶發(fā) 500t3code 在本地跑了一個多月都沒問題Schema 改過五六次數(shù)據也建了不少。結果一部署到 Vercel隔三差五就報PrismaClientInitializationError錯誤信息大致是PrismaClientInitializationError: P1001: Cant reach database server at ...第一次看到這個報錯我以為是連接串寫錯了反復檢查了十幾遍都沒問題。后來才意識到問題不在連接串而在 Serverless 的實例生命周期Vercel 的每個請求可能由不同的運行實例處理如果每次實例啟動都創(chuàng)建新的 PrismaClient短時間內會打爆數(shù)據庫連接數(shù)。本地開發(fā)因為是一個長駐進程所以永遠觸發(fā)不了這個問題。標準解法是讓 PrismaClient 復用同一個實例。create-t3-app 已經預設了這么一段代碼但你得確認它真的生效了// src/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; }這段代碼的思路很簡單開發(fā)環(huán)境熱更新可能會導致模塊重復加載所以把實例掛到globalThis上生產環(huán)境雖然不掛但每個 Serverless 實例內部還是會盡量復用。如果走到這里還偶發(fā) 500那就不是單例問題而是數(shù)據庫連接池容量問題。我最終換成了 PostgreSQL 的池化連接參數(shù)DATABASE_URLpostgresql://user:passwordhost:5432/t3code?pgbouncertrue加上pgbouncertrue后Prisma 會知道你的連接走的是 PgBouncer從而限制連接存活時間避免連接耗盡。4.2 坑二tRPC 查詢結果像是被“緩存”了上線后有個現(xiàn)象很奇怪新增一個片段列表不更新刷新頁面也不一定有要過幾秒或者再刷新一次才能看到。一開始我懷疑是 tRPC 緩存于是加了一堆invalidate仍然沒有根治。后來我把問題拆開排查鏈路是這樣的第一步直接查數(shù)據庫確認數(shù)據已經寫入了 —— 數(shù)據庫沒問題第二步在瀏覽器里直接訪問 tRPC 的接口地址返回的結果是最新的 —— 后端接口沒問題第三步看頁面請求 Load 面板發(fā)現(xiàn)頁面根本沒有發(fā)新的 tRPC 請求 —— 問題出在前端。再深挖發(fā)現(xiàn)是 Next.js App Router 的客戶端 Router Cache 在起作用。Next.js 會把 RSC Payload 緩存到客戶端如果你的頁面沒有顯式聲明動態(tài)渲染它可能把數(shù)據當作靜態(tài)內容緩存住。舉個例子我在app/snippets/page.tsx里沒有加任何動態(tài)標記Next.js 可能把首次請求的結果緩存下來之后從緩存里取。解決方式有三種按推薦程度排序在相關的 route 上加export const dynamic force-dynamic;這告訴 Next.js 這個路由每次請求都動態(tài)渲染不做靜態(tài)緩存。在調用list的頁面或布局中讀取 cookies 或 headers 這樣的動態(tài) APINext.js 會自動把它標記為動態(tài)渲染。mutation 完成后調用router.refresh()強制刷新當前路由的服務端組件數(shù)據。這個命令在 App Router 里很實用但它會刷新整個路由代價比invalidate大。最終我把動態(tài)渲染標記加到了片段詳情頁而列表頁保留了一部分靜態(tài)緩存只對“最近更新”區(qū)域做動態(tài)刷新。這樣即保證了新數(shù)據能出現(xiàn)又不會每個請求都重新渲染整棵樹。4.3 坑三NextAuth 的 session 在 tRPC context 里拿不到這個坑讓我印象最深。t3code 在本地登錄沒問題但部署到 Vercel 之后凡是protectedProcedure都報未授權。登錄接口本身正常瀏覽器里能看到 session cookie但到 tRPC 的 context 里getServerSession拿到了null。排查時我一度懷疑是 cookie 跨域問題后來把環(huán)境變量逐行對比發(fā)現(xiàn)問題出在NEXTAUTH_SECRET本地的.env和生產環(huán)境的 Vercel 環(huán)境變量里存了不同的值。NextAuth 的 session 是加密簽名的如果部署后的 secret 和登錄時不一致服務端就無法驗證 session 的合法性。這在本地不會發(fā)生因為本地永遠只有一套配置。另一個容易忽視的點是 tRPC context 的寫法。在 create-t3-app 的新版本里服務端渲染場景下你需要確保 context 里拿到的是同一個 session 對象。我的最終代碼是這樣// src/server/api/trpc.ts import { initTRPC, TRPCError, } from trpc/server; import { getServerSession } from next-auth; import { authOptions } from ~/server/auth; import { db } from ~/server/db; export const createTRPCContext async () { const session await getServerSession(authOptions); return { db, session }; }; const t initTRPC.contexttypeof createTRPCContext().create(); export const createTRPCRouter t.router; export const publicProcedure t.procedure; const enforceUserIsAuthed t.middleware(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { session: { ...ctx.session, user: ctx.session.user }, }, }); }); export const protectedProcedure t.procedure.use(enforceUserIsAuthed);這里的關鍵是 middleWare 會把 session 解構后傳給下一個中間件保證后續(xù)邏輯中一定存在ctx.session.user。如果你的 context 里session本身就是null那直接再看 session 來源是不是 NextAuth 的authOptions沒有正確配置 provider先解決登錄問題再排查 tRPC。我把這三個坑整理成了一張自查表方便你踩雷時快速對照現(xiàn)象可能原因優(yōu)先檢查部署后偶發(fā) 500PrismaClient 被反復創(chuàng)建 / 連接池耗盡全局單例、池化連接參數(shù)新增數(shù)據后頁面不刷新Next.js Router Cache / tRPC 緩存未失效動態(tài)渲染標記、invalidate、router.refresh()所有受保護接口報未授權NEXTAUTH_SECRET 不一致 / session 獲取失敗環(huán)境變量、getServerSession的前后一致性5. 部署到生產環(huán)境的細節(jié)與后續(xù)優(yōu)化5.1 首次部署環(huán)境變量與 migrate 流程t3code 的部署目標選了 Vercel因為 Next.js 項目在 Vercel 上基本零配置。不過這并不代表沒有注意點。首次部署時我踩了這樣一個流程坑在本地建好了 SQLite 數(shù)據庫代碼推上去之后遠程環(huán)境照樣連不上數(shù)據庫。原因很簡單Vercel 的 Serverless 文件系統(tǒng)是只讀的SQLite 這種單文件數(shù)據庫根本沒法持久化。所以生產環(huán)境必須換成 PostgreSQL。我的遷移步驟是這樣的在 Supabase 或 Neon 上創(chuàng)建一個 PostgreSQL 實例拿到連接串本地schema.prisma確認provider postgresql重新生成遷移文件執(zhí)行npx prisma migrate deploy在生產數(shù)據庫上執(zhí)行遷移在 Vercel 項目設置里配置三個環(huán)境變量DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL部署后訪問/api/auth/session確認登錄會話正常。這里必須強調一個和本地開發(fā)的差異本地開發(fā)時我習慣直接用prisma db push同步 schema因為它不產生遷移文件改表速度快。但生產環(huán)境千萬別用db push一是它不可追溯二是多人協(xié)作時沒人知道數(shù)據庫到底被誰改過。規(guī)范的做法是prisma migrate deploy它會按遷移文件順序執(zhí)行保證每個環(huán)境的結構一致。5.2 性能與資源控制小項目也要有優(yōu)化的意識t3code 的數(shù)據量短時間內不會很大但我在寫的時候還是埋了幾個優(yōu)化點免得以后改起來傷筋動骨。第一個是列表分頁。目前的list接口直接返回全部片段量大了會有兩個問題網絡包變大、數(shù)據庫查詢變慢。我給list加上了cursor分頁模式list: publicProcedure .input( z.object({ cursor: z.string().optional(), take: z.number().max(50).default(20), }) ) .query(async ({ ctx, input }) { return ctx.db.snippet.findMany({ take: input.take 1, cursor: input.cursor ? { id: input.cursor } : undefined, orderBy: { createdAt: desc }, }); }),take: input.take 1是判斷是否還有下一頁的技巧如果返回的記錄數(shù)大于take就說明還有下一頁前端再把最后一條記錄的 id 作為 cursor 繼續(xù)拉。第二個是代碼高亮。t3code 里片段內容可能比較長如果在前端引入一個重量級高亮庫首屏會明顯變慢。我選擇把高亮邏輯放到服務端來做用 Shiki 在頁面渲染時把代碼轉成帶樣式類名的 HTML前端只負責展示。這樣用戶的瀏覽器不加載高亮庫代碼高亮也不會閃爍。第三個是全文搜索。小項目階段用 Prisma 的contains勉強夠用where: { OR: [ { title: { contains: keyword } }, { content: { contains: keyword } }, ], }但超過幾千條之后contains的性能就會開始捉急。如果后續(xù)集成真正的全文檢索我會優(yōu)先考慮 PostgreSQL 的pg_trgm擴展再進一步才會上獨立的搜索引擎。這些都不用現(xiàn)在做但 schema 和接口層面要預留好擴展點別把自己寫死。5.3 后續(xù)規(guī)劃從“自用工具”到“團隊可用平臺”t3code 現(xiàn)在滿足了我的核心訴求快速記錄、快速檢索、可分享。但你要說它是個好產品還差得遠。我自己整理的后續(xù)優(yōu)化方向大致有三塊第一體驗層面的補充分享鏈接支持有效期過期后自動失效片段支持 Fork也就是在別人公開片段的基礎上另存一個自己的版本增加收藏夾的模糊搜索。第二數(shù)據層面的擴展把 Markdown 說明和代碼內容拆開支持下載 Markdown 文件快照提供瀏覽器擴展在 GitHub 或 GitLab 頁面上右鍵即可把選中代碼存入 t3code。第三工程層面的完善給 tRPC 接口加上請求日志和錯誤上報用 Playwright 寫幾條核心路徑的 e2e 測試把數(shù)據庫遷移流程 CI 化每次 schema 變更自動生成遷移文件。很多項目做到“自用 OK”就停了但如果你真的打算給團隊用穩(wěn)定性和數(shù)據安全就必須排在前面。比如片段內容對團隊可能是核心資產導出和刪除都必須有明確的操作記錄這些后續(xù)大概率得用一張 audit log 表來支撐。最后再分享一個我個人的操作習慣所有代碼片段錄入時強制要求填language和description兩個字段。前者是為了篩選方便后者是為了讓別人包括未來的自己能在一分鐘內理解這段代碼解決的是什么問題。這個習慣比任何技術選型都重要因為工具再順手也架不住你存進來的是沒有上下文的半成品。t3code 這個項目讓我真正體會到了“類型安全 統(tǒng)一錄入規(guī)范”帶來的長期價值也建議你從自己的高頻重復代碼開始先存它十個片段感受一下檢索效率的變化再做下一步功能的優(yōu)先級判斷。 T3 Stack實戰(zhàn)：構建類型安全的代碼片段管理工具與Serverless部署
我最近在維護一個叫 t3code 的小項目最初真的只是圖自己查代碼方便寫過的訂單狀態(tài)機、文件上傳分片、SSE 重連邏輯散落在三四個倉庫、幾百個 Markdown 筆記里還有不少躺在聊天記錄中。等下次要用的時候翻聊天記錄比重新寫一遍還痛苦。后來我干脆用 T3 Stack 把它做成一個代碼片段管理工具后端、前端、鑒權、數(shù)據庫全走一套 TypeScript 類型系統(tǒng)從錄入到檢索再到分享形成閉環(huán)。t3code 這個名字沒啥花哨含義技術棧是 T3業(yè)務是做 code snippet 的管理合在一起就是它。如果你也在做類似的全棧工具或者想找一個能真正練手 T3 Stack 的場景這篇文章比較適合你。我會把項目從立項到上線的完整思路寫清楚包括技術選型為什么這么定、數(shù)據庫模型怎么設計、tRPC 接口怎么組織以及部署到 Serverless 環(huán)境后踩過的幾個坑。項目本身不大但覆蓋的點很全很多問題都是真實跑過之后才發(fā)現(xiàn)的。1. 為什么做 t3code團隊里缺的不是代碼是能檢索到的代碼1.1 需求的起點片段散落在飛書、IDE、聊天記錄里先說背景。我所在的小組經常處理相似的業(yè)務邏輯比如根據用戶等級計算折扣、導出大 Excel 時控制內存峰值、定時任務里做冪等去重。這些邏輯每個項目都略有不同但核心思路一致。按道理應該沉淀成公共代碼片段但實際情況是老項目的代碼還在倉庫里但沒人記得具體是哪個文件有人把片段貼到飛書文檔里文檔權限混亂沒做過全文索引個人 IDE 的 snippet 只能自己用換個電腦就沒了偶爾有人分享 Gist但 Gist 默認是公開的稍微帶點內部邏輯就沒人敢發(fā)。所以我希望 t3code 能解決幾個很具體的問題錄入一個片段后一秒鐘之內能按語言、標簽、關鍵詞定位到它片段可以標記為私有也可以生成分享鏈接給同事每個片段附帶簡述和使用注意點這樣半年后看也不會一臉懵。做產品的人會立刻想到這不就是又一個 Gist 嗎對也不對。Gist 更適合公開小代碼團隊內部用有兩個硬傷一是沒有“代碼片段庫”的目錄感二是搜索能力很弱。我要做的是面向團隊內部少量人使用的私有工具核心不是“發(fā)出去”而是“存下來、找得到”。需求定位清楚后項目邊界也順勢定了暫不做代碼運行評測、不做多端離線同步、不做復雜的權限體系先把“增刪改查 全文檢索 分享”這條主鏈路打穿。1.2 為什么項目要叫 t3codeT3 Stack 這個組合在 TypeScript 圈子里不算陌生Next.js 做應用框架tRPC 做端到端類型安全的 API 層Tailwind 管樣式Prisma 管數(shù)據庫NextAuth 做鑒權底層全部由 TypeScript 串起來。因為 t3code 本質上服務于“代碼”而且所有數(shù)據都是純文本非常適合用這套技術棧快速驗證。在正式動手之前我也考慮過其他方案純 Next.js REST API需要在前后端各寫一套類型定義接口一多很容易兩邊不同步Next.js GraphQL類型安全很爽但 GraphQL 的學習成本和服務器復雜度對這個體量的項目偏高用現(xiàn)成的開源服務如 Outline、Docmost功能確實強但定制成本不低而且很多都假設你有自建基礎設施的前提。t3code 選擇 T3 Stack 的核心邏輯其實只有一句話讓類型從數(shù)據庫一路流到 UI中間不需要我手動維護任何 API 契約。這個“不手動維護”在幾十個片段的時候感受不明顯一旦接口數(shù)量膨脹到幾十上百個優(yōu)勢非常明顯。后面我會具體講 tRPC 是怎么做到這一點。2. t3code 的核心選型T3 Stack 五件套怎么搭才不浪費2.1 用 create-t3-app 一分鐘初始化項目T3 Stack 的官方腳手架是 create-t3-app它和別的腳手架最大區(qū)別是會讓你交互式勾選組件而不是一股腦全裝。我初始化 t3code 的命令是pnpm dlx create-t3-applatest t3code接下來選擇時我勾了 Next.js App Router、TypeScript、Tailwind CSS、tRPC、Prisma、NextAuth.js、ESLint 和 Prettier。這里有兩個選擇值得說明第一App Router 是 Next.js 近兩年的主線方向雖然服務端組件和客戶端組件的邊界需要一點時間適應但新項目沒有歷史包袱直接用是最省的。第二數(shù)據庫層面我建議先用 SQLite 起步。t3code 在開發(fā)階段數(shù)據量很小SQLite 不需要額外起服務file:./db.sqlite就能跑。等需要部署到 Serverless 環(huán)境時再切換到 PostgreSQL這個切換我在后面部署章節(jié)詳細說。腳手架初始化完以后目錄結構大概是這樣的t3code/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── app/ │ ├── server/ │ │ ├── api/ │ │ │ ├── root.ts │ │ │ └── routers/ │ │ └── db.ts │ └── trpc/ │ ├── server.ts │ └── react.tsx ├── .env ├── package.json └── next.config.jscreate-t3-app 默認已經幫你配好了 Prisma Client 單例在src/server/db.ts、tRPC 的 server 和 react 兩套入口、NextAuth 的初始化骨架。所以第一分鐘你不需要理解所有細節(jié)只需要知道每個文件是干什么的然后往里填業(yè)務即可。2.2 五件套各自的職責與取舍很多初學者會問tRPC 和 REST、GraphQL 到底差在哪用一句話概括REST 是“接口即約定”GraphQL 是“查詢即約定”tRPC 是“函數(shù)即約定”。你不需要寫 OpenAPI 文檔不需要手寫請求類型前端拿到的就是和后端定義一致的 TypeScript 類型。我整理了 t3code 用到的五個核心組件以及它們各自承擔的職責組件在 t3code 里的角色我為什么選它Next.js App Router頁面結構、路由、服務端渲染一個框架同時覆蓋前端和后端接口部署模型簡單TypeScript全鏈路類型檢查數(shù)據庫返回類型可以一直穿透到組件減少低級錯誤tRPC前后端 API 層無需維護接口文檔新增查詢就自動暴露給前端Prisma數(shù)據庫訪問層schema 即文檔遷移和改表都很直觀NextAuth登錄與會話和 tRPC context 融合度高Google/GitHub 登錄開箱即用Tailwind CSSUI 樣式寫小工具類不需要切到 css 文件找樣式上下文這里我想特別強調一下 tRPC 的一個使用原則不要為了 tRPC 把所有邏輯都塞到 API 層。在 t3code 里list、create、update、delete這些需要持久化的操作走 tRPC mutation/query 沒問題但像“把 Markdown 轉成 HTML”“高亮代碼”這類純計算應該放在服務端渲染階段或者獨立工具函數(shù)里不要讓客戶端每次都調一次接口。這樣能讓 tRPC 接口保持精簡也不容易產生額外網絡請求。2.3 環(huán)境準備里最容易被忽略的版本問題如果你打算照著復現(xiàn) t3code環(huán)境版本最好先固定一批Node.js 20 LTS 及以上 pnpm 8 及以上 Prisma 6.x Next.js 14.2 及以上 TypeScript 5.x最容易翻車的是兩個地方。一個是pnpm版本和 Next.js 的依賴解析方式偶發(fā)會出現(xiàn).pnpm目錄下包路徑不對的問題最常見的解決辦法是rm -rf node_modules pnpm install重新裝一遍不要盲目升級大版本。另一個是 Tailwind CSS 和 PostCSS 的兼容如果你拉到的腳手架版本比較舊注意看tailwind.config.ts里的content是否把src/**/*.tsx和src/**/*.ts都包含進去漏掉某一個目錄很可能導致樣式時有時無。環(huán)境變量方面create-t3-app 會生成一份.env.example我復制成.env后做了這樣幾項配置# 開發(fā)數(shù)據庫 DATABASE_URLfile:./db.sqlite # NextAuth 相關本地隨便填個足夠長的隨機字符串 NEXTAUTH_SECRETlocal-dev-secret-change-me NEXTAUTH_URLhttp://localhost:3000這兩行看起來簡單但它們決定了后續(xù)很多坑的方向NEXTAUTH_SECRET 不一致會導致生產環(huán)境登錄會話失效DATABASE_URL 不區(qū)分開發(fā)和生產會導致誤操作到真實數(shù)據庫。建議從開發(fā)第一天就把環(huán)境變量按環(huán)境切分不要圖省事只用一個。3. 數(shù)據庫模型與 tRPC 接口端到端類型安全的完整落地過程3.1 schema.prisma 設計片段、標簽、用戶的關系t3code 的業(yè)務對象其實不復雜用戶、代碼片段、標簽、收藏夾。但關系設計上我做了幾個刻意選擇寫出來給你參考。model User { id String id default(cuid()) name String? email String? unique snippets Snippet[] collections Collection[] } model Snippet { id String id default(cuid()) title String content String db.Text language String description String? isPublic Boolean default(false) createdAt DateTime default(now()) updatedAt DateTime updatedAt authorId String author User relation(fields: [authorId], references: [id], onDelete: Cascade) tags Tag[] collections Collection[] } model Tag { id String id default(cuid()) name String unique snippets Snippet[] } model Collection { id String id default(cuid()) name String userId String user User relation(fields: [userId], references: [id], onDelete: Cascade) snippets Snippet[] }幾個設計點解釋一下主鍵我沒有用自增整數(shù)而是用cuid()。原因有兩個一是避免通過 ID 猜測系統(tǒng)里有多少條片段二是未來要擴展多節(jié)點寫入時cuid 沖突概率遠低于自增 IDSnippet的isPublic默認是false也就是說默認所有片段都只有自己可見分享是主動行為。這個設計保證了“貼代碼”這個行為的心理門檻足夠低不會因為怕泄露而干脆不記Tag的 name 設置成unique新建片段時如果是已有標簽就直接關聯(lián)不重復建標簽Collection相當于用戶自建的文件夾和Tag的區(qū)別在于它有明確的用戶歸屬只有自己能增刪里面放了哪些片段。寫完 schema 后執(zhí)行npx prisma migrate dev --name init npx prisma generatemigrate dev會生成遷移文件并同步更新數(shù)據庫generate會生成 TypeScript 客戶端類型。這一步做完你就能在編輯器里體會到 Prisma 類型提示的好處——比如寫錯了字段名保存的瞬間就會標紅。3.2 tRPC Router 的代碼骨架t3code 的接口層主要分成兩部分一部分處理片段列表和詳情一部分處理片段的新增、修改、刪除。以新增片段為例我的snippetrouter 是這樣的// src/server/api/routers/snippet.ts import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure, } from ~/server/api/trpc; const createSnippetSchema z.object({ title: z.string().min(1, 標題不能為空), content: z.string().min(1, 代碼內容不能為空), language: z.string().min(1), description: z.string().optional(), tagNames: z.array(z.string()).default([]), isPublic: z.boolean().default(false), }); export const snippetRouter createTRPCRouter({ list: publicProcedure .input( z.object({ language: z.string().optional(), tag: z.string().optional(), keyword: z.string().optional(), }) ) .query(async ({ ctx }) { return ctx.db.snippet.findMany({ where: { OR: [{ isPublic: true }, { authorId: ctx.session?.user?.id }], }, include: { tags: true, author: { select: { name: true } }, }, orderBy: { createdAt: desc }, }); }), create: protectedProcedure .input(createSnippetSchema) .mutation(async ({ ctx, input }) { const tagNames [...new Set(input.tagNames.map((t) t.trim()))]; const tagConnections tagNames.map((name) ({ name })); return ctx.db.snippet.create({ data: { title: input.title, content: input.content, language: input.language, description: input.description, isPublic: input.isPublic, authorId: ctx.session.user.id, tags: { connectOrCreate: tagConnections.map((tag) ({ where: { name: tag.name }, create: { name: tag.name }, })), }, }, }); }), });這里最有價值的部分是connectOrCreate。它做的事是如果標簽已存在就直接關聯(lián)如果不存在就順便創(chuàng)建一條。這比“先查標簽再創(chuàng)建”少了一次網絡往返而且代碼更簡潔。再解釋一下publicProcedure和protectedProcedure的差別publicProcedure允許未登錄用戶訪問列表里公開的片段protectedProcedure要求必須有登錄會話在中間件里會校驗ctx.session拿不到就拋UNAUTHORIZED。t3code 里所有寫操作都應該是登錄后行為所以統(tǒng)一用protectedProcedure。3.3 前端組件怎么調用 tRPCt3code 的前端采用“列表頁用服務端組件交互區(qū)用客戶端組件”的混合模式。這樣做的原因是列表數(shù)據對 SEO 要求不高但首屏希望盡快看到內容而新增、編輯這種交互必須由客戶端觸發(fā)。在客戶端組件里調用 tRPC 的寫法是use client; import { api } from ~/trpc/react; export function SnippetList() { const [list] api.snippet.list.useSuspenseQuery({}); return ( ul {list.map((item) ( li key{item.id} code{item.language}/code p{item.title}/p /li ))} /ul ); }如果你使用useSuspenseQuery需要配合Suspense邊界使用否則頁面會一直轉圈。如果不想用 Suspense也可以換成useQuery但就要自己處理 loading 和 error 狀態(tài)。新增片段之后想讓列表刷新不必去 reload 頁面tRPC 提供了緩存失效機制const utils api.useUtils(); await api.snippet.create.mutateAsync({ title: form.title, content: form.content, language: form.language, tagNames: form.tags, }); utils.snippet.list.invalidate();invalidate會把 tRPC 內部緩存的list查詢標記為過期下次渲染時自動重新請求。這里有個常見誤解invalidate是異步的但你不一定要await它。如果不關心列表是否立刻刷新就讓它自己跑如果你希望列表馬上是最新建議await utils.snippet.list.invalidate()等它會話再給用戶反饋。4. 真實踩坑復盤連接池、緩存與中間件的三連擊4.1 坑一開發(fā)環(huán)境一切正常部署后偶發(fā) 500t3code 在本地跑了一個多月都沒問題Schema 改過五六次數(shù)據也建了不少。結果一部署到 Vercel隔三差五就報PrismaClientInitializationError錯誤信息大致是PrismaClientInitializationError: P1001: Cant reach database server at ...第一次看到這個報錯我以為是連接串寫錯了反復檢查了十幾遍都沒問題。后來才意識到問題不在連接串而在 Serverless 的實例生命周期Vercel 的每個請求可能由不同的運行實例處理如果每次實例啟動都創(chuàng)建新的 PrismaClient短時間內會打爆數(shù)據庫連接數(shù)。本地開發(fā)因為是一個長駐進程所以永遠觸發(fā)不了這個問題。標準解法是讓 PrismaClient 復用同一個實例。create-t3-app 已經預設了這么一段代碼但你得確認它真的生效了// src/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; }這段代碼的思路很簡單開發(fā)環(huán)境熱更新可能會導致模塊重復加載所以把實例掛到globalThis上生產環(huán)境雖然不掛但每個 Serverless 實例內部還是會盡量復用。如果走到這里還偶發(fā) 500那就不是單例問題而是數(shù)據庫連接池容量問題。我最終換成了 PostgreSQL 的池化連接參數(shù)DATABASE_URLpostgresql://user:passwordhost:5432/t3code?pgbouncertrue加上pgbouncertrue后Prisma 會知道你的連接走的是 PgBouncer從而限制連接存活時間避免連接耗盡。4.2 坑二tRPC 查詢結果像是被“緩存”了上線后有個現(xiàn)象很奇怪新增一個片段列表不更新刷新頁面也不一定有要過幾秒或者再刷新一次才能看到。一開始我懷疑是 tRPC 緩存于是加了一堆invalidate仍然沒有根治。后來我把問題拆開排查鏈路是這樣的第一步直接查數(shù)據庫確認數(shù)據已經寫入了 —— 數(shù)據庫沒問題第二步在瀏覽器里直接訪問 tRPC 的接口地址返回的結果是最新的 —— 后端接口沒問題第三步看頁面請求 Load 面板發(fā)現(xiàn)頁面根本沒有發(fā)新的 tRPC 請求 —— 問題出在前端。再深挖發(fā)現(xiàn)是 Next.js App Router 的客戶端 Router Cache 在起作用。Next.js 會把 RSC Payload 緩存到客戶端如果你的頁面沒有顯式聲明動態(tài)渲染它可能把數(shù)據當作靜態(tài)內容緩存住。舉個例子我在app/snippets/page.tsx里沒有加任何動態(tài)標記Next.js 可能把首次請求的結果緩存下來之后從緩存里取。解決方式有三種按推薦程度排序在相關的 route 上加export const dynamic force-dynamic;這告訴 Next.js 這個路由每次請求都動態(tài)渲染不做靜態(tài)緩存。在調用list的頁面或布局中讀取 cookies 或 headers 這樣的動態(tài) APINext.js 會自動把它標記為動態(tài)渲染。mutation 完成后調用router.refresh()強制刷新當前路由的服務端組件數(shù)據。這個命令在 App Router 里很實用但它會刷新整個路由代價比invalidate大。最終我把動態(tài)渲染標記加到了片段詳情頁而列表頁保留了一部分靜態(tài)緩存只對“最近更新”區(qū)域做動態(tài)刷新。這樣即保證了新數(shù)據能出現(xiàn)又不會每個請求都重新渲染整棵樹。4.3 坑三NextAuth 的 session 在 tRPC context 里拿不到這個坑讓我印象最深。t3code 在本地登錄沒問題但部署到 Vercel 之后凡是protectedProcedure都報未授權。登錄接口本身正常瀏覽器里能看到 session cookie但到 tRPC 的 context 里getServerSession拿到了null。排查時我一度懷疑是 cookie 跨域問題后來把環(huán)境變量逐行對比發(fā)現(xiàn)問題出在NEXTAUTH_SECRET本地的.env和生產環(huán)境的 Vercel 環(huán)境變量里存了不同的值。NextAuth 的 session 是加密簽名的如果部署后的 secret 和登錄時不一致服務端就無法驗證 session 的合法性。這在本地不會發(fā)生因為本地永遠只有一套配置。另一個容易忽視的點是 tRPC context 的寫法。在 create-t3-app 的新版本里服務端渲染場景下你需要確保 context 里拿到的是同一個 session 對象。我的最終代碼是這樣// src/server/api/trpc.ts import { initTRPC, TRPCError, } from trpc/server; import { getServerSession } from next-auth; import { authOptions } from ~/server/auth; import { db } from ~/server/db; export const createTRPCContext async () { const session await getServerSession(authOptions); return { db, session }; }; const t initTRPC.contexttypeof createTRPCContext().create(); export const createTRPCRouter t.router; export const publicProcedure t.procedure; const enforceUserIsAuthed t.middleware(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { session: { ...ctx.session, user: ctx.session.user }, }, }); }); export const protectedProcedure t.procedure.use(enforceUserIsAuthed);這里的關鍵是 middleWare 會把 session 解構后傳給下一個中間件保證后續(xù)邏輯中一定存在ctx.session.user。如果你的 context 里session本身就是null那直接再看 session 來源是不是 NextAuth 的authOptions沒有正確配置 provider先解決登錄問題再排查 tRPC。我把這三個坑整理成了一張自查表方便你踩雷時快速對照現(xiàn)象可能原因優(yōu)先檢查部署后偶發(fā) 500PrismaClient 被反復創(chuàng)建 / 連接池耗盡全局單例、池化連接參數(shù)新增數(shù)據后頁面不刷新Next.js Router Cache / tRPC 緩存未失效動態(tài)渲染標記、invalidate、router.refresh()所有受保護接口報未授權NEXTAUTH_SECRET 不一致 / session 獲取失敗環(huán)境變量、getServerSession的前后一致性5. 部署到生產環(huán)境的細節(jié)與后續(xù)優(yōu)化5.1 首次部署環(huán)境變量與 migrate 流程t3code 的部署目標選了 Vercel因為 Next.js 項目在 Vercel 上基本零配置。不過這并不代表沒有注意點。首次部署時我踩了這樣一個流程坑在本地建好了 SQLite 數(shù)據庫代碼推上去之后遠程環(huán)境照樣連不上數(shù)據庫。原因很簡單Vercel 的 Serverless 文件系統(tǒng)是只讀的SQLite 這種單文件數(shù)據庫根本沒法持久化。所以生產環(huán)境必須換成 PostgreSQL。我的遷移步驟是這樣的在 Supabase 或 Neon 上創(chuàng)建一個 PostgreSQL 實例拿到連接串本地schema.prisma確認provider postgresql重新生成遷移文件執(zhí)行npx prisma migrate deploy在生產數(shù)據庫上執(zhí)行遷移在 Vercel 項目設置里配置三個環(huán)境變量DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL部署后訪問/api/auth/session確認登錄會話正常。這里必須強調一個和本地開發(fā)的差異本地開發(fā)時我習慣直接用prisma db push同步 schema因為它不產生遷移文件改表速度快。但生產環(huán)境千萬別用db push一是它不可追溯二是多人協(xié)作時沒人知道數(shù)據庫到底被誰改過。規(guī)范的做法是prisma migrate deploy它會按遷移文件順序執(zhí)行保證每個環(huán)境的結構一致。5.2 性能與資源控制小項目也要有優(yōu)化的意識t3code 的數(shù)據量短時間內不會很大但我在寫的時候還是埋了幾個優(yōu)化點免得以后改起來傷筋動骨。第一個是列表分頁。目前的list接口直接返回全部片段量大了會有兩個問題網絡包變大、數(shù)據庫查詢變慢。我給list加上了cursor分頁模式list: publicProcedure .input( z.object({ cursor: z.string().optional(), take: z.number().max(50).default(20), }) ) .query(async ({ ctx, input }) { return ctx.db.snippet.findMany({ take: input.take 1, cursor: input.cursor ? { id: input.cursor } : undefined, orderBy: { createdAt: desc }, }); }),take: input.take 1是判斷是否還有下一頁的技巧如果返回的記錄數(shù)大于take就說明還有下一頁前端再把最后一條記錄的 id 作為 cursor 繼續(xù)拉。第二個是代碼高亮。t3code 里片段內容可能比較長如果在前端引入一個重量級高亮庫首屏會明顯變慢。我選擇把高亮邏輯放到服務端來做用 Shiki 在頁面渲染時把代碼轉成帶樣式類名的 HTML前端只負責展示。這樣用戶的瀏覽器不加載高亮庫代碼高亮也不會閃爍。第三個是全文搜索。小項目階段用 Prisma 的contains勉強夠用where: { OR: [ { title: { contains: keyword } }, { content: { contains: keyword } }, ], }但超過幾千條之后contains的性能就會開始捉急。如果后續(xù)集成真正的全文檢索我會優(yōu)先考慮 PostgreSQL 的pg_trgm擴展再進一步才會上獨立的搜索引擎。這些都不用現(xiàn)在做但 schema 和接口層面要預留好擴展點別把自己寫死。5.3 后續(xù)規(guī)劃從“自用工具”到“團隊可用平臺”t3code 現(xiàn)在滿足了我的核心訴求快速記錄、快速檢索、可分享。但你要說它是個好產品還差得遠。我自己整理的后續(xù)優(yōu)化方向大致有三塊第一體驗層面的補充分享鏈接支持有效期過期后自動失效片段支持 Fork也就是在別人公開片段的基礎上另存一個自己的版本增加收藏夾的模糊搜索。第二數(shù)據層面的擴展把 Markdown 說明和代碼內容拆開支持下載 Markdown 文件快照提供瀏覽器擴展在 GitHub 或 GitLab 頁面上右鍵即可把選中代碼存入 t3code。第三工程層面的完善給 tRPC 接口加上請求日志和錯誤上報用 Playwright 寫幾條核心路徑的 e2e 測試把數(shù)據庫遷移流程 CI 化每次 schema 變更自動生成遷移文件。很多項目做到“自用 OK”就停了但如果你真的打算給團隊用穩(wěn)定性和數(shù)據安全就必須排在前面。比如片段內容對團隊可能是核心資產導出和刪除都必須有明確的操作記錄這些后續(xù)大概率得用一張 audit log 表來支撐。最后再分享一個我個人的操作習慣所有代碼片段錄入時強制要求填language和description兩個字段。前者是為了篩選方便后者是為了讓別人包括未來的自己能在一分鐘內理解這段代碼解決的是什么問題。這個習慣比任何技術選型都重要因為工具再順手也架不住你存進來的是沒有上下文的半成品。t3code 這個項目讓我真正體會到了“類型安全 統(tǒng)一錄入規(guī)范”帶來的長期價值也建議你從自己的高頻重復代碼開始先存它十個片段感受一下檢索效率的變化再做下一步功能的優(yōu)先級判斷。