contract-manager/docs/task/server模块service缓存调整为Vo对象/DESIGN_server模块service缓存调整为Vo对象.md

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

1. 整体架构图

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

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

    subgraph WebSocket服务层
        WebSocketHandler[WebSocketServerHandler
        处理WebSocket连接]
        WebSocketTaskManager[WebSocketServerTaskManager
        管理WebSocket任务]
        WebSocketCallbackManager[WebSocketServerCallbackManager
        处理服务调用回调]
    end

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

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

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

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

    Controller -->|调用服务方法| Service1
    Controller -->|调用服务方法| Service2
    Controller -->|调用服务方法| Service3
    WebSocketHandler -->|注入服务| Service1
    WebSocketHandler -->|注入服务| Service2
    WebSocketHandler -->|注入服务| Service3
    WebSocketTaskManager -->|注入服务| Service1
    WebSocketTaskManager -->|注入服务| Service2
    WebSocketTaskManager -->|注入服务| Service3
    WebSocketCallbackManager -->|反射调用| Service1
    WebSocketCallbackManager -->|反射调用| Service2
    WebSocketCallbackManager -->|反射调用| 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
    style WebSocketCallbackManager fill:#fbb,stroke:#333,stroke-width:2px

2. 分层设计和核心组件

2.1 控制器层

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

2.2 服务层

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

2.3 WebSocket服务层

• 职责: 处理WebSocket连接、消息传递、任务管理和回调处理
• 核心组件:
  • WebSocketServerHandler：处理WebSocket连接、消息传递和断开连接
  • WebSocketServerTaskManager：管理WebSocket任务的注册和执行
  • WebSocketServerCallbackManager：通过反射调用服务方法，处理回调
• 影响:
  • WebSocketServerCallbackManager直接调用IEntityService接口，泛型修改将对其产生直接影响
  • 需要特别关注createNewEntity、findEntityTypeInInterfaces等方法的实现
  • invokerFindByIdMethod、invokerFindAllMethod等方法需要适应VO类型的返回值

2.4 数据转换层

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

2.5 数据访问层

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

2.6 缓存层

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

3. 模块依赖关系图

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

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

    subgraph WebSocket服务
        WebSocketHandler[WebSocketServerHandler
        处理WebSocket连接] --> WebSocketTaskManager[WebSocketServerTaskManager
        管理WebSocket任务]
        WebSocketTaskManager --> WebSocketCallbackManager[WebSocketServerCallbackManager
        处理服务调用回调]
    end

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

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

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

    IEntityService --> ServiceImpl
    QueryService --> ServiceImpl
    VoableService --> ServiceImpl
    ServiceImpl --> Repository
    Repository --> Entity
    ServiceImpl --> Entity
    ServiceImpl --> VO
    ServiceImpl <-->|缓存VO对象| RedisCache
    WebSocketHandler -->|注入| ServiceImpl
    WebSocketTaskManager -->|注入| ServiceImpl
    WebSocketCallbackManager -->|反射调用| IEntityService
    WebSocketCallbackManager -->|类型转换| VO
    
    style RedisCache fill:#bbf,stroke:#333,stroke-width:2px
    style WebSocketCallbackManager fill:#fbb,stroke:#333,stroke-width:2px

4. 接口契约定义

4.1 IEntityService接口

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

### 4.2 QueryService<Vo>接口

```java
public interface QueryService<Vo> {
    // 根据查询参数和分页条件获取Vo对象列表
    Page<Vo> findAll(JsonNode paramsNode, Pageable pageable);
    
    // 计数方法
    default long count(JsonNode paramsNode) {
        return 0;
    }
}

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 服务请求处理流程
        B[Controller接收请求
        调用Service方法] --> 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
    end

    subgraph WebSocket请求处理流程
        W1[WebSocket客户端请求
        消息传递] --> W2[WebSocketServerHandler
        接收消息] --> W3[WebSocketServerTaskManager
        处理任务] --> W4[WebSocketServerCallbackManager
        反射调用Service方法] --> W5{检查Redis缓存
        中是否存在VO对象}
        W5 -->|存在| W6[直接返回缓存中的VO对象]
        W5 -->|不存在| W7[Service处理请求
        进行数据转换] --> W8[Entity转换为VO
        准备响应数据] --> W9[WebSocketServerCallbackManager
        处理VO响应] --> W10[WebSocketServerHandler
        发送响应消息] --> W11[WebSocket客户端接收
        VO响应数据]
        W6 --> W9
    end

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

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

6. 异常处理策略

1. 转换异常处理:

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

2. 数据验证:

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

3. 事务处理:

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

4. 缓存异常:

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

5. 序列化异常:

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

6. WebSocket服务异常处理:

   • 处理WebSocketServerCallbackManager中反射调用IEntityService接口时可能出现的类型转换异常
   • 特别关注createNewEntity、findEntityTypeInInterfaces等依赖泛型参数的方法
   • 确保WebSocket服务在接口泛型修改后能够正常处理异常情况
   • 在invokerFindByIdMethod、invokerFindAllMethod等方法中添加类型安全检查

7. 设计原则

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

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

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

4. 可测试性原则: 设计支持单元测试和集成测试的代码结构，包括WebSocket服务的测试

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

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

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

8. 类型安全原则: 在WebSocketServerCallbackManager中添加类型安全检查，确保能够正确处理从实体类到VO类的泛型变化

9. 服务兼容性原则: 确保修改后的IEntityService接口能够与WebSocket服务和其他现有服务组件兼容

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