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