4. 模块边界隔离的原则：上下文映射、防腐层、依赖反转与接口契约

在多模块缓存同步项目中，模块边界隔离是防止架构腐化的核心防线。当订单模块、商品模块、用户模块共享同一缓存基础设施时，如果没有清晰的边界策略，一个模块的缓存变更可能引发连锁故障。本章围绕上下文映射（Context Mapping）、防腐层（Anti-Corruption Layer）、依赖反转（Dependency Inversion）与接口契约（Interface Contract）四个原则，结合缓存同步场景讲解模块边界隔离的落地实现。

4.1 上下文映射：定义限界上下文之间的缓存关系

上下文映射源自领域驱动设计（DDD），在缓存同步场景中用于明确每个模块的缓存边界以及模块间的缓存数据流动策略。没有清晰的上下文映射，缓存数据会成为全局共享的"脏池"，一个模块的缓存淘汰策略会意外影响另一个模块。

4.2 防腐层：保护业务领域不受缓存实现侵蚀

防腐层（ACL）位于业务模块与缓存基础设施之间，负责将外部缓存 API 转换为业务模块期望的接口。当底层缓存从 Redis 切换到 Memcached 或本地 Caffeine 时，只需修改防腐层适配器，业务代码零改动。

// 防腐层接口定义：业务模块只依赖此抽象
public interface CachePort {
    Optional<T> get(String key, Class<T> type);
    void put(String key, Object value, long ttlSeconds);
    void evict(String key);
    void evictByPrefix(String prefix);
}

// Redis 实现防腐层适配器
@Component
public class RedisCacheAdapter implements CachePort {
    private final RedisTemplate<String, Object> redisTemplate;
    private final Duration defaultTtl = Duration.ofMinutes(30);

    public RedisCacheAdapter(RedisTemplate<String, Object> redisTemplate) {
        this.redisTemplate = redisTemplate;
    }

    @Override
    public Optional<T> get(String key, Class<T> type) {
        Object raw = redisTemplate.opsForValue().get(key);
        if (raw == null) return Optional.empty();
        return Optional.of(type.cast(raw));
    }

    @Override
    public void put(String key, Object value, long ttlSeconds) {
        redisTemplate.opsForValue().set(key, value, Duration.ofSeconds(ttlSeconds));
    }

    @Override
    public void evict(String key) {
        redisTemplate.delete(key);
    }

    @Override
    public void evictByPrefix(String prefix) {
        Set<String> keys = redisTemplate.keys(prefix + "*");
        if (keys != null && !keys.isEmpty()) {
            redisTemplate.delete(keys);
        }
    }
}

4.3 依赖反转：让业务模块定义缓存抽象

依赖反转原则（DIP）要求高层模块（业务逻辑）不依赖低层模块（缓存实现），二者都依赖抽象。在缓存同步中，这意味着缓存操作接口由业务模块定义，缓存模块负责实现这些接口，而不是业务模块去适配缓存 API。

// 业务模块定义的缓存抽象（位于 domain 包）
// 不属于任何基础设施模块，业务模块拥有所有权
public interface OrderCacheRepository {
    Optional<OrderSummary> findById(Long orderId);
    void save(OrderSummary order);
    void invalidate(Long orderId);
}

// 基础设施模块实现该抽象
@Repository
public class RedisOrderCacheRepository implements OrderCacheRepository {
    private final CachePort cachePort;  // 通过防腐层接入

    private static final String KEY_PREFIX = "order:summary:";
    private static final long TTL = 600; // 10分钟

    public RedisOrderCacheRepository(CachePort cachePort) {
        this.cachePort = cachePort;
    }

    @Override
    public Optional<OrderSummary> findById(Long orderId) {
        return cachePort.get(KEY_PREFIX + orderId, OrderSummary.class);
    }

    @Override
    public void save(OrderSummary order) {
        cachePort.put(KEY_PREFIX + order.id(), order, TTL);
    }

    @Override
    public void invalidate(Long orderId) {
        cachePort.evict(KEY_PREFIX + orderId);
    }
}

4.4 接口契约：显式定义缓存操作的协议

接口契约是模块间通信的"法律条文"，涵盖方法签名、输入输出约束、异常规范、幂等性保证和超时策略。在缓存同步中，契约必须明确 缓存一致性级别（强一致性 / 最终一致性）和 失效传播语义。

// 缓存同步契约定义（OpenAPI 3.0 风格）
// 模块间通过此契约约定缓存操作行为

{
  "contract": "CacheSyncContract/v1",
  "operations": [
    {
      "name": "syncPut",
      "description": "跨模块缓存写入，触发失效传播",
      "input": {
        "key": "string (pattern: ^[a-z]+:[a-z]+:v\\d+:.*$)",
        "value": "object",
        "ttlSeconds": "integer (min: 60, max: 86400)",
        "originModule": "string (enum: [order, product, user])"
      },
      "output": {
        "status": "string (enum: [ACCEPTED, REJECTED])",
        "syncId": "string (uuid)"
      },
      "exceptions": [
        "InvalidKeyFormatException",
        "TtlOutOfRangeException",
        "ModuleNotAuthorizedException"
      ],
      "consistency": "EVENTUAL",
      "idempotent": true
    },
    {
      "name": "syncEvict",
      "description": "跨模块缓存失效，通知订阅方",
      "input": {
        "key": "string",
        "originModule": "string",
        "reason": "string (enum: [UPDATE, DELETE, EXPIRED])"
      },
      "output": {
        "affectedModules": "array<string>"
      },
      "exceptions": [
        "KeyNotFoundException"
      ],
      "consistency": "EVENTUAL",
      "idempotent": true
    }
  ]
}

4.5 四原则综合落地：缓存同步边界隔离示例

以下代码展示一个完整的模块边界隔离实现，将四个原则融为一体。订单模块通过防腐层 + 依赖反转访问缓存，并通过接口契约与商品模块同步缓存失效事件。

// 1. 上下文映射：订单模块使用独立缓存命名空间 "order:cache:v1:"
// 2. 防腐层：CachePort 隔离 Redis 实现
// 3. 依赖反转：OrderCacheRepository 由订单模块定义，基础设施实现
// 4. 接口契约：缓存失效事件通过 Contract 定义的 EventBus 传播

@Service
public class OrderCacheSynchronizer {
    private final OrderCacheRepository orderCache;
    private final CacheEventBus eventBus;  // 基于接口契约的事件总线

    public OrderCacheSynchronizer(OrderCacheRepository orderCache, CacheEventBus eventBus) {
        this.orderCache = orderCache;
        this.eventBus = eventBus;
    }

    public void onOrderUpdated(OrderUpdatedEvent event) {
        // 更新本地缓存
        orderCache.save(event.toSummary());
        // 发布跨模块失效事件（符合接口契约）
        eventBus.publish(new CacheInvalidationEvent(
            "order:summary:" + event.orderId(),
            "order",
            "UPDATE"
        ));
    }
}

// 商品模块监听失效事件
@Component
public class ProductCacheInvalidationListener {
    private final CachePort cachePort;

    public ProductCacheInvalidationListener(CachePort cachePort) {
        this.cachePort = cachePort;
    }

    @EventListener
    public void onCacheInvalidation(CacheInvalidationEvent event) {
        // 只处理与商品模块相关的缓存失效
        if (event.key().startsWith("product:cache:")) {
            cachePort.evict(event.key());
        }
    }
}

4.6 常见错误与边界隔离检查清单

• 错误1：上下文映射缺失——所有模块共用同一缓存前缀，key 冲突导致数据覆盖。强制每个模块在配置中心注册自己的 key 前缀，CI 阶段自动校验。
• 错误2：防腐层泄漏——在业务代码中直接调用 RedisTemplate.expire() 或使用 Redis 特有的序列化机制。代码审查时检查 import 语句，禁止基础设施类型出现在 domain 包。
• 错误3：依赖反转方向错误——业务模块依赖了具体的缓存客户端 jar。在模块的 build.gradle / pom.xml 中检查依赖范围，确保 infrastructure 依赖缓存客户端，domain 只依赖抽象接口。
• 错误4：接口契约不完整——跨模块缓存操作没有定义超时和异常码，导致调用方无限等待。使用契约测试（Pact 或 Spring Cloud Contract）自动验证接口实现与契约的一致性。

4.7 边界隔离的稳定性验证

在部署流水线中增加以下自动化验证，确保模块边界隔离不被破坏：

# 使用 ArchUnit 验证依赖方向（Java 示例）
@AnalyzeClasses(packages = "com.order")
public class DependencyRuleTest {
    @Test
    void domainShouldNotDependOnInfrastructure() {
        JavaClasses classes = new ClassFileImporter().importPackages("com.order");
        ArchRule rule = classes().that().resideInAPackage("..domain..")
            .should().onlyDependOnClassesThat()
            .resideInAnyPackage("..domain..", "java..", "org.springframework..");
        rule.check(classes);
    }
}

# 使用 jq 验证接口契约 key 格式
cat cache-contract.json | jq '.operations[].input.key' | grep -E '^"[a-z]+:[a-z]+:v[0-9]+:.*"$'
if [ $? -ne 0 ]; then
  echo "ERROR: 缓存 key 格式不符合契约规范"
  exit 1
fi

通过上下文映射、防腐层、依赖反转与接口契约四个原则的协同实施，多模块缓存同步项目能够实现清晰的边界隔离——每个模块的缓存变更不会意外影响其他模块，缓存基础设施的升级对业务代码透明，跨模块通信的协议有据可查。下一层将进入具体的缓存同步策略实现，包括基于事件的失效传播与基于定时任务的补偿同步。