前后端共享TypeScript类型定义的最佳实现方案咨询

针对前后端均使用TypeScript、两个团队独立协作的场景，按适用性从高到低推荐以下方案：

1. 契约优先的类型自动生成方案 #

这是跨团队协作的首推方案，核心是将API契约作为唯一的类型真值，避免人工重复编写类型带来的不一致问题。

• 操作流程：
  • 前后端团队共同评审确定中立的API描述契约，优先使用OpenAPI 3.0（REST场景）或者GraphQL Schema（GraphQL场景）编写
  • REST场景下，Node.js后端可直接用tsoa等工具从OpenAPI契约生成路由层的类型约束，前端用swagger-typescript-api等工具直接生成带类型的接口请求函数、请求/响应体类型
  • GraphQL场景下，共用一份Schema定义，通过graphql-codegen分别生成前后端的操作类型、钩子函数类型
• 优势：两个团队不需要互相依赖对方的代码仓库，仅需要对齐契约规范即可，类型修改走契约评审流程即可同步，完全避免冗余编写问题。

2. 独立私有类型包方案 #

如果团队不想引入契约生成工具，且类型变动频率较低，可以选择抽离独立类型包的方案。

• 操作流程：
  • 把公共的API请求/响应类型、公共实体枚举、基础参数类型抽成独立的npm私有包，仅存放TS类型声明或者TS源码，发布时编译为.d.ts文件
  • 前后端项目分别安装该类型包作为开发依赖
  • 类型更新时发布新的版本号，两个团队按需升级依赖
• 优势：实现成本极低，不需要修改现有开发流程，类型可以直接在代码中导入使用
• 注意事项：需要约定明确的版本同步规则，避免前后端依赖的类型包版本不一致导致的类型不匹配问题。

3. Monorepo共享目录方案 #

如果两个团队的代码仓库可以统一管理，协作流程非常紧密，可以选择Monorepo托管方案。

• 操作流程：
  • 将前后端项目放在同一个Monorepo中，单独设立公共类型目录存放共享的API类型
  • 前后端项目直接通过相对路径或者工作区别名引用公共类型
  • 可以用pnpm workspace、Turbo等工具管理Monorepo依赖，不需要额外发包
• 优势：类型修改可以和业务逻辑修改放在同一个PR中处理，同步成本最低

选型参考：如果两个团队协作流程独立、API变动相对频繁，优先选择契约优先方案；如果团队规模小、协作流程简单，类型包方案的落地成本最低。

内容的提问来源于stack exchange，提问作者Fay Chen