围绕真实项目里常见的 Liquibase（XML）反模式，按问题整理我目前更倾向采用的做法：从 changelog 怎么组织、changeSet 怎么命名，到大表 DDL、K8s 下的锁和回滚，最后是 CI 里怎么把这些挡住。

微服务规模增大后我开始补的两类结构化文档，问答体：ADR 记下为什么这样选，catalog-info.yaml 记下这是什么、归谁、依赖什么。

API 与 event contract 的兼容性保障按问答拆开：BFF 对外用 oasdiff 守 OpenAPI spec，内部 BFF 到 MS、MS 到 MS 用 JSON Schema 快照补 japicmp 的盲区，Kafka 事件再加 per-event schemaVersion。

只共享 contracts 往往还不够。按我目前的理解，更稳妥的做法是把 ArchUnit、japicmp、Deprecation/Sunset 头、ignore-unknown、WireMock 组合起来，Shop Platform 里的落地方式和几份可参考资料放在一起。

多模块 Maven 单仓微服务平台里，脚手架我选了 Maven Archetype 而不是 Spring Initializr，选型理由、六类 Archetype 的分层逻辑、为什么 Archetype 本身也要有测试、版本怎么维护，都收在这一篇。

Tracing 断链很少是 @HttpExchange 能解决的问题。能不能把 trace 和业务上下文一起跨服务传下去，取决于 W3C Trace Context、baggage 白名单和注入的 RestClient.Builder 这三样。

多仓库微服务的文档体系，我最后用的是中央架构 Repo 加各服务 Repo 内的 /docs/ 目录，再用 Docusaurus 收成统一入口，文档贴近代码，检索入口只有一个。

接入真实支付前，得先把支付抽象和 provider 边界理顺。Shop Platform 目前跑通的是 PaymentIntent 抽象和 Mock 与真实网关的切换，webhook、退款幂等和 Payment Element 还没落地。

BFF 与微服务之间到底该共享到哪一步？Shop Platform 的 monorepo 实践之外，共享 contracts、共享 client 和契约测试在 polyrepo 下各有 tradeoff，我目前更倾向其中一种组合。

在 code agent 普及的背景下，我在 Shop Platform 用 ArchUnit 作为可执行的 harness，它在微服务、monorepo 和普通 repo 里的落地方式各不相同。