feat(contract): 新增合同余额功能及重构文件管理
重构合同文件管理逻辑，增加错误处理和日志记录 新增ContractBalance实体、Repository和VO类 完善Voable接口文档和实现规范 更新项目架构文档和数据库设计 修复SmbFileService的连接问题 移动合同相关TabSkin类到contract包 添加合同文件重建任务的WebSocket支持
This commit is contained in:
@@ -1,83 +1,133 @@
|
||||
# 客户端 Service 类规则
|
||||
# Client Service 实现编写指南
|
||||
|
||||
## 1. 目录结构
|
||||
- 所有客户端 Service 类位于 `client/src/main/java/com/ecep/contract/service/` 目录下
|
||||
- 按业务领域组织，直接放置在 service 包下，不进行子包划分
|
||||
- 服务类命名与实体类一一对应
|
||||
## 📋 概述
|
||||
|
||||
## 2. 命名规范
|
||||
- 服务类命名格式为：`[实体名称]Service.java`
|
||||
- 例如：`CompanyService.java`、`ContractService.java`、`ProjectService.java`
|
||||
- 基础服务接口命名为：`IEntityService.java`、`ViewModelService.java`
|
||||
- 泛型基础服务类命名为：`QueryService.java`
|
||||
本指南总结 Client 模块 Service 层的实现经验，用于指导后续 Service 的编写。本指南基于 Contract-Manager 项目中已实现的 Service 模式整理。
|
||||
|
||||
## 3. 继承关系
|
||||
- 业务服务类通常继承自泛型基础服务类 `QueryService<T, TV>`
|
||||
- `T` 表示 VO 类型（实现了 IdentityEntity 接口）
|
||||
- `TV` 表示 ViewModel 类型（实现了 IdentityViewModel<T> 接口）
|
||||
- `QueryService` 实现了 `ViewModelService<T, TV>` 接口
|
||||
- `ViewModelService` 继承了 `IEntityService<T>` 接口
|
||||
- 特定场景下可以不继承 `QueryService`，直接实现所需接口或创建独立服务类
|
||||
---
|
||||
|
||||
## 🏗️ 基础架构
|
||||
|
||||
### 1. 继承层次结构
|
||||
|
||||
```java
|
||||
// Service 接口定义
|
||||
public interface IEntityService<T> {
|
||||
T findById(Integer id);
|
||||
T save(T entity);
|
||||
void delete(T entity);
|
||||
List<T> findAll();
|
||||
Page<T> findAll(Map<String, Object> params, Pageable pageable);
|
||||
StringConverter<T> getStringConverter();
|
||||
}
|
||||
|
||||
// 基础 Service 实现
|
||||
public abstract class QueryService<T extends IdentityEntity, TV extends IdentityViewModel<T>>
|
||||
implements ViewModelService<T, TV> {
|
||||
// 核心实现
|
||||
}
|
||||
|
||||
// 具体业务 Service
|
||||
@Service
|
||||
@CacheConfig(cacheNames = "company")
|
||||
public class CompanyService extends QueryService<CompanyVo, CompanyViewModel> {
|
||||
// 业务方法实现
|
||||
@CacheConfig(cacheNames = "business")
|
||||
public class XxxService extends QueryService<XxxVo, XxxViewModel> {
|
||||
// 业务特定实现
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 注解使用
|
||||
- **@Service**：标记为 Spring 服务组件，使其可被自动发现和注入
|
||||
- **@CacheConfig**：配置缓存名称，通常与服务类名对应
|
||||
- **@Cacheable**：标记方法结果可缓存，需指定缓存键（key）
|
||||
- **@CacheEvict**：标记方法执行后清除缓存，可指定缓存键或清除所有
|
||||
- **@Caching**：组合多个缓存操作（如同时清除多个缓存条目）
|
||||
- **@Autowired**：用于自动注入依赖的其他服务
|
||||
### 2. 核心特性
|
||||
|
||||
- **泛型支持**：`QueryService` 使用泛型处理不同类型的 Vo 和 ViewModel
|
||||
- **WebSocket 通信**：通过 `WebSocketClientService` 与 Server 端通信
|
||||
- **异步处理**：使用 `CompletableFuture` 实现异步操作
|
||||
- **缓存机制**：集成 Spring Cache 支持多级缓存
|
||||
- **错误处理**：统一的异常处理和日志记录
|
||||
|
||||
---
|
||||
|
||||
## 📝 Service 编写规范
|
||||
|
||||
### 1. 类声明和注解
|
||||
|
||||
```java
|
||||
@Service
|
||||
@CacheConfig(cacheNames = "contract")
|
||||
public class ContractService extends QueryService<ContractVo, ContractViewModel> {
|
||||
@Autowired
|
||||
private SysConfService confService;
|
||||
|
||||
@Cacheable(key = "#p0")
|
||||
public ContractVo findById(Integer id) {
|
||||
return super.findById(id);
|
||||
}
|
||||
|
||||
@Caching(evict = {
|
||||
@CacheEvict(key = "#p0.id"),
|
||||
@CacheEvict(key = "'code-'+#p0.code")
|
||||
})
|
||||
public ContractVo save(ContractVo contract) {
|
||||
return super.save(contract);
|
||||
}
|
||||
@Service // Spring 组件注解
|
||||
@CacheConfig(cacheNames = "xxx") // 缓存配置，xxx为业务域名称
|
||||
public class XxxService extends QueryService<XxxVo, XxxViewModel> {
|
||||
// Service 实现
|
||||
}
|
||||
```
|
||||
|
||||
## 5. 缓存机制
|
||||
- 每个服务类应有独立的缓存名称空间
|
||||
- 缓存键（key）应具有唯一性，通常使用 ID、代码或名称等唯一标识
|
||||
- 保存和删除操作时应清除相关缓存，保持数据一致性
|
||||
- 可使用 SpEL 表达式动态生成缓存键
|
||||
- 频繁查询的数据应考虑缓存，提高性能
|
||||
### 2. 缓存策略
|
||||
|
||||
## 6. 异步调用机制
|
||||
- 使用 `async()` 方法进行异步远程调用
|
||||
- 方法参数通常包括：方法名、参数值、参数类型列表
|
||||
- 使用 `CompletableFuture` 处理异步结果
|
||||
- 使用 `handle()` 方法处理响应和异常
|
||||
- 远程调用异常应包装为 RuntimeException 并提供详细错误信息
|
||||
#### 缓存注解使用
|
||||
```java
|
||||
@Cacheable(key = "#p0") // 按ID缓存
|
||||
@Cacheable(key = "'code-'+#p0") // 按代码缓存
|
||||
@Cacheable(key = "'name-'+#p0") // 按名称缓存
|
||||
|
||||
@CacheEvict(key = "#p0.id") // 删除时清除ID缓存
|
||||
@CacheEvict(key = "'code-'+#p0.code") // 清除代码缓存
|
||||
|
||||
@Caching(evict = {
|
||||
@CacheEvict(key = "#p0.id"),
|
||||
@CacheEvict(key = "'code-'+#p0.code")
|
||||
}) // 批量清除缓存
|
||||
```
|
||||
|
||||
#### 缓存键设计原则
|
||||
- **ID 缓存**：`#p0`（第一个参数，通常是ID）
|
||||
- **代码缓存**：`'code-'+#p0`（业务代码的缓存）
|
||||
- **名称缓存**：`'name-'+#p0`（业务名称的缓存）
|
||||
- **关联缓存**：`'company-'+#p0.id`（关联实体的缓存）
|
||||
|
||||
### 3. 核心方法实现
|
||||
|
||||
#### findById 方法
|
||||
```java
|
||||
@Cacheable(key = "#p0")
|
||||
@Override
|
||||
public XxxVo findById(Integer id) {
|
||||
return super.findById(id); // 调用父类方法
|
||||
}
|
||||
```
|
||||
|
||||
#### save 方法（带缓存清除）
|
||||
```java
|
||||
@Caching(evict = {
|
||||
@CacheEvict(key = "#p0.id"),
|
||||
@CacheEvict(key = "'code-'+#p0.code")
|
||||
})
|
||||
@Override
|
||||
public XxxVo save(XxxVo entity) {
|
||||
return super.save(entity);
|
||||
}
|
||||
```
|
||||
|
||||
#### delete 方法（带缓存清除）
|
||||
```java
|
||||
@Caching(evict = {
|
||||
@CacheEvict(key = "#p0.id"),
|
||||
@CacheEvict(key = "'code-'+#p0.code")
|
||||
})
|
||||
@Override
|
||||
public void delete(XxxVo entity) {
|
||||
super.delete(entity);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 异步通信模式
|
||||
|
||||
### 1. 基本异步调用
|
||||
|
||||
```java
|
||||
@Cacheable(key = "'code-'+#p0")
|
||||
public ContractVo findByCode(String code) {
|
||||
// 异步调用示例
|
||||
public XxxVo findByCode(String code) {
|
||||
try {
|
||||
return async("findByCode", code, String.class).handle((response, ex) -> {
|
||||
if (ex != null) {
|
||||
throw new RuntimeException("远程方法+findByCode+调用失败", ex);
|
||||
throw new RuntimeException("远程方法 findByCode 调用失败", ex);
|
||||
}
|
||||
if (response != null) {
|
||||
return updateValue(createNewEntity(), response);
|
||||
@@ -85,62 +135,374 @@ public ContractVo findByCode(String code) {
|
||||
return null;
|
||||
}).get();
|
||||
} catch (Exception e) {
|
||||
throw new RuntimeException("查询失败: " + code, e);
|
||||
throw new RuntimeException("查找实体失败: " + code, e);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 7. 基础方法实现
|
||||
- 应实现 `IEntityService<T>` 接口定义的核心方法：
|
||||
- `findById(Integer id)`：根据 ID 查询实体
|
||||
- `save(T entity)`：保存实体
|
||||
- `delete(T entity)`：删除实体
|
||||
- `findAll()`：查询所有实体
|
||||
- `findAll(Map<String, Object> params, Pageable pageable)`：条件分页查询
|
||||
- `getStringConverter()`：获取类型转换器
|
||||
- 通常通过继承 `QueryService` 来复用这些基础方法的实现
|
||||
- 可根据业务需求重写或扩展基础方法
|
||||
|
||||
## 8. 业务方法规范
|
||||
- 业务方法应与服务端对应，保持方法名和参数一致
|
||||
- 方法命名应清晰表达其功能，如 `findByName`, `findByCode`
|
||||
- 复杂业务逻辑应封装为独立方法
|
||||
- 参数校验应在方法开始处进行
|
||||
- 返回值类型应明确，避免使用过于泛化的类型
|
||||
|
||||
## 9. 类型转换器
|
||||
- 实现 `getStringConverter()` 方法，返回对应的 StringConverter 实例
|
||||
- 通常创建专用的 Converter 类，如 `CustomerCatalogStringConverter`
|
||||
- 转换器实例应作为服务类的成员变量，避免重复创建
|
||||
### 2. 复杂对象处理
|
||||
|
||||
```java
|
||||
public class CustomerCatalogService extends QueryService<CustomerCatalogVo, CustomerCatalogViewModel> {
|
||||
private final CustomerCatalogStringConverter stringConverter = new CustomerCatalogStringConverter(this);
|
||||
|
||||
@Override
|
||||
public StringConverter<CustomerCatalogVo> getStringConverter() {
|
||||
return stringConverter;
|
||||
public List<XxxDetailVo> findDetailsByXxxId(Integer xxxId) {
|
||||
try {
|
||||
return async("findDetailsByXxxId", List.of(xxxId), List.of(Integer.class))
|
||||
.handle((response, ex) -> {
|
||||
if (ex != null) {
|
||||
throw new RuntimeException("远程方法调用失败", ex);
|
||||
}
|
||||
if (response != null) {
|
||||
try {
|
||||
List<XxxDetailVo> content = new ArrayList<>();
|
||||
for (JsonNode node : response) {
|
||||
XxxDetailVo newEntity = new XxxDetailVo();
|
||||
objectMapper.updateValue(newEntity, node);
|
||||
content.add(newEntity);
|
||||
}
|
||||
return content;
|
||||
} catch (Exception e) {
|
||||
throw new RuntimeException(response.toString(), e);
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}).get();
|
||||
} catch (Exception e) {
|
||||
throw new RuntimeException(e);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 10. 错误处理
|
||||
- 远程调用异常应捕获并包装为更具描述性的 RuntimeException
|
||||
- 提供详细的错误信息，包括调用的方法名和参数
|
||||
- 对于可预期的业务异常，可添加专门的处理逻辑
|
||||
- 不推荐使用 printStackTrace()，应使用日志记录异常
|
||||
---
|
||||
|
||||
## 11. 工具方法和辅助功能
|
||||
- 通用功能可封装为工具方法
|
||||
- 配置相关操作可通过 `SysConfService` 实现
|
||||
- 文件路径处理应使用 `File` 类和相关工具方法
|
||||
- 日期时间处理应使用 Java 8+ 的日期时间 API
|
||||
## 💼 业务逻辑模式
|
||||
|
||||
## 12. 最佳实践
|
||||
- 遵循单一职责原则，每个服务类专注于一个业务领域
|
||||
- 优先使用继承和接口实现来复用代码
|
||||
- 合理使用缓存提高性能，但注意缓存一致性
|
||||
- 异步调用应正确处理异常和超时情况
|
||||
- 服务类之间的依赖应通过 `@Autowired` 注入，避免硬编码
|
||||
- 方法实现应简洁明了，复杂逻辑应拆分
|
||||
- 为重要方法添加 JavaDoc 注释，说明其功能和参数含义
|
||||
### 1. 文件系统集成
|
||||
|
||||
#### 路径管理
|
||||
```java
|
||||
@Autowired
|
||||
private SysConfService confService;
|
||||
|
||||
private File basePath;
|
||||
|
||||
public File getBasePath() {
|
||||
if (basePath == null) {
|
||||
basePath = new File(confService.getString(Constant.KEY_BASE_PATH));
|
||||
}
|
||||
return basePath;
|
||||
}
|
||||
|
||||
// 验证路径是否在基础目录内
|
||||
public boolean checkXxxPathInBasePath(XxxVo xxx) {
|
||||
if (!existsXxxPath(xxx)) {
|
||||
return false;
|
||||
}
|
||||
File basePath = getBasePath();
|
||||
if (basePath == null || !basePath.exists()) {
|
||||
throw new IllegalArgumentException("基础目录不存在");
|
||||
}
|
||||
File path = new File(xxx.getPath());
|
||||
return path.getAbsolutePath().startsWith(basePath.getAbsolutePath());
|
||||
}
|
||||
|
||||
// 检查路径是否存在
|
||||
public boolean existsXxxPath(XxxVo xxx) {
|
||||
if (!StringUtils.hasText(xxx.getPath())) {
|
||||
return false;
|
||||
}
|
||||
File path = new File(xxx.getPath());
|
||||
return path.exists();
|
||||
}
|
||||
```
|
||||
|
||||
#### 目录创建
|
||||
```java
|
||||
public File makePath(XxxVo xxx) {
|
||||
File basePath = getBasePath();
|
||||
if (!basePath.exists()) {
|
||||
holder.error("存储目录不存在：" + basePath.getAbsolutePath());
|
||||
return null;
|
||||
}
|
||||
|
||||
// 构建目录路径逻辑
|
||||
String fileName = FileUtils.escapeFileName(xxx.getName());
|
||||
File dir = new File(basePath, fileName);
|
||||
|
||||
if (!dir.exists()) {
|
||||
if (!dir.mkdir()) {
|
||||
holder.error("创建目录失败：" + dir.getAbsolutePath());
|
||||
return null;
|
||||
}
|
||||
}
|
||||
return dir;
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 业务验证模式
|
||||
|
||||
#### 数据完整性验证
|
||||
```java
|
||||
public void verifyXxx(XxxVo xxx, LocalDate verifyDate, MessageHolder holder) {
|
||||
// 检查关键字段
|
||||
if (!StringUtils.hasText(xxx.getCode())) {
|
||||
holder.error("编号异常：未设置");
|
||||
return;
|
||||
}
|
||||
|
||||
// 检查状态字段
|
||||
String status = xxx.getStatus();
|
||||
if (StringUtils.hasText(status) && status.contains("无效")) {
|
||||
LocalDate end = xxx.getEndDate();
|
||||
LocalDate begin = xxx.getBeginDate();
|
||||
if (begin == null || end == null) {
|
||||
holder.error("状态异常：" + status);
|
||||
} else {
|
||||
if (!MyDateTimeUtils.dateValidFilter(verifyDate, begin, end, 0)) {
|
||||
holder.error("状态异常：" + status);
|
||||
}
|
||||
}
|
||||
} else {
|
||||
holder.error("状态异常：未设置");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 关联实体验证
|
||||
```java
|
||||
public boolean verifyAsXxxType(XxxVo xxx, LocalDate verifyDate, MessageHolder holder) {
|
||||
boolean valid = false;
|
||||
|
||||
// 检查关联实体
|
||||
RelatedVo related = relatedService.findById(xxx.getRelatedId());
|
||||
if (related == null) {
|
||||
holder.error("关联实体不存在");
|
||||
valid = true;
|
||||
}
|
||||
|
||||
// 检查关联数据
|
||||
if (!StringUtils.hasText(xxx.getRelatedField())) {
|
||||
holder.error("关联字段未设置");
|
||||
valid = true;
|
||||
}
|
||||
|
||||
// 检查业务规则
|
||||
if (xxx.getStatus() == XxxStatus.INACTIVE) {
|
||||
holder.error("业务状态异常：已停用");
|
||||
valid = true;
|
||||
}
|
||||
|
||||
return valid;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 复杂业务查询
|
||||
|
||||
#### 分页查询
|
||||
```java
|
||||
public List<XxxVo> findAllByXxxCondition(XxxCondition condition, LocalDate beginDate, LocalDate endDate) {
|
||||
return findAll(ParamUtils.builder()
|
||||
.equals("field1", condition.getField1())
|
||||
.between("createDate", beginDate, endDate)
|
||||
.equals("status", "ACTIVE")
|
||||
.build(), Pageable.unpaged()).getContent();
|
||||
}
|
||||
```
|
||||
|
||||
#### 组合条件查询
|
||||
```java
|
||||
public Page<XxxVo> findAllWithComplexCondition(XxxQueryParam param) {
|
||||
ParamUtils.ParamBuilder builder = ParamUtils.builder()
|
||||
.equals("category", param.getCategory());
|
||||
|
||||
if (StringUtils.hasText(param.getName())) {
|
||||
builder.like("name", "%" + param.getName() + "%");
|
||||
}
|
||||
|
||||
if (param.getDateRange() != null) {
|
||||
builder.between("createDate", param.getDateRange().getStart(),
|
||||
param.getDateRange().getEnd());
|
||||
}
|
||||
|
||||
return findAll(builder.build(), Pageable.ofSize(param.getPageSize()));
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 工具类和依赖注入
|
||||
|
||||
### 1. 常用工具类依赖
|
||||
|
||||
```java
|
||||
// 常用注入
|
||||
@Autowired
|
||||
private SysConfService confService; // 系统配置服务
|
||||
@Autowired
|
||||
private RelatedService relatedService; // 关联实体服务
|
||||
|
||||
// 静态工具类使用
|
||||
import com.ecep.contract.util.FileUtils; // 文件工具
|
||||
import com.ecep.contract.util.ParamUtils; // 参数工具
|
||||
import com.ecep.contract.util.MyStringUtils; // 字符串工具
|
||||
```
|
||||
|
||||
### 2. 工具类使用示例
|
||||
|
||||
#### ParamUtils 构建查询条件
|
||||
```java
|
||||
// 构建复杂查询条件
|
||||
Map<String, Object> params = ParamUtils.builder()
|
||||
.equals("field1", value1)
|
||||
.equals("field2", value2)
|
||||
.like("name", "%" + keyword + "%")
|
||||
.between("date", startDate, endDate)
|
||||
.in("status", List.of("ACTIVE", "PENDING"))
|
||||
.orderBy("createTime", "desc")
|
||||
.build();
|
||||
```
|
||||
|
||||
#### FileUtils 处理文件路径
|
||||
```java
|
||||
// 文件名转义
|
||||
String safeFileName = FileUtils.escapeFileName(companyName);
|
||||
|
||||
// 获取父级前缀
|
||||
String parentPrefix = FileUtils.getParentPrefixByDistrict(district);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 错误处理和日志
|
||||
|
||||
### 1. 异常处理模式
|
||||
|
||||
```java
|
||||
// 查询异常处理
|
||||
try {
|
||||
return async("findByCode", code, String.class).handle((response, ex) -> {
|
||||
if (ex != null) {
|
||||
throw new RuntimeException("远程方法 findByCode 调用失败", ex);
|
||||
}
|
||||
if (response != null) {
|
||||
return updateValue(createNewEntity(), response);
|
||||
}
|
||||
return null;
|
||||
}).get();
|
||||
} catch (Exception e) {
|
||||
throw new RuntimeException("查找实体失败: " + code, e);
|
||||
}
|
||||
|
||||
// 业务验证异常
|
||||
public boolean businessMethod(XxxVo xxx) {
|
||||
if (xxx == null) {
|
||||
return false;
|
||||
}
|
||||
|
||||
if (!xxx.isValid()) {
|
||||
throw new IllegalArgumentException("实体数据无效");
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 日志记录
|
||||
|
||||
```java
|
||||
// 在 QueryService 中已集成日志
|
||||
private static final Logger logger = LoggerFactory.getLogger(QueryService.class);
|
||||
|
||||
// 在业务方法中使用
|
||||
public void deleteXxx(XxxVo xxx) {
|
||||
try {
|
||||
super.delete(xxx);
|
||||
logger.info("删除实体成功 #{}", xxx.getId());
|
||||
} catch (Exception e) {
|
||||
logger.error("删除实体失败 #{}", xxx.getId(), e);
|
||||
throw new RuntimeException("删除实体失败", e);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 测试和验证
|
||||
|
||||
### 1. 方法验证检查点
|
||||
|
||||
- **输入参数验证**：检查空值、格式、范围
|
||||
- **业务逻辑验证**：检查状态、关联、权限
|
||||
- **文件系统验证**：检查路径、权限、空间
|
||||
- **数据库验证**：检查连接、事务、一致性
|
||||
|
||||
### 2. 常见测试场景
|
||||
|
||||
```java
|
||||
// 测试用例示例
|
||||
@Test
|
||||
public void testFindById() {
|
||||
// 正常情况
|
||||
XxxVo result = xxxService.findById(1);
|
||||
assertNotNull(result);
|
||||
|
||||
// 异常情况
|
||||
assertThrows(RuntimeException.class, () -> {
|
||||
xxxService.findById(-1);
|
||||
});
|
||||
}
|
||||
|
||||
@Test
|
||||
public void testSaveWithCache() {
|
||||
XxxVo xxx = createTestXxx();
|
||||
xxx.setCode("TEST001");
|
||||
|
||||
XxxVo saved = xxxService.save(xxx);
|
||||
assertNotNull(saved.getId());
|
||||
|
||||
// 验证缓存
|
||||
XxxVo cached = xxxService.findById(saved.getId());
|
||||
assertEquals(saved.getId(), cached.getId());
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 最佳实践
|
||||
|
||||
### 1. 代码组织原则
|
||||
|
||||
- **单一职责**：每个 Service 专注特定的业务域
|
||||
- **依赖注入**：合理使用 `@Autowired` 注入依赖
|
||||
- **缓存策略**：为高频查询字段配置缓存
|
||||
- **异常处理**：统一处理业务异常和系统异常
|
||||
|
||||
### 2. 性能优化建议
|
||||
|
||||
- **缓存配置**：合理设置缓存过期时间
|
||||
- **分页查询**：避免大数据量一次性查询
|
||||
- **异步处理**：使用异步调用提升响应速度
|
||||
- **批量操作**：考虑批量处理减少网络开销
|
||||
|
||||
### 3. 可维护性提升
|
||||
|
||||
- **命名规范**：遵循项目统一的命名约定
|
||||
- **注释文档**：为复杂业务逻辑添加注释
|
||||
- **代码复用**：提取公共逻辑到工具类
|
||||
- **版本兼容**：考虑前后端版本兼容性
|
||||
|
||||
---
|
||||
|
||||
## 📚 相关规范
|
||||
|
||||
- **Controller 规范**：[client_controller_rules.md](.trae/rules/client_controller_rules.md)
|
||||
- **转换器规范**：[client_converter_rules.md](.trae/rules/client_converter_rules.md)
|
||||
- **Task 规范**：[client_task_rules.md](.trae/rules/client_task_rules.md)
|
||||
- **Entity 规范**：[entity_rules.md](.trae/rules/entity_rules.md)
|
||||
- **VO 规范**：[vo_rules.md](.trae/rules/vo_rules.md)
|
||||
|
||||
---
|
||||
|
||||
*本文档基于 Contract-Manager 项目现有 Service 实现模式总结，遵循项目既定的技术架构和编程规范。*
|
||||
|
||||
**文档版本**: v1.0.0
|
||||
**最后更新**: 2024-12-19
|
||||
**维护团队**: Contract Manager Development Team
|
||||
374
.trae/rules/repository_comprehensive_analysis_report.md
Normal file
374
.trae/rules/repository_comprehensive_analysis_report.md
Normal file
@@ -0,0 +1,374 @@
|
||||
# Repository一致性分析 - 综合报告
|
||||
|
||||
## 📊 执行摘要
|
||||
|
||||
### 分析概览
|
||||
- **总Repository数量**: 22个
|
||||
- **涉及业务域**: contract, company, customer, project, vendor
|
||||
- **分析时间**: 2024年项目全面分析
|
||||
- **分析范围**: 覆盖server模块下所有5个业务域的Repository实现
|
||||
|
||||
### 目录覆盖情况
|
||||
✅ `server/src/main/java/com/ecep/contract/ds/contract/repository/` (13个)
|
||||
✅ `server/src/main/java/com/ecep/contract/ds/company/repository/` (3个)
|
||||
✅ `server/src/main/java/com/ecep/contract/ds/customer/repository/` (2个)
|
||||
✅ `server/src/main/java/com/ecep/contract/ds/project/repository/` (3个)
|
||||
✅ `server/src/main/java/com/ecep/contract/ds/vendor/repository/` (2个)
|
||||
|
||||
## 🔍 关键发现与评估
|
||||
|
||||
### 🔴 严重问题：继承层次不一致（5个）
|
||||
|
||||
#### 1. 直接继承JpaRepository（4个）
|
||||
- `ContractFileRepository` - 直接继承`JpaRepository`和`JpaSpecificationExecutor`
|
||||
- `ContractItemRepository` - 直接继承`JpaRepository`和`JpaSpecificationExecutor`
|
||||
- `VendorFileRepository` - 直接继承`JpaRepository`和`JpaSpecificationExecutor`
|
||||
- `ProjectQuotationRepository` - 直接继承`JpaRepository`和`JpaSpecificationExecutor`
|
||||
|
||||
#### 2. 继承多个冗余接口（1个）
|
||||
- `PurchaseOrderRepository` - 同时继承了4个接口：`CrudRepository`, `PagingAndSortingRepository`, `JpaRepository`, `JpaSpecificationExecutor`
|
||||
|
||||
### 🟡 中等问题（6个）
|
||||
|
||||
#### 注解缺失（2个）
|
||||
- `CompanyFileRepository` - 缺少`@Repository`注解
|
||||
- `ProjectFileRepository` - 缺少`@Repository`注解
|
||||
|
||||
#### 文档注释缺失（4个）
|
||||
- `CompanyFileRepository` - 缺少JavaDoc注释
|
||||
- `ProjectFileRepository` - 缺少JavaDoc注释
|
||||
- `VendorFileRepository` - 缺少JavaDoc注释
|
||||
- `ProjectQuotationRepository` - 缺少JavaDoc注释
|
||||
|
||||
### 📈 整体质量评估
|
||||
|
||||
#### 正确实现统计
|
||||
- ✅ **17个Repository正确继承MyRepository** (77%)
|
||||
- ❌ **5个Repository继承层次错误** (23%)
|
||||
- 🟡 **2个Repository缺少注解** (9%)
|
||||
- 🟡 **4个Repository文档不完整** (18%)
|
||||
|
||||
#### 质量分级分布
|
||||
- **A级（完全正确）**: 13个 (59%)
|
||||
- **B级（轻微问题）**: 6个 (27%)
|
||||
- **C级（严重错误）**: 3个 (14%)
|
||||
|
||||
---
|
||||
|
||||
# 详细技术分析
|
||||
|
||||
## 继承一致性详细分析
|
||||
|
||||
### ✅ 正确继承MyRepository的Repository（17个）
|
||||
|
||||
**contract业务域（7个）：**
|
||||
- ContractRepository
|
||||
- ContractBalanceRepository
|
||||
- SalesOrderRepository
|
||||
- ContractTypeRepository
|
||||
- ContractKindRepository
|
||||
- ContractInvoiceRepository
|
||||
|
||||
**company业务域（3个）：**
|
||||
- CompanyRepository
|
||||
- CompanyFileRepository (有注解问题)
|
||||
- CompanyCustomerRepository
|
||||
|
||||
**customer业务域（2个）：**
|
||||
- CustomerCatalogRepository
|
||||
|
||||
**project业务域（2个）：**
|
||||
- ProjectRepository
|
||||
- ProjectFileRepository (有注解问题)
|
||||
|
||||
**vendor业务域（1个）：**
|
||||
- VendorRepository
|
||||
|
||||
### ❌ 继承层次错误的Repository（5个）
|
||||
|
||||
#### Contract业务域（3个）
|
||||
1. **ContractFileRepository**
|
||||
2. **ContractItemRepository**
|
||||
3. **PurchaseOrderRepository**
|
||||
|
||||
#### Project业务域（1个）
|
||||
4. **ProjectQuotationRepository**
|
||||
|
||||
#### Vendor业务域（1个）
|
||||
5. **VendorFileRepository**
|
||||
|
||||
## 问题影响分析
|
||||
|
||||
### 技术影响
|
||||
- ❌ 违反了统一的架构设计原则
|
||||
- ❌ 失去了MyRepository提供的统一功能增强
|
||||
- ❌ 代码风格不一致，影响可维护性
|
||||
- ❌ 开发团队需要维护多种不同的实现模式
|
||||
- ❌ 增加了代码维护成本和技术债务
|
||||
|
||||
### 业务影响
|
||||
- ❌ 代码可维护性降低
|
||||
- ❌ 新团队成员学习成本增加
|
||||
- ❌ 代码审查复杂度提高
|
||||
- ❌ 系统稳定性潜在风险增加
|
||||
|
||||
## 详细修复方案
|
||||
|
||||
### 🔴 优先级1：修复继承层次错误
|
||||
|
||||
#### 1. ContractFileRepository
|
||||
```java
|
||||
// ❌ 当前错误实现
|
||||
public interface ContractFileRepository
|
||||
extends JpaRepository<ContractFile, Integer>, JpaSpecificationExecutor<ContractFile> {
|
||||
|
||||
// ✅ 正确修复
|
||||
@Repository
|
||||
public interface ContractFileRepository extends MyRepository<ContractFile, Integer> {
|
||||
// 自动获得MyRepository提供的所有功能
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. ContractItemRepository
|
||||
```java
|
||||
// ❌ 当前错误实现
|
||||
public interface ContractItemRepository
|
||||
extends JpaRepository<ContractItem, Integer>, JpaSpecificationExecutor<ContractItem> {
|
||||
|
||||
// ✅ 正确修复
|
||||
@Repository
|
||||
public interface ContractItemRepository extends MyRepository<ContractItem, Integer> {
|
||||
// 统一继承结构，简化维护
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. VendorFileRepository
|
||||
```java
|
||||
// ❌ 当前错误实现
|
||||
@Repository
|
||||
public interface VendorFileRepository
|
||||
extends JpaRepository<VendorFile, Integer>, JpaSpecificationExecutor<VendorFile> {
|
||||
|
||||
// ✅ 正确修复
|
||||
@Repository
|
||||
public interface VendorFileRepository extends MyRepository<VendorFile, Integer> {
|
||||
// 保持注解的同时修正继承结构
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. ProjectQuotationRepository
|
||||
```java
|
||||
// ❌ 当前错误实现
|
||||
@Repository
|
||||
public interface ProjectQuotationRepository
|
||||
extends JpaRepository<ProjectQuotation, Integer>, JpaSpecificationExecutor<ProjectQuotation> {
|
||||
|
||||
// ✅ 正确修复
|
||||
@Repository
|
||||
public interface ProjectQuotationRepository extends MyRepository<ProjectQuotation, Integer> {
|
||||
// 获得MyRepository的所有增强功能
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. PurchaseOrderRepository
|
||||
```java
|
||||
// ❌ 当前错误实现（继承4个冗余接口）
|
||||
public interface PurchaseOrderRepository extends
|
||||
CrudRepository<PurchaseOrder, Integer>,
|
||||
PagingAndSortingRepository<PurchaseOrder, Integer>,
|
||||
JpaRepository<PurchaseOrder, Integer>,
|
||||
JpaSpecificationExecutor<PurchaseOrder> {
|
||||
|
||||
// ✅ 正确修复
|
||||
@Repository
|
||||
public interface PurchaseOrderRepository extends MyRepository<PurchaseOrder, Integer> {
|
||||
// 单一继承，清晰简洁
|
||||
}
|
||||
```
|
||||
|
||||
### 🟡 优先级2：修复注解缺失
|
||||
|
||||
#### CompanyFileRepository
|
||||
```java
|
||||
// ❌ 当前缺少注解
|
||||
public interface CompanyFileRepository extends MyRepository<CompanyFile, Integer> {
|
||||
|
||||
// ✅ 添加注解
|
||||
@Repository
|
||||
public interface CompanyFileRepository extends MyRepository<CompanyFile, Integer> {
|
||||
// 添加完整的JavaDoc注释
|
||||
/**
|
||||
* 公司文件数据访问接口
|
||||
* 提供公司相关文件的CRUD操作和业务查询功能
|
||||
*/
|
||||
}
|
||||
```
|
||||
|
||||
#### ProjectFileRepository
|
||||
```java
|
||||
// ❌ 当前缺少注解
|
||||
public interface ProjectFileRepository extends MyRepository<ProjectFile, Integer> {
|
||||
|
||||
// ✅ 添加注解
|
||||
@Repository
|
||||
public interface ProjectFileRepository extends MyRepository<ProjectFile, Integer> {
|
||||
/**
|
||||
* 项目文件数据访问接口
|
||||
* 提供项目文件的管理和查询功能
|
||||
*/
|
||||
}
|
||||
```
|
||||
|
||||
### 🟡 优先级3：完善文档注释
|
||||
|
||||
为以下Repository补充完整的JavaDoc注释：
|
||||
- CompanyFileRepository
|
||||
- ProjectFileRepository
|
||||
- VendorFileRepository
|
||||
- ProjectQuotationRepository
|
||||
|
||||
标准JavaDoc格式示例：
|
||||
```java
|
||||
/**
|
||||
* [功能描述]数据访问接口
|
||||
*
|
||||
* 提供[业务描述]的CRUD操作和业务查询功能
|
||||
*
|
||||
* @author [作者]
|
||||
* @since [版本]
|
||||
*/
|
||||
```
|
||||
|
||||
## 实施计划
|
||||
|
||||
### 阶段1：立即修复（1-2天）
|
||||
**目标**: 解决所有严重的继承层次错误
|
||||
|
||||
**执行步骤**:
|
||||
1. 备份当前的Repository实现
|
||||
2. 逐一修复5个继承层次错误的Repository
|
||||
3. 添加缺失的@Repository注解
|
||||
4. 运行编译测试确保无破坏性变更
|
||||
5. 执行基本功能验证测试
|
||||
|
||||
**验收标准**:
|
||||
- 所有Repository都继承MyRepository
|
||||
- 编译通过，无语法错误
|
||||
- 基本CRUD功能正常
|
||||
|
||||
### 阶段2：文档完善（1天）
|
||||
**目标**: 统一JavaDoc注释规范
|
||||
|
||||
**执行步骤**:
|
||||
1. 为4个Repository补充JavaDoc注释
|
||||
2. 检查并更新相关单元测试
|
||||
3. 验证文档格式规范性
|
||||
4. 代码审查确认
|
||||
|
||||
**验收标准**:
|
||||
- 所有Repository都有完整的JavaDoc注释
|
||||
- 测试用例覆盖主要功能
|
||||
- 代码审查通过
|
||||
|
||||
### 阶段3：质量保证（半天）
|
||||
**目标**: 确保修改不影响系统稳定性
|
||||
|
||||
**执行步骤**:
|
||||
1. 全面编译测试
|
||||
2. 运行相关单元测试套件
|
||||
3. 执行集成测试验证
|
||||
4. 更新相关文档
|
||||
5. 最终验收确认
|
||||
|
||||
**验收标准**:
|
||||
- 所有测试通过
|
||||
- 系统功能完整
|
||||
- 性能无明显影响
|
||||
|
||||
## 对规范文档的影响
|
||||
|
||||
### ✅ 已更新的规范文档
|
||||
- **`server_repository_rules.md`** - 已包含错误示例和正确实现指南
|
||||
- 新增"2.2 重要错误示例"章节
|
||||
- 新增"2.3 当前项目错误统计"章节
|
||||
- 新增"2.5 MyRepository基类能力"章节
|
||||
|
||||
### 📋 需要更新的检查清单
|
||||
1. **继承层次检查** - 确保所有Repository继承MyRepository
|
||||
2. **注解完整性检查** - 验证所有Repository都有@Repository注解
|
||||
3. **文档规范性检查** - 确认JavaDoc注释完整性
|
||||
4. **代码风格一致性检查** - 验证命名规范和代码格式
|
||||
|
||||
## 🎯 预期收益
|
||||
|
||||
### 技术收益
|
||||
- ✅ **统一架构设计** - 所有Repository遵循一致的设计模式
|
||||
- ✅ **代码一致性提升** - 消除实现差异，提高代码质量
|
||||
- ✅ **维护成本降低** - 单一继承结构，简化维护工作
|
||||
- ✅ **团队开发效率提升** - 统一规范，降低学习成本
|
||||
|
||||
### 质量收益
|
||||
- ✅ **减少代码冗余** - 消除重复的接口继承
|
||||
- ✅ **提高代码可读性** - 统一模式，易于理解
|
||||
- ✅ **降低技术债务** - 减少不一致实现的技术负担
|
||||
- ✅ **增强系统稳定性** - 统一模式，减少潜在风险
|
||||
|
||||
## 📅 后续行动
|
||||
|
||||
### 立即行动（本周）
|
||||
1. 🔧 修复5个继承层次错误的Repository
|
||||
2. 🔧 添加缺失的@Repository注解
|
||||
3. 🔧 编译测试验证功能完整性
|
||||
|
||||
### 短期完善（下周）
|
||||
1. 📝 补充JavaDoc文档注释
|
||||
2. 🧪 运行完整的单元测试套件
|
||||
3. 👥 代码审查确认实现质量
|
||||
|
||||
### 长期维护
|
||||
1. 📋 建立Repository开发规范检查清单
|
||||
2. 🔍 定期进行Repository实现一致性检查
|
||||
3. 🎓 团队培训和规范宣贯
|
||||
4. 🤖 建立CI/CD流程中的自动检查机制
|
||||
|
||||
## 📞 技术支持
|
||||
|
||||
如需技术支持或有任何疑问，请参考：
|
||||
|
||||
### 相关文档
|
||||
- **详细技术分析**: `repository_analysis_report.md`
|
||||
- **实施规范指导**: `server_repository_rules.md`
|
||||
- **项目整体规范**: `.trae/rules/` 目录
|
||||
|
||||
### 联系方式
|
||||
- 技术问题: 参考详细分析报告中的修复代码示例
|
||||
- 规范疑问: 查看server_repository_rules.md文档
|
||||
- 实施支持: 遵循本报告的分阶段实施计划
|
||||
|
||||
---
|
||||
|
||||
## 结论
|
||||
|
||||
通过对项目中22个Repository的全面分析，我们发现了明显的实现不一致性问题，特别是23%的Repository存在继承层次错误。这些问题严重影响了代码的可维护性和架构的统一性。
|
||||
|
||||
**关键统计数据**:
|
||||
- 17个Repository正确实现 (77%)
|
||||
- 5个继承层次错误 (23%)
|
||||
- 2个注解缺失 (9%)
|
||||
- 4个文档不完整 (18%)
|
||||
|
||||
**修复优先级**:
|
||||
1. **高优先级**: 修复5个继承层次错误（1-2天）
|
||||
2. **中优先级**: 补充2个缺失注解（半天）
|
||||
3. **低优先级**: 完善4个文档注释（1天）
|
||||
|
||||
建议按照本报告提出的分阶段实施计划，逐步改进所有Repository实现，确保项目达到统一的架构设计标准。通过这些改进，将显著提升代码质量、降低维护成本，并为团队的长期发展奠定坚实基础。
|
||||
|
||||
**分析状态**: ✅ 完成
|
||||
**下一步**: 执行分阶段修复计划
|
||||
**预计完成时间**: 3-4个工作日
|
||||
|
||||
---
|
||||
**报告生成时间**: 2024年
|
||||
**分析深度**: 全面技术分析
|
||||
**实施可行性**: 高（详细修复方案已提供）
|
||||
460
.trae/rules/server_repository_rules.md
Normal file
460
.trae/rules/server_repository_rules.md
Normal file
@@ -0,0 +1,460 @@
|
||||
# Server模块 Repository 实现经验总结
|
||||
|
||||
## 1. Repository 基本架构
|
||||
|
||||
### 1.1 接口设计原则
|
||||
- Repository接口必须继承`MyRepository<T, ID>`基类
|
||||
- 使用`@Repository`注解标记为Spring组件
|
||||
- 遵循接口隔离原则，按业务功能组织方法
|
||||
|
||||
### 1.2 包结构规范
|
||||
```
|
||||
com.ecep.contract.ds.{business}.repository.{EntityName}Repository.java
|
||||
```
|
||||
示例：`ContractBalanceRepository`位于`com.ecep.contract.ds.contract.repository`
|
||||
|
||||
## 2. 接口继承层次
|
||||
|
||||
### 2.1 基础接口结构
|
||||
```java
|
||||
@Repository
|
||||
public interface ContractBalanceRepository extends MyRepository<ContractBalance, Integer> {
|
||||
// 自定义查询方法
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 ⚠️ 重要错误示例 - 避免这些实现方式
|
||||
|
||||
**❌ 错误示例1：直接继承JpaRepository**
|
||||
```java
|
||||
// ContractFileRepository, ContractItemRepository, VendorFileRepository, ProjectQuotationRepository
|
||||
@Repository
|
||||
public interface ContractFileRepository
|
||||
extends JpaRepository<ContractFile, Integer>, JpaSpecificationExecutor<ContractFile> {
|
||||
// 错误：不应该直接继承JpaRepository
|
||||
List<ContractFile> findByContractId(Integer contractId);
|
||||
}
|
||||
```
|
||||
|
||||
**❌ 错误示例2：继承多个冗余接口**
|
||||
```java
|
||||
// PurchaseOrderRepository
|
||||
public interface PurchaseOrderRepository extends
|
||||
CrudRepository<PurchaseOrder, Integer>,
|
||||
PagingAndSortingRepository<PurchaseOrder, Integer>,
|
||||
JpaRepository<PurchaseOrder, Integer>,
|
||||
JpaSpecificationExecutor<PurchaseOrder> {
|
||||
// 错误：冗余接口继承，应该只继承MyRepository
|
||||
}
|
||||
```
|
||||
|
||||
**❌ 错误示例3：缺少@Repository注解**
|
||||
```java
|
||||
// CompanyFileRepository, ProjectFileRepository
|
||||
public interface CompanyFileRepository extends MyRepository<CompanyFile, Integer> {
|
||||
// 错误：缺少@Repository注解
|
||||
List<CompanyFile> findByCompany(Company company);
|
||||
}
|
||||
```
|
||||
|
||||
**❌ 错误示例4：缺少JavaDoc注释**
|
||||
```java
|
||||
// 多个Repository存在此问题
|
||||
public interface VendorFileRepository extends MyRepository<VendorFile, Integer> {
|
||||
// 错误：缺少JavaDoc注释说明用途和方法
|
||||
List<VendorFile> findAllByVendorId(int vendorId);
|
||||
}
|
||||
```
|
||||
|
||||
**✅ 正确实现示例**
|
||||
```java
|
||||
/**
|
||||
* 合同Repository - 提供合同相关的数据库访问操作
|
||||
*/
|
||||
@Repository
|
||||
public interface ContractRepository extends MyRepository<Contract, Integer> {
|
||||
// 正确：统一继承MyRepository，有完整的JavaDoc
|
||||
|
||||
/**
|
||||
* 根据合同代码查询合同
|
||||
* @param code 合同代码
|
||||
* @return 合同 Optional
|
||||
*/
|
||||
Optional<Contract> findByCode(String code);
|
||||
|
||||
/**
|
||||
* 根据状态查询合同列表
|
||||
* @param status 合同状态
|
||||
* @return 合同列表
|
||||
*/
|
||||
List<Contract> findByStatus(ContractStatus status);
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 当前项目错误统计
|
||||
|
||||
基于对全项目22个Repository的全面分析，发现以下问题分布：
|
||||
|
||||
**🔴 继承层次错误（5个）：**
|
||||
- `ContractFileRepository` - 直接继承JpaRepository
|
||||
- `ContractItemRepository` - 直接继承JpaRepository
|
||||
- `VendorFileRepository` - 直接继承JpaRepository
|
||||
- `ProjectQuotationRepository` - 直接继承JpaRepository
|
||||
- `PurchaseOrderRepository` - 继承4个冗余接口
|
||||
|
||||
**🟡 注解缺失（2个）：**
|
||||
- `CompanyFileRepository` - 缺少@Repository注解
|
||||
- `ProjectFileRepository` - 缺少@Repository注解
|
||||
|
||||
**🟡 文档注释不完整（4个）：**
|
||||
- `CompanyFileRepository` - 缺少JavaDoc注释
|
||||
- `ProjectFileRepository` - 缺少JavaDoc注释
|
||||
- `VendorFileRepository` - 缺少JavaDoc注释
|
||||
- `ProjectQuotationRepository` - 缺少JavaDoc注释
|
||||
|
||||
**✅ 正确实现（17个）：**
|
||||
- contract: ContractRepository, ContractBalanceRepository, SalesOrderRepository, ContractTypeRepository, ContractKindRepository, ContractInvoiceRepository
|
||||
- company: CompanyRepository
|
||||
- customer: CompanyCustomerRepository, CustomerCatalogRepository
|
||||
- project: ProjectRepository
|
||||
- vendor: VendorRepository
|
||||
|
||||
### 2.5 MyRepository基类能力
|
||||
|
||||
`MyRepository`接口继承结构：
|
||||
- `JpaRepository`提供CRUD操作
|
||||
- 继承`JpaSpecificationExecutor`提供条件查询能力
|
||||
- 继承`QueryByExampleExecutor`提供示例查询能力
|
||||
|
||||
## 3. 查询方法设计
|
||||
|
||||
### 3.1 方法命名规范
|
||||
使用Spring Data JPA的查询方法命名约定：
|
||||
|
||||
#### 基本查询方法
|
||||
- `findBy{属性名}` - 根据属性查找
|
||||
- `findBy{属性名}And{属性名}` - 多条件AND查询
|
||||
- `findBy{属性名}Or{属性名}` - 多条件OR查询
|
||||
- `findBy{属性名}OrderBy{排序属性}` - 带排序查询
|
||||
|
||||
#### 关联对象查询
|
||||
- `findBy{关联对象属性名}.{关联对象属性}` - 嵌套属性查询
|
||||
- 支持多级嵌套，如：`findByContractCompanyName`
|
||||
|
||||
#### 特殊查询类型
|
||||
```java
|
||||
// 根据业务ID查找
|
||||
ContractBalance findByGuid(UUID guid);
|
||||
|
||||
// 根据合同ID查找（带分页支持）
|
||||
Page<ContractBalance> findByContractId(Integer contractId, Pageable pageable);
|
||||
|
||||
// 根据多个条件组合查询
|
||||
List<ContractBalance> findByContractIdAndRefId(Integer contractId, String refId);
|
||||
```
|
||||
|
||||
### 3.2 自定义查询实现
|
||||
当方法命名无法满足需求时，使用`@Query`注解：
|
||||
|
||||
```java
|
||||
@Query("SELECT cb FROM ContractBalance cb WHERE cb.contract.id = :contractId " +
|
||||
"AND cb.guid = :guid AND cb.setupDate >= :startDate")
|
||||
Page<ContractBalance> findByContractAndGuidAndDateRange(
|
||||
@Param("contractId") Integer contractId,
|
||||
@Param("guid") UUID guid,
|
||||
@Param("startDate") LocalDateTime startDate,
|
||||
Pageable pageable
|
||||
);
|
||||
```
|
||||
|
||||
## 4. 分页和排序支持
|
||||
|
||||
### 4.1 分页查询
|
||||
```java
|
||||
// 在Repository接口中定义
|
||||
Page<ContractBalance> findByContractId(Integer contractId, Pageable pageable);
|
||||
|
||||
// 在Service中调用
|
||||
Page<ContractBalance> result = repository.findByContractId(contractId,
|
||||
PageRequest.of(page, size, Sort.by("setupDate").descending()));
|
||||
```
|
||||
|
||||
### 4.2 排序规范
|
||||
- 默认按主键ID降序排列
|
||||
- 业务相关字段按创建时间降序
|
||||
- 支持多字段排序：`Sort.by("field1").ascending().and(Sort.by("field2").descending())`
|
||||
|
||||
## 5. 统计和聚合查询
|
||||
|
||||
### 5.1 基础统计
|
||||
```java
|
||||
@Query("SELECT COUNT(cb) FROM ContractBalance cb WHERE cb.contract.id = :contractId")
|
||||
Long countByContractId(@Param("contractId") Integer contractId);
|
||||
|
||||
@Query("SELECT SUM(cb.balanceAmount) FROM ContractBalance cb WHERE cb.contract.id = :contractId")
|
||||
BigDecimal sumBalanceByContractId(@Param("contractId") Integer contractId);
|
||||
```
|
||||
|
||||
### 5.2 复杂聚合
|
||||
```java
|
||||
@Query("SELECT new com.ecep.contract.vo.ContractBalanceStatsVO(" +
|
||||
"cb.contract.id, COUNT(cb), SUM(cb.balanceAmount)) " +
|
||||
"FROM ContractBalance cb GROUP BY cb.contract.id")
|
||||
List<ContractBalanceStatsVO> getBalanceStatsByContract();
|
||||
```
|
||||
|
||||
## 6. 缓存策略
|
||||
|
||||
### 6.1 缓存注解使用
|
||||
虽然Repository本身不直接使用缓存，但需要考虑Service层的缓存需求：
|
||||
|
||||
```java
|
||||
// 在Service层配合使用
|
||||
@Cacheable(key = "#p0")
|
||||
ContractBalance findById(Integer id);
|
||||
|
||||
@CacheEvict(key = "#p0.id")
|
||||
ContractBalance save(ContractBalance contractBalance);
|
||||
```
|
||||
|
||||
### 6.2 缓存键设计原则
|
||||
- 单一记录：使用主键作为键，如`"balance-" + id`
|
||||
- 按业务维度缓存：使用业务标识，如`"contract-" + contractId`
|
||||
- 避免缓存键冲突
|
||||
|
||||
## 7. 事务管理
|
||||
|
||||
### 7.1 事务传播级别
|
||||
- 查询方法：默认`REQUIRED`
|
||||
- 写操作：明确指定`@Transactional(propagation = Propagation.REQUIRED)`
|
||||
|
||||
### 7.2 异常处理
|
||||
```java
|
||||
@Transactional
|
||||
public ContractBalance saveWithRetry(ContractBalance balance) {
|
||||
try {
|
||||
return repository.save(balance);
|
||||
} catch (DataIntegrityViolationException e) {
|
||||
// 处理数据完整性异常
|
||||
throw new BusinessException("数据重复或违反约束", e);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 8. 性能优化
|
||||
|
||||
### 8.1 懒加载优化
|
||||
```java
|
||||
// 在查询时指定抓取策略
|
||||
@Query("SELECT cb FROM ContractBalance cb LEFT JOIN FETCH cb.contract " +
|
||||
"LEFT JOIN FETCH cb.employee WHERE cb.id = :id")
|
||||
Optional<ContractBalance> findByIdWithRelations(@Param("id") Integer id);
|
||||
```
|
||||
|
||||
### 8.2 批量操作优化
|
||||
```java
|
||||
// 批量插入
|
||||
@Modifying
|
||||
@Query("DELETE FROM ContractBalance cb WHERE cb.contract.id IN :contractIds")
|
||||
void deleteByContractIds(@Param("contractIds") List<Integer> contractIds);
|
||||
```
|
||||
|
||||
## 9. 错误处理和调试
|
||||
|
||||
### 9.1 常见异常类型
|
||||
- `DataAccessException` - 数据访问异常
|
||||
- `DataIntegrityViolationException` - 数据完整性异常
|
||||
- `EmptyResultDataAccessException` - 空结果异常
|
||||
|
||||
### 9.2 日志记录
|
||||
```java
|
||||
@Repository
|
||||
@Slf4j
|
||||
public class ContractBalanceRepository {
|
||||
|
||||
@Query("...")
|
||||
public List<ContractBalance> findComplexQuery(...) {
|
||||
log.debug("执行复杂查询: {}", jpql);
|
||||
// 执行查询
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 10. 测试策略
|
||||
|
||||
### 10.1 Repository测试
|
||||
```java
|
||||
@DataJpaTest
|
||||
@TestInstance(TestInstance.Lifecycle.PER_CLASS)
|
||||
class ContractBalanceRepositoryTest {
|
||||
|
||||
@Autowired
|
||||
private TestEntityManager em;
|
||||
|
||||
@Autowired
|
||||
private ContractBalanceRepository repository;
|
||||
|
||||
@Test
|
||||
void shouldFindByContractId() {
|
||||
// 测试数据准备
|
||||
ContractBalance balance = createTestBalance();
|
||||
|
||||
// 执行测试
|
||||
Page<ContractBalance> result = repository.findByContractId(
|
||||
balance.getContract().getId(),
|
||||
PageRequest.of(0, 10)
|
||||
);
|
||||
|
||||
// 断言验证
|
||||
assertThat(result.getContent()).hasSize(1);
|
||||
assertThat(result.getContent().get(0)).isEqualTo(balance);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 10.2 性能测试
|
||||
```java
|
||||
@Test
|
||||
@RepeatedTest(100)
|
||||
@Timeout(value = 5, unit = TimeUnit.SECONDS)
|
||||
void performanceTest() {
|
||||
// 性能测试实现
|
||||
}
|
||||
```
|
||||
|
||||
## 11. 最佳实践总结
|
||||
|
||||
### 11.1 设计原则
|
||||
1. **单一职责**：每个Repository只负责一个实体类型
|
||||
2. **接口隔离**：根据客户端需求设计专用查询方法
|
||||
3. **命名清晰**：方法名应能直观表达查询意图
|
||||
4. **性能优先**：合理使用索引和查询优化
|
||||
|
||||
### 11.2 代码规范
|
||||
1. **注解完整**：正确使用`@Repository`、`@Query`、`@Param`
|
||||
2. **参数校验**：对传入参数进行null和有效性检查
|
||||
3. **异常处理**：捕获并处理数据库访问异常
|
||||
4. **日志记录**：记录关键查询操作和性能指标
|
||||
|
||||
### 11.3 维护性
|
||||
1. **版本兼容**：考虑数据库模式变更的影响
|
||||
2. **向后兼容**：新增方法不影响现有功能
|
||||
3. **文档完整**：复杂查询添加JavaDoc说明
|
||||
4. **测试覆盖**：确保关键查询逻辑有测试覆盖
|
||||
|
||||
## 12. 常见问题和解决方案
|
||||
|
||||
### 12.1 N+1查询问题
|
||||
**问题**：查询列表时触发N+1次关联查询
|
||||
**解决**：使用`JOIN FETCH`或`@EntityGraph`
|
||||
|
||||
### 12.2 性能瓶颈
|
||||
**问题**：复杂查询导致响应慢
|
||||
**解决**：
|
||||
1. 添加数据库索引
|
||||
2. 优化查询语句
|
||||
3. 使用分页限制结果集
|
||||
4. 考虑使用缓存
|
||||
|
||||
### 12.3 事务死锁
|
||||
**问题**：并发操作导致事务死锁
|
||||
**解决**：
|
||||
1. 合理设计事务边界
|
||||
2. 调整事务隔离级别
|
||||
3. 实现重试机制
|
||||
|
||||
## 13. 扩展建议
|
||||
|
||||
### 13.1 动态查询支持
|
||||
考虑使用`Querydsl`或`Specification`支持动态查询构建。
|
||||
|
||||
### 13.2 读写分离
|
||||
实现主从数据库分离，提升查询性能。
|
||||
|
||||
### 13.3 分布式缓存
|
||||
结合Redis等分布式缓存，提升查询性能。
|
||||
|
||||
---
|
||||
|
||||
## 14. 实施检查清单
|
||||
|
||||
### 14.1 Repository实现后验证步骤
|
||||
在每个Repository实现完成后，请按以下清单进行验证：
|
||||
|
||||
#### ✅ 基础架构检查
|
||||
- [ ] Repository接口继承了 `MyRepository<T, ID>`
|
||||
- [ ] 使用了 `@Repository` 注解
|
||||
- [ ] 包路径符合规范：`com.ecep.contract.ds.{business}.repository`
|
||||
- [ ] 类名符合命名规范：`{EntityName}Repository`
|
||||
|
||||
#### ✅ 方法设计检查
|
||||
- [ ] 遵循Spring Data JPA命名约定
|
||||
- [ ] 包含必要的业务查询方法
|
||||
- [ ] 复杂查询使用 `@Query` 注解
|
||||
- [ ] 分页方法支持 `Pageable` 参数
|
||||
|
||||
#### ✅ 文档和注释检查
|
||||
- [ ] 类级别JavaDoc注释完整
|
||||
- [ ] 关键方法有JavaDoc说明
|
||||
- [ ] 参数和返回值有明确说明
|
||||
|
||||
#### ✅ 性能和质量检查
|
||||
- [ ] 避免N+1查询问题
|
||||
- [ ] 适当使用索引提示
|
||||
- [ ] 包含必要的单元测试
|
||||
- [ ] 异常处理考虑周全
|
||||
|
||||
### 14.2 常见错误检查
|
||||
在提交代码前，特别检查是否犯了以下常见错误：
|
||||
|
||||
#### ❌ 继承层次错误
|
||||
```java
|
||||
// 错误示例 - 不要这样做
|
||||
public interface SomeRepository extends JpaRepository<Entity, Integer>
|
||||
public interface AnotherRepository extends CrudRepository<Entity, Integer>
|
||||
|
||||
// 正确做法 - 统一使用MyRepository
|
||||
public interface SomeRepository extends MyRepository<Entity, Integer>
|
||||
```
|
||||
|
||||
#### ❌ 方法命名不规范
|
||||
```java
|
||||
// 错误示例
|
||||
List<Entity> getDataByCondition(String condition) // 使用get前缀而非find
|
||||
|
||||
// 正确做法
|
||||
List<Entity> findByCondition(String condition) // 使用find前缀
|
||||
```
|
||||
|
||||
#### ❌ 缺少必要文档
|
||||
```java
|
||||
// 错误示例 - 无注释
|
||||
List<Entity> findByStatus(String status);
|
||||
|
||||
// 正确做法 - 完整注释
|
||||
/**
|
||||
* 根据状态查询实体列表
|
||||
*
|
||||
* @param status 状态值
|
||||
* @return 符合状态的实体列表
|
||||
*/
|
||||
List<Entity> findByStatus(String status);
|
||||
```
|
||||
|
||||
### 14.3 架构一致性验证
|
||||
确保新实现的Repository与项目中其他Repository保持一致：
|
||||
|
||||
1. **继承模式统一**：所有Repository都必须继承MyRepository
|
||||
2. **注解使用统一**：统一使用@Repository注解
|
||||
3. **命名约定统一**：遵循Spring Data JPA命名规范
|
||||
4. **文档风格统一**：保持JavaDoc注释风格一致
|
||||
|
||||
### 14.4 后续维护注意事项
|
||||
- 新增查询方法时遵循现有命名规范
|
||||
- 修改现有方法时保持向后兼容性
|
||||
- 定期审查Repository方法的性能和合理性
|
||||
- 及时更新相关文档和测试用例
|
||||
|
||||
---
|
||||
|
||||
*本文档基于ContractBalanceRepository实现经验总结，结合项目实际情况分析，其他Repository实现应参考此文档规范。特别注意避免文档中提到的常见错误。*
|
||||
@@ -1,260 +1,435 @@
|
||||
# 服务器端 Service 类规则文档
|
||||
# 服务器端Service设计规范
|
||||
|
||||
## 1. 概述
|
||||
## 目录结构
|
||||
|
||||
本规则文档定义了 Contract-Manager 项目服务器端（server模块）Service 类的设计规范、实现标准和最佳实践。所有服务器端 Service 类必须严格遵循本规则，以确保代码的一致性、可维护性和性能。
|
||||
每个业务域下的service目录结构示例：
|
||||
```
|
||||
ds/
|
||||
├── company/service/
|
||||
│ ├── CompanyService.java # 主业务服务
|
||||
│ ├── CompanyContactService.java # 联系人服务
|
||||
│ ├── CompanyFileService.java # 文件管理服务
|
||||
│ ├── CompanyOldNameService.java # 曾用名服务
|
||||
│ └── ...
|
||||
├── contract/service/
|
||||
│ ├── ContractService.java # 主业务服务
|
||||
│ ├── ContractCatalogService.java # 分类目录服务
|
||||
│ └── ...
|
||||
├── customer/service/
|
||||
│ ├── CustomerService.java # 主业务服务（继承CompanyBasicService）
|
||||
│ └── ...
|
||||
├── project/service/
|
||||
│ ├── ProjectService.java # 主业务服务
|
||||
│ ├── ProjectFileService.java # 文件管理服务
|
||||
│ └── ...
|
||||
└── vendor/service/
|
||||
├── VendorService.java # 主业务服务（继承CompanyBasicService）
|
||||
└── ...
|
||||
```
|
||||
|
||||
## 2. 目录结构
|
||||
## 核心基类和接口体系
|
||||
|
||||
Service 类按业务领域组织，位于 `server/src/main/java/com/ecep/contract/ds/{业务领域}/service/` 目录下。其中 `{业务领域}` 对应具体的业务模块，如 `customer`、`contract`、`company`、`project`、`other` 等。
|
||||
### 主要基类
|
||||
- **EntityService<M, Vo, ID>**: 通用实体服务基类，提供CRUD操作的标准实现
|
||||
- **CompanyBasicService**: 专门处理公司相关业务的基础服务类，支持公司关联查询
|
||||
|
||||
**示例：**
|
||||
- 客户分类服务：`server/src/main/java/com/ecep/contract/ds/customer/service/CustomerCatalogService.java`
|
||||
- 员工服务：`server/src/main/java/com/ecep/contract/ds/other/service/EmployeeService.java`
|
||||
### 核心接口
|
||||
- **IEntityService<T>**: 实体基本操作接口
|
||||
- **QueryService<Vo>**: 查询服务接口
|
||||
- **VoableService<M, Vo>**: 实体与视图对象转换服务接口
|
||||
|
||||
## 3. 命名规范
|
||||
## 注解使用规范
|
||||
|
||||
- **类名**：采用驼峰命名法，首字母大写，以 `Service` 结尾，表示这是一个服务类。
|
||||
**示例**：`CustomerCatalogService`、`EmployeeService`
|
||||
### 类级别注解
|
||||
```java
|
||||
@Lazy // 延迟加载，避免循环依赖
|
||||
@Service // Spring服务组件
|
||||
@CacheConfig(cacheNames = "业务缓存名称") // 缓存配置
|
||||
public class CompanyService extends EntityService<Company, CompanyVo, Integer>
|
||||
implements IEntityService<Company>, QueryService<CompanyVo>, VoableService<Company, CompanyVo> {
|
||||
// 实现代码
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 接口实现
|
||||
### 方法级别注解
|
||||
```java
|
||||
// 查询方法缓存 - 使用参数作为缓存键
|
||||
@Cacheable(key = "#p0") // ID查询
|
||||
public CompanyVo findById(Integer id) {
|
||||
return repository.findById(id).map(Company::toVo).orElse(null);
|
||||
}
|
||||
|
||||
所有业务领域的 Service 类必须实现以下三个核心接口：
|
||||
@Cacheable(key = "'name-'+#p0") // 名称查询，带前缀
|
||||
public CompanyVo findByName(String name) {
|
||||
return repository.findFirstByName(name).map(Company::toVo).orElse(null);
|
||||
}
|
||||
|
||||
### 4.1 IEntityService<T>
|
||||
// 修改方法缓存清理 - 清理所有相关缓存
|
||||
@Caching(evict = {
|
||||
@CacheEvict(key = "#p0.id"),
|
||||
@CacheEvict(key = "'name-'+#p0.name"),
|
||||
@CacheEvict(key = "'code-'+#p0.code")
|
||||
})
|
||||
public Contract save(Contract contract) {
|
||||
return contractRepository.save(contract);
|
||||
}
|
||||
```
|
||||
|
||||
提供实体类的基本 CRUD 操作。泛型 `T` 表示实体类类型。
|
||||
## 依赖注入规范
|
||||
|
||||
**主要方法：**
|
||||
- `T getById(Integer id)`：根据 ID 查询实体对象
|
||||
- `Page<T> findAll(Specification<T> spec, Pageable pageable)`：根据条件和分页参数查询实体列表
|
||||
- `Specification<T> getSpecification(String searchText)`：构建搜索条件
|
||||
- `void delete(T entity)`：删除实体
|
||||
- `T save(T entity)`：保存实体
|
||||
### Repository注入
|
||||
```java
|
||||
@Lazy
|
||||
@Autowired
|
||||
private CompanyRepository repository;
|
||||
```
|
||||
|
||||
### 4.2 QueryService<Vo>
|
||||
### Service间依赖注入
|
||||
```java
|
||||
@Lazy
|
||||
@Autowired
|
||||
private ContractService contractService;
|
||||
|
||||
提供 VO 对象的查询能力。泛型 `Vo` 表示视图对象类型。
|
||||
@Lazy
|
||||
@Autowired
|
||||
private VendorService vendorService;
|
||||
|
||||
**主要方法：**
|
||||
- `Vo findById(Integer id)`：根据 ID 查询 VO 对象
|
||||
- `Page<Vo> findAll(JsonNode paramsNode, Pageable pageable)`：根据 JSON 查询参数和分页条件查询 VO 列表
|
||||
- `default long count(JsonNode paramsNode)`：根据查询参数统计数据总数
|
||||
@Lazy
|
||||
@Autowired
|
||||
private CompanyContactService companyContactService;
|
||||
```
|
||||
|
||||
### 4.3 VoableService<M, Vo>
|
||||
### 外部服务依赖注入
|
||||
```java
|
||||
@Lazy
|
||||
@Autowired
|
||||
private CloudRkService cloudRkService;
|
||||
|
||||
提供从 VO 对象更新实体对象的能力。泛型 `M` 表示实体类类型，`Vo` 表示视图对象类型。
|
||||
@Lazy
|
||||
@Autowired
|
||||
private CloudTycService cloudTycService;
|
||||
|
||||
**主要方法：**
|
||||
- `void updateByVo(M model, Vo vo)`：根据 VO 对象更新实体对象
|
||||
@Autowired(required = false) // 可选依赖
|
||||
private YongYouU8Service yongYouU8Service;
|
||||
```
|
||||
|
||||
**实现示例：**
|
||||
## 查询实现模式
|
||||
|
||||
### 标准查询实现
|
||||
```java
|
||||
@Override
|
||||
public Page<CompanyVo> findAll(JsonNode paramsNode, Pageable pageable) {
|
||||
Specification<Company> spec = null;
|
||||
|
||||
// 搜索文本查询
|
||||
if (paramsNode.has("searchText")) {
|
||||
spec = getSpecification(paramsNode.get("searchText").asText());
|
||||
}
|
||||
|
||||
// 字段等值查询
|
||||
spec = SpecificationUtils.andFieldEqualParam(spec, paramsNode, "name", "uniscid", "abbName");
|
||||
|
||||
// 分页查询并转换为VO
|
||||
return findAll(spec, pageable).map(Company::toVo);
|
||||
}
|
||||
```
|
||||
|
||||
### 复杂查询条件构建
|
||||
```java
|
||||
@Override
|
||||
public Specification<Company> getSpecification(String searchText) {
|
||||
if (!StringUtils.hasText(searchText)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return (root, query, builder) -> {
|
||||
return builder.or(
|
||||
builder.like(root.get("name"), "%" + searchText + "%"),
|
||||
builder.like(root.get("code"), "%" + searchText + "%"),
|
||||
builder.like(root.get("description"), "%" + searchText + "%"));
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### CompanyBasicService继承模式
|
||||
继承CompanyBasicService的Service（如CustomerService、VendorService）提供公司关联查询：
|
||||
|
||||
```java
|
||||
@Override
|
||||
public Specification<Vendor> getSpecification(String searchText) {
|
||||
if (!StringUtils.hasText(searchText)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// 使用公司关联查询
|
||||
Specification<Vendor> nameSpec = (root, query, builder) -> {
|
||||
Path<Company> company = root.get("company");
|
||||
return companyService.buildSearchPredicate(searchText, company, query, builder);
|
||||
};
|
||||
|
||||
// 数字ID查询
|
||||
if (MyStringUtils.isAllDigit(searchText)) {
|
||||
try {
|
||||
int id = Integer.parseInt(searchText);
|
||||
nameSpec = SpecificationUtils.or(nameSpec, (root, query, builder) -> {
|
||||
return builder.equal(root.get("id"), id);
|
||||
});
|
||||
} catch (Exception ignored) {
|
||||
}
|
||||
}
|
||||
|
||||
// 实体搜索
|
||||
List<VendorEntity> searched = vendorEntityService.search(searchText);
|
||||
if (!searched.isEmpty()) {
|
||||
nameSpec = SpecificationUtils.or(nameSpec, (root, query, builder) -> {
|
||||
return builder.in(root.get("id")).value(searched.stream()
|
||||
.map(VendorEntity::getVendor)
|
||||
.filter(Objects::nonNull)
|
||||
.map(Vendor::getId)
|
||||
.collect(Collectors.toSet()));
|
||||
});
|
||||
}
|
||||
|
||||
return nameSpec;
|
||||
}
|
||||
```
|
||||
|
||||
## 业务逻辑实现模式
|
||||
|
||||
### 1. 主业务Service（继承EntityService）
|
||||
```java
|
||||
@Lazy
|
||||
@Service
|
||||
@CacheConfig(cacheNames = "customer-catalog")
|
||||
public class CustomerCatalogService implements IEntityService<CustomerCatalog>, QueryService<CustomerCatalogVo>,
|
||||
VoableService<CustomerCatalog, CustomerCatalogVo> {
|
||||
// 实现方法...
|
||||
@CacheConfig(cacheNames = "contract")
|
||||
public class ContractService extends EntityService<Contract, ContractVo, Integer>
|
||||
implements IEntityService<Contract>, QueryService<ContractVo>, VoableService<Contract, ContractVo> {
|
||||
|
||||
@Override
|
||||
protected ContractRepository getRepository() {
|
||||
return contractRepository;
|
||||
}
|
||||
|
||||
@Cacheable(key = "#p0")
|
||||
public ContractVo findById(Integer id) {
|
||||
return getRepository().findById(id).map(Contract::toVo).orElse(null);
|
||||
}
|
||||
|
||||
// 业务特定方法
|
||||
public List<Contract> findAllByCompany(Company company) {
|
||||
return contractRepository.findAllByCompanyId(company.getId());
|
||||
}
|
||||
|
||||
public File getContractCatalogPath(ContractCatalogVo catalog, ContractVo contract) {
|
||||
// 文件路径处理逻辑
|
||||
String parent = catalog.getParent();
|
||||
File dir = getBasePath();
|
||||
// ... 路径构建逻辑
|
||||
return dir;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 5. 注解规范
|
||||
|
||||
Service 类必须使用以下注解：
|
||||
|
||||
### 5.1 类级别注解
|
||||
|
||||
- `@Service`：标记这是一个 Spring 服务类，使其能够被自动扫描和管理
|
||||
- `@Lazy`：延迟加载服务类，提高应用启动性能
|
||||
- `@CacheConfig(cacheNames = "缓存名称")`：配置缓存名称，缓存名称通常与业务领域相关
|
||||
**示例**：`@CacheConfig(cacheNames = "customer-catalog")`、`@CacheConfig(cacheNames = "employee")`
|
||||
|
||||
### 5.2 方法级别注解
|
||||
|
||||
#### 5.2.1 查询方法注解
|
||||
|
||||
- `@Cacheable(key = "缓存键")`：将查询结果缓存起来，下次相同查询可以直接从缓存获取
|
||||
**示例**：`@Cacheable(key = "#p0")`（使用方法第一个参数作为缓存键）、`@Cacheable(key = "'code-'+#p0")`（使用前缀+参数值作为缓存键）
|
||||
|
||||
#### 5.2.2 数据修改方法注解
|
||||
|
||||
- `@Caching(evict = { ... })`：在保存或删除操作时清除相关缓存
|
||||
**示例**：
|
||||
```java
|
||||
@Caching(evict = {
|
||||
@CacheEvict(key = "#p0.id"),
|
||||
@CacheEvict(key = "'code-'+#p0.code"),
|
||||
@CacheEvict(key = "'name-'+#p0.name"),
|
||||
@CacheEvict(key = "'all'")
|
||||
})
|
||||
```
|
||||
|
||||
- `@Transactional`：标记方法需要在事务中执行，确保数据一致性
|
||||
**示例**：用于包含多个数据操作的复杂业务方法
|
||||
|
||||
## 6. 缓存策略
|
||||
|
||||
Service 类必须遵循以下缓存策略：
|
||||
|
||||
### 6.1 查询缓存
|
||||
|
||||
- 所有 `findById`、`findByCode`、`findByName` 等单条查询方法都应使用 `@Cacheable` 注解缓存结果
|
||||
- 缓存键设计应具有唯一性和可读性，通常包含参数值和适当的前缀
|
||||
- 列表查询（如 `findAll`）可以考虑使用 `@Cacheable`，但需谨慎管理缓存失效
|
||||
|
||||
### 6.2 缓存清理
|
||||
|
||||
- 所有 `save`、`delete` 等修改数据的方法都应使用 `@Caching` 和 `@CacheEvict` 注解清理相关缓存
|
||||
- 清理缓存时应考虑所有可能影响的查询，确保缓存数据的一致性
|
||||
|
||||
## 7. 方法实现规范
|
||||
|
||||
### 7.1 IEntityService 方法实现
|
||||
|
||||
- `getById`：直接调用 Repository 的 `findById` 方法，返回实体对象
|
||||
```java
|
||||
@Override
|
||||
public CustomerCatalog getById(Integer id) {
|
||||
return repository.findById(id).orElse(null);
|
||||
}
|
||||
```
|
||||
|
||||
- `findAll(Specification<T>, Pageable)`：直接调用 Repository 的 `findAll` 方法，返回实体分页对象
|
||||
```java
|
||||
@Override
|
||||
public Page<CustomerCatalog> findAll(Specification<CustomerCatalog> spec, Pageable pageable) {
|
||||
return repository.findAll(spec, pageable);
|
||||
}
|
||||
```
|
||||
|
||||
- `save/delete`：调用 Repository 的相应方法，并添加缓存清理注解
|
||||
```java
|
||||
@Caching(evict = { ... })
|
||||
@Override
|
||||
public CustomerCatalog save(CustomerCatalog catalog) {
|
||||
return repository.save(catalog);
|
||||
}
|
||||
```
|
||||
|
||||
### 7.2 QueryService 方法实现
|
||||
|
||||
- `findById`：调用 Repository 的 `findById` 方法，然后调用实体类的 `toVo` 方法转换为 VO 对象
|
||||
```java
|
||||
@Cacheable(key = "#p0")
|
||||
@Override
|
||||
public CustomerCatalogVo findById(Integer id) {
|
||||
return repository.findById(id).map(CustomerCatalog::toVo).orElse(null);
|
||||
}
|
||||
```
|
||||
|
||||
- `findAll(JsonNode, Pageable)`：构建 Specification，调用 IEntityService 的 `findAll` 方法，然后使用 Stream API 的 `map` 方法将结果转换为 VO 对象
|
||||
```java
|
||||
@Override
|
||||
public Page<CustomerCatalogVo> findAll(JsonNode paramsNode, Pageable pageable) {
|
||||
Specification<CustomerCatalog> spec = null;
|
||||
if (paramsNode.has(ServiceConstant.KEY_SEARCH_TEXT)) {
|
||||
spec = getSpecification(paramsNode.get(ServiceConstant.KEY_SEARCH_TEXT).asText());
|
||||
}
|
||||
|
||||
// 字段等值查询
|
||||
spec = SpecificationUtils.andFieldEqualParam(spec, paramsNode, "code", "name", "description");
|
||||
return repository.findAll(spec, pageable).map(CustomerCatalog::toVo);
|
||||
}
|
||||
```
|
||||
|
||||
### 7.3 VoableService 方法实现
|
||||
|
||||
- `updateByVo`：将 VO 对象的属性逐个复制到实体对象，实现 VO 到实体的转换
|
||||
```java
|
||||
@Override
|
||||
public void updateByVo(CustomerCatalog model, CustomerCatalogVo vo) {
|
||||
// 参数校验
|
||||
if (model == null) {
|
||||
throw new ServiceException("实体对象不能为空");
|
||||
}
|
||||
if (vo == null) {
|
||||
throw new ServiceException("VO对象不能为空");
|
||||
}
|
||||
|
||||
// 映射基本属性
|
||||
model.setCode(vo.getCode());
|
||||
model.setName(vo.getName());
|
||||
model.setDescription(vo.getDescription());
|
||||
}
|
||||
```
|
||||
|
||||
## 8. 依赖注入规范
|
||||
|
||||
- Service 类应使用 `@Autowired` 注解注入所需的 Repository 和其他依赖
|
||||
- 为了避免循环依赖，所有注入的依赖都应使用 `@Lazy` 注解标记为延迟加载
|
||||
```java
|
||||
@Lazy
|
||||
@Autowired
|
||||
private CustomerCatalogRepository repository;
|
||||
```
|
||||
|
||||
## 9. 查询条件构建
|
||||
|
||||
- 使用 `SpecificationUtils` 工具类辅助构建查询条件
|
||||
- 实现 `getSpecification(String searchText)` 方法，提供基于搜索文本的模糊查询能力
|
||||
```java
|
||||
@Override
|
||||
public Specification<CustomerCatalog> getSpecification(String searchText) {
|
||||
if (!StringUtils.hasText(searchText)) {
|
||||
return null;
|
||||
}
|
||||
String likeText = "%" + searchText + "%";
|
||||
return (root, query, builder) -> {
|
||||
return builder.or(
|
||||
builder.like(root.get("code"), likeText),
|
||||
builder.like(root.get("name"), likeText),
|
||||
builder.like(root.get("description"), likeText));
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## 10. 异常处理
|
||||
|
||||
- Service 类应适当处理异常，特别是对输入参数的校验
|
||||
- 对于业务逻辑异常，应抛出 `ServiceException`
|
||||
```java
|
||||
if (model == null) {
|
||||
throw new ServiceException("实体对象不能为空");
|
||||
}
|
||||
```
|
||||
|
||||
## 11. 最佳实践
|
||||
|
||||
1. **VO优先原则**：QueryService 接口应使用 VO 类型作为泛型参数，返回 VO 对象而不是实体对象
|
||||
2. **缓存粒度**：缓存键应设计得足够细粒度，避免缓存过大或频繁失效
|
||||
3. **事务管理**：包含多个数据操作的方法应使用 `@Transactional` 注解确保事务一致性
|
||||
4. **延迟加载**：所有依赖都应使用 `@Lazy` 注解，避免循环依赖问题
|
||||
5. **参数校验**：方法开始时应进行参数校验，确保输入数据的合法性
|
||||
6. **文档注释**：关键方法应有清晰的 JavaDoc 注释，说明其功能、参数和返回值
|
||||
7. **代码复用**：尽量使用 SpecificationUtils 等工具类辅助构建查询条件，提高代码复用性
|
||||
|
||||
## 12. 不符合规范的Service类示例
|
||||
|
||||
以下是不符合规范的Service类实现，应避免：
|
||||
|
||||
### 2. 继承CompanyBasicService的Service
|
||||
```java
|
||||
// 错误：QueryService泛型参数使用实体类型而非VO类型
|
||||
@Lazy
|
||||
@Service
|
||||
@CacheConfig(cacheNames = "company")
|
||||
public class CompanyService extends EntityService<Company, Integer>
|
||||
implements IEntityService<Company>, QueryService<Company>, VoableService<Company, CompanyVo> {
|
||||
// 实现方法...
|
||||
}
|
||||
|
||||
// 错误：未使用缓存注解
|
||||
@Service
|
||||
public class ExampleService implements IEntityService<Example>, QueryService<ExampleVo>,
|
||||
VoableService<Example, ExampleVo> {
|
||||
// 未使用@Cacheable、@CacheEvict等缓存注解
|
||||
@CacheConfig(cacheNames = "company-customer")
|
||||
public class CustomerService extends CompanyBasicService
|
||||
implements IEntityService<CompanyCustomer>, QueryService<CustomerVo>,
|
||||
VoableService<CompanyCustomer, CustomerVo> {
|
||||
|
||||
// 提供公司关联查询
|
||||
public CompanyCustomer findByCompany(Company company) {
|
||||
return repository.findByCompany(company).orElse(null);
|
||||
}
|
||||
|
||||
public CustomerVo findByCompany(CompanyVo company) {
|
||||
return repository.findByCompanyId(company.getId()).map(CompanyCustomer::toVo).orElse(null);
|
||||
}
|
||||
|
||||
// 文件重建业务逻辑
|
||||
public boolean reBuildingFiles(CompanyCustomer companyCustomer, MessageHolder holder) {
|
||||
List<CompanyCustomerFile> dbFiles = companyCustomerFileService.findAllByCustomer(companyCustomer);
|
||||
Map<String, CompanyCustomerFile> map = new HashMap<>();
|
||||
|
||||
boolean modified = fetchDbFiles(dbFiles, map, holder::info);
|
||||
|
||||
List<File> needMoveToCompanyPath = new ArrayList<>();
|
||||
fetchFiles(companyCustomer.getPath(), needMoveToCompanyPath, retrieveFiles, map, holder::info);
|
||||
|
||||
moveFileToCompany(companyCustomer.getCompany(), needMoveToCompanyPath);
|
||||
|
||||
holder.info("导入 " + retrieveFiles.size() + " 个文件");
|
||||
|
||||
if (!retrieveFiles.isEmpty()) {
|
||||
retrieveFiles.forEach(v -> v.setCustomer(companyCustomer));
|
||||
companyCustomerFileService.saveAll(retrieveFiles);
|
||||
modified = true;
|
||||
}
|
||||
|
||||
return modified;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 13. 总结
|
||||
## 文件管理Service实现模式
|
||||
|
||||
本规则文档定义了服务器端 Service 类的完整规范，包括目录结构、命名规范、接口实现、注解规范、缓存策略、方法实现、依赖注入等方面。所有服务器端开发人员都必须严格遵循这些规则，以确保代码的一致性、可维护性和性能。
|
||||
### 文件路径管理
|
||||
```java
|
||||
public File getBasePath() {
|
||||
return new File(confService.getString(ContractConstant.KEY_BASE_PATH));
|
||||
}
|
||||
|
||||
public File getContractCatalogPath(ContractCatalogVo catalog, ContractVo contract) {
|
||||
String parent = catalog.getParent();
|
||||
File dir = getBasePath();
|
||||
|
||||
if (StringUtils.hasText(parent)) {
|
||||
dir = new File(dir, parent);
|
||||
if (!dir.exists() && !dir.mkdir()) {
|
||||
System.out.println("unable make directory = " + dir.getAbsolutePath());
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
dir = new File(dir, catalog.getPath());
|
||||
if (!dir.exists() && !dir.mkdir()) {
|
||||
System.out.println("unable make directory = " + dir.getAbsolutePath());
|
||||
return null;
|
||||
}
|
||||
|
||||
if (catalog.isUseYear()) {
|
||||
String code = contract.getCode();
|
||||
String catalogCode = catalog.getCode();
|
||||
int length = catalogCode.length();
|
||||
String yearCode = code.substring(length, length + 2);
|
||||
dir = new File(dir, "20" + yearCode);
|
||||
if (!dir.exists() && !dir.mkdir()) {
|
||||
System.out.println("unable make directory = " + dir.getAbsolutePath());
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
return dir;
|
||||
}
|
||||
```
|
||||
|
||||
## 缓存策略最佳实践
|
||||
|
||||
### 缓存键设计原则
|
||||
- **ID查询**: `@Cacheable(key = "#p0")`
|
||||
- **字符串查询**: `@Cacheable(key = "'name-'+#p0")`
|
||||
- **复合键查询**: `@Cacheable(key = "'code-year-'+#p0+'-'+#p1")`
|
||||
|
||||
### 缓存清理策略
|
||||
```java
|
||||
@Caching(evict = {
|
||||
@CacheEvict(key = "#p0.id"), // 主键缓存
|
||||
@CacheEvict(key = "'name-'+#p0.name"), // 名称缓存
|
||||
@CacheEvict(key = "'code-'+#p0.code"), // 编码缓存
|
||||
@CacheEvict(key = "'guid-'+#p0.guid") // GUID缓存
|
||||
})
|
||||
public Contract save(Contract contract) {
|
||||
return contractRepository.save(contract);
|
||||
}
|
||||
```
|
||||
|
||||
## 性能优化建议
|
||||
|
||||
### 1. 延迟加载
|
||||
所有Service依赖都应使用@Lazy注解，避免循环依赖和启动时的性能问题。
|
||||
|
||||
### 2. 缓存粒度
|
||||
- 单条查询使用细粒度缓存键
|
||||
- 避免缓存大量数据的列表查询
|
||||
- 合理设置缓存过期策略
|
||||
|
||||
### 3. 分页查询
|
||||
使用Page<T>进行分页查询，避免一次性加载大量数据：
|
||||
```java
|
||||
public Page<Project> findAll(Specification<Project> spec, Pageable pageable) {
|
||||
return projectRepository.findAll(spec, pageable);
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 批量操作
|
||||
对于大量数据操作，考虑使用批量处理：
|
||||
```java
|
||||
public void saveAll(List<CompanyCustomerFile> files) {
|
||||
companyCustomerFileService.saveAll(retrieveFiles);
|
||||
}
|
||||
```
|
||||
|
||||
## 异常处理规范
|
||||
|
||||
### 参数校验
|
||||
```java
|
||||
public void updateByVo(CustomerCatalog model, CustomerCatalogVo vo) {
|
||||
if (model == null) {
|
||||
throw new ServiceException("实体对象不能为空");
|
||||
}
|
||||
if (vo == null) {
|
||||
throw new ServiceException("VO对象不能为空");
|
||||
}
|
||||
// ... 业务逻辑
|
||||
}
|
||||
```
|
||||
|
||||
### 业务异常处理
|
||||
```java
|
||||
public Company findAndRemoveDuplicateCompanyByUniscid(String uniscid) {
|
||||
List<Company> companies = repository.findAllByUniscid(uniscid);
|
||||
if (companies.isEmpty()) {
|
||||
return null;
|
||||
}
|
||||
if (companies.size() == 1) {
|
||||
return companies.getFirst();
|
||||
} else {
|
||||
List<Company> result = removeDuplicatesByUniscid(companies);
|
||||
if (!result.isEmpty()) {
|
||||
return result.getFirst();
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
```
|
||||
|
||||
## 工具类使用规范
|
||||
|
||||
### SpecificationUtils使用
|
||||
```java
|
||||
// 字段等值查询
|
||||
spec = SpecificationUtils.andFieldEqualParam(spec, paramsNode, "name", "code", "status");
|
||||
|
||||
// 参数关联查询
|
||||
spec = SpecificationUtils.andParam(spec, paramsNode, "company", "catalog", "type");
|
||||
|
||||
// 搜索文本组合
|
||||
spec = SpecificationUtils.andWith(searchText, this::buildSearchSpecification);
|
||||
```
|
||||
|
||||
### 字符串工具使用CompanyBasicService
|
||||
```java
|
||||
// 全数字判断
|
||||
if (MyStringUtils.isAllDigit(searchText)) {
|
||||
// 数字处理逻辑
|
||||
}
|
||||
|
||||
// 空值检查
|
||||
if (!StringUtils.hasText(searchText)) {
|
||||
return null;
|
||||
}
|
||||
```
|
||||
|
||||
## 最佳实践总结
|
||||
|
||||
1. **接口实现完整性**: 所有Service应实现三个核心接口，确保功能一致性
|
||||
2. **缓存策略一致性**: 遵循统一的缓存键设计和清理策略
|
||||
3. **依赖注入规范**: 使用@Lazy避免循环依赖，清晰管理Service间依赖关系
|
||||
4. **查询性能优化**: 合理使用SpecificationUtils构建查询条件，支持分页查询
|
||||
5. **异常处理统一**: 统一的异常处理方式，提高代码健壮性
|
||||
6. **代码复用**: 继承合适的基类，复用通用逻辑
|
||||
7. **文档注释**: 关键方法和复杂业务逻辑应有清晰的JavaDoc注释
|
||||
8. **性能监控**: 关注缓存命中率，适时调整缓存策略
|
||||
|
||||
这套规范确保了Service层的代码质量、性能和可维护性，为整个系统的稳定运行提供了坚实基础。
|
||||
@@ -118,7 +118,15 @@ WebSocketServerTaskManager类在启动时会读取`tasker_mapper.json`文件，
|
||||
@Override
|
||||
public void init(JsonNode argsNode) {
|
||||
// 解析参数或初始化任务状态
|
||||
// ContractRepairAllTasker 不需要参数，所以此方法为空实现
|
||||
// 如果 Client 没有传递参数，就不做处理
|
||||
// do nothing
|
||||
|
||||
// 如果有参数，正确做法：检查参数有效性并安全解析
|
||||
if (argsNode != null && argsNode.size() > 0) {
|
||||
ContractService contractService = getCachedBean(ContractService.class);
|
||||
int contractId = argsNode.get(0).asInt();
|
||||
this.contract = contractService.findById(contractId);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user