踐：T3技術(shù)棧全鏈路類型安全與項(xiàng)目結(jié)構(gòu)指南)
1. 從“t3code”這個(gè)代號(hào)說(shuō)起它到底指什么第一次看到“t3code”這個(gè)詞很多人會(huì)一頭霧水。它不像“Python入門”或“React教程”那樣直白更像是一個(gè)圈內(nèi)人才懂的暗號(hào)。我最初接觸這個(gè)詞是在一個(gè)技術(shù)社群里有人發(fā)了一句“t3code跑通了”底下跟了一串“求配置”。當(dāng)時(shí)我翻遍了主流搜索引擎能找到的有效信息非常零散大部分是零碎的代碼片段和語(yǔ)焉不詳?shù)挠懻?。后?lái)花了不少時(shí)間梳理才慢慢拼出它的全貌。簡(jiǎn)單來(lái)說(shuō)t3code是一套圍繞“T3技術(shù)?！闭归_(kāi)的代碼組織方式與工程實(shí)踐約定。這里的“T3”通常指向一個(gè)特定的全棧開(kāi)發(fā)組合——TypeScript、tRPC、Tailwind CSS再加上一個(gè)現(xiàn)代前端框架常見(jiàn)的是Next.js。這套組合在近幾年的獨(dú)立開(kāi)發(fā)者和中小團(tuán)隊(duì)中流行度上升得很快原因很直接它把類型安全從數(shù)據(jù)庫(kù)一路貫穿到前端UI省掉了大量手寫接口類型和聯(lián)調(diào)扯皮的時(shí)間。而“code”這個(gè)后綴強(qiáng)調(diào)的是落地層面的代碼結(jié)構(gòu)、目錄約定和復(fù)用模式而不是單純的技術(shù)選型清單。你可能會(huì)問(wèn)為什么非要給這套東西起個(gè)代號(hào)我的理解是當(dāng)一套技術(shù)組合的實(shí)踐足夠成熟、足夠有辨識(shí)度時(shí)社區(qū)自然會(huì)需要一個(gè)簡(jiǎn)短的標(biāo)簽來(lái)指代它。就像“LAMP”代表LinuxApacheMySQLPHP一樣t3code代表的是“用T3棧寫出來(lái)的、經(jīng)過(guò)工程化沉淀的代碼形態(tài)”。它解決的核心問(wèn)題是在保證端到端類型安全的前提下如何讓項(xiàng)目結(jié)構(gòu)清晰、模塊邊界明確、新人能快速上手。這篇文章適合誰(shuí)看如果你正在用或打算用TypeScript做全棧項(xiàng)目如果你厭倦了前后端類型對(duì)不齊的煩惱如果你想知道一套成熟的T3項(xiàng)目到底該怎么組織目錄、怎么劃分模塊、怎么處理認(rèn)證和數(shù)據(jù)庫(kù)那接下來(lái)的內(nèi)容應(yīng)該對(duì)你有用。我會(huì)從核心原理講起然后拆解目錄結(jié)構(gòu)、關(guān)鍵配置、常見(jiàn)坑點(diǎn)最后分享一些我在實(shí)際項(xiàng)目里踩出來(lái)的經(jīng)驗(yàn)。全文基于我對(duì)這類項(xiàng)目的理解和實(shí)踐不涉及任何特定平臺(tái)的綁定。2. T3棧的底層邏輯為什么這套組合能解決類型安全問(wèn)題2.1 類型安全的全鏈路是怎么打通的要理解t3code的價(jià)值得先搞清楚一個(gè)根本問(wèn)題傳統(tǒng)全棧開(kāi)發(fā)里類型信息是在哪里斷掉的。假設(shè)你用React寫前端用Node.js寫后端數(shù)據(jù)庫(kù)用PostgreSQL。前端定義了一個(gè)User接口后端也定義了一個(gè)User接口數(shù)據(jù)庫(kù)里還有一張users表。這三處的“User”看起來(lái)一樣實(shí)際上各寫各的。后端改了一個(gè)字段名前端不知道直到運(yùn)行時(shí)接口報(bào)錯(cuò)才發(fā)現(xiàn)。這就是典型的“類型斷裂”。T3棧的思路是讓類型信息從數(shù)據(jù)庫(kù)schema自動(dòng)流向API層再自動(dòng)流向客戶端調(diào)用處。具體怎么做到的數(shù)據(jù)庫(kù)層用Prisma或Drizzle這類ORM它們能從schema生成TypeScript類型。API層用tRPC它利用TypeScript的泛型推導(dǎo)把后端函數(shù)的輸入輸出類型直接暴露給前端。前端調(diào)用時(shí)編輯器能實(shí)時(shí)提示參數(shù)類型和返回值結(jié)構(gòu)寫錯(cuò)了立刻標(biāo)紅。整個(gè)過(guò)程不需要手寫任何接口類型定義也不需要生成中間文件。我舉個(gè)具體的例子。假設(shè)后端有一個(gè)getUserById的tRPC procedure輸入是{ id: string }返回是User類型。前端這樣調(diào)用const { data } trpc.user.getUserById.useQuery({ id: abc123 });此時(shí)data的類型會(huì)被自動(dòng)推導(dǎo)為User | undefined。如果你把id寫成數(shù)字編輯器會(huì)直接報(bào)錯(cuò)。如果后端把返回類型改了前端所有調(diào)用處會(huì)立刻出現(xiàn)類型錯(cuò)誤提示。這種“改一處、全鏈路感知”的體驗(yàn)是T3棧最核心的賣點(diǎn)。2.2 tRPC相比REST和GraphQL的取舍有人會(huì)問(wèn)GraphQL也能做到類型安全為什么還要用tRPC這里涉及一個(gè)關(guān)鍵的取舍。GraphQL的類型安全依賴于schema定義和代碼生成步驟你需要維護(hù)一份SDL然后跑codegen生成前端類型。多了一個(gè)中間環(huán)節(jié)就多了一層維護(hù)成本。而tRPC完全基于TypeScript的類型推導(dǎo)沒(méi)有schema文件沒(méi)有代碼生成后端函數(shù)即接口定義。對(duì)于TypeScript monorepo項(xiàng)目來(lái)說(shuō)這種“零中間層”的體驗(yàn)非常順滑。當(dāng)然tRPC也有明顯的局限。它天然綁定TypeScript如果你的客戶端是Swift或Kotlin就用不了。它也不適合對(duì)外暴露公共API因?yàn)樗念愋屯茖?dǎo)依賴服務(wù)端代碼。所以t3code的適用場(chǎng)景很明確前后端都是TypeScript、團(tuán)隊(duì)規(guī)模不大、迭代速度要求高、不需要對(duì)外開(kāi)放API。在這個(gè)邊界內(nèi)它的開(kāi)發(fā)效率優(yōu)勢(shì)非常明顯。2.3 Tailwind和Next.js在其中的角色Tailwind CSS在T3棧里的作用經(jīng)常被低估。很多人覺(jué)得它只是個(gè)CSS框架但在t3code的語(yǔ)境下它承擔(dān)了“樣式與組件同構(gòu)”的職責(zé)。因?yàn)門ailwind的類名直接寫在JSX里組件的樣式和邏輯是綁定在一起的復(fù)制一個(gè)組件到另一個(gè)項(xiàng)目樣式不會(huì)丟。這對(duì)于快速搭建UI、保持設(shè)計(jì)一致性很有幫助。Next.js則提供了全棧的運(yùn)行時(shí)基礎(chǔ)。它的API Routes或Server Actions可以承載tRPC的handler它的文件路由系統(tǒng)讓頁(yè)面組織變得直觀它的SSR/SSG能力讓首屏性能有保障。更重要的是Next.js的app目錄模式支持React Server Components這意味著部分?jǐn)?shù)據(jù)獲取可以放在服務(wù)端完成減少客戶端的請(qǐng)求瀑布。T3棧和Next.js的結(jié)合本質(zhì)上是在“類型安全”之外再疊加一層“渲染性能”的優(yōu)化。3. 一個(gè)標(biāo)準(zhǔn)t3code項(xiàng)目的目錄骨架長(zhǎng)什么樣3.1 頂層目錄的劃分邏輯我見(jiàn)過(guò)不少T3項(xiàng)目目錄結(jié)構(gòu)五花八門但跑得順的項(xiàng)目往往遵循一些共同的約定。下面這個(gè)結(jié)構(gòu)是我自己反復(fù)調(diào)整后覺(jué)得比較順手的版本├── prisma/ │ ├── schema.prisma │ └── migrations/ ├── src/ │ ├── app/ │ │ ├── (auth)/ │ │ ├── (main)/ │ │ └── api/ │ ├── components/ │ │ ├── ui/ │ │ └── features/ │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ │ │ │ ├── root.ts │ │ │ └── trpc.ts │ │ ├── auth/ │ │ └── db/ │ ├── lib/ │ ├── styles/ │ └── types/ ├── public/ ├── .env ├── next.config.js ├── tailwind.config.ts └── tsconfig.json這個(gè)結(jié)構(gòu)的核心思路是按職責(zé)分層而不是按文件類型分層。src/server下面集中放所有服務(wù)端代碼包括tRPC路由、認(rèn)證邏輯、數(shù)據(jù)庫(kù)客戶端。src/app是Next.js的頁(yè)面和API入口。src/components放React組件其中ui放通用基礎(chǔ)組件features放業(yè)務(wù)組件。src/lib放工具函數(shù)和共享邏輯。為什么要把server和app分開(kāi)因?yàn)镹ext.js的app目錄里既有服務(wù)端代碼也有客戶端代碼邊界容易模糊。把tRPC路由和數(shù)據(jù)庫(kù)邏輯單獨(dú)抽到server目錄能強(qiáng)制形成一道心理邊界這里的代碼只在服務(wù)端運(yùn)行不要在前端組件里直接import。3.2 tRPC路由的嵌套與合并tRPC的路由組織是t3code里最需要花心思的部分。一個(gè)常見(jiàn)的做法是每個(gè)業(yè)務(wù)領(lǐng)域一個(gè)router文件然后在root.ts里合并。// src/server/api/routers/user.ts import { z } from zod; import { createTRPCRouter, protectedProcedure } from ../trpc; export const userRouter createTRPCRouter({ getById: protectedProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx, input }) { return ctx.db.user.findUnique({ where: { id: input.id } }); }), updateProfile: protectedProcedure .input(z.object({ name: z.string().min(1) })) .mutation(async ({ ctx, input }) { return ctx.db.user.update({ where: { id: ctx.session.user.id }, data: { name: input.name }, }); }), });然后在root.ts里合并// src/server/api/root.ts import { createTRPCRouter } from ./trpc; import { userRouter } from ./routers/user; import { postRouter } from ./routers/post; export const appRouter createTRPCRouter({ user: userRouter, post: postRouter, }); export type AppRouter typeof appRouter;這里的關(guān)鍵點(diǎn)是AppRouter類型的導(dǎo)出。前端通過(guò)import type { AppRouter } from ~/server/api/root拿到這個(gè)類型tRPC的client就能自動(dòng)推導(dǎo)出所有路由的輸入輸出類型。這個(gè)類型導(dǎo)入是純類型導(dǎo)入不會(huì)把服務(wù)端代碼打包進(jìn)客戶端。3.3 組件目錄的拆分策略components目錄的拆分我踩過(guò)坑。一開(kāi)始我把所有組件都放在一個(gè)components文件夾里結(jié)果很快就亂了。后來(lái)改成兩層ui放無(wú)業(yè)務(wù)邏輯的通用組件比如Button、Input、Modal、Cardfeatures放帶業(yè)務(wù)邏輯的組件比如UserProfile、PostList、CommentForm。這樣拆的好處是ui組件可以跨項(xiàng)目復(fù)用它們只依賴props不依賴tRPC或數(shù)據(jù)庫(kù)。features組件可以自由調(diào)用tRPC hooks因?yàn)樗鼈儽緛?lái)就是業(yè)務(wù)的一部分。當(dāng)你想把某個(gè)功能模塊抽成獨(dú)立包時(shí)features下的目錄可以直接搬走依賴關(guān)系清晰。還有一個(gè)細(xì)節(jié)features下的組件盡量按業(yè)務(wù)領(lǐng)域建子目錄比如features/user/、features/post/。每個(gè)子目錄里可以放組件、hooks、工具函數(shù)形成一個(gè)自包含的模塊。這樣當(dāng)業(yè)務(wù)增長(zhǎng)時(shí)你不會(huì)在一個(gè)巨大的components文件夾里大海撈針。4. 環(huán)境搭建與核心配置從零跑通第一個(gè)t3code項(xiàng)目4.1 初始化項(xiàng)目時(shí)最容易忽略的三個(gè)配置現(xiàn)在社區(qū)里有現(xiàn)成的腳手架工具可以一鍵生成T3項(xiàng)目但自動(dòng)生成的東西往往讓人知其然不知其所以然。我建議至少手動(dòng)過(guò)一遍關(guān)鍵配置這樣出了問(wèn)題才知道去哪里找。第一個(gè)容易忽略的是tsconfig.json里的路徑別名。T3項(xiàng)目通常用~或指向src目錄這樣import路徑不會(huì)出現(xiàn)../../..這種反人類寫法。配置大概長(zhǎng)這樣{ compilerOptions: { baseUrl: ., paths: { ~/*: [./src/*] } } }配完之后import { Button } from ~/components/ui/button就能正常解析。但要注意Next.js的app目錄和src目錄的關(guān)系需要確認(rèn)清楚如果app在src下面路徑別名要相應(yīng)調(diào)整。第二個(gè)是環(huán)境變量的類型聲明。T3項(xiàng)目通常用t3-oss/env-nextjs這個(gè)包來(lái)管理環(huán)境變量它能在構(gòu)建時(shí)校驗(yàn)變量是否存在、格式是否正確。配置在src/env.js里import { createEnv } from t3-oss/env-nextjs; import { z } from zod; export const env createEnv({ server: { DATABASE_URL: z.string().url(), NEXTAUTH_SECRET: z.string().min(1), }, client: { NEXT_PUBLIC_APP_URL: z.string().url(), }, runtimeEnv: { DATABASE_URL: process.env.DATABASE_URL, NEXTAUTH_SECRET: process.env.NEXTAUTH_SECRET, NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL, }, });這樣做的好處是如果忘了配某個(gè)環(huán)境變量項(xiàng)目啟動(dòng)時(shí)會(huì)直接報(bào)錯(cuò)而不是等到運(yùn)行時(shí)才出現(xiàn)莫名其妙的undefined。第三個(gè)是Prisma的客戶端單例模式。在開(kāi)發(fā)環(huán)境下Next.js的熱重載會(huì)反復(fù)執(zhí)行模塊代碼如果每次都new PrismaClient()數(shù)據(jù)庫(kù)連接數(shù)會(huì)迅速耗盡。標(biāo)準(zhǔn)做法是在src/server/db.ts里做全局單例import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma: PrismaClient | undefined; }; export const db globalForPrisma.prisma ?? new PrismaClient({ log: process.env.NODE_ENV development ? [query, error, warn] : [error], }); if (process.env.NODE_ENV ! production) globalForPrisma.prisma db;這個(gè)模式在Prisma官方文檔里有詳細(xì)說(shuō)明但很多新手會(huì)忽略導(dǎo)致開(kāi)發(fā)時(shí)數(shù)據(jù)庫(kù)連接報(bào)錯(cuò)。4.2 tRPC上下文與認(rèn)證的銜接方式tRPC的context是連接認(rèn)證系統(tǒng)和數(shù)據(jù)庫(kù)的橋梁。在src/server/api/trpc.ts里你需要定義createTRPCContext函數(shù)它接收每個(gè)請(qǐng)求的原始信息返回一個(gè)包含db和session的對(duì)象。import { initTRPC, TRPCError } from trpc/server; import { type Session } from next-auth; import { db } from ../db; interface CreateContextOptions { session: Session | null; } export const createTRPCContext async (opts: CreateContextOptions) { return { db, session: opts.session, }; }; const t initTRPC.contexttypeof createTRPCContext().create(); export const createTRPCRouter t.router; export const publicProcedure t.procedure; 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 }, }, }); });這里的關(guān)鍵設(shè)計(jì)是protectedProcedure。它通過(guò)中間件檢查session是否存在如果不存在就拋UNAUTHORIZED錯(cuò)誤。所有需要登錄的接口都用protectedProcedure定義這樣認(rèn)證邏輯只寫一次所有路由自動(dòng)繼承。認(rèn)證系統(tǒng)本身通常用NextAuth現(xiàn)在叫Auth.js它和tRPC的集成點(diǎn)在于NextAuth負(fù)責(zé)處理登錄流程和session管理tRPC的context從NextAuth的getServerSession里拿session。兩者通過(guò)createTRPCContext的調(diào)用處銜接通常在Next.js的API handler里完成。4.3 數(shù)據(jù)庫(kù)schema設(shè)計(jì)中的類型推導(dǎo)技巧Prisma schema是類型鏈路的起點(diǎn)。你在schema里定義的每個(gè)modelPrisma都會(huì)生成對(duì)應(yīng)的TypeScript類型。這些類型會(huì)通過(guò)tRPC的返回類型自動(dòng)流向客戶端。model Post { id String id default(cuid()) title String content String? published Boolean default(false) authorId String author User relation(fields: [authorId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt }這個(gè)Postmodel會(huì)生成Post類型包含所有字段。當(dāng)你在tRPC的postRouter里返回一個(gè)Post對(duì)象時(shí)前端拿到的data類型就是Post。如果你在schema里加了一個(gè)字段Prisma重新生成后前端所有用到這個(gè)類型的地方都會(huì)自動(dòng)更新。有一個(gè)技巧值得分享用Prisma的select和include來(lái)精確控制返回類型。比如你不想把用戶的密碼哈希返回給前端可以在查詢時(shí)用select排除掉。這樣生成的類型里就不會(huì)包含敏感字段前端也無(wú)法訪問(wèn)。const user await ctx.db.user.findUnique({ where: { id: input.id }, select: { id: true, name: true, email: true, image: true }, });這樣返回的類型就是{ id: string; name: string | null; email: string; image: string | null }不包含passwordHash。類型安全在這里不僅是防錯(cuò)也是防泄露。5. 實(shí)際開(kāi)發(fā)中那些文檔不會(huì)告訴你的坑5.1 類型推導(dǎo)在復(fù)雜嵌套路由下的性能問(wèn)題tRPC的類型推導(dǎo)很強(qiáng)大但當(dāng)路由數(shù)量增長(zhǎng)到幾十個(gè)、每個(gè)路由的輸入輸出類型都很復(fù)雜時(shí)TypeScript的類型檢查速度會(huì)明顯下降。我遇到過(guò)一次項(xiàng)目里有大概四十多個(gè)procedure編輯器里每次保存文件都要等三四秒才能出類型提示。后來(lái)排查發(fā)現(xiàn)問(wèn)題出在AppRouter類型的遞歸推導(dǎo)上。解決辦法有兩個(gè)。一是拆分router把不相關(guān)的業(yè)務(wù)路由分到不同的子router里減少單個(gè)router的復(fù)雜度。二是避免在procedure的返回類型里使用過(guò)深的嵌套對(duì)象如果某個(gè)接口返回的數(shù)據(jù)結(jié)構(gòu)特別復(fù)雜考慮用zod定義明確的輸出schema而不是讓TypeScript去推導(dǎo)。還有一個(gè)相關(guān)的坑在monorepo里如果前端和后端在不同的package里AppRouter類型的導(dǎo)入路徑會(huì)變得很長(zhǎng)TypeScript需要跨package解析類型。這種情況下建議在共享package里放一個(gè)types.ts只導(dǎo)出AppRouter類型前端從那里導(dǎo)入減少解析開(kāi)銷。5.2 客戶端組件與服務(wù)端組件的邊界混淆Next.js的app目錄引入了React Server Components的概念這給t3code項(xiàng)目帶來(lái)了新的復(fù)雜度。默認(rèn)情況下app目錄下的組件是Server Component它們不能使用useState、useEffect也不能調(diào)用tRPC的useQueryhook。如果你不小心在Server Component里寫了客戶端代碼會(huì)看到一堆莫名其妙的報(bào)錯(cuò)。我的經(jīng)驗(yàn)是在文件頂部明確標(biāo)注use client并且盡量把客戶端組件推到葉子節(jié)點(diǎn)。比如一個(gè)頁(yè)面整體是Server Component負(fù)責(zé)數(shù)據(jù)預(yù)取和布局只有需要交互的部分比如一個(gè)點(diǎn)贊按鈕、一個(gè)表單才抽成Client Component。這樣既能享受Server Component的性能優(yōu)勢(shì)又能保留交互能力。tRPC在Server Component里的用法和Client Component不同。Server Component里不能直接用trpc.xxx.useQuery()而是要用createCaller或者api.xxx()的方式直接調(diào)用服務(wù)端函數(shù)。這個(gè)切換點(diǎn)容易搞混建議在項(xiàng)目初期就定好規(guī)范哪些頁(yè)面用Server Component哪些用Client ComponenttRPC的調(diào)用方式分別是什么。5.3 數(shù)據(jù)庫(kù)遷移與類型同步的時(shí)序問(wèn)題Prisma的遷移流程是改schema → 跑prisma migrate dev→ 生成新客戶端 → TypeScript類型更新。這個(gè)鏈條里有一個(gè)時(shí)序問(wèn)題如果你改了schema但忘了跑遷移或者遷移失敗了但客戶端已經(jīng)生成類型和數(shù)據(jù)庫(kù)實(shí)際結(jié)構(gòu)就會(huì)不一致。我踩過(guò)一次坑在schema里加了一個(gè)可選字段跑遷移時(shí)因?yàn)閿?shù)據(jù)庫(kù)里有臟數(shù)據(jù)導(dǎo)致遷移失敗但Prisma客戶端已經(jīng)生成了包含新字段的類型。結(jié)果代碼里訪問(wèn)這個(gè)字段時(shí)類型檢查通過(guò)運(yùn)行時(shí)卻報(bào)錯(cuò)說(shuō)列不存在。排查了半天才發(fā)現(xiàn)是遷移沒(méi)成功。避免這個(gè)問(wèn)題的辦法是每次改schema后先確認(rèn)遷移成功再重新生成客戶端?？梢栽趐ackage.json里加一個(gè)腳本把遷移和生成綁在一起{ scripts: { db:migrate: prisma migrate dev prisma generate } }另外在CI流程里要加一步檢查確保遷移文件和schema是同步的。Prisma提供了prisma migrate diff命令可以對(duì)比schema和數(shù)據(jù)庫(kù)的實(shí)際差異適合在CI里做校驗(yàn)。5.4 生產(chǎn)環(huán)境構(gòu)建時(shí)的類型檢查策略Next.js的next build默認(rèn)會(huì)跑TypeScript類型檢查。在t3code項(xiàng)目里這個(gè)檢查可能會(huì)很慢因?yàn)閠RPC的類型推導(dǎo)本身就耗時(shí)。如果每次構(gòu)建都全量檢查CI時(shí)間會(huì)拉得很長(zhǎng)。我的做法是在本地開(kāi)發(fā)時(shí)用tsc --noEmit --watch做增量檢查在CI里用next build做全量檢查但把類型檢查單獨(dú)抽成一個(gè)job。這樣構(gòu)建和類型檢查可以并行節(jié)省時(shí)間。另外可以在next.config.js里配置typescript.ignoreBuildErrors為false默認(rèn)就是false確保構(gòu)建時(shí)不會(huì)跳過(guò)類型錯(cuò)誤。還有一個(gè)細(xì)節(jié)如果項(xiàng)目里用了zod做輸入校驗(yàn)確保zod的版本在前后端一致。我曾經(jīng)遇到過(guò)前端用zod 3.21、后端用zod 3.22導(dǎo)致某些校驗(yàn)行為不一致類型推導(dǎo)也出現(xiàn)了偏差。把zod固定在同一個(gè)版本能避免這類問(wèn)題。6. 從能跑到好用t3code項(xiàng)目的優(yōu)化與擴(kuò)展思路6.1 用中間件統(tǒng)一處理日志和錯(cuò)誤tRPC的中間件機(jī)制很適合做橫切關(guān)注點(diǎn)。除了認(rèn)證還可以加日志中間件、錯(cuò)誤上報(bào)中間件、性能計(jì)時(shí)中間件。比如一個(gè)簡(jiǎn)單的日志中間件const loggerMiddleware t.middleware(async ({ path, type, next }) { const start Date.now(); const result await next(); const duration Date.now() - start; console.log([trpc] ${type} ${path} - ${duration}ms); return result; }); export const loggedProcedure t.procedure.use(loggerMiddleware);然后在需要的地方用loggedProcedure替代publicProcedure。這樣每個(gè)請(qǐng)求的耗時(shí)和路徑都會(huì)被記錄排查性能問(wèn)題時(shí)很有用。錯(cuò)誤處理也可以用中間件統(tǒng)一格式化。tRPC拋出的TRPCError會(huì)帶著錯(cuò)誤碼和消息傳到前端前端可以用error.message展示用戶友好的提示。但要注意不要把服務(wù)端的堆棧信息暴露給前端中間件里可以做一層過(guò)濾。6.2 共享邏輯的抽離與復(fù)用模式t3code項(xiàng)目里有些邏輯是前后端都要用的比如數(shù)據(jù)校驗(yàn)規(guī)則、常量定義、工具函數(shù)。這些代碼應(yīng)該放在src/lib或一個(gè)獨(dú)立的packages/shared里前后端都從這里導(dǎo)入。一個(gè)典型的例子是zod schema。后端用zod校驗(yàn)輸入前端也可以用同一個(gè)schema做表單校驗(yàn)。這樣校驗(yàn)規(guī)則只寫一次前后端行為一致。// src/lib/validators/post.ts import { z } from zod; export const createPostSchema z.object({ title: z.string().min(1).max(100), content: z.string().max(5000).optional(), }); export type CreatePostInput z.infertypeof createPostSchema;后端在tRPC procedure里用createPostSchema做input校驗(yàn)前端在表單提交前用同一個(gè)schema做校驗(yàn)。類型CreatePostInput也可以前后端共用。這種復(fù)用模式能顯著減少重復(fù)代碼和不一致問(wèn)題。6.3 性能監(jiān)控與類型安全的平衡類型安全不是免費(fèi)的它需要TypeScript在編譯時(shí)做大量推導(dǎo)。在大型項(xiàng)目里這個(gè)開(kāi)銷會(huì)體現(xiàn)在構(gòu)建時(shí)間和編輯器響應(yīng)速度上。我的經(jīng)驗(yàn)是在核心業(yè)務(wù)路徑上保持嚴(yán)格的類型安全在邊緣邏輯上適當(dāng)放寬。比如對(duì)于數(shù)據(jù)庫(kù)查詢和API接口堅(jiān)持用Prisma和tRPC的完整類型推導(dǎo)。但對(duì)于一些純展示組件、工具函數(shù)可以用更寬松的類型甚至用any做臨時(shí)過(guò)渡但要加注釋說(shuō)明原因。關(guān)鍵是找到一個(gè)平衡點(diǎn)既不讓類型系統(tǒng)拖慢開(kāi)發(fā)速度也不讓類型漏洞導(dǎo)致運(yùn)行時(shí)錯(cuò)誤。另外可以用tsc --diagnostics查看類型檢查的耗時(shí)分布找出最耗時(shí)的文件或模塊針對(duì)性優(yōu)化。常見(jiàn)的手段包括減少泛型嵌套、避免循環(huán)引用、拆分大型類型定義。6.4 團(tuán)隊(duì)協(xié)作中的代碼規(guī)范約定t3code項(xiàng)目在團(tuán)隊(duì)協(xié)作時(shí)最大的挑戰(zhàn)不是技術(shù)本身而是約定的一致性。如果每個(gè)人對(duì)目錄結(jié)構(gòu)、命名方式、路由劃分的理解不同項(xiàng)目很快就會(huì)變得難以維護(hù)。我建議在項(xiàng)目初期就定好這幾條規(guī)范tRPC路由按業(yè)務(wù)領(lǐng)域劃分每個(gè)router文件不超過(guò)200行組件按ui和features分層features下按業(yè)務(wù)建子目錄所有數(shù)據(jù)庫(kù)操作必須通過(guò)ctx.db不允許在組件里直接import Prisma客戶端環(huán)境變量必須通過(guò)env.js訪問(wèn)不允許直接讀process.env。這些規(guī)范看起來(lái)瑣碎但能避免很多后期重構(gòu)的痛苦。可以用ESLint的no-restricted-imports規(guī)則來(lái)強(qiáng)制某些約定比如禁止從prisma/client直接導(dǎo)入到src/app目錄。工具能做的事就不要靠人的自覺(jué)。7. 關(guān)于t3code的一些個(gè)人體會(huì)我在幾個(gè)中小型項(xiàng)目里用過(guò)T3棧最大的感受是它把“類型安全”從一個(gè)口號(hào)變成了日常開(kāi)發(fā)中能感知到的便利。以前改一個(gè)字段名要全局搜索替換現(xiàn)在編輯器直接標(biāo)紅以前前后端聯(lián)調(diào)要對(duì)著文檔對(duì)參數(shù)現(xiàn)在類型提示直接告訴你該傳什么。這種體驗(yàn)上的提升用久了就回不去了。但它也不是銀彈。tRPC的生態(tài)相對(duì)年輕遇到一些邊緣場(chǎng)景時(shí)文檔和社區(qū)答案不如REST那么豐富。Next.js的版本迭代很快app目錄和pages目錄的混用有時(shí)會(huì)讓人困惑。Prisma在某些復(fù)雜查詢場(chǎng)景下生成的SQL不夠優(yōu)化需要手動(dòng)調(diào)優(yōu)。這些問(wèn)題都需要在實(shí)際項(xiàng)目中慢慢積累經(jīng)驗(yàn)。如果你打算開(kāi)始一個(gè)T3項(xiàng)目我的建議是先用腳手架跑通一個(gè)最小可用的demo然后花時(shí)間理解每個(gè)配置項(xiàng)的作用再逐步替換成自己的業(yè)務(wù)邏輯。不要一上來(lái)就追求完美的目錄結(jié)構(gòu)先讓項(xiàng)目跑起來(lái)然后在迭代中調(diào)整。類型安全的價(jià)值在于長(zhǎng)期維護(hù)而不是一開(kāi)始就完美無(wú)缺。最后分享一個(gè)小技巧在package.json里加一個(gè)typecheck腳本用tsc --noEmit做全量類型檢查然后在提交代碼前跑一遍。這個(gè)習(xí)慣能幫你提前發(fā)現(xiàn)很多類型問(wèn)題避免把錯(cuò)誤帶到CI階段。配合編輯器的實(shí)時(shí)提示基本上能做到“寫的時(shí)候就知道對(duì)不對(duì)”。 t3code工程實(shí)踐：T3技術(shù)棧全鏈路類型安全與項(xiàng)目結(jié)構(gòu)指南
1. 從“t3code”這個(gè)代號(hào)說(shuō)起它到底指什么第一次看到“t3code”這個(gè)詞很多人會(huì)一頭霧水。它不像“Python入門”或“React教程”那樣直白更像是一個(gè)圈內(nèi)人才懂的暗號(hào)。我最初接觸這個(gè)詞是在一個(gè)技術(shù)社群里有人發(fā)了一句“t3code跑通了”底下跟了一串“求配置”。當(dāng)時(shí)我翻遍了主流搜索引擎能找到的有效信息非常零散大部分是零碎的代碼片段和語(yǔ)焉不詳?shù)挠懻?。后?lái)花了不少時(shí)間梳理才慢慢拼出它的全貌。簡(jiǎn)單來(lái)說(shuō)t3code是一套圍繞“T3技術(shù)?！闭归_(kāi)的代碼組織方式與工程實(shí)踐約定。這里的“T3”通常指向一個(gè)特定的全棧開(kāi)發(fā)組合——TypeScript、tRPC、Tailwind CSS再加上一個(gè)現(xiàn)代前端框架常見(jiàn)的是Next.js。這套組合在近幾年的獨(dú)立開(kāi)發(fā)者和中小團(tuán)隊(duì)中流行度上升得很快原因很直接它把類型安全從數(shù)據(jù)庫(kù)一路貫穿到前端UI省掉了大量手寫接口類型和聯(lián)調(diào)扯皮的時(shí)間。而“code”這個(gè)后綴強(qiáng)調(diào)的是落地層面的代碼結(jié)構(gòu)、目錄約定和復(fù)用模式而不是單純的技術(shù)選型清單。你可能會(huì)問(wèn)為什么非要給這套東西起個(gè)代號(hào)我的理解是當(dāng)一套技術(shù)組合的實(shí)踐足夠成熟、足夠有辨識(shí)度時(shí)社區(qū)自然會(huì)需要一個(gè)簡(jiǎn)短的標(biāo)簽來(lái)指代它。就像“LAMP”代表LinuxApacheMySQLPHP一樣t3code代表的是“用T3棧寫出來(lái)的、經(jīng)過(guò)工程化沉淀的代碼形態(tài)”。它解決的核心問(wèn)題是在保證端到端類型安全的前提下如何讓項(xiàng)目結(jié)構(gòu)清晰、模塊邊界明確、新人能快速上手。這篇文章適合誰(shuí)看如果你正在用或打算用TypeScript做全棧項(xiàng)目如果你厭倦了前后端類型對(duì)不齊的煩惱如果你想知道一套成熟的T3項(xiàng)目到底該怎么組織目錄、怎么劃分模塊、怎么處理認(rèn)證和數(shù)據(jù)庫(kù)那接下來(lái)的內(nèi)容應(yīng)該對(duì)你有用。我會(huì)從核心原理講起然后拆解目錄結(jié)構(gòu)、關(guān)鍵配置、常見(jiàn)坑點(diǎn)最后分享一些我在實(shí)際項(xiàng)目里踩出來(lái)的經(jīng)驗(yàn)。全文基于我對(duì)這類項(xiàng)目的理解和實(shí)踐不涉及任何特定平臺(tái)的綁定。2. T3棧的底層邏輯為什么這套組合能解決類型安全問(wèn)題2.1 類型安全的全鏈路是怎么打通的要理解t3code的價(jià)值得先搞清楚一個(gè)根本問(wèn)題傳統(tǒng)全棧開(kāi)發(fā)里類型信息是在哪里斷掉的。假設(shè)你用React寫前端用Node.js寫后端數(shù)據(jù)庫(kù)用PostgreSQL。前端定義了一個(gè)User接口后端也定義了一個(gè)User接口數(shù)據(jù)庫(kù)里還有一張users表。這三處的“User”看起來(lái)一樣實(shí)際上各寫各的。后端改了一個(gè)字段名前端不知道直到運(yùn)行時(shí)接口報(bào)錯(cuò)才發(fā)現(xiàn)。這就是典型的“類型斷裂”。T3棧的思路是讓類型信息從數(shù)據(jù)庫(kù)schema自動(dòng)流向API層再自動(dòng)流向客戶端調(diào)用處。具體怎么做到的數(shù)據(jù)庫(kù)層用Prisma或Drizzle這類ORM它們能從schema生成TypeScript類型。API層用tRPC它利用TypeScript的泛型推導(dǎo)把后端函數(shù)的輸入輸出類型直接暴露給前端。前端調(diào)用時(shí)編輯器能實(shí)時(shí)提示參數(shù)類型和返回值結(jié)構(gòu)寫錯(cuò)了立刻標(biāo)紅。整個(gè)過(guò)程不需要手寫任何接口類型定義也不需要生成中間文件。我舉個(gè)具體的例子。假設(shè)后端有一個(gè)getUserById的tRPC procedure輸入是{ id: string }返回是User類型。前端這樣調(diào)用const { data } trpc.user.getUserById.useQuery({ id: abc123 });此時(shí)data的類型會(huì)被自動(dòng)推導(dǎo)為User | undefined。如果你把id寫成數(shù)字編輯器會(huì)直接報(bào)錯(cuò)。如果后端把返回類型改了前端所有調(diào)用處會(huì)立刻出現(xiàn)類型錯(cuò)誤提示。這種“改一處、全鏈路感知”的體驗(yàn)是T3棧最核心的賣點(diǎn)。2.2 tRPC相比REST和GraphQL的取舍有人會(huì)問(wèn)GraphQL也能做到類型安全為什么還要用tRPC這里涉及一個(gè)關(guān)鍵的取舍。GraphQL的類型安全依賴于schema定義和代碼生成步驟你需要維護(hù)一份SDL然后跑codegen生成前端類型。多了一個(gè)中間環(huán)節(jié)就多了一層維護(hù)成本。而tRPC完全基于TypeScript的類型推導(dǎo)沒(méi)有schema文件沒(méi)有代碼生成后端函數(shù)即接口定義。對(duì)于TypeScript monorepo項(xiàng)目來(lái)說(shuō)這種“零中間層”的體驗(yàn)非常順滑。當(dāng)然tRPC也有明顯的局限。它天然綁定TypeScript如果你的客戶端是Swift或Kotlin就用不了。它也不適合對(duì)外暴露公共API因?yàn)樗念愋屯茖?dǎo)依賴服務(wù)端代碼。所以t3code的適用場(chǎng)景很明確前后端都是TypeScript、團(tuán)隊(duì)規(guī)模不大、迭代速度要求高、不需要對(duì)外開(kāi)放API。在這個(gè)邊界內(nèi)它的開(kāi)發(fā)效率優(yōu)勢(shì)非常明顯。2.3 Tailwind和Next.js在其中的角色Tailwind CSS在T3棧里的作用經(jīng)常被低估。很多人覺(jué)得它只是個(gè)CSS框架但在t3code的語(yǔ)境下它承擔(dān)了“樣式與組件同構(gòu)”的職責(zé)。因?yàn)門ailwind的類名直接寫在JSX里組件的樣式和邏輯是綁定在一起的復(fù)制一個(gè)組件到另一個(gè)項(xiàng)目樣式不會(huì)丟。這對(duì)于快速搭建UI、保持設(shè)計(jì)一致性很有幫助。Next.js則提供了全棧的運(yùn)行時(shí)基礎(chǔ)。它的API Routes或Server Actions可以承載tRPC的handler它的文件路由系統(tǒng)讓頁(yè)面組織變得直觀它的SSR/SSG能力讓首屏性能有保障。更重要的是Next.js的app目錄模式支持React Server Components這意味著部分?jǐn)?shù)據(jù)獲取可以放在服務(wù)端完成減少客戶端的請(qǐng)求瀑布。T3棧和Next.js的結(jié)合本質(zhì)上是在“類型安全”之外再疊加一層“渲染性能”的優(yōu)化。3. 一個(gè)標(biāo)準(zhǔn)t3code項(xiàng)目的目錄骨架長(zhǎng)什么樣3.1 頂層目錄的劃分邏輯我見(jiàn)過(guò)不少T3項(xiàng)目目錄結(jié)構(gòu)五花八門但跑得順的項(xiàng)目往往遵循一些共同的約定。下面這個(gè)結(jié)構(gòu)是我自己反復(fù)調(diào)整后覺(jué)得比較順手的版本├── prisma/ │ ├── schema.prisma │ └── migrations/ ├── src/ │ ├── app/ │ │ ├── (auth)/ │ │ ├── (main)/ │ │ └── api/ │ ├── components/ │ │ ├── ui/ │ │ └── features/ │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ │ │ │ ├── root.ts │ │ │ └── trpc.ts │ │ ├── auth/ │ │ └── db/ │ ├── lib/ │ ├── styles/ │ └── types/ ├── public/ ├── .env ├── next.config.js ├── tailwind.config.ts └── tsconfig.json這個(gè)結(jié)構(gòu)的核心思路是按職責(zé)分層而不是按文件類型分層。src/server下面集中放所有服務(wù)端代碼包括tRPC路由、認(rèn)證邏輯、數(shù)據(jù)庫(kù)客戶端。src/app是Next.js的頁(yè)面和API入口。src/components放React組件其中ui放通用基礎(chǔ)組件features放業(yè)務(wù)組件。src/lib放工具函數(shù)和共享邏輯。為什么要把server和app分開(kāi)因?yàn)镹ext.js的app目錄里既有服務(wù)端代碼也有客戶端代碼邊界容易模糊。把tRPC路由和數(shù)據(jù)庫(kù)邏輯單獨(dú)抽到server目錄能強(qiáng)制形成一道心理邊界這里的代碼只在服務(wù)端運(yùn)行不要在前端組件里直接import。3.2 tRPC路由的嵌套與合并tRPC的路由組織是t3code里最需要花心思的部分。一個(gè)常見(jiàn)的做法是每個(gè)業(yè)務(wù)領(lǐng)域一個(gè)router文件然后在root.ts里合并。// src/server/api/routers/user.ts import { z } from zod; import { createTRPCRouter, protectedProcedure } from ../trpc; export const userRouter createTRPCRouter({ getById: protectedProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx, input }) { return ctx.db.user.findUnique({ where: { id: input.id } }); }), updateProfile: protectedProcedure .input(z.object({ name: z.string().min(1) })) .mutation(async ({ ctx, input }) { return ctx.db.user.update({ where: { id: ctx.session.user.id }, data: { name: input.name }, }); }), });然后在root.ts里合并// src/server/api/root.ts import { createTRPCRouter } from ./trpc; import { userRouter } from ./routers/user; import { postRouter } from ./routers/post; export const appRouter createTRPCRouter({ user: userRouter, post: postRouter, }); export type AppRouter typeof appRouter;這里的關(guān)鍵點(diǎn)是AppRouter類型的導(dǎo)出。前端通過(guò)import type { AppRouter } from ~/server/api/root拿到這個(gè)類型tRPC的client就能自動(dòng)推導(dǎo)出所有路由的輸入輸出類型。這個(gè)類型導(dǎo)入是純類型導(dǎo)入不會(huì)把服務(wù)端代碼打包進(jìn)客戶端。3.3 組件目錄的拆分策略components目錄的拆分我踩過(guò)坑。一開(kāi)始我把所有組件都放在一個(gè)components文件夾里結(jié)果很快就亂了。后來(lái)改成兩層ui放無(wú)業(yè)務(wù)邏輯的通用組件比如Button、Input、Modal、Cardfeatures放帶業(yè)務(wù)邏輯的組件比如UserProfile、PostList、CommentForm。這樣拆的好處是ui組件可以跨項(xiàng)目復(fù)用它們只依賴props不依賴tRPC或數(shù)據(jù)庫(kù)。features組件可以自由調(diào)用tRPC hooks因?yàn)樗鼈儽緛?lái)就是業(yè)務(wù)的一部分。當(dāng)你想把某個(gè)功能模塊抽成獨(dú)立包時(shí)features下的目錄可以直接搬走依賴關(guān)系清晰。還有一個(gè)細(xì)節(jié)features下的組件盡量按業(yè)務(wù)領(lǐng)域建子目錄比如features/user/、features/post/。每個(gè)子目錄里可以放組件、hooks、工具函數(shù)形成一個(gè)自包含的模塊。這樣當(dāng)業(yè)務(wù)增長(zhǎng)時(shí)你不會(huì)在一個(gè)巨大的components文件夾里大海撈針。4. 環(huán)境搭建與核心配置從零跑通第一個(gè)t3code項(xiàng)目4.1 初始化項(xiàng)目時(shí)最容易忽略的三個(gè)配置現(xiàn)在社區(qū)里有現(xiàn)成的腳手架工具可以一鍵生成T3項(xiàng)目但自動(dòng)生成的東西往往讓人知其然不知其所以然。我建議至少手動(dòng)過(guò)一遍關(guān)鍵配置這樣出了問(wèn)題才知道去哪里找。第一個(gè)容易忽略的是tsconfig.json里的路徑別名。T3項(xiàng)目通常用~或指向src目錄這樣import路徑不會(huì)出現(xiàn)../../..這種反人類寫法。配置大概長(zhǎng)這樣{ compilerOptions: { baseUrl: ., paths: { ~/*: [./src/*] } } }配完之后import { Button } from ~/components/ui/button就能正常解析。但要注意Next.js的app目錄和src目錄的關(guān)系需要確認(rèn)清楚如果app在src下面路徑別名要相應(yīng)調(diào)整。第二個(gè)是環(huán)境變量的類型聲明。T3項(xiàng)目通常用t3-oss/env-nextjs這個(gè)包來(lái)管理環(huán)境變量它能在構(gòu)建時(shí)校驗(yàn)變量是否存在、格式是否正確。配置在src/env.js里import { createEnv } from t3-oss/env-nextjs; import { z } from zod; export const env createEnv({ server: { DATABASE_URL: z.string().url(), NEXTAUTH_SECRET: z.string().min(1), }, client: { NEXT_PUBLIC_APP_URL: z.string().url(), }, runtimeEnv: { DATABASE_URL: process.env.DATABASE_URL, NEXTAUTH_SECRET: process.env.NEXTAUTH_SECRET, NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL, }, });這樣做的好處是如果忘了配某個(gè)環(huán)境變量項(xiàng)目啟動(dòng)時(shí)會(huì)直接報(bào)錯(cuò)而不是等到運(yùn)行時(shí)才出現(xiàn)莫名其妙的undefined。第三個(gè)是Prisma的客戶端單例模式。在開(kāi)發(fā)環(huán)境下Next.js的熱重載會(huì)反復(fù)執(zhí)行模塊代碼如果每次都new PrismaClient()數(shù)據(jù)庫(kù)連接數(shù)會(huì)迅速耗盡。標(biāo)準(zhǔn)做法是在src/server/db.ts里做全局單例import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma: PrismaClient | undefined; }; export const db globalForPrisma.prisma ?? new PrismaClient({ log: process.env.NODE_ENV development ? [query, error, warn] : [error], }); if (process.env.NODE_ENV ! production) globalForPrisma.prisma db;這個(gè)模式在Prisma官方文檔里有詳細(xì)說(shuō)明但很多新手會(huì)忽略導(dǎo)致開(kāi)發(fā)時(shí)數(shù)據(jù)庫(kù)連接報(bào)錯(cuò)。4.2 tRPC上下文與認(rèn)證的銜接方式tRPC的context是連接認(rèn)證系統(tǒng)和數(shù)據(jù)庫(kù)的橋梁。在src/server/api/trpc.ts里你需要定義createTRPCContext函數(shù)它接收每個(gè)請(qǐng)求的原始信息返回一個(gè)包含db和session的對(duì)象。import { initTRPC, TRPCError } from trpc/server; import { type Session } from next-auth; import { db } from ../db; interface CreateContextOptions { session: Session | null; } export const createTRPCContext async (opts: CreateContextOptions) { return { db, session: opts.session, }; }; const t initTRPC.contexttypeof createTRPCContext().create(); export const createTRPCRouter t.router; export const publicProcedure t.procedure; 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 }, }, }); });這里的關(guān)鍵設(shè)計(jì)是protectedProcedure。它通過(guò)中間件檢查session是否存在如果不存在就拋UNAUTHORIZED錯(cuò)誤。所有需要登錄的接口都用protectedProcedure定義這樣認(rèn)證邏輯只寫一次所有路由自動(dòng)繼承。認(rèn)證系統(tǒng)本身通常用NextAuth現(xiàn)在叫Auth.js它和tRPC的集成點(diǎn)在于NextAuth負(fù)責(zé)處理登錄流程和session管理tRPC的context從NextAuth的getServerSession里拿session。兩者通過(guò)createTRPCContext的調(diào)用處銜接通常在Next.js的API handler里完成。4.3 數(shù)據(jù)庫(kù)schema設(shè)計(jì)中的類型推導(dǎo)技巧Prisma schema是類型鏈路的起點(diǎn)。你在schema里定義的每個(gè)modelPrisma都會(huì)生成對(duì)應(yīng)的TypeScript類型。這些類型會(huì)通過(guò)tRPC的返回類型自動(dòng)流向客戶端。model Post { id String id default(cuid()) title String content String? published Boolean default(false) authorId String author User relation(fields: [authorId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt }這個(gè)Postmodel會(huì)生成Post類型包含所有字段。當(dāng)你在tRPC的postRouter里返回一個(gè)Post對(duì)象時(shí)前端拿到的data類型就是Post。如果你在schema里加了一個(gè)字段Prisma重新生成后前端所有用到這個(gè)類型的地方都會(huì)自動(dòng)更新。有一個(gè)技巧值得分享用Prisma的select和include來(lái)精確控制返回類型。比如你不想把用戶的密碼哈希返回給前端可以在查詢時(shí)用select排除掉。這樣生成的類型里就不會(huì)包含敏感字段前端也無(wú)法訪問(wèn)。const user await ctx.db.user.findUnique({ where: { id: input.id }, select: { id: true, name: true, email: true, image: true }, });這樣返回的類型就是{ id: string; name: string | null; email: string; image: string | null }不包含passwordHash。類型安全在這里不僅是防錯(cuò)也是防泄露。5. 實(shí)際開(kāi)發(fā)中那些文檔不會(huì)告訴你的坑5.1 類型推導(dǎo)在復(fù)雜嵌套路由下的性能問(wèn)題tRPC的類型推導(dǎo)很強(qiáng)大但當(dāng)路由數(shù)量增長(zhǎng)到幾十個(gè)、每個(gè)路由的輸入輸出類型都很復(fù)雜時(shí)TypeScript的類型檢查速度會(huì)明顯下降。我遇到過(guò)一次項(xiàng)目里有大概四十多個(gè)procedure編輯器里每次保存文件都要等三四秒才能出類型提示。后來(lái)排查發(fā)現(xiàn)問(wèn)題出在AppRouter類型的遞歸推導(dǎo)上。解決辦法有兩個(gè)。一是拆分router把不相關(guān)的業(yè)務(wù)路由分到不同的子router里減少單個(gè)router的復(fù)雜度。二是避免在procedure的返回類型里使用過(guò)深的嵌套對(duì)象如果某個(gè)接口返回的數(shù)據(jù)結(jié)構(gòu)特別復(fù)雜考慮用zod定義明確的輸出schema而不是讓TypeScript去推導(dǎo)。還有一個(gè)相關(guān)的坑在monorepo里如果前端和后端在不同的package里AppRouter類型的導(dǎo)入路徑會(huì)變得很長(zhǎng)TypeScript需要跨package解析類型。這種情況下建議在共享package里放一個(gè)types.ts只導(dǎo)出AppRouter類型前端從那里導(dǎo)入減少解析開(kāi)銷。5.2 客戶端組件與服務(wù)端組件的邊界混淆Next.js的app目錄引入了React Server Components的概念這給t3code項(xiàng)目帶來(lái)了新的復(fù)雜度。默認(rèn)情況下app目錄下的組件是Server Component它們不能使用useState、useEffect也不能調(diào)用tRPC的useQueryhook。如果你不小心在Server Component里寫了客戶端代碼會(huì)看到一堆莫名其妙的報(bào)錯(cuò)。我的經(jīng)驗(yàn)是在文件頂部明確標(biāo)注use client并且盡量把客戶端組件推到葉子節(jié)點(diǎn)。比如一個(gè)頁(yè)面整體是Server Component負(fù)責(zé)數(shù)據(jù)預(yù)取和布局只有需要交互的部分比如一個(gè)點(diǎn)贊按鈕、一個(gè)表單才抽成Client Component。這樣既能享受Server Component的性能優(yōu)勢(shì)又能保留交互能力。tRPC在Server Component里的用法和Client Component不同。Server Component里不能直接用trpc.xxx.useQuery()而是要用createCaller或者api.xxx()的方式直接調(diào)用服務(wù)端函數(shù)。這個(gè)切換點(diǎn)容易搞混建議在項(xiàng)目初期就定好規(guī)范哪些頁(yè)面用Server Component哪些用Client ComponenttRPC的調(diào)用方式分別是什么。5.3 數(shù)據(jù)庫(kù)遷移與類型同步的時(shí)序問(wèn)題Prisma的遷移流程是改schema → 跑prisma migrate dev→ 生成新客戶端 → TypeScript類型更新。這個(gè)鏈條里有一個(gè)時(shí)序問(wèn)題如果你改了schema但忘了跑遷移或者遷移失敗了但客戶端已經(jīng)生成類型和數(shù)據(jù)庫(kù)實(shí)際結(jié)構(gòu)就會(huì)不一致。我踩過(guò)一次坑在schema里加了一個(gè)可選字段跑遷移時(shí)因?yàn)閿?shù)據(jù)庫(kù)里有臟數(shù)據(jù)導(dǎo)致遷移失敗但Prisma客戶端已經(jīng)生成了包含新字段的類型。結(jié)果代碼里訪問(wèn)這個(gè)字段時(shí)類型檢查通過(guò)運(yùn)行時(shí)卻報(bào)錯(cuò)說(shuō)列不存在。排查了半天才發(fā)現(xiàn)是遷移沒(méi)成功。避免這個(gè)問(wèn)題的辦法是每次改schema后先確認(rèn)遷移成功再重新生成客戶端?？梢栽趐ackage.json里加一個(gè)腳本把遷移和生成綁在一起{ scripts: { db:migrate: prisma migrate dev prisma generate } }另外在CI流程里要加一步檢查確保遷移文件和schema是同步的。Prisma提供了prisma migrate diff命令可以對(duì)比schema和數(shù)據(jù)庫(kù)的實(shí)際差異適合在CI里做校驗(yàn)。5.4 生產(chǎn)環(huán)境構(gòu)建時(shí)的類型檢查策略Next.js的next build默認(rèn)會(huì)跑TypeScript類型檢查。在t3code項(xiàng)目里這個(gè)檢查可能會(huì)很慢因?yàn)閠RPC的類型推導(dǎo)本身就耗時(shí)。如果每次構(gòu)建都全量檢查CI時(shí)間會(huì)拉得很長(zhǎng)。我的做法是在本地開(kāi)發(fā)時(shí)用tsc --noEmit --watch做增量檢查在CI里用next build做全量檢查但把類型檢查單獨(dú)抽成一個(gè)job。這樣構(gòu)建和類型檢查可以并行節(jié)省時(shí)間。另外可以在next.config.js里配置typescript.ignoreBuildErrors為false默認(rèn)就是false確保構(gòu)建時(shí)不會(huì)跳過(guò)類型錯(cuò)誤。還有一個(gè)細(xì)節(jié)如果項(xiàng)目里用了zod做輸入校驗(yàn)確保zod的版本在前后端一致。我曾經(jīng)遇到過(guò)前端用zod 3.21、后端用zod 3.22導(dǎo)致某些校驗(yàn)行為不一致類型推導(dǎo)也出現(xiàn)了偏差。把zod固定在同一個(gè)版本能避免這類問(wèn)題。6. 從能跑到好用t3code項(xiàng)目的優(yōu)化與擴(kuò)展思路6.1 用中間件統(tǒng)一處理日志和錯(cuò)誤tRPC的中間件機(jī)制很適合做橫切關(guān)注點(diǎn)。除了認(rèn)證還可以加日志中間件、錯(cuò)誤上報(bào)中間件、性能計(jì)時(shí)中間件。比如一個(gè)簡(jiǎn)單的日志中間件const loggerMiddleware t.middleware(async ({ path, type, next }) { const start Date.now(); const result await next(); const duration Date.now() - start; console.log([trpc] ${type} ${path} - ${duration}ms); return result; }); export const loggedProcedure t.procedure.use(loggerMiddleware);然后在需要的地方用loggedProcedure替代publicProcedure。這樣每個(gè)請(qǐng)求的耗時(shí)和路徑都會(huì)被記錄排查性能問(wèn)題時(shí)很有用。錯(cuò)誤處理也可以用中間件統(tǒng)一格式化。tRPC拋出的TRPCError會(huì)帶著錯(cuò)誤碼和消息傳到前端前端可以用error.message展示用戶友好的提示。但要注意不要把服務(wù)端的堆棧信息暴露給前端中間件里可以做一層過(guò)濾。6.2 共享邏輯的抽離與復(fù)用模式t3code項(xiàng)目里有些邏輯是前后端都要用的比如數(shù)據(jù)校驗(yàn)規(guī)則、常量定義、工具函數(shù)。這些代碼應(yīng)該放在src/lib或一個(gè)獨(dú)立的packages/shared里前后端都從這里導(dǎo)入。一個(gè)典型的例子是zod schema。后端用zod校驗(yàn)輸入前端也可以用同一個(gè)schema做表單校驗(yàn)。這樣校驗(yàn)規(guī)則只寫一次前后端行為一致。// src/lib/validators/post.ts import { z } from zod; export const createPostSchema z.object({ title: z.string().min(1).max(100), content: z.string().max(5000).optional(), }); export type CreatePostInput z.infertypeof createPostSchema;后端在tRPC procedure里用createPostSchema做input校驗(yàn)前端在表單提交前用同一個(gè)schema做校驗(yàn)。類型CreatePostInput也可以前后端共用。這種復(fù)用模式能顯著減少重復(fù)代碼和不一致問(wèn)題。6.3 性能監(jiān)控與類型安全的平衡類型安全不是免費(fèi)的它需要TypeScript在編譯時(shí)做大量推導(dǎo)。在大型項(xiàng)目里這個(gè)開(kāi)銷會(huì)體現(xiàn)在構(gòu)建時(shí)間和編輯器響應(yīng)速度上。我的經(jīng)驗(yàn)是在核心業(yè)務(wù)路徑上保持嚴(yán)格的類型安全在邊緣邏輯上適當(dāng)放寬。比如對(duì)于數(shù)據(jù)庫(kù)查詢和API接口堅(jiān)持用Prisma和tRPC的完整類型推導(dǎo)。但對(duì)于一些純展示組件、工具函數(shù)可以用更寬松的類型甚至用any做臨時(shí)過(guò)渡但要加注釋說(shuō)明原因。關(guān)鍵是找到一個(gè)平衡點(diǎn)既不讓類型系統(tǒng)拖慢開(kāi)發(fā)速度也不讓類型漏洞導(dǎo)致運(yùn)行時(shí)錯(cuò)誤。另外可以用tsc --diagnostics查看類型檢查的耗時(shí)分布找出最耗時(shí)的文件或模塊針對(duì)性優(yōu)化。常見(jiàn)的手段包括減少泛型嵌套、避免循環(huán)引用、拆分大型類型定義。6.4 團(tuán)隊(duì)協(xié)作中的代碼規(guī)范約定t3code項(xiàng)目在團(tuán)隊(duì)協(xié)作時(shí)最大的挑戰(zhàn)不是技術(shù)本身而是約定的一致性。如果每個(gè)人對(duì)目錄結(jié)構(gòu)、命名方式、路由劃分的理解不同項(xiàng)目很快就會(huì)變得難以維護(hù)。我建議在項(xiàng)目初期就定好這幾條規(guī)范tRPC路由按業(yè)務(wù)領(lǐng)域劃分每個(gè)router文件不超過(guò)200行組件按ui和features分層features下按業(yè)務(wù)建子目錄所有數(shù)據(jù)庫(kù)操作必須通過(guò)ctx.db不允許在組件里直接import Prisma客戶端環(huán)境變量必須通過(guò)env.js訪問(wèn)不允許直接讀process.env。這些規(guī)范看起來(lái)瑣碎但能避免很多后期重構(gòu)的痛苦。可以用ESLint的no-restricted-imports規(guī)則來(lái)強(qiáng)制某些約定比如禁止從prisma/client直接導(dǎo)入到src/app目錄。工具能做的事就不要靠人的自覺(jué)。7. 關(guān)于t3code的一些個(gè)人體會(huì)我在幾個(gè)中小型項(xiàng)目里用過(guò)T3棧最大的感受是它把“類型安全”從一個(gè)口號(hào)變成了日常開(kāi)發(fā)中能感知到的便利。以前改一個(gè)字段名要全局搜索替換現(xiàn)在編輯器直接標(biāo)紅以前前后端聯(lián)調(diào)要對(duì)著文檔對(duì)參數(shù)現(xiàn)在類型提示直接告訴你該傳什么。這種體驗(yàn)上的提升用久了就回不去了。但它也不是銀彈。tRPC的生態(tài)相對(duì)年輕遇到一些邊緣場(chǎng)景時(shí)文檔和社區(qū)答案不如REST那么豐富。Next.js的版本迭代很快app目錄和pages目錄的混用有時(shí)會(huì)讓人困惑。Prisma在某些復(fù)雜查詢場(chǎng)景下生成的SQL不夠優(yōu)化需要手動(dòng)調(diào)優(yōu)。這些問(wèn)題都需要在實(shí)際項(xiàng)目中慢慢積累經(jīng)驗(yàn)。如果你打算開(kāi)始一個(gè)T3項(xiàng)目我的建議是先用腳手架跑通一個(gè)最小可用的demo然后花時(shí)間理解每個(gè)配置項(xiàng)的作用再逐步替換成自己的業(yè)務(wù)邏輯。不要一上來(lái)就追求完美的目錄結(jié)構(gòu)先讓項(xiàng)目跑起來(lái)然后在迭代中調(diào)整。類型安全的價(jià)值在于長(zhǎng)期維護(hù)而不是一開(kāi)始就完美無(wú)缺。最后分享一個(gè)小技巧在package.json里加一個(gè)typecheck腳本用tsc --noEmit做全量類型檢查然后在提交代碼前跑一遍。這個(gè)習(xí)慣能幫你提前發(fā)現(xiàn)很多類型問(wèn)題避免把錯(cuò)誤帶到CI階段。配合編輯器的實(shí)時(shí)提示基本上能做到“寫的時(shí)候就知道對(duì)不對(duì)”。