围绕 OpenAPI 的 Contract First 实践笔记：工具栈如何拼、AI 怎么起草 spec、团队同步机制、breaking change 治理、常见坑的对策，以及老项目的迁移路径。

以问答方式拆解我在 Shop Platform 中对 API 与 event contract 的兼容性保障：BFF 对外用 oasdiff 守 OpenAPI spec；内部 BFF→MS 和 MS→MS 用 JSON Schema 快照补 japicmp 的盲区；Kafka 事件用相同手法加 per-event schemaVersion。

BFF 与微服务之间到底该共享到哪一步？本文从 Shop Platform 的 monorepo 实践出发，拆解共享 contracts、共享 client、契约测试三种思路在 polyrepo 下的 tradeoff，并记录我目前更倾向的落地方式。

介绍 OpenAPI 3.1 相比 3.0 的几项核心变化：JSON Schema 2020-12 对齐、nullable 语义重构、webhooks 原生支持，以及我在项目里做升级验证时看到的收益与边界。

在 Gateway + BFF + Domain Service 架构下，记录一种用 Spring Cloud Gateway MVC 和 SpringDoc 聚合 OpenAPI 文档的做法，方便前后端协作和接口自查。