Monorepo

背景 Monorepo 解决了代码放在哪里，却不会自动解决谁可以依赖谁。一个工具包反向依赖业务层，很快会让整个仓库无法独立演进。 核心判断 画出允许的依赖方向，公共入口仅导出稳定契约。 项目引用描述编译依赖，包 exports 与 lint 管理实际导入路径。 构建缓存键包含源码、依赖版本和配置输入。 最小示例 下面保留核心逻辑；业务类型、调用入口和环境配置按项目补齐。 { "references": [{ "path": "../domain" }], "compilerOptions": { "composite": true, "declaration": true } } 边界与误区 project references 不等于访问控制，也不会自动阻止跨包深层导入。composite 项目的输出目录和包解析必须与运行方式匹配。 验证方式 新增一个故意违规的导入，确认 lint 能拦截；修改底层包，检查受影响包重建，干净环境仍能按依赖顺序完成构建。 小结 每个包只暴露稳定入口，规定依赖方向并阻止通过深层路径绕过边界。

背景与问题界定 随着前端项目规模的扩大，monorepo 已经成为中大型项目的标准组织方式。pnpm workspace + TypeScript + turborepo 的组合方案逐渐成为主流技术栈。但在 monorepo 中使用 TypeScript 面临着几个特有的挑战：首先是类型共享问题——公共类型定义放在哪个包中？如何在保持类型一致性的同时避免循环依赖？其次是构建性能——在包含 20+ 子包的项目中，全量类型检查耗时可达 30 秒以上，极大地影响了开发体验和 CI 流水线效率。再者是发布约束——当 A 包的类型定义引用了 B 包，A 的发布版本如何与 B 的版本保持一致？这些问题如果不在工程化层面系统性解决，monorepo 带来的类型一致性红利很快会被构建和发布摩擦抵消。 目标拆解与工程约束 类型包的独立版本管理：通用类型定义放在独立的 @company/types 包中，遵守 semver，变更时通过 changesets 自动生成 changelog。 增量编译替代全量编译：使用 TypeScript 的 Project References 或 tsc --build 实现依赖感知的增量编译，大幅减少全量检查的场景。 类型可见性控制：包的 package.json 的 types 字段只暴露公共类型，内部类型通过 tsconfig.json 的 paths 映射避免被外部引用。 构建管道的缓存优化：结合 turborepo 的缓存策略，未变更包的编译产物直接复用缓存，CI 构建时间控制在 3 分钟以内。 方案设计 类型共享架构 在 monorepo 中，类型共享有三种模式：集中式类型包、分布式内联类型 和 接口契约生成。我们推荐集中式类型包作为默认方案。 集中式类型包 ( packages/types ) 放置所有跨包共享的类型定义，包括 API 请求/响应 DTO、配置接口、事件定义和常量枚举。其他包通过 @company/types 导入。这种模式的优点是类型定义单一来源，不存在多个副本的同步问题。缺点是可能演进为巨大的类型垃圾场，需要通过子域拆分和定期清理来控制： ...

背景 这类问题在真实项目里很常见：高并发、复杂依赖、发布频繁、团队协作面广。只有把边界条件提前定义清楚，系统才会在压力下保持稳定。 实践要点 先定义目标：可用性、延迟、成本哪个优先。 把关键路径显式化：超时、重试、降级、回滚。 把策略写进代码和流程，而不是只停留在文档。 代码片段 const state = reactive({ loading: false }) 总结 工程实践最怕“看起来正确”。把策略做成可观测、可验证、可回滚的闭环，才能在生产环境里真正稳定运行。 稳定性不是某个技巧，而是持续的系统化约束。

背景 Monorepo 常见痛点是：改了一个子目录，多个镜像都触发重建。 改进方向 精细化 .dockerignore 子项目独立 context 共享基础层分离 COPY services/api/go.mod services/api/go.sum ./ RUN go mod download COPY services/api/ ./ RUN go build -o app ./cmd/api 总结 缓存命中率是 CI 成本的核心变量，Monorepo 必须做分层构建设计。 构建系统的复杂度，迟早会和代码规模一起增长。