目實(shí)戰(zhàn)：Next.js、TypeScript與tRPC打造類型安全的應(yīng)用底座)
第一次見(jiàn)到t3code這個(gè)名字時(shí)我以為又是一個(gè)趕時(shí)髦的縮寫組合。真正把整套代碼跑起來(lái)之后我才意識(shí)到它的價(jià)值不在某個(gè)單一框架而在于把現(xiàn)代全棧項(xiàng)目里最麻煩的“類型銜接”和“配置整合”一次性做完了。簡(jiǎn)單說(shuō)t3code是一套基于 T3 技術(shù)棧的全棧項(xiàng)目底座核心組合是 Next.js TypeScript Tailwind CSS tRPC Prisma。它解決的問(wèn)題非常具體前端調(diào)用接口不再靠猜后端改完字段前端立刻報(bào)錯(cuò)提醒數(shù)據(jù)庫(kù)模型定義完類型能自動(dòng)貫穿到頁(yè)面組件和 API 層再加上 Tailwind 處理樣式幾乎不用在 CSS 文件之間反復(fù)跳轉(zhuǎn)。這套組合適合前端想轉(zhuǎn)全棧的開發(fā)者、獨(dú)立開發(fā)者做小產(chǎn)品原型也適合三五個(gè)人的小團(tuán)隊(duì)統(tǒng)一技術(shù)底座。我后面所有內(nèi)容都會(huì)基于這個(gè)項(xiàng)目模板來(lái)拆解盡量把每一步為什么這么做都講清楚。1. 項(xiàng)目定位t3code 到底解決了什么問(wèn)題1.1 全棧開發(fā)最常見(jiàn)的兩種痛配置地獄和類型撕裂我先說(shuō)一個(gè)很多團(tuán)隊(duì)從前后端分離轉(zhuǎn)到全棧時(shí)的真實(shí)感受。傳統(tǒng)做法是前端 React 一個(gè)倉(cāng)庫(kù)后端 Express 一個(gè)倉(cāng)庫(kù)兩邊各有一套接口文檔。前端定義 request 類型后端定義 response 類型中間靠 Postman 或者 Swagger 同步。業(yè)務(wù)一復(fù)雜前端改了一個(gè)字段名后端還在用舊字段直到線上報(bào)錯(cuò)才被發(fā)現(xiàn)。這個(gè)問(wèn)題的本質(zhì)不是“寫錯(cuò)代碼”而是“類型沒(méi)有在編譯期打通”。t3code解決的就是這個(gè)痛點(diǎn)。它強(qiáng)制你用一套 TypeScript 類型貫穿整個(gè)鏈路Prisma 根據(jù)數(shù)據(jù)庫(kù) schema 生成類型tRPC 復(fù)用這些類型生成 API 調(diào)用函數(shù)前端組件里直接useQuery就能拿到帶類型推斷的返回值。改數(shù)據(jù)庫(kù)字段遷移之后跑一遍prisma generate所有引用點(diǎn)一起報(bào)錯(cuò)IDE 里就能把所有關(guān)聯(lián)位置找出來(lái)。這比任何運(yùn)行時(shí)監(jiān)控都更早地規(guī)避問(wèn)題。另一個(gè)痛點(diǎn)更常見(jiàn)配置地獄。Next.js 項(xiàng)目要配 webpack、babel、tsconfig、并處理 API 路由和靜態(tài)資源加上 Prisma 要管數(shù)據(jù)庫(kù)連接和遷移加上 Tailwind 要配 content 路徑和主題再加鑒權(quán)、環(huán)境變量一個(gè)項(xiàng)目半天起不來(lái)是常態(tài)。t3code本質(zhì)上是把這些配置預(yù)先收斂成一套經(jīng)過(guò)驗(yàn)證的默認(rèn)值你不需要理解每一層怎么協(xié)同也能先跑起來(lái)等業(yè)務(wù)深入后再按需修改。1.2 什么場(chǎng)景適合用它什么場(chǎng)景最好繞開我用了大半年t3code之后對(duì)它的適用范圍有了比較明確的判斷。如果你做的事情是獨(dú)立開發(fā)一個(gè) SaaS 工具、企業(yè)內(nèi)部系統(tǒng)、數(shù)據(jù)看板、內(nèi)容后臺(tái)或者你是幾個(gè)人協(xié)作的小團(tuán)隊(duì)想在第一周就見(jiàn)到能跑的完整業(yè)務(wù)閉環(huán)那這套組合非常合適。它把最常見(jiàn)的“用戶登錄 - 數(shù)據(jù)寫入 - 列表展示 - 權(quán)限控制”鏈路做成了開箱狀態(tài)你只需要往里面填業(yè)務(wù)表結(jié)構(gòu)。反過(guò)來(lái)如果你的場(chǎng)景是已經(jīng)有龐大的遺留數(shù)據(jù)庫(kù)和成熟的 REST/GraphQL 服務(wù)或者團(tuán)隊(duì)前端、后端是兩撥人后端要用 Java/Go 獨(dú)立維護(hù)那就不需要強(qiáng)行套t3code。它更適合那些自己掌握全流程、希望減少溝通損耗的人。還有個(gè)容易忽略的場(chǎng)景做外包或接私活。給甲方做后臺(tái)管理項(xiàng)目時(shí)最怕的就是需求反復(fù)改字段。用t3code的打通式類型系統(tǒng)甲方要求給用戶表加一個(gè)phone字段你改完 schema 生成遷移前端引用user.phone的地方對(duì)照編譯錯(cuò)誤全部改掉半小時(shí)內(nèi)就能改完交付。2. 技術(shù)選型拆解為什么 t3code 按下的是“確定性優(yōu)先”2.1 Next.js 作為全棧入口關(guān)鍵是心智統(tǒng)一t3code沒(méi)有選擇把前端打包成純靜態(tài)站點(diǎn)也沒(méi)有選擇 Express 單獨(dú)開后端端口而是把整個(gè)應(yīng)用放在 Next.js 里。很多人覺(jué)得 Next.js 只是 React 的服務(wù)端渲染框架其實(shí)它同時(shí)承擔(dān)了頁(yè)面路由、API 路由、服務(wù)端數(shù)據(jù)獲取三層職責(zé)。在t3code里頁(yè)面文件和 API 路由都在同一個(gè)應(yīng)用進(jìn)程內(nèi)數(shù)據(jù)庫(kù)調(diào)用發(fā)生在服務(wù)端瀏覽器拿到的是渲染完成的 HTML。這樣做的最大好處是心智統(tǒng)一我不需要維護(hù)兩個(gè)項(xiàng)目、兩套部署流程、兩套日志。尤其做個(gè)人項(xiàng)目時(shí)一個(gè)項(xiàng)目目錄、一條啟動(dòng)命令、一份環(huán)境變量就能把完整系統(tǒng)跑起來(lái)。再說(shuō)服務(wù)端渲染的收益。后臺(tái)管理類頁(yè)面往往有首屏數(shù)據(jù)加載需求。傳統(tǒng)前端做法是頁(yè)面加載后發(fā)出 fetch 請(qǐng)求 → 顯示 loading → 數(shù)據(jù)返回 → 重新渲染。t3code的頁(yè)面可以直接在服務(wù)端調(diào)用 tRPC 查詢把數(shù)據(jù)作為當(dāng)前頁(yè)面的 props 傳給組件首屏 HTML 里就帶真實(shí)數(shù)據(jù)。用戶感知是秒開搜索引擎也能讀到內(nèi)容這對(duì)內(nèi)容型產(chǎn)品有實(shí)際價(jià)值。2.2 tRPC 讓 API 調(diào)用像函數(shù)調(diào)用一樣安全t3code里最顛覆使用習(xí)慣的是 tRPC。它不是一個(gè)傳統(tǒng)框架而是一種“沒(méi)有 API 的 API 方案”。你不需要手寫 URL、method、請(qǐng)求體字段只需要在服務(wù)端定義一個(gè) router在前端 import 同一個(gè)函數(shù)引用調(diào)用方式就是api.post.list.useQuery(...)。為什么能做到類型安全因?yàn)?tRPC 的 schema 由 zod 定義zod 對(duì)象既是運(yùn)行時(shí)校驗(yàn)器又是靜態(tài)類型來(lái)源。比如我定義list的輸入是{ limit: number }那么在客戶端調(diào)用時(shí)如果傳了一個(gè)字符串limitTypeScript 編譯期就會(huì)直接報(bào)錯(cuò)。如果服務(wù)端查詢返回的字段和前端使用的字段不一致同樣在編譯期報(bào)錯(cuò)。很多不熟悉的人會(huì)擔(dān)心tRPC 是不是只適合小項(xiàng)目我的看法是只要你的系統(tǒng)前端和服務(wù)端共享 TypeScript 代碼庫(kù)它就完全夠用。大型系統(tǒng)里如果有什么模塊必須獨(dú)立部署你仍可以把 tRPC router 暴露為 HTTP 服務(wù)其他語(yǔ)言系統(tǒng)走標(biāo)準(zhǔn) JSON 接口即可。至少在t3code這種模板存在的時(shí)間里它的維護(hù)價(jià)值遠(yuǎn)大于傳統(tǒng)接口聯(lián)調(diào)。2.3 Prisma 把數(shù)據(jù)庫(kù)模型變成類型“源頭”t3code的數(shù)據(jù)層選型是 Prisma。它的核心優(yōu)勢(shì)有三個(gè)schema 可讀性好、遷移文件可審查、類型自動(dòng)生成。Prisma schema 不像 TypeORM 那樣用裝飾器寫死在實(shí)體類里而是一個(gè)獨(dú)立的schema.prisma文件。你在這個(gè)文件里定義表和關(guān)系執(zhí)行prisma migrate生成 SQL 遷移文件再執(zhí)行prisma generate生成客戶端代碼。這個(gè)客戶端代碼內(nèi)置了所有類型你的db.post.findMany()返回結(jié)果會(huì)被 TypeScript 推導(dǎo)成Post[]而且Post類型包含你定義的所有字段。用 Prisma 還有一個(gè)對(duì)新手很友好的地方錯(cuò)誤提示相對(duì)清晰。字段名寫錯(cuò)、關(guān)系沒(méi)有定義遷移階段就會(huì)報(bào)出來(lái)。對(duì)比直接寫 SQL 的 mybatis 風(fēng)格排查成本會(huì)低很多。t3code把 Prisma 和 tRPC 放在一起后數(shù)據(jù)庫(kù)的列名就是前端接口返回字段的“唯一事實(shí)來(lái)源”徹底消滅了手寫 DTO 和 VO 的重復(fù)勞動(dòng)。2.4 Tailwind CSS 并不只是樣式方案更是一種設(shè)計(jì)約束t3code引入 Tailwind CSS表面上看是“原子化 CSS 更省事”但我用下來(lái)發(fā)現(xiàn)它的真正價(jià)值是“避免樣式命名災(zāi)難”。傳統(tǒng)方式是每個(gè)組件一個(gè).module.css或者在styles目錄里定義 BEM 類名。項(xiàng)目一大類名沖突和優(yōu)先級(jí)問(wèn)題就開始出現(xiàn)。Tailwind 的做法是直接在 JSX 里寫flex items-center justify-between這類工具類沒(méi)有“樣式文件與組件文件對(duì)應(yīng)查找”的思維負(fù)擔(dān)。當(dāng)然原子類的代價(jià)是 JSX 會(huì)變長(zhǎng)有些人覺(jué)得“模板里塞太多類名不夠干凈”。我的折中方案是把復(fù)雜的顏色和間距抽象成組件組件內(nèi)部接受 className 覆蓋頁(yè)面層保持語(yǔ)義化命名和 Tailwind 工具類并存。t3code默認(rèn)配置里也支持這個(gè)做法你不需要被“純工具類”教條綁架按團(tuán)隊(duì)習(xí)慣調(diào)整即可。2.5 這幾層到底是怎么配合的會(huì)不會(huì)打架我聽(tīng)到過(guò)一種質(zhì)疑Next.js、tRPC、Prisma、Tailwind 都是獨(dú)立發(fā)展階段很強(qiáng)的工具硬放一起會(huì)不會(huì)互相牽制實(shí)際上它們的分工非常清晰。Prisma 管數(shù)據(jù)庫(kù)層產(chǎn)出類型和查詢客戶端tRPC 管 API 層讀取 Prisma 客戶端并按 zod 規(guī)則校驗(yàn)入?yún)ext.js 管路由和渲染層在服務(wù)端組件里調(diào)用 tRPC 查詢?cè)诳蛻舳私M件里通過(guò) hooks 觸發(fā)修改Tailwind 只負(fù)責(zé)樣式表達(dá)不摻和任何數(shù)據(jù)流。每一層只做一件事交給下一層的產(chǎn)物是強(qiáng)類型數(shù)據(jù)或 UI 描述沒(méi)有循環(huán)依賴。真正的風(fēng)險(xiǎn)點(diǎn)其實(shí)是版本升級(jí)節(jié)奏。Next.js 每年有大版本更新tRPC 也有自己的迭代不能盲目更新要先看官方升級(jí)文檔確認(rèn)兼容性。t3code的價(jià)值也在于它是一個(gè)可復(fù)現(xiàn)的“穩(wěn)定組合版本”你照著一份代碼模板維護(hù)不會(huì)出現(xiàn)“按網(wǎng)上教程裝完所有依賴但起不來(lái)”的情況。3. 從零初始化 t3code腳手架命令和目錄設(shè)計(jì)3.1 一條命令生成可運(yùn)行項(xiàng)目t3code的起點(diǎn)是官方腳手架 create-t3-app。我通常會(huì)先確認(rèn) Node.js 版本在 18 以上然后執(zhí)行npx create-t3-applatest t3code創(chuàng)建過(guò)程中會(huì)讓你選擇需要的模塊Next.js、TypeScript、Tailwind CSS、tRPC、Prisma、NextAuth.js。如果做的是一個(gè)需要登錄的后臺(tái)系統(tǒng)我會(huì)把 NextAuth.js 也勾上一次性把 session 機(jī)制和數(shù)據(jù)庫(kù)用戶表組件配好。還要注意選擇“是否使用 import alias”。強(qiáng)烈建議選/*這樣代碼里的相對(duì)路徑引用會(huì)明顯更好維護(hù)。初始化完成后直接執(zhí)行npm run dev打開本地 3000 端口看到的應(yīng)該是一個(gè)帶導(dǎo)航欄的首頁(yè)。這一步相當(dāng)于驗(yàn)證了“基礎(chǔ)配置能跑通”后面改造業(yè)務(wù)是在一套已驗(yàn)證的建筑骨架上裝修而不是空地起樓。3.2 目錄結(jié)構(gòu)如何暗示數(shù)據(jù)流我實(shí)際初始化出來(lái)并整理過(guò)的t3code目錄結(jié)構(gòu)大致是t3code/ ├─ app/ │ ├─ (auth)/ │ ├─ dashboard/ │ ├─ layout.tsx │ ├─ page.tsx │ └─ api/trpc/[trpc]/route.ts ├─ prisma/ │ ├─ schema.prisma │ └─ migrations/ ├─ server/ │ ├─ api/ │ │ ├─ root.ts │ │ ├─ trpc.ts │ │ └─ routers/ │ ├─ auth.ts │ └─ db.ts ├─ styles/ │ └─ globals.css ├─ .env.example ├─ next.config.js ├─ tailwind.config.ts └─ tsconfig.json這個(gè)結(jié)構(gòu)最需要理解的是app和server的邊界。app/api/trpc/[trpc]/route.ts是 Next.js 暴露 HTTP 端點(diǎn)的唯一入口它把 tRPC router 轉(zhuǎn)成處理請(qǐng)求的標(biāo)準(zhǔn)路由。寫業(yè)務(wù)的時(shí)候你很少需要改這個(gè)文件。server/api/routers才是寫業(yè)務(wù)的地方每個(gè)業(yè)務(wù)域一個(gè)文件比如post.ts、user.ts最后在root.ts里合并成 appRouter。這樣當(dāng)你打開一個(gè)路由文件能一眼看到這個(gè)域提供了哪些查詢和變更操作。server/db.ts是 PrismaClient 單例的導(dǎo)出位置。這里有個(gè)常見(jiàn)坑如果在多個(gè)文件里分別new PrismaClient()開發(fā)環(huán)境下會(huì)創(chuàng)建過(guò)多數(shù)據(jù)庫(kù)連接熱更新時(shí)尤其容易卡死。t3code默認(rèn)生成代碼里已經(jīng)用全局變量緩存了 client我建議保留這個(gè)寫法。3.3 關(guān)鍵配置文件里藏著的幾個(gè)細(xì)節(jié)先看.env.example。它至少包含這些變量DATABASE_URLmysql://user:passwordlocalhost:3306/t3code NEXTAUTH_SECRETyour-secret NEXTAUTH_URLhttp://localhost:3000實(shí)際開發(fā)時(shí)我會(huì)把.env.example作為環(huán)境變量清單真正敏感的密鑰放在.env.local里并確認(rèn) .gitignore 忽略了它。很多團(tuán)隊(duì)數(shù)據(jù)庫(kù)密鑰被提交到倉(cāng)庫(kù)事故就是這么來(lái)的。再看next.config.js它通常不需要大動(dòng)。需要知道的是transpilePackages選項(xiàng)如果將來(lái)你開發(fā)了本地 npm 包想復(fù)用需要把包名加進(jìn)去否則 Next.js 不會(huì)編譯 node_modules 里那些未編譯的 TS 代碼。最后是tsconfig.json里的baseUrl和paths。t3code默認(rèn)把./server/*指向源碼目錄。這個(gè)配置直接影響你在業(yè)務(wù)代碼里import { db } from ~/server/db能否被正確解析。遇到“模塊找不到”的錯(cuò)誤第一反應(yīng)不是去安裝包而是檢查 paths 配置和文件名大小寫。4. 核心業(yè)務(wù)閉環(huán)用戶、文章、儀表盤4.1 Prisma schema 設(shè)計(jì)與首次遷移只有腳手架沒(méi)有業(yè)務(wù)模板是沒(méi)有意義的。我來(lái)演示t3code里最常見(jiàn)的閉環(huán)用戶發(fā)表文章首頁(yè)展示文章列表后臺(tái)顯示統(tǒng)計(jì)數(shù)字。先定義 Prisma modelmodel User { id String id default(cuid()) email String unique name String? posts Post[] createdAt DateTime default(now()) } model Post { id String id default(cuid()) title String content String author User relation(fields: [authorId], references: [id]) authorId String createdAt DateTime default(now()) }設(shè)計(jì)上有兩點(diǎn)值得說(shuō)明。第一主鍵用cuid()而不是自增數(shù)字好處是分布式環(huán)境下不會(huì)撞號(hào)也避免讓別人猜測(cè)業(yè)務(wù)總量。第二authorId的命名要和關(guān)系字段對(duì)應(yīng)Prisma 才能正確識(shí)別多對(duì)一關(guān)系。寫完后執(zhí)行npx prisma migrate dev --name init這條命令會(huì)創(chuàng)建數(shù)據(jù)庫(kù)表并生成遷移文件。遷移文件是文本形式應(yīng)該提交到代碼倉(cāng)庫(kù)這樣團(tuán)隊(duì)成員prisma migrate deploy就能同步表結(jié)構(gòu)。4.2 tRPC Router 編寫規(guī)范接下來(lái)在server/api/routers/post.ts里定義文章查詢接口import { z } from zod; import { createTRPCRouter, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ list: publicProcedure .input( z.object({ limit: z.number().min(1).max(50).default(10), }) ) .query(async ({ ctx, input }) { return ctx.db.post.findMany({ take: input.limit, orderBy: { createdAt: desc }, include: { author: { select: { name: true }, }, }, }); }), });這里最有意思的是input和output的類型都由 zod 推導(dǎo)?？蛻舳苏{(diào)用時(shí)limit的類型、是否必須、取值范圍全部被 TypeScript 感知。如果某天你在前端調(diào)用了limit: 100編譯期就會(huì)被攔截而不是等到請(qǐng)求發(fā)起后后端報(bào) 400。我再擴(kuò)展一個(gè)創(chuàng)建文章的 mutationcreate: publicProcedure .input( z.object({ title: z.string().min(1, 標(biāo)題不能為空), content: z.string().min(1), authorId: z.string().cuid(), }) ) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: input.authorId, }, }); }),寫好的 router 要在 root.ts 里合并export const appRouter createTRPCRouter({ post: postRouter, user: userRouter, });導(dǎo)出的appRouter就是整個(gè)前端的類型來(lái)源。核心習(xí)慣是每個(gè)業(yè)務(wù)域一個(gè) router 文件不要在 root.ts 里堆業(yè)務(wù)代碼否則后期幾百行混在一起類型還能通但人已經(jīng)瘋了。4.3 頁(yè)面數(shù)據(jù)接入類型安全第一次體現(xiàn)前端頁(yè)面在app/dashboard/page.tsx里使用服務(wù)端組件方式調(diào)用import { api } from ~/server/api/root; import { db } from ~/server/db; export default async function DashboardPage() { const posts await db.post.findMany({ orderBy: { createdAt: desc }, take: 10, }); const total await db.post.count(); return ( main classNamep-6 h1 classNametext-2xl font-bold儀表盤/h1 p文章總數(shù){total}/p ul {posts.map((post) ( li key{post.id}{post.title}/li ))} /ul /main ); }這段代碼里沒(méi)有 fetch、沒(méi)有 URL、沒(méi)有 any 類型。posts的類型完全來(lái)自 Prisma 的findMany返回值。如果改天Post表加了status字段前端直接寫post.status就能拿到新字段不需要額外定義接口。對(duì)于需要?jiǎng)討B(tài)交互的客戶端組件就用 tRPC hooksuse client; import { api } from ~/server/api/react; export function PostList() { const { data, isLoading } api.post.list.useQuery({ limit: 10 }); if (isLoading) return p加載中.../p; return ( ul {data?.map((post) ( li key{post.id}{post.title} - {post.author.name}/li ))} /ul ); }api.post.list.useQuery的參數(shù)類型、返回類型全部從服務(wù)端 router 自動(dòng)推導(dǎo)。這就是t3code的核心體驗(yàn)寫完 router前端不需要再看接口文檔。4.4 服務(wù)端渲染和客戶端渲染該怎么選很多新手會(huì)把所有頁(yè)面都寫成客戶端組件然后抱怨首屏慢。我的判斷標(biāo)準(zhǔn)很簡(jiǎn)單頁(yè)面內(nèi)容如果和用戶會(huì)話狀態(tài)無(wú)關(guān)就優(yōu)先用服務(wù)端組件直接查庫(kù)頁(yè)面內(nèi)容如果完全依賴客戶端交互比如搜索框、表單實(shí)時(shí)校驗(yàn)、彈窗就用帶use client的組件。t3code里還有一個(gè)常用中間態(tài)在服務(wù)端組件里先取數(shù)據(jù)傳給客戶端組件客戶端組件只負(fù)責(zé)交互。比如文章列表的篩選按鈕可以把初始列表作為 props 傳入后續(xù)篩選在客戶端繼續(xù)調(diào)用useQuery。這樣首屏不閃爍交互又流暢。5. 實(shí)際運(yùn)行中的那些坑我踩過(guò)的都寫在下面5.1 tRPC 返回 Date 對(duì)象時(shí)的序列化邊界tRPC 默認(rèn)會(huì)把Date對(duì)象序列化成 ISO 字符串所以 Prisma 查詢返回的createdAt到了前端就成了字符串。如果你寫的組件直接用new Date(post.createdAt)沒(méi)問(wèn)題如果你用比較兩個(gè)時(shí)間就會(huì)出現(xiàn)類型對(duì)不上。我的處理習(xí)慣是在 Prisma schema 里把日期類型保持為DateTime在展示層明確轉(zhuǎn)成toLocaleString()。不建議為了省事把數(shù)據(jù)庫(kù)字段降級(jí)成字符串因?yàn)榕判?、時(shí)區(qū)計(jì)算都會(huì)變成噩夢(mèng)。5.2 Tailwind 動(dòng)態(tài)拼接類名失效這是所有 Tailwind 用戶都會(huì)踩的坑。在 JSX 里寫${condition ? text-red-500 : text-gray-500}時(shí)類名是完整字符串能生效。但如果寫成className{text-${color}-500}, Tailwind 的靜態(tài)掃描就找不到text-red-500這個(gè)類編譯產(chǎn)物里不會(huì)有對(duì)應(yīng)樣式。t3code項(xiàng)目里我的規(guī)避方法很簡(jiǎn)單要么使用完整的類名字符串要么在tailwind.config.ts的 safelist 里聲明需要?jiǎng)討B(tài)生成的類名組合。前者優(yōu)先因?yàn)檎Z(yǔ)義更清晰。5.3 Prisma 連接數(shù)打滿與冷啟動(dòng)超時(shí)本地開發(fā)時(shí)熱更新會(huì)頻繁重建 PrismaClient如果不做全局緩存連接數(shù)會(huì)漲得很快。t3code默認(rèn)的db.ts通常已經(jīng)包含這段邏輯import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma: PrismaClient | undefined; }; export const db globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV ! production) globalForPrisma.prisma db;這段代碼的建議保留。另一個(gè)問(wèn)題出現(xiàn)在 serverless 環(huán)境每次冷啟動(dòng)建立數(shù)據(jù)庫(kù)連接會(huì)增加幾百毫秒延遲。如果預(yù)算允許給 Prisma 加連接池配置比較穩(wěn)妥。連接池連接字符串通常是DATABASE_URL的 URL 參數(shù)加上?connection_limit5這樣的配置具體參數(shù)要看托管平臺(tái)文檔。5.4 環(huán)境變量混淆和密鑰泄漏t3code的.env.example里寫著 NEXTAUTH_SECRET。如果你不做登錄功能這個(gè)變量無(wú)所謂一旦啟用 NextAuth.js沒(méi)有正確的 secret很多會(huì)話邏輯會(huì)隨機(jī)失敗。另一個(gè)常見(jiàn)錯(cuò)誤是服務(wù)端代碼里寫了process.env.DATABASE_URL卻在客戶端組件里訪問(wèn)。Next.js 默認(rèn)會(huì)把沒(méi)有NEXT_PUBLIC_前綴的變量只暴露給服務(wù)端客戶端引用到的值是undefined導(dǎo)致線上故障但本地模擬不出來(lái)。排查這類問(wèn)題的順序是先在頁(yè)面服務(wù)端打印變量存不存在再確認(rèn)客戶端訪問(wèn)的環(huán)境變量名是否有NEXT_PUBLIC_前綴。6. 部署上線與日常維護(hù)要點(diǎn)6.1 構(gòu)建打包和數(shù)據(jù)庫(kù)遷移的順序t3code部署時(shí)最容易翻車的場(chǎng)景是代碼先發(fā)布數(shù)據(jù)庫(kù)遷移還沒(méi)跑前端查新字段直接報(bào)錯(cuò)。正確順序是先執(zhí)行數(shù)據(jù)庫(kù)遷移再部署應(yīng)用代碼或者在同一部署流程里先 migrate 再 build。我在 CI 里的腳本一般是npx prisma migrate deploy npx prisma generate npm run buildmigrate deploy只執(zhí)行未執(zhí)行過(guò)的遷移文件不會(huì)像migrate dev那樣要求你輸入名稱或重新生成遷移。正式環(huán)境永遠(yuǎn)只跑 deploy。prisma generate確保新的客戶端類型被打進(jìn)構(gòu)建產(chǎn)物。最后再跑next build這樣頁(yè)面里用到的字段和數(shù)據(jù)庫(kù)實(shí)際結(jié)構(gòu)是一致的。6.2 認(rèn)證、文件上傳、監(jiān)控這些擴(kuò)展方向t3code模板本身更像地板和承重墻居住體驗(yàn)取決于你如何擴(kuò)展。如果你需要登錄把 NextAuth.js 的 provider 配置填好數(shù)據(jù)庫(kù)里加Account、Session模型Prisma migrate 后就能用。文件上傳建議獨(dú)立走對(duì)象存儲(chǔ)不要把文件放進(jìn)數(shù)據(jù)庫(kù)在本地開發(fā)時(shí)可以用localStorage目錄線上換成 OSS/S3。監(jiān)控維度上我最推薦先接日志其次接錯(cuò)誤上報(bào)。t3code項(xiàng)目里我會(huì)用 Server Action 或 tRPC middleware 統(tǒng)一記錄每個(gè)請(qǐng)求的耗時(shí)、輸入?yún)?shù)和錯(cuò)誤堆棧。注意不要記錄密碼和 token 字段日志泄漏也是數(shù)據(jù)安全事故。6.3 一條一直被我記住的開發(fā)紀(jì)律最后分享一個(gè)經(jīng)驗(yàn)不一定和技術(shù)選型有關(guān)。用t3code這類強(qiáng)類型項(xiàng)目時(shí)最大的誘惑是“改完類型然后找遍所有引用點(diǎn)”。IDE 的重構(gòu)功能可以把字段重命名一步到位但運(yùn)行時(shí)有狀態(tài)的數(shù)據(jù)比如用戶已經(jīng)寫入的歷史記錄不會(huì)因?yàn)樽侄胃拿詣?dòng)遷移。所以凡是涉及核心表結(jié)構(gòu)的修改我的習(xí)慣是先寫數(shù)據(jù)遷移腳本再改類型和界面最后跑一遍全量測(cè)試確認(rèn)沒(méi)有臟數(shù)據(jù)。順序反了短期看不出問(wèn)題長(zhǎng)期一定會(huì)被隱藏的舊數(shù)據(jù)絆倒。從我個(gè)人的使用體會(huì)看t3code最大的意義不是某一項(xiàng)技術(shù)而是它用組合拳把“類型安全”推到了開發(fā)者很容易獲得的位置。它在提醒我好項(xiàng)目不是堆砌更多新輪子而是讓每次改動(dòng)都能在最早階段暴露問(wèn)題。如果你正在籌備一個(gè)全新的全棧產(chǎn)品我建議你照著這個(gè)思路把項(xiàng)目跑起來(lái)先讓類型作為你最嚴(yán)格也最耐心的代碼評(píng)審員。 t3code全棧項(xiàng)目實(shí)戰(zhàn)：Next.js、TypeScript與tRPC打造類型安全的應(yīng)用底座
第一次見(jiàn)到t3code這個(gè)名字時(shí)我以為又是一個(gè)趕時(shí)髦的縮寫組合。真正把整套代碼跑起來(lái)之后我才意識(shí)到它的價(jià)值不在某個(gè)單一框架而在于把現(xiàn)代全棧項(xiàng)目里最麻煩的“類型銜接”和“配置整合”一次性做完了。簡(jiǎn)單說(shuō)t3code是一套基于 T3 技術(shù)棧的全棧項(xiàng)目底座核心組合是 Next.js TypeScript Tailwind CSS tRPC Prisma。它解決的問(wèn)題非常具體前端調(diào)用接口不再靠猜后端改完字段前端立刻報(bào)錯(cuò)提醒數(shù)據(jù)庫(kù)模型定義完類型能自動(dòng)貫穿到頁(yè)面組件和 API 層再加上 Tailwind 處理樣式幾乎不用在 CSS 文件之間反復(fù)跳轉(zhuǎn)。這套組合適合前端想轉(zhuǎn)全棧的開發(fā)者、獨(dú)立開發(fā)者做小產(chǎn)品原型也適合三五個(gè)人的小團(tuán)隊(duì)統(tǒng)一技術(shù)底座。我后面所有內(nèi)容都會(huì)基于這個(gè)項(xiàng)目模板來(lái)拆解盡量把每一步為什么這么做都講清楚。1. 項(xiàng)目定位t3code 到底解決了什么問(wèn)題1.1 全棧開發(fā)最常見(jiàn)的兩種痛配置地獄和類型撕裂我先說(shuō)一個(gè)很多團(tuán)隊(duì)從前后端分離轉(zhuǎn)到全棧時(shí)的真實(shí)感受。傳統(tǒng)做法是前端 React 一個(gè)倉(cāng)庫(kù)后端 Express 一個(gè)倉(cāng)庫(kù)兩邊各有一套接口文檔。前端定義 request 類型后端定義 response 類型中間靠 Postman 或者 Swagger 同步。業(yè)務(wù)一復(fù)雜前端改了一個(gè)字段名后端還在用舊字段直到線上報(bào)錯(cuò)才被發(fā)現(xiàn)。這個(gè)問(wèn)題的本質(zhì)不是“寫錯(cuò)代碼”而是“類型沒(méi)有在編譯期打通”。t3code解決的就是這個(gè)痛點(diǎn)。它強(qiáng)制你用一套 TypeScript 類型貫穿整個(gè)鏈路Prisma 根據(jù)數(shù)據(jù)庫(kù) schema 生成類型tRPC 復(fù)用這些類型生成 API 調(diào)用函數(shù)前端組件里直接useQuery就能拿到帶類型推斷的返回值。改數(shù)據(jù)庫(kù)字段遷移之后跑一遍prisma generate所有引用點(diǎn)一起報(bào)錯(cuò)IDE 里就能把所有關(guān)聯(lián)位置找出來(lái)。這比任何運(yùn)行時(shí)監(jiān)控都更早地規(guī)避問(wèn)題。另一個(gè)痛點(diǎn)更常見(jiàn)配置地獄。Next.js 項(xiàng)目要配 webpack、babel、tsconfig、并處理 API 路由和靜態(tài)資源加上 Prisma 要管數(shù)據(jù)庫(kù)連接和遷移加上 Tailwind 要配 content 路徑和主題再加鑒權(quán)、環(huán)境變量一個(gè)項(xiàng)目半天起不來(lái)是常態(tài)。t3code本質(zhì)上是把這些配置預(yù)先收斂成一套經(jīng)過(guò)驗(yàn)證的默認(rèn)值你不需要理解每一層怎么協(xié)同也能先跑起來(lái)等業(yè)務(wù)深入后再按需修改。1.2 什么場(chǎng)景適合用它什么場(chǎng)景最好繞開我用了大半年t3code之后對(duì)它的適用范圍有了比較明確的判斷。如果你做的事情是獨(dú)立開發(fā)一個(gè) SaaS 工具、企業(yè)內(nèi)部系統(tǒng)、數(shù)據(jù)看板、內(nèi)容后臺(tái)或者你是幾個(gè)人協(xié)作的小團(tuán)隊(duì)想在第一周就見(jiàn)到能跑的完整業(yè)務(wù)閉環(huán)那這套組合非常合適。它把最常見(jiàn)的“用戶登錄 - 數(shù)據(jù)寫入 - 列表展示 - 權(quán)限控制”鏈路做成了開箱狀態(tài)你只需要往里面填業(yè)務(wù)表結(jié)構(gòu)。反過(guò)來(lái)如果你的場(chǎng)景是已經(jīng)有龐大的遺留數(shù)據(jù)庫(kù)和成熟的 REST/GraphQL 服務(wù)或者團(tuán)隊(duì)前端、后端是兩撥人后端要用 Java/Go 獨(dú)立維護(hù)那就不需要強(qiáng)行套t3code。它更適合那些自己掌握全流程、希望減少溝通損耗的人。還有個(gè)容易忽略的場(chǎng)景做外包或接私活。給甲方做后臺(tái)管理項(xiàng)目時(shí)最怕的就是需求反復(fù)改字段。用t3code的打通式類型系統(tǒng)甲方要求給用戶表加一個(gè)phone字段你改完 schema 生成遷移前端引用user.phone的地方對(duì)照編譯錯(cuò)誤全部改掉半小時(shí)內(nèi)就能改完交付。2. 技術(shù)選型拆解為什么 t3code 按下的是“確定性優(yōu)先”2.1 Next.js 作為全棧入口關(guān)鍵是心智統(tǒng)一t3code沒(méi)有選擇把前端打包成純靜態(tài)站點(diǎn)也沒(méi)有選擇 Express 單獨(dú)開后端端口而是把整個(gè)應(yīng)用放在 Next.js 里。很多人覺(jué)得 Next.js 只是 React 的服務(wù)端渲染框架其實(shí)它同時(shí)承擔(dān)了頁(yè)面路由、API 路由、服務(wù)端數(shù)據(jù)獲取三層職責(zé)。在t3code里頁(yè)面文件和 API 路由都在同一個(gè)應(yīng)用進(jìn)程內(nèi)數(shù)據(jù)庫(kù)調(diào)用發(fā)生在服務(wù)端瀏覽器拿到的是渲染完成的 HTML。這樣做的最大好處是心智統(tǒng)一我不需要維護(hù)兩個(gè)項(xiàng)目、兩套部署流程、兩套日志。尤其做個(gè)人項(xiàng)目時(shí)一個(gè)項(xiàng)目目錄、一條啟動(dòng)命令、一份環(huán)境變量就能把完整系統(tǒng)跑起來(lái)。再說(shuō)服務(wù)端渲染的收益。后臺(tái)管理類頁(yè)面往往有首屏數(shù)據(jù)加載需求。傳統(tǒng)前端做法是頁(yè)面加載后發(fā)出 fetch 請(qǐng)求 → 顯示 loading → 數(shù)據(jù)返回 → 重新渲染。t3code的頁(yè)面可以直接在服務(wù)端調(diào)用 tRPC 查詢把數(shù)據(jù)作為當(dāng)前頁(yè)面的 props 傳給組件首屏 HTML 里就帶真實(shí)數(shù)據(jù)。用戶感知是秒開搜索引擎也能讀到內(nèi)容這對(duì)內(nèi)容型產(chǎn)品有實(shí)際價(jià)值。2.2 tRPC 讓 API 調(diào)用像函數(shù)調(diào)用一樣安全t3code里最顛覆使用習(xí)慣的是 tRPC。它不是一個(gè)傳統(tǒng)框架而是一種“沒(méi)有 API 的 API 方案”。你不需要手寫 URL、method、請(qǐng)求體字段只需要在服務(wù)端定義一個(gè) router在前端 import 同一個(gè)函數(shù)引用調(diào)用方式就是api.post.list.useQuery(...)。為什么能做到類型安全因?yàn)?tRPC 的 schema 由 zod 定義zod 對(duì)象既是運(yùn)行時(shí)校驗(yàn)器又是靜態(tài)類型來(lái)源。比如我定義list的輸入是{ limit: number }那么在客戶端調(diào)用時(shí)如果傳了一個(gè)字符串limitTypeScript 編譯期就會(huì)直接報(bào)錯(cuò)。如果服務(wù)端查詢返回的字段和前端使用的字段不一致同樣在編譯期報(bào)錯(cuò)。很多不熟悉的人會(huì)擔(dān)心tRPC 是不是只適合小項(xiàng)目我的看法是只要你的系統(tǒng)前端和服務(wù)端共享 TypeScript 代碼庫(kù)它就完全夠用。大型系統(tǒng)里如果有什么模塊必須獨(dú)立部署你仍可以把 tRPC router 暴露為 HTTP 服務(wù)其他語(yǔ)言系統(tǒng)走標(biāo)準(zhǔn) JSON 接口即可。至少在t3code這種模板存在的時(shí)間里它的維護(hù)價(jià)值遠(yuǎn)大于傳統(tǒng)接口聯(lián)調(diào)。2.3 Prisma 把數(shù)據(jù)庫(kù)模型變成類型“源頭”t3code的數(shù)據(jù)層選型是 Prisma。它的核心優(yōu)勢(shì)有三個(gè)schema 可讀性好、遷移文件可審查、類型自動(dòng)生成。Prisma schema 不像 TypeORM 那樣用裝飾器寫死在實(shí)體類里而是一個(gè)獨(dú)立的schema.prisma文件。你在這個(gè)文件里定義表和關(guān)系執(zhí)行prisma migrate生成 SQL 遷移文件再執(zhí)行prisma generate生成客戶端代碼。這個(gè)客戶端代碼內(nèi)置了所有類型你的db.post.findMany()返回結(jié)果會(huì)被 TypeScript 推導(dǎo)成Post[]而且Post類型包含你定義的所有字段。用 Prisma 還有一個(gè)對(duì)新手很友好的地方錯(cuò)誤提示相對(duì)清晰。字段名寫錯(cuò)、關(guān)系沒(méi)有定義遷移階段就會(huì)報(bào)出來(lái)。對(duì)比直接寫 SQL 的 mybatis 風(fēng)格排查成本會(huì)低很多。t3code把 Prisma 和 tRPC 放在一起后數(shù)據(jù)庫(kù)的列名就是前端接口返回字段的“唯一事實(shí)來(lái)源”徹底消滅了手寫 DTO 和 VO 的重復(fù)勞動(dòng)。2.4 Tailwind CSS 并不只是樣式方案更是一種設(shè)計(jì)約束t3code引入 Tailwind CSS表面上看是“原子化 CSS 更省事”但我用下來(lái)發(fā)現(xiàn)它的真正價(jià)值是“避免樣式命名災(zāi)難”。傳統(tǒng)方式是每個(gè)組件一個(gè).module.css或者在styles目錄里定義 BEM 類名。項(xiàng)目一大類名沖突和優(yōu)先級(jí)問(wèn)題就開始出現(xiàn)。Tailwind 的做法是直接在 JSX 里寫flex items-center justify-between這類工具類沒(méi)有“樣式文件與組件文件對(duì)應(yīng)查找”的思維負(fù)擔(dān)。當(dāng)然原子類的代價(jià)是 JSX 會(huì)變長(zhǎng)有些人覺(jué)得“模板里塞太多類名不夠干凈”。我的折中方案是把復(fù)雜的顏色和間距抽象成組件組件內(nèi)部接受 className 覆蓋頁(yè)面層保持語(yǔ)義化命名和 Tailwind 工具類并存。t3code默認(rèn)配置里也支持這個(gè)做法你不需要被“純工具類”教條綁架按團(tuán)隊(duì)習(xí)慣調(diào)整即可。2.5 這幾層到底是怎么配合的會(huì)不會(huì)打架我聽(tīng)到過(guò)一種質(zhì)疑Next.js、tRPC、Prisma、Tailwind 都是獨(dú)立發(fā)展階段很強(qiáng)的工具硬放一起會(huì)不會(huì)互相牽制實(shí)際上它們的分工非常清晰。Prisma 管數(shù)據(jù)庫(kù)層產(chǎn)出類型和查詢客戶端tRPC 管 API 層讀取 Prisma 客戶端并按 zod 規(guī)則校驗(yàn)入?yún)ext.js 管路由和渲染層在服務(wù)端組件里調(diào)用 tRPC 查詢?cè)诳蛻舳私M件里通過(guò) hooks 觸發(fā)修改Tailwind 只負(fù)責(zé)樣式表達(dá)不摻和任何數(shù)據(jù)流。每一層只做一件事交給下一層的產(chǎn)物是強(qiáng)類型數(shù)據(jù)或 UI 描述沒(méi)有循環(huán)依賴。真正的風(fēng)險(xiǎn)點(diǎn)其實(shí)是版本升級(jí)節(jié)奏。Next.js 每年有大版本更新tRPC 也有自己的迭代不能盲目更新要先看官方升級(jí)文檔確認(rèn)兼容性。t3code的價(jià)值也在于它是一個(gè)可復(fù)現(xiàn)的“穩(wěn)定組合版本”你照著一份代碼模板維護(hù)不會(huì)出現(xiàn)“按網(wǎng)上教程裝完所有依賴但起不來(lái)”的情況。3. 從零初始化 t3code腳手架命令和目錄設(shè)計(jì)3.1 一條命令生成可運(yùn)行項(xiàng)目t3code的起點(diǎn)是官方腳手架 create-t3-app。我通常會(huì)先確認(rèn) Node.js 版本在 18 以上然后執(zhí)行npx create-t3-applatest t3code創(chuàng)建過(guò)程中會(huì)讓你選擇需要的模塊Next.js、TypeScript、Tailwind CSS、tRPC、Prisma、NextAuth.js。如果做的是一個(gè)需要登錄的后臺(tái)系統(tǒng)我會(huì)把 NextAuth.js 也勾上一次性把 session 機(jī)制和數(shù)據(jù)庫(kù)用戶表組件配好。還要注意選擇“是否使用 import alias”。強(qiáng)烈建議選/*這樣代碼里的相對(duì)路徑引用會(huì)明顯更好維護(hù)。初始化完成后直接執(zhí)行npm run dev打開本地 3000 端口看到的應(yīng)該是一個(gè)帶導(dǎo)航欄的首頁(yè)。這一步相當(dāng)于驗(yàn)證了“基礎(chǔ)配置能跑通”后面改造業(yè)務(wù)是在一套已驗(yàn)證的建筑骨架上裝修而不是空地起樓。3.2 目錄結(jié)構(gòu)如何暗示數(shù)據(jù)流我實(shí)際初始化出來(lái)并整理過(guò)的t3code目錄結(jié)構(gòu)大致是t3code/ ├─ app/ │ ├─ (auth)/ │ ├─ dashboard/ │ ├─ layout.tsx │ ├─ page.tsx │ └─ api/trpc/[trpc]/route.ts ├─ prisma/ │ ├─ schema.prisma │ └─ migrations/ ├─ server/ │ ├─ api/ │ │ ├─ root.ts │ │ ├─ trpc.ts │ │ └─ routers/ │ ├─ auth.ts │ └─ db.ts ├─ styles/ │ └─ globals.css ├─ .env.example ├─ next.config.js ├─ tailwind.config.ts └─ tsconfig.json這個(gè)結(jié)構(gòu)最需要理解的是app和server的邊界。app/api/trpc/[trpc]/route.ts是 Next.js 暴露 HTTP 端點(diǎn)的唯一入口它把 tRPC router 轉(zhuǎn)成處理請(qǐng)求的標(biāo)準(zhǔn)路由。寫業(yè)務(wù)的時(shí)候你很少需要改這個(gè)文件。server/api/routers才是寫業(yè)務(wù)的地方每個(gè)業(yè)務(wù)域一個(gè)文件比如post.ts、user.ts最后在root.ts里合并成 appRouter。這樣當(dāng)你打開一個(gè)路由文件能一眼看到這個(gè)域提供了哪些查詢和變更操作。server/db.ts是 PrismaClient 單例的導(dǎo)出位置。這里有個(gè)常見(jiàn)坑如果在多個(gè)文件里分別new PrismaClient()開發(fā)環(huán)境下會(huì)創(chuàng)建過(guò)多數(shù)據(jù)庫(kù)連接熱更新時(shí)尤其容易卡死。t3code默認(rèn)生成代碼里已經(jīng)用全局變量緩存了 client我建議保留這個(gè)寫法。3.3 關(guān)鍵配置文件里藏著的幾個(gè)細(xì)節(jié)先看.env.example。它至少包含這些變量DATABASE_URLmysql://user:passwordlocalhost:3306/t3code NEXTAUTH_SECRETyour-secret NEXTAUTH_URLhttp://localhost:3000實(shí)際開發(fā)時(shí)我會(huì)把.env.example作為環(huán)境變量清單真正敏感的密鑰放在.env.local里并確認(rèn) .gitignore 忽略了它。很多團(tuán)隊(duì)數(shù)據(jù)庫(kù)密鑰被提交到倉(cāng)庫(kù)事故就是這么來(lái)的。再看next.config.js它通常不需要大動(dòng)。需要知道的是transpilePackages選項(xiàng)如果將來(lái)你開發(fā)了本地 npm 包想復(fù)用需要把包名加進(jìn)去否則 Next.js 不會(huì)編譯 node_modules 里那些未編譯的 TS 代碼。最后是tsconfig.json里的baseUrl和paths。t3code默認(rèn)把./server/*指向源碼目錄。這個(gè)配置直接影響你在業(yè)務(wù)代碼里import { db } from ~/server/db能否被正確解析。遇到“模塊找不到”的錯(cuò)誤第一反應(yīng)不是去安裝包而是檢查 paths 配置和文件名大小寫。4. 核心業(yè)務(wù)閉環(huán)用戶、文章、儀表盤4.1 Prisma schema 設(shè)計(jì)與首次遷移只有腳手架沒(méi)有業(yè)務(wù)模板是沒(méi)有意義的。我來(lái)演示t3code里最常見(jiàn)的閉環(huán)用戶發(fā)表文章首頁(yè)展示文章列表后臺(tái)顯示統(tǒng)計(jì)數(shù)字。先定義 Prisma modelmodel User { id String id default(cuid()) email String unique name String? posts Post[] createdAt DateTime default(now()) } model Post { id String id default(cuid()) title String content String author User relation(fields: [authorId], references: [id]) authorId String createdAt DateTime default(now()) }設(shè)計(jì)上有兩點(diǎn)值得說(shuō)明。第一主鍵用cuid()而不是自增數(shù)字好處是分布式環(huán)境下不會(huì)撞號(hào)也避免讓別人猜測(cè)業(yè)務(wù)總量。第二authorId的命名要和關(guān)系字段對(duì)應(yīng)Prisma 才能正確識(shí)別多對(duì)一關(guān)系。寫完后執(zhí)行npx prisma migrate dev --name init這條命令會(huì)創(chuàng)建數(shù)據(jù)庫(kù)表并生成遷移文件。遷移文件是文本形式應(yīng)該提交到代碼倉(cāng)庫(kù)這樣團(tuán)隊(duì)成員prisma migrate deploy就能同步表結(jié)構(gòu)。4.2 tRPC Router 編寫規(guī)范接下來(lái)在server/api/routers/post.ts里定義文章查詢接口import { z } from zod; import { createTRPCRouter, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ list: publicProcedure .input( z.object({ limit: z.number().min(1).max(50).default(10), }) ) .query(async ({ ctx, input }) { return ctx.db.post.findMany({ take: input.limit, orderBy: { createdAt: desc }, include: { author: { select: { name: true }, }, }, }); }), });這里最有意思的是input和output的類型都由 zod 推導(dǎo)?？蛻舳苏{(diào)用時(shí)limit的類型、是否必須、取值范圍全部被 TypeScript 感知。如果某天你在前端調(diào)用了limit: 100編譯期就會(huì)被攔截而不是等到請(qǐng)求發(fā)起后后端報(bào) 400。我再擴(kuò)展一個(gè)創(chuàng)建文章的 mutationcreate: publicProcedure .input( z.object({ title: z.string().min(1, 標(biāo)題不能為空), content: z.string().min(1), authorId: z.string().cuid(), }) ) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: input.authorId, }, }); }),寫好的 router 要在 root.ts 里合并export const appRouter createTRPCRouter({ post: postRouter, user: userRouter, });導(dǎo)出的appRouter就是整個(gè)前端的類型來(lái)源。核心習(xí)慣是每個(gè)業(yè)務(wù)域一個(gè) router 文件不要在 root.ts 里堆業(yè)務(wù)代碼否則后期幾百行混在一起類型還能通但人已經(jīng)瘋了。4.3 頁(yè)面數(shù)據(jù)接入類型安全第一次體現(xiàn)前端頁(yè)面在app/dashboard/page.tsx里使用服務(wù)端組件方式調(diào)用import { api } from ~/server/api/root; import { db } from ~/server/db; export default async function DashboardPage() { const posts await db.post.findMany({ orderBy: { createdAt: desc }, take: 10, }); const total await db.post.count(); return ( main classNamep-6 h1 classNametext-2xl font-bold儀表盤/h1 p文章總數(shù){total}/p ul {posts.map((post) ( li key{post.id}{post.title}/li ))} /ul /main ); }這段代碼里沒(méi)有 fetch、沒(méi)有 URL、沒(méi)有 any 類型。posts的類型完全來(lái)自 Prisma 的findMany返回值。如果改天Post表加了status字段前端直接寫post.status就能拿到新字段不需要額外定義接口。對(duì)于需要?jiǎng)討B(tài)交互的客戶端組件就用 tRPC hooksuse client; import { api } from ~/server/api/react; export function PostList() { const { data, isLoading } api.post.list.useQuery({ limit: 10 }); if (isLoading) return p加載中.../p; return ( ul {data?.map((post) ( li key{post.id}{post.title} - {post.author.name}/li ))} /ul ); }api.post.list.useQuery的參數(shù)類型、返回類型全部從服務(wù)端 router 自動(dòng)推導(dǎo)。這就是t3code的核心體驗(yàn)寫完 router前端不需要再看接口文檔。4.4 服務(wù)端渲染和客戶端渲染該怎么選很多新手會(huì)把所有頁(yè)面都寫成客戶端組件然后抱怨首屏慢。我的判斷標(biāo)準(zhǔn)很簡(jiǎn)單頁(yè)面內(nèi)容如果和用戶會(huì)話狀態(tài)無(wú)關(guān)就優(yōu)先用服務(wù)端組件直接查庫(kù)頁(yè)面內(nèi)容如果完全依賴客戶端交互比如搜索框、表單實(shí)時(shí)校驗(yàn)、彈窗就用帶use client的組件。t3code里還有一個(gè)常用中間態(tài)在服務(wù)端組件里先取數(shù)據(jù)傳給客戶端組件客戶端組件只負(fù)責(zé)交互。比如文章列表的篩選按鈕可以把初始列表作為 props 傳入后續(xù)篩選在客戶端繼續(xù)調(diào)用useQuery。這樣首屏不閃爍交互又流暢。5. 實(shí)際運(yùn)行中的那些坑我踩過(guò)的都寫在下面5.1 tRPC 返回 Date 對(duì)象時(shí)的序列化邊界tRPC 默認(rèn)會(huì)把Date對(duì)象序列化成 ISO 字符串所以 Prisma 查詢返回的createdAt到了前端就成了字符串。如果你寫的組件直接用new Date(post.createdAt)沒(méi)問(wèn)題如果你用比較兩個(gè)時(shí)間就會(huì)出現(xiàn)類型對(duì)不上。我的處理習(xí)慣是在 Prisma schema 里把日期類型保持為DateTime在展示層明確轉(zhuǎn)成toLocaleString()。不建議為了省事把數(shù)據(jù)庫(kù)字段降級(jí)成字符串因?yàn)榕判?、時(shí)區(qū)計(jì)算都會(huì)變成噩夢(mèng)。5.2 Tailwind 動(dòng)態(tài)拼接類名失效這是所有 Tailwind 用戶都會(huì)踩的坑。在 JSX 里寫${condition ? text-red-500 : text-gray-500}時(shí)類名是完整字符串能生效。但如果寫成className{text-${color}-500}, Tailwind 的靜態(tài)掃描就找不到text-red-500這個(gè)類編譯產(chǎn)物里不會(huì)有對(duì)應(yīng)樣式。t3code項(xiàng)目里我的規(guī)避方法很簡(jiǎn)單要么使用完整的類名字符串要么在tailwind.config.ts的 safelist 里聲明需要?jiǎng)討B(tài)生成的類名組合。前者優(yōu)先因?yàn)檎Z(yǔ)義更清晰。5.3 Prisma 連接數(shù)打滿與冷啟動(dòng)超時(shí)本地開發(fā)時(shí)熱更新會(huì)頻繁重建 PrismaClient如果不做全局緩存連接數(shù)會(huì)漲得很快。t3code默認(rèn)的db.ts通常已經(jīng)包含這段邏輯import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma: PrismaClient | undefined; }; export const db globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV ! production) globalForPrisma.prisma db;這段代碼的建議保留。另一個(gè)問(wèn)題出現(xiàn)在 serverless 環(huán)境每次冷啟動(dòng)建立數(shù)據(jù)庫(kù)連接會(huì)增加幾百毫秒延遲。如果預(yù)算允許給 Prisma 加連接池配置比較穩(wěn)妥。連接池連接字符串通常是DATABASE_URL的 URL 參數(shù)加上?connection_limit5這樣的配置具體參數(shù)要看托管平臺(tái)文檔。5.4 環(huán)境變量混淆和密鑰泄漏t3code的.env.example里寫著 NEXTAUTH_SECRET。如果你不做登錄功能這個(gè)變量無(wú)所謂一旦啟用 NextAuth.js沒(méi)有正確的 secret很多會(huì)話邏輯會(huì)隨機(jī)失敗。另一個(gè)常見(jiàn)錯(cuò)誤是服務(wù)端代碼里寫了process.env.DATABASE_URL卻在客戶端組件里訪問(wèn)。Next.js 默認(rèn)會(huì)把沒(méi)有NEXT_PUBLIC_前綴的變量只暴露給服務(wù)端客戶端引用到的值是undefined導(dǎo)致線上故障但本地模擬不出來(lái)。排查這類問(wèn)題的順序是先在頁(yè)面服務(wù)端打印變量存不存在再確認(rèn)客戶端訪問(wèn)的環(huán)境變量名是否有NEXT_PUBLIC_前綴。6. 部署上線與日常維護(hù)要點(diǎn)6.1 構(gòu)建打包和數(shù)據(jù)庫(kù)遷移的順序t3code部署時(shí)最容易翻車的場(chǎng)景是代碼先發(fā)布數(shù)據(jù)庫(kù)遷移還沒(méi)跑前端查新字段直接報(bào)錯(cuò)。正確順序是先執(zhí)行數(shù)據(jù)庫(kù)遷移再部署應(yīng)用代碼或者在同一部署流程里先 migrate 再 build。我在 CI 里的腳本一般是npx prisma migrate deploy npx prisma generate npm run buildmigrate deploy只執(zhí)行未執(zhí)行過(guò)的遷移文件不會(huì)像migrate dev那樣要求你輸入名稱或重新生成遷移。正式環(huán)境永遠(yuǎn)只跑 deploy。prisma generate確保新的客戶端類型被打進(jìn)構(gòu)建產(chǎn)物。最后再跑next build這樣頁(yè)面里用到的字段和數(shù)據(jù)庫(kù)實(shí)際結(jié)構(gòu)是一致的。6.2 認(rèn)證、文件上傳、監(jiān)控這些擴(kuò)展方向t3code模板本身更像地板和承重墻居住體驗(yàn)取決于你如何擴(kuò)展。如果你需要登錄把 NextAuth.js 的 provider 配置填好數(shù)據(jù)庫(kù)里加Account、Session模型Prisma migrate 后就能用。文件上傳建議獨(dú)立走對(duì)象存儲(chǔ)不要把文件放進(jìn)數(shù)據(jù)庫(kù)在本地開發(fā)時(shí)可以用localStorage目錄線上換成 OSS/S3。監(jiān)控維度上我最推薦先接日志其次接錯(cuò)誤上報(bào)。t3code項(xiàng)目里我會(huì)用 Server Action 或 tRPC middleware 統(tǒng)一記錄每個(gè)請(qǐng)求的耗時(shí)、輸入?yún)?shù)和錯(cuò)誤堆棧。注意不要記錄密碼和 token 字段日志泄漏也是數(shù)據(jù)安全事故。6.3 一條一直被我記住的開發(fā)紀(jì)律最后分享一個(gè)經(jīng)驗(yàn)不一定和技術(shù)選型有關(guān)。用t3code這類強(qiáng)類型項(xiàng)目時(shí)最大的誘惑是“改完類型然后找遍所有引用點(diǎn)”。IDE 的重構(gòu)功能可以把字段重命名一步到位但運(yùn)行時(shí)有狀態(tài)的數(shù)據(jù)比如用戶已經(jīng)寫入的歷史記錄不會(huì)因?yàn)樽侄胃拿詣?dòng)遷移。所以凡是涉及核心表結(jié)構(gòu)的修改我的習(xí)慣是先寫數(shù)據(jù)遷移腳本再改類型和界面最后跑一遍全量測(cè)試確認(rèn)沒(méi)有臟數(shù)據(jù)。順序反了短期看不出問(wèn)題長(zhǎng)期一定會(huì)被隱藏的舊數(shù)據(jù)絆倒。從我個(gè)人的使用體會(huì)看t3code最大的意義不是某一項(xiàng)技術(shù)而是它用組合拳把“類型安全”推到了開發(fā)者很容易獲得的位置。它在提醒我好項(xiàng)目不是堆砌更多新輪子而是讓每次改動(dòng)都能在最早階段暴露問(wèn)題。如果你正在籌備一個(gè)全新的全棧產(chǎn)品我建議你照著這個(gè)思路把項(xiàng)目跑起來(lái)先讓類型作為你最嚴(yán)格也最耐心的代碼評(píng)審員。