3. 缓存领域模型（一）：缓存实体（Cache Entity）与值对象（Value Object）的建模

在 OpenAPI 场景下，缓存一致性治理的第一步是建立精确的领域模型。许多团队陷入缓存混乱的根本原因，是将“缓存”视为一个技术工具，而非领域概念。本节从领域驱动设计（DDD）的视角，将缓存抽象为缓存实体（Cache Entity）与值对象（Value Object），并给出明确的建模边界与治理规则。

3.1 为什么缓存需要领域建模？

传统缓存设计往往直接面向 Redis Key-Value 或本地 Map，导致以下问题：

• 身份模糊：同一个业务对象在缓存中可能被多个 Key 表示，无法追踪其生命周期。
• 变更失控：缓存更新时只更新了值，未更新标识，导致脏数据。
• 一致性缺失：没有区分“可替换的值”与“需追踪的实体”，缓存失效策略混乱。

3.2 缓存实体（Cache Entity）

定义：缓存实体是具有唯一标识（Cache ID）且生命周期需要被追踪的缓存对象。即使其属性值发生变化，该对象在缓存中的身份保持不变。

3.2.1 建模特征

3.2.2 代码建模示例

// 缓存实体：具有唯一标识的缓存对象
public class CacheEntity<T> {
    private final String cacheId;          // 全局唯一标识
    private final String entityType;       // 实体类型（如 "user", "order"）
    private T data;                        // 业务数据
    private long version;                  // 乐观锁版本号
    private Instant lastModified;          // 最后修改时间

    public CacheEntity(String cacheId, String entityType, T data) {
        this.cacheId = cacheId;
        this.entityType = entityType;
        this.data = data;
        this.version = 1L;
        this.lastModified = Instant.now();
    }

    // 更新数据时版本号递增
    public void updateData(T newData) {
        this.data = newData;
        this.version++;
        this.lastModified = Instant.now();
    }

    // 通过 cacheId 判断身份是否相同
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        CacheEntity<?> that = (CacheEntity<?>) o;
        return Objects.equals(cacheId, that.cacheId);
    }

    @Override
    public int hashCode() {
        return Objects.hash(cacheId);
    }
}

3.3 缓存值对象（Cache Value Object）

定义：缓存值对象是没有唯一标识、仅通过属性值来定义自身的缓存对象。两个值对象如果所有属性值相同，则视为同一个对象。

3.3.1 建模特征

3.3.2 代码建模示例

// 缓存值对象：无标识，不可变，通过值比较
public final class CacheValueObject<T> {
    private final T data;                  // 业务数据
    private final Instant cachedAt;        // 缓存时间戳

    public CacheValueObject(T data) {
        this.data = data;
        this.cachedAt = Instant.now();
    }

    public T getData() {
        return data;
    }

    public Instant getCachedAt() {
        return cachedAt;
    }

    // 值对象通过所有属性比较
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        CacheValueObject<?> that = (CacheValueObject<?>) o;
        return Objects.equals(data, that.data);
    }

    @Override
    public int hashCode() {
        return Objects.hash(data);
    }
}

3.4 实体 vs 值对象：选择决策矩阵

3.5 缓存领域模型关系图

下图展示了缓存实体与值对象在缓存层中的协作关系：

3.6 实体与值对象的协作模式

在 OpenAPI 缓存治理中，实体与值对象通常以组合方式出现：

1. 实体持有值对象：用户实体（Entity）持有地址值对象（Value Object）。地址变更时，直接替换整个值对象，用户实体的版本号递增。
2. 值对象独立缓存：高频读取但极少变更的配置数据（如接口超时时间），直接作为值对象缓存，不绑定实体。
3. 实体聚合值对象列表：订单实体包含商品列表（值对象集合），商品信息变更不影响订单实体的身份。

3.7 建模后的治理收益