現(xiàn)前后端類型安全打通)
前陣子我在梳理全棧項(xiàng)目模板時(shí)發(fā)現(xiàn)一個(gè)很有意思的現(xiàn)象很多人把 T3 Stack 掛在嘴邊但真正能把 Next.js、TypeScript、tRPC、Prisma、Tailwind 這套組合落成一個(gè)可復(fù)用、可擴(kuò)展的代碼體系的人其實(shí)并不多。t3code 這個(gè)名字乍一看只是個(gè)簡單的“代碼”集合但往深了挖它更像是一套以 TypeScript 為骨架、以類型安全為靈魂的全棧項(xiàng)目落地模板。它能解決的是開發(fā)團(tuán)隊(duì)在啟動(dòng)新項(xiàng)目時(shí)反復(fù)做重復(fù)選型、重復(fù)配環(huán)境、重復(fù)寫膠水代碼的問題也能幫助個(gè)人開發(fā)者從零快速搭出一個(gè)結(jié)構(gòu)清晰、前后端類型打通的應(yīng)用骨架。這篇文章不適合只想抄一段代碼就跑的人更適合真正想把全棧 TypeScript 項(xiàng)目做出“標(biāo)準(zhǔn)姿勢”的人。無論你是剛開始接觸 T3 相關(guān)技術(shù)棧還是已經(jīng)在用 Next.js 但總感覺前后端類型沒有打通都可以從這套代碼實(shí)踐中找到可以照搬的結(jié)構(gòu)和思路。我會(huì)直接把 t3code 在架構(gòu)選型、目錄組織、數(shù)據(jù)模型、接口封裝、前端接入、部署細(xì)節(jié)這幾個(gè)層面的實(shí)際做法拆開來講。1. t3code 在解決什么問題一套全棧 TypeScript 的“標(biāo)準(zhǔn)姿勢”1.1 從技術(shù)選型說起為什么是 Next.js tRPC Prisma很多人在搭新項(xiàng)目時(shí)第一個(gè)糾結(jié)的地方就是技術(shù)選型。前端用 React 沒問題但 Next.js 是不是過度設(shè)計(jì)后端接口用 REST 還是 GraphQL數(shù)據(jù)庫 ORM 用 Prisma 還是 Drizzle這些問題一旦在團(tuán)隊(duì)里展開基本就是一場沒完沒了的討論。t3code 的選擇邏輯非常直白如果整個(gè)應(yīng)用都用 TypeScript 寫那就讓類型從前端一路穿透到數(shù)據(jù)庫。Next.js 負(fù)責(zé)應(yīng)用框架和應(yīng)用路由既有 SSR 能力也可以純靜態(tài)導(dǎo)出團(tuán)隊(duì)可以根據(jù)場景分別使用 Server Component 和 Client Component。TypeScript 負(fù)責(zé)語言層面的類型約束從組件 props 到接口參數(shù)所有邊界都有類型定義。tRPC 負(fù)責(zé)前后端接口通信它的特點(diǎn)是不需要額外定義 REST 路由也不需要寫 GraphQL Schema直接利用 TypeScript 的類型推斷能力讓前端調(diào)用后端方法時(shí)獲得完整的自動(dòng)補(bǔ)全和類型校驗(yàn)。Prisma 負(fù)責(zé)數(shù)據(jù)模型定義和數(shù)據(jù)庫訪問schema 文件本身就是一份數(shù)據(jù)庫設(shè)計(jì)文檔同時(shí)生成的客戶端自帶類型。這四樣?xùn)|西放在一起等于把“前端組件、后端邏輯、數(shù)據(jù)模型”三層的類型全部串成一整條鏈。說白了你在前端寫const data await trpc.user.list.query()如果后端list方法沒寫編輯器直接就報(bào)紅了根本不用等運(yùn)行時(shí)接口報(bào) 404。1.2 T3 理念的核心類型安全不是口號(hào)是流程本身很多人會(huì)覺得類型安全就是“用了 TypeScript 而已”但 t3code 做的事情不止于此。它把類型安全延伸到了三個(gè)層面第一層是數(shù)據(jù)模型的類型安全。Prisma Schema 里定義了User、Post這些模型字段類型、關(guān)聯(lián)關(guān)系、索引都在這里確認(rèn)生成的 TypeScript 類型直接成為整個(gè)應(yīng)用的唯一事實(shí)來源。第二層是接口調(diào)用的類型安全。tRPC Router 的每個(gè) procedure 都帶有輸入輸出類型。你在前端寫調(diào)用時(shí)傳的參數(shù)類型不對(duì)會(huì)立刻報(bào)錯(cuò)返回的數(shù)據(jù)結(jié)構(gòu)也是自動(dòng)推斷出來的不需要手動(dòng)維護(hù)一份接口文檔。第三層是業(yè)務(wù)狀態(tài)的類型安全。React Query 配合 tRPC請(qǐng)求狀態(tài)、緩存 key、數(shù)據(jù)更新都能類型化。重新取數(shù)、失效緩存、樂觀更新這些操作不再是靠字符串約定而是靠類型系統(tǒng)約束。所以 t3code 的核心價(jià)值不是它用了多新的技術(shù)而是它把類型安全變成了整個(gè)開發(fā)流程的默認(rèn)行為。這就像你寫后端代碼時(shí)函數(shù)參數(shù)不寫類型會(huì)渾身難受一樣t3code 讓你在寫全棧代碼時(shí)體會(huì)一次“類型不到處傳心里就不踏實(shí)”的狀態(tài)。2. t3code 的結(jié)構(gòu)設(shè)計(jì)與代碼組織2.1 項(xiàng)目目錄與職責(zé)劃分t3code 的目錄結(jié)構(gòu)看起來并不復(fù)雜但每個(gè)目錄的職責(zé)邊界非常清晰。我基于常見實(shí)踐把它整理成下面這套劃分方式新項(xiàng)目直接照抄都可以├── prisma │ ├── schema.prisma # 數(shù)據(jù)模型的唯一事實(shí)來源 │ └── migrations # 數(shù)據(jù)庫遷移記錄 ├── src │ ├── server │ │ ├── api │ │ │ ├── routers # 按業(yè)務(wù)域拆分的 tRPC Router │ │ │ │ ├── user.ts │ │ │ │ └── post.ts │ │ │ └── root.ts # 所有子 Router 匯總到根 Router │ │ ├── auth.ts # 認(rèn)證相關(guān)邏輯如果啟用了鑒權(quán) │ │ └── db.ts # Prisma Client 單例 │ ├── pages # Next.js 頁面路由 │ │ ├── _app.tsx # 全局 Provider 掛載點(diǎn) │ │ └── index.tsx │ ├── components # 通用 UI 組件 │ ├── styles # Tailwind 入口文件 │ ├── utils # 工具函數(shù) │ └── trpc │ ├── client.ts # 前端 tRPC 客戶端配置 │ └── server.ts # SSR 時(shí)的 tRPC 調(diào)用輔助 └── .env # 環(huán)境變量這個(gè)結(jié)構(gòu)的核心思想是按職責(zé)分層不按文件類型亂堆。server 目錄只放后端相關(guān)代碼pages 目錄只負(fù)責(zé)路由入口components 目錄只放可復(fù)用 UI。真正業(yè)務(wù)相關(guān)的代碼比如查詢邏輯、數(shù)據(jù)轉(zhuǎn)換都收在 routers 和對(duì)應(yīng)的業(yè)務(wù)模塊里。2.2 最容易被忽略的配置細(xì)節(jié)目錄結(jié)構(gòu)誰都會(huì)列真正拉開差距的是配置細(xì)節(jié)。我見過不少項(xiàng)目從表面看結(jié)構(gòu)一樣但用起來就是各種不舒服問題基本都出在下面這幾個(gè)地方。路徑別名的統(tǒng)一。tsconfig.json 里配置server/*、/*這些路徑別名本身不難難的是讓 ESLint、Prettier、Jest 這些周邊工具都認(rèn)同一套路徑。t3code 的做法是在 tsconfig 和 tailwind.config 里都顯式聲明同樣的別名確保編輯器提示、構(gòu)建解析、測試環(huán)境三者行為一致。嚴(yán)格模式必須開滿。TypeScript 的strict: true只是底線。t3code 還會(huì)額外開啟noUncheckedIndexedAccess這意味著arr[0]不會(huì)自動(dòng)推斷為元素類型而是T | undefined。這個(gè)配置一開始會(huì)覺得煩但實(shí)際上會(huì)逼你把所有數(shù)組訪問的邊界都想清楚在寫業(yè)務(wù)代碼時(shí)特別能預(yù)防線上才出現(xiàn)的取不到值問題。環(huán)境變量的類型化。項(xiàng)目啟動(dòng)時(shí)如果DATABASE_URL沒設(shè)置Prisma 會(huì)報(bào)錯(cuò)但報(bào)錯(cuò)信息有時(shí)候不夠直觀。t3code 會(huì)做一個(gè)統(tǒng)一的環(huán)境變量校驗(yàn)?zāi)K啟動(dòng)前把所有必需變量一次性檢查完缺哪個(gè)就明確提示缺哪個(gè)而不是等數(shù)據(jù)庫連接超時(shí)之后才猜原因。依賴安裝順序。先裝運(yùn)行時(shí)依賴再裝開發(fā)依賴。因?yàn)?t3code 涉及 Next.js 的編譯、Prisma 的 generate、tRPC 的類型生成這幾個(gè)工具的安裝順序如果不一致在某些 Node 版本下會(huì)出現(xiàn)原生模塊編譯失敗或者 Prisma Engine 下載不完整。3. 從零搭建一次 t3code 全流程實(shí)操3.1 環(huán)境準(zhǔn)備與腳手架初始化如果你要復(fù)現(xiàn) t3code 這套代碼實(shí)踐建議直接從干凈的目錄開始。我假設(shè)你已經(jīng)裝好了 Node.js 18 LTS 以上版本的運(yùn)行環(huán)境并且本機(jī)有可用的包管理器。創(chuàng)建一個(gè)新項(xiàng)目時(shí)可以直接基于 create-t3-app 起步。執(zhí)行初始化命令之后交互式問答里重點(diǎn)確認(rèn)幾個(gè)選項(xiàng)是否啟用 Next.js App Router、是否啟用 tRPC、是否啟用 Prisma、是否啟用 Tailwind CSS。我的建議是全選啟用因?yàn)?t3code 的完整價(jià)值就是讓這四樣?xùn)|西協(xié)同工作去掉任何一樣類型安全鏈路都會(huì)出現(xiàn)斷點(diǎn)。完成初始化后第一件事不是寫業(yè)務(wù)代碼而是先跑一遍npm run dev確認(rèn)基礎(chǔ)頁面能正常打開。然后再改schema.prisma讓 Prisma 客戶端和后端類型生成到node_modules/.prisma與src/server/db.ts能正常聯(lián)動(dòng)。這里有一個(gè)非常關(guān)鍵的細(xì)節(jié)不要一上來就用最新版 Prisma除非你已經(jīng)確認(rèn)它與 Next.js 當(dāng)前版本兼容。我在實(shí)操中遇到的多數(shù)疑難問題都源于 Prisma 升級(jí)帶來的生成路徑變化。穩(wěn)妥做法是鎖定一個(gè)經(jīng)過驗(yàn)證的版本組合比如 Next.js 14 Prisma 5.x跑通整條鏈路后再考慮升級(jí)。3.2 數(shù)據(jù)模型設(shè)計(jì)用 Prisma 定義業(yè)務(wù)實(shí)體并生成客戶端數(shù)據(jù)模型設(shè)計(jì)是 t3code 里最需要提前想清楚的部分因?yàn)?Prisma Schema 一旦確定數(shù)據(jù)庫遷移和所有關(guān)聯(lián)類型都會(huì)跟著確定下來。以一個(gè)簡單的內(nèi)容發(fā)布系統(tǒng)為例我會(huì)在prisma/schema.prisma里定義出兩個(gè)相互關(guān)聯(lián)的模型generator client { provider prisma-client-js } datasource db { provider postgresql url env(DATABASE_URL) } model User { id String id default(cuid()) email String unique name String? posts Post[] 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 createdAt DateTime default(now()) updatedAt DateTime updatedAt }一切模型設(shè)計(jì)都圍繞“關(guān)系”展開。author和posts這兩個(gè)字段在數(shù)據(jù)庫層面對(duì)應(yīng)外鍵關(guān)系在 Prisma 層面對(duì)應(yīng)關(guān)聯(lián)查詢能力。當(dāng)你寫好這條 schema 后執(zhí)行npx prisma migrate dev --name initPrisma 會(huì)幫你生成遷移文件并同步數(shù)據(jù)庫結(jié)構(gòu)同時(shí)自動(dòng)重新生成客戶端代碼。我使用 Prisma 客戶端時(shí)習(xí)慣在同一文件里導(dǎo)出單例避免在開發(fā)環(huán)境下因?yàn)槟K熱更新創(chuàng)建多個(gè)連接實(shí)例import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma?: PrismaClient }; export const prisma globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV ! production) { globalForPrisma.prisma prisma; }這個(gè)單例模式雖然不是 Prisma 官方文檔開篇就講的內(nèi)容但在 Next.js 開發(fā)模式下幾乎屬于標(biāo)配不這樣做的話每次文件改動(dòng)熱更新都可能產(chǎn)生數(shù)據(jù)庫連接堆積。3.3 接口層封裝tRPC Router 的寫法與調(diào)用鏈數(shù)據(jù)模型就緒后接下來就是最容易寫出“樣板代碼”的部分接口層。tRPC 的 Router 并不等同于傳統(tǒng) REST 路由它更像是一個(gè)“可遠(yuǎn)程調(diào)用的函數(shù)集合”。每個(gè) procedure 就是一個(gè)可被前端調(diào)用的函數(shù)由輸入解析、權(quán)限檢查、業(yè)務(wù)邏輯三部分組成。我先建立一個(gè)基礎(chǔ) Router 工廠import { initTRPC } from trpc/server; import { z } from zod; const t initTRPC.context{ userId: string | null }().create(); export const router t.router; export const publicProcedure t.procedure; export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.userId) { throw new Error(Unauthorized); } return next({ ctx: { ...ctx, userId: ctx.userId } }); });這里有個(gè)關(guān)鍵點(diǎn)輸入校驗(yàn)用 zod而且是必選項(xiàng)。很多從 REST 轉(zhuǎn)過來的開發(fā)者會(huì)覺得 zod 是多余的因?yàn)?TypeScript 類型已經(jīng)定義了參數(shù)結(jié)構(gòu)。但運(yùn)行時(shí)輸入是不可信的TypeScript 類型在編譯后會(huì)消失zod 的作用就是接管運(yùn)行時(shí)校驗(yàn)。tRPC 和 zod 是官配procedure 的輸入一旦定義好前端調(diào)用時(shí)不僅自動(dòng)獲得類型推導(dǎo)錯(cuò)誤信息也會(huì)非常直觀。具體到業(yè)務(wù) Router我會(huì)這樣寫import { z } from zod; import { router, publicProcedure, protectedProcedure } from ../trpc; import { prisma } from ../db; export const postRouter router({ list: publicProcedure .input(z.object({ take: z.number().min(1).max(50).default(10) })) .query(async ({ input }) { return prisma.post.findMany({ take: input.take, orderBy: { createdAt: desc }, }); }), 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.userId, }, }); }), });接著在 root Router 里合并所有子 Routerimport { router } from ./trpc; import { postRouter } from ./routers/post; import { userRouter } from ./routers/user; export const appRouter router({ post: postRouter, user: userRouter, }); export type AppRouter typeof appRouter;上面這一步最重要的東西是export type AppRouter。這個(gè)類型導(dǎo)出之后前端可以基于它生成完整的類型安全的 tRPC 客戶端。整個(gè)調(diào)用鏈的銜接靠的就是這個(gè)類型定義。類型的穿透力有多強(qiáng)前端代碼里手寫trpc.post.create.mutate({ title: x, content: y })時(shí)title和content都是必填的參數(shù)類型錯(cuò)誤在保存文件的那一刻就會(huì)顯示出來。整個(gè)鏈路里只要有一層類型對(duì)不上編輯器就是一面紅色錯(cuò)誤墻這比任何接口文檔都來得可靠。3.4 前端頁面接入與樣式處理t3code 的前端接入核心工作就是把 tRPC 客戶端掛到 React 應(yīng)用上然后在組件里直接調(diào)用查詢方法。頁面入口_app.tsx要包一層 Providerimport { httpBatchLink } from trpc/client; import { QueryClient, QueryClientProvider } from tanstack/react-query; import { trpc } from ../utils/trpc; import type { AppProps } from next/app; const queryClient new QueryClient({ defaultOptions: { queries: { refetchOnWindowFocus: false, }, }, }); const trpcClient trpc.createClient({ links: [ httpBatchLink({ url: /api/trpc, }), ], }); export default function App({ Component, pageProps }: AppProps) { return ( trpc.Provider client{trpcClient} queryClient{queryClient} QueryClientProvider client{queryClient} Component {...pageProps} / /QueryClientProvider /trpc.Provider ); }實(shí)際業(yè)務(wù)組件里的寫法是import { trpc } from ../utils/trpc; export default function PostList() { const { data, isLoading } trpc.post.list.useQuery({ take: 10 }); if (isLoading) return div加載中.../div; return ( ul {data?.map((post) ( li key{post.id} h2{post.title}/h2 p{post.content}/p /li ))} /ul ); }注意看調(diào)用useQuery時(shí)傳入的({ take: 10 })是有類型檢查的data的每一項(xiàng)直接就是 Prisma 返回的Post類型。這里不需要手寫任何接口類型定義也不需要在前后端之間復(fù)制 DTO。狀態(tài)管理這部分用 React Query 處理緩存、重試、加載態(tài)都不需要自己造輪子。樣式方面Tailwind 主要負(fù)責(zé)原子類但 t3code 并不強(qiáng)制你用 Tailwind。實(shí)際用下來Tailwind 在快速搭建頁面時(shí)確實(shí)高效可一旦設(shè)計(jì)系統(tǒng)復(fù)雜到一定程度單獨(dú)抽離組件樣式反而更明智。所以我的建議是項(xiàng)目前期用 Tailwind 打通所有基礎(chǔ)樣式等出現(xiàn)重復(fù)性極高的樣式組合時(shí)再抽成組件類不用把每個(gè)頁面都寫成純?cè)宇惗询B。4. 實(shí)際踩過的坑t3code 常見問題與排查記錄這一部分是我最想寫的因?yàn)?t3code 這類全棧模板真正的門檻不是學(xué)會(huì)某個(gè)框架而是各種配置在真實(shí)開發(fā)環(huán)境里互相作用時(shí)的那些隱藏問題。我整理了一份速查表然后挑幾個(gè)最典型的展開講。問題現(xiàn)象根本原因處理方式啟動(dòng)時(shí)提示PrismaClientInitializationErrorDATABASE_URL未設(shè)置或格式不正確檢查.env文件和.env.example是否同步前端調(diào)用接口時(shí)類型不匹配tRPC 客戶端基于的AppRouter類型是舊版本重新跑一遍prisma generate和類型檢查確認(rèn)根組件導(dǎo)出類型已更新頁面顯示舊數(shù)據(jù)刷新后恢復(fù)客戶端 Query 緩存未失效在 mutation 成功回調(diào)里調(diào)用trpc.useUtils().post.list.invalidate()熱更新之后數(shù)據(jù)庫連接數(shù)暴漲Next.js dev 模式下創(chuàng)建了多個(gè) Prisma 實(shí)例使用全局單例模式復(fù)用 PrismaClientTailwind 類名沒有生效內(nèi)容路徑配置不全新目錄未被掃描在tailwind.config.ts中顯式添加./src/**/*.{ts,tsx}tRPC procedure 調(diào)用報(bào) 500但日志不詳細(xì)異常被 tRPC 默認(rèn)處理攔截開發(fā)環(huán)境開啟onError日志生產(chǎn)環(huán)境使用錯(cuò)誤格式化中間件4.1 Prisma 版本升級(jí)導(dǎo)致的生成異常這個(gè)問題我會(huì)放第一個(gè)說因?yàn)閹缀趺總€(gè)跑了一段時(shí)間的 t3code 項(xiàng)目都會(huì)遇到。某天執(zhí)行npm update后突然發(fā)現(xiàn)prisma generate生成的結(jié)果和舊版本不兼容數(shù)據(jù)庫訪問層報(bào)出一堆類型錯(cuò)誤或者 Prisma Client 報(bào)“The generated client has been modified”的提示。排查思路很簡單先看項(xiàng)目鎖定文件里 Prisma 和prisma/client的版本是否完全一致。這兩個(gè)包必須同步升級(jí)不能一個(gè)升一個(gè)不升。其次看 schema 文件是否有舊的生成器配置殘留。最后如果升級(jí)后實(shí)在找不到原因直接刪除node_modules、刪除生成的prisma/migrations中未提交的遷移記錄重新安裝并執(zhí)行prisma migrate dev基本都能恢復(fù)。4.2 tRPC 類型在跨包引用時(shí)丟失tRPC 在單一代碼庫里效果最好但如果你的項(xiàng)目一開始就設(shè)計(jì)成 monorepo或者把業(yè)務(wù)模塊抽成了多個(gè) npm 包類型穿透的鏈路就可能斷掉。我遇到過的典型情況是后端新增了一個(gè) procedure前端包里的AppRouter類型始終沒有同步更新不管怎么重新安裝依賴編輯器里都看不到新接口。這個(gè)問題在 t3code 里的標(biāo)準(zhǔn)解法是確保類型導(dǎo)出的路徑是純類型導(dǎo)出并且業(yè)務(wù)包之間的依賴方式使用 workspace 協(xié)議。如果前端包直接依賴后端包的構(gòu)建產(chǎn)物那么每次后端代碼變更后都要重新構(gòu)建一次否則類型就是舊的。使用 workspace 協(xié)議配合 TypeScript Project References可以讓類型在源文件層面直接關(guān)聯(lián)省掉構(gòu)建這一步。4.3 HMR 與路由緩存帶來的“看得到舊數(shù)據(jù)”Next.js 開發(fā)模式下熱更新有時(shí)會(huì)觸發(fā)頁面路由緩存導(dǎo)致你明明改了后端返回邏輯刷新頁面看到的還是舊數(shù)據(jù)。這種行為不一定是 tRPC 或 Prisma 的問題而是 React Query 的緩存策略在作祟。解決方案是在 mutation 成功后主動(dòng)失效相關(guān)查詢緩存。t3code 習(xí)慣在封裝的創(chuàng)建、更新、刪除操作里統(tǒng)一調(diào)用失效方法const utils trpc.useUtils(); const createPost trpc.post.create.useMutation({ onSuccess: () { utils.post.list.invalidate(); }, });這樣每次數(shù)據(jù)變更后列表都會(huì)自動(dòng)重新請(qǐng)求頁面展示的數(shù)據(jù)和數(shù)據(jù)庫狀態(tài)保持一致不需要手動(dòng)刷新。這個(gè)細(xì)節(jié)如果沒處理用戶會(huì)反復(fù)反饋“我提交了但看不到新內(nèi)容”特別影響體驗(yàn)。4.4 環(huán)境變量缺失引發(fā)的隱蔽報(bào)錯(cuò)環(huán)境變量相關(guān)的問題總是最隱蔽的因?yàn)楸镜亻_發(fā)時(shí).env存在一切正常一到部署或者新成員拉代碼時(shí)缺少必要變量報(bào)錯(cuò)五花八門。我見過最心累的一種是DATABASE_URL寫錯(cuò)但不是完全缺失導(dǎo)致 Prisma 能初始化但每次查詢都超時(shí)。t3code 的做法值得借鑒在服務(wù)端入口處統(tǒng)一校驗(yàn)環(huán)境變量而不是用到哪就在哪讀取。我會(huì)寫一個(gè)簡單的校驗(yàn)函數(shù)在應(yīng)用啟動(dòng)時(shí)檢查DATABASE_URL、NEXTAUTH_URL如果啟用了認(rèn)證等核心變量缺失時(shí)直接拋出帶有具體變量名的錯(cuò)誤讓排查時(shí)間縮短到一分鐘以內(nèi)。5. t3code 的擴(kuò)展方向與我的個(gè)人體會(huì)5.1 從模板到業(yè)務(wù)腳手架還能往哪些方向長t3code 作為一套代碼實(shí)踐它的價(jià)值不止于“創(chuàng)造一個(gè)項(xiàng)目”更在于后續(xù)可以沿著多個(gè)方向延伸成完整的業(yè)務(wù)腳手架。第一個(gè)方向是接入文件上傳與對(duì)象存儲(chǔ)。目前大多數(shù) T3 項(xiàng)目在涉及文件上傳時(shí)都會(huì)臨時(shí)找方案有的用第三方存儲(chǔ) SDK有的用云函數(shù)直傳。如果把這部分抽象成統(tǒng)一的上傳模塊配合 Prisma 保存文件元數(shù)據(jù)就會(huì)省去很多重復(fù)勞動(dòng)。第二個(gè)方向是把權(quán)限模型做進(jìn) Router 中間件。tRPC 的中間件機(jī)制非常適合做 RBAC。你可以根據(jù)業(yè)務(wù)角色封裝出一套adminProcedure、editorProcedure把權(quán)限檢查從業(yè)務(wù)代碼里完全剝離出去。到這一步t3code 就從一個(gè)技術(shù)模板變成了貼合業(yè)務(wù)的開發(fā)框架。第三個(gè)方向是服務(wù)端渲染與 tRPC 的深度配合。t3code 的基礎(chǔ)演示大多集中在客戶端調(diào)用但在實(shí)際項(xiàng)目中很多頁面需要服務(wù)端直接取數(shù)首屏渲染或者利用 Next.js 的 Server Component 來做數(shù)據(jù)預(yù)取。tRPC 的服務(wù)端調(diào)用器和客戶端調(diào)用器可以在同一套類型體系下工作這意味著你在服務(wù)端可以直接調(diào)用喂給組件的預(yù)取數(shù)據(jù)不需要額外維護(hù)一套數(shù)據(jù)獲取方案。這塊做深之后整個(gè)應(yīng)用的響應(yīng)速度和首屏體驗(yàn)都會(huì)明顯提升。5.2 關(guān)于 t3code 的幾句實(shí)在話根據(jù)我個(gè)人的使用經(jīng)驗(yàn)t3code 這套技術(shù)組合并不適合所有場景。如果你的項(xiàng)目非常簡單只是一個(gè)展示頁加上一個(gè)聯(lián)系表單那完全沒有必要上 Prisma 和 tRPC直接用 Next.js 的 API Route 就夠了引入整條類型安全鏈路反而是負(fù)擔(dān)。如果你的項(xiàng)目業(yè)務(wù)邏輯復(fù)雜、接口數(shù)量多、團(tuán)隊(duì)協(xié)作頻繁那 t3code 帶來的類型安全收益會(huì)非常可觀。前后端類型統(tǒng)一之后接口聯(lián)調(diào)的時(shí)間會(huì)大幅壓縮很多運(yùn)行時(shí)的“字段不存在”“類型是 string 但實(shí)際是 number”這類問題會(huì)大幅減少。它不保證沒有 bug但確實(shí)能把一類特別難排查的集成 bug 在編譯期擋在門外。另外我想特別提一點(diǎn)t3code 這種模板的價(jià)值會(huì)隨著項(xiàng)目演進(jìn)逐漸上升。剛開始你可能不覺得類型穿透有多重要但當(dāng)項(xiàng)目到兩萬行代碼、幾十個(gè) Router、十幾個(gè)頁面模型時(shí)你會(huì)慶幸每一次數(shù)據(jù)結(jié)構(gòu)的改動(dòng)都有 TypeScript 替你兜底。那種“改一個(gè)字段所有引用點(diǎn)全部提示更新”的體驗(yàn)值得你為它多花點(diǎn)時(shí)間把基礎(chǔ)架構(gòu)搭穩(wěn)。最后再說一個(gè)小技巧如果你打算把 t3code 長期用在團(tuán)隊(duì)項(xiàng)目里一定要維護(hù)一份自定義的初始化文檔記錄你安裝依賴的版本、遇到過的問題、團(tuán)隊(duì)約定的目錄職責(zé)甚至可以把初始化腳本固化下來。模板的意義在于縮短啟動(dòng)時(shí)間而不是成為團(tuán)隊(duì)里人人都不敢碰的“黑盒”。把這些過程沉淀下來新成員進(jìn)入項(xiàng)目的成本會(huì)低很多整個(gè)團(tuán)隊(duì)的開發(fā)效率也會(huì)真正受益。 t3code全棧模板：用TypeScript實(shí)現(xiàn)前后端類型安全打通
前陣子我在梳理全棧項(xiàng)目模板時(shí)發(fā)現(xiàn)一個(gè)很有意思的現(xiàn)象很多人把 T3 Stack 掛在嘴邊但真正能把 Next.js、TypeScript、tRPC、Prisma、Tailwind 這套組合落成一個(gè)可復(fù)用、可擴(kuò)展的代碼體系的人其實(shí)并不多。t3code 這個(gè)名字乍一看只是個(gè)簡單的“代碼”集合但往深了挖它更像是一套以 TypeScript 為骨架、以類型安全為靈魂的全棧項(xiàng)目落地模板。它能解決的是開發(fā)團(tuán)隊(duì)在啟動(dòng)新項(xiàng)目時(shí)反復(fù)做重復(fù)選型、重復(fù)配環(huán)境、重復(fù)寫膠水代碼的問題也能幫助個(gè)人開發(fā)者從零快速搭出一個(gè)結(jié)構(gòu)清晰、前后端類型打通的應(yīng)用骨架。這篇文章不適合只想抄一段代碼就跑的人更適合真正想把全棧 TypeScript 項(xiàng)目做出“標(biāo)準(zhǔn)姿勢”的人。無論你是剛開始接觸 T3 相關(guān)技術(shù)棧還是已經(jīng)在用 Next.js 但總感覺前后端類型沒有打通都可以從這套代碼實(shí)踐中找到可以照搬的結(jié)構(gòu)和思路。我會(huì)直接把 t3code 在架構(gòu)選型、目錄組織、數(shù)據(jù)模型、接口封裝、前端接入、部署細(xì)節(jié)這幾個(gè)層面的實(shí)際做法拆開來講。1. t3code 在解決什么問題一套全棧 TypeScript 的“標(biāo)準(zhǔn)姿勢”1.1 從技術(shù)選型說起為什么是 Next.js tRPC Prisma很多人在搭新項(xiàng)目時(shí)第一個(gè)糾結(jié)的地方就是技術(shù)選型。前端用 React 沒問題但 Next.js 是不是過度設(shè)計(jì)后端接口用 REST 還是 GraphQL數(shù)據(jù)庫 ORM 用 Prisma 還是 Drizzle這些問題一旦在團(tuán)隊(duì)里展開基本就是一場沒完沒了的討論。t3code 的選擇邏輯非常直白如果整個(gè)應(yīng)用都用 TypeScript 寫那就讓類型從前端一路穿透到數(shù)據(jù)庫。Next.js 負(fù)責(zé)應(yīng)用框架和應(yīng)用路由既有 SSR 能力也可以純靜態(tài)導(dǎo)出團(tuán)隊(duì)可以根據(jù)場景分別使用 Server Component 和 Client Component。TypeScript 負(fù)責(zé)語言層面的類型約束從組件 props 到接口參數(shù)所有邊界都有類型定義。tRPC 負(fù)責(zé)前后端接口通信它的特點(diǎn)是不需要額外定義 REST 路由也不需要寫 GraphQL Schema直接利用 TypeScript 的類型推斷能力讓前端調(diào)用后端方法時(shí)獲得完整的自動(dòng)補(bǔ)全和類型校驗(yàn)。Prisma 負(fù)責(zé)數(shù)據(jù)模型定義和數(shù)據(jù)庫訪問schema 文件本身就是一份數(shù)據(jù)庫設(shè)計(jì)文檔同時(shí)生成的客戶端自帶類型。這四樣?xùn)|西放在一起等于把“前端組件、后端邏輯、數(shù)據(jù)模型”三層的類型全部串成一整條鏈。說白了你在前端寫const data await trpc.user.list.query()如果后端list方法沒寫編輯器直接就報(bào)紅了根本不用等運(yùn)行時(shí)接口報(bào) 404。1.2 T3 理念的核心類型安全不是口號(hào)是流程本身很多人會(huì)覺得類型安全就是“用了 TypeScript 而已”但 t3code 做的事情不止于此。它把類型安全延伸到了三個(gè)層面第一層是數(shù)據(jù)模型的類型安全。Prisma Schema 里定義了User、Post這些模型字段類型、關(guān)聯(lián)關(guān)系、索引都在這里確認(rèn)生成的 TypeScript 類型直接成為整個(gè)應(yīng)用的唯一事實(shí)來源。第二層是接口調(diào)用的類型安全。tRPC Router 的每個(gè) procedure 都帶有輸入輸出類型。你在前端寫調(diào)用時(shí)傳的參數(shù)類型不對(duì)會(huì)立刻報(bào)錯(cuò)返回的數(shù)據(jù)結(jié)構(gòu)也是自動(dòng)推斷出來的不需要手動(dòng)維護(hù)一份接口文檔。第三層是業(yè)務(wù)狀態(tài)的類型安全。React Query 配合 tRPC請(qǐng)求狀態(tài)、緩存 key、數(shù)據(jù)更新都能類型化。重新取數(shù)、失效緩存、樂觀更新這些操作不再是靠字符串約定而是靠類型系統(tǒng)約束。所以 t3code 的核心價(jià)值不是它用了多新的技術(shù)而是它把類型安全變成了整個(gè)開發(fā)流程的默認(rèn)行為。這就像你寫后端代碼時(shí)函數(shù)參數(shù)不寫類型會(huì)渾身難受一樣t3code 讓你在寫全棧代碼時(shí)體會(huì)一次“類型不到處傳心里就不踏實(shí)”的狀態(tài)。2. t3code 的結(jié)構(gòu)設(shè)計(jì)與代碼組織2.1 項(xiàng)目目錄與職責(zé)劃分t3code 的目錄結(jié)構(gòu)看起來并不復(fù)雜但每個(gè)目錄的職責(zé)邊界非常清晰。我基于常見實(shí)踐把它整理成下面這套劃分方式新項(xiàng)目直接照抄都可以├── prisma │ ├── schema.prisma # 數(shù)據(jù)模型的唯一事實(shí)來源 │ └── migrations # 數(shù)據(jù)庫遷移記錄 ├── src │ ├── server │ │ ├── api │ │ │ ├── routers # 按業(yè)務(wù)域拆分的 tRPC Router │ │ │ │ ├── user.ts │ │ │ │ └── post.ts │ │ │ └── root.ts # 所有子 Router 匯總到根 Router │ │ ├── auth.ts # 認(rèn)證相關(guān)邏輯如果啟用了鑒權(quán) │ │ └── db.ts # Prisma Client 單例 │ ├── pages # Next.js 頁面路由 │ │ ├── _app.tsx # 全局 Provider 掛載點(diǎn) │ │ └── index.tsx │ ├── components # 通用 UI 組件 │ ├── styles # Tailwind 入口文件 │ ├── utils # 工具函數(shù) │ └── trpc │ ├── client.ts # 前端 tRPC 客戶端配置 │ └── server.ts # SSR 時(shí)的 tRPC 調(diào)用輔助 └── .env # 環(huán)境變量這個(gè)結(jié)構(gòu)的核心思想是按職責(zé)分層不按文件類型亂堆。server 目錄只放后端相關(guān)代碼pages 目錄只負(fù)責(zé)路由入口components 目錄只放可復(fù)用 UI。真正業(yè)務(wù)相關(guān)的代碼比如查詢邏輯、數(shù)據(jù)轉(zhuǎn)換都收在 routers 和對(duì)應(yīng)的業(yè)務(wù)模塊里。2.2 最容易被忽略的配置細(xì)節(jié)目錄結(jié)構(gòu)誰都會(huì)列真正拉開差距的是配置細(xì)節(jié)。我見過不少項(xiàng)目從表面看結(jié)構(gòu)一樣但用起來就是各種不舒服問題基本都出在下面這幾個(gè)地方。路徑別名的統(tǒng)一。tsconfig.json 里配置server/*、/*這些路徑別名本身不難難的是讓 ESLint、Prettier、Jest 這些周邊工具都認(rèn)同一套路徑。t3code 的做法是在 tsconfig 和 tailwind.config 里都顯式聲明同樣的別名確保編輯器提示、構(gòu)建解析、測試環(huán)境三者行為一致。嚴(yán)格模式必須開滿。TypeScript 的strict: true只是底線。t3code 還會(huì)額外開啟noUncheckedIndexedAccess這意味著arr[0]不會(huì)自動(dòng)推斷為元素類型而是T | undefined。這個(gè)配置一開始會(huì)覺得煩但實(shí)際上會(huì)逼你把所有數(shù)組訪問的邊界都想清楚在寫業(yè)務(wù)代碼時(shí)特別能預(yù)防線上才出現(xiàn)的取不到值問題。環(huán)境變量的類型化。項(xiàng)目啟動(dòng)時(shí)如果DATABASE_URL沒設(shè)置Prisma 會(huì)報(bào)錯(cuò)但報(bào)錯(cuò)信息有時(shí)候不夠直觀。t3code 會(huì)做一個(gè)統(tǒng)一的環(huán)境變量校驗(yàn)?zāi)K啟動(dòng)前把所有必需變量一次性檢查完缺哪個(gè)就明確提示缺哪個(gè)而不是等數(shù)據(jù)庫連接超時(shí)之后才猜原因。依賴安裝順序。先裝運(yùn)行時(shí)依賴再裝開發(fā)依賴。因?yàn)?t3code 涉及 Next.js 的編譯、Prisma 的 generate、tRPC 的類型生成這幾個(gè)工具的安裝順序如果不一致在某些 Node 版本下會(huì)出現(xiàn)原生模塊編譯失敗或者 Prisma Engine 下載不完整。3. 從零搭建一次 t3code 全流程實(shí)操3.1 環(huán)境準(zhǔn)備與腳手架初始化如果你要復(fù)現(xiàn) t3code 這套代碼實(shí)踐建議直接從干凈的目錄開始。我假設(shè)你已經(jīng)裝好了 Node.js 18 LTS 以上版本的運(yùn)行環(huán)境并且本機(jī)有可用的包管理器。創(chuàng)建一個(gè)新項(xiàng)目時(shí)可以直接基于 create-t3-app 起步。執(zhí)行初始化命令之后交互式問答里重點(diǎn)確認(rèn)幾個(gè)選項(xiàng)是否啟用 Next.js App Router、是否啟用 tRPC、是否啟用 Prisma、是否啟用 Tailwind CSS。我的建議是全選啟用因?yàn)?t3code 的完整價(jià)值就是讓這四樣?xùn)|西協(xié)同工作去掉任何一樣類型安全鏈路都會(huì)出現(xiàn)斷點(diǎn)。完成初始化后第一件事不是寫業(yè)務(wù)代碼而是先跑一遍npm run dev確認(rèn)基礎(chǔ)頁面能正常打開。然后再改schema.prisma讓 Prisma 客戶端和后端類型生成到node_modules/.prisma與src/server/db.ts能正常聯(lián)動(dòng)。這里有一個(gè)非常關(guān)鍵的細(xì)節(jié)不要一上來就用最新版 Prisma除非你已經(jīng)確認(rèn)它與 Next.js 當(dāng)前版本兼容。我在實(shí)操中遇到的多數(shù)疑難問題都源于 Prisma 升級(jí)帶來的生成路徑變化。穩(wěn)妥做法是鎖定一個(gè)經(jīng)過驗(yàn)證的版本組合比如 Next.js 14 Prisma 5.x跑通整條鏈路后再考慮升級(jí)。3.2 數(shù)據(jù)模型設(shè)計(jì)用 Prisma 定義業(yè)務(wù)實(shí)體并生成客戶端數(shù)據(jù)模型設(shè)計(jì)是 t3code 里最需要提前想清楚的部分因?yàn)?Prisma Schema 一旦確定數(shù)據(jù)庫遷移和所有關(guān)聯(lián)類型都會(huì)跟著確定下來。以一個(gè)簡單的內(nèi)容發(fā)布系統(tǒng)為例我會(huì)在prisma/schema.prisma里定義出兩個(gè)相互關(guān)聯(lián)的模型generator client { provider prisma-client-js } datasource db { provider postgresql url env(DATABASE_URL) } model User { id String id default(cuid()) email String unique name String? posts Post[] 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 createdAt DateTime default(now()) updatedAt DateTime updatedAt }一切模型設(shè)計(jì)都圍繞“關(guān)系”展開。author和posts這兩個(gè)字段在數(shù)據(jù)庫層面對(duì)應(yīng)外鍵關(guān)系在 Prisma 層面對(duì)應(yīng)關(guān)聯(lián)查詢能力。當(dāng)你寫好這條 schema 后執(zhí)行npx prisma migrate dev --name initPrisma 會(huì)幫你生成遷移文件并同步數(shù)據(jù)庫結(jié)構(gòu)同時(shí)自動(dòng)重新生成客戶端代碼。我使用 Prisma 客戶端時(shí)習(xí)慣在同一文件里導(dǎo)出單例避免在開發(fā)環(huán)境下因?yàn)槟K熱更新創(chuàng)建多個(gè)連接實(shí)例import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma?: PrismaClient }; export const prisma globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV ! production) { globalForPrisma.prisma prisma; }這個(gè)單例模式雖然不是 Prisma 官方文檔開篇就講的內(nèi)容但在 Next.js 開發(fā)模式下幾乎屬于標(biāo)配不這樣做的話每次文件改動(dòng)熱更新都可能產(chǎn)生數(shù)據(jù)庫連接堆積。3.3 接口層封裝tRPC Router 的寫法與調(diào)用鏈數(shù)據(jù)模型就緒后接下來就是最容易寫出“樣板代碼”的部分接口層。tRPC 的 Router 并不等同于傳統(tǒng) REST 路由它更像是一個(gè)“可遠(yuǎn)程調(diào)用的函數(shù)集合”。每個(gè) procedure 就是一個(gè)可被前端調(diào)用的函數(shù)由輸入解析、權(quán)限檢查、業(yè)務(wù)邏輯三部分組成。我先建立一個(gè)基礎(chǔ) Router 工廠import { initTRPC } from trpc/server; import { z } from zod; const t initTRPC.context{ userId: string | null }().create(); export const router t.router; export const publicProcedure t.procedure; export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.userId) { throw new Error(Unauthorized); } return next({ ctx: { ...ctx, userId: ctx.userId } }); });這里有個(gè)關(guān)鍵點(diǎn)輸入校驗(yàn)用 zod而且是必選項(xiàng)。很多從 REST 轉(zhuǎn)過來的開發(fā)者會(huì)覺得 zod 是多余的因?yàn)?TypeScript 類型已經(jīng)定義了參數(shù)結(jié)構(gòu)。但運(yùn)行時(shí)輸入是不可信的TypeScript 類型在編譯后會(huì)消失zod 的作用就是接管運(yùn)行時(shí)校驗(yàn)。tRPC 和 zod 是官配procedure 的輸入一旦定義好前端調(diào)用時(shí)不僅自動(dòng)獲得類型推導(dǎo)錯(cuò)誤信息也會(huì)非常直觀。具體到業(yè)務(wù) Router我會(huì)這樣寫import { z } from zod; import { router, publicProcedure, protectedProcedure } from ../trpc; import { prisma } from ../db; export const postRouter router({ list: publicProcedure .input(z.object({ take: z.number().min(1).max(50).default(10) })) .query(async ({ input }) { return prisma.post.findMany({ take: input.take, orderBy: { createdAt: desc }, }); }), 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.userId, }, }); }), });接著在 root Router 里合并所有子 Routerimport { router } from ./trpc; import { postRouter } from ./routers/post; import { userRouter } from ./routers/user; export const appRouter router({ post: postRouter, user: userRouter, }); export type AppRouter typeof appRouter;上面這一步最重要的東西是export type AppRouter。這個(gè)類型導(dǎo)出之后前端可以基于它生成完整的類型安全的 tRPC 客戶端。整個(gè)調(diào)用鏈的銜接靠的就是這個(gè)類型定義。類型的穿透力有多強(qiáng)前端代碼里手寫trpc.post.create.mutate({ title: x, content: y })時(shí)title和content都是必填的參數(shù)類型錯(cuò)誤在保存文件的那一刻就會(huì)顯示出來。整個(gè)鏈路里只要有一層類型對(duì)不上編輯器就是一面紅色錯(cuò)誤墻這比任何接口文檔都來得可靠。3.4 前端頁面接入與樣式處理t3code 的前端接入核心工作就是把 tRPC 客戶端掛到 React 應(yīng)用上然后在組件里直接調(diào)用查詢方法。頁面入口_app.tsx要包一層 Providerimport { httpBatchLink } from trpc/client; import { QueryClient, QueryClientProvider } from tanstack/react-query; import { trpc } from ../utils/trpc; import type { AppProps } from next/app; const queryClient new QueryClient({ defaultOptions: { queries: { refetchOnWindowFocus: false, }, }, }); const trpcClient trpc.createClient({ links: [ httpBatchLink({ url: /api/trpc, }), ], }); export default function App({ Component, pageProps }: AppProps) { return ( trpc.Provider client{trpcClient} queryClient{queryClient} QueryClientProvider client{queryClient} Component {...pageProps} / /QueryClientProvider /trpc.Provider ); }實(shí)際業(yè)務(wù)組件里的寫法是import { trpc } from ../utils/trpc; export default function PostList() { const { data, isLoading } trpc.post.list.useQuery({ take: 10 }); if (isLoading) return div加載中.../div; return ( ul {data?.map((post) ( li key{post.id} h2{post.title}/h2 p{post.content}/p /li ))} /ul ); }注意看調(diào)用useQuery時(shí)傳入的({ take: 10 })是有類型檢查的data的每一項(xiàng)直接就是 Prisma 返回的Post類型。這里不需要手寫任何接口類型定義也不需要在前后端之間復(fù)制 DTO。狀態(tài)管理這部分用 React Query 處理緩存、重試、加載態(tài)都不需要自己造輪子。樣式方面Tailwind 主要負(fù)責(zé)原子類但 t3code 并不強(qiáng)制你用 Tailwind。實(shí)際用下來Tailwind 在快速搭建頁面時(shí)確實(shí)高效可一旦設(shè)計(jì)系統(tǒng)復(fù)雜到一定程度單獨(dú)抽離組件樣式反而更明智。所以我的建議是項(xiàng)目前期用 Tailwind 打通所有基礎(chǔ)樣式等出現(xiàn)重復(fù)性極高的樣式組合時(shí)再抽成組件類不用把每個(gè)頁面都寫成純?cè)宇惗询B。4. 實(shí)際踩過的坑t3code 常見問題與排查記錄這一部分是我最想寫的因?yàn)?t3code 這類全棧模板真正的門檻不是學(xué)會(huì)某個(gè)框架而是各種配置在真實(shí)開發(fā)環(huán)境里互相作用時(shí)的那些隱藏問題。我整理了一份速查表然后挑幾個(gè)最典型的展開講。問題現(xiàn)象根本原因處理方式啟動(dòng)時(shí)提示PrismaClientInitializationErrorDATABASE_URL未設(shè)置或格式不正確檢查.env文件和.env.example是否同步前端調(diào)用接口時(shí)類型不匹配tRPC 客戶端基于的AppRouter類型是舊版本重新跑一遍prisma generate和類型檢查確認(rèn)根組件導(dǎo)出類型已更新頁面顯示舊數(shù)據(jù)刷新后恢復(fù)客戶端 Query 緩存未失效在 mutation 成功回調(diào)里調(diào)用trpc.useUtils().post.list.invalidate()熱更新之后數(shù)據(jù)庫連接數(shù)暴漲Next.js dev 模式下創(chuàng)建了多個(gè) Prisma 實(shí)例使用全局單例模式復(fù)用 PrismaClientTailwind 類名沒有生效內(nèi)容路徑配置不全新目錄未被掃描在tailwind.config.ts中顯式添加./src/**/*.{ts,tsx}tRPC procedure 調(diào)用報(bào) 500但日志不詳細(xì)異常被 tRPC 默認(rèn)處理攔截開發(fā)環(huán)境開啟onError日志生產(chǎn)環(huán)境使用錯(cuò)誤格式化中間件4.1 Prisma 版本升級(jí)導(dǎo)致的生成異常這個(gè)問題我會(huì)放第一個(gè)說因?yàn)閹缀趺總€(gè)跑了一段時(shí)間的 t3code 項(xiàng)目都會(huì)遇到。某天執(zhí)行npm update后突然發(fā)現(xiàn)prisma generate生成的結(jié)果和舊版本不兼容數(shù)據(jù)庫訪問層報(bào)出一堆類型錯(cuò)誤或者 Prisma Client 報(bào)“The generated client has been modified”的提示。排查思路很簡單先看項(xiàng)目鎖定文件里 Prisma 和prisma/client的版本是否完全一致。這兩個(gè)包必須同步升級(jí)不能一個(gè)升一個(gè)不升。其次看 schema 文件是否有舊的生成器配置殘留。最后如果升級(jí)后實(shí)在找不到原因直接刪除node_modules、刪除生成的prisma/migrations中未提交的遷移記錄重新安裝并執(zhí)行prisma migrate dev基本都能恢復(fù)。4.2 tRPC 類型在跨包引用時(shí)丟失tRPC 在單一代碼庫里效果最好但如果你的項(xiàng)目一開始就設(shè)計(jì)成 monorepo或者把業(yè)務(wù)模塊抽成了多個(gè) npm 包類型穿透的鏈路就可能斷掉。我遇到過的典型情況是后端新增了一個(gè) procedure前端包里的AppRouter類型始終沒有同步更新不管怎么重新安裝依賴編輯器里都看不到新接口。這個(gè)問題在 t3code 里的標(biāo)準(zhǔn)解法是確保類型導(dǎo)出的路徑是純類型導(dǎo)出并且業(yè)務(wù)包之間的依賴方式使用 workspace 協(xié)議。如果前端包直接依賴后端包的構(gòu)建產(chǎn)物那么每次后端代碼變更后都要重新構(gòu)建一次否則類型就是舊的。使用 workspace 協(xié)議配合 TypeScript Project References可以讓類型在源文件層面直接關(guān)聯(lián)省掉構(gòu)建這一步。4.3 HMR 與路由緩存帶來的“看得到舊數(shù)據(jù)”Next.js 開發(fā)模式下熱更新有時(shí)會(huì)觸發(fā)頁面路由緩存導(dǎo)致你明明改了后端返回邏輯刷新頁面看到的還是舊數(shù)據(jù)。這種行為不一定是 tRPC 或 Prisma 的問題而是 React Query 的緩存策略在作祟。解決方案是在 mutation 成功后主動(dòng)失效相關(guān)查詢緩存。t3code 習(xí)慣在封裝的創(chuàng)建、更新、刪除操作里統(tǒng)一調(diào)用失效方法const utils trpc.useUtils(); const createPost trpc.post.create.useMutation({ onSuccess: () { utils.post.list.invalidate(); }, });這樣每次數(shù)據(jù)變更后列表都會(huì)自動(dòng)重新請(qǐng)求頁面展示的數(shù)據(jù)和數(shù)據(jù)庫狀態(tài)保持一致不需要手動(dòng)刷新。這個(gè)細(xì)節(jié)如果沒處理用戶會(huì)反復(fù)反饋“我提交了但看不到新內(nèi)容”特別影響體驗(yàn)。4.4 環(huán)境變量缺失引發(fā)的隱蔽報(bào)錯(cuò)環(huán)境變量相關(guān)的問題總是最隱蔽的因?yàn)楸镜亻_發(fā)時(shí).env存在一切正常一到部署或者新成員拉代碼時(shí)缺少必要變量報(bào)錯(cuò)五花八門。我見過最心累的一種是DATABASE_URL寫錯(cuò)但不是完全缺失導(dǎo)致 Prisma 能初始化但每次查詢都超時(shí)。t3code 的做法值得借鑒在服務(wù)端入口處統(tǒng)一校驗(yàn)環(huán)境變量而不是用到哪就在哪讀取。我會(huì)寫一個(gè)簡單的校驗(yàn)函數(shù)在應(yīng)用啟動(dòng)時(shí)檢查DATABASE_URL、NEXTAUTH_URL如果啟用了認(rèn)證等核心變量缺失時(shí)直接拋出帶有具體變量名的錯(cuò)誤讓排查時(shí)間縮短到一分鐘以內(nèi)。5. t3code 的擴(kuò)展方向與我的個(gè)人體會(huì)5.1 從模板到業(yè)務(wù)腳手架還能往哪些方向長t3code 作為一套代碼實(shí)踐它的價(jià)值不止于“創(chuàng)造一個(gè)項(xiàng)目”更在于后續(xù)可以沿著多個(gè)方向延伸成完整的業(yè)務(wù)腳手架。第一個(gè)方向是接入文件上傳與對(duì)象存儲(chǔ)。目前大多數(shù) T3 項(xiàng)目在涉及文件上傳時(shí)都會(huì)臨時(shí)找方案有的用第三方存儲(chǔ) SDK有的用云函數(shù)直傳。如果把這部分抽象成統(tǒng)一的上傳模塊配合 Prisma 保存文件元數(shù)據(jù)就會(huì)省去很多重復(fù)勞動(dòng)。第二個(gè)方向是把權(quán)限模型做進(jìn) Router 中間件。tRPC 的中間件機(jī)制非常適合做 RBAC。你可以根據(jù)業(yè)務(wù)角色封裝出一套adminProcedure、editorProcedure把權(quán)限檢查從業(yè)務(wù)代碼里完全剝離出去。到這一步t3code 就從一個(gè)技術(shù)模板變成了貼合業(yè)務(wù)的開發(fā)框架。第三個(gè)方向是服務(wù)端渲染與 tRPC 的深度配合。t3code 的基礎(chǔ)演示大多集中在客戶端調(diào)用但在實(shí)際項(xiàng)目中很多頁面需要服務(wù)端直接取數(shù)首屏渲染或者利用 Next.js 的 Server Component 來做數(shù)據(jù)預(yù)取。tRPC 的服務(wù)端調(diào)用器和客戶端調(diào)用器可以在同一套類型體系下工作這意味著你在服務(wù)端可以直接調(diào)用喂給組件的預(yù)取數(shù)據(jù)不需要額外維護(hù)一套數(shù)據(jù)獲取方案。這塊做深之后整個(gè)應(yīng)用的響應(yīng)速度和首屏體驗(yàn)都會(huì)明顯提升。5.2 關(guān)于 t3code 的幾句實(shí)在話根據(jù)我個(gè)人的使用經(jīng)驗(yàn)t3code 這套技術(shù)組合并不適合所有場景。如果你的項(xiàng)目非常簡單只是一個(gè)展示頁加上一個(gè)聯(lián)系表單那完全沒有必要上 Prisma 和 tRPC直接用 Next.js 的 API Route 就夠了引入整條類型安全鏈路反而是負(fù)擔(dān)。如果你的項(xiàng)目業(yè)務(wù)邏輯復(fù)雜、接口數(shù)量多、團(tuán)隊(duì)協(xié)作頻繁那 t3code 帶來的類型安全收益會(huì)非常可觀。前后端類型統(tǒng)一之后接口聯(lián)調(diào)的時(shí)間會(huì)大幅壓縮很多運(yùn)行時(shí)的“字段不存在”“類型是 string 但實(shí)際是 number”這類問題會(huì)大幅減少。它不保證沒有 bug但確實(shí)能把一類特別難排查的集成 bug 在編譯期擋在門外。另外我想特別提一點(diǎn)t3code 這種模板的價(jià)值會(huì)隨著項(xiàng)目演進(jìn)逐漸上升。剛開始你可能不覺得類型穿透有多重要但當(dāng)項(xiàng)目到兩萬行代碼、幾十個(gè) Router、十幾個(gè)頁面模型時(shí)你會(huì)慶幸每一次數(shù)據(jù)結(jié)構(gòu)的改動(dòng)都有 TypeScript 替你兜底。那種“改一個(gè)字段所有引用點(diǎn)全部提示更新”的體驗(yàn)值得你為它多花點(diǎn)時(shí)間把基礎(chǔ)架構(gòu)搭穩(wěn)。最后再說一個(gè)小技巧如果你打算把 t3code 長期用在團(tuán)隊(duì)項(xiàng)目里一定要維護(hù)一份自定義的初始化文檔記錄你安裝依賴的版本、遇到過的問題、團(tuán)隊(duì)約定的目錄職責(zé)甚至可以把初始化腳本固化下來。模板的意義在于縮短啟動(dòng)時(shí)間而不是成為團(tuán)隊(duì)里人人都不敢碰的“黑盒”。把這些過程沉淀下來新成員進(jìn)入項(xiàng)目的成本會(huì)低很多整個(gè)團(tuán)隊(duì)的開發(fā)效率也會(huì)真正受益。