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

Server模块Service缓存调整为Vo对象设计文档

1. 整体架构图

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

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

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

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

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

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

    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类
• 修改内容:
  • Service类同时实现IEntityService和QueryService接口
  • IEntityService接口泛型保持为实体类（Model）
  • QueryService接口泛型修改为VO类
  • 继承 VoableService<M, Vo>接口，实现 updateByVo 方法
  • 修改 findById 方法，返回VO对象，并且使用 @Cacheable(key = "#p0") 注解
  • 保留 getById 方法，调用 repository.findById(id) 返回实体对象

2.3 数据转换层

• 职责: 负责实体类和VO类之间的数据转换
• 核心组件:
  • 现有的VoableService接口
  • 实体类自带的toVo()方法
• 设计考虑: 使用实体类自带的toVo()方法进行转换，简化代码结构

2.4 数据访问层

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

2.5 缓存层

• 职责: 存储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 数据访问
        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
    
    style RedisCache fill:#bbf,stroke:#333,stroke-width:2px

4. 接口契约定义

4.1 IEntityService接口

public interface IEntityService<Model> {
    // 根据ID查询Model对象
    Model getById(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> {
    // 根据ID查询Vo对象
    Vo findById(Integer id);
    
    // 根据查询参数和分页条件获取Vo对象列表
    Page<Vo> findAll(JsonNode paramsNode, Pageable pageable);
    
    // 计数方法
    default long count(JsonNode paramsNode) {
        return 0;
    }
}

4.3 Service实现类接口契约

对于每个Service实现类，需要同时实现IEntityService和QueryService接口：

IEntityService实现方法：

方法签名	实现逻辑
Model getById(Integer id)	1. 调用repository.findById(id)
2. 直接返回实体对象（不做缓存）
Page<Model> findAll(Specification<Model> spec, Pageable pageable)	1. 构建查询条件
2. 调用repository.findAll(spec, pageable)
3. 返回包含实体对象的Page
void delete(Model entity)	1. 直接调用repository.delete(entity)
Model save(Model entity)	1. 直接调用repository.save(entity)
2. 清除相关缓存
3. 返回实体对象

QueryService实现方法：

方法签名	实现逻辑
Vo findById(Integer id)	1. 调用repository.findById(id)
2. 将查询到的实体对象转换为VO对象
3. 使用@Cacheable注解缓存VO对象
4. 返回VO对象
Page<Vo> findAll(JsonNode paramsNode, Pageable pageable)	1. 构建查询条件
2. 调用repository.findAll(spec, pageable)
3. 将查询结果中的每个实体对象转换为VO对象
4. 返回包含VO对象的Page

5. 数据流向图

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

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

    C -->|查询操作| D
    C -->|更新/删除操作| D2
    D2 --> L
    E --> L
    F --> K
    
    style G 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类中包含不可序列化的引用

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接口泛型的修改任务，确保修改后的系统能够正确、高效地运行。