简介面向需要进阶TypeScript与Vue3的开发者资源以类型系统为切入口覆盖条件类型、映射类型、装饰器、全局声明文件等核心难点并通过Vue3TSPinia项目演示类型在真实业务中的落地方式。配套的Vite配置、TS配置、Turborepo工程化、ESBuild打包与VSCode调试文件可帮助读者快速搭建从依赖安装、类型检查到打包调试的完整前端开发链路省去从零摸索配置的时间。包体共15个文件以ts源码为主承担类型练习与项目逻辑json用于工程与依赖配置vue组件展示页面结构md则为说明文档整体仅8KB轻量而紧凑。所有代码均为手动原创编写注释完整并附有详细安装运行教程便于对照学习类型体操与模块化配置思路目录按类型练习和Vue3工程分区也可作为实际项目开发时的参考蓝本。目前已有41人学习适合前端进阶者深度研读。 做全栈项目真正让人难受的往往不是功能写不出来而是改需求的时候一个类型报错炸出一串连锁修改。TypeScript的类型系统加上Vue3的组合恰恰是解决这件事最顺手的路子。这次要分享的是一个基于TypeScript类型系统与Vue3的全栈项目实战源码它不是demo而是把前端展示层、后端服务层、数据库访问层全部串起来的一套完整工程。整个项目从schema定义到接口返回、再到前端组件props全程TypeScript写到底前后端共享同一套类型定义。这个做法带来的直接收益是接口文档的半壁江山其实是编译器在维护只要后端改了返回结构前端编译立刻报错根本不用等联调阶段再去对字段。如果你正在学TS和Vue3或者刚从前端转向全栈开发这篇文章能帮你把这两件事串成一条清晰的路线。1. 整体设计与技术选型1.1 项目定位不是脚手架是一套可以复用的全栈工程这个源码项目包含了一个常见业务系统最典型的几个模块登录鉴权、用户管理、内容列表、基于权限的动态路由。功能上不算复杂但链路是完整的数据库表 - ORM模型 - 后端路由 - 接口返回 - 前端api层 - 组件状态每一个环节都有类型覆盖没有一处是用any糊过去的。为什么强调“原创源码”而不是“项目脚手架”因为脚手架给你的是目录和依赖而这套源码的价值在于类型定义的组织方式。你在网上随便搜Vue3项目能看到一堆components、views、router的目录结构但很少有人把shared/types这种跨端类型层单独拿出来设计。这套源码里每一个类型定义文件都回答了三个问题这个类型属于哪一层、它为什么出现在这里、谁可以引用它。把这套思路吃透换任何业务场景都能套用。1.2 技术选型的几个关键决策先列一下技术栈全貌后面再逐个解释为什么这么选。技术栈选型选择理由前端框架Vue3 Composition APIsetup语法糖对TS类型推导支持最好几乎不需要手动标注props类型构建工具Vitedev启动快esbuild不做类型检查类型问题交给CI阶段统一卡状态管理Pinia天然支持TSstore定义本身就是类型定义后端框架Node.js Express轻量、直接配合TS类型推导完全够用不引入重量级框架ORMPrisma从数据库schema自动生成TS类型省掉手写DTO的体力活数据库SQLite / PostgreSQL本地开发用SQLite部署切换PostgreSQLPrisma屏蔽差异类型共享pnpm workspace shared包前后端引用同一份类型定义从根上消灭重复代码Vue3在TS支持上相比Vue2是质变。Vue2的Options API里mixin一混入类型推导基本就崩了最后全部退化成any。Vue3的setup函数和defineProps泛型让编译器可以从模板中直接推导出props类型源码里几乎看不到手工编写interface描述props的代码因为语法糖已经能做得很干净。1.3 目录结构设计源码采用pnpm workspace管理核心目录结构是这样的project-root/ ├── shared/ │ └── types/ │ ├── api.ts # 统一响应、分页等公共类型 │ ├── user.ts # 用户相关类型 │ └── article.ts # 内容相关类型 ├── server/ │ ├── prisma/ │ │ └── schema.prisma │ ├── src/ │ │ ├── routes/ │ │ └── services/ │ └── tsconfig.json ├── client/ │ ├── src/ │ │ ├── api/ │ │ ├── components/ │ │ ├── composables/ │ │ └── router/ │ ├── vite.config.ts │ └── tsconfig.json └── package.json设计上有一条铁律shared只放类型定义不放任何函数和业务逻辑。原因是shared会被server和client同时引用如果往里面塞了运行时逻辑构建时要么把后端代码打进前端包要么产生循环依赖问题非常难排查。类型就安全得多编译完就消失了没有任何运行时成本。2. 类型系统设计的几个核心环节2.1 类型链路的起点数据库schema到TS声明这套源码的类型链路是从数据层开始的。Prisma的schema即类型定义比如用户模型model User { id String id default(cuid()) email String unique name String? passwordHash String role Role default(USER) createdAt DateTime default(now()) updatedAt DateTime updatedAt } enum Role { USER ADMIN }跑完prisma generate之后Prisma会自动生成完整的User类型声明。但注意一个关键决策前端不直接引node_modules/.prisma/client里的类型而是由shared层再封装一层// shared/types/user.ts export interface UserInfo { id: string email: string name: string role: USER | ADMIN }为什么多此一举因为数据库实体字段和暴露给前端的字段并不一样。比如passwordHash这种敏感字段如果前端直接拿数据库User类型编译不会报错但代码里就可能无意间把密码哈希传到视图层。shared层的UserInfo只保留视图需要的内容相当于在类型层面划了一条数据边界。这个封装不是重复劳动而是在源头截断脏数据。2.2 泛型在业务层的实际落地泛型是这套源码里用得最频繁的类型工具。后端接口返回结构几乎是固定的如果用interface写死每个接口都要重复定义一遍类似的形状。源码里定义了一套通用响应类型// shared/types/api.ts export interface ApiResponseT { status: success | error data?: T error?: { code: string; message: string } } export interface PagedResultT { list: T[] total: number page: number pageSize: number }前端请求方法直接带泛型调用async function getUserList(page: number) { return http.getApiResponsePagedResultUserInfo(/api/users, { params: { page } }) }这行代码的效果是在调用getUserList的地方.data.data.list的类型自动被推导为UserInfo[]每个字段都有补全和检查。如果后端字段名改成了items前端编译立刻报错。相比之下如果写成http.get(/api/users)然后res.data.data.list那list就是any类型体系在这段代码就断了。2.3 类型收窄与品牌类型的应用业务代码里最常见的类型判断就是成功/失败分支。源码里的ApiResponse用联合类型表达得比interface更精确export type ApiResultT | { status: success; data: T } | { status: error; code: string; message: string }这是典型的可辨识联合discriminated union。处理时只要switch一下statusTS就会自动收窄类型if (result.status success) { // 这里 result.data 的类型是 T全部字段可用 render(result.data) } else { // 这里 result.message 是可访问的result.data 不存在 showToast(result.message) }在success分支里TS知道data一定存在不会报可能为undefined的错在error分支里data字段直接不存在想点也点不出来。这种写法比一个松散的ApiResponse要严格得多杜绝了“忘记处理失败分支”的静默bug。源码里还有一个比较发烧的设计——品牌类型branded type。业务里userId和articleId都是string但混用的时候很危险把文章id传给用户查询函数编译不报错运行结果却是错的。品牌类型可以把它们区分开export type UserId string { readonly __brand: unique symbol } export type ArticleId string { readonly __brand: unique symbol } export function asUserId(id: string): UserId { return id as UserId }函数签名一改传错ID类型编译期就拦截。代价是多写一个asUserId转换函数但对有强约束需求的函数入口这点成本完全值得。2.4 前后端共享类型的三种组织方式共享类型有几种常见做法这套源码选择了pnpm workspace包。对比一下方式实现优点缺点相对路径共享client/src引../../shared/types简单直接跨包路径容易把server代码卷进构建workspace包app/shared作为独立包职责清晰依赖关系明确需要配monorepo有学习成本独立类型仓库单独npm包发布可复用多项目发布更新麻烦版本管理成本高源码最终用的是workspace包方案。shared里的类型通过app/shared包名引用不会出现“上一秒还在调类型下一秒把server模块整个import进来”的问题。还要强调一句共享类型里只放interface、type、const枚举坚决不放函数实现否则类型包就变质了。3. Vue3工程中的TypeScript整合实践3.1 setup语法糖与defineProps/defineEmitsVue3的script setup语法糖和TS配合得有多好写起来才知道。最典型的是props声明新代码推荐用泛型写法而不是运行时声明// 推荐泛型声明拿到的类型是编译期推导的 defineProps{ user: UserInfo }() // 不推荐运行时声明类型容易丢失 defineProps({ user: { type: Object as PropTypeUserInfo, required: true } })两种写法都能跑但泛型写法在模板里点props属性的时候会有完整补全第二种在某些场景下会退化成unknown或Object。同样的思路适用于emitsconst emit defineEmits{ (e: update, id: string): void (e: delete, id: string): void }()这样触发事件时事件名和参数都会被严格检查父子组件之间的协议在编译期就锁定了。源码里组件之间传参基本都走这种方式基本靠编辑器提示就不会把事件名拼错。3.2 组合式函数composable的类型设计组合式函数是Vue3代码复用的核心单元源码里设计了一个通用分页组合式函数export function usePagedListT( fetcher: (page: number, pageSize: number) PromisePagedResultT, pageSize 10 ) { const list refT[]([]) const page ref(1) const total ref(0) const loading ref(false) async function load() { loading.value true try { const res await fetcher(page.value, pageSize) list.value res.list total.value res.total } finally { loading.value false } } return { list, page, total, loading, load } }调用时传入的fetcher返回什么类型list就会被推导成什么类型。比如usePagedList(loadUsers)list自动是RefUserInfo[]模板里点u.name有补全写错了有报错。这个设计的好处是一个usePagedList可以服务所有分页模块但每个模块拿到的类型精确且独立。3.3 动态路由与权限控制的类型安全很多项目一到动态路由和权限判断就开始用any最常见的写法是route.meta.role user.role然后route.meta被当成任意类型处理。源码里的做法是先扩展vue-router的RouteMeta类型declare module vue-router { interface RouteMeta { title: string requiresAuth?: boolean permission?: string[] } }扩展之后开发者在路由配置里写meta时编辑器会提示这三个字段权限判断钩子里的route.meta也自动获得了类型检查。不再需要手动断言也不需要(route.meta as any).permission这种自欺欺人的写法。动态路由生成菜单的逻辑也保持了类型一致后端返回的权限列表是string[]前端根据它在路由表里筛选出可以访问的路由最终生成菜单树。整个过程filter函数的参数都明确是RouteRecordRaw不会因为动态添加路由就把类型丢了。3.4 关于TypeScript 7.0的一个配置提醒最近不少项目升级TypeScript版本后编译会打出这样一个警告option baseurl is deprecated and will stop functioning in typescript 7.0.。很多老项目的tsconfig.json里都写了baseUrl: .配合paths做路径别名。TypeScript 7.0会彻底移除baseUrl选项旧配置会直接失效。这套源码里已经提前处理了这个问题。tsconfig里不写baseUrl路径别名直接用{ compilerOptions: { paths: { /*: [./src/*] } } }实测下来TS 5.x开始paths本身可以基于tsconfig所在目录解析不需要baseUrl前置。同时vite.config.ts里用resolve.alias指向src目录两边各自配置互不干扰。类型检查和构建都正常lint也没有报错。如果你的项目还在用baseUrl: .建议趁早改掉不然升级到7.0那天所有路径别名会一夜之间全挂。4. 全栈联调与常见问题排查4.1 利用ReturnType推导后端接口类型全栈项目最容易出现的类型问题就是前端手写接口类型后端口是心非两边对不上。源码里解决这个问题的思路是类型来源尽量往后端函数的返回类型上靠。后端定义一个数据查询函数返回类型清晰地表达出数据形状export async function fetchUserList(): PromiseUserInfo[] { const rows await prisma.user.findMany() return rows.map(row ({ id: row.id, email: row.email, name: row.name, role: row.role })) }路由处理函数调用它把结果包成统一响应后返回。前端就能直接引用这个函数的返回类型而不需要自己再写一遍UserInfo[]import type { fetchUserList } from app/server type UserListResult AwaitedReturnTypetypeof fetchUserList这种做法的前提是后端函数返回值不能有any不能有隐式类型丢失。一旦后端函数签名改变前端编译立刻报错联调阶段大部分“字段对不上”的问题就消失了。这套源码没有引入openapi代码生成因为Prisma已经覆盖了数据层类型的来源手工维护API函数返回类型足够可靠。4.2 统一异常建模ResultT后端异常处理是类型最容易崩塌的地方。源码里定义了一套前后端共用的Result类型export type ResultT | { ok: true; data: T } | { ok: false; code: string; message: string } export function okT(data: T): ResultT { return { ok: true, data } } export function fail(code: string, message: string): Resultnever { return { ok: false, code, message } }后端所有接口统一返回Result前端api层拿到后先判断ok再取data。这比裸返回数据或裸抛异常要清晰得多失败情况被建模成类型的一部分前端if判断的时候TS会帮你收窄不会出现“data可能为空但代码直接用了”的隐蔽问题。ResultT还有一层额外的好处把错误处理从“例外”变成“常态”。前端只用处理ok分支然后放心地拿dataerror分支统一走全局弹窗或者错误提示逻辑。源码里后端所有服务函数都返回Result前端所有api方法都解码成功后返回业务数据错误提示在拦截器里统一处理业务代码干净不少。4.3 常见问题速查表这套源码开发和联调过程中遇到的问题不少整理成一张速查表以后遇到直接对照场景典型报错/现象解决思路路径别名找不到Cannot find module /xxxtsconfig的paths和vite alias两边都要配或直接换相对导入泛型推导丢失返回类型变成unknown/any给泛型加约束或用satisfies关键字props类型不生效模板里props一直是any改用definePropsT()泛型写法后端改类型前端没报错共享类型没有更新检查引用路径重启dev server让workspace包重新链接类型检查越来越慢vue-tsc耗时几十秒开发时用vite编译不做类型检查把类型检查移到CI同一类型出现两份共享类型在包里有两份定义用pnpm workspace软链保证全项目唯一定义最隐蔽的问题是“同一类型两份定义”。曾经遇到前端和后端各自在package.json里依赖了不同版本的app/shared结果就是两个UserInfo接口长得一模一样但TS认为它们不是同一个类型赋值怎么都不通过。解决方式是让shared包统一走workspace协议链接全项目只有一个物理实例。4.4 类型检查性能与CI落地的取舍Vite开发时用esbuild转译TS不做类型检查所以dev启动和热更新都很快。但这也意味着开发过程中类型错误不会被发现。源码项目里的方案是在CI和pre-commit阶段跑完整的类型检查命令{ scripts: { typecheck: vue-tsc --noEmit tsc -p server/tsconfig.json --noEmit } }client和server各自有独立的tsconfig.json分开检查互不干扰。这样设计后开发时速度不受影响提交和合并前类型问题会被自动拦截。源码里还用了一个小技巧在package.json的pre-commit钩子中只检查变动的文件范围避免全量检查拖慢提交速度。最后再说几句写这个全栈项目源码最大的收获不是多记了几个类型工具而是理解了类型安全是设计出来的不是检查出来的。如果只在代码后面补类型标注类型系统最多帮你报报错但从数据模型、接口协议、组件边界的角度去设计类型它就成了项目的文档、契约和自动化测试三合一。建议你可以先做一件小事把ResultT和分页类型抽到你自己的项目里用在两三个接口上试试。跑顺之后你会发现自己写代码的时候会下意识先想清楚“这个数据的类型到底长什么样”再动手写逻辑。等到这个习惯养成了前端转全栈的路就顺了一半。本文还有配套的精品资源点击获取