/tags/archunit/ Recent content in archunit 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. /posts/archunit-harness-microservices-monorepo/ Tue, 21 Apr 2026 12:54:15 +0800 /posts/archunit-harness-microservices-monorepo/ 📦 本文基于的完整项目源码：meirongdev/shop 背景：在 code agent 时代重新谈 ArchUnit 这两年很多团队都在引入 code agent。它们写代码的速度很快，能补样板、改依赖、重构包结构、批量修复低级问题，但也因此更容易把"本来只存在于文档和 review 习惯里的约束"绕过去。 下面这些问题，人在赶时间时会犯，agent 在缺少硬约束时也会犯： 为了省事直接加 @Autowired 字段注入 在 BFF 里偷偷落一个 @Entity Controller 直接访问 Repository Kafka consumer 没有幂等保护 契约模块慢慢混入 Spring Web / JPA 依赖 这些都不是"功能对不对"的问题，而是"代码还在不在团队允许的边界里"的问题。在我看来，ArchUnit 的价值就在这里：它把架构约束从口头约定变成可执行测试。 这个视角并不是孤立的观察。Birgitta Böckeler 在 2026 年 2 月的 Harness Engineering, First Thoughts 里把这种"给 agent 搭结构化反馈 harness"的工程学命名了出来，并明确问到：“Have you experimented with structural testing frameworks like ArchUnit?” 同一时期，Sasha Podlesniuk 在 2026 年 1 月的 From Prompts to Invariants: Re-architecting Systems with ArchUnit and LLMs 里具体写了怎么把 ArchUnit 的失败信息当作 agent 的反馈信号。更早的概念根源是 Neal Ford 在《Building Evolutionary Architectures》里提出的 fitness function——结构化测试就是最典型的、可执行的 fitness function。 /posts/shop-platform-architecture-quality-gates/ Mon, 06 Apr 2026 10:00:00 +0800 /posts/shop-platform-architecture-quality-gates/ 在这个系列的前几篇文章中，我们看了 Shop Platform 的各个技术层面：API Gateway、BFF 聚合、领域服务、事件驱动、活动引擎。但有一个问题始终没有回答——如何保证 15+ 个服务、多个开发者在长时间演进中不把这些设计搞乱？ 靠 Code Review 口头约定往往不够。人总是会犯错，尤其是当 deadline 临近的时候。按我目前的理解，一个更稳妥的办法是：把架构约束尽量变成可自动执行的测试用例。 📦 本文基于的完整项目源码：https://github.com/meirongdev/shop 上一篇：（六）插件化活动引擎 2026-04 实践更新 当前主线仓库里，ArchUnit、WireMock consumer contract tests、@HttpExchange 客户端基线、以及 JWKS 认证链都已经进入可验证状态；本文里的质量Quality Gates思路仍然适用，但哪些Quality Gates“只是方向”、哪些已经落地，请以 main 分支和 docs/ROADMAP-2026.md 为准。 质量Quality Gates全景 Shop Platform 的架构质量保障由三个支柱组成： ┌─────────────────────────────────────────────────────────┐ │ 架构质量Quality Gates │ │ │ │ ① ArchUnit 规则 → 验证已有代码是否符合约定 │ │ (19 条规则) │ │ │ │ ② Maven Archetype → 新服务从标准化骨架出发 │ │ (6 个模板) │ │ │ │ ③ WireMock contract → BFF 与领域服务接口兼容 │ │ (13 个 contract tests) │ └─────────────────────────────────────────────────────────┘ ArchUnit：用代码验证架构 ArchUnit 是一个 Java 库，可以在单元测试中验证类之间的依赖关系、命名约定、注解使用等架构约束。它的核心价值在于：把架构规则变成编译和 CI 中自动执行的测试，而不是文档里容易漂移的约定。