如果你也是个一闲下来就忍不住折腾新项目的人那你多半经历过这种循环技术栈选了一圈代码写了一堆最后烂尾收场。我手里这个t3code是过去大半年一直在维护的一个全栈代码仓库主线思路很清晰——TypeScript 优先类型安全贯穿始终。这篇文章不聊泛泛的口号直接把我怎么设计项目结构、怎么在几层数据流里落地类型约束、踩过哪些让人抓狂的坑以及沉淀下来的工程习惯全部摊开讲一遍。适合想搭一个长期维护型全栈项目、或者正在折腾 T3 系技术栈的朋友参考。1. 为什么会有 t3code一个全栈项目脚手架的自我修养1.1 名字背后的含义与技术选型逻辑t3code这个名字第一眼容易联想到 T3 Stack也就是很多人在聊的Next.js tRPC TailwindCSS组合。我实际选型时没有照搬全套而是借用了它的核心理念偏向前端友好的全栈架构坚持纯 TypeScript 的端到端类型安全。我抽掉了那些对当前项目不必要的部分保留了三件事Next.js App Router 作为 Web 应用的宿主框架负责页面、路由和服务端渲染tRPC 模式的 API 层让前端调用后端接口时能直接拿到类型推导结果TailwindCSS 负责样式同时被我约束成一套自己定义的 design tokens选择这套组合主要是看中它在迭代速度上的优势。全栈项目的痛点在于前后端交接API 文档写得不全、类型对不上、字段改名后前端不知道这套组合能把这类问题尽量压在编译之前解决。对一个人维护的项目来说少跑来回沟通就是实打实的时间。1.2 目录结构一个仓库如何同时承载类型定义、组件、业务示例我用的是 pnpm workspace 的 monorepo 结构目录长这样t3code/ ├── apps/ │ └── web/ # Next.js 应用 ├── packages/ │ ├── types/ # 共享类型定义与 API 契约 │ ├── utils/ # 通用工具函数 │ ├── ui/ # UI 组件库 │ └── config/ # 共享 lint / tsconfig / 环境配置 └── docs/ # 架构决策记录这个结构不是一次性定下来的。一开始我把类型散落在各个业务文件里后来才意识到类型定义应该是独立的、被显式引用的基础设施而不是文件之间的意外产物。把它们集中到packages/types所有 app 和 package 都从同一个地方 import字段定义改一处全网生效。packages/utils放的是不依赖任何框架的纯函数例如日期处理、金额格式化、数组分页。之所以单独拆包是因为这些函数在服务端、客户端和脚本里都会用到。packages/ui则是组件库初期先收拢 Button、Input、Modal 这类基础组件后期再往业务组件方向沉淀。单仓库的好处是改依赖、加工具链、跑联调都方便但需要注意 workspace 的版本管理。我用 changesets 管理发布和生成 changelog每次改包版本时依赖它的其他包会自动感知。1.3 面向谁我期望的读者和使用场景写这套项目时我给自己定了一个目标任何一次改动都必须能被回溯。所以文档不只是 README还包括架构决策记录。这个仓库适合谁首先是那些想跑通一个真实全栈项目、但不想被复杂工程化配置劝退的开发者其次是想参考类型安全最佳实践的进阶玩家最后是打算把个人项目长期维护下去的独立开发者。如果你只是想要一个能跑的 Demo这个仓库对你来说可能有点重但如果你想拿着它做基石持续往上加业务它的结构会越用越顺手。2. 类型安全不是一句口号t3code 里三层防线怎么搭2.1 核心类型定义层从数据库到界面的“单一事实来源”类型安全的第一层也是最重要的一层是让核心类型成为所有环节共同遵守的契约。我在packages/types里定义数据模型比如用户、文章、订单这些领域实体。export type UserRole admin | editor | viewer; export interface User { id: string; email: string; role: UserRole; profile?: UserProfile; createdAt: string; updatedAt: string; } export interface UserProfile { displayName: string; avatarUrl?: string; bio?: string; }这里有几个细节值得留意。一是createdAt和updatedAt这种字段直接用 ISO 字符串表示没有塞进自定义类型避免前后端序列化时出现不一致。二是可选字段用?明确标注例如profile可能不存在前端拿到数据后必须做空值判断类型系统会替你考虑这件事。如果业务模型既需要User这种完整形状又需要UserListItem这种精简形状不要靠复制粘贴用工具类型export type UserListItem OmitUser, profile | updatedAt { postCount: number; };这样新的列表类型始终跟随核心类型演进。我是从一次字段改名的教训里体会到的这条规则当时把nickname改成displayName全仓库大概有二十多处报错但有两处因为硬编码字符串绕过了类型检查上线后才暴露。从那一刻起所有接口字段一律走类型定义不打折。2.2 API 层把运行时错误提前变成编译期错误类型安全的第二层在 API 边界上。我用 tRPC 风格的 API 方式时最核心的点是输入和输出都要验证而不只是声明类型。类型声明只存在于编译期运行时要注意数据不符合预期的情况。以 Zod 作为校验库定义一个输入 schemaimport { z } from zod; export const createPostSchema z.object({ title: z.string().min(1).max(100), content: z.string().min(1), tags: z.array(z.string()).max(10).default([]), }); export type CreatePostInput z.infertypeof createPostSchema;然后在路由里用z.infer反推出 TypeScript 类型。这样输入类型既能在前端获得自动提示RBAC 的权限判断也能在这层做校验不过直接返回错误不会穿透到业务逻辑。zod 的 schema 和 TypeScript 类型之间是单向推导关系我习惯把 schema 当唯一来源。有些代码库先写 TS interface 再用z.object()去对齐两个来源容易产生漂移时间一长就出现类型和运行时校验不一致的问题。2.3 前端消费层的类型收敛与断言策略第三层防线是前端对接口响应数据的消费。tRPC 的调用方式会直接把返回类型传给前端但并非所有场景都这么顺利。比如本地存储读出来的数据或者从 URL query 里解析的参数类型系统在默认情况下都会给一个any或宽松类型。这类地方我会显式写解析函数import { z } from zod; const pageParamSchema z.object({ page: z.coerce.number().int().min(1).default(1), pageSize: z.coerce.number().int().min(1).max(100).default(20), }); export function parsePageParams(params: URLSearchParams) { const result pageParamSchema.safeParse({ page: params.get(page), pageSize: params.get(pageSize), }); return result.success ? result.data : { page: 1, pageSize: 20 }; }这么做有两个好处路由参数从字符串变成数字类型是精确的解析失败时回退到默认值行为明确。我一直保留一条心得绝对不要用as强行断言一个未知数据。as只是让你骗过编译器运行时报错一个都躲不掉。我宁可多写几行校验函数也不让脏数据在我的类型边界上裸奔。3. 写代码过程中的三个关键决策模块边界、配置管理、错误处理3.1 模块边界为什么我把工具函数单独拆成一个大包工具函数是最容易被随手塞进业务代码里的东西。项目初期一个formatDate可能只在一个组件里用过两个月出现第二个组件需要它再往后可能有五六个组件都调它。如果不给工具函数一个明确“住址”它们就会变成散落各处的复制粘贴。我把packages/utils当做一个独立包之后内部按模块分子目录date/日期格式化、时间区处理text/slug 生成、截断、脱敏array/分页、去重、分组guard/类型守卫与运行时断言同时遵循一个硬性规则utils 包内的函数不依赖 React、Next.js、数据库。因为一旦依赖了框架它就只能被特定环境使用丧失通用性。如果某个函数需要操作 React 状态或浏览器 API它会被移到packages/ui的 hooks 目录或者业务代码里。拆分过程做了挺大的重构但收益很直接每个包的职责一眼能看明白测试也能写得更薄。现在 utils 包的测试覆盖率维持在 85% 以上核心边界函数接近 100%。3.2 配置管理环境变量和特性开关的取舍全栈项目最容易在配置管理上翻车因为环境变量散落在前端、后端、数据库、CI 多个位置每个地方的访问方式还不一样。我的做法是配置类型管理方式使用注意通用配置packages/config下统一导出不包含任何密钥环境变量通过 zod schema 校验后再使用缺失立即报错不静默降级特性开关拆成独立配置分组合并按发布环境组合生效环境变量处理示例这是我维护成本最低的方案import { z } from zod; const envSchema z.object({ DATABASE_URL: z.string().url(), DATABASE_AUTH_TOKEN: z.string().min(1), NEXT_PUBLIC_APP_URL: z.string().url(), ANALYTICS_ID: z.string().optional(), }); const parsed envSchema.safeParse(process.env); if (!parsed.success) { console.error([t3code] Invalid environment variables:, parsed.error.flatten()); throw new Error(Missing required environment variables); } export const env parsed.data;这样做的好处是启动阶段就能发现问题而不是等请求到了数据库那一步才报错。现在很多框架自带zod风格的环境校验例如 Next.js 的experimental.typedRoutes配合next.config.ts思路一致。特性开关方面我不追求过度动态化。只有两类开关一类是上线前内部灰度用的另一类是紧急关闭某个高风险功能用的。前者在构建时按环境打包后者在运行时读取配置中心。不用的开关及时删掉否则代码里全是死人代码。3.3 错误处理Result 风格 vs 异常抛出的实际选择错误处理是类型安全项目里最容易分裂的地方。很多纯函数领域推崇 Result 风格因为它在类型层面强制你处理失败情况。但放到 tRPC 这种边界场景里全链路都套 Result 反而增加噪音。我在t3code里做了一个分层约定业务逻辑内部使用try/catch和自定义错误类型把可预期错误转换成带错误码的返回API 边界tRPC 的 errorFormatter 统一收敛输出{ code, message, details }结构前端消费用unwrap工具函数提取数据或错误避免层层判断export type ApiResultT | { ok: true; data: T } | { ok: false; code: string; message: string };用这种结构替换原本泛泛的throw new Error(something went wrong)后错误信息里终于能带上业务语义。前端可以直接根据code做文案映射或者跳转处理而不是用正则去匹配中文报错文案。这条线我犹豫了好几轮。最终选择混合方案的理由是边界上用模型化结果内部逻辑保留异常机制两者各管一段团队协作时心智负担最低。4. 实测排障记录会劝退新人的三个高频坑4.1 坑一Next.js 热更新把类型上下文搞丢开发时最痛苦的事莫过于热更新之后 tRPC 的类型推导突然变回any所有调用处开始报“类型不存在于类型上”的错误。最开始我以为是代码写错了反复检查看不出问题后来才发现是 TypeScript 编辑器服务和 Next.js 的缓存不同步。完整排查过程先重启 TypeScript 服务无效果再清.next缓存重启 dev server短暂恢复后又复发最后定位到是 editor 的 TS server 在 workspace 包频繁变更后没有重新加载类型上下文。解决办法其实不复杂把tsconfig.json里的baseUrl和paths简化让所有 workspace 包都通过 package name 直接 import而不是路径别名。同时给 VS Code 配置了typescript.tsserver.enableProjectIsolation重启一次 TSServer 就能规避开。遇到这种诡异问题的排查心态就是先怀疑缓存再怀疑配置最后才怀疑代码逻辑。顺序反了会浪费非常多时间。4.2 坑二tRPC 路由类型偶尔“失灵”另一个高频问题是路由调用处拿不到自定义的返回类型。最初我写了一个解析器export const getUserById protectedProcedure .input(z.object({ id: z.string().uuid() })) .query(async ({ input }) { const user await db.user.findUnique({ where: { id: input.id } }); return user; });前端调用时data被推断为User | null本来没问题。但后来我加了业务逻辑导致返回值有时候是一个对象有时候是一个 Promise还有错误分支返回undefined。前端再通过useQuery取数据时类型开始不稳定一个分支处理漏掉就报错。真正的问题在于我对输出类型没有显式声明完全依赖推断而推断在复杂分支下不可靠。我给所有 router 的 query 方法加上了显式返回类型注解同时把可能为空的查询结果统一转成可辨识结果export const getUserById protectedProcedure .input(z.object({ id: z.string().uuid() })) .query(async ({ input }): PromiseApiResultUser { const user await db.user.findUnique({ where: { id: input.id } }); if (!user) { return { ok: false, code: USER_NOT_FOUND, message: User not found }; } return { ok: true, data: user }; });想让类型系统稳定依赖推断省事但风险大显式标注边界输出才是最稳的。这种场景下多写几个字母换来全链路类型透明非常值。4.3 坑三部署时 Tailwind 类名被裁剪样式问题看着不大但真出现时一样劝退。我在packages/ui里封装组件其中用了类似bg-${color}的类名拼接开发时一切正常一部署到生产环境颜色全灰。原因是 Tailwind 的 JIT 扫描器没有把这种拼接出来的类名当作完整字符串它扫不到bg-red-500就不会生成对应样式。编译时没问题运行时才发现。解决方案有两个改用安全列表在 Tailwind 配置里显式声明不会动态出现的类名export default { safelist: [bg-red-500, bg-blue-500, text-white], }更推荐的做法是彻底杜绝字符串拼接改用完整的类名字典const colorClassMap: Recordstring, string { primary: bg-indigo-500 hover:bg-indigo-600, danger: bg-red-500 hover:bg-red-600, success: bg-green-500 hover:bg-green-600, };现在新代码一律不写拼接类名只允许在字典里全量声明。这个问题花费了我半天排查根源就一句话动态类名在 Jamstack 构建体系里是个定时炸弹。5. 从 t3code 沉淀下来的工程习惯代码规范、生成脚本、文档5.1 lint-staged TypeScript checks 的本地检查链单靠个人自觉维护代码质量不现实我把检查链条做进了 Git 钩子里。提交代码时 lint-staged 会只检查本次变更的文件跑一遍 ESLint、Prettier 和tsc --noEmit三条全过才允许 commit。package.json里配置看起来像这样{ lint-staged: { *.{ts,tsx}: [eslint --fix, prettier --write, tsc --noEmit -p tsconfig.json] } }注意这里的tsc --noEmit是针对整个项目跑全量类型检查而不是只查当前文件因为类型错误往往跨文件。配合 husky 的 pre-commit 钩子稳定运行半年之后仓库几乎没出现过“类型错误被合到 main 分支”的脏数据。这条检查链最关键的点在于把它放在提交之前而不是之后。等 CI 报错再回头改不仅反馈周期长还会打断开发状态。5.2 类型生成与 mock 数据让前后端并行更顺畅单人项目不太需要严格的分工协作但当我同时维护多个小项目时类型生成的瓶颈依然存在。数据模型一旦改了基础类型、zod schema、mock 工厂三个地方都要跟着动手动改不仅累还容易漏。我从一个真实教训里意识到给数据模型加字段时接口类型更新了但 mock 工厂没跟上导致测试环境校验失败。此后我把 mock 工厂的生成规则固化下来export function createUserMock(overrides: PartialUser {}): User { return { id: crypto.randomUUID(), email: testexample.com, role: viewer, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), ...overrides, }; }所有 mock 工厂统一收在packages/types/test/目录下通过一个脚本在开发环境和测试环境分别引用。注意一个细节crypto.randomUUID()在 Node 18 以上可用但部分旧 Node 版本没有这个全局方法需要留意运行时环境。5.3 项目文档为什么我把架构决策记录写进仓库文档最大的价值不是今天写的而是三个月后回头看时能让当时的自己明白“为什么这么做”。我在docs/下放了一组 ADRArchitecture Decision Record每篇极短就三段上下文、决策、后果。比如有一条记录是关于 API 输出格式的ADR-0005API 输出统一使用 ApiResult 包装上下文错误信息无法携带业务语义前端不得不硬编码判断。决策所有 query 方法返回{ ok, data }或{ ok, code, message }结构。后果前端消费路径统一但写起来稍显繁琐后续可引入 unwrap 工具简化。这种文档不需要长篇大论每一篇花 10 分钟写未来回溯时能省下好几个小时。我强烈建议项目在创建初期就建立这个习惯而不是等架构腐化后才想起补文档。写在最后一些实际维护中的体会t3code这套代码用了大半年最大的实际体会是类型安全不是“多写几个 interface”而已它需要你认真设计类型边界、API 契约和错误模型并把这些规则落到工具链里。踩过热更新缓存、类型推断不稳定、动态类名被裁剪这些坑之后我对“框架默认配置不等于最佳实践”这件事有了更深的理解。如果你打算搭一个长期维护的全栈项目参考这套思路时建议从小处做起先把类型定义收拢到一个包再给 API 加统一的错误结构最后把检查链挂进 Git 钩子。不用一步到位但每一步都要有明确收益。最后再分享一个具体技巧我会在每个包的业务入口放一个index.ts名为“同名导出”的规范文件只负责 re-export 公开 API内部文件路径一概不暴露。这样任何跨包引用都能被追踪重构时只需要调整一个文件。就是这些看着不起眼的小习惯让项目的可维护性在不知不觉中拉开差距。