戰(zhàn)：Next.js + TypeScript + tRPC 類型安全架構(gòu)解析)
先說(shuō)說(shuō) t3code 是什么。它不是一個(gè)框架也不是某個(gè)大廠的開源項(xiàng)目而是我最近集中精力打磨的一套全棧工程樣例以 Next.js TypeScript 為核心集成了 Tailwind CSS、Prisma、tRPC 等一套組合目標(biāo)是把“從零到能穩(wěn)定上線”的全過(guò)程固化下來(lái)讓新項(xiàng)目不用總是重復(fù)踩坑。這套組合有一個(gè)社區(qū)里的普遍叫法T3 Stack。T3 這個(gè)概念最早來(lái)自對(duì)“TypeScript-first 全棧開發(fā)”的總結(jié)核心是相信扁平的端到端類型安全能減少大量無(wú)效溝通和低級(jí)錯(cuò)誤。我之所以給項(xiàng)目起名叫 t3code就是想把它當(dāng)作一套可以不斷復(fù)用的代碼底座既能承載真實(shí)業(yè)務(wù)也可以作為團(tuán)隊(duì)內(nèi)部腳手架甚至拿來(lái)對(duì)新人做全棧入門教學(xué)。下面這篇文章會(huì)把整個(gè)項(xiàng)目的設(shè)計(jì)思路、目錄結(jié)構(gòu)、數(shù)據(jù)模型、API 層、前端交互、測(cè)試部署和我在實(shí)際開發(fā)中踩過(guò)的坑完整講一遍。適合有一定 React 基礎(chǔ)、但對(duì)全棧工程化還比較陌生的讀者也適合想優(yōu)化技術(shù)棧選型的團(tuán)隊(duì)參考。1. 先把項(xiàng)目拆開t3code 的核心目標(biāo)與工程邊界1.1 這一套組合解決了什么問(wèn)題前端項(xiàng)目發(fā)展到今天困擾大家的往往不是“會(huì)不會(huì)寫組件”而是幾個(gè)老生常談的痛點(diǎn)前后端接口文檔對(duì)不上、類型不一致、配置分散、部署鏈路太長(zhǎng)、新人接手成本高。t3code 選擇 T3 Stack 的原因就在于此。Next.js 負(fù)責(zé)頁(yè)面、路由和服務(wù)端渲染框架本身已經(jīng)吸收了大量 Web 性能最佳實(shí)踐TypeScript 嚴(yán)格模式保證代碼在編譯階段就把大部分類型問(wèn)題暴露出來(lái)不需要等運(yùn)行時(shí)報(bào)錯(cuò)Tailwind CSS 把樣式從“命名地獄”里解放出來(lái)改排版再也不用擔(dān)心牽一發(fā)動(dòng)全身Prisma 提供數(shù)據(jù)庫(kù)建模、遷移和類型安全的客戶端tRPC 讓前后端 API 像調(diào)用本地函數(shù)一樣自然類型直接從服務(wù)端傳到客戶端。這一套組合真正解決的核心問(wèn)題是“認(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)用框架。換句話說(shuō)它默認(rèn)幫你把路由、樣式、數(shù)據(jù)庫(kù)、鑒權(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ù)庫(kù)、服務(wù)端渲染之間的關(guān)系。如果你已經(jīng)有兩年以上的 React/Node 經(jīng)驗(yàn)這套代碼讀起來(lái)基本沒(méi)有門檻如果你剛接觸全棧建議先把 React 基礎(chǔ)過(guò)一遍再動(dòng)手改樣式和數(shù)據(jù)模型。我自己帶過(guò)幾個(gè)實(shí)習(xí)生他們第一次看 t3code 的代碼時(shí)最大的障礙反而不是語(yǔ)法而是“服務(wù)端和客戶端到底怎么區(qū)分”。這一點(diǎn)在交流里我更傾向用最直白的方式解釋src/server 下面的代碼不會(huì)進(jìn)瀏覽器src/app 下面的代碼才是頁(yè)面入口剩下的事交給框架約定。2. 從零搭起 t3code工具鏈與工程化2.1 初始化工具鏈不該省的一步我習(xí)慣用 pnpm 管理依賴。相比 npm/yarnpnpm 對(duì)磁盤空間更友好依賴安裝速度也更快更重要的是它默認(rèn)做了更嚴(yán)格的依賴隔離不容易出現(xiàn)“本地能跑、打包就掛”的問(wè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ù)庫(kù)。所以在真正啟動(dòng)開發(fā)服務(wù)前你需要先把數(shù)據(jù)庫(kù)連接串和認(rèn)證配置填好。我記得第一次跑的時(shí)候漏掉了環(huán)境變量結(jié)果 tRPC 路由全部報(bào)錯(cuò)白排查了好幾個(gè)小時(shí)。還有一個(gè)小提醒生成器默認(rèn)可能在根目錄創(chuàng)建 .env 和 .env.example你可以立即把 .env.example 補(bǔ)全為一份“無(wú)敏感信息的模板”。我后來(lái)在團(tuán)隊(duì)協(xié)作中受益很大因?yàn)樾氯?clone 下來(lái)之后對(duì)著 example 文件就能快速知道要配哪些變量不用反復(fù)來(lái)問(wèn)。2.2 TS 嚴(yán)格性與項(xiàng)目結(jié)構(gòu)t3code 的 TypeScript 配置走的是“嚴(yán)格到底”的路線。說(shuō)實(shí)話剛開始寫會(huì)覺(jué)得有點(diǎn)煩比如可空類型、未使用變量、隱式 any 都會(huì)被編譯器攔下來(lái)。但這種方式長(zhǎng)期看非常劃算尤其是項(xiàng)目規(guī)模變大之后重構(gòu)時(shí)不會(huì)出現(xiàn)“改了一個(gè)對(duì)象屬性十幾個(gè)頁(yè)面默默出錯(cuò)”的場(chǎng)面。項(xiàng)目的核心目錄結(jié)構(gòu)如下src/ app/ # Next.js App Router 路由與頁(yè)面 components/ # 可復(fù)用的 React 組件 lib/ # 全局工具、數(shù)據(jù)庫(kù)實(shí)例、認(rèn)證配置 server/ # 服務(wù)端邏輯tRPC 路由、鑒權(quán)、上下文 styles/ # 全局樣式與 Tailwind 配置 prisma/ schema.prisma # 數(shù)據(jù)模型與數(shù)據(jù)庫(kù)配置這個(gè)結(jié)構(gòu)并不復(fù)雜但它把服務(wù)端和客戶端邏輯分得很清楚不會(huì)出現(xiàn)業(yè)務(wù)代碼互相糾纏的情況。尤其是 tRPC 的實(shí)例、上下文、路由必須放在服務(wù)端一旦放錯(cuò)位置很可能會(huì)把數(shù)據(jù)庫(kù)憑據(jù)泄漏到客戶端 bundle 里這個(gè)風(fēng)險(xiǎn)點(diǎn)需要重點(diǎn)記住。實(shí)際開發(fā)時(shí)我還會(huì)順手加一個(gè) src/env 目錄用來(lái)集中解析環(huán)境變量。create-t3-app 默認(rèn)會(huì)用 zod 對(duì) env 做運(yùn)行時(shí)校驗(yàn)這看起來(lái)有點(diǎn)小題大做但如果你在團(tuán)隊(duì)里見過(guò)“某個(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ù)庫(kù)的入口NEXTAUTH_SECRET 是 NextAuth 加密會(huì)話用的密鑰NEXTAUTH_URL 指定當(dāng)前應(yīng)用的地址。這三個(gè)是本地開發(fā)最基礎(chǔ)的三件套不要省略。注意生產(chǎn)環(huán)境不要使用本地?cái)?shù)據(jù)庫(kù)地址也不要把真實(shí)密鑰提交到 Git 倉(cāng)庫(kù)。我在團(tuán)隊(duì)里一直強(qiáng)調(diào).env 文件要進(jìn) .gitignore密鑰走專門的密鑰管理服務(wù)或部署平臺(tái)的 env 配置。順帶一提我在本地經(jīng)常用 docker 起一個(gè) MySQL 實(shí)例來(lái)跑開發(fā)庫(kù)。這個(gè)方案最大的好處是環(huán)境一致不會(huì)因?yàn)槊總€(gè)人本機(jī)裝的數(shù)據(jù)庫(kù)版本不同而出現(xiàn)奇怪的兼容問(wèn)題。用 docker compose 起個(gè)測(cè)試庫(kù)基本五分鐘搞定比手動(dòng)安裝數(shù)據(jù)庫(kù)省心。3. 數(shù)據(jù)層與業(yè)務(wù) API從 schema 到 tRPC 的完整鏈路3.1 Prisma 模型設(shè)計(jì)先想清楚關(guān)系t3code 的數(shù)據(jù)模型用 Prisma Schema 聲明。開發(fā)前最好先把“誰(shuí)和誰(shuí)有對(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 通過(guò) 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ù)庫(kù)里創(chuàng)建對(duì)應(yīng)的表并把 migration 歷史記錄下來(lái)方便團(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)來(lái)說(shuō)完全可接受換來(lái)的是更強(qiáng)的可遷移性。3.2 tRPC router 的設(shè)計(jì)接口即函數(shù)tRPC 的設(shè)計(jì)哲學(xué)是“接口即函數(shù)”。服務(wù)端定義一個(gè) router客戶端引入類型后調(diào)用起來(lái)就像調(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)也值得多說(shuō)兩句。很多人會(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ù)庫(kù)報(bào)錯(cuò)。這對(duì)接口健壯性的提升是立竿見影的。3.3 中間件與鑒權(quán)NextAuth 和 tRPC 的配合在 T3 Stack 里可以說(shuō)是“官方推薦組合”。它的流程是NextAuth 負(fù)責(zé)登錄會(huì)話tRPC createContext 會(huì)讀取 session 信息然后注入到每個(gè)路由的 ctx 中。我一開始遇到的問(wèn)題是把 session 類型定義寫得不夠嚴(yán)格導(dǎo)致客戶端拿到的 user 對(duì)象可能為 null。后來(lái)我加了類型斷言和中間件統(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è)中間件看起來(lái)很簡(jiǎn)單但它把“是否登錄”的判斷收斂到了一處。后面所有需要登錄的接口只要套一個(gè) protectedProcedure就不需要再重復(fù)寫判斷邏輯也不會(huì)出現(xiàn)漏判。注意登錄態(tài)判斷永遠(yuǎn)不要只依賴前端。即使你用了 tRPC前端路由可以寫各種守衛(wèi)但真正的數(shù)據(jù)訪問(wèn)控制一定發(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í)際寫頁(yè)面的時(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è)頁(yè)面里反復(fù)復(fù)制后續(xù)想統(tǒng)一改圓角、改陰影時(shí)只需要?jiǎng)右粋€(gè)地方。4.2 客戶端數(shù)據(jù)流把服務(wù)端數(shù)據(jù)拉起來(lái)在 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)過(guò)我才格外推薦 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ù)來(lái)自服務(wù)端最穩(wěn)妥的更新方式就是讓服務(wù)端重新給一份而不是在前端猜。4.3 性能兜底與加載體驗(yàn)全棧應(yīng)用很容易出現(xiàn)“數(shù)據(jù)太慢”的問(wèn)題。t3code 做性能優(yōu)化時(shí)主要抓三個(gè)點(diǎn)頁(yè)面骨架屏用服務(wù)端渲染先出 HTML配合 loading 狀態(tài)展示骨架減少白屏焦慮數(shù)據(jù)復(fù)用對(duì)不常變更的數(shù)據(jù)使用 React Query 的 staleTime 配置避免每次都發(fā)請(qǐng)求按需加載組件層面用 Next.js 的 dynamic import路由拆包避免首屏 bundle 過(guò)大。一個(gè)典型的示例是在根頁(yè)面組件里設(shè)置 staleTimeconst { data } api.post.list.useQuery( { limit: 10 }, { staleTime: 30_000 } );這樣 30 秒內(nèi)再次訪問(wèn)React Query 不會(huì)重新發(fā)起網(wǎng)絡(luò)請(qǐng)求直接使用緩存。對(duì)訪問(wèn)量的優(yōu)化非常明顯。這里還要提醒一句React Query 的 cache 默認(rèn)是內(nèi)存級(jí)的刷新頁(yè)面后一定會(huì)重新拉數(shù)據(jù)。如果你需要持久化緩存比如把用戶偏好設(shè)置存到 localStorage那就不能只依賴 React Query 默認(rèn)行為得配合 persist 之類的方案。大多數(shù)場(chǎng)景下默認(rèn)內(nèi)存緩存已經(jīng)夠用了不需要過(guò)早優(yōu)化。5. 測(cè)試、部署與運(yùn)維5.1 自動(dòng)化測(cè)試的最小集很多人習(xí)慣手動(dòng)點(diǎn)一遍頁(yè)面就當(dāng)測(cè)試過(guò)了但項(xiàng)目到中后期會(huì)越來(lái)越脆弱。t3code 里我保留了一個(gè)最小可用的測(cè)試集單元測(cè)試主要覆蓋工具函數(shù)和 tRPC 路由的輸入校驗(yàn)集成測(cè)試用 Vitest React Testing Library 渲染關(guān)鍵頁(yè)面數(shù)據(jù)庫(kù)測(cè)試在測(cè)試環(huán)境里跑內(nèi)存數(shù)據(jù)庫(kù)或獨(dú)立的測(cè)試庫(kù)驗(yàn)證數(shù)據(jù)模型。Vitest 配置非常輕直接在 vite.config 里加 test 字段就行它的 API 和 Jest 很接近遷移成本低。針對(duì) tRPC 路由測(cè)試我一般直接調(diào)用 router.createCaller 來(lái)模擬客戶端請(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ù)庫(kù)也不用起服務(wù)器測(cè)試速度非?？臁?.2 部署與數(shù)據(jù)庫(kù)前端部分部署到 Vercel 是成本最低的選擇push 到 Git 倉(cāng)庫(kù)后自動(dòng)構(gòu)建發(fā)布日常發(fā)布基本不需要手動(dòng)干預(yù)。數(shù)據(jù)庫(kù)我一般選擇托管數(shù)據(jù)庫(kù)服務(wù)避免自己維護(hù)服務(wù)器和高可用開發(fā)效率優(yōu)先。部署前Build 命令需要提前在環(huán)境變量里配置好DATABASE_URL指向生產(chǎn)數(shù)據(jù)庫(kù)NEXTAUTH_URL生產(chǎn)環(huán)境域名NEXTAUTH_SECRET新的隨機(jī)密鑰。在 Vercel 上配置時(shí)不要直接復(fù)制本地 .env應(yīng)該重新生成一套生產(chǎn)密鑰并限制數(shù)據(jù)庫(kù)白名單。很多安全事故其實(shí)不是代碼問(wèn)題而是開發(fā)環(huán)境的密鑰直接被帶到了線上。有一個(gè)經(jīng)驗(yàn)值得分享生產(chǎn)環(huán)境的 DATABASE_URL 要和本地隔離。如果本地和線上共用同一個(gè)數(shù)據(jù)庫(kù)開發(fā)時(shí)的誤操作很可能會(huì)污染生產(chǎn)數(shù)據(jù)尤其是跑 migrate reset 之類的命令時(shí)后果可能是毀滅性的。我自己的習(xí)慣是本地、預(yù)發(fā)布、生產(chǎn)各一套數(shù)據(jù)庫(kù)再怎么折騰都不影響線上。5.3 監(jiān)控與日志t3code 上線后重點(diǎn)觀察的數(shù)據(jù)有三類頁(yè)面錯(cuò)誤率、接口延遲、數(shù)據(jù)庫(kù)連接數(shù)。如果項(xiàng)目還比較小可以先用框架自帶的 logging 和 Sentry 這類服務(wù)先頂起來(lái)等業(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è)性兜住上線后排查問(wèn)題會(huì)省不少力氣。有朋友問(wèn)我為什么不用 Grafana / Prometheus 那套重型方案我的回答是看項(xiàng)目階段。如果你每天的請(qǐng)求量連一萬(wàn)都不到堆一堆監(jiān)控系統(tǒng)反而成了維護(hù)負(fù)擔(dān)。先把 log 打全、把錯(cuò)誤上報(bào)鏈路接好等業(yè)務(wù)真的需要再逐步加指標(biāo)系統(tǒng)這才是更務(wù)實(shí)的選擇。6. 常見問(wèn)題速查與個(gè)人心得6.1 高頻問(wèn)題一次說(shuō)清下面這個(gè)表格是我在 t3code 開發(fā)過(guò)程中反復(fù)遇到的幾個(gè)問(wèn)題整理出來(lái)供大家對(duì)照排查癥狀常見原因排查思路tRPC 請(qǐng)求全部報(bào) 500DATABASE_URL 沒(méi)有配置或者數(shù)據(jù)庫(kù)沒(méi)啟動(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ù)更新后頁(yè)面不刷新沒(méi)有調(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è)坑我踩過(guò)不止一次所以現(xiàn)在我會(huì)在部署腳本里強(qiáng)制執(zhí)行一行檢查如果某個(gè)環(huán)境的 secret 和本地相同直接中斷部署并給出警告。6.2 我在實(shí)際開發(fā)中維護(hù)的小習(xí)慣最后分享幾點(diǎn)長(zhǎng)期改動(dòng)下來(lái)的習(xí)慣。第一t3code 的所有數(shù)據(jù)庫(kù)模型都盡量以業(yè)務(wù)語(yǔ)義命名不在 schema 里堆“技術(shù)晦澀”的字段。比如使用 createdAt、updatedAt、authorId而不要用 ctime、utime、owner_id。名字清楚遷移時(shí)也容易讀懂歷史記錄。第二每一次修改 Prisma schema 后都立即生成 migration而不是攢到最后一起遷移。中途發(fā)現(xiàn)問(wèn)題時(shí)小的 migration 更好回滾和分析。第三不要在客戶端代碼里直接 import prisma也不要在組件里 import 任何 server-only 文件。t3code 的目錄劃分已經(jīng)把 server 目錄獨(dú)立出來(lái)這樣不僅能避免類型混亂也能防止把數(shù)據(jù)庫(kù)連接代碼打進(jìn)客戶端 bundle。6.3 后續(xù)還能怎么擴(kuò)展t3code 這套底座想擴(kuò)展成其他產(chǎn)品形態(tài)并不難。想做成多用戶協(xié)作工具可以在 User 模型加一個(gè) workspaceId再通過(guò) tRPC 中間件做資源隔離想做內(nèi)容社區(qū)可以加 Comment 模型和 Tag 模型想接 AI 能力可以在服務(wù)端路由里調(diào)模型接口再把結(jié)果通過(guò) tRPC 返回前端。關(guān)鍵在于保持類型安全和分層意識(shí)新增功能時(shí)先修改 schema再定義路由最后寫界面不容易把系統(tǒng)寫亂。說(shuō)回最初我起名 t3code 其實(shí)沒(méi)有太復(fù)雜的含義就是“T3 棧的代碼倉(cāng)庫(kù)”的簡(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)解析
先說(shuō)說(shuō) t3code 是什么。它不是一個(gè)框架也不是某個(gè)大廠的開源項(xiàng)目而是我最近集中精力打磨的一套全棧工程樣例以 Next.js TypeScript 為核心集成了 Tailwind CSS、Prisma、tRPC 等一套組合目標(biāo)是把“從零到能穩(wěn)定上線”的全過(guò)程固化下來(lái)讓新項(xiàng)目不用總是重復(fù)踩坑。這套組合有一個(gè)社區(qū)里的普遍叫法T3 Stack。T3 這個(gè)概念最早來(lái)自對(duì)“TypeScript-first 全棧開發(fā)”的總結(jié)核心是相信扁平的端到端類型安全能減少大量無(wú)效溝通和低級(jí)錯(cuò)誤。我之所以給項(xiàng)目起名叫 t3code就是想把它當(dāng)作一套可以不斷復(fù)用的代碼底座既能承載真實(shí)業(yè)務(wù)也可以作為團(tuán)隊(duì)內(nèi)部腳手架甚至拿來(lái)對(duì)新人做全棧入門教學(xué)。下面這篇文章會(huì)把整個(gè)項(xiàng)目的設(shè)計(jì)思路、目錄結(jié)構(gòu)、數(shù)據(jù)模型、API 層、前端交互、測(cè)試部署和我在實(shí)際開發(fā)中踩過(guò)的坑完整講一遍。適合有一定 React 基礎(chǔ)、但對(duì)全棧工程化還比較陌生的讀者也適合想優(yōu)化技術(shù)棧選型的團(tuán)隊(duì)參考。1. 先把項(xiàng)目拆開t3code 的核心目標(biāo)與工程邊界1.1 這一套組合解決了什么問(wèn)題前端項(xiàng)目發(fā)展到今天困擾大家的往往不是“會(huì)不會(huì)寫組件”而是幾個(gè)老生常談的痛點(diǎn)前后端接口文檔對(duì)不上、類型不一致、配置分散、部署鏈路太長(zhǎng)、新人接手成本高。t3code 選擇 T3 Stack 的原因就在于此。Next.js 負(fù)責(zé)頁(yè)面、路由和服務(wù)端渲染框架本身已經(jīng)吸收了大量 Web 性能最佳實(shí)踐TypeScript 嚴(yán)格模式保證代碼在編譯階段就把大部分類型問(wèn)題暴露出來(lái)不需要等運(yùn)行時(shí)報(bào)錯(cuò)Tailwind CSS 把樣式從“命名地獄”里解放出來(lái)改排版再也不用擔(dān)心牽一發(fā)動(dòng)全身Prisma 提供數(shù)據(jù)庫(kù)建模、遷移和類型安全的客戶端tRPC 讓前后端 API 像調(diào)用本地函數(shù)一樣自然類型直接從服務(wù)端傳到客戶端。這一套組合真正解決的核心問(wèn)題是“認(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)用框架。換句話說(shuō)它默認(rèn)幫你把路由、樣式、數(shù)據(jù)庫(kù)、鑒權(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ù)庫(kù)、服務(wù)端渲染之間的關(guān)系。如果你已經(jīng)有兩年以上的 React/Node 經(jīng)驗(yàn)這套代碼讀起來(lái)基本沒(méi)有門檻如果你剛接觸全棧建議先把 React 基礎(chǔ)過(guò)一遍再動(dòng)手改樣式和數(shù)據(jù)模型。我自己帶過(guò)幾個(gè)實(shí)習(xí)生他們第一次看 t3code 的代碼時(shí)最大的障礙反而不是語(yǔ)法而是“服務(wù)端和客戶端到底怎么區(qū)分”。這一點(diǎn)在交流里我更傾向用最直白的方式解釋src/server 下面的代碼不會(huì)進(jìn)瀏覽器src/app 下面的代碼才是頁(yè)面入口剩下的事交給框架約定。2. 從零搭起 t3code工具鏈與工程化2.1 初始化工具鏈不該省的一步我習(xí)慣用 pnpm 管理依賴。相比 npm/yarnpnpm 對(duì)磁盤空間更友好依賴安裝速度也更快更重要的是它默認(rèn)做了更嚴(yán)格的依賴隔離不容易出現(xiàn)“本地能跑、打包就掛”的問(wè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ù)庫(kù)。所以在真正啟動(dòng)開發(fā)服務(wù)前你需要先把數(shù)據(jù)庫(kù)連接串和認(rèn)證配置填好。我記得第一次跑的時(shí)候漏掉了環(huán)境變量結(jié)果 tRPC 路由全部報(bào)錯(cuò)白排查了好幾個(gè)小時(shí)。還有一個(gè)小提醒生成器默認(rèn)可能在根目錄創(chuàng)建 .env 和 .env.example你可以立即把 .env.example 補(bǔ)全為一份“無(wú)敏感信息的模板”。我后來(lái)在團(tuán)隊(duì)協(xié)作中受益很大因?yàn)樾氯?clone 下來(lái)之后對(duì)著 example 文件就能快速知道要配哪些變量不用反復(fù)來(lái)問(wèn)。2.2 TS 嚴(yán)格性與項(xiàng)目結(jié)構(gòu)t3code 的 TypeScript 配置走的是“嚴(yán)格到底”的路線。說(shuō)實(shí)話剛開始寫會(huì)覺(jué)得有點(diǎn)煩比如可空類型、未使用變量、隱式 any 都會(huì)被編譯器攔下來(lái)。但這種方式長(zhǎng)期看非常劃算尤其是項(xiàng)目規(guī)模變大之后重構(gòu)時(shí)不會(huì)出現(xiàn)“改了一個(gè)對(duì)象屬性十幾個(gè)頁(yè)面默默出錯(cuò)”的場(chǎng)面。項(xiàng)目的核心目錄結(jié)構(gòu)如下src/ app/ # Next.js App Router 路由與頁(yè)面 components/ # 可復(fù)用的 React 組件 lib/ # 全局工具、數(shù)據(jù)庫(kù)實(shí)例、認(rèn)證配置 server/ # 服務(wù)端邏輯tRPC 路由、鑒權(quán)、上下文 styles/ # 全局樣式與 Tailwind 配置 prisma/ schema.prisma # 數(shù)據(jù)模型與數(shù)據(jù)庫(kù)配置這個(gè)結(jié)構(gòu)并不復(fù)雜但它把服務(wù)端和客戶端邏輯分得很清楚不會(huì)出現(xiàn)業(yè)務(wù)代碼互相糾纏的情況。尤其是 tRPC 的實(shí)例、上下文、路由必須放在服務(wù)端一旦放錯(cuò)位置很可能會(huì)把數(shù)據(jù)庫(kù)憑據(jù)泄漏到客戶端 bundle 里這個(gè)風(fēng)險(xiǎn)點(diǎn)需要重點(diǎn)記住。實(shí)際開發(fā)時(shí)我還會(huì)順手加一個(gè) src/env 目錄用來(lái)集中解析環(huán)境變量。create-t3-app 默認(rèn)會(huì)用 zod 對(duì) env 做運(yùn)行時(shí)校驗(yàn)這看起來(lái)有點(diǎn)小題大做但如果你在團(tuán)隊(duì)里見過(guò)“某個(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ù)庫(kù)的入口NEXTAUTH_SECRET 是 NextAuth 加密會(huì)話用的密鑰NEXTAUTH_URL 指定當(dāng)前應(yīng)用的地址。這三個(gè)是本地開發(fā)最基礎(chǔ)的三件套不要省略。注意生產(chǎn)環(huán)境不要使用本地?cái)?shù)據(jù)庫(kù)地址也不要把真實(shí)密鑰提交到 Git 倉(cāng)庫(kù)。我在團(tuán)隊(duì)里一直強(qiáng)調(diào).env 文件要進(jìn) .gitignore密鑰走專門的密鑰管理服務(wù)或部署平臺(tái)的 env 配置。順帶一提我在本地經(jīng)常用 docker 起一個(gè) MySQL 實(shí)例來(lái)跑開發(fā)庫(kù)。這個(gè)方案最大的好處是環(huán)境一致不會(huì)因?yàn)槊總€(gè)人本機(jī)裝的數(shù)據(jù)庫(kù)版本不同而出現(xiàn)奇怪的兼容問(wèn)題。用 docker compose 起個(gè)測(cè)試庫(kù)基本五分鐘搞定比手動(dòng)安裝數(shù)據(jù)庫(kù)省心。3. 數(shù)據(jù)層與業(yè)務(wù) API從 schema 到 tRPC 的完整鏈路3.1 Prisma 模型設(shè)計(jì)先想清楚關(guān)系t3code 的數(shù)據(jù)模型用 Prisma Schema 聲明。開發(fā)前最好先把“誰(shuí)和誰(shuí)有對(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 通過(guò) 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ù)庫(kù)里創(chuàng)建對(duì)應(yīng)的表并把 migration 歷史記錄下來(lái)方便團(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)來(lái)說(shuō)完全可接受換來(lái)的是更強(qiáng)的可遷移性。3.2 tRPC router 的設(shè)計(jì)接口即函數(shù)tRPC 的設(shè)計(jì)哲學(xué)是“接口即函數(shù)”。服務(wù)端定義一個(gè) router客戶端引入類型后調(diào)用起來(lái)就像調(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)也值得多說(shuō)兩句。很多人會(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ù)庫(kù)報(bào)錯(cuò)。這對(duì)接口健壯性的提升是立竿見影的。3.3 中間件與鑒權(quán)NextAuth 和 tRPC 的配合在 T3 Stack 里可以說(shuō)是“官方推薦組合”。它的流程是NextAuth 負(fù)責(zé)登錄會(huì)話tRPC createContext 會(huì)讀取 session 信息然后注入到每個(gè)路由的 ctx 中。我一開始遇到的問(wèn)題是把 session 類型定義寫得不夠嚴(yán)格導(dǎo)致客戶端拿到的 user 對(duì)象可能為 null。后來(lái)我加了類型斷言和中間件統(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è)中間件看起來(lái)很簡(jiǎn)單但它把“是否登錄”的判斷收斂到了一處。后面所有需要登錄的接口只要套一個(gè) protectedProcedure就不需要再重復(fù)寫判斷邏輯也不會(huì)出現(xiàn)漏判。注意登錄態(tài)判斷永遠(yuǎn)不要只依賴前端。即使你用了 tRPC前端路由可以寫各種守衛(wèi)但真正的數(shù)據(jù)訪問(wèn)控制一定發(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í)際寫頁(yè)面的時(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è)頁(yè)面里反復(fù)復(fù)制后續(xù)想統(tǒng)一改圓角、改陰影時(shí)只需要?jiǎng)右粋€(gè)地方。4.2 客戶端數(shù)據(jù)流把服務(wù)端數(shù)據(jù)拉起來(lái)在 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)過(guò)我才格外推薦 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ù)來(lái)自服務(wù)端最穩(wěn)妥的更新方式就是讓服務(wù)端重新給一份而不是在前端猜。4.3 性能兜底與加載體驗(yàn)全棧應(yīng)用很容易出現(xiàn)“數(shù)據(jù)太慢”的問(wèn)題。t3code 做性能優(yōu)化時(shí)主要抓三個(gè)點(diǎn)頁(yè)面骨架屏用服務(wù)端渲染先出 HTML配合 loading 狀態(tài)展示骨架減少白屏焦慮數(shù)據(jù)復(fù)用對(duì)不常變更的數(shù)據(jù)使用 React Query 的 staleTime 配置避免每次都發(fā)請(qǐng)求按需加載組件層面用 Next.js 的 dynamic import路由拆包避免首屏 bundle 過(guò)大。一個(gè)典型的示例是在根頁(yè)面組件里設(shè)置 staleTimeconst { data } api.post.list.useQuery( { limit: 10 }, { staleTime: 30_000 } );這樣 30 秒內(nèi)再次訪問(wèn)React Query 不會(huì)重新發(fā)起網(wǎng)絡(luò)請(qǐng)求直接使用緩存。對(duì)訪問(wèn)量的優(yōu)化非常明顯。這里還要提醒一句React Query 的 cache 默認(rèn)是內(nèi)存級(jí)的刷新頁(yè)面后一定會(huì)重新拉數(shù)據(jù)。如果你需要持久化緩存比如把用戶偏好設(shè)置存到 localStorage那就不能只依賴 React Query 默認(rèn)行為得配合 persist 之類的方案。大多數(shù)場(chǎng)景下默認(rèn)內(nèi)存緩存已經(jīng)夠用了不需要過(guò)早優(yōu)化。5. 測(cè)試、部署與運(yùn)維5.1 自動(dòng)化測(cè)試的最小集很多人習(xí)慣手動(dòng)點(diǎn)一遍頁(yè)面就當(dāng)測(cè)試過(guò)了但項(xiàng)目到中后期會(huì)越來(lái)越脆弱。t3code 里我保留了一個(gè)最小可用的測(cè)試集單元測(cè)試主要覆蓋工具函數(shù)和 tRPC 路由的輸入校驗(yàn)集成測(cè)試用 Vitest React Testing Library 渲染關(guān)鍵頁(yè)面數(shù)據(jù)庫(kù)測(cè)試在測(cè)試環(huán)境里跑內(nèi)存數(shù)據(jù)庫(kù)或獨(dú)立的測(cè)試庫(kù)驗(yàn)證數(shù)據(jù)模型。Vitest 配置非常輕直接在 vite.config 里加 test 字段就行它的 API 和 Jest 很接近遷移成本低。針對(duì) tRPC 路由測(cè)試我一般直接調(diào)用 router.createCaller 來(lái)模擬客戶端請(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ù)庫(kù)也不用起服務(wù)器測(cè)試速度非?？臁?.2 部署與數(shù)據(jù)庫(kù)前端部分部署到 Vercel 是成本最低的選擇push 到 Git 倉(cāng)庫(kù)后自動(dòng)構(gòu)建發(fā)布日常發(fā)布基本不需要手動(dòng)干預(yù)。數(shù)據(jù)庫(kù)我一般選擇托管數(shù)據(jù)庫(kù)服務(wù)避免自己維護(hù)服務(wù)器和高可用開發(fā)效率優(yōu)先。部署前Build 命令需要提前在環(huán)境變量里配置好DATABASE_URL指向生產(chǎn)數(shù)據(jù)庫(kù)NEXTAUTH_URL生產(chǎn)環(huán)境域名NEXTAUTH_SECRET新的隨機(jī)密鑰。在 Vercel 上配置時(shí)不要直接復(fù)制本地 .env應(yīng)該重新生成一套生產(chǎn)密鑰并限制數(shù)據(jù)庫(kù)白名單。很多安全事故其實(shí)不是代碼問(wèn)題而是開發(fā)環(huán)境的密鑰直接被帶到了線上。有一個(gè)經(jīng)驗(yàn)值得分享生產(chǎn)環(huán)境的 DATABASE_URL 要和本地隔離。如果本地和線上共用同一個(gè)數(shù)據(jù)庫(kù)開發(fā)時(shí)的誤操作很可能會(huì)污染生產(chǎn)數(shù)據(jù)尤其是跑 migrate reset 之類的命令時(shí)后果可能是毀滅性的。我自己的習(xí)慣是本地、預(yù)發(fā)布、生產(chǎn)各一套數(shù)據(jù)庫(kù)再怎么折騰都不影響線上。5.3 監(jiān)控與日志t3code 上線后重點(diǎn)觀察的數(shù)據(jù)有三類頁(yè)面錯(cuò)誤率、接口延遲、數(shù)據(jù)庫(kù)連接數(shù)。如果項(xiàng)目還比較小可以先用框架自帶的 logging 和 Sentry 這類服務(wù)先頂起來(lái)等業(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è)性兜住上線后排查問(wèn)題會(huì)省不少力氣。有朋友問(wèn)我為什么不用 Grafana / Prometheus 那套重型方案我的回答是看項(xiàng)目階段。如果你每天的請(qǐng)求量連一萬(wàn)都不到堆一堆監(jiān)控系統(tǒng)反而成了維護(hù)負(fù)擔(dān)。先把 log 打全、把錯(cuò)誤上報(bào)鏈路接好等業(yè)務(wù)真的需要再逐步加指標(biāo)系統(tǒng)這才是更務(wù)實(shí)的選擇。6. 常見問(wèn)題速查與個(gè)人心得6.1 高頻問(wèn)題一次說(shuō)清下面這個(gè)表格是我在 t3code 開發(fā)過(guò)程中反復(fù)遇到的幾個(gè)問(wèn)題整理出來(lái)供大家對(duì)照排查癥狀常見原因排查思路tRPC 請(qǐng)求全部報(bào) 500DATABASE_URL 沒(méi)有配置或者數(shù)據(jù)庫(kù)沒(méi)啟動(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ù)更新后頁(yè)面不刷新沒(méi)有調(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è)坑我踩過(guò)不止一次所以現(xiàn)在我會(huì)在部署腳本里強(qiáng)制執(zhí)行一行檢查如果某個(gè)環(huán)境的 secret 和本地相同直接中斷部署并給出警告。6.2 我在實(shí)際開發(fā)中維護(hù)的小習(xí)慣最后分享幾點(diǎn)長(zhǎng)期改動(dòng)下來(lái)的習(xí)慣。第一t3code 的所有數(shù)據(jù)庫(kù)模型都盡量以業(yè)務(wù)語(yǔ)義命名不在 schema 里堆“技術(shù)晦澀”的字段。比如使用 createdAt、updatedAt、authorId而不要用 ctime、utime、owner_id。名字清楚遷移時(shí)也容易讀懂歷史記錄。第二每一次修改 Prisma schema 后都立即生成 migration而不是攢到最后一起遷移。中途發(fā)現(xiàn)問(wèn)題時(shí)小的 migration 更好回滾和分析。第三不要在客戶端代碼里直接 import prisma也不要在組件里 import 任何 server-only 文件。t3code 的目錄劃分已經(jīng)把 server 目錄獨(dú)立出來(lái)這樣不僅能避免類型混亂也能防止把數(shù)據(jù)庫(kù)連接代碼打進(jìn)客戶端 bundle。6.3 后續(xù)還能怎么擴(kuò)展t3code 這套底座想擴(kuò)展成其他產(chǎn)品形態(tài)并不難。想做成多用戶協(xié)作工具可以在 User 模型加一個(gè) workspaceId再通過(guò) tRPC 中間件做資源隔離想做內(nèi)容社區(qū)可以加 Comment 模型和 Tag 模型想接 AI 能力可以在服務(wù)端路由里調(diào)模型接口再把結(jié)果通過(guò) tRPC 返回前端。關(guān)鍵在于保持類型安全和分層意識(shí)新增功能時(shí)先修改 schema再定義路由最后寫界面不容易把系統(tǒng)寫亂。說(shuō)回最初我起名 t3code 其實(shí)沒(méi)有太復(fù)雜的含義就是“T3 棧的代碼倉(cāng)庫(kù)”的簡(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ì)少走很多彎路。