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