/tags/japicmp/ Recent content in japicmp on Hugo -- gohugo.io en Wed, 22 Apr 2026 23:00:00 +0800 /posts/microservice-contract-compatibility-defense-in-depth/ Wed, 22 Apr 2026 23:00:00 +0800 /posts/microservice-contract-compatibility-defense-in-depth/ 📦 本文基于的完整项目源码：meirongdev/shop 先说我的做法 如果你在做一组 Java 微服务，已经把 contracts 独立成 jar、每个 caller 自己写 client，你会很快遇到下一个问题：谁来阻止下一次 contracts 变更悄悄打穿所有下游？ 我现在更倾向的做法是——把五层防线组合起来，单独任何一层都不太够： ArchUnit COMPAT-01：每个 *Api 的 BASE_PATH 最好带显式版本段（/vN 或 /internal）。 ArchUnit COMPAT-02：事件契约最好容忍未知字段，并带上 schemaVersion。 ArchUnit COMPAT-03：任何 @ApiDeprecation 最好都声明 replacement。 japicmp 二进制兼容门禁：在 Maven verify 阶段对比新旧 contracts jar，binary-incompatible 变更直接 fail build。 WireMock 契约测试：consumer 侧冻结自己对契约的理解，任何反序列化漂移都暴露在单元测试阶段。 加上运行时的 ApiCompatibilityInterceptor（自动写入 X-API-Version / Deprecation / Sunset / X-API-Replacement）——这些一起构成了一个可执行的"契约安全带"。 这篇文章把 shop 项目里具体是怎么落地的写下来，也把近两年可以对照的业界参考一起贴上。 为什么只共享 contracts 还不够 上一篇 微服务契约共享的 Tradeoff 讲过——共享 @HttpExchange 接口是反模式，真正该共享的是 contracts（路径常量 + DTO）。问题是，一旦契约成了跨服务的共识，它就变成了一个隐式的耦合面： 某个 caller 在 OrderApi.