戰(zhàn)：Next.js + TypeScript + tRPC 類型安全架構(gòu)解析)
先說說 t3code 是什么。它不是一個(gè)框架也不是某個(gè)大廠的開源項(xiàng)目而是我最近集中精力打磨的一套全棧工程樣例以 Next.js TypeScript 為核心集成了 Tailwind CSS、Prisma、tRPC 等一套組合目標(biāo)是把“從零到能穩(wěn)定上線”的全過程固化下來讓新項(xiàng)目不用總是重復(fù)踩坑。這套組合有一個(gè)社區(qū)里的普遍叫法T3 Stack。T3 這個(gè)概念最早來自對(duì)“TypeScript-first 全棧開發(fā)”的總結(jié)核心是相信扁平的端到端類型安全能減少大量無效溝通和低級(jí)錯(cuò)誤。我之所以給項(xiàng)目起名叫 t3code就是想把它當(dāng)作一套可以不斷復(fù)用的代碼底座既能承載真實(shí)業(yè)務(wù)也可以作為團(tuán)隊(duì)內(nèi)部腳手架甚至拿來對(duì)新人做全棧入門教學(xué)。下面這篇文章會(huì)把整個(gè)項(xiàng)目的設(shè)計(jì)思路、目錄結(jié)構(gòu)、數(shù)據(jù)模型、API 層、前端交互、測(cè)試部署和我在實(shí)際開發(fā)中踩過的坑完整講一遍。適合有一定 React 基礎(chǔ)、但對(duì)全棧工程化還比較陌生的讀者也適合想優(yōu)化技術(shù)棧選型的團(tuán)隊(duì)參考。1. 先把項(xiàng)目拆開t3code 的核心目標(biāo)與工程邊界1.1 這一套組合解決了什么問題前端項(xiàng)目發(fā)展到今天困擾大家的往往不是“會(huì)不會(huì)寫組件”而是幾個(gè)老生常談的痛點(diǎn)前后端接口文檔對(duì)不上、類型不一致、配置分散、部署鏈路太長、新人接手成本高。t3code 選擇 T3 Stack 的原因就在于此。Next.js 負(fù)責(zé)頁面、路由和服務(wù)端渲染框架本身已經(jīng)吸收了大量 Web 性能最佳實(shí)踐TypeScript 嚴(yán)格模式保證代碼在編譯階段就把大部分類型問題暴露出來不需要等運(yùn)行時(shí)報(bào)錯(cuò)Tailwind CSS 把樣式從“命名地獄”里解放出來改排版再也不用擔(dān)心牽一發(fā)動(dòng)全身Prisma 提供數(shù)據(jù)庫建模、遷移和類型安全的客戶端tRPC 讓前后端 API 像調(diào)用本地函數(shù)一樣自然類型直接從服務(wù)端傳到客戶端。這一套組合真正解決的核心問題是“認(rèn)知負(fù)載”。你不需要同時(shí)維護(hù) REST API 文檔、手寫類型定義、各種代碼生成腳本只需要依賴 TypeScript 編譯器和框架本身的約定就能讓全鏈路保持類型安全。1.2 能力邊界與技術(shù)展望t3code 并不想把所有業(yè)務(wù)都塞進(jìn)一套模板里。我在設(shè)計(jì)的時(shí)候明確劃了一條邊界它負(fù)責(zé)提供一個(gè)成熟的起點(diǎn)而不是一個(gè)大而全的應(yīng)用框架。換句話說它默認(rèn)幫你把路由、樣式、數(shù)據(jù)庫、鑒權(quán)、部署這些基礎(chǔ)能力搭好但具體業(yè)務(wù)邏輯需要你按自己的領(lǐng)域去填。比如如果你想做一個(gè)博客系統(tǒng)可以直接在 Prisma 里加 Post 模型如果你想做一個(gè)小型 SaaS可以在 tRPC router 里定義自己的計(jì)費(fèi)接口。這套底座還有一個(gè)隱藏優(yōu)勢(shì)因?yàn)樗心K都保持解耦后續(xù)把某個(gè)部分替換成別的方案也不傷筋動(dòng)骨。比如你不想用 Prisma完全可以換成 Drizzle 或 TypeORM只要 tRPC 路由對(duì)外暴露的輸入輸出不變前端代碼幾乎零改動(dòng)。1.3 適用人群這個(gè)項(xiàng)目特別適合三類人獨(dú)立開發(fā)者想在短時(shí)間內(nèi)把一個(gè)想法做成可演示的 MVP不需要從零搭配置前端團(tuán)隊(duì)想統(tǒng)一全棧開發(fā)規(guī)范降低協(xié)作成本特別是成員對(duì) Node.js 后端不太熟悉時(shí)教學(xué)場(chǎng)景用 t3code 作為實(shí)訓(xùn)資料讓學(xué)生在真實(shí)工程里理解 TypeScript、數(shù)據(jù)庫、服務(wù)端渲染之間的關(guān)系。如果你已經(jīng)有兩年以上的 React/Node 經(jīng)驗(yàn)這套代碼讀起來基本沒有門檻如果你剛接觸全棧建議先把 React 基礎(chǔ)過一遍再動(dòng)手改樣式和數(shù)據(jù)模型。我自己帶過幾個(gè)實(shí)習(xí)生他們第一次看 t3code 的代碼時(shí)最大的障礙反而不是語法而是“服務(wù)端和客戶端到底怎么區(qū)分”。這一點(diǎn)在交流里我更傾向用最直白的方式解釋src/server 下面的代碼不會(huì)進(jìn)瀏覽器src/app 下面的代碼才是頁面入口剩下的事交給框架約定。2. 從零搭起 t3code工具鏈與工程化2.1 初始化工具鏈不該省的一步我習(xí)慣用 pnpm 管理依賴。相比 npm/yarnpnpm 對(duì)磁盤空間更友好依賴安裝速度也更快更重要的是它默認(rèn)做了更嚴(yán)格的依賴隔離不容易出現(xiàn)“本地能跑、打包就掛”的問題。初始化 t3code 的時(shí)候可以直接用 create-t3-app 命令行工具。執(zhí)行下面的命令pnpm create t3-applatest t3code交互終端會(huì)讓你選擇需要哪些模塊我勾選的是Next.jsTypeScriptTailwind CSSPrismatRPCNextAuth.js鑒權(quán)項(xiàng)目生成后先進(jìn)入目錄安裝依賴cd t3code pnpm install這里有一個(gè)容易被忽略的細(xì)節(jié)create-t3-app 默認(rèn)會(huì)幫你搭好 .env、代碼規(guī)范、tsconfig但不會(huì)自動(dòng)創(chuàng)建數(shù)據(jù)庫。所以在真正啟動(dòng)開發(fā)服務(wù)前你需要先把數(shù)據(jù)庫連接串和認(rèn)證配置填好。我記得第一次跑的時(shí)候漏掉了環(huán)境變量結(jié)果 tRPC 路由全部報(bào)錯(cuò)白排查了好幾個(gè)小時(shí)。還有一個(gè)小提醒生成器默認(rèn)可能在根目錄創(chuàng)建 .env 和 .env.example你可以立即把 .env.example 補(bǔ)全為一份“無敏感信息的模板”。我后來在團(tuán)隊(duì)協(xié)作中受益很大因?yàn)樾氯?clone 下來之后對(duì)著 example 文件就能快速知道要配哪些變量不用反復(fù)來問。2.2 TS 嚴(yán)格性與項(xiàng)目結(jié)構(gòu)t3code 的 TypeScript 配置走的是“嚴(yán)格到底”的路線。說實(shí)話剛開始寫會(huì)覺得有點(diǎn)煩比如可空類型、未使用變量、隱式 any 都會(huì)被編譯器攔下來。但這種方式長期看非常劃算尤其是項(xiàng)目規(guī)模變大之后重構(gòu)時(shí)不會(huì)出現(xiàn)“改了一個(gè)對(duì)象屬性十幾個(gè)頁面默默出錯(cuò)”的場(chǎng)面。項(xiàng)目的核心目錄結(jié)構(gòu)如下src/ app/ # Next.js App Router 路由與頁面 components/ # 可復(fù)用的 React 組件 lib/ # 全局工具、數(shù)據(jù)庫實(shí)例、認(rèn)證配置 server/ # 服務(wù)端邏輯tRPC 路由、鑒權(quán)、上下文 styles/ # 全局樣式與 Tailwind 配置 prisma/ schema.prisma # 數(shù)據(jù)模型與數(shù)據(jù)庫配置這個(gè)結(jié)構(gòu)并不復(fù)雜但它把服務(wù)端和客戶端邏輯分得很清楚不會(huì)出現(xiàn)業(yè)務(wù)代碼互相糾纏的情況。尤其是 tRPC 的實(shí)例、上下文、路由必須放在服務(wù)端一旦放錯(cuò)位置很可能會(huì)把數(shù)據(jù)庫憑據(jù)泄漏到客戶端 bundle 里這個(gè)風(fēng)險(xiǎn)點(diǎn)需要重點(diǎn)記住。實(shí)際開發(fā)時(shí)我還會(huì)順手加一個(gè) src/env 目錄用來集中解析環(huán)境變量。create-t3-app 默認(rèn)會(huì)用 zod 對(duì) env 做運(yùn)行時(shí)校驗(yàn)這看起來有點(diǎn)小題大做但如果你在團(tuán)隊(duì)里見過“某個(gè)變量拼錯(cuò)了導(dǎo)致線上全掛”的案例就會(huì)理解這種“一啟動(dòng)就報(bào)錯(cuò)”的設(shè)計(jì)有多友好。2.3 環(huán)境變量與配置管理環(huán)境變量方面我會(huì)在 .env 里維護(hù)幾類關(guān)鍵配置DATABASE_URLmysql://user:passwordlocalhost:3306/t3code NEXTAUTH_SECRETyour-secret NEXTAUTH_URLhttp://localhost:3000其中 DATABASE_URL 是 Prisma 連接數(shù)據(jù)庫的入口NEXTAUTH_SECRET 是 NextAuth 加密會(huì)話用的密鑰NEXTAUTH_URL 指定當(dāng)前應(yīng)用的地址。這三個(gè)是本地開發(fā)最基礎(chǔ)的三件套不要省略。注意生產(chǎn)環(huán)境不要使用本地?cái)?shù)據(jù)庫地址也不要把真實(shí)密鑰提交到 Git 倉庫。我在團(tuán)隊(duì)里一直強(qiáng)調(diào).env 文件要進(jìn) .gitignore密鑰走專門的密鑰管理服務(wù)或部署平臺(tái)的 env 配置。順帶一提我在本地經(jīng)常用 docker 起一個(gè) MySQL 實(shí)例來跑開發(fā)庫。這個(gè)方案最大的好處是環(huán)境一致不會(huì)因?yàn)槊總€(gè)人本機(jī)裝的數(shù)據(jù)庫版本不同而出現(xiàn)奇怪的兼容問題。用 docker compose 起個(gè)測(cè)試庫基本五分鐘搞定比手動(dòng)安裝數(shù)據(jù)庫省心。3. 數(shù)據(jù)層與業(yè)務(wù) API從 schema 到 tRPC 的完整鏈路3.1 Prisma 模型設(shè)計(jì)先想清楚關(guān)系t3code 的數(shù)據(jù)模型用 Prisma Schema 聲明。開發(fā)前最好先把“誰和誰有對(duì)應(yīng)關(guān)系”想清楚否則后面遷移表結(jié)構(gòu)會(huì)比較痛苦。以常見的內(nèi)容型應(yīng)用為例generator client { provider prisma-client-js } datasource db { provider mysql url env(DATABASE_URL) } model User { id String id default(cuid()) name String email String unique emailVerified DateTime? posts Post[] } model Post { id String id default(cuid()) title String content String published Boolean default(false) createdAt DateTime default(now()) updatedAt DateTime updatedAt authorId String author User relation(fields: [authorId], references: [id]) }這里有個(gè)很典型的例子User 和 Post 是一對(duì)多關(guān)系Post 通過 authorId 外鍵關(guān)聯(lián)到 User。我在實(shí)際開發(fā)中經(jīng)?？吹接腥税?createdBy 寫成字符串或者在服務(wù)端再手寫一遍關(guān)系邏輯這些都是不必要的重復(fù)。Prisma 會(huì)根據(jù) schema 自動(dòng)生成帶關(guān)系類型的客戶端類型安全是天然的。改完 schema 后運(yùn)行npx prisma migrate dev --name init這個(gè)命令會(huì)在數(shù)據(jù)庫里創(chuàng)建對(duì)應(yīng)的表并把 migration 歷史記錄下來方便團(tuán)隊(duì)其他成員同步結(jié)構(gòu)和后續(xù)回滾。如果只是在本地快速驗(yàn)證也可以先用 npx prisma db push但生產(chǎn)環(huán)境我仍然推薦走正式 migration。關(guān)于主鍵類型我默認(rèn)使用字符串 cuid 而不是自增數(shù)字。原因是自增主鍵容易在數(shù)據(jù)合并、多環(huán)境同步時(shí)撞車cuid 則是全局唯一的。雖然字符串索引比數(shù)字略慢一點(diǎn)點(diǎn)但對(duì)絕大多數(shù)業(yè)務(wù)系統(tǒng)來說完全可接受換來的是更強(qiáng)的可遷移性。3.2 tRPC router 的設(shè)計(jì)接口即函數(shù)tRPC 的設(shè)計(jì)哲學(xué)是“接口即函數(shù)”。服務(wù)端定義一個(gè) router客戶端引入類型后調(diào)用起來就像調(diào)用本地 Promise 函數(shù)一樣。一個(gè)最簡(jiǎn)單的 tRPC 查詢可以這樣寫import { createTRPCRouter, protectedProcedure, publicProcedure } from ~/server/trpc; import { z } from zod; import { prisma } from ~/server/db; export const postRouter createTRPCRouter({ list: publicProcedure .input(z.object({ limit: z.number().min(1).max(100).default(10) })) .query(async ({ input }) { const posts await prisma.post.findMany({ take: input.limit, orderBy: { createdAt: desc }, }); return posts; }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().min(1) })) .mutation(async ({ ctx, input }) { return prisma.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); }), });這段代碼里publicProcedure 和 protectedProcedure 的區(qū)別就是鑒權(quán)。protectedProcedure 要求用戶必須先登錄未登錄時(shí) tRPC 會(huì)拋出認(rèn)證錯(cuò)誤。對(duì)于內(nèi)容創(chuàng)建這類寫操作我強(qiáng)烈建議只用 protectedProcedure不要為了省事把所有接口都設(shè)為 public。zod 的 input 校驗(yàn)也值得多說兩句。很多人會(huì)以為它只是“省去 if 判斷”實(shí)際上它同時(shí)兼任類型定義和運(yùn)行時(shí)校驗(yàn)兩個(gè)職責(zé)。你定義了 z.string().min(1)那么客戶端傳入空字符串時(shí)tRPC 會(huì)在進(jìn)入業(yè)務(wù)邏輯之前就拒絕請(qǐng)求而不是等數(shù)據(jù)庫報(bào)錯(cuò)。這對(duì)接口健壯性的提升是立竿見影的。3.3 中間件與鑒權(quán)NextAuth 和 tRPC 的配合在 T3 Stack 里可以說是“官方推薦組合”。它的流程是NextAuth 負(fù)責(zé)登錄會(huì)話tRPC createContext 會(huì)讀取 session 信息然后注入到每個(gè)路由的 ctx 中。我一開始遇到的問題是把 session 類型定義寫得不夠嚴(yán)格導(dǎo)致客戶端拿到的 user 對(duì)象可能為 null。后來我加了類型斷言和中間件統(tǒng)一處理export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { session: { ...ctx.session, user: ctx.session.user }, }, }); });這個(gè)中間件看起來很簡(jiǎn)單但它把“是否登錄”的判斷收斂到了一處。后面所有需要登錄的接口只要套一個(gè) protectedProcedure就不需要再重復(fù)寫判斷邏輯也不會(huì)出現(xiàn)漏判。注意登錄態(tài)判斷永遠(yuǎn)不要只依賴前端。即使你用了 tRPC前端路由可以寫各種守衛(wèi)但真正的數(shù)據(jù)訪問控制一定發(fā)生在服務(wù)端。這是安全底線。在 t3code 里我還加了一層資源歸屬校驗(yàn)。比如用戶只能編輯自己創(chuàng)建的文章這個(gè)邏輯不能只靠 protectedProcedure還要在 procedure 內(nèi)部判斷 resource.ownerId 是否等于 session.user.id。很多數(shù)據(jù)泄露事故本質(zhì)上都是“能登錄就能看別人數(shù)據(jù)”導(dǎo)致的這一點(diǎn)要在業(yè)務(wù)路由里單獨(dú)加固。4. 前端體驗(yàn)UI、狀態(tài)與交互細(xì)節(jié)4.1 Tailwind 渲染與設(shè)計(jì)系統(tǒng)t3code 的樣式層做得比較克制。Tailwind CSS 很適合“只寫該寫的樣式”不會(huì)像傳統(tǒng) CSS 那樣產(chǎn)生大量難以維護(hù)的類名堆疊。我會(huì)先在 tailwind.config.ts 里定義幾個(gè) design token比如主色、圓角、陰影import type { Config } from tailwindcss; export default { content: [./src/**/*.{ts,tsx}], theme: { extend: { colors: { primary: #2563eb, accent: #f59e0b, }, borderRadius: { xl: 1rem, }, }, }, plugins: [], } satisfies Config;實(shí)際寫頁面的時(shí)候我通常不會(huì)把樣式復(fù)雜化。比如一個(gè)按鈕直接寫 classNamerounded-xl bg-primary px-4 py-2 text-white基本不用再額外寫 CSS 文件。這樣做的收益是新人接手時(shí)不需要翻樣式表看到 className 就能猜出大概樣式。我還習(xí)慣把重復(fù)出現(xiàn)的樣式抽成小組件。比如一個(gè)基礎(chǔ)按鈕 Button、一個(gè)卡片 Card把這些小組件統(tǒng)一放在 components/ui 下面。這樣既保留了 Tailwind 的靈活性又避免了同一段樣式在二十個(gè)頁面里反復(fù)復(fù)制后續(xù)想統(tǒng)一改圓角、改陰影時(shí)只需要?jiǎng)右粋€(gè)地方。4.2 客戶端數(shù)據(jù)流把服務(wù)端數(shù)據(jù)拉起來在 t3code 里客戶端調(diào)用服務(wù)端并不需要寫 fetch 和 URL 拼接。還記得剛才的 postRouter 嗎在 React 組件里可以直接這么用use client; import { api } from ~/utils/api; export default function PostList() { const { data: posts, isLoading } api.post.list.useQuery({ limit: 10 }); if (isLoading) return div加載中.../div; return ( ul {posts?.map((post) ( li key{post.id}{post.title}/li ))} /ul ); }這里的 api.post.list.useQuery 是類型安全的如果你在服務(wù)端把返回值改成別的字段客戶端這里立刻會(huì)編譯報(bào)錯(cuò)。這種體驗(yàn)在傳統(tǒng) REST API 開發(fā)里幾乎是不可能的也正因?yàn)槲矣H身體驗(yàn)過我才格外推薦 tRPC。寫操作時(shí)可以用 useMutation它會(huì)自動(dòng)管理請(qǐng)求狀態(tài)和緩存失效const utils api.useUtils(); const createPost api.post.create.useMutation({ onSuccess: async () { await utils.post.list.invalidate(); }, });這里 invalidate 是 tRPC 提供的一個(gè)很實(shí)用的能力它會(huì)在創(chuàng)建成功后讓 post.list 自動(dòng)重新拉取不用手動(dòng)去改本地緩存。很多人第一次接觸時(shí)不太能理解為什么不用手動(dòng) setState 去更新列表其實(shí)這就是“服務(wù)端狀態(tài)”和“客戶端狀態(tài)”的區(qū)別。列表數(shù)據(jù)來自服務(wù)端最穩(wěn)妥的更新方式就是讓服務(wù)端重新給一份而不是在前端猜。4.3 性能兜底與加載體驗(yàn)全棧應(yīng)用很容易出現(xiàn)“數(shù)據(jù)太慢”的問題。t3code 做性能優(yōu)化時(shí)主要抓三個(gè)點(diǎn)頁面骨架屏用服務(wù)端渲染先出 HTML配合 loading 狀態(tài)展示骨架減少白屏焦慮數(shù)據(jù)復(fù)用對(duì)不常變更的數(shù)據(jù)使用 React Query 的 staleTime 配置避免每次都發(fā)請(qǐng)求按需加載組件層面用 Next.js 的 dynamic import路由拆包避免首屏 bundle 過大。一個(gè)典型的示例是在根頁面組件里設(shè)置 staleTimeconst { data } api.post.list.useQuery( { limit: 10 }, { staleTime: 30_000 } );這樣 30 秒內(nèi)再次訪問React Query 不會(huì)重新發(fā)起網(wǎng)絡(luò)請(qǐng)求直接使用緩存。對(duì)訪問量的優(yōu)化非常明顯。這里還要提醒一句React Query 的 cache 默認(rèn)是內(nèi)存級(jí)的刷新頁面后一定會(huì)重新拉數(shù)據(jù)。如果你需要持久化緩存比如把用戶偏好設(shè)置存到 localStorage那就不能只依賴 React Query 默認(rèn)行為得配合 persist 之類的方案。大多數(shù)場(chǎng)景下默認(rèn)內(nèi)存緩存已經(jīng)夠用了不需要過早優(yōu)化。5. 測(cè)試、部署與運(yùn)維5.1 自動(dòng)化測(cè)試的最小集很多人習(xí)慣手動(dòng)點(diǎn)一遍頁面就當(dāng)測(cè)試過了但項(xiàng)目到中后期會(huì)越來越脆弱。t3code 里我保留了一個(gè)最小可用的測(cè)試集單元測(cè)試主要覆蓋工具函數(shù)和 tRPC 路由的輸入校驗(yàn)集成測(cè)試用 Vitest React Testing Library 渲染關(guān)鍵頁面數(shù)據(jù)庫測(cè)試在測(cè)試環(huán)境里跑內(nèi)存數(shù)據(jù)庫或獨(dú)立的測(cè)試庫驗(yàn)證數(shù)據(jù)模型。Vitest 配置非常輕直接在 vite.config 里加 test 字段就行它的 API 和 Jest 很接近遷移成本低。針對(duì) tRPC 路由測(cè)試我一般直接調(diào)用 router.createCaller 來模擬客戶端請(qǐng)求比真正起一個(gè) HTTP 服務(wù)器更省事。import { postRouter } from ~/server/api/routers/post; import { createCallerFactory } from ~/server/trpc; const caller createCallerFactory(postRouter); test(未登錄用戶不能創(chuàng)建文章, async () { await expect(caller.withContext({ session: null }).create({ title: hello, content: world, })).rejects.toThrow(/UNAUTHORIZED/); });這種測(cè)試方式非常貼近真實(shí)調(diào)用鏈因?yàn)?createCaller 會(huì)走完整的 zod 校驗(yàn)和中間件邏輯。只要把 session 傳入不同的 mock 對(duì)象就能模擬登錄和未登錄兩種場(chǎng)景不用去 mock 數(shù)據(jù)庫也不用起服務(wù)器測(cè)試速度非?？?。5.2 部署與數(shù)據(jù)庫前端部分部署到 Vercel 是成本最低的選擇push 到 Git 倉庫后自動(dòng)構(gòu)建發(fā)布日常發(fā)布基本不需要手動(dòng)干預(yù)。數(shù)據(jù)庫我一般選擇托管數(shù)據(jù)庫服務(wù)避免自己維護(hù)服務(wù)器和高可用開發(fā)效率優(yōu)先。部署前Build 命令需要提前在環(huán)境變量里配置好DATABASE_URL指向生產(chǎn)數(shù)據(jù)庫NEXTAUTH_URL生產(chǎn)環(huán)境域名NEXTAUTH_SECRET新的隨機(jī)密鑰。在 Vercel 上配置時(shí)不要直接復(fù)制本地 .env應(yīng)該重新生成一套生產(chǎn)密鑰并限制數(shù)據(jù)庫白名單。很多安全事故其實(shí)不是代碼問題而是開發(fā)環(huán)境的密鑰直接被帶到了線上。有一個(gè)經(jīng)驗(yàn)值得分享生產(chǎn)環(huán)境的 DATABASE_URL 要和本地隔離。如果本地和線上共用同一個(gè)數(shù)據(jù)庫開發(fā)時(shí)的誤操作很可能會(huì)污染生產(chǎn)數(shù)據(jù)尤其是跑 migrate reset 之類的命令時(shí)后果可能是毀滅性的。我自己的習(xí)慣是本地、預(yù)發(fā)布、生產(chǎn)各一套數(shù)據(jù)庫再怎么折騰都不影響線上。5.3 監(jiān)控與日志t3code 上線后重點(diǎn)觀察的數(shù)據(jù)有三類頁面錯(cuò)誤率、接口延遲、數(shù)據(jù)庫連接數(shù)。如果項(xiàng)目還比較小可以先用框架自帶的 logging 和 Sentry 這類服務(wù)先頂起來等業(yè)務(wù)體量大了再引入更重的可觀測(cè)平臺(tái)。我的習(xí)慣是在 tRPC 路由的外層加一個(gè)簡(jiǎn)單的錯(cuò)誤捕獲中間件統(tǒng)一記錄請(qǐng)求路徑、錯(cuò)誤碼、耗時(shí)export const loggingMiddleware t.middleware(async ({ path, type, next, ctx }) { const start Date.now(); try { const result await next(); console.log(${type} ${path} ${Date.now() - start}ms); return result; } catch (err) { console.error(${type} ${path} failed, err); throw err; } });中間件本身不復(fù)雜但能把所有接口的可觀測(cè)性兜住上線后排查問題會(huì)省不少力氣。有朋友問我為什么不用 Grafana / Prometheus 那套重型方案我的回答是看項(xiàng)目階段。如果你每天的請(qǐng)求量連一萬都不到堆一堆監(jiān)控系統(tǒng)反而成了維護(hù)負(fù)擔(dān)。先把 log 打全、把錯(cuò)誤上報(bào)鏈路接好等業(yè)務(wù)真的需要再逐步加指標(biāo)系統(tǒng)這才是更務(wù)實(shí)的選擇。6. 常見問題速查與個(gè)人心得6.1 高頻問題一次說清下面這個(gè)表格是我在 t3code 開發(fā)過程中反復(fù)遇到的幾個(gè)問題整理出來供大家對(duì)照排查癥狀常見原因排查思路tRPC 請(qǐng)求全部報(bào) 500DATABASE_URL 沒有配置或者數(shù)據(jù)庫沒啟動(dòng)先確認(rèn) .env 加載再執(zhí)行 npx prisma db push 或 migrate登錄后 session 丟失NEXTAUTH_SECRET 不一致或 NEXTAUTH_URL 不對(duì)檢查部署環(huán)境和本地環(huán)境是否共用同一密鑰打包后樣式錯(cuò)亂使用 Tailwind 時(shí)漏配置 content 路徑確認(rèn) tailwind.config.ts 包含 src 下的所有 tsx 文件表單校驗(yàn)不生效zod schema 類型和組件 input 類型不一致統(tǒng)一用 z.infer 導(dǎo)出類型給前端用數(shù)據(jù)更新后頁面不刷新沒有調(diào)用 invalidate 或 refetch在 mutation onSuccess 里調(diào)用對(duì)應(yīng) query 的 invalidate還有一個(gè)容易被忽略的點(diǎn)是權(quán)限相關(guān)。很多“明明登錄了卻提示未登錄”的案例其實(shí)是因?yàn)?session 在客戶端和服務(wù)端的 secret 不一致。NextAuth 在做加密和簽名時(shí)會(huì)用到 NEXTAUTH_SECRET本地、Vercel、測(cè)試環(huán)境如果各用各的就會(huì)導(dǎo)致 token 互相解不開。這個(gè)坑我踩過不止一次所以現(xiàn)在我會(huì)在部署腳本里強(qiáng)制執(zhí)行一行檢查如果某個(gè)環(huán)境的 secret 和本地相同直接中斷部署并給出警告。6.2 我在實(shí)際開發(fā)中維護(hù)的小習(xí)慣最后分享幾點(diǎn)長期改動(dòng)下來的習(xí)慣。第一t3code 的所有數(shù)據(jù)庫模型都盡量以業(yè)務(wù)語義命名不在 schema 里堆“技術(shù)晦澀”的字段。比如使用 createdAt、updatedAt、authorId而不要用 ctime、utime、owner_id。名字清楚遷移時(shí)也容易讀懂歷史記錄。第二每一次修改 Prisma schema 后都立即生成 migration而不是攢到最后一起遷移。中途發(fā)現(xiàn)問題時(shí)小的 migration 更好回滾和分析。第三不要在客戶端代碼里直接 import prisma也不要在組件里 import 任何 server-only 文件。t3code 的目錄劃分已經(jīng)把 server 目錄獨(dú)立出來這樣不僅能避免類型混亂也能防止把數(shù)據(jù)庫連接代碼打進(jìn)客戶端 bundle。6.3 后續(xù)還能怎么擴(kuò)展t3code 這套底座想擴(kuò)展成其他產(chǎn)品形態(tài)并不難。想做成多用戶協(xié)作工具可以在 User 模型加一個(gè) workspaceId再通過 tRPC 中間件做資源隔離想做內(nèi)容社區(qū)可以加 Comment 模型和 Tag 模型想接 AI 能力可以在服務(wù)端路由里調(diào)模型接口再把結(jié)果通過 tRPC 返回前端。關(guān)鍵在于保持類型安全和分層意識(shí)新增功能時(shí)先修改 schema再定義路由最后寫界面不容易把系統(tǒng)寫亂。說回最初我起名 t3code 其實(shí)沒有太復(fù)雜的含義就是“T3 棧的代碼倉庫”的簡(jiǎn)稱。但做完整套東西之后我最大的感受是全棧開發(fā)真正要對(duì)抗的不是學(xué)習(xí)難度而是散落各處的信息和不確定性。把不確定的類型、接口、配置都收攏到一處整個(gè)開發(fā)體驗(yàn)就會(huì)好非常多。如果你正準(zhǔn)備從零開始做一個(gè)全棧產(chǎn)品或者想把團(tuán)隊(duì)的技術(shù)棧收斂一下建議照這個(gè)思路復(fù)現(xiàn)一遍 t3code你會(huì)少走很多彎路。 T3 Stack 全棧工程實(shí)戰(zhàn)：Next.js + TypeScript + tRPC 類型安全架構(gòu)解析
先說說 t3code 是什么。它不是一個(gè)框架也不是某個(gè)大廠的開源項(xiàng)目而是我最近集中精力打磨的一套全棧工程樣例以 Next.js TypeScript 為核心集成了 Tailwind CSS、Prisma、tRPC 等一套組合目標(biāo)是把“從零到能穩(wěn)定上線”的全過程固化下來讓新項(xiàng)目不用總是重復(fù)踩坑。這套組合有一個(gè)社區(qū)里的普遍叫法T3 Stack。T3 這個(gè)概念最早來自對(duì)“TypeScript-first 全棧開發(fā)”的總結(jié)核心是相信扁平的端到端類型安全能減少大量無效溝通和低級(jí)錯(cuò)誤。我之所以給項(xiàng)目起名叫 t3code就是想把它當(dāng)作一套可以不斷復(fù)用的代碼底座既能承載真實(shí)業(yè)務(wù)也可以作為團(tuán)隊(duì)內(nèi)部腳手架甚至拿來對(duì)新人做全棧入門教學(xué)。下面這篇文章會(huì)把整個(gè)項(xiàng)目的設(shè)計(jì)思路、目錄結(jié)構(gòu)、數(shù)據(jù)模型、API 層、前端交互、測(cè)試部署和我在實(shí)際開發(fā)中踩過的坑完整講一遍。適合有一定 React 基礎(chǔ)、但對(duì)全棧工程化還比較陌生的讀者也適合想優(yōu)化技術(shù)棧選型的團(tuán)隊(duì)參考。1. 先把項(xiàng)目拆開t3code 的核心目標(biāo)與工程邊界1.1 這一套組合解決了什么問題前端項(xiàng)目發(fā)展到今天困擾大家的往往不是“會(huì)不會(huì)寫組件”而是幾個(gè)老生常談的痛點(diǎn)前后端接口文檔對(duì)不上、類型不一致、配置分散、部署鏈路太長、新人接手成本高。t3code 選擇 T3 Stack 的原因就在于此。Next.js 負(fù)責(zé)頁面、路由和服務(wù)端渲染框架本身已經(jīng)吸收了大量 Web 性能最佳實(shí)踐TypeScript 嚴(yán)格模式保證代碼在編譯階段就把大部分類型問題暴露出來不需要等運(yùn)行時(shí)報(bào)錯(cuò)Tailwind CSS 把樣式從“命名地獄”里解放出來改排版再也不用擔(dān)心牽一發(fā)動(dòng)全身Prisma 提供數(shù)據(jù)庫建模、遷移和類型安全的客戶端tRPC 讓前后端 API 像調(diào)用本地函數(shù)一樣自然類型直接從服務(wù)端傳到客戶端。這一套組合真正解決的核心問題是“認(rèn)知負(fù)載”。你不需要同時(shí)維護(hù) REST API 文檔、手寫類型定義、各種代碼生成腳本只需要依賴 TypeScript 編譯器和框架本身的約定就能讓全鏈路保持類型安全。1.2 能力邊界與技術(shù)展望t3code 并不想把所有業(yè)務(wù)都塞進(jìn)一套模板里。我在設(shè)計(jì)的時(shí)候明確劃了一條邊界它負(fù)責(zé)提供一個(gè)成熟的起點(diǎn)而不是一個(gè)大而全的應(yīng)用框架。換句話說它默認(rèn)幫你把路由、樣式、數(shù)據(jù)庫、鑒權(quán)、部署這些基礎(chǔ)能力搭好但具體業(yè)務(wù)邏輯需要你按自己的領(lǐng)域去填。比如如果你想做一個(gè)博客系統(tǒng)可以直接在 Prisma 里加 Post 模型如果你想做一個(gè)小型 SaaS可以在 tRPC router 里定義自己的計(jì)費(fèi)接口。這套底座還有一個(gè)隱藏優(yōu)勢(shì)因?yàn)樗心K都保持解耦后續(xù)把某個(gè)部分替換成別的方案也不傷筋動(dòng)骨。比如你不想用 Prisma完全可以換成 Drizzle 或 TypeORM只要 tRPC 路由對(duì)外暴露的輸入輸出不變前端代碼幾乎零改動(dòng)。1.3 適用人群這個(gè)項(xiàng)目特別適合三類人獨(dú)立開發(fā)者想在短時(shí)間內(nèi)把一個(gè)想法做成可演示的 MVP不需要從零搭配置前端團(tuán)隊(duì)想統(tǒng)一全棧開發(fā)規(guī)范降低協(xié)作成本特別是成員對(duì) Node.js 后端不太熟悉時(shí)教學(xué)場(chǎng)景用 t3code 作為實(shí)訓(xùn)資料讓學(xué)生在真實(shí)工程里理解 TypeScript、數(shù)據(jù)庫、服務(wù)端渲染之間的關(guān)系。如果你已經(jīng)有兩年以上的 React/Node 經(jīng)驗(yàn)這套代碼讀起來基本沒有門檻如果你剛接觸全棧建議先把 React 基礎(chǔ)過一遍再動(dòng)手改樣式和數(shù)據(jù)模型。我自己帶過幾個(gè)實(shí)習(xí)生他們第一次看 t3code 的代碼時(shí)最大的障礙反而不是語法而是“服務(wù)端和客戶端到底怎么區(qū)分”。這一點(diǎn)在交流里我更傾向用最直白的方式解釋src/server 下面的代碼不會(huì)進(jìn)瀏覽器src/app 下面的代碼才是頁面入口剩下的事交給框架約定。2. 從零搭起 t3code工具鏈與工程化2.1 初始化工具鏈不該省的一步我習(xí)慣用 pnpm 管理依賴。相比 npm/yarnpnpm 對(duì)磁盤空間更友好依賴安裝速度也更快更重要的是它默認(rèn)做了更嚴(yán)格的依賴隔離不容易出現(xiàn)“本地能跑、打包就掛”的問題。初始化 t3code 的時(shí)候可以直接用 create-t3-app 命令行工具。執(zhí)行下面的命令pnpm create t3-applatest t3code交互終端會(huì)讓你選擇需要哪些模塊我勾選的是Next.jsTypeScriptTailwind CSSPrismatRPCNextAuth.js鑒權(quán)項(xiàng)目生成后先進(jìn)入目錄安裝依賴cd t3code pnpm install這里有一個(gè)容易被忽略的細(xì)節(jié)create-t3-app 默認(rèn)會(huì)幫你搭好 .env、代碼規(guī)范、tsconfig但不會(huì)自動(dòng)創(chuàng)建數(shù)據(jù)庫。所以在真正啟動(dòng)開發(fā)服務(wù)前你需要先把數(shù)據(jù)庫連接串和認(rèn)證配置填好。我記得第一次跑的時(shí)候漏掉了環(huán)境變量結(jié)果 tRPC 路由全部報(bào)錯(cuò)白排查了好幾個(gè)小時(shí)。還有一個(gè)小提醒生成器默認(rèn)可能在根目錄創(chuàng)建 .env 和 .env.example你可以立即把 .env.example 補(bǔ)全為一份“無敏感信息的模板”。我后來在團(tuán)隊(duì)協(xié)作中受益很大因?yàn)樾氯?clone 下來之后對(duì)著 example 文件就能快速知道要配哪些變量不用反復(fù)來問。2.2 TS 嚴(yán)格性與項(xiàng)目結(jié)構(gòu)t3code 的 TypeScript 配置走的是“嚴(yán)格到底”的路線。說實(shí)話剛開始寫會(huì)覺得有點(diǎn)煩比如可空類型、未使用變量、隱式 any 都會(huì)被編譯器攔下來。但這種方式長期看非常劃算尤其是項(xiàng)目規(guī)模變大之后重構(gòu)時(shí)不會(huì)出現(xiàn)“改了一個(gè)對(duì)象屬性十幾個(gè)頁面默默出錯(cuò)”的場(chǎng)面。項(xiàng)目的核心目錄結(jié)構(gòu)如下src/ app/ # Next.js App Router 路由與頁面 components/ # 可復(fù)用的 React 組件 lib/ # 全局工具、數(shù)據(jù)庫實(shí)例、認(rèn)證配置 server/ # 服務(wù)端邏輯tRPC 路由、鑒權(quán)、上下文 styles/ # 全局樣式與 Tailwind 配置 prisma/ schema.prisma # 數(shù)據(jù)模型與數(shù)據(jù)庫配置這個(gè)結(jié)構(gòu)并不復(fù)雜但它把服務(wù)端和客戶端邏輯分得很清楚不會(huì)出現(xiàn)業(yè)務(wù)代碼互相糾纏的情況。尤其是 tRPC 的實(shí)例、上下文、路由必須放在服務(wù)端一旦放錯(cuò)位置很可能會(huì)把數(shù)據(jù)庫憑據(jù)泄漏到客戶端 bundle 里這個(gè)風(fēng)險(xiǎn)點(diǎn)需要重點(diǎn)記住。實(shí)際開發(fā)時(shí)我還會(huì)順手加一個(gè) src/env 目錄用來集中解析環(huán)境變量。create-t3-app 默認(rèn)會(huì)用 zod 對(duì) env 做運(yùn)行時(shí)校驗(yàn)這看起來有點(diǎn)小題大做但如果你在團(tuán)隊(duì)里見過“某個(gè)變量拼錯(cuò)了導(dǎo)致線上全掛”的案例就會(huì)理解這種“一啟動(dòng)就報(bào)錯(cuò)”的設(shè)計(jì)有多友好。2.3 環(huán)境變量與配置管理環(huán)境變量方面我會(huì)在 .env 里維護(hù)幾類關(guān)鍵配置DATABASE_URLmysql://user:passwordlocalhost:3306/t3code NEXTAUTH_SECRETyour-secret NEXTAUTH_URLhttp://localhost:3000其中 DATABASE_URL 是 Prisma 連接數(shù)據(jù)庫的入口NEXTAUTH_SECRET 是 NextAuth 加密會(huì)話用的密鑰NEXTAUTH_URL 指定當(dāng)前應(yīng)用的地址。這三個(gè)是本地開發(fā)最基礎(chǔ)的三件套不要省略。注意生產(chǎn)環(huán)境不要使用本地?cái)?shù)據(jù)庫地址也不要把真實(shí)密鑰提交到 Git 倉庫。我在團(tuán)隊(duì)里一直強(qiáng)調(diào).env 文件要進(jìn) .gitignore密鑰走專門的密鑰管理服務(wù)或部署平臺(tái)的 env 配置。順帶一提我在本地經(jīng)常用 docker 起一個(gè) MySQL 實(shí)例來跑開發(fā)庫。這個(gè)方案最大的好處是環(huán)境一致不會(huì)因?yàn)槊總€(gè)人本機(jī)裝的數(shù)據(jù)庫版本不同而出現(xiàn)奇怪的兼容問題。用 docker compose 起個(gè)測(cè)試庫基本五分鐘搞定比手動(dòng)安裝數(shù)據(jù)庫省心。3. 數(shù)據(jù)層與業(yè)務(wù) API從 schema 到 tRPC 的完整鏈路3.1 Prisma 模型設(shè)計(jì)先想清楚關(guān)系t3code 的數(shù)據(jù)模型用 Prisma Schema 聲明。開發(fā)前最好先把“誰和誰有對(duì)應(yīng)關(guān)系”想清楚否則后面遷移表結(jié)構(gòu)會(huì)比較痛苦。以常見的內(nèi)容型應(yīng)用為例generator client { provider prisma-client-js } datasource db { provider mysql url env(DATABASE_URL) } model User { id String id default(cuid()) name String email String unique emailVerified DateTime? posts Post[] } model Post { id String id default(cuid()) title String content String published Boolean default(false) createdAt DateTime default(now()) updatedAt DateTime updatedAt authorId String author User relation(fields: [authorId], references: [id]) }這里有個(gè)很典型的例子User 和 Post 是一對(duì)多關(guān)系Post 通過 authorId 外鍵關(guān)聯(lián)到 User。我在實(shí)際開發(fā)中經(jīng)?？吹接腥税?createdBy 寫成字符串或者在服務(wù)端再手寫一遍關(guān)系邏輯這些都是不必要的重復(fù)。Prisma 會(huì)根據(jù) schema 自動(dòng)生成帶關(guān)系類型的客戶端類型安全是天然的。改完 schema 后運(yùn)行npx prisma migrate dev --name init這個(gè)命令會(huì)在數(shù)據(jù)庫里創(chuàng)建對(duì)應(yīng)的表并把 migration 歷史記錄下來方便團(tuán)隊(duì)其他成員同步結(jié)構(gòu)和后續(xù)回滾。如果只是在本地快速驗(yàn)證也可以先用 npx prisma db push但生產(chǎn)環(huán)境我仍然推薦走正式 migration。關(guān)于主鍵類型我默認(rèn)使用字符串 cuid 而不是自增數(shù)字。原因是自增主鍵容易在數(shù)據(jù)合并、多環(huán)境同步時(shí)撞車cuid 則是全局唯一的。雖然字符串索引比數(shù)字略慢一點(diǎn)點(diǎn)但對(duì)絕大多數(shù)業(yè)務(wù)系統(tǒng)來說完全可接受換來的是更強(qiáng)的可遷移性。3.2 tRPC router 的設(shè)計(jì)接口即函數(shù)tRPC 的設(shè)計(jì)哲學(xué)是“接口即函數(shù)”。服務(wù)端定義一個(gè) router客戶端引入類型后調(diào)用起來就像調(diào)用本地 Promise 函數(shù)一樣。一個(gè)最簡(jiǎn)單的 tRPC 查詢可以這樣寫import { createTRPCRouter, protectedProcedure, publicProcedure } from ~/server/trpc; import { z } from zod; import { prisma } from ~/server/db; export const postRouter createTRPCRouter({ list: publicProcedure .input(z.object({ limit: z.number().min(1).max(100).default(10) })) .query(async ({ input }) { const posts await prisma.post.findMany({ take: input.limit, orderBy: { createdAt: desc }, }); return posts; }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().min(1) })) .mutation(async ({ ctx, input }) { return prisma.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); }), });這段代碼里publicProcedure 和 protectedProcedure 的區(qū)別就是鑒權(quán)。protectedProcedure 要求用戶必須先登錄未登錄時(shí) tRPC 會(huì)拋出認(rèn)證錯(cuò)誤。對(duì)于內(nèi)容創(chuàng)建這類寫操作我強(qiáng)烈建議只用 protectedProcedure不要為了省事把所有接口都設(shè)為 public。zod 的 input 校驗(yàn)也值得多說兩句。很多人會(huì)以為它只是“省去 if 判斷”實(shí)際上它同時(shí)兼任類型定義和運(yùn)行時(shí)校驗(yàn)兩個(gè)職責(zé)。你定義了 z.string().min(1)那么客戶端傳入空字符串時(shí)tRPC 會(huì)在進(jìn)入業(yè)務(wù)邏輯之前就拒絕請(qǐng)求而不是等數(shù)據(jù)庫報(bào)錯(cuò)。這對(duì)接口健壯性的提升是立竿見影的。3.3 中間件與鑒權(quán)NextAuth 和 tRPC 的配合在 T3 Stack 里可以說是“官方推薦組合”。它的流程是NextAuth 負(fù)責(zé)登錄會(huì)話tRPC createContext 會(huì)讀取 session 信息然后注入到每個(gè)路由的 ctx 中。我一開始遇到的問題是把 session 類型定義寫得不夠嚴(yán)格導(dǎo)致客戶端拿到的 user 對(duì)象可能為 null。后來我加了類型斷言和中間件統(tǒng)一處理export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { session: { ...ctx.session, user: ctx.session.user }, }, }); });這個(gè)中間件看起來很簡(jiǎn)單但它把“是否登錄”的判斷收斂到了一處。后面所有需要登錄的接口只要套一個(gè) protectedProcedure就不需要再重復(fù)寫判斷邏輯也不會(huì)出現(xiàn)漏判。注意登錄態(tài)判斷永遠(yuǎn)不要只依賴前端。即使你用了 tRPC前端路由可以寫各種守衛(wèi)但真正的數(shù)據(jù)訪問控制一定發(fā)生在服務(wù)端。這是安全底線。在 t3code 里我還加了一層資源歸屬校驗(yàn)。比如用戶只能編輯自己創(chuàng)建的文章這個(gè)邏輯不能只靠 protectedProcedure還要在 procedure 內(nèi)部判斷 resource.ownerId 是否等于 session.user.id。很多數(shù)據(jù)泄露事故本質(zhì)上都是“能登錄就能看別人數(shù)據(jù)”導(dǎo)致的這一點(diǎn)要在業(yè)務(wù)路由里單獨(dú)加固。4. 前端體驗(yàn)UI、狀態(tài)與交互細(xì)節(jié)4.1 Tailwind 渲染與設(shè)計(jì)系統(tǒng)t3code 的樣式層做得比較克制。Tailwind CSS 很適合“只寫該寫的樣式”不會(huì)像傳統(tǒng) CSS 那樣產(chǎn)生大量難以維護(hù)的類名堆疊。我會(huì)先在 tailwind.config.ts 里定義幾個(gè) design token比如主色、圓角、陰影import type { Config } from tailwindcss; export default { content: [./src/**/*.{ts,tsx}], theme: { extend: { colors: { primary: #2563eb, accent: #f59e0b, }, borderRadius: { xl: 1rem, }, }, }, plugins: [], } satisfies Config;實(shí)際寫頁面的時(shí)候我通常不會(huì)把樣式復(fù)雜化。比如一個(gè)按鈕直接寫 classNamerounded-xl bg-primary px-4 py-2 text-white基本不用再額外寫 CSS 文件。這樣做的收益是新人接手時(shí)不需要翻樣式表看到 className 就能猜出大概樣式。我還習(xí)慣把重復(fù)出現(xiàn)的樣式抽成小組件。比如一個(gè)基礎(chǔ)按鈕 Button、一個(gè)卡片 Card把這些小組件統(tǒng)一放在 components/ui 下面。這樣既保留了 Tailwind 的靈活性又避免了同一段樣式在二十個(gè)頁面里反復(fù)復(fù)制后續(xù)想統(tǒng)一改圓角、改陰影時(shí)只需要?jiǎng)右粋€(gè)地方。4.2 客戶端數(shù)據(jù)流把服務(wù)端數(shù)據(jù)拉起來在 t3code 里客戶端調(diào)用服務(wù)端并不需要寫 fetch 和 URL 拼接。還記得剛才的 postRouter 嗎在 React 組件里可以直接這么用use client; import { api } from ~/utils/api; export default function PostList() { const { data: posts, isLoading } api.post.list.useQuery({ limit: 10 }); if (isLoading) return div加載中.../div; return ( ul {posts?.map((post) ( li key{post.id}{post.title}/li ))} /ul ); }這里的 api.post.list.useQuery 是類型安全的如果你在服務(wù)端把返回值改成別的字段客戶端這里立刻會(huì)編譯報(bào)錯(cuò)。這種體驗(yàn)在傳統(tǒng) REST API 開發(fā)里幾乎是不可能的也正因?yàn)槲矣H身體驗(yàn)過我才格外推薦 tRPC。寫操作時(shí)可以用 useMutation它會(huì)自動(dòng)管理請(qǐng)求狀態(tài)和緩存失效const utils api.useUtils(); const createPost api.post.create.useMutation({ onSuccess: async () { await utils.post.list.invalidate(); }, });這里 invalidate 是 tRPC 提供的一個(gè)很實(shí)用的能力它會(huì)在創(chuàng)建成功后讓 post.list 自動(dòng)重新拉取不用手動(dòng)去改本地緩存。很多人第一次接觸時(shí)不太能理解為什么不用手動(dòng) setState 去更新列表其實(shí)這就是“服務(wù)端狀態(tài)”和“客戶端狀態(tài)”的區(qū)別。列表數(shù)據(jù)來自服務(wù)端最穩(wěn)妥的更新方式就是讓服務(wù)端重新給一份而不是在前端猜。4.3 性能兜底與加載體驗(yàn)全棧應(yīng)用很容易出現(xiàn)“數(shù)據(jù)太慢”的問題。t3code 做性能優(yōu)化時(shí)主要抓三個(gè)點(diǎn)頁面骨架屏用服務(wù)端渲染先出 HTML配合 loading 狀態(tài)展示骨架減少白屏焦慮數(shù)據(jù)復(fù)用對(duì)不常變更的數(shù)據(jù)使用 React Query 的 staleTime 配置避免每次都發(fā)請(qǐng)求按需加載組件層面用 Next.js 的 dynamic import路由拆包避免首屏 bundle 過大。一個(gè)典型的示例是在根頁面組件里設(shè)置 staleTimeconst { data } api.post.list.useQuery( { limit: 10 }, { staleTime: 30_000 } );這樣 30 秒內(nèi)再次訪問React Query 不會(huì)重新發(fā)起網(wǎng)絡(luò)請(qǐng)求直接使用緩存。對(duì)訪問量的優(yōu)化非常明顯。這里還要提醒一句React Query 的 cache 默認(rèn)是內(nèi)存級(jí)的刷新頁面后一定會(huì)重新拉數(shù)據(jù)。如果你需要持久化緩存比如把用戶偏好設(shè)置存到 localStorage那就不能只依賴 React Query 默認(rèn)行為得配合 persist 之類的方案。大多數(shù)場(chǎng)景下默認(rèn)內(nèi)存緩存已經(jīng)夠用了不需要過早優(yōu)化。5. 測(cè)試、部署與運(yùn)維5.1 自動(dòng)化測(cè)試的最小集很多人習(xí)慣手動(dòng)點(diǎn)一遍頁面就當(dāng)測(cè)試過了但項(xiàng)目到中后期會(huì)越來越脆弱。t3code 里我保留了一個(gè)最小可用的測(cè)試集單元測(cè)試主要覆蓋工具函數(shù)和 tRPC 路由的輸入校驗(yàn)集成測(cè)試用 Vitest React Testing Library 渲染關(guān)鍵頁面數(shù)據(jù)庫測(cè)試在測(cè)試環(huán)境里跑內(nèi)存數(shù)據(jù)庫或獨(dú)立的測(cè)試庫驗(yàn)證數(shù)據(jù)模型。Vitest 配置非常輕直接在 vite.config 里加 test 字段就行它的 API 和 Jest 很接近遷移成本低。針對(duì) tRPC 路由測(cè)試我一般直接調(diào)用 router.createCaller 來模擬客戶端請(qǐng)求比真正起一個(gè) HTTP 服務(wù)器更省事。import { postRouter } from ~/server/api/routers/post; import { createCallerFactory } from ~/server/trpc; const caller createCallerFactory(postRouter); test(未登錄用戶不能創(chuàng)建文章, async () { await expect(caller.withContext({ session: null }).create({ title: hello, content: world, })).rejects.toThrow(/UNAUTHORIZED/); });這種測(cè)試方式非常貼近真實(shí)調(diào)用鏈因?yàn)?createCaller 會(huì)走完整的 zod 校驗(yàn)和中間件邏輯。只要把 session 傳入不同的 mock 對(duì)象就能模擬登錄和未登錄兩種場(chǎng)景不用去 mock 數(shù)據(jù)庫也不用起服務(wù)器測(cè)試速度非?？?。5.2 部署與數(shù)據(jù)庫前端部分部署到 Vercel 是成本最低的選擇push 到 Git 倉庫后自動(dòng)構(gòu)建發(fā)布日常發(fā)布基本不需要手動(dòng)干預(yù)。數(shù)據(jù)庫我一般選擇托管數(shù)據(jù)庫服務(wù)避免自己維護(hù)服務(wù)器和高可用開發(fā)效率優(yōu)先。部署前Build 命令需要提前在環(huán)境變量里配置好DATABASE_URL指向生產(chǎn)數(shù)據(jù)庫NEXTAUTH_URL生產(chǎn)環(huán)境域名NEXTAUTH_SECRET新的隨機(jī)密鑰。在 Vercel 上配置時(shí)不要直接復(fù)制本地 .env應(yīng)該重新生成一套生產(chǎn)密鑰并限制數(shù)據(jù)庫白名單。很多安全事故其實(shí)不是代碼問題而是開發(fā)環(huán)境的密鑰直接被帶到了線上。有一個(gè)經(jīng)驗(yàn)值得分享生產(chǎn)環(huán)境的 DATABASE_URL 要和本地隔離。如果本地和線上共用同一個(gè)數(shù)據(jù)庫開發(fā)時(shí)的誤操作很可能會(huì)污染生產(chǎn)數(shù)據(jù)尤其是跑 migrate reset 之類的命令時(shí)后果可能是毀滅性的。我自己的習(xí)慣是本地、預(yù)發(fā)布、生產(chǎn)各一套數(shù)據(jù)庫再怎么折騰都不影響線上。5.3 監(jiān)控與日志t3code 上線后重點(diǎn)觀察的數(shù)據(jù)有三類頁面錯(cuò)誤率、接口延遲、數(shù)據(jù)庫連接數(shù)。如果項(xiàng)目還比較小可以先用框架自帶的 logging 和 Sentry 這類服務(wù)先頂起來等業(yè)務(wù)體量大了再引入更重的可觀測(cè)平臺(tái)。我的習(xí)慣是在 tRPC 路由的外層加一個(gè)簡(jiǎn)單的錯(cuò)誤捕獲中間件統(tǒng)一記錄請(qǐng)求路徑、錯(cuò)誤碼、耗時(shí)export const loggingMiddleware t.middleware(async ({ path, type, next, ctx }) { const start Date.now(); try { const result await next(); console.log(${type} ${path} ${Date.now() - start}ms); return result; } catch (err) { console.error(${type} ${path} failed, err); throw err; } });中間件本身不復(fù)雜但能把所有接口的可觀測(cè)性兜住上線后排查問題會(huì)省不少力氣。有朋友問我為什么不用 Grafana / Prometheus 那套重型方案我的回答是看項(xiàng)目階段。如果你每天的請(qǐng)求量連一萬都不到堆一堆監(jiān)控系統(tǒng)反而成了維護(hù)負(fù)擔(dān)。先把 log 打全、把錯(cuò)誤上報(bào)鏈路接好等業(yè)務(wù)真的需要再逐步加指標(biāo)系統(tǒng)這才是更務(wù)實(shí)的選擇。6. 常見問題速查與個(gè)人心得6.1 高頻問題一次說清下面這個(gè)表格是我在 t3code 開發(fā)過程中反復(fù)遇到的幾個(gè)問題整理出來供大家對(duì)照排查癥狀常見原因排查思路tRPC 請(qǐng)求全部報(bào) 500DATABASE_URL 沒有配置或者數(shù)據(jù)庫沒啟動(dòng)先確認(rèn) .env 加載再執(zhí)行 npx prisma db push 或 migrate登錄后 session 丟失NEXTAUTH_SECRET 不一致或 NEXTAUTH_URL 不對(duì)檢查部署環(huán)境和本地環(huán)境是否共用同一密鑰打包后樣式錯(cuò)亂使用 Tailwind 時(shí)漏配置 content 路徑確認(rèn) tailwind.config.ts 包含 src 下的所有 tsx 文件表單校驗(yàn)不生效zod schema 類型和組件 input 類型不一致統(tǒng)一用 z.infer 導(dǎo)出類型給前端用數(shù)據(jù)更新后頁面不刷新沒有調(diào)用 invalidate 或 refetch在 mutation onSuccess 里調(diào)用對(duì)應(yīng) query 的 invalidate還有一個(gè)容易被忽略的點(diǎn)是權(quán)限相關(guān)。很多“明明登錄了卻提示未登錄”的案例其實(shí)是因?yàn)?session 在客戶端和服務(wù)端的 secret 不一致。NextAuth 在做加密和簽名時(shí)會(huì)用到 NEXTAUTH_SECRET本地、Vercel、測(cè)試環(huán)境如果各用各的就會(huì)導(dǎo)致 token 互相解不開。這個(gè)坑我踩過不止一次所以現(xiàn)在我會(huì)在部署腳本里強(qiáng)制執(zhí)行一行檢查如果某個(gè)環(huán)境的 secret 和本地相同直接中斷部署并給出警告。6.2 我在實(shí)際開發(fā)中維護(hù)的小習(xí)慣最后分享幾點(diǎn)長期改動(dòng)下來的習(xí)慣。第一t3code 的所有數(shù)據(jù)庫模型都盡量以業(yè)務(wù)語義命名不在 schema 里堆“技術(shù)晦澀”的字段。比如使用 createdAt、updatedAt、authorId而不要用 ctime、utime、owner_id。名字清楚遷移時(shí)也容易讀懂歷史記錄。第二每一次修改 Prisma schema 后都立即生成 migration而不是攢到最后一起遷移。中途發(fā)現(xiàn)問題時(shí)小的 migration 更好回滾和分析。第三不要在客戶端代碼里直接 import prisma也不要在組件里 import 任何 server-only 文件。t3code 的目錄劃分已經(jīng)把 server 目錄獨(dú)立出來這樣不僅能避免類型混亂也能防止把數(shù)據(jù)庫連接代碼打進(jìn)客戶端 bundle。6.3 后續(xù)還能怎么擴(kuò)展t3code 這套底座想擴(kuò)展成其他產(chǎn)品形態(tài)并不難。想做成多用戶協(xié)作工具可以在 User 模型加一個(gè) workspaceId再通過 tRPC 中間件做資源隔離想做內(nèi)容社區(qū)可以加 Comment 模型和 Tag 模型想接 AI 能力可以在服務(wù)端路由里調(diào)模型接口再把結(jié)果通過 tRPC 返回前端。關(guān)鍵在于保持類型安全和分層意識(shí)新增功能時(shí)先修改 schema再定義路由最后寫界面不容易把系統(tǒng)寫亂。說回最初我起名 t3code 其實(shí)沒有太復(fù)雜的含義就是“T3 棧的代碼倉庫”的簡(jiǎn)稱。但做完整套東西之后我最大的感受是全棧開發(fā)真正要對(duì)抗的不是學(xué)習(xí)難度而是散落各處的信息和不確定性。把不確定的類型、接口、配置都收攏到一處整個(gè)開發(fā)體驗(yàn)就會(huì)好非常多。如果你正準(zhǔn)備從零開始做一個(gè)全棧產(chǎn)品或者想把團(tuán)隊(duì)的技術(shù)棧收斂一下建議照這個(gè)思路復(fù)現(xiàn)一遍 t3code你會(huì)少走很多彎路。