戰(zhàn)：t3code 全棧項(xiàng)目中的類型安全與工程實(shí)踐)
t3code 這個(gè)代號(hào)算是我今年親手從零搭起來(lái)的一個(gè)全棧項(xiàng)目。說(shuō)白了它不是一個(gè) Murmur 出來(lái)的新框架也不是什么花哨工具鏈而是一套以 TypeScript 類型安全為軸心的完整開(kāi)發(fā)模板前端用 Next.js后端邏輯收進(jìn) tRPC 路由數(shù)據(jù)庫(kù)走 Prisma樣式用 Tailwind認(rèn)證交給 NextAuth。這一套組合在圈子里常被叫 T3 Stack而 t3code 就是我在這個(gè)技術(shù)選型下沉淀出來(lái)的項(xiàng)目骨架和踩坑實(shí)錄。這篇文章想把我在搭建過(guò)程中真正有價(jià)值的決策、踩過(guò)的坑、以及最后留下的工程實(shí)踐寫(xiě)清楚給那些準(zhǔn)備拿起 T3 Stack 做全棧項(xiàng)目的人一個(gè)可以參考的真實(shí)樣本也聊聊為什么“類型安全”這三個(gè)字能省掉那么多破事。這個(gè)項(xiàng)目適合誰(shuí)看如果你已經(jīng)在用 TypeScript 寫(xiě) React又對(duì) Next.js 的 API Routes 感到似懂非懂或者你想知道數(shù)據(jù)庫(kù)、API、前端類型到底能不能共用一份那這篇文章應(yīng)該能給你一個(gè)很具體的答案。1. 為什么 t3code 會(huì)把項(xiàng)目壓在 T3 Stack 上1.1 先理清“類型安全全?！钡降资×耸裁次蚁日f(shuō)結(jié)論類型安全全棧不是一個(gè)錦上添花的特性它會(huì)直接改變你寫(xiě)代碼的順序和溝通成本。傳統(tǒng)的前后端分離項(xiàng)目里前端要依賴后端開(kāi)放的 REST 文檔或者一個(gè)手寫(xiě)的類型聲明文件接口一變前端大部分情況是不知道的——等編譯報(bào)錯(cuò)已經(jīng)是在聯(lián)調(diào)時(shí)了。T3 Stack 的核心思路是把類型本身當(dāng)作前后端之間的接口協(xié)議數(shù)據(jù)庫(kù)字段類型由 Prisma Schema 定義tRPC 路由的輸入輸出類型由 TypeScript 自動(dòng)推導(dǎo)前端組件 import 一個(gè)被推導(dǎo)好的 hook直接就能拿到帶類型的返回值。我在 t3code 里第一次明顯感覺(jué)到這個(gè)優(yōu)勢(shì)是寫(xiě)一個(gè)用戶列表頁(yè)面。后端有一個(gè)getAllUsers的 query返回結(jié)構(gòu)里帶有profile關(guān)聯(lián)表的數(shù)據(jù)。我在 Prisma 里給Profile模型加了個(gè)字段前端頁(yè)面代碼完全沒(méi)動(dòng)再看瀏覽器頁(yè)面上的字段已經(jīng)自動(dòng)被 TypeScript 識(shí)別到了。沒(méi)有聯(lián)調(diào)群沒(méi)有“后端接口改了前端記得跟上”這種需求因?yàn)閮烧弑緛?lái)就在同一個(gè)類型系統(tǒng)里。1.2 tRPC 和 API Routes 的取舍像函數(shù)調(diào)用一樣調(diào)后端有人會(huì)問(wèn)Next.js 自帶 API Routes為什么還要再加一層 tRPC我的答案是API Routes 是 HTTP 層面的解決方案而 tRPC 是類型層面的解決方案。API Routes 要求你手動(dòng)管理請(qǐng)求路徑、校驗(yàn)參數(shù)、序列化響應(yīng)、處理錯(cuò)誤每個(gè)環(huán)節(jié)都是手寫(xiě)的也因此每個(gè)環(huán)節(jié)都可能跟類型脫節(jié)。tRPC 則把這一層包裝成類型安全的函數(shù)調(diào)用你寫(xiě)的是api.user.getAll.query()但它在瀏覽器環(huán)境會(huì)自動(dòng)通過(guò) HTTP 請(qǐng)求把參數(shù)發(fā)到服務(wù)端路由再把返回值序列化回來(lái)全程類型都是推導(dǎo)的不需要你維護(hù)任何路由字符串。當(dāng)然這不是說(shuō) REST 就一無(wú)是處。如果你的項(xiàng)目有公共 API、有大量第三方調(diào)用REST 和 OpenAPI 可能更合適。但對(duì)于 t3code 這種前后端同倉(cāng)庫(kù)、同語(yǔ)言的內(nèi)部業(yè)務(wù)系統(tǒng)tRPC 的性價(jià)比非常高。它省掉的不只是寫(xiě)接口文檔的時(shí)間更省掉了“前端猜后端字段含義”這種溝通摩擦。1.3 三個(gè)關(guān)鍵依賴的邊界Next.js 只是宿主tRPC 是骨Prisma 是丹田很多初學(xué)者會(huì)把這幾個(gè)概念混在一起我建議把它們拆開(kāi)理解。Next.js 在這里只承擔(dān)框架宿主角色負(fù)責(zé)頁(yè)面渲染、路由處理和 Server Component 的調(diào)度。tRPC 是連接層它不負(fù)責(zé)渲染也不負(fù)責(zé)數(shù)據(jù)庫(kù)只負(fù)責(zé)“讓函數(shù)調(diào)用變?yōu)檫h(yuǎn)程調(diào)用”這件事。Prisma 才是數(shù)據(jù)世界真正的源頭你的模型字段、枚舉、關(guān)系都在這里定義。Tailwind 是純表現(xiàn)層它跟業(yè)務(wù)邏輯沒(méi)有耦合愛(ài)用不用。我在 t3code 的架構(gòu)設(shè)計(jì)里非?？桃獾刈屵@三者保持單方向依賴Prisma Schema 是真理之源tRPC Router 消費(fèi) Prisma 的輸出Next.js 頁(yè)面消費(fèi) tRPC 的輸出。方向一旦反過(guò)來(lái)代碼就會(huì)開(kāi)始亂。比如有人會(huì)把 tRPC 調(diào)用寫(xiě)到 Prisma 的 seed 腳本里我看了就腦仁疼——那個(gè)腳本應(yīng)該直接用 Prisma Client沒(méi)必要經(jīng)過(guò) tRPC 這層 HTTP 邏輯。2. 腳手架跑通之后目錄里真正值得警惕的東西2.1 create-t3-app 到底生成了什么先別急著刪用npm create t3-applatest t3code初始化項(xiàng)目非?？鞄追昼娋湍芘芷饋?lái)。但跑起來(lái)之后最容易犯的錯(cuò)是看多了網(wǎng)上那些“精簡(jiǎn)目錄”的教程手癢把默認(rèn)結(jié)構(gòu)改了。我建議你在項(xiàng)目初期至少保留這幾個(gè)文件src/server/db.tsPrisma Client 的單例封裝開(kāi)發(fā)環(huán)境避免熱更新創(chuàng)建太多連接。src/server/api/trpc.tstRPC 的初始化文件和上下文類型定義幾乎所有路由都依賴它。src/trpc/server.ts/src/trpc/react.tsx服務(wù)端調(diào)用器和客戶端 React Hooks 的橋接層。這些文件不是說(shuō)不能改而是你會(huì)頻繁用到它們不如先保持默認(rèn)等理解透了再優(yōu)化。我在 t3code 的前兩周就是這么干的只新增業(yè)務(wù)文件不重構(gòu)腳手架把精力放在熟悉結(jié)構(gòu)上。這里還要提一個(gè)細(xì)節(jié)默認(rèn)模板會(huì)生成app/api/trpc/[trpc]/route.ts這是 tRPC HTTP 網(wǎng)關(guān)在 Next.js App Router 下的標(biāo)準(zhǔn)入口。初次看這個(gè)文件的人可能會(huì)覺(jué)得它很“魔法”但展開(kāi)看它其實(shí)就是把收到的 HTTP 請(qǐng)求交給fetchRequestHandler再傳一個(gè)createContext函數(shù)進(jìn)去而已。理解它之后你調(diào)試 tRPC 的報(bào)錯(cuò)會(huì)方便很多。2.2 App Router 還是 Pages Routert3code 的選擇與理由create-t3-app 在很長(zhǎng)一段時(shí)間里默認(rèn)使用 Next.js App Router我直接沿用沒(méi)有切回 Pages Router。原因不復(fù)雜App Router 的 Server Component 可以讓我在服務(wù)端直接調(diào)用 tRPC Procedure避免很多組件變成 Client Component頁(yè)面也更容易拿搜索引擎的分?jǐn)?shù)。但我也必須誠(chéng)實(shí)提醒App Router 的學(xué)習(xí)曲線明顯更陡如果你是第一次接觸建議先花半天把一個(gè) React Server Component 和 Client Component 的邊界理清楚再來(lái)用 tRPC。在 App Router 下t3code 的做法是頁(yè)面主體邏輯盡量放 Server Component只有需要交互的局部區(qū)域比如搜索框、表格操作按鈕、篩選器用use client。數(shù)據(jù)獲取統(tǒng)一走服務(wù)端調(diào)用 tRPC 的createCaller而不是在客戶端useQuery。這樣首屏 HTML 里已經(jīng)有數(shù)據(jù)瀏覽器端不需要先發(fā)一堆請(qǐng)求再渲染骨架屏體驗(yàn)好很多。2.3 補(bǔ)齊 tRPC 客戶端 Context否則瀏覽器里全是 404這里我要說(shuō)一個(gè)特別容易踩、但又特別隱蔽的坑。如果你在非 Server Component 環(huán)境調(diào)用api.user.getAll.useQuery()而項(xiàng)目里沒(méi)有在根布局或者TRPCReactProvider里掛載 Context Provider瀏覽器控制臺(tái)只會(huì)給你一片 404。原因很簡(jiǎn)單tRPC 客戶端的 hooks 需要 Provider 才能拿到正確的 URL 和請(qǐng)求方法Provider 沒(méi)掛請(qǐng)求路徑不會(huì)自動(dòng)注冊(cè)到 Next.js 的 route handler 上。t3code 的寫(xiě)法是在app/layout.tsx里用TRPCReactProvider包住整個(gè)頁(yè)面Provider 內(nèi)部再包一層headers()讀取服務(wù)端返回的 cookies確保服務(wù)端渲染和客戶端渲染兩邊拿到的請(qǐng)求頭一致。這個(gè)細(xì)節(jié)如果不做部分頁(yè)面在 SSR 下可能正常一旦客戶端導(dǎo)航就出問(wèn)題Debug 起來(lái)非常費(fèi)勁因?yàn)閳?bào)錯(cuò)不一定指向 Provider。3. Prisma 從 SQLite 遷到 PostgreSQL 時(shí)我踩過(guò)的三個(gè)數(shù)據(jù)坑3.1 第一個(gè)坑SQLite 習(xí)慣寫(xiě)進(jìn) schemaPostgres 直接給你顏色t3code 開(kāi)發(fā)早期為了零配置我直接用 SQLite 當(dāng)數(shù)據(jù)庫(kù)。本地跑得很爽直到我決定把數(shù)據(jù)庫(kù)換成 PostgreSQL準(zhǔn)備上生產(chǎn)環(huán)境的時(shí)候才發(fā)現(xiàn) schema 里有好幾個(gè)字段是為 SQLite 量身定做的。最典型的是String default()這種寫(xiě)法。SQLite 對(duì)空串處理很佛系但 PostgreSQL 里有些字段類型會(huì)在空串和空值之間產(chǎn)生語(yǔ)義沖突比如Decimal類型存儲(chǔ)空串會(huì)直接報(bào)錯(cuò)。另一個(gè)坑是枚舉類型SQLite 不原生支持enumPrisma 會(huì)退化成字符串檢查一換到 PostgreSQL模型定義就必須顯式聲明枚舉舊數(shù)據(jù)里如果有枚舉外的值遷移會(huì)失敗。我的建議是從第一天就用 PostgreSQL 或者 MySQL 來(lái)開(kāi)發(fā)哪怕本地跑 Docker 也要用生產(chǎn)同款數(shù)據(jù)庫(kù)?，F(xiàn)在 Docker 起一個(gè) Postgres 只要一分鐘不要在“反正后面會(huì)換”上面省時(shí)間。3.2 第二個(gè)坑BigInt 與 Date 在 tRPC 傳輸層的序列化問(wèn)題Prisma 里有幾個(gè)字段類型會(huì)在 JSON 序列化時(shí)產(chǎn)生意外。最典型的是BigInt。PostgreSQL 的某些計(jì)數(shù) ID 用了BigIntPrisma 返回的是一個(gè) JavaScript BigInt 對(duì)象可 JSON.stringify 根本不支持 BigInt默認(rèn)直接拋TypeError: Do not know how to serialize a BigInt。這個(gè)問(wèn)題在沒(méi)有 tRPC 的時(shí)候也存在但因?yàn)?tRPC 會(huì)自動(dòng)做序列化報(bào)錯(cuò)信息會(huì)出現(xiàn)在運(yùn)行時(shí)更隱蔽。t3code 的處理方式是給這些字段定義明確的數(shù)據(jù)傳輸對(duì)象DTO在 tRPC Router 的返回處就把BigInt轉(zhuǎn)成字符串或者 Number。另外一個(gè)常見(jiàn)問(wèn)題是 Date 對(duì)象Prisma 返回的 Date 在 tRPC 里會(huì)變成 ISO 字符串前端做時(shí)間格式化的時(shí)候如果直接new Date(value)還能用但如果拿它做value instanceof Date的判斷就會(huì)出問(wèn)題。所以我的原則是跨 tRPC 邊界的日期統(tǒng)一用字符串傳遞顯示格式統(tǒng)一在展示層處理絕不把 Date 對(duì)象直接往 client 丟。3.3 第三個(gè)坑connection pool 和事務(wù)隔離級(jí)別少一次壓測(cè)都不知道本地 SQLite 是一次連接一個(gè)文件幾乎沒(méi)有并發(fā)問(wèn)題。但 PostgreSQL 在 Serverless 環(huán)境下的連接數(shù)是非常稀缺的資源尤其是部署到 Vercel 或 Netlify 這類無(wú)服務(wù)器平臺(tái)時(shí)Prisma Client 如果不做連接池管理每個(gè) Lambda 實(shí)例可能都會(huì)去搶數(shù)據(jù)庫(kù)連接稍微有點(diǎn)流量連接數(shù)就爆了。t3code 后面部署到一臺(tái)小云主機(jī)上用常駐 Node 進(jìn)程跑遇到的情況是Prisma 默認(rèn)的事務(wù)隔離級(jí)別在并發(fā)寫(xiě)多的時(shí)候會(huì)產(chǎn)生大量重試異常看起來(lái)像是“偶發(fā)報(bào)錯(cuò)”但壓測(cè)一上就原形畢露。我建議你在寫(xiě)涉及多表更新的 mutation 時(shí)提前想清楚這個(gè)事務(wù)的隔離級(jí)別并且使用 Prisma 的連接池配置比如?connection_limit5pool_timeout2這類參數(shù)。平時(shí)看起來(lái)無(wú)關(guān)緊要到了并發(fā)場(chǎng)景就是能不能扛住壓測(cè)的分水嶺。4. tRPC 路由不是簡(jiǎn)單拆文件中間件、上下文與錯(cuò)誤碼設(shè)計(jì)4.1 從 createTRPCRouter 到隱式依賴先說(shuō)說(shuō) tRPC 路由的組織方式。很多人第一次接觸 tRPC會(huì)以為它就是把 API Routes 換個(gè)寫(xiě)法路由文件拆得多了自然就有結(jié)構(gòu)。但實(shí)際上 tRPC 有一個(gè)更重要的隱式依賴路由會(huì)攜帶一個(gè)共享的 Context。這個(gè) Context 是你每次請(qǐng)求的“環(huán)境快照”里面可以放數(shù)據(jù)庫(kù)實(shí)例、當(dāng)前登錄用戶、請(qǐng)求頭信息等。所有 Procedure 都能訪問(wèn)這份 Context所以路由設(shè)計(jì)得好不好很大程度取決于 Context 設(shè)計(jì)得好不好。t3code 的 Context 里我放了三樣?xùn)|西Prisma Client 實(shí)例、session對(duì)象可能為 null、以及一個(gè)表示“當(dāng)前請(qǐng)求是否來(lái)自客戶端”的isClient布爾值。中間件再根據(jù) Context 里的 session 狀態(tài)決定放行還是拒絕。如果想把 Context 設(shè)計(jì)好一個(gè)習(xí)慣是永遠(yuǎn)不要在生產(chǎn)路由里直接讀文件或者請(qǐng)求體所有依賴都通過(guò) Context 注入后續(xù)測(cè)試會(huì)輕松很多。4.2 一個(gè)全局 middleware 能省掉多少 if這里的核心是避免在每一個(gè) mutation 里寫(xiě)一大段“如果是管理員就怎么樣”的邏輯。t3code 里我套了兩層中間件第一層是全局的只做基本日志和耗時(shí)記錄第二層是“需要登錄”的中間件掛在所有需要身份校驗(yàn)的路由組上。這個(gè)中間件的寫(xiě)法非常直白const protectedProcedure tRPC.procedure.use(async ({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED, message: 登錄后才能執(zhí)行這個(gè)操作, }); } return next({ ctx: { ...ctx, user: ctx.session.user, }, }); });之后任何需要登錄的接口都直接用protectedProcedure不需要在業(yè)務(wù)代碼里再判斷session。如果你有十幾個(gè)查詢都要做登錄校驗(yàn)這一個(gè)中間件就能刪掉十幾遍重復(fù)邏輯。更關(guān)鍵的是后面加權(quán)限系統(tǒng)也只需要在中間件里多套一層業(yè)務(wù)代碼一行都不用改。4.3 錯(cuò)誤碼與錯(cuò)誤信息的結(jié)構(gòu)約定tRPC 自帶的錯(cuò)誤碼體系已經(jīng)覆蓋了常見(jiàn)情況比如BAD_REQUEST、UNAUTHORIZED、FORBIDDEN、NOT_FOUND、INTERNAL_SERVER_ERROR。但這里有個(gè)容易忽略的點(diǎn)默認(rèn)的message是字面量英文而前端用戶根本看不到也不應(yīng)該看到。我的做法是在前端統(tǒng)一封裝一個(gè)errorMapper函數(shù)把 tRPC 的 error shape 映射成用戶可讀的中文文案同時(shí)把code傳給日志系統(tǒng)。另外不要把業(yè)務(wù)錯(cuò)誤全拋成INTERNAL_SERVER_ERROR否則你查日志會(huì)瘋掉。比如用戶傳了一個(gè)不存在的 ID就應(yīng)該拋NOT_FOUND權(quán)限不夠就拋FORBIDDEN。我見(jiàn)過(guò)很多半路出家的項(xiàng)目不管什么錯(cuò)誤都是BAD_REQUEST排查起來(lái)完全靠猜。錯(cuò)誤碼的語(yǔ)義化是工程成熟度非常顯性的信號(hào)。5. NextAuth 接入 tRPC 受保護(hù)路由的完整鏈路5.1 為什么在 App Router 下不能直接用舊版 session 寫(xiě)法NextAuth 在 Pages Router 時(shí)代最常用的拿 session 方式是getSession()在服務(wù)端getServerSideProps里每次請(qǐng)求調(diào)用一次。但在 App Router 下推薦的做法是getServerSession()配合authOptions從請(qǐng)求頭里恢復(fù) session。t3code 一開(kāi)始沒(méi)注意這個(gè)區(qū)別我照舊用getSession()在 Server Component 里取數(shù)據(jù)某天突然發(fā)現(xiàn)部分頁(yè)面在刷新時(shí)會(huì)拿到 null而客戶端導(dǎo)航時(shí)又是正常的。最后定位下來(lái)是因?yàn)間etSession()依賴的請(qǐng)求上下文在 App Router 的 Server Component 里不一定能拿到完整的 cookies 和 headers導(dǎo)致 session 讀取不穩(wěn)定。換成getServerSession后這個(gè)問(wèn)題就消失了。如果你用 NextAuth v5現(xiàn)在是 Auth.js那一套 API 又會(huì)變所以我的建議是不要憑記憶寫(xiě)每次都要確認(rèn)當(dāng)前版本對(duì)應(yīng)的官方示例這種基礎(chǔ)鏈路不值得省那兩分鐘。5.2 Auth.ts 與 tRPC context 的橋接t3code 里最關(guān)鍵的橋接文件是把 tRPC 的 Context 和 NextAuth 的 Session 連起來(lái)?；咀龇ㄊ窃赾reateContext里并行調(diào)用getServerSession把返回的 session 塞給 tRPC。這里有個(gè)實(shí)操細(xì)節(jié)第一次請(qǐng)求時(shí)Prisma Client、session 這些對(duì)象都會(huì)被初始化如果你的選擇器頻繁創(chuàng)建 PrismaClient熱更新階段會(huì)有大量連接殘留所以一定記得用全局單例模式。而生成了 session 之后要記得把 session 放到 Context 里而不是每次在路由里重新getServerSession否則你的 query 函數(shù)會(huì)變得很啰嗦而且沒(méi)法統(tǒng)一做緩存。5.3 Credentials Provider 的 JWT 坑t3code 早期為了簡(jiǎn)單用 NextAuth 的 Credentials Provider 實(shí)現(xiàn)郵箱密碼登錄。這個(gè) Provider 默認(rèn)不會(huì)把用戶 ID 寫(xiě)進(jìn) session而是把整個(gè)登錄請(qǐng)求交給 JWT 策略。這里有個(gè)坑如果你在signIn回調(diào)里沒(méi)有做足夠校驗(yàn)或者jwt回調(diào)里沒(méi)有把 userId 賦到 token 上前端拿到 session 時(shí)沒(méi)有 user.id然后 tRPC 中間件就會(huì)把明明已經(jīng)登錄的人當(dāng)成游客。正確做法是在jwt回調(diào)里手動(dòng)寫(xiě)入callbacks: { jwt({ token, user }) { if (user) { token.userId user.id; } return token; }, session({ session, token }) { if (session.user) { session.user.id token.userId as string; } return session; }, }這個(gè)看著不復(fù)雜但網(wǎng)上能搜到的案例大多只寫(xiě) GitHub 登錄沒(méi)有注意 Credentials Provider 的特殊性。如果你用第三方 OAuth 登錄可能不會(huì)觸發(fā)這個(gè)場(chǎng)景但一旦切到賬密登錄就非常容易卡在這里。6. 部署到生產(chǎn)環(huán)境后類型安全救不了你的那些時(shí)刻6.1 Vercel Serverless 環(huán)境下的 Prisma 連接池坦白說(shuō)t3code 部署到 Vercel 的第一版是在流量稍大時(shí)直接崩掉的。原因跟前面說(shuō)的數(shù)據(jù)庫(kù)連接池高度相關(guān)Vercel 的 Lambda 是短生命周期進(jìn)程每個(gè)實(shí)例啟動(dòng)時(shí)都會(huì)初始化 Prisma Client如果數(shù)據(jù)庫(kù)連接池的上限配置得太小一有流量波動(dòng)Prisma 就只能排隊(duì)等待。而排隊(duì)時(shí)間一旦超過(guò) Lambda 超時(shí)閾值用戶就會(huì)看到 504。我的解決方式其實(shí)很“土”在云廠商的數(shù)據(jù)庫(kù)參數(shù)里提高了最大連接數(shù)同時(shí)在 Prisma 的連接串上顯式設(shè)置了connection_limit和pool_timeout讓連接等待有上限。如果你用的是 Prisma 官方加速服務(wù)那又是另一套配置?？傊涀∫稽c(diǎn)本地跑得好不代表生產(chǎn)不會(huì)死連接池這個(gè)東西一定要在部署前想清楚。6.2 WebSocket 適配器在無(wú)狀態(tài)環(huán)境里的噩夢(mèng)如果想做實(shí)時(shí)更新很多人第一反應(yīng)是上 tRPC subscription。但請(qǐng)注意tRPC subscription 默認(rèn)依賴 WebSocket而 Vercel 這類 Serverless 平臺(tái)對(duì) WebSocket 的支持非常有限如果你部署到邊緣函數(shù)WebSocket 長(zhǎng)連接更是直接不可用。t3code 后來(lái)放棄在 Vercel 上做實(shí)時(shí)訂閱改到了常駐 Node 進(jìn)程的服務(wù)器上WebSocket 才穩(wěn)定下來(lái)。如果你一定要在 Serverless 環(huán)境用 subscription建議了解trpc/server的subscription適配器和平臺(tái)限制。很多項(xiàng)目的實(shí)時(shí)功能用輪詢就足夠了不一定非要長(zhǎng)連接。千萬(wàn)不要因?yàn)椤皩?shí)時(shí)”兩個(gè)字就把架構(gòu)搞得復(fù)雜輪詢 短緩存往往在 90% 的場(chǎng)景里都?jí)蛴谩?.3 環(huán)境變量與多環(huán)境配置zod 校驗(yàn)寫(xiě)在最前面環(huán)境變量是部署出錯(cuò)的高發(fā)區(qū)。t3code 的做法是用一個(gè) zod schema 在啟動(dòng)時(shí)校驗(yàn)所有關(guān)鍵環(huán)境變量缺哪個(gè)直接給你一個(gè)清晰的中文報(bào)錯(cuò)而不是等你運(yùn)行到某個(gè)接口才炸。比如DATABASE_URL、NEXTAUTH_SECRET、S3_BUCKET這些變量在 config 文件里統(tǒng)一讀取并校驗(yàn)。這樣做的另一個(gè)好處是如果把環(huán)境變量集中到一個(gè) TypeScript 文件IDE 提示會(huì)非常舒服而且新同事上手時(shí)看到這個(gè)文件就大概知道項(xiàng)目依賴哪些外部資源。這也是我從很多生產(chǎn)事故里學(xué)到的教訓(xùn)說(shuō)句實(shí)話類型安全能保證代碼內(nèi)部不出錯(cuò)但保證不了你部署環(huán)境的外部配置不出錯(cuò)多一道啟動(dòng)時(shí)校驗(yàn)比什么都強(qiáng)。7. t3code 下一步實(shí)時(shí)訂閱、文件上傳、可觀測(cè)性7.1 用 tRPC subscription 替換定時(shí)輪詢t3code 現(xiàn)在的消息列表已經(jīng)改成真實(shí)時(shí)更新了因?yàn)榉?wù)端不再受限于無(wú)狀態(tài)環(huán)境。tRPC subscription 的寫(xiě)法跟 query 非常接近核心還是在 router 里注冊(cè)subscription然后通過(guò)發(fā)布訂閱源把更新推給客戶端。這里有一個(gè)值得注意的設(shè)計(jì)不要在前端直接調(diào)用 subscription 的發(fā)布函數(shù)所有發(fā)布動(dòng)作都應(yīng)該由服務(wù)端業(yè)務(wù)觸發(fā)客戶端只能監(jiān)聽(tīng)。我在實(shí)際使用中的體會(huì)是tRPC subscription 的代碼量比 WebSocket 原生實(shí)現(xiàn)少得多可讀性也好適合中小型項(xiàng)目。但它對(duì)連接狀態(tài)的恢復(fù)處理不如成熟的消息隊(duì)列所以 websocket 斷線重連時(shí)的消息補(bǔ)償還得自己在業(yè)務(wù)層處理。這部分如果做得不好用戶可能錯(cuò)過(guò)重要通知。7.2 文件上傳不留服務(wù)器直接走后端簽名 URL很多初學(xué)者會(huì)把文件上傳寫(xiě)成POST /api/upload然后把文件寫(xiě)進(jìn)服務(wù)器磁盤(pán)。這在本地開(kāi)發(fā)沒(méi)事上了生產(chǎn)要么磁盤(pán)不夠要么負(fù)載均衡多個(gè)實(shí)例之間文件不同步。t3code 的做法是走 Object Storage比如 S3 兼容存儲(chǔ)上傳邏輯用預(yù)簽名 URL 實(shí)現(xiàn)前端先調(diào)用 tRPC 的getUploadUrlmutation傳入文件名和類型。后端返回一個(gè)短時(shí)有效的上傳 URL。前端直接用 PUT 或 POST 把文件流推到存儲(chǔ)服務(wù)不走應(yīng)用服務(wù)器。這個(gè)方案既減少服務(wù)器帶寬壓力又能避免接口被惡意塞大文件。我之前踩過(guò)一個(gè)坑是沒(méi)有限制上傳大小結(jié)果被一個(gè)同事傳了個(gè) 2GB 的視頻桶直接吃到告警。后來(lái)我加上了文件大小和后綴名校驗(yàn)總算沒(méi)再出事。7.3 加一層可觀測(cè)性把每次 query 的耗時(shí)暴露出來(lái)最后我想聊一個(gè)沒(méi)那么炫酷但非常重要的部分可觀測(cè)性。t3code 在中間件里給每個(gè) tRPC procedure 記錄了一條日志包含路徑、耗時(shí)、狀態(tài)碼、用戶 ID。這樣一旦線上有問(wèn)題我可以從日志里很快定位到具體是哪個(gè)查詢慢而不是等到用戶反饋。具體實(shí)現(xiàn)也很簡(jiǎn)單就是給 tRPC 加一個(gè)onError處理器和一個(gè)耗時(shí)中間件。日志不一定要上分布式鏈路追蹤剛開(kāi)始用控制臺(tái)輸出加一個(gè)結(jié)構(gòu)化日志文件就夠用。等哪天流量大了再引入 OpenTelemetry 也不遲。這個(gè)過(guò)程中最有價(jià)值的不是某個(gè)工具而是“把每一次請(qǐng)求都當(dāng)成可觀測(cè)事件”的工程習(xí)慣。t3code 這套搭建過(guò)程里我印象最深的反而不是某個(gè)具體 API而是類型安全帶來(lái)的正反饋循環(huán)數(shù)據(jù)庫(kù)結(jié)構(gòu)一變類型跟著變編譯就報(bào)錯(cuò)修復(fù)的速度遠(yuǎn)快于肉眼排查接口文檔。但也正因?yàn)樗验_(kāi)發(fā)體驗(yàn)拉得很高部署和運(yùn)維階段的坑反而容易被忽略。如果你打算用 T3 Stack 做自己的項(xiàng)目我建議不要只盯著框架的花哨功能先把 Context、中間件、錯(cuò)誤碼、連接池這些基建打扎實(shí)很多線上問(wèn)題是可以提前避免的。 T3 Stack 實(shí)戰(zhàn)：t3code 全棧項(xiàng)目中的類型安全與工程實(shí)踐
t3code 這個(gè)代號(hào)算是我今年親手從零搭起來(lái)的一個(gè)全棧項(xiàng)目。說(shuō)白了它不是一個(gè) Murmur 出來(lái)的新框架也不是什么花哨工具鏈而是一套以 TypeScript 類型安全為軸心的完整開(kāi)發(fā)模板前端用 Next.js后端邏輯收進(jìn) tRPC 路由數(shù)據(jù)庫(kù)走 Prisma樣式用 Tailwind認(rèn)證交給 NextAuth。這一套組合在圈子里常被叫 T3 Stack而 t3code 就是我在這個(gè)技術(shù)選型下沉淀出來(lái)的項(xiàng)目骨架和踩坑實(shí)錄。這篇文章想把我在搭建過(guò)程中真正有價(jià)值的決策、踩過(guò)的坑、以及最后留下的工程實(shí)踐寫(xiě)清楚給那些準(zhǔn)備拿起 T3 Stack 做全棧項(xiàng)目的人一個(gè)可以參考的真實(shí)樣本也聊聊為什么“類型安全”這三個(gè)字能省掉那么多破事。這個(gè)項(xiàng)目適合誰(shuí)看如果你已經(jīng)在用 TypeScript 寫(xiě) React又對(duì) Next.js 的 API Routes 感到似懂非懂或者你想知道數(shù)據(jù)庫(kù)、API、前端類型到底能不能共用一份那這篇文章應(yīng)該能給你一個(gè)很具體的答案。1. 為什么 t3code 會(huì)把項(xiàng)目壓在 T3 Stack 上1.1 先理清“類型安全全?！钡降资×耸裁次蚁日f(shuō)結(jié)論類型安全全棧不是一個(gè)錦上添花的特性它會(huì)直接改變你寫(xiě)代碼的順序和溝通成本。傳統(tǒng)的前后端分離項(xiàng)目里前端要依賴后端開(kāi)放的 REST 文檔或者一個(gè)手寫(xiě)的類型聲明文件接口一變前端大部分情況是不知道的——等編譯報(bào)錯(cuò)已經(jīng)是在聯(lián)調(diào)時(shí)了。T3 Stack 的核心思路是把類型本身當(dāng)作前后端之間的接口協(xié)議數(shù)據(jù)庫(kù)字段類型由 Prisma Schema 定義tRPC 路由的輸入輸出類型由 TypeScript 自動(dòng)推導(dǎo)前端組件 import 一個(gè)被推導(dǎo)好的 hook直接就能拿到帶類型的返回值。我在 t3code 里第一次明顯感覺(jué)到這個(gè)優(yōu)勢(shì)是寫(xiě)一個(gè)用戶列表頁(yè)面。后端有一個(gè)getAllUsers的 query返回結(jié)構(gòu)里帶有profile關(guān)聯(lián)表的數(shù)據(jù)。我在 Prisma 里給Profile模型加了個(gè)字段前端頁(yè)面代碼完全沒(méi)動(dòng)再看瀏覽器頁(yè)面上的字段已經(jīng)自動(dòng)被 TypeScript 識(shí)別到了。沒(méi)有聯(lián)調(diào)群沒(méi)有“后端接口改了前端記得跟上”這種需求因?yàn)閮烧弑緛?lái)就在同一個(gè)類型系統(tǒng)里。1.2 tRPC 和 API Routes 的取舍像函數(shù)調(diào)用一樣調(diào)后端有人會(huì)問(wèn)Next.js 自帶 API Routes為什么還要再加一層 tRPC我的答案是API Routes 是 HTTP 層面的解決方案而 tRPC 是類型層面的解決方案。API Routes 要求你手動(dòng)管理請(qǐng)求路徑、校驗(yàn)參數(shù)、序列化響應(yīng)、處理錯(cuò)誤每個(gè)環(huán)節(jié)都是手寫(xiě)的也因此每個(gè)環(huán)節(jié)都可能跟類型脫節(jié)。tRPC 則把這一層包裝成類型安全的函數(shù)調(diào)用你寫(xiě)的是api.user.getAll.query()但它在瀏覽器環(huán)境會(huì)自動(dòng)通過(guò) HTTP 請(qǐng)求把參數(shù)發(fā)到服務(wù)端路由再把返回值序列化回來(lái)全程類型都是推導(dǎo)的不需要你維護(hù)任何路由字符串。當(dāng)然這不是說(shuō) REST 就一無(wú)是處。如果你的項(xiàng)目有公共 API、有大量第三方調(diào)用REST 和 OpenAPI 可能更合適。但對(duì)于 t3code 這種前后端同倉(cāng)庫(kù)、同語(yǔ)言的內(nèi)部業(yè)務(wù)系統(tǒng)tRPC 的性價(jià)比非常高。它省掉的不只是寫(xiě)接口文檔的時(shí)間更省掉了“前端猜后端字段含義”這種溝通摩擦。1.3 三個(gè)關(guān)鍵依賴的邊界Next.js 只是宿主tRPC 是骨Prisma 是丹田很多初學(xué)者會(huì)把這幾個(gè)概念混在一起我建議把它們拆開(kāi)理解。Next.js 在這里只承擔(dān)框架宿主角色負(fù)責(zé)頁(yè)面渲染、路由處理和 Server Component 的調(diào)度。tRPC 是連接層它不負(fù)責(zé)渲染也不負(fù)責(zé)數(shù)據(jù)庫(kù)只負(fù)責(zé)“讓函數(shù)調(diào)用變?yōu)檫h(yuǎn)程調(diào)用”這件事。Prisma 才是數(shù)據(jù)世界真正的源頭你的模型字段、枚舉、關(guān)系都在這里定義。Tailwind 是純表現(xiàn)層它跟業(yè)務(wù)邏輯沒(méi)有耦合愛(ài)用不用。我在 t3code 的架構(gòu)設(shè)計(jì)里非?？桃獾刈屵@三者保持單方向依賴Prisma Schema 是真理之源tRPC Router 消費(fèi) Prisma 的輸出Next.js 頁(yè)面消費(fèi) tRPC 的輸出。方向一旦反過(guò)來(lái)代碼就會(huì)開(kāi)始亂。比如有人會(huì)把 tRPC 調(diào)用寫(xiě)到 Prisma 的 seed 腳本里我看了就腦仁疼——那個(gè)腳本應(yīng)該直接用 Prisma Client沒(méi)必要經(jīng)過(guò) tRPC 這層 HTTP 邏輯。2. 腳手架跑通之后目錄里真正值得警惕的東西2.1 create-t3-app 到底生成了什么先別急著刪用npm create t3-applatest t3code初始化項(xiàng)目非?？鞄追昼娋湍芘芷饋?lái)。但跑起來(lái)之后最容易犯的錯(cuò)是看多了網(wǎng)上那些“精簡(jiǎn)目錄”的教程手癢把默認(rèn)結(jié)構(gòu)改了。我建議你在項(xiàng)目初期至少保留這幾個(gè)文件src/server/db.tsPrisma Client 的單例封裝開(kāi)發(fā)環(huán)境避免熱更新創(chuàng)建太多連接。src/server/api/trpc.tstRPC 的初始化文件和上下文類型定義幾乎所有路由都依賴它。src/trpc/server.ts/src/trpc/react.tsx服務(wù)端調(diào)用器和客戶端 React Hooks 的橋接層。這些文件不是說(shuō)不能改而是你會(huì)頻繁用到它們不如先保持默認(rèn)等理解透了再優(yōu)化。我在 t3code 的前兩周就是這么干的只新增業(yè)務(wù)文件不重構(gòu)腳手架把精力放在熟悉結(jié)構(gòu)上。這里還要提一個(gè)細(xì)節(jié)默認(rèn)模板會(huì)生成app/api/trpc/[trpc]/route.ts這是 tRPC HTTP 網(wǎng)關(guān)在 Next.js App Router 下的標(biāo)準(zhǔn)入口。初次看這個(gè)文件的人可能會(huì)覺(jué)得它很“魔法”但展開(kāi)看它其實(shí)就是把收到的 HTTP 請(qǐng)求交給fetchRequestHandler再傳一個(gè)createContext函數(shù)進(jìn)去而已。理解它之后你調(diào)試 tRPC 的報(bào)錯(cuò)會(huì)方便很多。2.2 App Router 還是 Pages Routert3code 的選擇與理由create-t3-app 在很長(zhǎng)一段時(shí)間里默認(rèn)使用 Next.js App Router我直接沿用沒(méi)有切回 Pages Router。原因不復(fù)雜App Router 的 Server Component 可以讓我在服務(wù)端直接調(diào)用 tRPC Procedure避免很多組件變成 Client Component頁(yè)面也更容易拿搜索引擎的分?jǐn)?shù)。但我也必須誠(chéng)實(shí)提醒App Router 的學(xué)習(xí)曲線明顯更陡如果你是第一次接觸建議先花半天把一個(gè) React Server Component 和 Client Component 的邊界理清楚再來(lái)用 tRPC。在 App Router 下t3code 的做法是頁(yè)面主體邏輯盡量放 Server Component只有需要交互的局部區(qū)域比如搜索框、表格操作按鈕、篩選器用use client。數(shù)據(jù)獲取統(tǒng)一走服務(wù)端調(diào)用 tRPC 的createCaller而不是在客戶端useQuery。這樣首屏 HTML 里已經(jīng)有數(shù)據(jù)瀏覽器端不需要先發(fā)一堆請(qǐng)求再渲染骨架屏體驗(yàn)好很多。2.3 補(bǔ)齊 tRPC 客戶端 Context否則瀏覽器里全是 404這里我要說(shuō)一個(gè)特別容易踩、但又特別隱蔽的坑。如果你在非 Server Component 環(huán)境調(diào)用api.user.getAll.useQuery()而項(xiàng)目里沒(méi)有在根布局或者TRPCReactProvider里掛載 Context Provider瀏覽器控制臺(tái)只會(huì)給你一片 404。原因很簡(jiǎn)單tRPC 客戶端的 hooks 需要 Provider 才能拿到正確的 URL 和請(qǐng)求方法Provider 沒(méi)掛請(qǐng)求路徑不會(huì)自動(dòng)注冊(cè)到 Next.js 的 route handler 上。t3code 的寫(xiě)法是在app/layout.tsx里用TRPCReactProvider包住整個(gè)頁(yè)面Provider 內(nèi)部再包一層headers()讀取服務(wù)端返回的 cookies確保服務(wù)端渲染和客戶端渲染兩邊拿到的請(qǐng)求頭一致。這個(gè)細(xì)節(jié)如果不做部分頁(yè)面在 SSR 下可能正常一旦客戶端導(dǎo)航就出問(wèn)題Debug 起來(lái)非常費(fèi)勁因?yàn)閳?bào)錯(cuò)不一定指向 Provider。3. Prisma 從 SQLite 遷到 PostgreSQL 時(shí)我踩過(guò)的三個(gè)數(shù)據(jù)坑3.1 第一個(gè)坑SQLite 習(xí)慣寫(xiě)進(jìn) schemaPostgres 直接給你顏色t3code 開(kāi)發(fā)早期為了零配置我直接用 SQLite 當(dāng)數(shù)據(jù)庫(kù)。本地跑得很爽直到我決定把數(shù)據(jù)庫(kù)換成 PostgreSQL準(zhǔn)備上生產(chǎn)環(huán)境的時(shí)候才發(fā)現(xiàn) schema 里有好幾個(gè)字段是為 SQLite 量身定做的。最典型的是String default()這種寫(xiě)法。SQLite 對(duì)空串處理很佛系但 PostgreSQL 里有些字段類型會(huì)在空串和空值之間產(chǎn)生語(yǔ)義沖突比如Decimal類型存儲(chǔ)空串會(huì)直接報(bào)錯(cuò)。另一個(gè)坑是枚舉類型SQLite 不原生支持enumPrisma 會(huì)退化成字符串檢查一換到 PostgreSQL模型定義就必須顯式聲明枚舉舊數(shù)據(jù)里如果有枚舉外的值遷移會(huì)失敗。我的建議是從第一天就用 PostgreSQL 或者 MySQL 來(lái)開(kāi)發(fā)哪怕本地跑 Docker 也要用生產(chǎn)同款數(shù)據(jù)庫(kù)?，F(xiàn)在 Docker 起一個(gè) Postgres 只要一分鐘不要在“反正后面會(huì)換”上面省時(shí)間。3.2 第二個(gè)坑BigInt 與 Date 在 tRPC 傳輸層的序列化問(wèn)題Prisma 里有幾個(gè)字段類型會(huì)在 JSON 序列化時(shí)產(chǎn)生意外。最典型的是BigInt。PostgreSQL 的某些計(jì)數(shù) ID 用了BigIntPrisma 返回的是一個(gè) JavaScript BigInt 對(duì)象可 JSON.stringify 根本不支持 BigInt默認(rèn)直接拋TypeError: Do not know how to serialize a BigInt。這個(gè)問(wèn)題在沒(méi)有 tRPC 的時(shí)候也存在但因?yàn)?tRPC 會(huì)自動(dòng)做序列化報(bào)錯(cuò)信息會(huì)出現(xiàn)在運(yùn)行時(shí)更隱蔽。t3code 的處理方式是給這些字段定義明確的數(shù)據(jù)傳輸對(duì)象DTO在 tRPC Router 的返回處就把BigInt轉(zhuǎn)成字符串或者 Number。另外一個(gè)常見(jiàn)問(wèn)題是 Date 對(duì)象Prisma 返回的 Date 在 tRPC 里會(huì)變成 ISO 字符串前端做時(shí)間格式化的時(shí)候如果直接new Date(value)還能用但如果拿它做value instanceof Date的判斷就會(huì)出問(wèn)題。所以我的原則是跨 tRPC 邊界的日期統(tǒng)一用字符串傳遞顯示格式統(tǒng)一在展示層處理絕不把 Date 對(duì)象直接往 client 丟。3.3 第三個(gè)坑connection pool 和事務(wù)隔離級(jí)別少一次壓測(cè)都不知道本地 SQLite 是一次連接一個(gè)文件幾乎沒(méi)有并發(fā)問(wèn)題。但 PostgreSQL 在 Serverless 環(huán)境下的連接數(shù)是非常稀缺的資源尤其是部署到 Vercel 或 Netlify 這類無(wú)服務(wù)器平臺(tái)時(shí)Prisma Client 如果不做連接池管理每個(gè) Lambda 實(shí)例可能都會(huì)去搶數(shù)據(jù)庫(kù)連接稍微有點(diǎn)流量連接數(shù)就爆了。t3code 后面部署到一臺(tái)小云主機(jī)上用常駐 Node 進(jìn)程跑遇到的情況是Prisma 默認(rèn)的事務(wù)隔離級(jí)別在并發(fā)寫(xiě)多的時(shí)候會(huì)產(chǎn)生大量重試異常看起來(lái)像是“偶發(fā)報(bào)錯(cuò)”但壓測(cè)一上就原形畢露。我建議你在寫(xiě)涉及多表更新的 mutation 時(shí)提前想清楚這個(gè)事務(wù)的隔離級(jí)別并且使用 Prisma 的連接池配置比如?connection_limit5pool_timeout2這類參數(shù)。平時(shí)看起來(lái)無(wú)關(guān)緊要到了并發(fā)場(chǎng)景就是能不能扛住壓測(cè)的分水嶺。4. tRPC 路由不是簡(jiǎn)單拆文件中間件、上下文與錯(cuò)誤碼設(shè)計(jì)4.1 從 createTRPCRouter 到隱式依賴先說(shuō)說(shuō) tRPC 路由的組織方式。很多人第一次接觸 tRPC會(huì)以為它就是把 API Routes 換個(gè)寫(xiě)法路由文件拆得多了自然就有結(jié)構(gòu)。但實(shí)際上 tRPC 有一個(gè)更重要的隱式依賴路由會(huì)攜帶一個(gè)共享的 Context。這個(gè) Context 是你每次請(qǐng)求的“環(huán)境快照”里面可以放數(shù)據(jù)庫(kù)實(shí)例、當(dāng)前登錄用戶、請(qǐng)求頭信息等。所有 Procedure 都能訪問(wèn)這份 Context所以路由設(shè)計(jì)得好不好很大程度取決于 Context 設(shè)計(jì)得好不好。t3code 的 Context 里我放了三樣?xùn)|西Prisma Client 實(shí)例、session對(duì)象可能為 null、以及一個(gè)表示“當(dāng)前請(qǐng)求是否來(lái)自客戶端”的isClient布爾值。中間件再根據(jù) Context 里的 session 狀態(tài)決定放行還是拒絕。如果想把 Context 設(shè)計(jì)好一個(gè)習(xí)慣是永遠(yuǎn)不要在生產(chǎn)路由里直接讀文件或者請(qǐng)求體所有依賴都通過(guò) Context 注入后續(xù)測(cè)試會(huì)輕松很多。4.2 一個(gè)全局 middleware 能省掉多少 if這里的核心是避免在每一個(gè) mutation 里寫(xiě)一大段“如果是管理員就怎么樣”的邏輯。t3code 里我套了兩層中間件第一層是全局的只做基本日志和耗時(shí)記錄第二層是“需要登錄”的中間件掛在所有需要身份校驗(yàn)的路由組上。這個(gè)中間件的寫(xiě)法非常直白const protectedProcedure tRPC.procedure.use(async ({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED, message: 登錄后才能執(zhí)行這個(gè)操作, }); } return next({ ctx: { ...ctx, user: ctx.session.user, }, }); });之后任何需要登錄的接口都直接用protectedProcedure不需要在業(yè)務(wù)代碼里再判斷session。如果你有十幾個(gè)查詢都要做登錄校驗(yàn)這一個(gè)中間件就能刪掉十幾遍重復(fù)邏輯。更關(guān)鍵的是后面加權(quán)限系統(tǒng)也只需要在中間件里多套一層業(yè)務(wù)代碼一行都不用改。4.3 錯(cuò)誤碼與錯(cuò)誤信息的結(jié)構(gòu)約定tRPC 自帶的錯(cuò)誤碼體系已經(jīng)覆蓋了常見(jiàn)情況比如BAD_REQUEST、UNAUTHORIZED、FORBIDDEN、NOT_FOUND、INTERNAL_SERVER_ERROR。但這里有個(gè)容易忽略的點(diǎn)默認(rèn)的message是字面量英文而前端用戶根本看不到也不應(yīng)該看到。我的做法是在前端統(tǒng)一封裝一個(gè)errorMapper函數(shù)把 tRPC 的 error shape 映射成用戶可讀的中文文案同時(shí)把code傳給日志系統(tǒng)。另外不要把業(yè)務(wù)錯(cuò)誤全拋成INTERNAL_SERVER_ERROR否則你查日志會(huì)瘋掉。比如用戶傳了一個(gè)不存在的 ID就應(yīng)該拋NOT_FOUND權(quán)限不夠就拋FORBIDDEN。我見(jiàn)過(guò)很多半路出家的項(xiàng)目不管什么錯(cuò)誤都是BAD_REQUEST排查起來(lái)完全靠猜。錯(cuò)誤碼的語(yǔ)義化是工程成熟度非常顯性的信號(hào)。5. NextAuth 接入 tRPC 受保護(hù)路由的完整鏈路5.1 為什么在 App Router 下不能直接用舊版 session 寫(xiě)法NextAuth 在 Pages Router 時(shí)代最常用的拿 session 方式是getSession()在服務(wù)端getServerSideProps里每次請(qǐng)求調(diào)用一次。但在 App Router 下推薦的做法是getServerSession()配合authOptions從請(qǐng)求頭里恢復(fù) session。t3code 一開(kāi)始沒(méi)注意這個(gè)區(qū)別我照舊用getSession()在 Server Component 里取數(shù)據(jù)某天突然發(fā)現(xiàn)部分頁(yè)面在刷新時(shí)會(huì)拿到 null而客戶端導(dǎo)航時(shí)又是正常的。最后定位下來(lái)是因?yàn)間etSession()依賴的請(qǐng)求上下文在 App Router 的 Server Component 里不一定能拿到完整的 cookies 和 headers導(dǎo)致 session 讀取不穩(wěn)定。換成getServerSession后這個(gè)問(wèn)題就消失了。如果你用 NextAuth v5現(xiàn)在是 Auth.js那一套 API 又會(huì)變所以我的建議是不要憑記憶寫(xiě)每次都要確認(rèn)當(dāng)前版本對(duì)應(yīng)的官方示例這種基礎(chǔ)鏈路不值得省那兩分鐘。5.2 Auth.ts 與 tRPC context 的橋接t3code 里最關(guān)鍵的橋接文件是把 tRPC 的 Context 和 NextAuth 的 Session 連起來(lái)?；咀龇ㄊ窃赾reateContext里并行調(diào)用getServerSession把返回的 session 塞給 tRPC。這里有個(gè)實(shí)操細(xì)節(jié)第一次請(qǐng)求時(shí)Prisma Client、session 這些對(duì)象都會(huì)被初始化如果你的選擇器頻繁創(chuàng)建 PrismaClient熱更新階段會(huì)有大量連接殘留所以一定記得用全局單例模式。而生成了 session 之后要記得把 session 放到 Context 里而不是每次在路由里重新getServerSession否則你的 query 函數(shù)會(huì)變得很啰嗦而且沒(méi)法統(tǒng)一做緩存。5.3 Credentials Provider 的 JWT 坑t3code 早期為了簡(jiǎn)單用 NextAuth 的 Credentials Provider 實(shí)現(xiàn)郵箱密碼登錄。這個(gè) Provider 默認(rèn)不會(huì)把用戶 ID 寫(xiě)進(jìn) session而是把整個(gè)登錄請(qǐng)求交給 JWT 策略。這里有個(gè)坑如果你在signIn回調(diào)里沒(méi)有做足夠校驗(yàn)或者jwt回調(diào)里沒(méi)有把 userId 賦到 token 上前端拿到 session 時(shí)沒(méi)有 user.id然后 tRPC 中間件就會(huì)把明明已經(jīng)登錄的人當(dāng)成游客。正確做法是在jwt回調(diào)里手動(dòng)寫(xiě)入callbacks: { jwt({ token, user }) { if (user) { token.userId user.id; } return token; }, session({ session, token }) { if (session.user) { session.user.id token.userId as string; } return session; }, }這個(gè)看著不復(fù)雜但網(wǎng)上能搜到的案例大多只寫(xiě) GitHub 登錄沒(méi)有注意 Credentials Provider 的特殊性。如果你用第三方 OAuth 登錄可能不會(huì)觸發(fā)這個(gè)場(chǎng)景但一旦切到賬密登錄就非常容易卡在這里。6. 部署到生產(chǎn)環(huán)境后類型安全救不了你的那些時(shí)刻6.1 Vercel Serverless 環(huán)境下的 Prisma 連接池坦白說(shuō)t3code 部署到 Vercel 的第一版是在流量稍大時(shí)直接崩掉的。原因跟前面說(shuō)的數(shù)據(jù)庫(kù)連接池高度相關(guān)Vercel 的 Lambda 是短生命周期進(jìn)程每個(gè)實(shí)例啟動(dòng)時(shí)都會(huì)初始化 Prisma Client如果數(shù)據(jù)庫(kù)連接池的上限配置得太小一有流量波動(dòng)Prisma 就只能排隊(duì)等待。而排隊(duì)時(shí)間一旦超過(guò) Lambda 超時(shí)閾值用戶就會(huì)看到 504。我的解決方式其實(shí)很“土”在云廠商的數(shù)據(jù)庫(kù)參數(shù)里提高了最大連接數(shù)同時(shí)在 Prisma 的連接串上顯式設(shè)置了connection_limit和pool_timeout讓連接等待有上限。如果你用的是 Prisma 官方加速服務(wù)那又是另一套配置?？傊涀∫稽c(diǎn)本地跑得好不代表生產(chǎn)不會(huì)死連接池這個(gè)東西一定要在部署前想清楚。6.2 WebSocket 適配器在無(wú)狀態(tài)環(huán)境里的噩夢(mèng)如果想做實(shí)時(shí)更新很多人第一反應(yīng)是上 tRPC subscription。但請(qǐng)注意tRPC subscription 默認(rèn)依賴 WebSocket而 Vercel 這類 Serverless 平臺(tái)對(duì) WebSocket 的支持非常有限如果你部署到邊緣函數(shù)WebSocket 長(zhǎng)連接更是直接不可用。t3code 后來(lái)放棄在 Vercel 上做實(shí)時(shí)訂閱改到了常駐 Node 進(jìn)程的服務(wù)器上WebSocket 才穩(wěn)定下來(lái)。如果你一定要在 Serverless 環(huán)境用 subscription建議了解trpc/server的subscription適配器和平臺(tái)限制。很多項(xiàng)目的實(shí)時(shí)功能用輪詢就足夠了不一定非要長(zhǎng)連接。千萬(wàn)不要因?yàn)椤皩?shí)時(shí)”兩個(gè)字就把架構(gòu)搞得復(fù)雜輪詢 短緩存往往在 90% 的場(chǎng)景里都?jí)蛴谩?.3 環(huán)境變量與多環(huán)境配置zod 校驗(yàn)寫(xiě)在最前面環(huán)境變量是部署出錯(cuò)的高發(fā)區(qū)。t3code 的做法是用一個(gè) zod schema 在啟動(dòng)時(shí)校驗(yàn)所有關(guān)鍵環(huán)境變量缺哪個(gè)直接給你一個(gè)清晰的中文報(bào)錯(cuò)而不是等你運(yùn)行到某個(gè)接口才炸。比如DATABASE_URL、NEXTAUTH_SECRET、S3_BUCKET這些變量在 config 文件里統(tǒng)一讀取并校驗(yàn)。這樣做的另一個(gè)好處是如果把環(huán)境變量集中到一個(gè) TypeScript 文件IDE 提示會(huì)非常舒服而且新同事上手時(shí)看到這個(gè)文件就大概知道項(xiàng)目依賴哪些外部資源。這也是我從很多生產(chǎn)事故里學(xué)到的教訓(xùn)說(shuō)句實(shí)話類型安全能保證代碼內(nèi)部不出錯(cuò)但保證不了你部署環(huán)境的外部配置不出錯(cuò)多一道啟動(dòng)時(shí)校驗(yàn)比什么都強(qiáng)。7. t3code 下一步實(shí)時(shí)訂閱、文件上傳、可觀測(cè)性7.1 用 tRPC subscription 替換定時(shí)輪詢t3code 現(xiàn)在的消息列表已經(jīng)改成真實(shí)時(shí)更新了因?yàn)榉?wù)端不再受限于無(wú)狀態(tài)環(huán)境。tRPC subscription 的寫(xiě)法跟 query 非常接近核心還是在 router 里注冊(cè)subscription然后通過(guò)發(fā)布訂閱源把更新推給客戶端。這里有一個(gè)值得注意的設(shè)計(jì)不要在前端直接調(diào)用 subscription 的發(fā)布函數(shù)所有發(fā)布動(dòng)作都應(yīng)該由服務(wù)端業(yè)務(wù)觸發(fā)客戶端只能監(jiān)聽(tīng)。我在實(shí)際使用中的體會(huì)是tRPC subscription 的代碼量比 WebSocket 原生實(shí)現(xiàn)少得多可讀性也好適合中小型項(xiàng)目。但它對(duì)連接狀態(tài)的恢復(fù)處理不如成熟的消息隊(duì)列所以 websocket 斷線重連時(shí)的消息補(bǔ)償還得自己在業(yè)務(wù)層處理。這部分如果做得不好用戶可能錯(cuò)過(guò)重要通知。7.2 文件上傳不留服務(wù)器直接走后端簽名 URL很多初學(xué)者會(huì)把文件上傳寫(xiě)成POST /api/upload然后把文件寫(xiě)進(jìn)服務(wù)器磁盤(pán)。這在本地開(kāi)發(fā)沒(méi)事上了生產(chǎn)要么磁盤(pán)不夠要么負(fù)載均衡多個(gè)實(shí)例之間文件不同步。t3code 的做法是走 Object Storage比如 S3 兼容存儲(chǔ)上傳邏輯用預(yù)簽名 URL 實(shí)現(xiàn)前端先調(diào)用 tRPC 的getUploadUrlmutation傳入文件名和類型。后端返回一個(gè)短時(shí)有效的上傳 URL。前端直接用 PUT 或 POST 把文件流推到存儲(chǔ)服務(wù)不走應(yīng)用服務(wù)器。這個(gè)方案既減少服務(wù)器帶寬壓力又能避免接口被惡意塞大文件。我之前踩過(guò)一個(gè)坑是沒(méi)有限制上傳大小結(jié)果被一個(gè)同事傳了個(gè) 2GB 的視頻桶直接吃到告警。后來(lái)我加上了文件大小和后綴名校驗(yàn)總算沒(méi)再出事。7.3 加一層可觀測(cè)性把每次 query 的耗時(shí)暴露出來(lái)最后我想聊一個(gè)沒(méi)那么炫酷但非常重要的部分可觀測(cè)性。t3code 在中間件里給每個(gè) tRPC procedure 記錄了一條日志包含路徑、耗時(shí)、狀態(tài)碼、用戶 ID。這樣一旦線上有問(wèn)題我可以從日志里很快定位到具體是哪個(gè)查詢慢而不是等到用戶反饋。具體實(shí)現(xiàn)也很簡(jiǎn)單就是給 tRPC 加一個(gè)onError處理器和一個(gè)耗時(shí)中間件。日志不一定要上分布式鏈路追蹤剛開(kāi)始用控制臺(tái)輸出加一個(gè)結(jié)構(gòu)化日志文件就夠用。等哪天流量大了再引入 OpenTelemetry 也不遲。這個(gè)過(guò)程中最有價(jià)值的不是某個(gè)工具而是“把每一次請(qǐng)求都當(dāng)成可觀測(cè)事件”的工程習(xí)慣。t3code 這套搭建過(guò)程里我印象最深的反而不是某個(gè)具體 API而是類型安全帶來(lái)的正反饋循環(huán)數(shù)據(jù)庫(kù)結(jié)構(gòu)一變類型跟著變編譯就報(bào)錯(cuò)修復(fù)的速度遠(yuǎn)快于肉眼排查接口文檔。但也正因?yàn)樗验_(kāi)發(fā)體驗(yàn)拉得很高部署和運(yùn)維階段的坑反而容易被忽略。如果你打算用 T3 Stack 做自己的項(xiàng)目我建議不要只盯著框架的花哨功能先把 Context、中間件、錯(cuò)誤碼、連接池這些基建打扎實(shí)很多線上問(wèn)題是可以提前避免的。