contract-manager/docs/task/DESIGN_接口泛型修改.md

IEntityService接口泛型修改任务设计文档

1. 整体架构图

flowchart TD
    subgraph 客户端层
        Client[客户端应用]
    end

    subgraph 控制器层
        Controller[Controller控制器]
    end

    subgraph 服务层
        direction LR
        Service1[Service类
        实现IEntityService<Vo>]
        Service2[Service类
        实现IEntityService<Vo>]
        Service3[Service类
        实现IEntityService<Vo>]
    end

    subgraph 数据转换层
        Mapper[实体-VO转换器
        负责双向转换]
    end

    subgraph 数据访问层
        Repository[Repository接口
        操作实体类]
    end

    subgraph 数据层
        Database[(数据库)]
    end

    subgraph 缓存层
        RedisCache[Redis缓存
        存储VO对象]
    end

    Client -->|请求| Controller
    Controller -->|调用服务方法| Service1
    Controller -->|调用服务方法| Service2
    Controller -->|调用服务方法| Service3
    Service1 -->|转换VO到实体| Mapper
    Service2 -->|转换VO到实体| Mapper
    Service3 -->|转换VO到实体| Mapper
    Mapper -->|转换实体到VO| Service1
    Mapper -->|转换实体到VO| Service2
    Mapper -->|转换实体到VO| Service3
    Service1 -->|CRUD操作| Repository
    Service2 -->|CRUD操作| Repository
    Service3 -->|CRUD操作| Repository
    Repository -->|存取数据| Database
    Service1 <-->|缓存VO对象| RedisCache
    Service2 <-->|缓存VO对象| RedisCache
    Service3 <-->|缓存VO对象| RedisCache

    %% 关键修改点
    style RedisCache fill:#bbf,stroke:#333,stroke-width:2px

2. 分层设计和核心组件

2.1 控制器层

• 职责: 处理HTTP请求，调用Service层方法，返回处理结果
• 影响: 可能需要调整调用Service层方法的参数和返回值类型

2.2 服务层

• 职责: 实现业务逻辑，处理数据转换，调用Repository层进行数据操作，管理缓存
• 核心组件: 所有注解了@CacheConfig的Service类
• 修改内容:
  • 将IEntityService的泛型T从实体类改为VO类
  • 修改实现的接口方法，添加数据转换逻辑
  • 确保缓存中存储的是VO对象而非实体类对象

2.3 数据转换层

• 职责: 负责实体类和VO类之间的数据转换
• 核心组件:
  • 现有的VoableService接口
  • 新增的实体-VO转换工具方法
• 设计考虑: 可以使用工具类或在每个Service类中实现转换逻辑

2.4 数据访问层

• 职责: 提供对数据库的访问操作
• 核心组件: Spring Data JPA Repository接口
• 影响: 基本不受修改影响，仍然操作实体类

2.5 缓存层

• 职责: 存储VO对象，提高数据访问性能
• 核心组件: Redis缓存
• 关键修改: 确保只缓存VO对象，避免代理对象序列化问题

3. 模块依赖关系图

flowchart TD
    subgraph 接口定义
        IEntityService[IEntityService<Vo>
        定义CRUD操作接口] --> VoableService[VoableService<M, Vo>
        定义VO更新方法]
    end

    subgraph 服务实现
        ServiceImpl[Service实现类
        实现IEntityService<Vo>和VoableService]
    end

    subgraph 数据访问
        Repository[Repository接口
        操作实体类]
    end

    subgraph 数据模型
        Entity[实体类
        持久化对象]
        VO[VO类
        视图对象]
    end

    subgraph 缓存
        RedisCache[Redis缓存
        存储VO对象]
    end

    IEntityService --> ServiceImpl
    VoableService --> ServiceImpl
    ServiceImpl --> Repository
    Repository --> Entity
    ServiceImpl --> Entity
    ServiceImpl --> VO
    ServiceImpl <-->|缓存VO对象| RedisCache
    
    style RedisCache fill:#bbf,stroke:#333,stroke-width:2px

4. 接口契约定义

4.1 IEntityService接口

public interface IEntityService<Vo> {
    // 根据ID查询VO对象
    Vo findById(Integer id);
    
    // 根据查询规范和分页参数查询VO对象列表
    Page<Vo> findAll(Specification<Vo> spec, Pageable pageable);
    
    // 根据搜索文本构建查询规范
    Specification<Vo> getSpecification(String searchText);
    
    // 搜索VO对象列表（默认方法）
    default List<Vo> search(String searchText) {
        throw new UnsupportedOperationException();
    }
    
    // 删除VO对象
    void delete(Vo entity);
    
    // 保存VO对象
    Vo save(Vo entity);
}

4.2 Service实现类接口契约

对于每个Service实现类，需要实现以下方法的契约转换：

原方法签名	新方法签名	实现逻辑
Entity findById(Integer id)	Vo findById(Integer id)	1. 调用repository.findById(id)
2. 将查询到的实体对象转换为VO对象
3. 返回VO对象
Page<Entity> findAll(Specification<Entity> spec, Pageable pageable)	Page<Vo> findAll(Specification<Vo> spec, Pageable pageable)	1. 将VO的Specification转换为Entity的Specification
2. 调用repository.findAll(spec, pageable)
3. 将查询结果中的每个实体对象转换为VO对象
4. 返回包含VO对象的Page
Specification<Entity> getSpecification(String searchText)	Specification<Vo> getSpecification(String searchText)	1. 构建基于Entity的Specification
2. 封装或转换为基于Vo的Specification（可能需要特殊处理）
void delete(Entity entity)	void delete(Vo entity)	1. 将VO对象转换为实体对象
2. 调用repository.delete(entity)
Entity save(Entity entity)	Vo save(Vo entity)	1. 将VO对象转换为实体对象
2. 调用repository.save(entity)
3. 将保存结果转换为VO对象
4. 返回VO对象

5. 数据流向图

flowchart TD
    subgraph 客户端请求处理流程
        A[客户端发送请求
        包含VO数据] --> B[Controller接收请求
        调用Service方法]
        B --> C[Service方法处理
        接收VO参数] --> D{检查Redis缓存
        中是否存在VO对象}
        D -->|存在| D1[直接返回缓存中的VO对象]
        D -->|不存在| D2[VO转换为Entity
        准备数据操作]
        D2 --> E[调用Repository
        执行数据操作] --> F[Repository操作数据库
        返回Entity结果]
        F --> G[Entity转换为VO
        准备响应数据]
        G --> H[将VO对象存入Redis缓存] --> I[Service返回VO
        Controller组装响应]
        D1 --> I
        I --> J[客户端接收响应
        包含VO数据]
    end

    subgraph 数据转换流程
        K[VO对象] -->|属性映射| L[Entity对象
        用于数据持久化]
        L -->|属性映射| K
    end

    C --> K
    D2 --> K
    F --> L
    G --> K
    
    style H fill:#bbf,stroke:#333,stroke-width:2px
    style D fill:#bbf,stroke:#333,stroke-width:2px

6. 异常处理策略

1. 转换异常处理:

   • 在实体类和VO类之间进行转换时，捕获并处理可能的转换异常
   • 提供清晰的错误信息，指明转换失败的原因

2. 数据验证:

   • 在接收VO对象时，进行数据验证，确保数据的有效性
   • 对于无效数据，抛出适当的异常并提供错误信息

3. 事务处理:

   • 保持原有的事务边界，确保数据操作的原子性
   • 在事务中包含完整的数据操作和转换过程

4. 缓存异常:

   • 处理可能的缓存操作异常，确保即使缓存失败也不会影响业务逻辑
   • 考虑添加缓存回退机制
   • 特别处理Redis连接问题和序列化问题，确保系统可用性

5. 序列化异常:

   • 处理VO对象序列化失败的情况
   • 确保VO类实现Serializable接口，避免在VO类中包含不可序列化的引用

7. 设计原则

1. 最小化修改原则: 仅修改必要的代码，避免不必要的重构

2. 向后兼容原则: 尽量保持与原有系统的兼容性，特别是对依赖这些Service的组件

3. 数据一致性原则: 确保实体类和VO类之间的数据转换不会导致数据丢失或不一致

4. 可测试性原则: 设计支持单元测试和集成测试的代码结构

5. 性能优化原则: 考虑数据转换可能带来的性能影响，必要时进行优化

6. 代码复用原则: 尽量复用现有的代码和模式，特别是数据转换相关的代码

7. 序列化安全原则: 确保所有缓存的VO对象都是可序列化的，避免在VO对象中包含循环引用和不可序列化的组件

通过以上设计，我们可以系统地完成IEntityService接口泛型的修改任务，确保修改后的系统能够正确、高效地运行。