3. 领域层Repository接口设计：接口职责、方法签名、查询与命令分离、缓存标注

3.1 接口职责

领域层Repository接口是聚合根在领域模型中的持久化边界，它的核心职责是将领域对象存储与基础设施实现完全解耦。接口只描述“能做什么”，而不暴露“怎么做”。具体职责包括：

• 数据访问抽象：定义对聚合根的增删改查操作，但不暴露数据库、ORM、缓存等具体技术。
• 领域对象生命周期管理：确保从持久化存储中恢复的聚合根处于完整、一致的状态。
• 事务与一致性边界：为命令方法隐式界定事务范围，一个方法通常对应一个工作单元。
• 缓存策略标注：通过注解或元数据指明哪些查询结果可被缓存，且缓存失效规则由领域层控制。

3.2 方法签名设计

方法签名应当遵循“以领域语言命名、以领域类型传参”的准则。常见模式如下：

Optional<Order> findById(OrderId id);
List<Order> findByCustomerId(CustomerId customerId, Page page);
boolean existsByOrderNumber(OrderNumber number);

void save(Order order);
void delete(OrderId id);
OrderId create(Order order);

void saveAll(List<Order> orders);
void deleteAll(List<OrderId> ids);

3.3 查询与命令分离（CQS）

Repository接口应当显式遵循命令-查询分离原则：

• 查询方法：只读、无副作用、幂等。返回对象或集合，不允许修改传入参数或外部状态。
• 命令方法：有副作用（写入数据库/发送事件），返回void或标识符。必须保障事务完整。

分离后的接口结构清晰，便于单元测试（查询可mock、命令可验证）。在跨微服务场景下，查询方法可独立启用只读数据库副本或缓存，命令方法强制走主库。

3.4 缓存标注

为支持高性能查询，可在接口方法上添加缓存标注。标注形式可以是注解、接口默认方法或独立的元数据配置。示例如下：

• 注解方式：@Cacheable(key = "#id") 标记在findById方法上，声明缓存区域和键表达式。
• 缓存区域划分：按聚合根类型或查询维度定义不同缓存区域（如order_cache、customer_cache）。
• 失效策略：命令方法（如save、delete）应通过@CacheEvict标注，自动清除相关缓存条目。

3.5 接口设计的内联SVG：查询/命令与缓存标注关系

3.6 选型权衡与风险点

3.7 落地步骤与验收标准

落地步骤

1. 定义聚合根标识符：为每个聚合根创建值对象（如OrderId），作为Repository方法的参数和返回类型。
2. 声明接口方法：按CQS原则分别列出所需查询和命令方法，确保每个方法语义单一。
3. 标注缓存注解：在频繁调用的查询方法上添加缓存标注，并指定缓存区域名称；在对应的命令方法上添加缓存失效标注。
4. 编写接口文档：在方法上方使用JavaDoc（或等效文档）描述预期行为、是否幂等、缓存策略、事务边界。
5. 建立单元测试桩：使用Mock框架为Repository接口创建测试替身，验证应用服务对接口的调用符合预期。

验收标准

• 所有Repository方法参数和返回值均为领域层类型，无基础设施依赖。
• 查询方法不产生任何写操作（通过测试拦截或静态分析验证）。
• 命令方法执行后，相关缓存条目被正确清除（集成测试验证）。
• 接口方法总数不超过15个（含继承方法），避免冗余。
• 更换ORM或数据库实现时，领域层Repository接口无需修改任何代码。