調鏈路)
1. t3code在解決什么問題一次全棧項目選型的真實算賬t3code是我在GitHub上維護的一套全棧樣板工程核心思路很樸素把 Next.js、TypeScript、tRPC、Prisma、Tailwind 這五個工具以類型安全為共同主線串成一個開箱即用的底座。很多人第一次看到 T3 Stack 會覺得它是網紅技術棧真正用起來才發(fā)現(xiàn)它解決的問題非常具體——前后端聯(lián)調時那種接口文檔寫了等于沒寫、改個字段兩邊同時炸的尷尬在 t3code 這套架構里會大幅減少。1.1 傳統(tǒng)分工模式里類型斷裂的代價被低估了先說說我為什么最終選了這套方案。早幾年做全棧項目最常見的結構是前端一個倉庫、后端一個倉庫前端用 Axios 手寫接口調用后端用 Swagger 出文檔。這種模式在項目小的時候很順暢一旦業(yè)務復雜起來問題就暴露了后端改了接口返回結構前端只要沒及時更新類型定義運行時大概率直接拿不到字段。接口文檔要么沒人維護要么反序列化類型和真實返回根本對不上聯(lián)調階段一半時間在扯皮。所有接口調用都得手寫一遍類型聲明一百個接口就是一百份重復勞動模板代碼多到讓人麻木。t3code 這套東西最核心的思路就是把這些手寫類型的環(huán)節(jié)改成自動推導。數(shù)據(jù)庫表結構由 Prisma 的 schema 定義類型從 schema 生成后端接口由 tRPC 的 router 定義前端調用方可以直接復用同一套類型。換句話說類型不是人寫的而是從源頭流出來的。我第一次跑通這條鏈路的時候感覺最明顯的變化是前后端對字段的理解從約定變成了編譯期強制。1.2 選型時我也對比過其他方案不只是跟風可能有人會說Next.js 自帶 API Route也可以用 GraphQL為什么偏偏選 tRPC我實際對比過幾種方案方案類型穿透能力學習成本服務端緩存/鑒權靈活性適合場景REST 手寫類型弱需要維護兩份代碼低高完全自定義團隊已有成熟規(guī)范GraphQL codegen中等需要生成步驟中高中需要自己處理緩存復雜聚合查詢、多端復用Next.js API Route fetch弱仍需額外類型層低高簡單項目夠用tRPC強端到端自動推導中理解泛型需要時間中高procedure 可包裝鑒權全棧 TypeScript 團隊真實體驗下來tRPC 并不是萬能的。如果你的項目需要給第三方提供公開 API或者前端不只是 Web 端還有大量小程序/移動端REST 或者 GraphQL 仍然是更穩(wěn)的選擇。t3code 的定位是內部全棧項目尤其是一個團隊同時寫前端和后端的場景。類型穿透的優(yōu)勢在這個場景下被放到最大而對外暴露接口的劣勢則不太重要。1.3 t3code 的邊界感它不是什么都能干我特別想強調一點t3code 不是拿來即用的業(yè)務框架它更像一個骨架清晰的最小可運行系統(tǒng)。你拿它起步能省掉配環(huán)境、折騰連接、搭建目錄結構的瑣碎時間但業(yè)務邏輯還是要自己寫。它也不會替你決定部署方式、數(shù)據(jù)庫到底用 PostgreSQL 還是 MySQL、組件庫用哪個——這些是需要你自己拍板的部分。如果你正處在一個想試試全棧 TypeScript但不知道從哪下手的狀態(tài)或者被前后端類型不一致的 bug 折磨過這篇文章接下來的內容會很有用。我會把 t3code 的骨架邏輯、一個真實功能的落地過程以及我在生產環(huán)境里踩過的坑一條一條拆開講。2. 骨架拆解五個核心成員是怎么咬合在一起的開始實戰(zhàn)之前有必要先把 t3code 的骨架邏輯講清楚。這五個工具各司其職但真正讓它們產生化學反應的是彼此之間的接口設計。理解了這個咬合關系后面遇到報錯時你能更快判斷問題出在哪一層。2.1 Next.js 是底座App Router 決定了邊界的劃分t3code 基于 Next.js 的 App Router 構建。App Router 帶來的一個關鍵變化是服務端組件和客戶端組件的邊界。服務端組件在服務器上執(zhí)行可以直接訪問數(shù)據(jù)庫、讀取環(huán)境變量代碼不會打包到瀏覽器?？蛻舳私M件需要標記use client在瀏覽器里運行負責交互邏輯。這個邊界對類型安全很重要。t3code 里的 tRPC 在服務端可以直接調用在客戶端則需要走一個專門的 hooks 封裝。你要做的是清晰地區(qū)分哪些邏輯必須在服務端處理比如直接查庫、處理密鑰相關的操作和哪些邏輯必須交給瀏覽器比如點擊事件、表單狀態(tài)。我在剛上手時經常犯的錯是把所有組件都寫成客戶端組件導致服務端該干的事跑到瀏覽器里去干類型倒是沒崩性能和安全性先崩了。2.2 tRPC 是無文檔的契約tRPC 的特別之處在于它不需要你寫接口文檔也不需要你手寫類型定義。你在服務端定義了一個 router// server/api/routers/post.ts import { createTRPCRouter, publicProcedure } from ~/server/api/trpc; import { z } from zod; export const postRouter createTRPCRouter({ list: publicProcedure.query(async ({ ctx }) { return ctx.db.post.findMany({ orderBy: { createdAt: desc }, }); }), create: publicProcedure .input(z.object({ title: z.string().min(1), content: z.string().optional(), })) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: input }); }), });前端調用時類型會被自動推斷出來連輸入參數(shù)的校驗規(guī)則都是同一份// app/_components/post-list.tsx use client; import { api } from ~/trpc/react; export function PostList() { const { data: posts, refetch } api.post.list.useQuery(); const createPost api.post.create.useMutation({ onSuccess: () refetch(), }); return ( div {posts?.map((post) ( div key{post.id} h3{post.title}/h3 {post.content p{post.content}/p} /div ))} button onClick{() createPost.mutate({ title: 新文章, content: 內容 }) } 新建 /button /div ); }注意這里的api.post.list.useQuery()不是普通的函數(shù)它背后是 React Query 的 hooks。也就是說緩存、重試、請求狀態(tài)管理這些邏輯也被 tRPC 的 React 封裝一并處理了不需要你再單獨引入一套數(shù)據(jù)請求方案。2.3 Prisma 是類型的源頭在 t3code 里數(shù)據(jù)庫表結構由 Prisma 的 schema 定義。你只要維護一個schema.prisma文件Prisma 就能生成對應的 TypeScript 類型和 Client。這意味著數(shù)據(jù)庫字段變成代碼里的類型這個環(huán)節(jié)是自動的不存在數(shù)據(jù)庫改了個字段代碼里忘了同步的問題。generator client { provider prisma-client-js } datasource db { provider postgresql url env(DATABASE_URL) } model Post { id String id default(cuid()) title String content String? createdAt DateTime default(now()) updatedAt DateTime updatedAt }執(zhí)行npx prisma migrate dev之后ctx.db.post.findMany()里返回的post對象就是帶類型的。這個類型再被 tRPC 的返回值攜帶一路傳到前端組件整個鏈路就通了。我在實際使用中最喜歡的細節(jié)是改 schema 之后只要重新生成 Prisma Client前端代碼馬上會報出所有字段名對不上的地方這種安全感是傳統(tǒng)接口聯(lián)調給不了的。2.4 Tailwind 是樣式層但要配合組件規(guī)范Tailwind 在 t3code 里承擔的是樣式職責。它本身和上面的類型鏈路關系不大但它決定了樣板工程的 UI 長什么樣。我是這么看 Tailwind 的它可以讓你不寫 CSS 文件就完成大部分布局但如果完全靠 utility class 堆頁面后期維護會更吃力。在 t3code 里我會建議搭配一個組件庫比如 shadcn/ui來收斂樣式原子。Tailwind 負責基礎原子類組件庫負責提供結構化的組件業(yè)務頁面只關心數(shù)據(jù)和布局不用每次從零拼按鈕和輸入框。這個組合用起來比較順手也不容易出現(xiàn)改一個按鈕樣式要翻十幾個文件的窘境。2.5 一張圖看完整鏈路如果把它們的關系簡化為一條數(shù)據(jù)流大概是這樣的Prisma Schema → 數(shù)據(jù)庫表 TypeScript 類型 ↓ tRPC Router → 輸入校驗 業(yè)務邏輯 類型導出 ↓ React Query Hooks → 狀態(tài)管理 緩存 ↓ React 組件 → 渲染與交互這條鏈路的每一個環(huán)節(jié)類型的承重墻都是自動生成的人只負責寫業(yè)務邏輯。理解了這點后面排查問題時會非常有用——當你看到一個類型報錯你要判斷的其實是它發(fā)生在哪一層數(shù)據(jù)庫層、接口層、還是組件層。3. t3code 實戰(zhàn)落地從數(shù)據(jù)庫到頁面的類型閉環(huán)理論講完接下來把袖子擼起來。我用一個真實的例子——從初始化項目到實現(xiàn)一個帶數(shù)據(jù)庫寫入和列表展示的完整功能——帶你跑一遍 t3code 的落地過程。3.1 初始化項目交互式命令行里有哪些選項先說明一下如果你要手動復刻 t3code 的結構最直接的方式是用官方腳手架生成一個同構項目npx create-t3-applatest my-app執(zhí)行命令后交互式界面會問你要不要啟用 Tailwind、tRPC、Prisma、NextAuth 等模塊。我的建議是如果只是學類型閉環(huán)Prisma 和 tRPC 必須勾上。NextAuth 可以先不勾它處理的是鑒權邏輯第一次上手時容易把注意力從類型鏈路上帶偏。Tailwind 建議勾上即使你不用它后續(xù)調整界面也方便。腳手架生成完之后目錄結構大致是這樣的prisma/ schema.prisma src/ server/ api/ root.ts # 匯總所有子 router routers/ post.ts # 業(yè)務 router trpc.ts # tRPC 實例與上下文 db.ts # Prisma Client 單例 trpc/ react.tsx # 客戶端 tRPC provider 與 hooks server.ts # 服務端 tRPC caller可選 app/ api/trpc/[trpc]/ route.ts # tRPC 的 HTTP 入口 _components/ post-list.tsx page.tsx這個結構本身是 t3code 的核心價值——它把所有樣板代碼和配置文件都擺好了你不用從空白開始思考tRPC 掛在哪個文件、Prisma Client 怎么全局共享這類問題。3.2 配置數(shù)據(jù)庫環(huán)境變量與連接串的講究默認情況下腳手架會用 SQLite 起步但我建議你直接換成 PostgreSQL 或者 MySQL因為生產環(huán)境基本不會用 SQLite。修改prisma/schema.prismadatasource db { provider postgresql url env(DATABASE_URL) }然后在.env里配置DATABASE_URLpostgresql://user:passwordlocalhost:5432/t3code這里有一個很容易踩的坑不要把包含敏感信息的 .env 文件提交到 Git。腳手架生成的.gitignore通常已經幫你把.env排除掉了但如果你是自己手動搭的環(huán)境一定要檢查確認。數(shù)據(jù)庫連接串相當于數(shù)據(jù)庫的鑰匙泄露出去就是一個嚴重的安全事故。配置好之后在 schema 里加上最簡單的 Post 模型然后執(zhí)行遷移npx prisma migrate dev --name init這個命令會把變更同步到數(shù)據(jù)庫同時生成 Prisma Client。如果沒有任何報錯你打開src/server/db.ts里面應該是這樣的import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma?: PrismaClient }; export const db globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV ! production) { globalForPrisma.prisma db; }這個全局單例的模式很關鍵。它確保在開發(fā)環(huán)境的模塊熱更新HMR過程中不會因為每次文件變更都創(chuàng)建新的 Prisma Client 而導致連接數(shù)暴增。不寫這個單例開發(fā)到一半你可能會看到數(shù)據(jù)庫連接被占滿的警告。3.3 寫第一個 tRPC 接口從 router 到頁面接下來定義一個 post router并在根 router 里注冊// src/server/api/root.ts import { createTRPCRouter } from ~/server/api/trpc; import { postRouter } from ~/server/api/routers/post; export const appRouter createTRPCRouter({ post: postRouter, }); export type AppRouter typeof appRouter;回到之前那個例子——我們已經有l(wèi)ist和create兩個 procedure 了?，F(xiàn)在重點是理解前端如何調用。在服務的入口處t3code 已經把 HTTP 路由掛好了src/app/api/trpc/[trpc]/route.ts所以前端不需要關心請求路徑。你只需要在客戶端組件里使用api對象use client; import { api } from ~/trpc/react; export function PostList() { const utils api.useUtils(); const { data: posts, isLoading } api.post.list.useQuery(); const createPost api.post.create.useMutation({ onSuccess: () utils.post.list.invalidate(), }); if (isLoading) return divLoading.../div; return ( div {posts?.map((post) ( div key{post.id}{post.title}/div ))} button onClick{() createPost.mutate({ title: Hello t3code })} 新增 /button /div ); }這里你可能注意到我沒有用refetch而是用了utils.post.list.invalidate()。這是 React Query 比較推薦的做法讓緩存失效后自動重新拉取而不是手動觸發(fā)請求。在 t3code 里React Query 的緩存策略可以按業(yè)務場景定制比如設置staleTime減少不必要的請求。3.4 類型是怎么流動的以及為什么你不會漏改字段很多人第一次看 t3code 會有個疑問前端代碼明明沒有導入任何后端類型為什么posts是帶類型的答案在于 tRPC 的泛型推導。api.post.list.useQuery()的api對象是createTRPCReactAppRouter()生成的而AppRouter又是typeof appRouter。所以TypeScript 會把appRouter里所有 router 的輸入輸出類型全部推導出來并注入到前端的 hooks 類型參數(shù)中。這相當于一個全項目的類型地圖前端不需要手動 import編輯器自動補全就能看到返回字段。這套機制帶來的實際效果是如果后端list返回值從{ title: string }變成了{ title: string; content: string }前端除非顯式解構字段否則不會報錯但如果后端改了字段名比如title改成name前端所有用到post.title的地方會立即標紅。這種改錯名十分鐘內發(fā)現(xiàn)的體驗在傳統(tǒng)接口聯(lián)調里幾乎不敢想。4. 生產環(huán)境最容易翻車的坑和完整的排查鏈路t3code 這套架構本地跑得很順但一到生產環(huán)境還是有幾個高頻問題我一個個說清楚包括排查思路和解決方案。4.1 數(shù)據(jù)庫連接被邊緣函數(shù)打滿Prisma 連接池配置如果你把 Next.js 部署到 Vercel 這類邊緣/Serverless 環(huán)境會遇到一個特別典型的坑Prisma Client 默認創(chuàng)建的連接池和 Serverless 按需啟動的短生命周期實例不匹配。現(xiàn)象是請求量稍微上來之后數(shù)據(jù)庫報錯P1001連接超時或者后臺看到大量閑置連接。原因是每個 Serverless 實例都會創(chuàng)建自己的 Prisma Client實例銷毀時連接池來不及釋放積少成多。排查鏈路先看日志是不是PrismaClientInitializationError或者連接數(shù)告警。確認是否每個 function 實例都持有了數(shù)據(jù)庫連接。解決方向有兩個一個是在數(shù)據(jù)庫里把直接連接地址和連接池地址分開一個是用外置連接池。在我的 t3code 倉庫里推薦的做法是在.env里區(qū)分兩個變量DATABASE_URLpostgresql://user:passwordhost:5432/db?pgbouncertrueconnection_limit1 DIRECT_URLpostgresql://user:passwordhost:5432/db然后在 schema 里聲明datasource db { provider postgresql url env(DATABASE_URL) directUrl env(DIRECT_URL) }DATABASE_URL走連接池適合 Prisma Client 在 Serverless 環(huán)境里頻繁創(chuàng)建連接DIRECT_URL走直連適合執(zhí)行遷移命令時使用。遷移的時候不需要連接池直連更可靠。4.2 tRPC 類型不同步兩端的版本斷裂t3code 的強項是類型穿透但如果你把前后端拆成兩個倉庫部署或者一個倉庫里前后端依賴版本不一致就會出現(xiàn)后端新加了一個 procedure前端類型卻沒更新的情況。這種斷裂在 monorepo 結構里尤其常見。典型報錯是前端調用api.xxx.yyy時TypeScript 提示Property yyy does not exist on type ...。排查鏈路確認是否運行過npm install確保trpc/server和trpc/react-query版本一致。確認src/server/api/root.ts里新 router 有沒有正確注冊。清掉 TypeScript 的增量緩存npx tsc --noEmit如果仍報錯再看編輯器里的 TypeScript 服務是否舊緩存重啟 TS Server。如果你用了 monorepo檢查子包之間的依賴是否指向了舊構建產物必要時重新 build。這類問題的根源基本不在代碼而在類型生成層沒有同步。我建議把prisma generate和類型檢查放進 CI 流程任何一步沒跑過都不允許合并。4.3 App Router 的use client邊界錯誤使用帶來的混亂App Router 出現(xiàn)之后哪些組件能直接用 tRPC hooks成了新問題。tRPC 的 React hooks 依賴客戶端狀態(tài)React Query 的 Provider所以只能在客戶端組件里調用。但是很多新手會把整個頁面都標成use client導致服務端組件完全失效首屏渲染變成瀏覽器渲染性能明顯下滑。正確做法是頁面外殼保持服務端組件只有需要交互的葉子組件按鈕、表單、列表容器單獨標記use client。比如在 t3code 里一個典型的服務端頁面骨架// app/page.tsx服務端組件 import { PostList } from ./_components/post-list; export default function HomePage() { return ( main h1文章列表/h1 PostList / /main ); }而PostList內部才是一個客戶端組件。這樣做的好處是頁面首屏可以靜默渲染只有列表區(qū)域在客戶端進行交互。如果你發(fā)現(xiàn)自己把use client寫到了頁面最頂層就要停下來想想是不是所有代碼都真的需要運行在瀏覽器上。排查思路用 React DevTools 看組件是否被正確區(qū)分為 Server/Client用構建產物檢查瀏覽器 bundle 的大小如果服務端代碼被打進去了邊界就出問題了。4.4 Zod 校驗失敗時的模糊報錯tRPC 的輸入校驗依賴 Zod。當你傳的參數(shù)不合法時報錯信息有時會比較原始尤其是嵌套對象里的字段名錯誤容易看得一頭霧水。我踩過的一個典型例子createPost.mutate({ title: });z.string().min(1)會拋錯但如果你沒有配置全局錯誤處理或者前端顯示邏輯用戶只會看到一個籠統(tǒng)的錯誤。解決辦法是在客戶端統(tǒng)一做錯誤映射const createPost api.post.create.useMutation({ onError: (err) { const message err.shape?.message ?? 請求失敗; // 在這里把 message 展示給用戶 }, });生產環(huán)境里我建議前端對用戶輸入先做一層 UI 校驗比如禁用按鈕、提示必填Zod 校驗作為后端兜底。這樣既保證用戶體驗流暢也不會依賴后端錯誤提示的文案質量。5. 部署收尾連接池、邊緣函數(shù)與構建配置最后聊聊把 t3code 從開發(fā)機推到生產環(huán)境時我在部署層面整理的幾條經驗。5.1 數(shù)據(jù)庫連接方案按部署環(huán)境區(qū)分前面已經提到連接池的問題這里再細化一下。在生產環(huán)境我通常給數(shù)據(jù)庫配置兩個連接地址DATABASE_URL給應用運行時使用走連接池比如通過外部連接池服務或者數(shù)據(jù)庫自帶的連接池端口。DIRECT_URL給prisma migrate deploy這類遷移命令使用直連更穩(wěn)定。如果是 PostgreSQL還建議設置合理的connection_limit。在 Serverless 場景下單個實例的并發(fā)請求數(shù)通常很小connection_limit1是合理的起點。不要把它設得太大否則實例一多連接數(shù)會迅速膨脹。5.2 構建階段的類型檢查不要跳過t3code 的腳手架在構建時會默認跑tsc --noEmit和next build。很多人嫌慢會在 CI 里把類型檢查關掉這是個典型隱患。類型安全是這個架構的地基如果構建階段不檢查類型等于把自動推導的優(yōu)勢白白扔掉了。我的建議是本地開發(fā)npm run dev可以跳過完整類型檢查保證熱更新速度。CI/生產構建必須跑npm run build它會執(zhí)行完整類型檢查。首次啟動慢一點沒關系換來的是類型斷裂不會悄悄溜進生產。5.3 邊緣運行時Edge Runtime和 Node 運行時的選擇Next.js 頁面可以配置為 Edge Runtime 或 Node.js Runtime。tRPC 和 Prisma 有一些生態(tài)兼容性差異尤其是 Prisma它依賴 Node 的部分原生能力和 Edge Runtime 的兼容性并不總是理想。我的經驗是如果用了 Prisma就老老實實用 Node.js Runtime。Edge Runtime 的優(yōu)勢在于全球低延遲響應但前提是你的數(shù)據(jù)層也要跟著駐留邊緣否則請求最終還是得回源到數(shù)據(jù)庫所在區(qū)域優(yōu)化效果非常有限。在 t3code 里我會讓 API 路由和頁面都使用默認的 Node.js Runtime優(yōu)先保證穩(wěn)定性和功能完整。5.4 環(huán)境變量的三個必須部署到托管平臺不管 Vercel、Netlify 還是自建 Node 服務環(huán)境變量都要單獨檢查一遍漏掉任何一個都會在運行時出問題。我的檢查清單是DATABASE_URL和DIRECT_URL是否正確指向生產數(shù)據(jù)庫。NODE_ENV是否自動設置為production大多數(shù)平臺會自動處理。是否有任何第三方服務的密鑰、公開地址被硬編碼進代碼里。另外有一點要特別提醒前端的構建產物里不要包含任何服務端密鑰。Next.js 里只有以NEXT_PUBLIC_開頭的環(huán)境變量才會被打進瀏覽器 bundle其他變量只在服務器端可見。在 t3code 里數(shù)據(jù)庫連接串永遠不要以NEXT_PUBLIC_開頭否則等于把數(shù)據(jù)庫鑰匙掛在門口。最后聊幾句實際使用感受如果你現(xiàn)在正在糾結要不要仿照 t3code 的方式搭業(yè)務我的個人建議是先在一個小項目上試水而不要一上來就全量遷移。t3code 這套架構的好處是類型安全和開發(fā)體驗代價是你需要習慣所有東西都要先定義類型的思路。有些同學剛開始會覺得麻煩但跑通第一個功能后大多數(shù)人回不去手寫接口類型的日子。小技巧放最后開發(fā)時如果你發(fā)現(xiàn)編輯器卡頓或者類型提示不更新先試試重啟 TypeScript 服務如果問題還在再清node_modules/.cache。這類問題八成不是代碼錯誤而是 TypeScript 的增量緩存和 tRPC 的復雜泛型在較老的 IDE 版本上鬧脾氣。換新版本或者升級依賴后通常就好了。 t3code全棧樣板工程：以類型安全重構前后端聯(lián)調鏈路
1. t3code在解決什么問題一次全棧項目選型的真實算賬t3code是我在GitHub上維護的一套全棧樣板工程核心思路很樸素把 Next.js、TypeScript、tRPC、Prisma、Tailwind 這五個工具以類型安全為共同主線串成一個開箱即用的底座。很多人第一次看到 T3 Stack 會覺得它是網紅技術棧真正用起來才發(fā)現(xiàn)它解決的問題非常具體——前后端聯(lián)調時那種接口文檔寫了等于沒寫、改個字段兩邊同時炸的尷尬在 t3code 這套架構里會大幅減少。1.1 傳統(tǒng)分工模式里類型斷裂的代價被低估了先說說我為什么最終選了這套方案。早幾年做全棧項目最常見的結構是前端一個倉庫、后端一個倉庫前端用 Axios 手寫接口調用后端用 Swagger 出文檔。這種模式在項目小的時候很順暢一旦業(yè)務復雜起來問題就暴露了后端改了接口返回結構前端只要沒及時更新類型定義運行時大概率直接拿不到字段。接口文檔要么沒人維護要么反序列化類型和真實返回根本對不上聯(lián)調階段一半時間在扯皮。所有接口調用都得手寫一遍類型聲明一百個接口就是一百份重復勞動模板代碼多到讓人麻木。t3code 這套東西最核心的思路就是把這些手寫類型的環(huán)節(jié)改成自動推導。數(shù)據(jù)庫表結構由 Prisma 的 schema 定義類型從 schema 生成后端接口由 tRPC 的 router 定義前端調用方可以直接復用同一套類型。換句話說類型不是人寫的而是從源頭流出來的。我第一次跑通這條鏈路的時候感覺最明顯的變化是前后端對字段的理解從約定變成了編譯期強制。1.2 選型時我也對比過其他方案不只是跟風可能有人會說Next.js 自帶 API Route也可以用 GraphQL為什么偏偏選 tRPC我實際對比過幾種方案方案類型穿透能力學習成本服務端緩存/鑒權靈活性適合場景REST 手寫類型弱需要維護兩份代碼低高完全自定義團隊已有成熟規(guī)范GraphQL codegen中等需要生成步驟中高中需要自己處理緩存復雜聚合查詢、多端復用Next.js API Route fetch弱仍需額外類型層低高簡單項目夠用tRPC強端到端自動推導中理解泛型需要時間中高procedure 可包裝鑒權全棧 TypeScript 團隊真實體驗下來tRPC 并不是萬能的。如果你的項目需要給第三方提供公開 API或者前端不只是 Web 端還有大量小程序/移動端REST 或者 GraphQL 仍然是更穩(wěn)的選擇。t3code 的定位是內部全棧項目尤其是一個團隊同時寫前端和后端的場景。類型穿透的優(yōu)勢在這個場景下被放到最大而對外暴露接口的劣勢則不太重要。1.3 t3code 的邊界感它不是什么都能干我特別想強調一點t3code 不是拿來即用的業(yè)務框架它更像一個骨架清晰的最小可運行系統(tǒng)。你拿它起步能省掉配環(huán)境、折騰連接、搭建目錄結構的瑣碎時間但業(yè)務邏輯還是要自己寫。它也不會替你決定部署方式、數(shù)據(jù)庫到底用 PostgreSQL 還是 MySQL、組件庫用哪個——這些是需要你自己拍板的部分。如果你正處在一個想試試全棧 TypeScript但不知道從哪下手的狀態(tài)或者被前后端類型不一致的 bug 折磨過這篇文章接下來的內容會很有用。我會把 t3code 的骨架邏輯、一個真實功能的落地過程以及我在生產環(huán)境里踩過的坑一條一條拆開講。2. 骨架拆解五個核心成員是怎么咬合在一起的開始實戰(zhàn)之前有必要先把 t3code 的骨架邏輯講清楚。這五個工具各司其職但真正讓它們產生化學反應的是彼此之間的接口設計。理解了這個咬合關系后面遇到報錯時你能更快判斷問題出在哪一層。2.1 Next.js 是底座App Router 決定了邊界的劃分t3code 基于 Next.js 的 App Router 構建。App Router 帶來的一個關鍵變化是服務端組件和客戶端組件的邊界。服務端組件在服務器上執(zhí)行可以直接訪問數(shù)據(jù)庫、讀取環(huán)境變量代碼不會打包到瀏覽器?？蛻舳私M件需要標記use client在瀏覽器里運行負責交互邏輯。這個邊界對類型安全很重要。t3code 里的 tRPC 在服務端可以直接調用在客戶端則需要走一個專門的 hooks 封裝。你要做的是清晰地區(qū)分哪些邏輯必須在服務端處理比如直接查庫、處理密鑰相關的操作和哪些邏輯必須交給瀏覽器比如點擊事件、表單狀態(tài)。我在剛上手時經常犯的錯是把所有組件都寫成客戶端組件導致服務端該干的事跑到瀏覽器里去干類型倒是沒崩性能和安全性先崩了。2.2 tRPC 是無文檔的契約tRPC 的特別之處在于它不需要你寫接口文檔也不需要你手寫類型定義。你在服務端定義了一個 router// server/api/routers/post.ts import { createTRPCRouter, publicProcedure } from ~/server/api/trpc; import { z } from zod; export const postRouter createTRPCRouter({ list: publicProcedure.query(async ({ ctx }) { return ctx.db.post.findMany({ orderBy: { createdAt: desc }, }); }), create: publicProcedure .input(z.object({ title: z.string().min(1), content: z.string().optional(), })) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: input }); }), });前端調用時類型會被自動推斷出來連輸入參數(shù)的校驗規(guī)則都是同一份// app/_components/post-list.tsx use client; import { api } from ~/trpc/react; export function PostList() { const { data: posts, refetch } api.post.list.useQuery(); const createPost api.post.create.useMutation({ onSuccess: () refetch(), }); return ( div {posts?.map((post) ( div key{post.id} h3{post.title}/h3 {post.content p{post.content}/p} /div ))} button onClick{() createPost.mutate({ title: 新文章, content: 內容 }) } 新建 /button /div ); }注意這里的api.post.list.useQuery()不是普通的函數(shù)它背后是 React Query 的 hooks。也就是說緩存、重試、請求狀態(tài)管理這些邏輯也被 tRPC 的 React 封裝一并處理了不需要你再單獨引入一套數(shù)據(jù)請求方案。2.3 Prisma 是類型的源頭在 t3code 里數(shù)據(jù)庫表結構由 Prisma 的 schema 定義。你只要維護一個schema.prisma文件Prisma 就能生成對應的 TypeScript 類型和 Client。這意味著數(shù)據(jù)庫字段變成代碼里的類型這個環(huán)節(jié)是自動的不存在數(shù)據(jù)庫改了個字段代碼里忘了同步的問題。generator client { provider prisma-client-js } datasource db { provider postgresql url env(DATABASE_URL) } model Post { id String id default(cuid()) title String content String? createdAt DateTime default(now()) updatedAt DateTime updatedAt }執(zhí)行npx prisma migrate dev之后ctx.db.post.findMany()里返回的post對象就是帶類型的。這個類型再被 tRPC 的返回值攜帶一路傳到前端組件整個鏈路就通了。我在實際使用中最喜歡的細節(jié)是改 schema 之后只要重新生成 Prisma Client前端代碼馬上會報出所有字段名對不上的地方這種安全感是傳統(tǒng)接口聯(lián)調給不了的。2.4 Tailwind 是樣式層但要配合組件規(guī)范Tailwind 在 t3code 里承擔的是樣式職責。它本身和上面的類型鏈路關系不大但它決定了樣板工程的 UI 長什么樣。我是這么看 Tailwind 的它可以讓你不寫 CSS 文件就完成大部分布局但如果完全靠 utility class 堆頁面后期維護會更吃力。在 t3code 里我會建議搭配一個組件庫比如 shadcn/ui來收斂樣式原子。Tailwind 負責基礎原子類組件庫負責提供結構化的組件業(yè)務頁面只關心數(shù)據(jù)和布局不用每次從零拼按鈕和輸入框。這個組合用起來比較順手也不容易出現(xiàn)改一個按鈕樣式要翻十幾個文件的窘境。2.5 一張圖看完整鏈路如果把它們的關系簡化為一條數(shù)據(jù)流大概是這樣的Prisma Schema → 數(shù)據(jù)庫表 TypeScript 類型 ↓ tRPC Router → 輸入校驗 業(yè)務邏輯 類型導出 ↓ React Query Hooks → 狀態(tài)管理 緩存 ↓ React 組件 → 渲染與交互這條鏈路的每一個環(huán)節(jié)類型的承重墻都是自動生成的人只負責寫業(yè)務邏輯。理解了這點后面排查問題時會非常有用——當你看到一個類型報錯你要判斷的其實是它發(fā)生在哪一層數(shù)據(jù)庫層、接口層、還是組件層。3. t3code 實戰(zhàn)落地從數(shù)據(jù)庫到頁面的類型閉環(huán)理論講完接下來把袖子擼起來。我用一個真實的例子——從初始化項目到實現(xiàn)一個帶數(shù)據(jù)庫寫入和列表展示的完整功能——帶你跑一遍 t3code 的落地過程。3.1 初始化項目交互式命令行里有哪些選項先說明一下如果你要手動復刻 t3code 的結構最直接的方式是用官方腳手架生成一個同構項目npx create-t3-applatest my-app執(zhí)行命令后交互式界面會問你要不要啟用 Tailwind、tRPC、Prisma、NextAuth 等模塊。我的建議是如果只是學類型閉環(huán)Prisma 和 tRPC 必須勾上。NextAuth 可以先不勾它處理的是鑒權邏輯第一次上手時容易把注意力從類型鏈路上帶偏。Tailwind 建議勾上即使你不用它后續(xù)調整界面也方便。腳手架生成完之后目錄結構大致是這樣的prisma/ schema.prisma src/ server/ api/ root.ts # 匯總所有子 router routers/ post.ts # 業(yè)務 router trpc.ts # tRPC 實例與上下文 db.ts # Prisma Client 單例 trpc/ react.tsx # 客戶端 tRPC provider 與 hooks server.ts # 服務端 tRPC caller可選 app/ api/trpc/[trpc]/ route.ts # tRPC 的 HTTP 入口 _components/ post-list.tsx page.tsx這個結構本身是 t3code 的核心價值——它把所有樣板代碼和配置文件都擺好了你不用從空白開始思考tRPC 掛在哪個文件、Prisma Client 怎么全局共享這類問題。3.2 配置數(shù)據(jù)庫環(huán)境變量與連接串的講究默認情況下腳手架會用 SQLite 起步但我建議你直接換成 PostgreSQL 或者 MySQL因為生產環(huán)境基本不會用 SQLite。修改prisma/schema.prismadatasource db { provider postgresql url env(DATABASE_URL) }然后在.env里配置DATABASE_URLpostgresql://user:passwordlocalhost:5432/t3code這里有一個很容易踩的坑不要把包含敏感信息的 .env 文件提交到 Git。腳手架生成的.gitignore通常已經幫你把.env排除掉了但如果你是自己手動搭的環(huán)境一定要檢查確認。數(shù)據(jù)庫連接串相當于數(shù)據(jù)庫的鑰匙泄露出去就是一個嚴重的安全事故。配置好之后在 schema 里加上最簡單的 Post 模型然后執(zhí)行遷移npx prisma migrate dev --name init這個命令會把變更同步到數(shù)據(jù)庫同時生成 Prisma Client。如果沒有任何報錯你打開src/server/db.ts里面應該是這樣的import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma?: PrismaClient }; export const db globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV ! production) { globalForPrisma.prisma db; }這個全局單例的模式很關鍵。它確保在開發(fā)環(huán)境的模塊熱更新HMR過程中不會因為每次文件變更都創(chuàng)建新的 Prisma Client 而導致連接數(shù)暴增。不寫這個單例開發(fā)到一半你可能會看到數(shù)據(jù)庫連接被占滿的警告。3.3 寫第一個 tRPC 接口從 router 到頁面接下來定義一個 post router并在根 router 里注冊// src/server/api/root.ts import { createTRPCRouter } from ~/server/api/trpc; import { postRouter } from ~/server/api/routers/post; export const appRouter createTRPCRouter({ post: postRouter, }); export type AppRouter typeof appRouter;回到之前那個例子——我們已經有l(wèi)ist和create兩個 procedure 了?，F(xiàn)在重點是理解前端如何調用。在服務的入口處t3code 已經把 HTTP 路由掛好了src/app/api/trpc/[trpc]/route.ts所以前端不需要關心請求路徑。你只需要在客戶端組件里使用api對象use client; import { api } from ~/trpc/react; export function PostList() { const utils api.useUtils(); const { data: posts, isLoading } api.post.list.useQuery(); const createPost api.post.create.useMutation({ onSuccess: () utils.post.list.invalidate(), }); if (isLoading) return divLoading.../div; return ( div {posts?.map((post) ( div key{post.id}{post.title}/div ))} button onClick{() createPost.mutate({ title: Hello t3code })} 新增 /button /div ); }這里你可能注意到我沒有用refetch而是用了utils.post.list.invalidate()。這是 React Query 比較推薦的做法讓緩存失效后自動重新拉取而不是手動觸發(fā)請求。在 t3code 里React Query 的緩存策略可以按業(yè)務場景定制比如設置staleTime減少不必要的請求。3.4 類型是怎么流動的以及為什么你不會漏改字段很多人第一次看 t3code 會有個疑問前端代碼明明沒有導入任何后端類型為什么posts是帶類型的答案在于 tRPC 的泛型推導。api.post.list.useQuery()的api對象是createTRPCReactAppRouter()生成的而AppRouter又是typeof appRouter。所以TypeScript 會把appRouter里所有 router 的輸入輸出類型全部推導出來并注入到前端的 hooks 類型參數(shù)中。這相當于一個全項目的類型地圖前端不需要手動 import編輯器自動補全就能看到返回字段。這套機制帶來的實際效果是如果后端list返回值從{ title: string }變成了{ title: string; content: string }前端除非顯式解構字段否則不會報錯但如果后端改了字段名比如title改成name前端所有用到post.title的地方會立即標紅。這種改錯名十分鐘內發(fā)現(xiàn)的體驗在傳統(tǒng)接口聯(lián)調里幾乎不敢想。4. 生產環(huán)境最容易翻車的坑和完整的排查鏈路t3code 這套架構本地跑得很順但一到生產環(huán)境還是有幾個高頻問題我一個個說清楚包括排查思路和解決方案。4.1 數(shù)據(jù)庫連接被邊緣函數(shù)打滿Prisma 連接池配置如果你把 Next.js 部署到 Vercel 這類邊緣/Serverless 環(huán)境會遇到一個特別典型的坑Prisma Client 默認創(chuàng)建的連接池和 Serverless 按需啟動的短生命周期實例不匹配。現(xiàn)象是請求量稍微上來之后數(shù)據(jù)庫報錯P1001連接超時或者后臺看到大量閑置連接。原因是每個 Serverless 實例都會創(chuàng)建自己的 Prisma Client實例銷毀時連接池來不及釋放積少成多。排查鏈路先看日志是不是PrismaClientInitializationError或者連接數(shù)告警。確認是否每個 function 實例都持有了數(shù)據(jù)庫連接。解決方向有兩個一個是在數(shù)據(jù)庫里把直接連接地址和連接池地址分開一個是用外置連接池。在我的 t3code 倉庫里推薦的做法是在.env里區(qū)分兩個變量DATABASE_URLpostgresql://user:passwordhost:5432/db?pgbouncertrueconnection_limit1 DIRECT_URLpostgresql://user:passwordhost:5432/db然后在 schema 里聲明datasource db { provider postgresql url env(DATABASE_URL) directUrl env(DIRECT_URL) }DATABASE_URL走連接池適合 Prisma Client 在 Serverless 環(huán)境里頻繁創(chuàng)建連接DIRECT_URL走直連適合執(zhí)行遷移命令時使用。遷移的時候不需要連接池直連更可靠。4.2 tRPC 類型不同步兩端的版本斷裂t3code 的強項是類型穿透但如果你把前后端拆成兩個倉庫部署或者一個倉庫里前后端依賴版本不一致就會出現(xiàn)后端新加了一個 procedure前端類型卻沒更新的情況。這種斷裂在 monorepo 結構里尤其常見。典型報錯是前端調用api.xxx.yyy時TypeScript 提示Property yyy does not exist on type ...。排查鏈路確認是否運行過npm install確保trpc/server和trpc/react-query版本一致。確認src/server/api/root.ts里新 router 有沒有正確注冊。清掉 TypeScript 的增量緩存npx tsc --noEmit如果仍報錯再看編輯器里的 TypeScript 服務是否舊緩存重啟 TS Server。如果你用了 monorepo檢查子包之間的依賴是否指向了舊構建產物必要時重新 build。這類問題的根源基本不在代碼而在類型生成層沒有同步。我建議把prisma generate和類型檢查放進 CI 流程任何一步沒跑過都不允許合并。4.3 App Router 的use client邊界錯誤使用帶來的混亂App Router 出現(xiàn)之后哪些組件能直接用 tRPC hooks成了新問題。tRPC 的 React hooks 依賴客戶端狀態(tài)React Query 的 Provider所以只能在客戶端組件里調用。但是很多新手會把整個頁面都標成use client導致服務端組件完全失效首屏渲染變成瀏覽器渲染性能明顯下滑。正確做法是頁面外殼保持服務端組件只有需要交互的葉子組件按鈕、表單、列表容器單獨標記use client。比如在 t3code 里一個典型的服務端頁面骨架// app/page.tsx服務端組件 import { PostList } from ./_components/post-list; export default function HomePage() { return ( main h1文章列表/h1 PostList / /main ); }而PostList內部才是一個客戶端組件。這樣做的好處是頁面首屏可以靜默渲染只有列表區(qū)域在客戶端進行交互。如果你發(fā)現(xiàn)自己把use client寫到了頁面最頂層就要停下來想想是不是所有代碼都真的需要運行在瀏覽器上。排查思路用 React DevTools 看組件是否被正確區(qū)分為 Server/Client用構建產物檢查瀏覽器 bundle 的大小如果服務端代碼被打進去了邊界就出問題了。4.4 Zod 校驗失敗時的模糊報錯tRPC 的輸入校驗依賴 Zod。當你傳的參數(shù)不合法時報錯信息有時會比較原始尤其是嵌套對象里的字段名錯誤容易看得一頭霧水。我踩過的一個典型例子createPost.mutate({ title: });z.string().min(1)會拋錯但如果你沒有配置全局錯誤處理或者前端顯示邏輯用戶只會看到一個籠統(tǒng)的錯誤。解決辦法是在客戶端統(tǒng)一做錯誤映射const createPost api.post.create.useMutation({ onError: (err) { const message err.shape?.message ?? 請求失敗; // 在這里把 message 展示給用戶 }, });生產環(huán)境里我建議前端對用戶輸入先做一層 UI 校驗比如禁用按鈕、提示必填Zod 校驗作為后端兜底。這樣既保證用戶體驗流暢也不會依賴后端錯誤提示的文案質量。5. 部署收尾連接池、邊緣函數(shù)與構建配置最后聊聊把 t3code 從開發(fā)機推到生產環(huán)境時我在部署層面整理的幾條經驗。5.1 數(shù)據(jù)庫連接方案按部署環(huán)境區(qū)分前面已經提到連接池的問題這里再細化一下。在生產環(huán)境我通常給數(shù)據(jù)庫配置兩個連接地址DATABASE_URL給應用運行時使用走連接池比如通過外部連接池服務或者數(shù)據(jù)庫自帶的連接池端口。DIRECT_URL給prisma migrate deploy這類遷移命令使用直連更穩(wěn)定。如果是 PostgreSQL還建議設置合理的connection_limit。在 Serverless 場景下單個實例的并發(fā)請求數(shù)通常很小connection_limit1是合理的起點。不要把它設得太大否則實例一多連接數(shù)會迅速膨脹。5.2 構建階段的類型檢查不要跳過t3code 的腳手架在構建時會默認跑tsc --noEmit和next build。很多人嫌慢會在 CI 里把類型檢查關掉這是個典型隱患。類型安全是這個架構的地基如果構建階段不檢查類型等于把自動推導的優(yōu)勢白白扔掉了。我的建議是本地開發(fā)npm run dev可以跳過完整類型檢查保證熱更新速度。CI/生產構建必須跑npm run build它會執(zhí)行完整類型檢查。首次啟動慢一點沒關系換來的是類型斷裂不會悄悄溜進生產。5.3 邊緣運行時Edge Runtime和 Node 運行時的選擇Next.js 頁面可以配置為 Edge Runtime 或 Node.js Runtime。tRPC 和 Prisma 有一些生態(tài)兼容性差異尤其是 Prisma它依賴 Node 的部分原生能力和 Edge Runtime 的兼容性并不總是理想。我的經驗是如果用了 Prisma就老老實實用 Node.js Runtime。Edge Runtime 的優(yōu)勢在于全球低延遲響應但前提是你的數(shù)據(jù)層也要跟著駐留邊緣否則請求最終還是得回源到數(shù)據(jù)庫所在區(qū)域優(yōu)化效果非常有限。在 t3code 里我會讓 API 路由和頁面都使用默認的 Node.js Runtime優(yōu)先保證穩(wěn)定性和功能完整。5.4 環(huán)境變量的三個必須部署到托管平臺不管 Vercel、Netlify 還是自建 Node 服務環(huán)境變量都要單獨檢查一遍漏掉任何一個都會在運行時出問題。我的檢查清單是DATABASE_URL和DIRECT_URL是否正確指向生產數(shù)據(jù)庫。NODE_ENV是否自動設置為production大多數(shù)平臺會自動處理。是否有任何第三方服務的密鑰、公開地址被硬編碼進代碼里。另外有一點要特別提醒前端的構建產物里不要包含任何服務端密鑰。Next.js 里只有以NEXT_PUBLIC_開頭的環(huán)境變量才會被打進瀏覽器 bundle其他變量只在服務器端可見。在 t3code 里數(shù)據(jù)庫連接串永遠不要以NEXT_PUBLIC_開頭否則等于把數(shù)據(jù)庫鑰匙掛在門口。最后聊幾句實際使用感受如果你現(xiàn)在正在糾結要不要仿照 t3code 的方式搭業(yè)務我的個人建議是先在一個小項目上試水而不要一上來就全量遷移。t3code 這套架構的好處是類型安全和開發(fā)體驗代價是你需要習慣所有東西都要先定義類型的思路。有些同學剛開始會覺得麻煩但跑通第一個功能后大多數(shù)人回不去手寫接口類型的日子。小技巧放最后開發(fā)時如果你發(fā)現(xiàn)編輯器卡頓或者類型提示不更新先試試重啟 TypeScript 服務如果問題還在再清node_modules/.cache。這類問題八成不是代碼錯誤而是 TypeScript 的增量緩存和 tRPC 的復雜泛型在較老的 IDE 版本上鬧脾氣。換新版本或者升級依賴后通常就好了。