戰(zhàn)：tRPC+Prisma+Next.js開(kāi)發(fā)指南)
1. 項(xiàng)目緣起與整體設(shè)計(jì)思路1.1 t3code是什么一個(gè)圍繞T3 Stack落地的全棧類型安全項(xiàng)目t3code這個(gè)名字第一眼容易讓人疑惑——T3指的是什么code肯定離不開(kāi)寫(xiě)代碼但T3到底是什么這里我得先把背景交代清楚。T3 Stack是一套由TypeScript、Next.js、tRPC、Tailwind CSS、Prisma以及可選的NextAuth.js組合而成的全棧Web開(kāi)發(fā)技術(shù)棧。它的核心理念就是讓“類型安全”貫穿整個(gè)開(kāi)發(fā)鏈路從數(shù)據(jù)庫(kù)的數(shù)據(jù)模型到后端API的輸入輸出再到前端頁(yè)面的數(shù)據(jù)消費(fèi)所有類型都是同一個(gè)源頭由TypeScript編譯器幫你兜底。我最初接觸T3 Stack是因?yàn)橐粋€(gè)實(shí)際痛點(diǎn)傳統(tǒng)的前后端分離項(xiàng)目里后端REST接口寫(xiě)好了前端要重新定義一遍TypeScript接口參數(shù)結(jié)構(gòu)稍微變一下前端經(jīng)常要翻半天才知道哪里壞了。更離譜的是接口文檔和代碼脫節(jié)后端改了字段忘記同步文檔前端收到一個(gè)不符合預(yù)期的響應(yīng)只能打開(kāi)瀏覽器控制臺(tái)一個(gè)一個(gè)對(duì)字段。t3code這個(gè)項(xiàng)目本質(zhì)上是我把T3 Stack完整跑通一遍后沉淀下來(lái)的經(jīng)驗(yàn)總結(jié)從數(shù)據(jù)庫(kù)模型設(shè)計(jì)、API層搭建、前端頁(yè)面渲染到部署時(shí)的常見(jiàn)坑全部走了一遍。它解決的核心問(wèn)題就是“前后端類型割裂”以及由此帶來(lái)的聯(lián)調(diào)效率低下。這個(gè)內(nèi)容適合誰(shuí)來(lái)參考一種是剛接觸全棧開(kāi)發(fā)、想找一個(gè)現(xiàn)代實(shí)踐方案的中級(jí)開(kāi)發(fā)者另一種是已經(jīng)用REST模式寫(xiě)了好幾年想看看tRPC這條路到底靠不靠譜的人。我可以先給你一個(gè)結(jié)論如果你只做短平快的內(nèi)部工具或者獨(dú)立開(kāi)發(fā)一個(gè)中小型產(chǎn)品T3 Stack這套組合能幫你把CRUD開(kāi)發(fā)時(shí)間壓縮一半以上而且類型錯(cuò)誤在編譯期就被攔住不再是運(yùn)行時(shí)的黑色報(bào)錯(cuò)。1.2 為什么選T3這套組合而不是自己拼一套技術(shù)棧很多人第一個(gè)問(wèn)題就是Next.js、Prisma、tRPC我都聽(tīng)過(guò)但為什么要綁在一起我自己拼一套不行嗎當(dāng)然可以但你自己拼面臨的是版本兼容、上下文傳遞、類型定義手工維護(hù)這一大堆瑣碎問(wèn)題。T3 Stack默認(rèn)把這套集成方案已經(jīng)內(nèi)置好了。它不是一個(gè)像Laravel那樣的大一統(tǒng)框架而是一套約定告訴你每個(gè)工具負(fù)責(zé)什么環(huán)節(jié)、數(shù)據(jù)流怎么走。具體拆開(kāi)看Next.js負(fù)責(zé)前端頁(yè)面渲染、路由以及前后端代碼放在同一個(gè)倉(cāng)庫(kù)里跑的便利性。你可以在app目錄里寫(xiě)頁(yè)面組件也可以在src/server/api里寫(xiě)后端邏輯。Prisma管數(shù)據(jù)庫(kù)訪問(wèn)層它的schema.prisma文件是數(shù)據(jù)模型的唯一真相源。你改了這個(gè)文件運(yùn)行遷移命令之后TypeScript類型會(huì)自動(dòng)更新。tRPC是T3 Stack的靈魂。它讓你在Next.js的API層定義一個(gè)個(gè)procedure前端直接像調(diào)用本地函數(shù)一樣調(diào)用這些procedure不需要REST路徑、不需要手寫(xiě)請(qǐng)求封裝、不需要手寫(xiě)響應(yīng)類型。Tailwind CSS負(fù)責(zé)樣式它不參與數(shù)據(jù)流但它的原子類設(shè)計(jì)讓UI層不需要額外維護(hù)組件樣式文件開(kāi)發(fā)速度提升很明顯。NextAuth.js現(xiàn)在叫Auth.js負(fù)責(zé)認(rèn)證它把登錄會(huì)話和tRPC的context打通了你做“只能看到自己數(shù)據(jù)”這類功能時(shí)會(huì)省很多事。這套組合的核心邏輯是“少即是多”。T3 Stack的設(shè)計(jì)哲學(xué)決定了它只保留你真正需要的東西你能用TypeScript解決的事情絕不引入額外的運(yùn)行時(shí)依賴。舉個(gè)例子tRPC的輸入校驗(yàn)在開(kāi)發(fā)模式走zod驗(yàn)證在類型層面你不需要手動(dòng)聲明請(qǐng)求參數(shù)的類型zod schema本身就是類型這也是t3code這個(gè)項(xiàng)目名字里“code”部分的意義——代碼即契約類型即文檔。2. t3code的核心架構(gòu)與關(guān)鍵技術(shù)拆解2.1 端到端類型共享的完整數(shù)據(jù)鏈路t3code項(xiàng)目里最值得琢磨的一條線是類型從數(shù)據(jù)庫(kù)一路流到前端組件的完整鏈路。這不像傳統(tǒng)的REST API那樣前端拿到響應(yīng)后還要定義一個(gè)interface去聲明“這個(gè)響應(yīng)長(zhǎng)什么樣”。在T3 Stack里類型源頭只有一個(gè)Prisma Schema。我建議在動(dòng)手前先記住這條鏈路schema.prisma數(shù)據(jù)庫(kù)模型 ↓ 類型生成 Prisma ClientNode層訪問(wèn)數(shù)據(jù)庫(kù) ↓ 傳給 tRPC procedure輸入用zod校驗(yàn)輸出依賴Prisma類型 ↓ 類型推斷 react-query hooks前端調(diào)用tRPC的useQuery ↓ 類型傳遞 React組件里的props/state如果鏈路中間任何一環(huán)修改了數(shù)據(jù)類型TypeScript編譯器會(huì)立刻告訴你哪個(gè)組件在傳參時(shí)出了錯(cuò)。比如數(shù)據(jù)庫(kù)里把用戶名字段從name改成了username你在Prisma模型里改完運(yùn)行npx prisma generate然后編譯項(xiàng)目所有用到name的組件全部報(bào)錯(cuò)。這種“改一處全項(xiàng)目受檢”的體驗(yàn)在傳統(tǒng)模式下需要額外配合swagger-codegen之類的代碼生成工具才能勉強(qiáng)做到而且生成的代碼版本管理還是個(gè)大麻煩。T3 Stack把這一整套流程收斂到了編譯器和IDE提示里省心非常多。在實(shí)際落地時(shí)我特別推薦一個(gè)習(xí)慣先把schema.prisma設(shè)計(jì)得足夠貼合業(yè)務(wù)然后再去寫(xiě)頁(yè)面。因?yàn)镻risma模型一旦確定后面所有的API邏輯都是圍繞這套模型展開(kāi)的。數(shù)據(jù)庫(kù)設(shè)計(jì)考慮得越周全tRPC路由寫(xiě)起來(lái)就越順。2.2 tRPC的請(qǐng)求生命周期函數(shù)調(diào)用為什么能替代REST很多人聽(tīng)到tRPC會(huì)疑惑前端直接“調(diào)用函數(shù)”網(wǎng)絡(luò)請(qǐng)求到底怎么走其實(shí)底層的HTTP傳輸并沒(méi)消失tRPC只是幫你把“生產(chǎn)請(qǐng)求、解析請(qǐng)求、封裝響應(yīng)、校驗(yàn)參數(shù)、推斷類型”這些原本手工寫(xiě)的代碼全部自動(dòng)化了。在t3code項(xiàng)目里一個(gè)標(biāo)準(zhǔn)操作是這樣的// src/server/api/routers/post.ts import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ list: publicProcedure .input( z.object({ limit: z.number().min(1).max(100).default(20), cursor: z.string().optional(), }) ) .query(async ({ ctx, input }) { const items await ctx.db.post.findMany({ take: input.limit, skip: input.cursor ? 1 : 0, cursor: input.cursor ? { id: input.cursor } : undefined, orderBy: { createdAt: desc }, }); return items; }), });前端調(diào)用時(shí)是這樣的const { data, isPending } api.post.list.useQuery({ limit: 10 });注意useQuery里面的參數(shù)類型和返回的data類型都是編譯時(shí)確定的。如果你在調(diào)用時(shí)傳了多余的字段或者少傳了必填字段IDE會(huì)直接報(bào)錯(cuò)。這種體驗(yàn)平時(shí)用REST API時(shí)根本不可能有。再拆解一下tRPC背后的生命周期它可以分為五個(gè)階段前端調(diào)用useQuery時(shí)tRPC會(huì)生成一個(gè)以procedure路徑為標(biāo)識(shí)的HTTP請(qǐng)求比如/api/trpc/post.list。Next.js的API路由收到請(qǐng)求tRPC根據(jù)路徑找到對(duì)應(yīng)router。請(qǐng)求先經(jīng)過(guò)input中的zod schema校驗(yàn)參數(shù)不合格直接返回客戶端錯(cuò)誤。在query函數(shù)內(nèi)部ctx攜帶數(shù)據(jù)庫(kù)實(shí)例和session信息供你執(zhí)行數(shù)據(jù)訪問(wèn)。響應(yīng)返回后tRPC客戶端根據(jù)路由類型推斷出返回值類型前端拿到帶有完整類型的data。有人會(huì)問(wèn)為什么不用GraphQLGraphQL也能做到類型安全但它的schema定義、resolver拆分、codegen成本比較高。tRPC更適合“服務(wù)端和客戶端同在一個(gè)代碼倉(cāng)庫(kù)”的場(chǎng)景你不需要定義一套獨(dú)立的schema語(yǔ)言TypeScript本身的類型就是schema。這也是t3code能快速落地的關(guān)鍵原因。2.3 Prisma Schema設(shè)計(jì)數(shù)據(jù)模型的真相源t3code項(xiàng)目的數(shù)據(jù)模型我建議按業(yè)務(wù)實(shí)體來(lái)劃分。舉一個(gè)實(shí)際例子一個(gè)帶評(píng)論功能的博客系統(tǒng)包含用戶User、文章Post、評(píng)論Comment三個(gè)核心實(shí)體它們之間的關(guān)聯(lián)關(guān)系用Prisma模型表示如下// prisma/schema.prisma generator client { provider prisma-client-js } datasource db { provider sqlite // 開(kāi)發(fā)環(huán)境先用SQLite生產(chǎn)切換PostgreSQL url env(DATABASE_URL) } model User { id String id default(cuid()) name String? email String unique posts Post[] comments Comment[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Post { id String id default(cuid()) title String content String published Boolean default(false) author User relation(fields: [authorId], references: [id]) authorId String comments Comment[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Comment { id String id default(cuid()) body String post Post relation(fields: [postId], references: [id]) postId String author User relation(fields: [authorId], references: [id]) authorId String createdAt DateTime default(now()) }這里我用了cuid()而不是自增整數(shù)主鍵原因有幾個(gè)公開(kāi)API中整數(shù)ID容易枚舉遍歷cuid更難猜測(cè)分布式或多人協(xié)作時(shí)不需要等待數(shù)據(jù)庫(kù)自增tRPC把ID作為字符串傳參時(shí)不會(huì)有類型不匹配問(wèn)題。設(shè)計(jì)模型時(shí)我有兩個(gè)建議其一盡早把唯一性約束寫(xiě)清楚比如email unique到了生產(chǎn)環(huán)境再補(bǔ)唯一索引遷移成本和風(fēng)險(xiǎn)都會(huì)高很多其二DateTime字段務(wù)必加上default(now())否則創(chuàng)建記錄時(shí)漏傳字段會(huì)導(dǎo)致運(yùn)行時(shí)錯(cuò)誤。模型改完后運(yùn)行npx prisma migrate dev --name init npx prisma generate第一次遷移會(huì)創(chuàng)建數(shù)據(jù)庫(kù)表并生成Prisma Client類型。之后每次修改模型重復(fù)這兩個(gè)命令即可。有一個(gè)細(xì)節(jié)建議特別注意prisma generate生成的類型文件是tRPC返回值類型推斷的依據(jù)所以改完schema后一定要重新生成否則編譯期拿到的還是舊類型。3. 實(shí)操落地從零搭建一個(gè)可運(yùn)行的t3code項(xiàng)目3.1 初始化腳手架與目錄結(jié)構(gòu)解讀T3 Stack官方維護(hù)了一個(gè)腳手架create-t3-app建議從它開(kāi)始因?yàn)閮?nèi)置了這些能力的初始配置TypeScript嚴(yán)格模式、Next.js App Router、tRPC router目錄、Prisma數(shù)據(jù)庫(kù)連接、Tailwind樣式體系。自己手搓這些配置至少需要折騰大半天而腳手架只要一個(gè)命令npx create-t3-applatest t3code項(xiàng)目初始化時(shí)交互式命令行會(huì)問(wèn)你開(kāi)啟哪些可選模塊。我的建議是首次體驗(yàn)全開(kāi)尤其是NextAuth.js和Drizzle這類的依賴先裝上再逐個(gè)理解。如果你已經(jīng)確定不用數(shù)據(jù)庫(kù)可以不勾Prisma。但t3code既然是圍繞類型安全的全棧項(xiàng)目數(shù)據(jù)庫(kù)訪問(wèn)層是必要的別省。初始化完成后標(biāo)準(zhǔn)目錄長(zhǎng)這樣prisma/ schema.prisma src/ app/ api/ trpc/ [trpc]/route.ts layout.tsx page.tsx server/ api/ routers/ post.ts root.ts db.ts auth.ts trpc/ server.ts client.ts react.tsx初次看到這些目錄的人容易慌其實(shí)關(guān)鍵就兩處src/server/api/routers/放你的tRPC業(yè)務(wù)邏輯src/trpc/放服務(wù)端和客戶端共享的類型定義與tRPC實(shí)例。啟動(dòng)開(kāi)發(fā)服務(wù)器npm run dev看到Next.js默認(rèn)頁(yè)后先別急著寫(xiě)代碼進(jìn)入src/server/db.ts確認(rèn)數(shù)據(jù)庫(kù)地址已經(jīng)正確配置。腳手架默認(rèn)讀DATABASE_URL這個(gè)環(huán)境變量如果你用SQLite.env里應(yīng)該長(zhǎng)這樣DATABASE_URLfile:./db.sqlite3.2 數(shù)據(jù)模型遷移的完整過(guò)程我以帶評(píng)論的博客功能為例先創(chuàng)建幾組tRPC路由。第一步定義文章相關(guān)路由// src/server/api/routers/post.ts import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ listPublished: publicProcedure .input( z.object({ limit: z.number().min(1).max(50).default(10), }) ) .query(async ({ ctx, input }) { return ctx.db.post.findMany({ where: { published: true }, orderBy: { createdAt: desc }, take: input.limit, include: { author: { select: { name: true } } }, }); }), getById: publicProcedure .input(z.object({ id: z.string().cuid() })) .query(async ({ ctx, input }) { return ctx.db.post.findUnique({ where: { id: input.id }, include: { comments: { include: { author: true } } }, }); }), create: protectedProcedure .input( z.object({ title: z.string().min(1).max(120), content: z.string().min(1), published: z.boolean().default(false), }) ) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, published: input.published, authorId: ctx.session.user.id, }, }); }), });第二步把路由掛到根router上// src/server/api/root.ts import { postRouter } from ./routers/post; import { createTRPCRouter } from ../trpc; export const appRouter createTRPCRouter({ post: postRouter, }); export type AppRouter typeof appRouter;注意export type AppRouter這一行它是tRPC前端類型推斷的核心。前端trpc客戶端實(shí)例就依賴這個(gè)類型來(lái)確定所有procedure的入?yún)⒑统鰠㈩愋?。只要后端router變化前端代碼的TypeScript提示立刻跟著變。第三步運(yùn)行遷移npx prisma migrate dev --name add-post-comment此時(shí)數(shù)據(jù)庫(kù)已經(jīng)生成對(duì)應(yīng)的表。你可以打開(kāi)prisma/studio看一下數(shù)據(jù)模型npx prisma studioStudio會(huì)啟動(dòng)一個(gè)本地可視化管理界面用來(lái)檢查數(shù)據(jù)是否正確寫(xiě)入排查時(shí)很好用。3.3 前端頁(yè)面調(diào)用tRPC并渲染數(shù)據(jù)前端調(diào)用邏輯放在Next.js的Server Component或者Client Component里都有。以Client Component為例use client; import { api } from ~/trpc/react; export function PostList() { const { data, isLoading, error } api.post.listPublished.useQuery({ limit: 10, }); if (isLoading) return div加載中.../div; if (error) return div請(qǐng)求失敗: {error.message}/div; return ( ul {data?.map((post) ( li key{post.id} h2{post.title}/h2 p{post.content}/p span作者: {post.author.name ?? 匿名}/span /li ))} /ul ); }我覺(jué)得這個(gè)模式最大的價(jià)值在于編輯代碼時(shí)IDE的自動(dòng)補(bǔ)全能顯示出一個(gè)數(shù)據(jù)庫(kù)查詢返回的所有字段而且字段拼錯(cuò)會(huì)直接報(bào)ts-error。你不必記住后端到底返回了什么因?yàn)殚_(kāi)發(fā)環(huán)境里整個(gè)類型鏈?zhǔn)峭该鞯摹倪@個(gè)角度看t3code項(xiàng)目的“類型安全”不是一句空話而是實(shí)際開(kāi)發(fā)中的默認(rèn)狀態(tài)。還有一個(gè)容易被忽略的地方在Server Component中如果你通過(guò)createCaller直接調(diào)用tRPC查詢可以避免額外的HTTP往返import { createCaller } from ~/trpc/server; export default async function HomePage() { const caller createCaller(); const posts await caller.post.listPublished({ limit: 5 }); return ( main PostList initialData{posts} / /main ); }createCaller從服務(wù)端直接調(diào)用procedure函數(shù)繞過(guò)了HTTP層響應(yīng)時(shí)間會(huì)更短并且仍然能得到完整的類型推斷。理解這一點(diǎn)后你就知道T3 Stack并不強(qiáng)迫你所有的數(shù)據(jù)都走網(wǎng)絡(luò)請(qǐng)求該直連的時(shí)候直連該走HTTP的時(shí)候走HTTP主動(dòng)權(quán)在你自己手里。3.4 鑒權(quán)與受保護(hù)接口的落地前面post.create用了protectedProcedure它的含義是“必須登錄才能調(diào)用”。T3 Stack默認(rèn)集成NextAuth.js現(xiàn)在叫Auth.js它會(huì)把session塞進(jìn)tRPC的context里。在src/server/api/trpc.ts里可以看到類似這樣的代碼export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { ...ctx, session: ctx.session } }); });所有掛在protectedProcedure下的接口只要用戶未登錄就會(huì)返回401錯(cuò)誤前端useQuery會(huì)捕獲到error.data.httpStatus為401。你可以據(jù)此在頁(yè)面上跳轉(zhuǎn)登錄頁(yè)。如果要做“用戶只能修改自己的文章”這類權(quán)限控制在mutation內(nèi)部判斷即可update: protectedProcedure .input(z.object({ id: z.string().cuid(), title: z.string().optional() })) .mutation(async ({ ctx, input }) { const post await ctx.db.post.findUnique({ where: { id: input.id } }); if (!post || post.authorId ! ctx.session.user.id) { throw new TRPCError({ code: FORBIDDEN }); } return ctx.db.post.update({ where: { id: input.id }, data: { title: input.title }, }); }),這類授權(quán)邏輯寫(xiě)在tRPC服務(wù)端的最明顯好處是前端無(wú)論如何繞道都不會(huì)繞過(guò)權(quán)限校驗(yàn)因?yàn)樾ｒ?yàn)發(fā)生在靠近數(shù)據(jù)源的那一層。3.5 服務(wù)端渲染時(shí)如何避免類型與數(shù)據(jù)不同步在Server Component里直接調(diào)用createCaller有一個(gè)細(xì)節(jié)要注意如果procedure內(nèi)部使用了ctx.headers比如做多語(yǔ)言判斷Server Component環(huán)境里可能拿不到完全一致的header信息。腳手架給了一個(gè)headers注入的方式createCaller默認(rèn)會(huì)從Next的headers()里讀取。我在實(shí)際使用中遇到過(guò)開(kāi)發(fā)模式一切正常、部署后偶發(fā)跨域讀取異常的問(wèn)題主要原因是不知道為什么在某個(gè)中間層請(qǐng)求頭被改寫(xiě)。排查思路是先在src/server/api/trpc.ts里加一個(gè)臨時(shí)的header打印然后分別對(duì)比瀏覽器直連和Server Component內(nèi)部調(diào)用的結(jié)果。如果發(fā)現(xiàn)差異就改為顯式傳入關(guān)鍵header字段const caller createCaller({ headers: { x-user-locale: zh-CN } });這種顯式傳參方式能避免依賴隱式上下文排查起來(lái)也更清晰。4. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄4.1 類型報(bào)錯(cuò)集中在哪幾個(gè)坑t3code這類T3項(xiàng)目最常見(jiàn)的編譯錯(cuò)誤我總結(jié)下來(lái)有四個(gè)來(lái)源Prisma類型未重新生成。改了schema.prisma后沒(méi)有運(yùn)行npx prisma generate結(jié)果前端引用的字段在舊類型上不存在。解決辦法就是先跑generate大多數(shù)情況下編譯錯(cuò)誤會(huì)消失。zod schema與Prisma類型不一致。比如input里聲明了一個(gè)必填字符串但Prisma模型里字段允許為null。這種情況多發(fā)生在“手寫(xiě)schema時(shí)想得不夠周全”。我的建議是輸入校驗(yàn)嚴(yán)格一點(diǎn)內(nèi)部處理靈活一點(diǎn)。你不想讓前端傳null就在zod里直接拒絕null。ctx.db類型為null或undefined。在初始化腳手架時(shí)createTRPCContext里面的db可能因?yàn)榄h(huán)境變量沒(méi)配好而變成undefined導(dǎo)致后續(xù)所有使用ctx.db的地方報(bào)錯(cuò)。檢查一下.env里的DATABASE_URL是否正確。在Server Component中錯(cuò)誤引用客戶端tRPC實(shí)例。比如在app/page.tsx這種Server Component里使用了~/trpc/react這是客戶端專用模塊應(yīng)該改用~/trpc/server的createCaller。否則會(huì)報(bào)“組件無(wú)法在Server Component中使用客戶端hook”之類的錯(cuò)誤。4.2 tRPC請(qǐng)求404、無(wú)法訪問(wèn)服務(wù)器返回問(wèn)題如果你看到瀏覽器請(qǐng)求/api/trpc/post.list返回404而不是正常的JSON響應(yīng)通常是Next.js的API路由沒(méi)有正確掛載。檢查src/app/api/trpc/[trpc]/route.ts文件是否存在并且內(nèi)容是否導(dǎo)出了GET和POST兩個(gè)handler。還有一個(gè)容易被忽略的情況如果你在Next.js中間件middleware里做了路徑攔截比如未登錄時(shí)重定向到登錄頁(yè)可能會(huì)把/api/trpc的請(qǐng)求也攔截掉導(dǎo)致所有tRPC請(qǐng)求404或302。我給中間件加一個(gè)白名單export const config { matcher: [/((?!api/trpc|_next/static|_next/image|favicon.ico).*)], };這個(gè)方法能放行API路徑又不影響頁(yè)面級(jí)鑒權(quán)。4.3 Prisma遷移沖突與數(shù)據(jù)庫(kù)狀態(tài)不一致開(kāi)發(fā)過(guò)程中經(jīng)常要反復(fù)修改模型如果上一次遷移還沒(méi)應(yīng)用到某個(gè)環(huán)境再跑新遷移時(shí)可能報(bào)P3005之類的錯(cuò)誤。不用慌先把本地的遷移回滾到一致?tīng)顟B(tài)。操作方式npx prisma migrate reset它會(huì)清空數(shù)據(jù)庫(kù)重新應(yīng)用所有遷移文件。這個(gè)命令只適合開(kāi)發(fā)環(huán)境生產(chǎn)庫(kù)千萬(wàn)不要用。如果你在團(tuán)隊(duì)協(xié)作中遇到遷移分支沖突建議約定每個(gè)人都基于最新的main分支拉代碼跑完遷移再改模型減少遷移文件沖突的概率。4.4 tRPC在SSR模式下的性能與緩存問(wèn)題在Server Component里使用createCaller每次渲染頁(yè)面都可能執(zhí)行數(shù)據(jù)庫(kù)查詢。如果某個(gè)查詢非常重頁(yè)面響應(yīng)會(huì)變慢。我自己給t3code加了一層簡(jiǎn)單的緩存針對(duì)不常變更的列表在router內(nèi)做數(shù)據(jù)緩存。其實(shí)Next.js本身提供了unstable_cache可以包住caller.xxx這個(gè)執(zhí)行過(guò)程但要注意緩存鍵必須和入?yún)⒈３忠恢滦浴２贿^(guò)要提醒一點(diǎn)不要把ctx整個(gè)對(duì)象緩存下來(lái)它包含session等請(qǐng)求級(jí)信息。像下面這種做法就比較容易踩坑。// 錯(cuò)誤示范緩存了包含請(qǐng)求級(jí)信息的ctx const cached await unstable_cache( () caller.post.listPublished(input), // 緩存條件里沒(méi)有考慮用戶權(quán)限危險(xiǎn) )();更穩(wěn)妥的做法是在procedure函數(shù)的實(shí)現(xiàn)內(nèi)部做細(xì)粒度緩存或者用react-query的staleTime控制客戶端緩存。對(duì)于剛上手T3 Stack的人來(lái)說(shuō)先別過(guò)度設(shè)計(jì)緩存保持默認(rèn)行為等確實(shí)有性能瓶頸再優(yōu)化。4.5 排查思路速查表現(xiàn)象首要排查點(diǎn)推薦命令/操作前端調(diào)用后報(bào)404Next.js API路由是否掛載檢查src/app/api/trpc/[trpc]/route.ts編譯報(bào)類型缺失Prisma類型未更新npx prisma generate查詢字段為undefined前端字段名與Prisma返回不一致在IDE中懸浮查看返回類型401錯(cuò)誤使用了protectedProcedure但未登錄在調(diào)用前確保session.user存在Server Component里用不了hook誤用了客戶端tRPC實(shí)例改用~/trpc/server的createCaller數(shù)據(jù)庫(kù)遷移失敗遷移歷史沖突開(kāi)發(fā)環(huán)境用migrate reset數(shù)據(jù)查詢慢N1查詢或缺少索引使用Prisma的include優(yōu)化關(guān)聯(lián)查詢我建議把這些常見(jiàn)問(wèn)題存在本地筆記里每次新項(xiàng)目遇到相同報(bào)錯(cuò)直接翻表格對(duì)照能節(jié)省很多時(shí)間。5. 后續(xù)擴(kuò)展思路與我的個(gè)人體會(huì)t3code這個(gè)項(xiàng)目其實(shí)可以在很多方向繼續(xù)擴(kuò)展。最直接的一步是接入文件上傳用tRPC定義一個(gè)mutation接收文件元數(shù)據(jù)然后把文件存到對(duì)象存儲(chǔ)或者本地目錄數(shù)據(jù)庫(kù)里只保存訪問(wèn)路徑。前端可以用react-dropzone之類的組件配合調(diào)用整個(gè)過(guò)程仍然能保持類型安全。另一個(gè)方向是加入訂閱推送tRPC的subscription能力配合Server-Sent Events可以做實(shí)時(shí)評(píng)論、在線狀態(tài)這類功能。需要說(shuō)明的是tRPC的subscription在Next.js上的配置比query稍復(fù)雜你需要額外處理EventSource的連接生命周期。還有一個(gè)很實(shí)用的擴(kuò)展是把t3code當(dāng)作一個(gè)內(nèi)部管理后臺(tái)的基石。T3 Stack做后臺(tái)系統(tǒng)非常順手左邊側(cè)邊欄導(dǎo)航、右邊數(shù)據(jù)表格、頂部搜索篩選這些功能在Tailwind加tRPC的組合下開(kāi)發(fā)速度比傳統(tǒng)方案快一截。因?yàn)槟悴槐鼗〞r(shí)間維護(hù)接口文檔改完數(shù)據(jù)模型整個(gè)后臺(tái)的字段提示都會(huì)同步更新。我個(gè)人的體會(huì)是T3 Stack特別適合這種“一個(gè)人或者小團(tuán)隊(duì)要快速把想法變成可用產(chǎn)品”的場(chǎng)景。它的學(xué)習(xí)曲線不是完全沒(méi)有比如第一次接觸tRPC時(shí)你會(huì)疑惑“這到底怎么通信的”但一旦跑通第一個(gè)query后面的開(kāi)發(fā)會(huì)越寫(xiě)越順。踩過(guò)幾次坑之后你會(huì)越來(lái)越依賴IDE的類型提示而不是翻接口文檔。最后再分享一個(gè)小技巧如果你在服務(wù)端直接用createCaller發(fā)現(xiàn)某個(gè)查詢返回的數(shù)據(jù)格式和客戶端調(diào)用時(shí)略有不同比如多了一層包裝可以看看src/trpc/server.ts里的初始化代碼確認(rèn)是否傳入了正確的headers。很多莫名其妙的SSR渲染差異追到最后都是請(qǐng)求上下文沒(méi)傳對(duì)。搞定了這點(diǎn)t3code這套流程基本就穩(wěn)了。 T3 Stack全棧類型安全實(shí)戰(zhàn)：tRPC+Prisma+Next.js開(kāi)發(fā)指南
1. 項(xiàng)目緣起與整體設(shè)計(jì)思路1.1 t3code是什么一個(gè)圍繞T3 Stack落地的全棧類型安全項(xiàng)目t3code這個(gè)名字第一眼容易讓人疑惑——T3指的是什么code肯定離不開(kāi)寫(xiě)代碼但T3到底是什么這里我得先把背景交代清楚。T3 Stack是一套由TypeScript、Next.js、tRPC、Tailwind CSS、Prisma以及可選的NextAuth.js組合而成的全棧Web開(kāi)發(fā)技術(shù)棧。它的核心理念就是讓“類型安全”貫穿整個(gè)開(kāi)發(fā)鏈路從數(shù)據(jù)庫(kù)的數(shù)據(jù)模型到后端API的輸入輸出再到前端頁(yè)面的數(shù)據(jù)消費(fèi)所有類型都是同一個(gè)源頭由TypeScript編譯器幫你兜底。我最初接觸T3 Stack是因?yàn)橐粋€(gè)實(shí)際痛點(diǎn)傳統(tǒng)的前后端分離項(xiàng)目里后端REST接口寫(xiě)好了前端要重新定義一遍TypeScript接口參數(shù)結(jié)構(gòu)稍微變一下前端經(jīng)常要翻半天才知道哪里壞了。更離譜的是接口文檔和代碼脫節(jié)后端改了字段忘記同步文檔前端收到一個(gè)不符合預(yù)期的響應(yīng)只能打開(kāi)瀏覽器控制臺(tái)一個(gè)一個(gè)對(duì)字段。t3code這個(gè)項(xiàng)目本質(zhì)上是我把T3 Stack完整跑通一遍后沉淀下來(lái)的經(jīng)驗(yàn)總結(jié)從數(shù)據(jù)庫(kù)模型設(shè)計(jì)、API層搭建、前端頁(yè)面渲染到部署時(shí)的常見(jiàn)坑全部走了一遍。它解決的核心問(wèn)題就是“前后端類型割裂”以及由此帶來(lái)的聯(lián)調(diào)效率低下。這個(gè)內(nèi)容適合誰(shuí)來(lái)參考一種是剛接觸全棧開(kāi)發(fā)、想找一個(gè)現(xiàn)代實(shí)踐方案的中級(jí)開(kāi)發(fā)者另一種是已經(jīng)用REST模式寫(xiě)了好幾年想看看tRPC這條路到底靠不靠譜的人。我可以先給你一個(gè)結(jié)論如果你只做短平快的內(nèi)部工具或者獨(dú)立開(kāi)發(fā)一個(gè)中小型產(chǎn)品T3 Stack這套組合能幫你把CRUD開(kāi)發(fā)時(shí)間壓縮一半以上而且類型錯(cuò)誤在編譯期就被攔住不再是運(yùn)行時(shí)的黑色報(bào)錯(cuò)。1.2 為什么選T3這套組合而不是自己拼一套技術(shù)棧很多人第一個(gè)問(wèn)題就是Next.js、Prisma、tRPC我都聽(tīng)過(guò)但為什么要綁在一起我自己拼一套不行嗎當(dāng)然可以但你自己拼面臨的是版本兼容、上下文傳遞、類型定義手工維護(hù)這一大堆瑣碎問(wèn)題。T3 Stack默認(rèn)把這套集成方案已經(jīng)內(nèi)置好了。它不是一個(gè)像Laravel那樣的大一統(tǒng)框架而是一套約定告訴你每個(gè)工具負(fù)責(zé)什么環(huán)節(jié)、數(shù)據(jù)流怎么走。具體拆開(kāi)看Next.js負(fù)責(zé)前端頁(yè)面渲染、路由以及前后端代碼放在同一個(gè)倉(cāng)庫(kù)里跑的便利性。你可以在app目錄里寫(xiě)頁(yè)面組件也可以在src/server/api里寫(xiě)后端邏輯。Prisma管數(shù)據(jù)庫(kù)訪問(wèn)層它的schema.prisma文件是數(shù)據(jù)模型的唯一真相源。你改了這個(gè)文件運(yùn)行遷移命令之后TypeScript類型會(huì)自動(dòng)更新。tRPC是T3 Stack的靈魂。它讓你在Next.js的API層定義一個(gè)個(gè)procedure前端直接像調(diào)用本地函數(shù)一樣調(diào)用這些procedure不需要REST路徑、不需要手寫(xiě)請(qǐng)求封裝、不需要手寫(xiě)響應(yīng)類型。Tailwind CSS負(fù)責(zé)樣式它不參與數(shù)據(jù)流但它的原子類設(shè)計(jì)讓UI層不需要額外維護(hù)組件樣式文件開(kāi)發(fā)速度提升很明顯。NextAuth.js現(xiàn)在叫Auth.js負(fù)責(zé)認(rèn)證它把登錄會(huì)話和tRPC的context打通了你做“只能看到自己數(shù)據(jù)”這類功能時(shí)會(huì)省很多事。這套組合的核心邏輯是“少即是多”。T3 Stack的設(shè)計(jì)哲學(xué)決定了它只保留你真正需要的東西你能用TypeScript解決的事情絕不引入額外的運(yùn)行時(shí)依賴。舉個(gè)例子tRPC的輸入校驗(yàn)在開(kāi)發(fā)模式走zod驗(yàn)證在類型層面你不需要手動(dòng)聲明請(qǐng)求參數(shù)的類型zod schema本身就是類型這也是t3code這個(gè)項(xiàng)目名字里“code”部分的意義——代碼即契約類型即文檔。2. t3code的核心架構(gòu)與關(guān)鍵技術(shù)拆解2.1 端到端類型共享的完整數(shù)據(jù)鏈路t3code項(xiàng)目里最值得琢磨的一條線是類型從數(shù)據(jù)庫(kù)一路流到前端組件的完整鏈路。這不像傳統(tǒng)的REST API那樣前端拿到響應(yīng)后還要定義一個(gè)interface去聲明“這個(gè)響應(yīng)長(zhǎng)什么樣”。在T3 Stack里類型源頭只有一個(gè)Prisma Schema。我建議在動(dòng)手前先記住這條鏈路schema.prisma數(shù)據(jù)庫(kù)模型 ↓ 類型生成 Prisma ClientNode層訪問(wèn)數(shù)據(jù)庫(kù) ↓ 傳給 tRPC procedure輸入用zod校驗(yàn)輸出依賴Prisma類型 ↓ 類型推斷 react-query hooks前端調(diào)用tRPC的useQuery ↓ 類型傳遞 React組件里的props/state如果鏈路中間任何一環(huán)修改了數(shù)據(jù)類型TypeScript編譯器會(huì)立刻告訴你哪個(gè)組件在傳參時(shí)出了錯(cuò)。比如數(shù)據(jù)庫(kù)里把用戶名字段從name改成了username你在Prisma模型里改完運(yùn)行npx prisma generate然后編譯項(xiàng)目所有用到name的組件全部報(bào)錯(cuò)。這種“改一處全項(xiàng)目受檢”的體驗(yàn)在傳統(tǒng)模式下需要額外配合swagger-codegen之類的代碼生成工具才能勉強(qiáng)做到而且生成的代碼版本管理還是個(gè)大麻煩。T3 Stack把這一整套流程收斂到了編譯器和IDE提示里省心非常多。在實(shí)際落地時(shí)我特別推薦一個(gè)習(xí)慣先把schema.prisma設(shè)計(jì)得足夠貼合業(yè)務(wù)然后再去寫(xiě)頁(yè)面。因?yàn)镻risma模型一旦確定后面所有的API邏輯都是圍繞這套模型展開(kāi)的。數(shù)據(jù)庫(kù)設(shè)計(jì)考慮得越周全tRPC路由寫(xiě)起來(lái)就越順。2.2 tRPC的請(qǐng)求生命周期函數(shù)調(diào)用為什么能替代REST很多人聽(tīng)到tRPC會(huì)疑惑前端直接“調(diào)用函數(shù)”網(wǎng)絡(luò)請(qǐng)求到底怎么走其實(shí)底層的HTTP傳輸并沒(méi)消失tRPC只是幫你把“生產(chǎn)請(qǐng)求、解析請(qǐng)求、封裝響應(yīng)、校驗(yàn)參數(shù)、推斷類型”這些原本手工寫(xiě)的代碼全部自動(dòng)化了。在t3code項(xiàng)目里一個(gè)標(biāo)準(zhǔn)操作是這樣的// src/server/api/routers/post.ts import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ list: publicProcedure .input( z.object({ limit: z.number().min(1).max(100).default(20), cursor: z.string().optional(), }) ) .query(async ({ ctx, input }) { const items await ctx.db.post.findMany({ take: input.limit, skip: input.cursor ? 1 : 0, cursor: input.cursor ? { id: input.cursor } : undefined, orderBy: { createdAt: desc }, }); return items; }), });前端調(diào)用時(shí)是這樣的const { data, isPending } api.post.list.useQuery({ limit: 10 });注意useQuery里面的參數(shù)類型和返回的data類型都是編譯時(shí)確定的。如果你在調(diào)用時(shí)傳了多余的字段或者少傳了必填字段IDE會(huì)直接報(bào)錯(cuò)。這種體驗(yàn)平時(shí)用REST API時(shí)根本不可能有。再拆解一下tRPC背后的生命周期它可以分為五個(gè)階段前端調(diào)用useQuery時(shí)tRPC會(huì)生成一個(gè)以procedure路徑為標(biāo)識(shí)的HTTP請(qǐng)求比如/api/trpc/post.list。Next.js的API路由收到請(qǐng)求tRPC根據(jù)路徑找到對(duì)應(yīng)router。請(qǐng)求先經(jīng)過(guò)input中的zod schema校驗(yàn)參數(shù)不合格直接返回客戶端錯(cuò)誤。在query函數(shù)內(nèi)部ctx攜帶數(shù)據(jù)庫(kù)實(shí)例和session信息供你執(zhí)行數(shù)據(jù)訪問(wèn)。響應(yīng)返回后tRPC客戶端根據(jù)路由類型推斷出返回值類型前端拿到帶有完整類型的data。有人會(huì)問(wèn)為什么不用GraphQLGraphQL也能做到類型安全但它的schema定義、resolver拆分、codegen成本比較高。tRPC更適合“服務(wù)端和客戶端同在一個(gè)代碼倉(cāng)庫(kù)”的場(chǎng)景你不需要定義一套獨(dú)立的schema語(yǔ)言TypeScript本身的類型就是schema。這也是t3code能快速落地的關(guān)鍵原因。2.3 Prisma Schema設(shè)計(jì)數(shù)據(jù)模型的真相源t3code項(xiàng)目的數(shù)據(jù)模型我建議按業(yè)務(wù)實(shí)體來(lái)劃分。舉一個(gè)實(shí)際例子一個(gè)帶評(píng)論功能的博客系統(tǒng)包含用戶User、文章Post、評(píng)論Comment三個(gè)核心實(shí)體它們之間的關(guān)聯(lián)關(guān)系用Prisma模型表示如下// prisma/schema.prisma generator client { provider prisma-client-js } datasource db { provider sqlite // 開(kāi)發(fā)環(huán)境先用SQLite生產(chǎn)切換PostgreSQL url env(DATABASE_URL) } model User { id String id default(cuid()) name String? email String unique posts Post[] comments Comment[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Post { id String id default(cuid()) title String content String published Boolean default(false) author User relation(fields: [authorId], references: [id]) authorId String comments Comment[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Comment { id String id default(cuid()) body String post Post relation(fields: [postId], references: [id]) postId String author User relation(fields: [authorId], references: [id]) authorId String createdAt DateTime default(now()) }這里我用了cuid()而不是自增整數(shù)主鍵原因有幾個(gè)公開(kāi)API中整數(shù)ID容易枚舉遍歷cuid更難猜測(cè)分布式或多人協(xié)作時(shí)不需要等待數(shù)據(jù)庫(kù)自增tRPC把ID作為字符串傳參時(shí)不會(huì)有類型不匹配問(wèn)題。設(shè)計(jì)模型時(shí)我有兩個(gè)建議其一盡早把唯一性約束寫(xiě)清楚比如email unique到了生產(chǎn)環(huán)境再補(bǔ)唯一索引遷移成本和風(fēng)險(xiǎn)都會(huì)高很多其二DateTime字段務(wù)必加上default(now())否則創(chuàng)建記錄時(shí)漏傳字段會(huì)導(dǎo)致運(yùn)行時(shí)錯(cuò)誤。模型改完后運(yùn)行npx prisma migrate dev --name init npx prisma generate第一次遷移會(huì)創(chuàng)建數(shù)據(jù)庫(kù)表并生成Prisma Client類型。之后每次修改模型重復(fù)這兩個(gè)命令即可。有一個(gè)細(xì)節(jié)建議特別注意prisma generate生成的類型文件是tRPC返回值類型推斷的依據(jù)所以改完schema后一定要重新生成否則編譯期拿到的還是舊類型。3. 實(shí)操落地從零搭建一個(gè)可運(yùn)行的t3code項(xiàng)目3.1 初始化腳手架與目錄結(jié)構(gòu)解讀T3 Stack官方維護(hù)了一個(gè)腳手架create-t3-app建議從它開(kāi)始因?yàn)閮?nèi)置了這些能力的初始配置TypeScript嚴(yán)格模式、Next.js App Router、tRPC router目錄、Prisma數(shù)據(jù)庫(kù)連接、Tailwind樣式體系。自己手搓這些配置至少需要折騰大半天而腳手架只要一個(gè)命令npx create-t3-applatest t3code項(xiàng)目初始化時(shí)交互式命令行會(huì)問(wèn)你開(kāi)啟哪些可選模塊。我的建議是首次體驗(yàn)全開(kāi)尤其是NextAuth.js和Drizzle這類的依賴先裝上再逐個(gè)理解。如果你已經(jīng)確定不用數(shù)據(jù)庫(kù)可以不勾Prisma。但t3code既然是圍繞類型安全的全棧項(xiàng)目數(shù)據(jù)庫(kù)訪問(wèn)層是必要的別省。初始化完成后標(biāo)準(zhǔn)目錄長(zhǎng)這樣prisma/ schema.prisma src/ app/ api/ trpc/ [trpc]/route.ts layout.tsx page.tsx server/ api/ routers/ post.ts root.ts db.ts auth.ts trpc/ server.ts client.ts react.tsx初次看到這些目錄的人容易慌其實(shí)關(guān)鍵就兩處src/server/api/routers/放你的tRPC業(yè)務(wù)邏輯src/trpc/放服務(wù)端和客戶端共享的類型定義與tRPC實(shí)例。啟動(dòng)開(kāi)發(fā)服務(wù)器npm run dev看到Next.js默認(rèn)頁(yè)后先別急著寫(xiě)代碼進(jìn)入src/server/db.ts確認(rèn)數(shù)據(jù)庫(kù)地址已經(jīng)正確配置。腳手架默認(rèn)讀DATABASE_URL這個(gè)環(huán)境變量如果你用SQLite.env里應(yīng)該長(zhǎng)這樣DATABASE_URLfile:./db.sqlite3.2 數(shù)據(jù)模型遷移的完整過(guò)程我以帶評(píng)論的博客功能為例先創(chuàng)建幾組tRPC路由。第一步定義文章相關(guān)路由// src/server/api/routers/post.ts import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ listPublished: publicProcedure .input( z.object({ limit: z.number().min(1).max(50).default(10), }) ) .query(async ({ ctx, input }) { return ctx.db.post.findMany({ where: { published: true }, orderBy: { createdAt: desc }, take: input.limit, include: { author: { select: { name: true } } }, }); }), getById: publicProcedure .input(z.object({ id: z.string().cuid() })) .query(async ({ ctx, input }) { return ctx.db.post.findUnique({ where: { id: input.id }, include: { comments: { include: { author: true } } }, }); }), create: protectedProcedure .input( z.object({ title: z.string().min(1).max(120), content: z.string().min(1), published: z.boolean().default(false), }) ) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, published: input.published, authorId: ctx.session.user.id, }, }); }), });第二步把路由掛到根router上// src/server/api/root.ts import { postRouter } from ./routers/post; import { createTRPCRouter } from ../trpc; export const appRouter createTRPCRouter({ post: postRouter, }); export type AppRouter typeof appRouter;注意export type AppRouter這一行它是tRPC前端類型推斷的核心。前端trpc客戶端實(shí)例就依賴這個(gè)類型來(lái)確定所有procedure的入?yún)⒑统鰠㈩愋?。只要后端router變化前端代碼的TypeScript提示立刻跟著變。第三步運(yùn)行遷移npx prisma migrate dev --name add-post-comment此時(shí)數(shù)據(jù)庫(kù)已經(jīng)生成對(duì)應(yīng)的表。你可以打開(kāi)prisma/studio看一下數(shù)據(jù)模型npx prisma studioStudio會(huì)啟動(dòng)一個(gè)本地可視化管理界面用來(lái)檢查數(shù)據(jù)是否正確寫(xiě)入排查時(shí)很好用。3.3 前端頁(yè)面調(diào)用tRPC并渲染數(shù)據(jù)前端調(diào)用邏輯放在Next.js的Server Component或者Client Component里都有。以Client Component為例use client; import { api } from ~/trpc/react; export function PostList() { const { data, isLoading, error } api.post.listPublished.useQuery({ limit: 10, }); if (isLoading) return div加載中.../div; if (error) return div請(qǐng)求失敗: {error.message}/div; return ( ul {data?.map((post) ( li key{post.id} h2{post.title}/h2 p{post.content}/p span作者: {post.author.name ?? 匿名}/span /li ))} /ul ); }我覺(jué)得這個(gè)模式最大的價(jià)值在于編輯代碼時(shí)IDE的自動(dòng)補(bǔ)全能顯示出一個(gè)數(shù)據(jù)庫(kù)查詢返回的所有字段而且字段拼錯(cuò)會(huì)直接報(bào)ts-error。你不必記住后端到底返回了什么因?yàn)殚_(kāi)發(fā)環(huán)境里整個(gè)類型鏈?zhǔn)峭该鞯摹倪@個(gè)角度看t3code項(xiàng)目的“類型安全”不是一句空話而是實(shí)際開(kāi)發(fā)中的默認(rèn)狀態(tài)。還有一個(gè)容易被忽略的地方在Server Component中如果你通過(guò)createCaller直接調(diào)用tRPC查詢可以避免額外的HTTP往返import { createCaller } from ~/trpc/server; export default async function HomePage() { const caller createCaller(); const posts await caller.post.listPublished({ limit: 5 }); return ( main PostList initialData{posts} / /main ); }createCaller從服務(wù)端直接調(diào)用procedure函數(shù)繞過(guò)了HTTP層響應(yīng)時(shí)間會(huì)更短并且仍然能得到完整的類型推斷。理解這一點(diǎn)后你就知道T3 Stack并不強(qiáng)迫你所有的數(shù)據(jù)都走網(wǎng)絡(luò)請(qǐng)求該直連的時(shí)候直連該走HTTP的時(shí)候走HTTP主動(dòng)權(quán)在你自己手里。3.4 鑒權(quán)與受保護(hù)接口的落地前面post.create用了protectedProcedure它的含義是“必須登錄才能調(diào)用”。T3 Stack默認(rèn)集成NextAuth.js現(xiàn)在叫Auth.js它會(huì)把session塞進(jìn)tRPC的context里。在src/server/api/trpc.ts里可以看到類似這樣的代碼export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { ...ctx, session: ctx.session } }); });所有掛在protectedProcedure下的接口只要用戶未登錄就會(huì)返回401錯(cuò)誤前端useQuery會(huì)捕獲到error.data.httpStatus為401。你可以據(jù)此在頁(yè)面上跳轉(zhuǎn)登錄頁(yè)。如果要做“用戶只能修改自己的文章”這類權(quán)限控制在mutation內(nèi)部判斷即可update: protectedProcedure .input(z.object({ id: z.string().cuid(), title: z.string().optional() })) .mutation(async ({ ctx, input }) { const post await ctx.db.post.findUnique({ where: { id: input.id } }); if (!post || post.authorId ! ctx.session.user.id) { throw new TRPCError({ code: FORBIDDEN }); } return ctx.db.post.update({ where: { id: input.id }, data: { title: input.title }, }); }),這類授權(quán)邏輯寫(xiě)在tRPC服務(wù)端的最明顯好處是前端無(wú)論如何繞道都不會(huì)繞過(guò)權(quán)限校驗(yàn)因?yàn)樾ｒ?yàn)發(fā)生在靠近數(shù)據(jù)源的那一層。3.5 服務(wù)端渲染時(shí)如何避免類型與數(shù)據(jù)不同步在Server Component里直接調(diào)用createCaller有一個(gè)細(xì)節(jié)要注意如果procedure內(nèi)部使用了ctx.headers比如做多語(yǔ)言判斷Server Component環(huán)境里可能拿不到完全一致的header信息。腳手架給了一個(gè)headers注入的方式createCaller默認(rèn)會(huì)從Next的headers()里讀取。我在實(shí)際使用中遇到過(guò)開(kāi)發(fā)模式一切正常、部署后偶發(fā)跨域讀取異常的問(wèn)題主要原因是不知道為什么在某個(gè)中間層請(qǐng)求頭被改寫(xiě)。排查思路是先在src/server/api/trpc.ts里加一個(gè)臨時(shí)的header打印然后分別對(duì)比瀏覽器直連和Server Component內(nèi)部調(diào)用的結(jié)果。如果發(fā)現(xiàn)差異就改為顯式傳入關(guān)鍵header字段const caller createCaller({ headers: { x-user-locale: zh-CN } });這種顯式傳參方式能避免依賴隱式上下文排查起來(lái)也更清晰。4. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄4.1 類型報(bào)錯(cuò)集中在哪幾個(gè)坑t3code這類T3項(xiàng)目最常見(jiàn)的編譯錯(cuò)誤我總結(jié)下來(lái)有四個(gè)來(lái)源Prisma類型未重新生成。改了schema.prisma后沒(méi)有運(yùn)行npx prisma generate結(jié)果前端引用的字段在舊類型上不存在。解決辦法就是先跑generate大多數(shù)情況下編譯錯(cuò)誤會(huì)消失。zod schema與Prisma類型不一致。比如input里聲明了一個(gè)必填字符串但Prisma模型里字段允許為null。這種情況多發(fā)生在“手寫(xiě)schema時(shí)想得不夠周全”。我的建議是輸入校驗(yàn)嚴(yán)格一點(diǎn)內(nèi)部處理靈活一點(diǎn)。你不想讓前端傳null就在zod里直接拒絕null。ctx.db類型為null或undefined。在初始化腳手架時(shí)createTRPCContext里面的db可能因?yàn)榄h(huán)境變量沒(méi)配好而變成undefined導(dǎo)致后續(xù)所有使用ctx.db的地方報(bào)錯(cuò)。檢查一下.env里的DATABASE_URL是否正確。在Server Component中錯(cuò)誤引用客戶端tRPC實(shí)例。比如在app/page.tsx這種Server Component里使用了~/trpc/react這是客戶端專用模塊應(yīng)該改用~/trpc/server的createCaller。否則會(huì)報(bào)“組件無(wú)法在Server Component中使用客戶端hook”之類的錯(cuò)誤。4.2 tRPC請(qǐng)求404、無(wú)法訪問(wèn)服務(wù)器返回問(wèn)題如果你看到瀏覽器請(qǐng)求/api/trpc/post.list返回404而不是正常的JSON響應(yīng)通常是Next.js的API路由沒(méi)有正確掛載。檢查src/app/api/trpc/[trpc]/route.ts文件是否存在并且內(nèi)容是否導(dǎo)出了GET和POST兩個(gè)handler。還有一個(gè)容易被忽略的情況如果你在Next.js中間件middleware里做了路徑攔截比如未登錄時(shí)重定向到登錄頁(yè)可能會(huì)把/api/trpc的請(qǐng)求也攔截掉導(dǎo)致所有tRPC請(qǐng)求404或302。我給中間件加一個(gè)白名單export const config { matcher: [/((?!api/trpc|_next/static|_next/image|favicon.ico).*)], };這個(gè)方法能放行API路徑又不影響頁(yè)面級(jí)鑒權(quán)。4.3 Prisma遷移沖突與數(shù)據(jù)庫(kù)狀態(tài)不一致開(kāi)發(fā)過(guò)程中經(jīng)常要反復(fù)修改模型如果上一次遷移還沒(méi)應(yīng)用到某個(gè)環(huán)境再跑新遷移時(shí)可能報(bào)P3005之類的錯(cuò)誤。不用慌先把本地的遷移回滾到一致?tīng)顟B(tài)。操作方式npx prisma migrate reset它會(huì)清空數(shù)據(jù)庫(kù)重新應(yīng)用所有遷移文件。這個(gè)命令只適合開(kāi)發(fā)環(huán)境生產(chǎn)庫(kù)千萬(wàn)不要用。如果你在團(tuán)隊(duì)協(xié)作中遇到遷移分支沖突建議約定每個(gè)人都基于最新的main分支拉代碼跑完遷移再改模型減少遷移文件沖突的概率。4.4 tRPC在SSR模式下的性能與緩存問(wèn)題在Server Component里使用createCaller每次渲染頁(yè)面都可能執(zhí)行數(shù)據(jù)庫(kù)查詢。如果某個(gè)查詢非常重頁(yè)面響應(yīng)會(huì)變慢。我自己給t3code加了一層簡(jiǎn)單的緩存針對(duì)不常變更的列表在router內(nèi)做數(shù)據(jù)緩存。其實(shí)Next.js本身提供了unstable_cache可以包住caller.xxx這個(gè)執(zhí)行過(guò)程但要注意緩存鍵必須和入?yún)⒈３忠恢滦浴２贿^(guò)要提醒一點(diǎn)不要把ctx整個(gè)對(duì)象緩存下來(lái)它包含session等請(qǐng)求級(jí)信息。像下面這種做法就比較容易踩坑。// 錯(cuò)誤示范緩存了包含請(qǐng)求級(jí)信息的ctx const cached await unstable_cache( () caller.post.listPublished(input), // 緩存條件里沒(méi)有考慮用戶權(quán)限危險(xiǎn) )();更穩(wěn)妥的做法是在procedure函數(shù)的實(shí)現(xiàn)內(nèi)部做細(xì)粒度緩存或者用react-query的staleTime控制客戶端緩存。對(duì)于剛上手T3 Stack的人來(lái)說(shuō)先別過(guò)度設(shè)計(jì)緩存保持默認(rèn)行為等確實(shí)有性能瓶頸再優(yōu)化。4.5 排查思路速查表現(xiàn)象首要排查點(diǎn)推薦命令/操作前端調(diào)用后報(bào)404Next.js API路由是否掛載檢查src/app/api/trpc/[trpc]/route.ts編譯報(bào)類型缺失Prisma類型未更新npx prisma generate查詢字段為undefined前端字段名與Prisma返回不一致在IDE中懸浮查看返回類型401錯(cuò)誤使用了protectedProcedure但未登錄在調(diào)用前確保session.user存在Server Component里用不了hook誤用了客戶端tRPC實(shí)例改用~/trpc/server的createCaller數(shù)據(jù)庫(kù)遷移失敗遷移歷史沖突開(kāi)發(fā)環(huán)境用migrate reset數(shù)據(jù)查詢慢N1查詢或缺少索引使用Prisma的include優(yōu)化關(guān)聯(lián)查詢我建議把這些常見(jiàn)問(wèn)題存在本地筆記里每次新項(xiàng)目遇到相同報(bào)錯(cuò)直接翻表格對(duì)照能節(jié)省很多時(shí)間。5. 后續(xù)擴(kuò)展思路與我的個(gè)人體會(huì)t3code這個(gè)項(xiàng)目其實(shí)可以在很多方向繼續(xù)擴(kuò)展。最直接的一步是接入文件上傳用tRPC定義一個(gè)mutation接收文件元數(shù)據(jù)然后把文件存到對(duì)象存儲(chǔ)或者本地目錄數(shù)據(jù)庫(kù)里只保存訪問(wèn)路徑。前端可以用react-dropzone之類的組件配合調(diào)用整個(gè)過(guò)程仍然能保持類型安全。另一個(gè)方向是加入訂閱推送tRPC的subscription能力配合Server-Sent Events可以做實(shí)時(shí)評(píng)論、在線狀態(tài)這類功能。需要說(shuō)明的是tRPC的subscription在Next.js上的配置比query稍復(fù)雜你需要額外處理EventSource的連接生命周期。還有一個(gè)很實(shí)用的擴(kuò)展是把t3code當(dāng)作一個(gè)內(nèi)部管理后臺(tái)的基石。T3 Stack做后臺(tái)系統(tǒng)非常順手左邊側(cè)邊欄導(dǎo)航、右邊數(shù)據(jù)表格、頂部搜索篩選這些功能在Tailwind加tRPC的組合下開(kāi)發(fā)速度比傳統(tǒng)方案快一截。因?yàn)槟悴槐鼗〞r(shí)間維護(hù)接口文檔改完數(shù)據(jù)模型整個(gè)后臺(tái)的字段提示都會(huì)同步更新。我個(gè)人的體會(huì)是T3 Stack特別適合這種“一個(gè)人或者小團(tuán)隊(duì)要快速把想法變成可用產(chǎn)品”的場(chǎng)景。它的學(xué)習(xí)曲線不是完全沒(méi)有比如第一次接觸tRPC時(shí)你會(huì)疑惑“這到底怎么通信的”但一旦跑通第一個(gè)query后面的開(kāi)發(fā)會(huì)越寫(xiě)越順。踩過(guò)幾次坑之后你會(huì)越來(lái)越依賴IDE的類型提示而不是翻接口文檔。最后再分享一個(gè)小技巧如果你在服務(wù)端直接用createCaller發(fā)現(xiàn)某個(gè)查詢返回的數(shù)據(jù)格式和客戶端調(diào)用時(shí)略有不同比如多了一層包裝可以看看src/trpc/server.ts里的初始化代碼確認(rèn)是否傳入了正確的headers。很多莫名其妙的SSR渲染差異追到最后都是請(qǐng)求上下文沒(méi)傳對(duì)。搞定了這點(diǎn)t3code這套流程基本就穩(wěn)了。