1. 先聊聊t3code到底是什么，以及为什么值得关注

先说结论：t3code不是某个公司出的商业框架，也不是某个大厂开源的黑科技，而是我个人在做TypeScript全栈项目时，自己沉淀出来的一套代码组织方案。它围绕“端到端类型安全”这一核心目标，把前端、后端、共享类型定义三块内容按模块拆开，用一套统一的配置和规范串起来，最终让整条业务链路从数据模型到接口返回，再到前端页面渲染，全程类型都是通的。

为什么我会折腾出这么一套东西？原因很简单——现有的全栈开发方案虽然多，但真正落地的时候总有几个绕不开的痛点。最典型的一个场景是：后端写了一套接口，返回的结构长什么样，前端完全要靠手写interface去猜。你猜对了，运气好；猜错了，页面跑起来才发现字段名差一个字母。更麻烦的是，当接口文档更新了，前端定义的DTO（Data Transfer Object）不会跟着自动变，结果就是联调阶段反复对着文档改类型，效率极低，还容易漏改。

t3code这套方案要解决的问题，就是在代码层面把前端、后端和共享类型真正绑在一起。不是靠文档约定，而是靠编译器和运行时校验强制保证。整个方案的核心可以概括成三点：

• 用monorepo结构管理代码，让前端、后端、共享包在同一个仓库内各居其位；
• 用TypeScript的project references能力，让不同模块之间可以精确引用类型，同时保持构建隔离；
• 用zod这类运行时校验库做统一出口，确保接口入参和出参不仅有静态类型，还有动态校验兜底。

这套思路适合谁来参考？如果你是独立全栈开发者、小团队的技术负责人，或者正在从传统的“前后端分离+接口文档”模式向“类型一体化”模式过渡，那t3code这套方案会给你一个非常具体的落地路径。它不要求你学新语言，也不要求你换掉现有的主要框架，只需要做一些目录重组和配置调整，就能把类型安全的水位整体抬高一截。就算你暂时不打算全部照搬，里面关于zod集成、monorepo配置、TS路径映射的细节，单独拿出来也是能直接用的干货。

接下来我会把整个方案的设计思路、技术选型、实操步骤和踩坑记录都拆开讲一遍。整个过程我会尽量按实际动手的顺序来写，包括每一步为什么要这么做，以及中途可能遇到哪些坑。

2. t3code的整体设计思路：TypeScript全栈项目为什么容易“断链”

动手写代码之前，得先把设计逻辑想清楚。t3code的第一版不是从技术栈开始选的，而是从“项目的代码到底是怎么断开的”开始排查的。这里说的“断开”，就是指类型在不同模块之间传递时失去关联。我把这种断链分成了三种典型场景。

2.1 第一种断链：后端持久层到接口层的类型丢失

很多项目一开始是好的，数据库有ORM模型，模型上有类型定义，后端Service层也有类型。但接口层往往就变味了——很多人习惯在controller里直接拼一个返回对象，或者把Service的结果做一层map之后返回。这一层map一旦不做类型标注，返回结构就变成了隐形的any，接口层和Service层之间就断了。前端拿到的接口数据，本质上是“没有类型背书的黑盒”。

t3code的解法是：在接口层强制要求定义“出参模式”。每个接口的返回不能直接从Service方法里裸返回，必须经过一个带zod schema（数据校验规则）的整形函数，把要传给前端的数据结构显式声明出来。这个schema同时也是类型推导的源头，前端不用自己定义interface。

2.2 第二种断链：前端API调用层到组件层的类型丢失

前端最容易断链的地方是API请求封装。大多数项目都会封装一个request.ts，但封装完之后返回的数据类型往往是泛型里的一个占位符——要么是any，要么是手写一份和实际结构可能对不上的interface。更糟的是，有些项目直接用axios的泛型参数来指定返回类型，传错了编译器也不知道，因为这是纯“断言”，没有任何运行时校验。

t3code的做法是：前端不直接调用axios或fetch，而是通过一个自动生成的API调用器来请求数据。这个API调用器以共享的zod schema作为依据，方法签名上的入参和出参都是根据schema自动推导出来的。前端组件调用时，参数类型不对，或者返回值某个字段不存在，IDE里直接就标红，根本走不到联调环节。

2.3 第三种断链：业务实体定义在不同地方各写一套

这是最隐蔽也最难治的一种断链。很多项目的业务实体，数据库里一套定义、后端代码里一套类型、前端代码里又一套interface，三者靠人肉同步。字段改了经常只改一处，另外两处就成了定时炸弹。

t3code把“单一事实来源”作为一条铁律：涉及跨端传输的数据结构，定义只能出现在共享包中。后端引用它的类型做数据校验，前端引用它的类型做表单和页面状态，谁都不允许自己另起炉灶。这个约束一旦建立，跨端的类型一致性从源头上就有了保证。

2.4 工具链选型的底层逻辑

整体设计定下来之后，选型就顺理成章了。仓库布局上我用pnpm workspace跑monorepo，原因很直接：多包仓库的依赖管理里，pnpm的符号链接机制是做得最干净的，安装速度快，磁盘占用也小，对ESM生态的兼容性好。TypeScript这边，用project references来管理不同包的编译边界，这样每个包的类型检查是隔离的，不会出现一个包里的类型错误拖垮整个仓库构建的情况。

zod这个库在这个方案里扛的是运行时校验的大梁。它跟TypeScript的配合方式是：先定义schema，然后通过z.infer把类型推导出来。这样一份定义同时服务运行时和编译期，不会出现“校验规则一套、类型声明一套”的割裂。选zod而不是yup或者joi，主要是看重它的类型推导能力——yup的类型推导在复杂对象嵌套时经常需要手动修正，zod在这块更顺滑，且对TypeScript版本升级的兼容性更好。

3. 关键技术选型与项目结构拆解：t3code的架构是怎么搭起来的

方案不是玄学，最后落下来都是具体的目录结构、配置文件和代码写法。这一节我把t3code项目的骨架完整拆一遍，重点说清楚每个部分承担什么职责，以及在搭建时有哪些必须注意的细节。

3.1 monorepo目录结构的设计逻辑

t3code的仓库结构长这样：

t3code/ ├── apps/ │ ├── api/ # 后端服务（Elysia或Hono） │ └── web/ # 前端应用（React/Vue均可） ├── packages/ │ ├── shared/ # 共享类型与schema定义 │ ├── api-client/ # 前端API调用器（基于shared生成） │ └── config/ # 共享的TS、ESLint、Prettier配置 ├── package.json └── pnpm-workspace.yaml

这个结构的关键点是apps和packages的分离。apps放的是可运行的应用，它们互相之间不直接引用，只通过packages下的共享包来通信。packages里的shared包是整个方案的核心，它不依赖任何框架，只放zod schema和类型定义。api-client包依赖shared，专门做前端请求封装。config包放的是各应用和包共用的配置文件，比如tsconfig的基础配置、ESLint规则集。

这里有一个很多人容易犯的错：在monorepo里直接把类型定义放在一个package里，然后让apps和web直接依赖这个package。这个思路本身没错，但如果没有正确配置TypeScript的composite模式，类型引用了半天编译不通过，包与包之间的边界很快就变成一团乱麻。solution是在shared（或其他包）的tsconfig里打开composite，并正确设置declaration和emitDeclarationOnly。

3.2 shared包的具体实现方式

shared包的核心不是“放一些interface然后导出”这么简单。因为t3code要求运行时校验，所以shared里放的是一组zod schema。例如用户相关的schema：

import { z } from 'zod'; // 数据库实体对应的基础schema export const UserSchema = z.object({ id: z.string().uuid(), name: z.string().min(1).max(50), email: z.string().email(), role: z.enum(['admin', 'user', 'guest']), createdAt: z.string().datetime(), }); // 创建用户的入参schema，和基础实体解耦 export const CreateUserInput = UserSchema.pick({ name: true, email: true, role: true, }); // 从schema推导类型，前端和后端都从这里拿类型 export type User = z.infer<typeof UserSchema>; export type CreateUserInputType = z.infer<typeof CreateUserInput>;

这段代码有几点值得展开。一是UserSchema.pick的用法，它把“创建用户时允许传的字段”和“用户实体完整的字段”区分开，避免了创建入参里带上id和createdAt的尴尬情况。二是z.infer的推导能力，在pick之后，CreateUserInput这个类型的字段结构也会精准对应，不会多出没用的字段。三是命名规范，schema用大写开头，type用PascalCase，这样在IDE自动补全时，schema和类型可以快速分辨，不会混淆。

3.3 后端集成：在路由层做校验与返回整形

后端在引入shared包之后，典型的做法是在路由定义中直接引用schema。以Elysia为例，路由可以写成这样（Hono的写法类似，只是把validator的位置换一下）：

import { Elysia, t } from 'elysia'; import { CreateUserInput, UserSchema } from '@t3code/shared'; const app = new Elysia() .post('/users', ({ body }) => { const user = createUser(body); // 内部业务逻辑 return UserSchema.parse(user); // 返回前用schema整形 }, { body: CreateUserInput, // 入参校验 } ) .listen(3000);

这里面的核心动作是UserSchema.parse(user)。这个parse不只是校验，它还有“整形”的效果——假设User实体里有个字段是数据库特有的（比如passwordHash），在parse之前手动把passwordHash删掉，parse之后的结构就完全符合schema定义的字段结构，不会有任何多余字段泄漏到前端响应里。这个习惯养成之后，接口“多返回字段”的问题基本上就绝迹了。

可能有读者会问，为什么不直接在后端用UserSchema当返回类型，还多包一层parse？原因是user对象从数据库查出来时，它的ts类型是Prisma或Drizzle生成的实体类型。这个类型可能比UserSchema多字段。如果不做一次schema过滤，虽然ts类型上可以通过“结构类型兼容”编译过去，但实际运行时字段还是带的。parse这一步是运行时层面的“结构裁剪”，和静态类型层面的“类型断言”是两码事。

3.4 前端集成：基于zod推导的API调用器

前端要消费后端的类型，最绕不开的步骤是把API调用器写好。t3code里api-client包的典型实现如下：

import { z } from 'zod'; export function createApi<Path extends string>(baseUrl: string) { return { async post<BodySchema extends z.ZodTypeAny, ResponseSchema extends z.ZodTypeAny>( path: Path, body: z.infer<BodySchema>, schemas: { body: BodySchema; response: ResponseSchema } ): Promise<z.infer<ResponseSchema>> { const res = await fetch(`${baseUrl}${path}`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(schemas.body.parse(body)), }); if (!res.ok) { throw new Error(`HTTP ${res.status}: ${await res.text()}`); } const data = await res.json(); return schemas.response.parse(data); } }; }

这个调用器的设计有两个精妙点。一是body: z.infer<BodySchema>直接把入参类型绑定到schema上，前端组件调用时的方法签名自带类型，参数错了IDE直接报错。二是返回值在parse成功之后，response是z.infer 的实例，类型和运行时数据结构是一致的，不会再出现“类型说好有name，运行时却没有”的灵异事件。

在具体的前端业务代码里，调用方式是这样：

import { CreateUserInput, UserSchema } from '@t3code/shared'; const api = createApi('/api'); const newUser = await api.post('/users', { name: '张三', email: 'zhangsan@example.com', role: 'user' }, { body: CreateUserInput, response: UserSchema } );

到这里，一条贯通链路已经打通了：前端组件 -> api-client -> HTTP请求 -> 后端路由 -> shared schema。前后端不再各维护一份类型，类型定义的全生命周期都在shared包里完成。

4. 实操全过程：从零到一跑通t3code项目的完整记录

光看结构和代码片段，还是会有人觉得没底。这一节我按操作顺序完整走一遍搭建t3code项目的流程，把每步的输入输出和中间遇见的坑都写清楚。

4.1 初始化monorepo与基础配置

第一步是创建仓库骨架。我用的是pnpm自带的workspace能力，在根目录创建pnpm-workspace.yaml：

packages: - 'apps/*' - 'packages/*'

然后创建根目录package.json，声明private为true，防止意外发布到npm。根目录的package.json主要作用是放统一的脚本，比如build、typecheck、dev等。typecheck这个脚本很重要，它负责全仓跑一次tsc类型检查，专门用于CI阶段把关。

接下来创建每个包自己的package.json。这里有个技巧：不用手动一个个写，可以在根目录先把shared包初始化出来，作为模板再复制。shared包的package.json关键项是：

{ "name": "@t3code/shared", "version": "0.0.0", "type": "module", "main": "./src/index.ts", "types": "./src/index.ts", "exports": { ".": "./src/index.ts" } }

注意main和types都指向src/index.ts，而不是dist。这个做法在monorepo开发阶段非常省心——不需要每次改代码都在包里构建一遍，前端和后端直接引用源码。只有需要发布到npm时才需要单独配置构建产物。

4.2 配置TypeScript project references

这一步是t3code方案里最容易出错的环节。如果tsconfig配置不对，包与包之间的类型引用会断得莫名其妙。我贴一份经过验证的配置。

根目录tsconfig.base.json负责放公共编译选项：

{ "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "bundler", "strict": true, "skipLibCheck": true, "composite": true, "declaration": true, "declarationMap": true, "emitDeclarationOnly": true, "outDir": "./dist", "baseUrl": ".", "paths": { "@t3code/shared": ["packages/shared/src/index.ts"], "@t3code/api-client": ["packages/api-client/src/index.ts"] } } }

核心项是composite: true和emitDeclarationOnly: true。前者的作用是告诉TypeScript这个项目可以被其他项目引用，后者是为了避免在开发时实际产出JS文件——类型声明就够了，真正的运行时代码由esbuild或tsx去处理。这样配置的优点是类型检查和实际运行解耦，t3code里的代码可以直接用tsx运行后端，前端用Vite的esbuild转译，两边都不需要面对tsc产物的兼容问题。

各包自己的tsconfig大致长这样：

{ "extends": "../../tsconfig.base.json", "compilerOptions": { "rootDir": "./src", "outDir": "./dist" }, "references": [] }

如果某个包依赖了shared（比如api-client），则需要加"references": [{ "path": "../shared" }]。references的意义是告诉TypeScript编译器先去检查被引用包的tsconfig定义，确认它的类型构建产物是最新的，然后再进行本包的类型检查。这样可以避免“本包编译时找不到别的包的类型声明”的尴尬情况。

4.3 实现共享类型包和后端联调

配置完成后，先把shared包的src/index.ts写上。我通常会按业务域把schema拆到不同文件里，比如user.ts、post.ts、order.ts，在index.ts里统一导出。这样做的好处是文件变多之后不会所有schema堆在一个大文件里，IDE的响应速度也会保持正常。

后端的初始化步骤里有几个容易忽略的点。第一步是在api包的package.json里加依赖：@t3code/shared: workspace:*。这里必须用workspace:*前缀，pnpm才会识别是本地包，而不是去npm registry找这个不存在的包。第二步是设置运行脚本，我用了tsx来跑开发环境：

{ "scripts": { "dev": "tsx watch src/index.ts" } }

tsx watch会自动监听文件变化，且原生支持TypeScript和ESM，不需要额外的构建步骤。相比ts-node，tsx的启动速度和ESM兼容性都要好得多，实测下来几乎没有配置上的意外。

4.4 前端集成与类型推导验证

前端部分我用Vite + React来示范，Vue和其他框架的思路一致。前端package.json同样依赖@t3code/api-client和@t3code/shared。在Vite的vite.config.ts里，加上别名配置，确保源码引用时能正确解析：

import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; import path from 'node:path'; export default defineConfig({ plugins: [react()], resolve: { alias: { '@t3code/shared': path.resolve(__dirname, '../../packages/shared/src/index.ts'), '@t3code/api-client': path.resolve(__dirname, '../../packages/api-client/src/index.ts'), }, }, });

设置别名是为了让Vite在开发时直接使用TS源码，不需要依赖包构建产物。这一步如果漏了，Vite大概率只能从node_modules里找包，而workspace包的通过symlink虽然存在，但Vite对symlink的兼容性在个别版本不太稳定，配别名是根除问题的最稳妥办法。

全部搭好后，在React组件里调用一次API，验证全链路：

const [user, setUser] = useState<User | null>(null); useEffect(() => { api.get('/users/123', { response: UserSchema }) .then(data => { setUser(data); // 此时data的类型是User，字段都有ts提示 }); }, []);

如果一切正常，IDE里data的字段提示是从shared的UserSchema推导过来的，而不是手动写的临时interface。这时候把后端某个schema的字段名改一下，前端组件里引用该字段的地方会立刻标红，类型断链问题被彻底暴露在编译期，再也不用靠“打开浏览器看console报错”来排查联调问题。

5. 常见问题与排查技巧实录

无论设计得再好，落到实操中总会遇到各种问题。这一节把我在折腾t3code过程中遇到的典型问题和排查思路整理成一份速查表，每一个都对应真实的踩坑记录。

5.1 类型引用失效、找不到模块的排查步骤

这个问题在第一次搭monorepo时几乎必现。现象是前端或后端代码里import @t3code/shared之后，IDE一直报红。常见原因有两个：一是workspace包的exports字段配置不正确，二是tsconfig的paths没有设置。排查步骤如下：

1. 先确认package.json里的exports是否指向了src下的入口文件。如果指向dist，就得先构建一次才能引用，开发阶段很容易忘记。
2. 再确认根tsconfig的paths是否写对了，baseUrl是否设置为根目录。路径映射只要有一处不对，tsc就找不到模块。
3. 确认pnpm-workspace.yaml是否真的包含了packages目录。有时候新增的包没被识别，可以在项目根执行pnpm ls --depth -1看看包列表里是否出现了@t3code/shared。
4. 最后检查IDE的TypeScript版本。VSCode内置的TS服务有时候不识别composite的references，需要手动重启TS server（Command+Shift+P，输入“TypeScript: Restart TS Server”）。

5.2 zod parse抛异常导致接口500的定位技巧

后端在用了UserSchema.parse之后，如果前端传的参数不符合schema规则，后端会直接抛ZodError，接口返500。很多一开始不熟悉zod的人会以为这是bug，其实这是预期的行为。问题是抛出来的错误信息对前端不友好，得统一做异常处理。

我的做法是在后端加一个全局错误处理中间件，把ZodError转换成400响应，并把错误明细按JSON结构返回：

import { ZodError } from 'zod'; app.onError(({ code, error, set }) => { if (error instanceof ZodError) { set.status = 400; return { issues: error.issues }; } set.status = 500; return { message: 'Internal Server Error' }; });

error.issues数组里包含了字段路径、错误原因和期望值，前端可以根据这个结构精准定位到哪个字段没填对。这个处理逻辑虽然不是t3code的核心，但在一开始就做好，能省掉大量联调期的扯皮。

5.3 前端拿到数据后ts类型和运行时不一致的排查

t3code已经尽力保证运行时和静态类型一致，但有一种情况仍然可能出问题：如果前端手动调用了某个API，而API响应内部变化了（比如后端在parse之前对字段做了非预期加工），那么前端的类型仍然可能和运行时差一层。这类问题排查的关键在于：永远信任parse结果，不要信任网络传输的原始数据。只要前端API调用器里带上了response.parse，运行时数据就一定会被校验一遍。如果经过parse还出现了字段缺失，那基本可以断定是schema定义出了问题，而不会是前端代码的问题。

还有一个排查技巧非常实用：在开发模式下开启zod的详细错误堆栈。在api-client包里加一行环境判断，当NODE_ENV不是production时，parse失败时打印完整错误信息，包括响应原文和schema结构。这一步能极大缩短定位时间。

5.4 构建与CI环境的特殊配置

开发环境跑通了，CI阶段又有新的坑。最典型的问题是CI的typecheck阶段不认识workspace包的源码，因为在CI里默认会用pnpm install安装依赖，但workspace包的源码引用依赖的是仓库内的源码路径，不是node_modules里的构建产物。解决方案是确保CI阶段直接运行pnpm typecheck时，tsc能通过references找到包的类型声明。由于tsconfig.base.json里设了composite和declaration，tsc在typecheck时本身就会先生成类型声明到dist，再根据references检查各包。因此CI机器上不能只装依赖就跑typecheck，还需要确认packages目录下的dist文件夹有生成权限。

我已经在无数个项目里吃过这个亏，所以现在都会在根package.json里加一条统一脚本：

{ "scripts": { "typecheck": "pnpm -r --parallel exec tsc --noEmit false" } }

注意这里的--noEmit false，它会让tsc在类型检查的同时产出类型声明文件。如果只做纯检查不产出，references在CI的干净环境下会报错。

5.5 IDE反应迟钝与TS性能优化

包多了之后，IDE的类型检查会明显变慢，特别是在大型组件文件里。t3code的monorepo结构天然给了优化余地：用project references把每个包隔离后，IDE只需要加载当前打开的包及其references，不需要全仓扫描。但如果你发现IDE还是卡，可以检查一下是否误把node_modules里的@t3code/shared加入到了tsconfig的include里。还有一个常见问题是VSCode的tsc版本和仓库依赖的TypeScript版本不一致。解决办法是在仓库根安装项目级别的TypeScript，然后在VSCode右下角或命令面板里选择“Use Workspace Version”。

6. 一些值得展开的经验细节

t3code这套方案在使用过程中，有几个点我觉得非常有价值，值得单独拿出来聊聊。它们不是核心架构的一部分，但对实际开发的流畅度和代码质量影响极大。

6.1 业务对象的schema设计边界

给共享包写schema时，最大的诱惑是“什么都要放进去”。以用户为例，数据库表里有id、name、email、passwordHash、createdAt、updatedAt，是不是都应该在UserSchema里定义？我的建议是：别贪多。Shared包里的schema应该是跨端传输的数据结构的契约，而不是数据库实体的完整镜像。passwordHash绝不应该出现在任何共享schema里，因为没有任何一个接口需要把密码哈希传给前端。正确做法是像前文写的，用UserSchema描述“对外暴露的用户结构”，再用Pick/Omit派生出创建、更新、列表等不同场景的入参schema。

坚持这个原则之后，API的返回结构会非常干净，接口层和前端的数据消费都变轻了。更重要的是，前端再也不会收到“字段比需要的多得多”的响应体，带宽和JSON解析开销都随之降下来了。

6.2 版本管理与破坏性变更的处理

shared包的schema一旦被多个app使用，就不可避免地会遇到“改字段”的问题。常规做法是直接改schema，然后前端同步改。但正式一点的项目里，更好的做法是先给schema加版本注解，或者用zod的.extend()保留旧版本的兼容：

export const UserSchemaV2 = UserSchema.extend({ fullName: z.string(), });

运行时可以让接口同时返回V1和V2版本（或通过header协商）。在中小项目里这么做有时显得繁琐，但如果你的项目会被多个前端平台（Web端、移动端、第三方开放API）同时消费，这个版本化习惯能避免非常多的线上事故。

6.3 与现有项目的渐进式融合

如果手里已经有一个成熟的TypeScript全栈项目，不必为了t3code方案推翻重来。渐进式迁移是我最推荐的路径。第一步，只把后端接口的返回结构用zod schema包一层parse。第二步，在共享包中新增schema定义，逐步把关键接口的数据结构固化下来。第三步，前端API层开始使用基于schema推导的类型，替换手写interface。每一步都是增量改动，风险可控，但已经能享受到端到端类型安全带来的好处。

我之前接手的一个项目就是通过这个路径逐步改造的。开始时只有两个接口用了共享schema，后来团队体会到改字段不用前后端同步排查的爽快后，自发把新接口都按这个模式来写。大概过了一个季度，整个项目的类型一致性水平就完全不一样了。

7. 最后再分享一个关于命名和心智的小经验

t3code这个名字，我自己用了一段时间后，慢慢把它当成一个组织代码的心智模型：Type-safeTransmissionToolchain，也就是“类型安全传输工具链”。码代码的时候，只要脑子里始终记着“消息要在前端和后端之间传输，传输的东西必须结构清晰、类型明确”，很多设计决策就会自动往正确的方向走。

如果你准备动手改造自己的项目，哪怕不采用整套t3code方案，我也强烈建议先从“后端接口返回必须过一道schema”做起。这个习惯一旦养成，你会很快感受到什么叫“类型即文档”，什么叫“改一处全链路自动更新”。等你跨过这个阶段，再回头看以前靠接口文档猜类型的日子，大概率就不想回去了。

这套方案的实际效果如何，最终还是得在自己的项目里跑一遍才知道。它适合有一定TypeScript基础、想提升全栈协作效率的开发者。碰到的绝大多数问题，原因都集中在配置细节上，不涉及特别晦涩的原理，所以不用有心理负担。直接照上面的步骤搭一个最小demo，跑通一个接口的链路，剩下的就水到渠成了。