調(diào)之痛)
以前搭全棧項(xiàng)目最讓我頭疼的從來(lái)不是功能復(fù)雜度而是前后端之間那層反復(fù)扯皮的類型定義。后端改了字段名前端編譯直接一片紅更別提寫一整套 API 封裝、手搓類型聲明、再對(duì)著文檔排查接口字段的日常。后來(lái)接觸到 t3code 這套基于 T3 Stack 的腳手架工作流我最大的感受是它不是在幫你寫代碼而是在重構(gòu)你組織全棧代碼的方式——把“前后端各寫一套”變成“從一個(gè)類型源頭自動(dòng)派生出整個(gè)調(diào)用鏈路”。這篇文章我就用實(shí)際經(jīng)歷聊聊t3code 到底解決了我哪些真實(shí)痛點(diǎn)里面的技術(shù)選型是怎么協(xié)作的以及從初始化到部署我用它做完兩個(gè)項(xiàng)目后沉淀下來(lái)的經(jīng)驗(yàn)和幾個(gè)躲不開(kāi)的坑。1. 為什么我盯上了 t3code從手寫后端到全棧類型安全的轉(zhuǎn)變1.1 全棧項(xiàng)目最消耗精力的是“共識(shí)維護(hù)”一提到全棧項(xiàng)目很多人第一反應(yīng)是“技術(shù)棧多”“要學(xué)的東西雜”。但我真正做了幾個(gè)商用規(guī)模的 Web 應(yīng)用之后發(fā)現(xiàn)技術(shù)棧復(fù)雜只是入門門檻真正的隱性成本在于前后端對(duì)數(shù)據(jù)結(jié)構(gòu)的共識(shí)怎么維護(hù)。傳統(tǒng)方案里前端通常通過(guò) REST API 和 Vue/React 頁(yè)面打交道我需要維護(hù)一份 API 文檔或者用 OpenAPI/Swagger 描述接口后端改了 User 模型的字段前端必須同步修改 interface。項(xiàng)目一大了這個(gè)同步過(guò)程就會(huì)出現(xiàn)三類問(wèn)題改了后端字段但前端沒(méi)跟上線上頁(yè)面白屏或者取到 undefined接口文檔更新不及時(shí)前端按舊文檔聯(lián)調(diào)浪費(fèi)半天時(shí)間某個(gè)字段從 string 變成 number類型沒(méi)有編譯期報(bào)錯(cuò)導(dǎo)致運(yùn)行期才暴露異常。t3code 的出現(xiàn)有意思在它換了個(gè)思路與其費(fèi)力維護(hù)前后端的類型共識(shí)不如讓后端類型直接生成前端調(diào)用代碼的類型簽名。也就是說(shuō)前端真正調(diào)用的數(shù)據(jù)是從后端那個(gè)唯一的類型源頭“長(zhǎng)”出來(lái)的。1.2 t3code 到底是什么雖然現(xiàn)在網(wǎng)上也有各種以 t3 開(kāi)頭命名的項(xiàng)目但我在實(shí)際開(kāi)發(fā)中使用的 t3code本質(zhì)上是一套面向全棧 TypeScript 項(xiàng)目的腳手架和模塊初始化工具。它圍繞 T3 StackNext.js TypeScript tRPC Prisma Tailwind CSS把項(xiàng)目的基礎(chǔ)骨架、數(shù)據(jù)模型、認(rèn)證體系、API 路由和前后端調(diào)用關(guān)系一次性裝配起來(lái)我拿到手就能直接把精力放到業(yè)務(wù)邏輯上。我自己的體會(huì)是t3code 最適合這幾類人獨(dú)立開(kāi)發(fā)者想用一份 TypeScript 代碼同時(shí)打通數(shù)據(jù)庫(kù)、后端邏輯和前端頁(yè)面小型全棧團(tuán)隊(duì)希望減少前后端聯(lián)調(diào)時(shí)的來(lái)回溝通成本正在搭建 MVP 的創(chuàng)業(yè)項(xiàng)目需要快速迭代數(shù)據(jù)結(jié)構(gòu)且不想被接口設(shè)計(jì)和類型維護(hù)拖慢速度。如果你平時(shí)只是寫純前端或者純后端t3code 的收益不大但如果你做的是那種“一個(gè)人要包圓前后端數(shù)據(jù)庫(kù)”的活它真的能幫你省下很多重復(fù)勞動(dòng)。1.3 它和“低代碼平臺(tái)”完全不是一回事第一次聽(tīng)到這類工具時(shí)我也擔(dān)心過(guò)這會(huì)不會(huì)又是一套低代碼平臺(tái)把我綁定到某個(gè)私有協(xié)議上以后想遷移都沒(méi)法遷移實(shí)際研究過(guò)后我可以明確說(shuō)t3code 不搞任何私有的運(yùn)行時(shí)協(xié)議它輸出的就是一個(gè)標(biāo)準(zhǔn)的 Next.js 項(xiàng)目里面有正常的 Prisma schema、tRPC router、頁(yè)面組件和 API 流程。換句話說(shuō)它幫我完成的是“裝配和初始化”不是“托管和綁架”。項(xiàng)目一旦生成源碼都在我手里所有邏輯都由我自己控制該寫測(cè)試寫測(cè)試、該做性能優(yōu)化做性能優(yōu)化沒(méi)有任何黑盒。1.4 從“寫最少代碼”到“改最少代碼”我用傳統(tǒng)方式做一個(gè)帶用戶系統(tǒng)的內(nèi)容管理后臺(tái)大概要經(jīng)歷設(shè)計(jì)數(shù)據(jù)庫(kù)表結(jié)構(gòu)、寫后端 CRUD 接口、逐一手寫路由和校驗(yàn)、生成前端 API 封裝、在頁(yè)面上手動(dòng)消費(fèi)數(shù)據(jù)、遇到類型不一致再回頭改。整個(gè)流程中真正屬于業(yè)務(wù)邏輯的代碼可能只占 40%剩下 60% 都在做“翻譯”和“適配”工作。t3code 把我從這種狀態(tài)里拉出來(lái)之后我明顯感覺(jué)到工作模式變了。從前是“寫最少代碼完成任務(wù)”現(xiàn)在更像是“盡量少改代碼地演化業(yè)務(wù)”。數(shù)據(jù)庫(kù)加個(gè)字段Prisma 遷移一執(zhí)行類型自動(dòng)更新后端在 tRPC 的 router 里加一個(gè) query前端立刻能在編輯器里拿到帶類型提示的調(diào)用方法甚至參數(shù)結(jié)構(gòu)都是自動(dòng)推導(dǎo)的。這種“一處修改處處類型安全”的體驗(yàn)用一次就回不去。2. t3code 的底層構(gòu)成T3 技術(shù)棧四件套是怎么協(xié)作的2.1 四個(gè)核心依賴各管哪一段t3code 生成的骨架里最核心的是四個(gè)依賴。很多人把它們當(dāng)成單純的技術(shù)組合但我在實(shí)際使用中更關(guān)注它們各自承擔(dān)的角色以及彼此之間的接縫在哪里。一是Next.js負(fù)責(zé)應(yīng)用框架層。它同時(shí)提供 React 頁(yè)面渲染、API Route、服務(wù)端渲染和靜態(tài)生成能力。在 T3 Stack 的語(yǔ)境里Next.js 不僅是一個(gè)頁(yè)面框架更是把前后端放在同一工程里的容器。二是TypeScript整個(gè)項(xiàng)目的類型系統(tǒng)基底。如果沒(méi)有 TypeScript后面講的“端到端類型安全”完全不成立所以我在 t3code 里很少看到 .js 文件所有業(yè)務(wù)代碼和配置文件都以 .ts 或 .tsx 為主。三是tRPC負(fù)責(zé)前后端調(diào)用層的協(xié)議。它不需要我們手寫 REST 路由也不需要生成 GraphQL schema而是直接通過(guò)函數(shù)調(diào)用的方式在前端調(diào)用后端方法并且自動(dòng)獲得完整的類型推導(dǎo)。它的實(shí)現(xiàn)原理不復(fù)雜就是依賴 TypeScript 的泛型把 router 類型直接傳遞到前端 hooks 上。四是Prisma負(fù)責(zé)數(shù)據(jù)模型和數(shù)據(jù)庫(kù)訪問(wèn)。它用一個(gè) schema 文件定義模型然后生成類型安全的客戶端。在 t3code 的項(xiàng)目里Prisma 的 model 是整個(gè)應(yīng)用數(shù)據(jù)結(jié)構(gòu)的直接描述者。至于 Tailwind CSS我一般把它看成錦上添花的樣式方案它解決的是 UI 層開(kāi)發(fā)效率的問(wèn)題不影響類型閉環(huán)。2.2 類型閉環(huán)是怎么走通的要真正理解 t3code 的價(jià)值我建議你先搞清楚這條類型閉環(huán)的路徑Prisma schema 定義模型 ↓ Prisma Client 生成類型 ↓ tRPC router 里用這些類型處理輸入輸出 ↓ 前端通過(guò) tRPC hooks 調(diào)用 router ↓ 編輯器根據(jù)推導(dǎo)自動(dòng)提示類型和參數(shù)我把這條鏈路拆開(kāi)講一下。假設(shè)我在prisma/schema.prisma里定義一個(gè)Todo模型model Todo { id String id default(cuid()) title String completed Boolean default(false) createdAt DateTime default(now()) }執(zhí)行npx prisma migrate dev之后Prisma 客戶端會(huì)生成對(duì)應(yīng)的Todo類型。接著在 tRPC router 中加入一個(gè)返回所有待辦事項(xiàng)的查詢import { router, publicProcedure } from ../trpc; import { prisma } from ../db; export const todoRouter router({ getAll: publicProcedure.query(() { return prisma.todo.findMany(); }), });前端頁(yè)面里我不需要重新定義任何 interface直接調(diào)用import { api } from ~/utils/api; export default function TodoList() { const { data: todos } api.todo.getAll.useQuery(); return ( ul {todos?.map((todo) ( li key{todo.id}{todo.title}/li ))} /ul ); }這里你會(huì)發(fā)現(xiàn)一個(gè)有意思的地方todos的類型是由后端 Prisma 查詢結(jié)果推導(dǎo)出來(lái)的而不是我手動(dòng)聲明的。哪怕哪天我往模型里加了字段前端代碼里todo.someNewField也馬上會(huì)有類型提示如果我刪了某個(gè)字段前端用到它的地方會(huì)直接編譯報(bào)錯(cuò)。這條閉環(huán)的意義在于它把“類型正確性”從一種約定變成了一種編譯期保證。我不用再擔(dān)心“前端不知道后端字段改過(guò)”這種事因?yàn)轭愋拖到y(tǒng)會(huì)第一時(shí)間攔住我。2.3 和 REST / GraphQL 方案的直觀對(duì)比我知道有人會(huì)問(wèn)我用 REST 加 OpenAPI 也能生成類型用 GraphQL 也能自動(dòng)推導(dǎo)為什么非要用 t3code 這一套我做了一張粗淺的對(duì)照表完全基于我的日常體感方案類型安全性聯(lián)調(diào)成本學(xué)習(xí)曲線適用場(chǎng)景REST 手寫類型靠自覺(jué)高低傳統(tǒng)前后端分離團(tuán)隊(duì)REST OpenAPI 生成類型中中中接口規(guī)范嚴(yán)格的團(tuán)隊(duì)GraphQL Codegen高低高需要靈活查詢的大前端團(tuán)隊(duì)t3codeT3 Stack高很低中全棧 TypeScript 項(xiàng)目、獨(dú)立開(kāi)發(fā)者GraphQL 雖然查詢能力很靈活但為了拿到這種靈活性我得維護(hù) schema、寫 resolver、配 codegen還要考慮客戶端緩存策略對(duì)一個(gè)人干全棧來(lái)說(shuō)其實(shí)不輕。t3code 里 tRPC 的模型更“純函數(shù)式”前端調(diào)用后端的體驗(yàn)幾乎等于調(diào)用本地函數(shù)而且不用額外跑代碼生成器類型推導(dǎo)是實(shí)時(shí)的。當(dāng)然 tRPC 也有自己的適用范圍——如果前后端完全分離且由不同團(tuán)隊(duì)維護(hù)或者需要對(duì)外提供公共 APItRPC 反而不合適。它更多是內(nèi)部后端和前端之間的一種高效溝通方式。選型永遠(yuǎn)要基于項(xiàng)目形態(tài)t3code 適合的是“一個(gè)代碼庫(kù)搞定全?！钡膱?chǎng)景。3. 跑通第一個(gè) t3code 項(xiàng)目從初始化到 CRUD 的完整鏈路3.1 初始化項(xiàng)目時(shí)該選哪些模塊t3code 的起點(diǎn)是create-t3-app這個(gè)命令。我在終端執(zhí)行npx create-t3-applatest my-app交互式命令行會(huì)問(wèn)你項(xiàng)目名稱、要不要啟用 NextAuth.js、Prisma、Tailwind CSS、tRPC 這些模塊以及使用 npm 還是 pnpm 等包管理器。我第一次跑的時(shí)候很老實(shí)把能勾選的全都勾上了。后來(lái)實(shí)際開(kāi)發(fā)才意識(shí)到不必為了齊全而全選要根據(jù)業(yè)務(wù)預(yù)判來(lái)選。我現(xiàn)在的選擇習(xí)慣是一定會(huì)選 TypeScript、Prisma、tRPC、Next.js這是核心需要用戶登錄時(shí)才會(huì)勾選 NextAuth.js如果只是內(nèi)部系統(tǒng)且不涉及用戶體系不選它反而省事Tailwind CSS 純看項(xiàng)目 UI 需求如果團(tuán)隊(duì)已經(jīng)定了組件庫(kù)或者用其他 CSS 方案就不必讓它進(jìn)入代碼庫(kù)部署平臺(tái)選擇 Vercel 時(shí)腳手架會(huì)順便把本地開(kāi)發(fā)和生產(chǎn)環(huán)境的配置處理好選 Docker 自托管的話后面要自己留意數(shù)據(jù)庫(kù)連接。初始化完成后項(xiàng)目的目錄結(jié)構(gòu)大概是這樣的my-app/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── pages/ │ ├── server/ │ │ ├── api/ │ │ │ └── trpc/ │ │ ├── auth.ts │ │ └── db.ts │ └── utils/ │ └── api.ts ├── .env └── package.json這里src/server/db.ts是 Prisma Client 單例src/utils/api.ts是前端 tRPC hooks 的封裝入口src/server/api/trpc.ts定義了 router 創(chuàng)建和 procedure 的基礎(chǔ)。我建議拿到項(xiàng)目后先花十分鐘把這三個(gè)文件讀一遍理解它們之間的引用關(guān)系后面寫業(yè)務(wù)會(huì)順很多。3.2 從 schema 到數(shù)據(jù)庫(kù)遷移我拿一個(gè)最簡(jiǎn)單的博客系統(tǒng)舉例。先在prisma/schema.prisma里定義 Post 和 User 模型model User { id String id default(cuid()) email String unique name String? posts Post[] } model Post { id String id default(cuid()) title String content String published Boolean default(false) authorId String author User relation(fields: [authorId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt }然后執(zhí)行npx prisma migrate dev --name init這個(gè)命令會(huì)做兩件事在數(shù)據(jù)庫(kù)里創(chuàng)建對(duì)應(yīng)的表同時(shí)生成最新版的 Prisma Client。我提醒一句本地?cái)?shù)據(jù)庫(kù)連接串記得先寫進(jìn).env很多人第一次跑 migrate 失敗都是因?yàn)榄h(huán)境變量沒(méi)配置。3.3 編寫 tRPC router 并注冊(cè)接著我在src/server/api/root.ts或其他你自定義的 router 聚合文件里添加一個(gè) postRouterimport { z } from zod; import { createTRPCRouter, publicProcedure } from ~/server/api/trpc; import { prisma } from ~/server/db; export const postRouter createTRPCRouter({ list: publicProcedure.query(() { return prisma.post.findMany({ orderBy: { createdAt: desc }, }); }), byId: publicProcedure .input(z.object({ id: z.string() })) .query(({ input }) { return prisma.post.findUnique({ where: { id: input.id }, include: { author: true }, }); }), create: publicProcedure .input( z.object({ title: z.string().min(1), content: z.string().min(1), authorEmail: z.string().email(), }) ) .mutation(async ({ input }) { const user await prisma.user.upsert({ where: { email: input.authorEmail }, update: {}, create: { email: input.authorEmail, name: input.authorEmail.split()[0] }, }); return prisma.post.create({ data: { title: input.title, content: input.content, authorId: user.id, }, }); }), });這里你可能注意到我用了 zod 做輸入校驗(yàn)。tRPC 原生建議用 zod 作為 schema 校驗(yàn)庫(kù)它和 tRPC 的 input 結(jié)合非常好。輸入校驗(yàn)不僅保證了后端接口的參數(shù)安全還讓前端調(diào)用時(shí)能拿到準(zhǔn)確的入?yún)㈩愋吞崾舅闶穷愋烷]環(huán)里的重要一環(huán)。寫完之后必須把 postRouter 注冊(cè)到根 router 上否則前端根本訪問(wèn)不到import { createTRPCRouter } from ~/server/api/trpc; import { postRouter } from ./post; export const appRouter createTRPCRouter({ post: postRouter, }); export type AppRouter typeof appRouter;3.4 前端頁(yè)面消費(fèi) API前端頁(yè)面直接對(duì)應(yīng)src/pages/index.tsx我用一個(gè)列表頁(yè)展示所有文章import { api } from ~/utils/api; import Link from next/link; export default function Home() { const { data: posts, isLoading } api.post.list.useQuery(); if (isLoading) return divLoading.../div; return ( div {posts?.map((post) ( Link key{post.id} href{/post/${post.id}} h2{post.title}/h2 p{post.content}/p /Link ))} /div ); }刷新頁(yè)面后數(shù)據(jù)就能正常渲染。我沒(méi)寫任何額外的 axios 封裝沒(méi)有手動(dòng)拼 URL沒(méi)有定義 response interface甚至連useQuery的泛型都不用傳類型全是從后端推導(dǎo)過(guò)來(lái)的。這個(gè)“少寫代碼但類型更強(qiáng)”的體驗(yàn)就是我前面說(shuō)的核心價(jià)值。如果想做創(chuàng)建文章的交互也很直接const createPost api.post.create.useMutation({ onSuccess: () { utils.post.list.invalidate(); }, }); createPost.mutate({ title: 新文章, content: 正文內(nèi)容, authorEmail: testexample.com, });用invalidate讓列表重新請(qǐng)求一次數(shù)據(jù)自動(dòng)刷新前端邏輯保持得非常干凈。3.5 雙向綁定與 SSR 模式的一點(diǎn)提醒t3code 默認(rèn)會(huì)用 Next.js 的 SSR/SSG 能力來(lái)預(yù)取 tRPC 數(shù)據(jù)。也就是說(shuō)服務(wù)端會(huì)先主動(dòng)調(diào)用 tRPC 方法把數(shù)據(jù)塞進(jìn)頁(yè)面 props 里瀏覽器端再用同一個(gè) hook 做水合。這套機(jī)制讓首屏加載很快也不會(huì)有白屏閃爍。但這里的隱性前提是服務(wù)端調(diào)用和客戶端調(diào)用共享同一套 tRPC 邏輯。如果你在 procedure 里訪問(wèn)了只存在于瀏覽器端的window或者localStorage服務(wù)端執(zhí)行時(shí)就會(huì)直接報(bào)錯(cuò)。我建議你從第一天開(kāi)始就養(yǎng)成習(xí)慣把涉及瀏覽器環(huán)境變量的邏輯放到獨(dú)立的工具函數(shù)里并且用typeof window ! undefined判斷環(huán)境不然部署到 Vercel 上很容易踩 SSR 相關(guān)的坑。4. 接入認(rèn)證和數(shù)據(jù)庫(kù)之后我踩過(guò)的那些坑4.1 NextAuth.js 和 Prisma 的適配器問(wèn)題t3code 腳手架雖然默認(rèn)集成了 NextAuth.js但真正接入登錄功能時(shí)我遇到的第一坑是適配器adapter的配置。NextAuth 要跟 Prisma 配合必須用next-auth/prisma-adapter并且在src/server/auth.ts里正確傳參。如果適配器沒(méi)配好最常見(jiàn)的報(bào)錯(cuò)是調(diào)用登錄接口時(shí)數(shù)據(jù)庫(kù)無(wú)法寫入 session 記錄。我當(dāng)時(shí)的排查過(guò)程是這樣的先看服務(wù)端日志確認(rèn)是 session 表寫入失敗再看auth.ts里的配置發(fā)現(xiàn)adapter沒(méi)有被傳入。修正后的核心代碼大致是import NextAuth from next-auth; import CredentialsProvider from next-auth/providers/credentials; import { PrismaAdapter } from next-auth/prisma-adapter; import { prisma } from ~/server/db; export const authOptions { adapter: PrismaAdapter(prisma), providers: [ CredentialsProvider({ name: credentials, credentials: { email: { label: Email, type: email }, password: { label: Password, type: password }, }, async authorize(credentials) { // 這里是校驗(yàn)邏輯 }, }), ], session: { strategy: jwt, }, secret: process.env.NEXTAUTH_SECRET, };接下來(lái)還有一個(gè)容易忽視的點(diǎn)如果用默認(rèn)的strategy: jwt就不太依賴數(shù)據(jù)庫(kù)里的 session 記錄這時(shí) PrismaAdapter 需要同步維護(hù)的其實(shí)是 User、Account、Session 等模型。我在 schema 里如果漏了這些模型登錄時(shí)也會(huì)因?yàn)閿?shù)據(jù)庫(kù)缺表而出錯(cuò)。解法很簡(jiǎn)單把官網(wǎng)文檔里提供的 NextAuth 相關(guān)模型復(fù)制到schema.prisma再跑一次遷移問(wèn)題基本就解決了。4.2 環(huán)境變量缺失導(dǎo)致的“幽靈報(bào)錯(cuò)”t3code 初始化后項(xiàng)目根目錄會(huì)生成一個(gè).env文件里面通常會(huì)預(yù)留DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL這些變量。我最開(kāi)始忽略了一點(diǎn)本地開(kāi)發(fā)和生產(chǎn)環(huán)境需要不同取值。比如本地.env里DATABASE_URL指向localhost的 PostgreSQL生產(chǎn)環(huán)境在 Vercel 后臺(tái)配的卻是線上數(shù)據(jù)庫(kù)地址。如果你在本地跑prisma migrate deploy時(shí)用錯(cuò)了環(huán)境變量有可能把遷移應(yīng)用到線上或者本地庫(kù)上那將是災(zāi)難。我的建議是給不同環(huán)境配獨(dú)立的.env文件如.env.local、.env.production并且永遠(yuǎn)只在項(xiàng)目目錄里執(zhí)行數(shù)據(jù)庫(kù)遷移命令。雖然這屬于老生常談但團(tuán)隊(duì)協(xié)作時(shí)真的有人會(huì)把線上連接串寫到公共配置里導(dǎo)致泄露。4.3 protectedProcedure 的正確姿勢(shì)t3code 腳手架通常會(huì)提供一個(gè)createTRPCContext函數(shù)把當(dāng)前請(qǐng)求的 session 塞進(jìn) context。我后來(lái)在寫需要登錄才能調(diào)用的接口時(shí)沒(méi)用publicProcedure而是基于 context 判斷后再拋錯(cuò)export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session || !ctx.session.user) { throw new Error(Unauthorized); } return next({ ctx: { session: { ...ctx.session, user: ctx.session.user }, }, }); });這個(gè)中間件做完之后我想獲取當(dāng)前用戶時(shí)直接讀ctx.session.user就行。前端調(diào)用時(shí)配合useSession()判斷登錄態(tài)體驗(yàn)整體很順。我踩過(guò)的坑是如果 session 類型沒(méi)和數(shù)據(jù)庫(kù)的 User 模型對(duì)齊前端拿到的session.user.id可能被推導(dǎo)成string | undefined導(dǎo)致一些危險(xiǎn)的隱性 bug——比如在創(chuàng)建 Post 時(shí)把 undefined 寫進(jìn) authorId。所以建議大家拿到 session 后先做一次顯式判空再往下走。4.4 CRUD 校驗(yàn)放在服務(wù)端不要在客戶端省事tRPC 的好處是輸入校驗(yàn)天然寫在服務(wù)端 procedure 里但我見(jiàn)過(guò)有些同事圖方便只在前端表單里做了校驗(yàn)后端換個(gè)請(qǐng)求工具直接把非法字段傳進(jìn)去。說(shuō)實(shí)話因?yàn)?tRPC 的類型推導(dǎo)太舒服了人很容易產(chǎn)生“前端類型安全等于接口安全”的錯(cuò)覺(jué)。實(shí)際上類型安全不等于安全。zod 校驗(yàn)?zāi)菍臃谰€必須留在服務(wù)端。我在 t3code 項(xiàng)目里的習(xí)慣是所有涉及寫入的操作一律寫 zod input schema并且把z.string().min(1)這類邊界條件寫全。這樣即使有人繞過(guò)前端調(diào)后端數(shù)據(jù)也會(huì)被攔截在這層不會(huì)污染數(shù)據(jù)庫(kù)。5. 部署與優(yōu)化從開(kāi)發(fā)機(jī)到生產(chǎn)環(huán)境的最后一公里5.1 部署到 Vercel 前要處理的事情t3code 生成的 Next.js 項(xiàng)目直接對(duì)接 Vercel 很方便。我第一次部署時(shí)只把 GitHub 倉(cāng)庫(kù)連到 Vercel然后添加環(huán)境變量就完事了。但后來(lái)發(fā)現(xiàn)有幾個(gè)細(xì)節(jié)要提前準(zhǔn)備好否則很容易在線上出現(xiàn)詭異問(wèn)題。第一Prisma Client 的生成時(shí)機(jī)。Vercel 構(gòu)建時(shí)會(huì)跑prisma generate但只在構(gòu)建環(huán)境里生成如果你本地的 Prisma Client 版本和線上不一致有可能導(dǎo)致運(yùn)行時(shí)錯(cuò)誤。我一般會(huì)在package.json的postinstall腳本里加上postinstall: prisma generate這樣每次裝完依賴都會(huì)從 schema 重新生成客戶端不會(huì)出現(xiàn)版本漂移。第二數(shù)據(jù)庫(kù)遷移怎么執(zhí)行。Vercel 的構(gòu)建環(huán)境不是跑遷移的好地方我推薦用 GitHub Actions 或一個(gè)獨(dú)立的環(huán)境去跑prisma migrate deploy。也就是說(shuō)代碼部署和數(shù)據(jù)庫(kù)遷移分成兩個(gè)流程代碼先發(fā)布遷移單獨(dú)控制節(jié)奏。這樣做的好處是一旦遷移失敗不會(huì)把應(yīng)用構(gòu)建直接拖死。第三NEXTAUTH_URL 必須和生產(chǎn)域名一致。NextAuth 在做回調(diào)時(shí)會(huì)校驗(yàn)這個(gè)變量我見(jiàn)過(guò)不少案例是由于把它留成http://localhost:3000導(dǎo)致線上登錄后跳轉(zhuǎn)回本地地址表現(xiàn)為“登錄成功但立刻又跳回登錄頁(yè)”。這個(gè)坑排查起來(lái)其實(shí)不難但確實(shí)很耗時(shí)間。5.2 Serverless 環(huán)境下的數(shù)據(jù)庫(kù)連接池Vercel 的 Serverless 函數(shù)是“按請(qǐng)求拉起、跑完即回收”的模型。如果我在每個(gè)函數(shù)實(shí)例里都創(chuàng)建一個(gè)新的 Prisma Client 連接很快會(huì)把數(shù)據(jù)庫(kù)連接數(shù)打滿尤其在使用 PostgreSQL 時(shí)特別明顯。t3code 生成的src/server/db.ts里幫我做了一個(gè)全局單例import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma: PrismaClient }; export const prisma globalForPrisma.prisma ?? new PrismaClient({ log: process.env.NODE_ENV development ? [query, error, warn] : [error], }); if (process.env.NODE_ENV ! production) globalForPrisma.prisma prisma;這個(gè)模式的核心意圖是在本地開(kāi)發(fā)時(shí)熱更新會(huì)導(dǎo)致模塊反復(fù)加載如果不做全局緩存每次刷新都會(huì)創(chuàng)建新的 Prisma 實(shí)例部署到 Serverless 環(huán)境后同一實(shí)例內(nèi)部復(fù)用連接。我在生產(chǎn)環(huán)境跑了一段時(shí)間后數(shù)據(jù)庫(kù)連接數(shù)一直保持在一個(gè)健康水位。如果項(xiàng)目流量上來(lái)還可以在數(shù)據(jù)庫(kù)連接串里加上連接池參數(shù)比如 Prisma 官方建議的?pgbouncertrue配合 PgBouncer 使用。要不要這樣做取決于實(shí)際并發(fā)量我自己的經(jīng)驗(yàn)是中小型應(yīng)用把單例模式做好就夠用了等連接數(shù)告警了再上連接池也不遲。5.3 首屏性能調(diào)優(yōu)的幾個(gè)實(shí)際操作雖然 t3code 的默認(rèn)體驗(yàn)已經(jīng)不錯(cuò)但生產(chǎn)環(huán)境對(duì)性能的要求更高。我做過(guò)的幾個(gè)有效優(yōu)化排在這里按需取數(shù)據(jù)Prisma 的select和include要按頁(yè)面需要來(lái)避免一次findMany把幾十個(gè)字段全撈出來(lái)。Serverless 函數(shù)的執(zhí)行時(shí)間就是錢數(shù)據(jù)量小一點(diǎn)響應(yīng)自然快。開(kāi)啟 Next.js 的緩存策略對(duì)于不常變的數(shù)據(jù)可以用staleTime控制 tRPC 查詢的緩存時(shí)長(zhǎng)。例如文章列表五分鐘內(nèi)不重新請(qǐng)求api.post.list.useQuery(undefined, { staleTime: 5 * 60 * 1000, });嚴(yán)格區(qū)分動(dòng)態(tài)和靜態(tài)頁(yè)面博客首頁(yè)、關(guān)于頁(yè)這種內(nèi)容基本不變的盡量用靜態(tài)生成用戶中心這種強(qiáng)個(gè)性化的頁(yè)面再走 SSR 或客戶端渲染。能靜態(tài)就不動(dòng)態(tài)能讓邊緣緩存接住就讓它接住。5.4 日志、監(jiān)控和錯(cuò)誤上報(bào)做全棧項(xiàng)目時(shí)日志是最容易被忽略但又最重要的一環(huán)。t3code 腳手架只給了基礎(chǔ)結(jié)構(gòu)不包含任何監(jiān)控。我后來(lái)接了一款錯(cuò)誤監(jiān)控工具把 tRPC 的 errors 統(tǒng)一上報(bào)因?yàn)?tRPC 的錯(cuò)誤信息非常規(guī)范有code、message、path這些字段非常適合直接對(duì)接到監(jiān)控平臺(tái)上。我在src/server/api/trpc.ts的 errorFormatter 里做了一次全局?jǐn)r截export const t initTRPC.contexttypeof createTRPCContext().create({ errorFormatter({ shape, error }) { // 在這里上報(bào)錯(cuò)誤 return shape; }, });這樣線上如果出現(xiàn) Zod 校驗(yàn)失敗、數(shù)據(jù)庫(kù)異常、未授權(quán)訪問(wèn)我都能第一時(shí)間從監(jiān)控后臺(tái)看到具體是哪個(gè) procedure 出了問(wèn)題而不需要等用戶反饋。6. 回顧 t3code 這段時(shí)間的實(shí)際體驗(yàn)用 t3code 做了完整項(xiàng)目之后我有個(gè)很直接的感覺(jué)它把全棧開(kāi)發(fā)里的“隱形稅”砍掉了一大半。以前我要花很多時(shí)間維護(hù)前后端接口文檔、類型聲明、API 封裝現(xiàn)在這些成本降到了接近零寫業(yè)務(wù)代碼的密度變得很高。對(duì)我來(lái)說(shuō)它最大的價(jià)值不在代碼生成而在那套類型閉環(huán)帶來(lái)的心智負(fù)擔(dān)減輕。當(dāng)然它也不是銀彈。如果你的團(tuán)隊(duì)前后端完全分離后端需要面向第三方開(kāi)放 API那 tRPC 這套“服務(wù)端和客戶端強(qiáng)綁定”的方式反而會(huì)成為負(fù)擔(dān)。另外T3 Stack 的生態(tài)相對(duì)年輕很多企業(yè)級(jí)基礎(chǔ)設(shè)施的兼容方案需要自己探索比如前面說(shuō)的連接池、多環(huán)境數(shù)據(jù)庫(kù)遷移、CI/CD 流程都需要你額外搭建。但如果你是單兵作戰(zhàn)或者小團(tuán)隊(duì)想做一個(gè)類型安全、可快速迭代的 Web 應(yīng)用t3code 這套工作流非常值得試一下。剛開(kāi)始上手時(shí)多花一點(diǎn)時(shí)間把 Prisma schema、tRPC router、NextAuth 的關(guān)系理解透后續(xù)開(kāi)發(fā)體驗(yàn)的提升會(huì)大大超出你的預(yù)期。最后再分享一個(gè)小技巧。我用 t3code 時(shí)習(xí)慣把項(xiàng)目里所有數(shù)據(jù)庫(kù)寫入操作收斂到mutation里并且做好輸入校驗(yàn)和結(jié)果類型聲明。這樣一旦業(yè)務(wù)邏輯要調(diào)整改動(dòng)范圍會(huì)非常小不會(huì)在十幾個(gè)頁(yè)面里到處找散落的 set 調(diào)用。這種習(xí)慣配合 t3code 的類型推導(dǎo)讓整個(gè)項(xiàng)目即使經(jīng)過(guò)幾個(gè)月的迭代依然保持著比較好的可維護(hù)性。如果你正準(zhǔn)備上手一個(gè)新的全棧項(xiàng)目我建議你從最小閉環(huán)開(kāi)始——先不急著一次性引入全部模塊把列表查詢和一條數(shù)據(jù)寫入跑通感受一下“類型自己長(zhǎng)腳走完全?！钡捏w驗(yàn)再做后續(xù)擴(kuò)展也不遲。 全棧類型安全新范式：用T3 Stack與tRPC告別前后端聯(lián)調(diào)之痛
以前搭全棧項(xiàng)目最讓我頭疼的從來(lái)不是功能復(fù)雜度而是前后端之間那層反復(fù)扯皮的類型定義。后端改了字段名前端編譯直接一片紅更別提寫一整套 API 封裝、手搓類型聲明、再對(duì)著文檔排查接口字段的日常。后來(lái)接觸到 t3code 這套基于 T3 Stack 的腳手架工作流我最大的感受是它不是在幫你寫代碼而是在重構(gòu)你組織全棧代碼的方式——把“前后端各寫一套”變成“從一個(gè)類型源頭自動(dòng)派生出整個(gè)調(diào)用鏈路”。這篇文章我就用實(shí)際經(jīng)歷聊聊t3code 到底解決了我哪些真實(shí)痛點(diǎn)里面的技術(shù)選型是怎么協(xié)作的以及從初始化到部署我用它做完兩個(gè)項(xiàng)目后沉淀下來(lái)的經(jīng)驗(yàn)和幾個(gè)躲不開(kāi)的坑。1. 為什么我盯上了 t3code從手寫后端到全棧類型安全的轉(zhuǎn)變1.1 全棧項(xiàng)目最消耗精力的是“共識(shí)維護(hù)”一提到全棧項(xiàng)目很多人第一反應(yīng)是“技術(shù)棧多”“要學(xué)的東西雜”。但我真正做了幾個(gè)商用規(guī)模的 Web 應(yīng)用之后發(fā)現(xiàn)技術(shù)棧復(fù)雜只是入門門檻真正的隱性成本在于前后端對(duì)數(shù)據(jù)結(jié)構(gòu)的共識(shí)怎么維護(hù)。傳統(tǒng)方案里前端通常通過(guò) REST API 和 Vue/React 頁(yè)面打交道我需要維護(hù)一份 API 文檔或者用 OpenAPI/Swagger 描述接口后端改了 User 模型的字段前端必須同步修改 interface。項(xiàng)目一大了這個(gè)同步過(guò)程就會(huì)出現(xiàn)三類問(wèn)題改了后端字段但前端沒(méi)跟上線上頁(yè)面白屏或者取到 undefined接口文檔更新不及時(shí)前端按舊文檔聯(lián)調(diào)浪費(fèi)半天時(shí)間某個(gè)字段從 string 變成 number類型沒(méi)有編譯期報(bào)錯(cuò)導(dǎo)致運(yùn)行期才暴露異常。t3code 的出現(xiàn)有意思在它換了個(gè)思路與其費(fèi)力維護(hù)前后端的類型共識(shí)不如讓后端類型直接生成前端調(diào)用代碼的類型簽名。也就是說(shuō)前端真正調(diào)用的數(shù)據(jù)是從后端那個(gè)唯一的類型源頭“長(zhǎng)”出來(lái)的。1.2 t3code 到底是什么雖然現(xiàn)在網(wǎng)上也有各種以 t3 開(kāi)頭命名的項(xiàng)目但我在實(shí)際開(kāi)發(fā)中使用的 t3code本質(zhì)上是一套面向全棧 TypeScript 項(xiàng)目的腳手架和模塊初始化工具。它圍繞 T3 StackNext.js TypeScript tRPC Prisma Tailwind CSS把項(xiàng)目的基礎(chǔ)骨架、數(shù)據(jù)模型、認(rèn)證體系、API 路由和前后端調(diào)用關(guān)系一次性裝配起來(lái)我拿到手就能直接把精力放到業(yè)務(wù)邏輯上。我自己的體會(huì)是t3code 最適合這幾類人獨(dú)立開(kāi)發(fā)者想用一份 TypeScript 代碼同時(shí)打通數(shù)據(jù)庫(kù)、后端邏輯和前端頁(yè)面小型全棧團(tuán)隊(duì)希望減少前后端聯(lián)調(diào)時(shí)的來(lái)回溝通成本正在搭建 MVP 的創(chuàng)業(yè)項(xiàng)目需要快速迭代數(shù)據(jù)結(jié)構(gòu)且不想被接口設(shè)計(jì)和類型維護(hù)拖慢速度。如果你平時(shí)只是寫純前端或者純后端t3code 的收益不大但如果你做的是那種“一個(gè)人要包圓前后端數(shù)據(jù)庫(kù)”的活它真的能幫你省下很多重復(fù)勞動(dòng)。1.3 它和“低代碼平臺(tái)”完全不是一回事第一次聽(tīng)到這類工具時(shí)我也擔(dān)心過(guò)這會(huì)不會(huì)又是一套低代碼平臺(tái)把我綁定到某個(gè)私有協(xié)議上以后想遷移都沒(méi)法遷移實(shí)際研究過(guò)后我可以明確說(shuō)t3code 不搞任何私有的運(yùn)行時(shí)協(xié)議它輸出的就是一個(gè)標(biāo)準(zhǔn)的 Next.js 項(xiàng)目里面有正常的 Prisma schema、tRPC router、頁(yè)面組件和 API 流程。換句話說(shuō)它幫我完成的是“裝配和初始化”不是“托管和綁架”。項(xiàng)目一旦生成源碼都在我手里所有邏輯都由我自己控制該寫測(cè)試寫測(cè)試、該做性能優(yōu)化做性能優(yōu)化沒(méi)有任何黑盒。1.4 從“寫最少代碼”到“改最少代碼”我用傳統(tǒng)方式做一個(gè)帶用戶系統(tǒng)的內(nèi)容管理后臺(tái)大概要經(jīng)歷設(shè)計(jì)數(shù)據(jù)庫(kù)表結(jié)構(gòu)、寫后端 CRUD 接口、逐一手寫路由和校驗(yàn)、生成前端 API 封裝、在頁(yè)面上手動(dòng)消費(fèi)數(shù)據(jù)、遇到類型不一致再回頭改。整個(gè)流程中真正屬于業(yè)務(wù)邏輯的代碼可能只占 40%剩下 60% 都在做“翻譯”和“適配”工作。t3code 把我從這種狀態(tài)里拉出來(lái)之后我明顯感覺(jué)到工作模式變了。從前是“寫最少代碼完成任務(wù)”現(xiàn)在更像是“盡量少改代碼地演化業(yè)務(wù)”。數(shù)據(jù)庫(kù)加個(gè)字段Prisma 遷移一執(zhí)行類型自動(dòng)更新后端在 tRPC 的 router 里加一個(gè) query前端立刻能在編輯器里拿到帶類型提示的調(diào)用方法甚至參數(shù)結(jié)構(gòu)都是自動(dòng)推導(dǎo)的。這種“一處修改處處類型安全”的體驗(yàn)用一次就回不去。2. t3code 的底層構(gòu)成T3 技術(shù)棧四件套是怎么協(xié)作的2.1 四個(gè)核心依賴各管哪一段t3code 生成的骨架里最核心的是四個(gè)依賴。很多人把它們當(dāng)成單純的技術(shù)組合但我在實(shí)際使用中更關(guān)注它們各自承擔(dān)的角色以及彼此之間的接縫在哪里。一是Next.js負(fù)責(zé)應(yīng)用框架層。它同時(shí)提供 React 頁(yè)面渲染、API Route、服務(wù)端渲染和靜態(tài)生成能力。在 T3 Stack 的語(yǔ)境里Next.js 不僅是一個(gè)頁(yè)面框架更是把前后端放在同一工程里的容器。二是TypeScript整個(gè)項(xiàng)目的類型系統(tǒng)基底。如果沒(méi)有 TypeScript后面講的“端到端類型安全”完全不成立所以我在 t3code 里很少看到 .js 文件所有業(yè)務(wù)代碼和配置文件都以 .ts 或 .tsx 為主。三是tRPC負(fù)責(zé)前后端調(diào)用層的協(xié)議。它不需要我們手寫 REST 路由也不需要生成 GraphQL schema而是直接通過(guò)函數(shù)調(diào)用的方式在前端調(diào)用后端方法并且自動(dòng)獲得完整的類型推導(dǎo)。它的實(shí)現(xiàn)原理不復(fù)雜就是依賴 TypeScript 的泛型把 router 類型直接傳遞到前端 hooks 上。四是Prisma負(fù)責(zé)數(shù)據(jù)模型和數(shù)據(jù)庫(kù)訪問(wèn)。它用一個(gè) schema 文件定義模型然后生成類型安全的客戶端。在 t3code 的項(xiàng)目里Prisma 的 model 是整個(gè)應(yīng)用數(shù)據(jù)結(jié)構(gòu)的直接描述者。至于 Tailwind CSS我一般把它看成錦上添花的樣式方案它解決的是 UI 層開(kāi)發(fā)效率的問(wèn)題不影響類型閉環(huán)。2.2 類型閉環(huán)是怎么走通的要真正理解 t3code 的價(jià)值我建議你先搞清楚這條類型閉環(huán)的路徑Prisma schema 定義模型 ↓ Prisma Client 生成類型 ↓ tRPC router 里用這些類型處理輸入輸出 ↓ 前端通過(guò) tRPC hooks 調(diào)用 router ↓ 編輯器根據(jù)推導(dǎo)自動(dòng)提示類型和參數(shù)我把這條鏈路拆開(kāi)講一下。假設(shè)我在prisma/schema.prisma里定義一個(gè)Todo模型model Todo { id String id default(cuid()) title String completed Boolean default(false) createdAt DateTime default(now()) }執(zhí)行npx prisma migrate dev之后Prisma 客戶端會(huì)生成對(duì)應(yīng)的Todo類型。接著在 tRPC router 中加入一個(gè)返回所有待辦事項(xiàng)的查詢import { router, publicProcedure } from ../trpc; import { prisma } from ../db; export const todoRouter router({ getAll: publicProcedure.query(() { return prisma.todo.findMany(); }), });前端頁(yè)面里我不需要重新定義任何 interface直接調(diào)用import { api } from ~/utils/api; export default function TodoList() { const { data: todos } api.todo.getAll.useQuery(); return ( ul {todos?.map((todo) ( li key{todo.id}{todo.title}/li ))} /ul ); }這里你會(huì)發(fā)現(xiàn)一個(gè)有意思的地方todos的類型是由后端 Prisma 查詢結(jié)果推導(dǎo)出來(lái)的而不是我手動(dòng)聲明的。哪怕哪天我往模型里加了字段前端代碼里todo.someNewField也馬上會(huì)有類型提示如果我刪了某個(gè)字段前端用到它的地方會(huì)直接編譯報(bào)錯(cuò)。這條閉環(huán)的意義在于它把“類型正確性”從一種約定變成了一種編譯期保證。我不用再擔(dān)心“前端不知道后端字段改過(guò)”這種事因?yàn)轭愋拖到y(tǒng)會(huì)第一時(shí)間攔住我。2.3 和 REST / GraphQL 方案的直觀對(duì)比我知道有人會(huì)問(wèn)我用 REST 加 OpenAPI 也能生成類型用 GraphQL 也能自動(dòng)推導(dǎo)為什么非要用 t3code 這一套我做了一張粗淺的對(duì)照表完全基于我的日常體感方案類型安全性聯(lián)調(diào)成本學(xué)習(xí)曲線適用場(chǎng)景REST 手寫類型靠自覺(jué)高低傳統(tǒng)前后端分離團(tuán)隊(duì)REST OpenAPI 生成類型中中中接口規(guī)范嚴(yán)格的團(tuán)隊(duì)GraphQL Codegen高低高需要靈活查詢的大前端團(tuán)隊(duì)t3codeT3 Stack高很低中全棧 TypeScript 項(xiàng)目、獨(dú)立開(kāi)發(fā)者GraphQL 雖然查詢能力很靈活但為了拿到這種靈活性我得維護(hù) schema、寫 resolver、配 codegen還要考慮客戶端緩存策略對(duì)一個(gè)人干全棧來(lái)說(shuō)其實(shí)不輕。t3code 里 tRPC 的模型更“純函數(shù)式”前端調(diào)用后端的體驗(yàn)幾乎等于調(diào)用本地函數(shù)而且不用額外跑代碼生成器類型推導(dǎo)是實(shí)時(shí)的。當(dāng)然 tRPC 也有自己的適用范圍——如果前后端完全分離且由不同團(tuán)隊(duì)維護(hù)或者需要對(duì)外提供公共 APItRPC 反而不合適。它更多是內(nèi)部后端和前端之間的一種高效溝通方式。選型永遠(yuǎn)要基于項(xiàng)目形態(tài)t3code 適合的是“一個(gè)代碼庫(kù)搞定全?！钡膱?chǎng)景。3. 跑通第一個(gè) t3code 項(xiàng)目從初始化到 CRUD 的完整鏈路3.1 初始化項(xiàng)目時(shí)該選哪些模塊t3code 的起點(diǎn)是create-t3-app這個(gè)命令。我在終端執(zhí)行npx create-t3-applatest my-app交互式命令行會(huì)問(wèn)你項(xiàng)目名稱、要不要啟用 NextAuth.js、Prisma、Tailwind CSS、tRPC 這些模塊以及使用 npm 還是 pnpm 等包管理器。我第一次跑的時(shí)候很老實(shí)把能勾選的全都勾上了。后來(lái)實(shí)際開(kāi)發(fā)才意識(shí)到不必為了齊全而全選要根據(jù)業(yè)務(wù)預(yù)判來(lái)選。我現(xiàn)在的選擇習(xí)慣是一定會(huì)選 TypeScript、Prisma、tRPC、Next.js這是核心需要用戶登錄時(shí)才會(huì)勾選 NextAuth.js如果只是內(nèi)部系統(tǒng)且不涉及用戶體系不選它反而省事Tailwind CSS 純看項(xiàng)目 UI 需求如果團(tuán)隊(duì)已經(jīng)定了組件庫(kù)或者用其他 CSS 方案就不必讓它進(jìn)入代碼庫(kù)部署平臺(tái)選擇 Vercel 時(shí)腳手架會(huì)順便把本地開(kāi)發(fā)和生產(chǎn)環(huán)境的配置處理好選 Docker 自托管的話后面要自己留意數(shù)據(jù)庫(kù)連接。初始化完成后項(xiàng)目的目錄結(jié)構(gòu)大概是這樣的my-app/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── pages/ │ ├── server/ │ │ ├── api/ │ │ │ └── trpc/ │ │ ├── auth.ts │ │ └── db.ts │ └── utils/ │ └── api.ts ├── .env └── package.json這里src/server/db.ts是 Prisma Client 單例src/utils/api.ts是前端 tRPC hooks 的封裝入口src/server/api/trpc.ts定義了 router 創(chuàng)建和 procedure 的基礎(chǔ)。我建議拿到項(xiàng)目后先花十分鐘把這三個(gè)文件讀一遍理解它們之間的引用關(guān)系后面寫業(yè)務(wù)會(huì)順很多。3.2 從 schema 到數(shù)據(jù)庫(kù)遷移我拿一個(gè)最簡(jiǎn)單的博客系統(tǒng)舉例。先在prisma/schema.prisma里定義 Post 和 User 模型model User { id String id default(cuid()) email String unique name String? posts Post[] } model Post { id String id default(cuid()) title String content String published Boolean default(false) authorId String author User relation(fields: [authorId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt }然后執(zhí)行npx prisma migrate dev --name init這個(gè)命令會(huì)做兩件事在數(shù)據(jù)庫(kù)里創(chuàng)建對(duì)應(yīng)的表同時(shí)生成最新版的 Prisma Client。我提醒一句本地?cái)?shù)據(jù)庫(kù)連接串記得先寫進(jìn).env很多人第一次跑 migrate 失敗都是因?yàn)榄h(huán)境變量沒(méi)配置。3.3 編寫 tRPC router 并注冊(cè)接著我在src/server/api/root.ts或其他你自定義的 router 聚合文件里添加一個(gè) postRouterimport { z } from zod; import { createTRPCRouter, publicProcedure } from ~/server/api/trpc; import { prisma } from ~/server/db; export const postRouter createTRPCRouter({ list: publicProcedure.query(() { return prisma.post.findMany({ orderBy: { createdAt: desc }, }); }), byId: publicProcedure .input(z.object({ id: z.string() })) .query(({ input }) { return prisma.post.findUnique({ where: { id: input.id }, include: { author: true }, }); }), create: publicProcedure .input( z.object({ title: z.string().min(1), content: z.string().min(1), authorEmail: z.string().email(), }) ) .mutation(async ({ input }) { const user await prisma.user.upsert({ where: { email: input.authorEmail }, update: {}, create: { email: input.authorEmail, name: input.authorEmail.split()[0] }, }); return prisma.post.create({ data: { title: input.title, content: input.content, authorId: user.id, }, }); }), });這里你可能注意到我用了 zod 做輸入校驗(yàn)。tRPC 原生建議用 zod 作為 schema 校驗(yàn)庫(kù)它和 tRPC 的 input 結(jié)合非常好。輸入校驗(yàn)不僅保證了后端接口的參數(shù)安全還讓前端調(diào)用時(shí)能拿到準(zhǔn)確的入?yún)㈩愋吞崾舅闶穷愋烷]環(huán)里的重要一環(huán)。寫完之后必須把 postRouter 注冊(cè)到根 router 上否則前端根本訪問(wèn)不到import { createTRPCRouter } from ~/server/api/trpc; import { postRouter } from ./post; export const appRouter createTRPCRouter({ post: postRouter, }); export type AppRouter typeof appRouter;3.4 前端頁(yè)面消費(fèi) API前端頁(yè)面直接對(duì)應(yīng)src/pages/index.tsx我用一個(gè)列表頁(yè)展示所有文章import { api } from ~/utils/api; import Link from next/link; export default function Home() { const { data: posts, isLoading } api.post.list.useQuery(); if (isLoading) return divLoading.../div; return ( div {posts?.map((post) ( Link key{post.id} href{/post/${post.id}} h2{post.title}/h2 p{post.content}/p /Link ))} /div ); }刷新頁(yè)面后數(shù)據(jù)就能正常渲染。我沒(méi)寫任何額外的 axios 封裝沒(méi)有手動(dòng)拼 URL沒(méi)有定義 response interface甚至連useQuery的泛型都不用傳類型全是從后端推導(dǎo)過(guò)來(lái)的。這個(gè)“少寫代碼但類型更強(qiáng)”的體驗(yàn)就是我前面說(shuō)的核心價(jià)值。如果想做創(chuàng)建文章的交互也很直接const createPost api.post.create.useMutation({ onSuccess: () { utils.post.list.invalidate(); }, }); createPost.mutate({ title: 新文章, content: 正文內(nèi)容, authorEmail: testexample.com, });用invalidate讓列表重新請(qǐng)求一次數(shù)據(jù)自動(dòng)刷新前端邏輯保持得非常干凈。3.5 雙向綁定與 SSR 模式的一點(diǎn)提醒t3code 默認(rèn)會(huì)用 Next.js 的 SSR/SSG 能力來(lái)預(yù)取 tRPC 數(shù)據(jù)。也就是說(shuō)服務(wù)端會(huì)先主動(dòng)調(diào)用 tRPC 方法把數(shù)據(jù)塞進(jìn)頁(yè)面 props 里瀏覽器端再用同一個(gè) hook 做水合。這套機(jī)制讓首屏加載很快也不會(huì)有白屏閃爍。但這里的隱性前提是服務(wù)端調(diào)用和客戶端調(diào)用共享同一套 tRPC 邏輯。如果你在 procedure 里訪問(wèn)了只存在于瀏覽器端的window或者localStorage服務(wù)端執(zhí)行時(shí)就會(huì)直接報(bào)錯(cuò)。我建議你從第一天開(kāi)始就養(yǎng)成習(xí)慣把涉及瀏覽器環(huán)境變量的邏輯放到獨(dú)立的工具函數(shù)里并且用typeof window ! undefined判斷環(huán)境不然部署到 Vercel 上很容易踩 SSR 相關(guān)的坑。4. 接入認(rèn)證和數(shù)據(jù)庫(kù)之后我踩過(guò)的那些坑4.1 NextAuth.js 和 Prisma 的適配器問(wèn)題t3code 腳手架雖然默認(rèn)集成了 NextAuth.js但真正接入登錄功能時(shí)我遇到的第一坑是適配器adapter的配置。NextAuth 要跟 Prisma 配合必須用next-auth/prisma-adapter并且在src/server/auth.ts里正確傳參。如果適配器沒(méi)配好最常見(jiàn)的報(bào)錯(cuò)是調(diào)用登錄接口時(shí)數(shù)據(jù)庫(kù)無(wú)法寫入 session 記錄。我當(dāng)時(shí)的排查過(guò)程是這樣的先看服務(wù)端日志確認(rèn)是 session 表寫入失敗再看auth.ts里的配置發(fā)現(xiàn)adapter沒(méi)有被傳入。修正后的核心代碼大致是import NextAuth from next-auth; import CredentialsProvider from next-auth/providers/credentials; import { PrismaAdapter } from next-auth/prisma-adapter; import { prisma } from ~/server/db; export const authOptions { adapter: PrismaAdapter(prisma), providers: [ CredentialsProvider({ name: credentials, credentials: { email: { label: Email, type: email }, password: { label: Password, type: password }, }, async authorize(credentials) { // 這里是校驗(yàn)邏輯 }, }), ], session: { strategy: jwt, }, secret: process.env.NEXTAUTH_SECRET, };接下來(lái)還有一個(gè)容易忽視的點(diǎn)如果用默認(rèn)的strategy: jwt就不太依賴數(shù)據(jù)庫(kù)里的 session 記錄這時(shí) PrismaAdapter 需要同步維護(hù)的其實(shí)是 User、Account、Session 等模型。我在 schema 里如果漏了這些模型登錄時(shí)也會(huì)因?yàn)閿?shù)據(jù)庫(kù)缺表而出錯(cuò)。解法很簡(jiǎn)單把官網(wǎng)文檔里提供的 NextAuth 相關(guān)模型復(fù)制到schema.prisma再跑一次遷移問(wèn)題基本就解決了。4.2 環(huán)境變量缺失導(dǎo)致的“幽靈報(bào)錯(cuò)”t3code 初始化后項(xiàng)目根目錄會(huì)生成一個(gè).env文件里面通常會(huì)預(yù)留DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL這些變量。我最開(kāi)始忽略了一點(diǎn)本地開(kāi)發(fā)和生產(chǎn)環(huán)境需要不同取值。比如本地.env里DATABASE_URL指向localhost的 PostgreSQL生產(chǎn)環(huán)境在 Vercel 后臺(tái)配的卻是線上數(shù)據(jù)庫(kù)地址。如果你在本地跑prisma migrate deploy時(shí)用錯(cuò)了環(huán)境變量有可能把遷移應(yīng)用到線上或者本地庫(kù)上那將是災(zāi)難。我的建議是給不同環(huán)境配獨(dú)立的.env文件如.env.local、.env.production并且永遠(yuǎn)只在項(xiàng)目目錄里執(zhí)行數(shù)據(jù)庫(kù)遷移命令。雖然這屬于老生常談但團(tuán)隊(duì)協(xié)作時(shí)真的有人會(huì)把線上連接串寫到公共配置里導(dǎo)致泄露。4.3 protectedProcedure 的正確姿勢(shì)t3code 腳手架通常會(huì)提供一個(gè)createTRPCContext函數(shù)把當(dāng)前請(qǐng)求的 session 塞進(jìn) context。我后來(lái)在寫需要登錄才能調(diào)用的接口時(shí)沒(méi)用publicProcedure而是基于 context 判斷后再拋錯(cuò)export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session || !ctx.session.user) { throw new Error(Unauthorized); } return next({ ctx: { session: { ...ctx.session, user: ctx.session.user }, }, }); });這個(gè)中間件做完之后我想獲取當(dāng)前用戶時(shí)直接讀ctx.session.user就行。前端調(diào)用時(shí)配合useSession()判斷登錄態(tài)體驗(yàn)整體很順。我踩過(guò)的坑是如果 session 類型沒(méi)和數(shù)據(jù)庫(kù)的 User 模型對(duì)齊前端拿到的session.user.id可能被推導(dǎo)成string | undefined導(dǎo)致一些危險(xiǎn)的隱性 bug——比如在創(chuàng)建 Post 時(shí)把 undefined 寫進(jìn) authorId。所以建議大家拿到 session 后先做一次顯式判空再往下走。4.4 CRUD 校驗(yàn)放在服務(wù)端不要在客戶端省事tRPC 的好處是輸入校驗(yàn)天然寫在服務(wù)端 procedure 里但我見(jiàn)過(guò)有些同事圖方便只在前端表單里做了校驗(yàn)后端換個(gè)請(qǐng)求工具直接把非法字段傳進(jìn)去。說(shuō)實(shí)話因?yàn)?tRPC 的類型推導(dǎo)太舒服了人很容易產(chǎn)生“前端類型安全等于接口安全”的錯(cuò)覺(jué)。實(shí)際上類型安全不等于安全。zod 校驗(yàn)?zāi)菍臃谰€必須留在服務(wù)端。我在 t3code 項(xiàng)目里的習(xí)慣是所有涉及寫入的操作一律寫 zod input schema并且把z.string().min(1)這類邊界條件寫全。這樣即使有人繞過(guò)前端調(diào)后端數(shù)據(jù)也會(huì)被攔截在這層不會(huì)污染數(shù)據(jù)庫(kù)。5. 部署與優(yōu)化從開(kāi)發(fā)機(jī)到生產(chǎn)環(huán)境的最后一公里5.1 部署到 Vercel 前要處理的事情t3code 生成的 Next.js 項(xiàng)目直接對(duì)接 Vercel 很方便。我第一次部署時(shí)只把 GitHub 倉(cāng)庫(kù)連到 Vercel然后添加環(huán)境變量就完事了。但后來(lái)發(fā)現(xiàn)有幾個(gè)細(xì)節(jié)要提前準(zhǔn)備好否則很容易在線上出現(xiàn)詭異問(wèn)題。第一Prisma Client 的生成時(shí)機(jī)。Vercel 構(gòu)建時(shí)會(huì)跑prisma generate但只在構(gòu)建環(huán)境里生成如果你本地的 Prisma Client 版本和線上不一致有可能導(dǎo)致運(yùn)行時(shí)錯(cuò)誤。我一般會(huì)在package.json的postinstall腳本里加上postinstall: prisma generate這樣每次裝完依賴都會(huì)從 schema 重新生成客戶端不會(huì)出現(xiàn)版本漂移。第二數(shù)據(jù)庫(kù)遷移怎么執(zhí)行。Vercel 的構(gòu)建環(huán)境不是跑遷移的好地方我推薦用 GitHub Actions 或一個(gè)獨(dú)立的環(huán)境去跑prisma migrate deploy。也就是說(shuō)代碼部署和數(shù)據(jù)庫(kù)遷移分成兩個(gè)流程代碼先發(fā)布遷移單獨(dú)控制節(jié)奏。這樣做的好處是一旦遷移失敗不會(huì)把應(yīng)用構(gòu)建直接拖死。第三NEXTAUTH_URL 必須和生產(chǎn)域名一致。NextAuth 在做回調(diào)時(shí)會(huì)校驗(yàn)這個(gè)變量我見(jiàn)過(guò)不少案例是由于把它留成http://localhost:3000導(dǎo)致線上登錄后跳轉(zhuǎn)回本地地址表現(xiàn)為“登錄成功但立刻又跳回登錄頁(yè)”。這個(gè)坑排查起來(lái)其實(shí)不難但確實(shí)很耗時(shí)間。5.2 Serverless 環(huán)境下的數(shù)據(jù)庫(kù)連接池Vercel 的 Serverless 函數(shù)是“按請(qǐng)求拉起、跑完即回收”的模型。如果我在每個(gè)函數(shù)實(shí)例里都創(chuàng)建一個(gè)新的 Prisma Client 連接很快會(huì)把數(shù)據(jù)庫(kù)連接數(shù)打滿尤其在使用 PostgreSQL 時(shí)特別明顯。t3code 生成的src/server/db.ts里幫我做了一個(gè)全局單例import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma: PrismaClient }; export const prisma globalForPrisma.prisma ?? new PrismaClient({ log: process.env.NODE_ENV development ? [query, error, warn] : [error], }); if (process.env.NODE_ENV ! production) globalForPrisma.prisma prisma;這個(gè)模式的核心意圖是在本地開(kāi)發(fā)時(shí)熱更新會(huì)導(dǎo)致模塊反復(fù)加載如果不做全局緩存每次刷新都會(huì)創(chuàng)建新的 Prisma 實(shí)例部署到 Serverless 環(huán)境后同一實(shí)例內(nèi)部復(fù)用連接。我在生產(chǎn)環(huán)境跑了一段時(shí)間后數(shù)據(jù)庫(kù)連接數(shù)一直保持在一個(gè)健康水位。如果項(xiàng)目流量上來(lái)還可以在數(shù)據(jù)庫(kù)連接串里加上連接池參數(shù)比如 Prisma 官方建議的?pgbouncertrue配合 PgBouncer 使用。要不要這樣做取決于實(shí)際并發(fā)量我自己的經(jīng)驗(yàn)是中小型應(yīng)用把單例模式做好就夠用了等連接數(shù)告警了再上連接池也不遲。5.3 首屏性能調(diào)優(yōu)的幾個(gè)實(shí)際操作雖然 t3code 的默認(rèn)體驗(yàn)已經(jīng)不錯(cuò)但生產(chǎn)環(huán)境對(duì)性能的要求更高。我做過(guò)的幾個(gè)有效優(yōu)化排在這里按需取數(shù)據(jù)Prisma 的select和include要按頁(yè)面需要來(lái)避免一次findMany把幾十個(gè)字段全撈出來(lái)。Serverless 函數(shù)的執(zhí)行時(shí)間就是錢數(shù)據(jù)量小一點(diǎn)響應(yīng)自然快。開(kāi)啟 Next.js 的緩存策略對(duì)于不常變的數(shù)據(jù)可以用staleTime控制 tRPC 查詢的緩存時(shí)長(zhǎng)。例如文章列表五分鐘內(nèi)不重新請(qǐng)求api.post.list.useQuery(undefined, { staleTime: 5 * 60 * 1000, });嚴(yán)格區(qū)分動(dòng)態(tài)和靜態(tài)頁(yè)面博客首頁(yè)、關(guān)于頁(yè)這種內(nèi)容基本不變的盡量用靜態(tài)生成用戶中心這種強(qiáng)個(gè)性化的頁(yè)面再走 SSR 或客戶端渲染。能靜態(tài)就不動(dòng)態(tài)能讓邊緣緩存接住就讓它接住。5.4 日志、監(jiān)控和錯(cuò)誤上報(bào)做全棧項(xiàng)目時(shí)日志是最容易被忽略但又最重要的一環(huán)。t3code 腳手架只給了基礎(chǔ)結(jié)構(gòu)不包含任何監(jiān)控。我后來(lái)接了一款錯(cuò)誤監(jiān)控工具把 tRPC 的 errors 統(tǒng)一上報(bào)因?yàn)?tRPC 的錯(cuò)誤信息非常規(guī)范有code、message、path這些字段非常適合直接對(duì)接到監(jiān)控平臺(tái)上。我在src/server/api/trpc.ts的 errorFormatter 里做了一次全局?jǐn)r截export const t initTRPC.contexttypeof createTRPCContext().create({ errorFormatter({ shape, error }) { // 在這里上報(bào)錯(cuò)誤 return shape; }, });這樣線上如果出現(xiàn) Zod 校驗(yàn)失敗、數(shù)據(jù)庫(kù)異常、未授權(quán)訪問(wèn)我都能第一時(shí)間從監(jiān)控后臺(tái)看到具體是哪個(gè) procedure 出了問(wèn)題而不需要等用戶反饋。6. 回顧 t3code 這段時(shí)間的實(shí)際體驗(yàn)用 t3code 做了完整項(xiàng)目之后我有個(gè)很直接的感覺(jué)它把全棧開(kāi)發(fā)里的“隱形稅”砍掉了一大半。以前我要花很多時(shí)間維護(hù)前后端接口文檔、類型聲明、API 封裝現(xiàn)在這些成本降到了接近零寫業(yè)務(wù)代碼的密度變得很高。對(duì)我來(lái)說(shuō)它最大的價(jià)值不在代碼生成而在那套類型閉環(huán)帶來(lái)的心智負(fù)擔(dān)減輕。當(dāng)然它也不是銀彈。如果你的團(tuán)隊(duì)前后端完全分離后端需要面向第三方開(kāi)放 API那 tRPC 這套“服務(wù)端和客戶端強(qiáng)綁定”的方式反而會(huì)成為負(fù)擔(dān)。另外T3 Stack 的生態(tài)相對(duì)年輕很多企業(yè)級(jí)基礎(chǔ)設(shè)施的兼容方案需要自己探索比如前面說(shuō)的連接池、多環(huán)境數(shù)據(jù)庫(kù)遷移、CI/CD 流程都需要你額外搭建。但如果你是單兵作戰(zhàn)或者小團(tuán)隊(duì)想做一個(gè)類型安全、可快速迭代的 Web 應(yīng)用t3code 這套工作流非常值得試一下。剛開(kāi)始上手時(shí)多花一點(diǎn)時(shí)間把 Prisma schema、tRPC router、NextAuth 的關(guān)系理解透后續(xù)開(kāi)發(fā)體驗(yàn)的提升會(huì)大大超出你的預(yù)期。最后再分享一個(gè)小技巧。我用 t3code 時(shí)習(xí)慣把項(xiàng)目里所有數(shù)據(jù)庫(kù)寫入操作收斂到mutation里并且做好輸入校驗(yàn)和結(jié)果類型聲明。這樣一旦業(yè)務(wù)邏輯要調(diào)整改動(dòng)范圍會(huì)非常小不會(huì)在十幾個(gè)頁(yè)面里到處找散落的 set 調(diào)用。這種習(xí)慣配合 t3code 的類型推導(dǎo)讓整個(gè)項(xiàng)目即使經(jīng)過(guò)幾個(gè)月的迭代依然保持著比較好的可維護(hù)性。如果你正準(zhǔn)備上手一個(gè)新的全棧項(xiàng)目我建議你從最小閉環(huán)開(kāi)始——先不急著一次性引入全部模塊把列表查詢和一條數(shù)據(jù)寫入跑通感受一下“類型自己長(zhǎng)腳走完全?！钡捏w驗(yàn)再做后續(xù)擴(kuò)展也不遲。