Stripe 将 API 视为基础设施(如电网、供水),分享其六年中管理近百次向后不兼容升级的工程实践。文章从 Unix 接口契约的不可逆性切入,对比了传统主版本号方案(v1/v2/v3)的痛点——用户升级成本高、易被锁定、供应商维护旧版本分身乏术。Stripe 采用以发布日期命名的滚动版本(如 2017-05-24),每次只含少量增量改动,新用户首次请求自动锁定最新版本,并可通过 Stripe-Version 头或 dashboard 覆盖。底层通过 API Resource DSL 定义响应结构,版本变更封装为独立的 version change module,按时间顺序反向应用到目标版本;含副作用的变更用 has_side_effects 标注。该方案还实现了 API 变更日志自动生成、文档按用户版本标记不兼容字段。最后总结三条原则:升级要轻量、版本管理要成为 API 一等公民、旧版本维护成本要固定在模块内。