很多团队把库的稳定性理解成“运行结果别错”，却忽略了另一层同样重要的契约：导出的类型。一旦一个类型、一个泛型参数顺序、一个联合成员名称被外部项目写进业务代码，它就不再只是你的内部实现，而是公共 API 的一部分。
TypeScript 库最容易踩的坑，不是功能不够，而是把太多实现细节顺手导出去了。用户一开始觉得类型很全、很好用，等你下一版重构内部实现时，才发现这些“好心暴露”的细节已经变成难以撤回的外部依赖。
公共 API 的起点，不是目录结构，而是你愿意长期承诺什么
很多库的导出面是这样长出来的：写完一个模块，顺手从 index.ts re-export；后面又有新场景，再继续 export *；最后库的公开入口几乎等于整个源码树的镜像。这种做法短期开发很快，但长期会让你失去演进空间。
更稳的思路是反过来问：
- 哪些类型是真正希望别人依赖的业务名词？
- 哪些只是为了内部推导方便而存在的辅助类型？
- 哪些实现可能在未来替换，但对外语义应该保持稳定？
公共 API 应该围绕这些长期语义组织，而不是围绕当前文件夹结构组织。
最危险的泄漏，不是函数实现，而是实现型类型细节
以下几类导出，最容易让库后续升级变得痛苦：
- 暴露只服务内部推导的条件类型和辅助泛型。
- 让调用方依赖内部枚举值、判别字段或中间态名称。
- 把复杂实现对象的完整形状直接导出，而不是给出更稳的接口层。
比如你原本内部使用 InternalRequestState<TMeta, TCache>，后来为了图省事把它导出。调用方开始在业务代码里直接判断 cachePhase、resolverMeta、sourceTag。接下来哪怕你只是想重构缓存层，也会发现用户已经把这些字段当正式协议在用。
真正稳的做法通常是：
- 对外给出语义化命名的类型，如
RequestSnapshot、RequestStatus。 - 把内部推导型工具留在私有实现层。
- 把可演进空间保留在内部映射和适配层，而不是直接开放实现对象。
Barrel 导出不是问题，盲目 export 才是问题
Barrel 文件本身没错，它只是组织导出的方式。问题在于很多团队把 barrel 当成“所有东西都能出门的自动通道”。
一个更健康的公共入口应该是精选导出，而不是通配导出：
// 推荐：明确选择公共面
export type { User, UserInput, UserRepository } from './user'
export { createUserService } from './service'
// 风险更高：把内部实现也顺手带出去
export * from './user'
export * from './service'
export * from './internal'
当你使用显式导出时，每增加一个公共符号都需要做一次承诺判断；而 export * 往往会让承诺在无意识中不断扩大。
公共类型设计要优先可读和可演进，不要让调用方继承你的复杂度
有些库作者会把内部非常灵活的泛型能力完整开放给用户，结果看似“高级”，实际把实现复杂度也一并转嫁出去了。典型信号包括：
- 一个对外类型带 4 个以上泛型参数。
- 调用方必须理解内部条件类型，才能用对 API。
- 错误信息几乎都在提示内部辅助类型，而不是用户的业务输入。
这类设计短期能显示“类型系统很强”，长期却会让库越来越难用。公共 API 更适合暴露经过压缩和命名后的语义层，而不是把内部类型推导树原封不动抬给用户看。
破坏式变更控制，不是发布前一天写 changelog，而是平时就保留缓冲带
很多破坏式变更并不是不能做，而是不能突然做。公共 API 治理更有效的方式通常是：
- 先新增替代接口，而不是立即删除旧接口。
- 给旧类型或旧字段标明弃用期和替换路径。
- 让一个版本同时兼容新旧写法，给下游迁移窗口。
- 在下个主版本再真正移除旧导出。
TypeScript 里尤其需要注意“类型层面的破坏式变更”。哪怕运行时没坏，只要类型收窄、字段改名、泛型默认值变化，都会让下游在升级时直接卡在编译阶段。
一个常见失败案例：导出太多 helper，最后谁都不敢删
某个内部工具库最初只有 6 个正式导出，后来为了方便同事“复用能力”，不断把内部 helper 和条件类型也放到了公共入口。半年后，库的导出面膨胀到 40 多个符号。团队想清理时才发现，没有人能确定哪些 helper 已经被外部项目直接依赖。
结果是两种成本同时出现：
- 不删，公共面持续膨胀，文档越来越难写。
- 要删，就要做一轮全仓搜索、迁移和兼容发布。
这类问题的根因不是团队不重视清理，而是最初没有区分“给自己用的类型工具”和“愿意对外承诺的公共类型”。
一个可执行的公共 API 审查清单
- 这个导出是否表达稳定业务语义，而不是内部实现细节。
- 如果未来替换实现，调用方是否还能不改代码继续使用。
- 这个类型是否需要暴露全部泛型，还是可以用更稳的命名类型包起来。
- 新版本的改动是否收窄了用户可传入或可读取的范围。
- 文档和示例是否只引用公共入口，而不是内部路径。
当这份清单固定下来后，公共 API 审查就不再只是发版前的补救动作，而会进入日常开发节奏。
总结
TypeScript 库的真正稳定性，不止来自实现正确，还来自对外导出是否克制。公共 API 设计要做的事，是把长期语义层和短期实现层拆开：前者稳定承诺，后者保留迭代空间。只要控制导出面、避免类型泄漏、给变更留缓冲带，你的库才不会因为“类型太全”而变成“升级太难”。
本批次专题导航：
- 工程边界：TypeScript 项目引用与 tsconfig 分层、TypeScript Monorepo 依赖边界治理、TypeScript 类型检查性能优化
- 协议协作：TypeScript 公共 API 设计、TypeScript 运行时校验与静态类型协作、TypeScript 与 OpenAPI 契约协同
- 落地复用：TypeScript 设计模式实战、TypeScript 测试数据构建
- 状态建模：TypeScript 事件系统建模、TypeScript 表单与错误状态建模
本系列导航：
- 如果你要继续收紧输入边界，接着读 TypeScript 运行时校验与静态类型协作
- 若你正在处理前后端协作，可顺着看 TypeScript 与 OpenAPI 契约协同
- 如果你想把抽象层和导出面一起做稳，再看 TypeScript 设计模式实战
延伸阅读：
