Cursor Rule模板

Cursor Rule模板

Cursor Rule模板

发表于
作者 kevin
42 分钟 阅读
Cursor Rule模板

核心技术栈

  • Java版本: Java 17
  • 构建工具: Gradle
  • 框架: Spring Boot 3.x + Spring Cloud
  • 微服务: 微服务项目
  • 数据库: JPA
  • 消息队列: 支持 MQ 集成
  • 服务发现: Nacos
  • API文档: Swagger/Knife4j
  • 日志: Log4j2 + 操作日志记录

项目模块结构

  • xxx-api: API接口定义模块，包含 Feign 客户端接口
  • xxx-core: 核心业务逻辑实现模块
  • xxx-server: 服务启动和配置模块

代码风格和结构规范

代码风格

  • 编写干净、高效且文档完善的 Java 代码，使用中文注释，禁止行尾注释
  • 使用 Spring Boot 最佳实践
  • 实现 RESTful API 设计模式
  • 使用描述性的方法和变量名称，遵循 camelCase 约定
  • 严格按照项目模块结构组织代码：controllers、services、repositories、models、configurations

命名约定

类型 规范 示例
类名 PascalCase StoreController、OrderService
方法和变量名 camelCase findUserById、isOrderValid
常量 ALL_CAPS MAX_RETRY_ATTEMPTS
包名 com.xx.xxx com.tt.store

Spring Boot规范

注解使用规范

  • 正确使用 Spring Boot 注解（@SpringBootApplication、@RestController、@Service、@Repository）
  • 实现正确的异常处理（@ControllerAdvice、@ExceptionHandler）
  • 使用 @Validated 进行参数验证

依赖注入规范

  • 优先使用构造函数注入，提高可测试性
  • 使用 @Autowired 注解进行依赖注入
  • 利用 Spring 的 IoC 容器管理 bean 生命周期

配置管理

  • 使用 application.yml 进行配置管理
  • 实现环境特定配置（dev、uat、prod）
  • 使用 @ConfigurationProperties 进行类型安全的配置属性

API 设计和 RPC 服务规范

REST API 设计

  • 遵循 RESTful 设计原则，正确使用 HTTP 方法和状态码
  • 使用 @RestController 和 @RequestMapping 注解
  • 实现统一的 API 响应格式（ApiResult<T>）
  • 使用 Swagger/Knife4j 进行 API 文档生成

RPC 服务实现

  • 在 store-api 模块中定义 Feign 客户端接口
  • 在 store-core 模块中实现 RPC 服务（@RestController）
  • 使用 @FeignClient 注解进行服务间调用
  • 实现统一的 RPC 接口规范

参数验证和错误处理

  • 使用 Bean Validation 进行参数验证（@Valid、@NotBlank 等）
  • 实现统一的异常处理机制
  • 提供有意义的错误信息和错误码

数据库和持久化规范

JPA 使用规范

  • 使用 Spring Data JPA 进行数据库操作
  • 实现正确的实体关系和级联配置
  • 使用 @Repository 注解标记数据访问层
  • 实现数据库迁移和版本管理

查询优化

  • 添加合适的数据库索引
  • 优化 SQL 查询语句，避免 N+1 查询问题
  • 使用批量操作提高性能
  • 实现查询缓存策略

业务逻辑和 Service 层规范

Service 层设计

  • 在 service 包中定义业务接口
  • 在 service.impl 包中实现业务逻辑
  • 使用 @Service 注解标记服务类
  • 实现事务管理和异常处理

业务对象和 DTO 规范

  • 使用 DTO 进行数据传输（在 rpc.dto 包中定义）
  • 使用 VO 进行视图对象定义（在 model.vo 包中定义）
  • 使用 Convert 工具类进行对象转换

用户上下文和权限规范

获取当前登录用户信息 

1

Long userId = SecurityContextUtil.currentUserId();
1
2
3
4
5

if (null == SecurityContextUtil.currentUser()) {
    throw new BusinessException("用户未登录");
}
Long userId = SecurityContextUtil.currentUser().getUserId();
String userName = SecurityContextUtil.currentUser().getUser().getLastName();

注意: 在需要验证用户登录状态时，务必先检查用户是否为空

日志记录标准格式：

1

String remark = StrUtil.format("{}提交了记录", SecurityContextUtil.currentUser().getUser().getLastName());

数据权限控制

获取当前用户及其下属用户 ID 列表：

1
2
3
4
5
6
7
8

SelectSubordinateUserReqDTO userReqDTO = new SelectSubordinateUserReqDTO();
userReqDTO.setUserId(SecurityContextUtil.currentUserId());
userReqDTO.setCascade(Boolean.TRUE);
Set<Long> subUserIds = userProviderRpcService.selectSubordinateUserIdByUserIdV2(userReqDTO);

Set<Long> authUserIds = Sets.newHashSet();
authUserIds.addAll(subUserIds);
authUserIds.add(SecurityContextUtil.currentUserId()); // 确保包含当前用户

门店数据权限获取：

1
2
3
4
5
6

ApiResult<Set<String>> setApiResult = StoreProvider.queryStoreCodeByUserId(SecurityContextUtil.currentUserId());
if (!setApiResult.isSuccess() || setApiResult.getData() == null){
    // 拥有所有门店权限
    return null;
}
return setApiResult.getData().stream().collect(Collectors.toList());

用户信息缓存

  • 使用 Redis 缓存用户信息，缓存键格式：CacheConstant.QUERY_BY_USER_ID + userId
  • 缓存用户组织信息和权限信息，避免重复查询
  • 在获取用户信息时优先从缓存读取
1
2
3
4
5

String cacheKey = CacheConstant.QUERY_BY_USER_ID + userId;
String userInfoStr = redisTemplate.opsForValue().get(cacheKey);
if (StringUtils.isNotBlank(userInfoStr)) {
    // 从缓存获取用户信息
}

日志和监控规范

日志记录

  • 使用 Log4j2 进行日志记录
  • 实现正确的日志级别（ERROR、WARN、INFO、DEBUG）
  • 使用 @Log4j2 注解进行日志记录
  • 集成操作日志记录功能

项目架构和模块规范

项目架构一致性

  • 项目组织: 采用统一的三层架构模式
  • 模块命名: 项目名格式为 xxx 或 xxx，模块名格式为 xxx-api、xxx-core、xxx-server
  • 包结构: 统一使用 com.xx.xxx 包名规范
  • 版本管理: 基于 Git 分支的版本策略，release 分支使用 RELEASE 后缀，其他分支使用 SNAPSHOT 后缀

模块职责划分

模块 职责
xxx-api 对外 API 接口定义、RPC 服务接口声明、数据传输对象（DTO、VO）定义、常量和枚举类、Feign 客户端接口
xxx-core 核心业务逻辑实现、RPC 服务接口实现、数据库实体和 Repository、业务服务层实现、配置类和工具类
xxx-server 应用启动类、配置文件（bootstrap.yaml 等）、环境特定配置、国际化资源文件

包结构标准化

基于对 5 个项目的分析，所有项目都应遵循以下包结构：

API 模块包结构（com.xx.xxx） 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

com.xx.xxx/
├── Application.java           # 应用常量类
├── constant/                   # 常量和枚举
│   ├── *Enum.java             # 枚举类（以 Enum 结尾）
│   └── *Constant.java         # 常量类（以 Constant 结尾）
└── rpc/                       # RPC 服务接口
    ├── *RpcService.java       # RPC 服务接口（以 RpcService 结尾）
    ├── dto/                   # 请求参数 DTO
    │   ├── *QueryDTO.java     # 查询参数（以 QueryDTO 结尾）
    │   ├── *SaveDTO.java      # 保存参数（以 SaveDTO 结尾）
    │   └── *.java             # 其他 DTO（以 DTO 结尾）
    └── vo/                    # 返回结果 VO
        ├── *VO.java           # 返回对象（以 VO 结尾）
        └── *ListVO.java       # 列表返回对象（以 ListVO 结尾）

Core 模块包结构（com.xx.xxx） 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

com.xx.xxx/
├── annotation/                # 自定义注解
├── aspect/                    # 切面类（以 Aspect 结尾）
├── config/                   # 配置类
│   ├── *Config.java          # 配置类（以 Config 结尾）
│   └── *Properties.java      # 属性配置类（以 Properties 结尾）
├── constant/                  # 常量类（以 Constant 结尾）
├── controller/                # 控制器层
│   ├── api/                  # 对外 API 控制器
│   ├── app/                  # 移动端控制器
│   ├── mng/                  # 管理端控制器
│   └── common/               # 通用控制器
├── convert/                   # 对象转换器（以 Convert/Converter 结尾）
├── enums/                     # 枚举类（以 Enum 结尾）
├── model/                     # 数据模型
│   ├── entity/               # 实体类（以 DO 结尾）
│   ├── dto/                  # 数据传输对象（以 DTO 结尾）
│   ├── vo/                   # 视图对象（以 VO 结尾）
│   └── common/               # 通用模型类
├── provider/                  # 服务提供者
│   ├── export/              # 导出服务提供者
│   ├── imports/             # 导入服务提供者
│   ├── mq/                  # 消息队列相关服务
│   ├── rmi/                 # 远程调用封装
│   └── task/                # 任务调度相关
├── rpc/                      # RPC 服务实现（以 RpcServiceImpl 结尾）
├── service/                   # 业务服务层
│   ├── *.java               # 服务接口（以 Service 结尾）
│   ├── impl/                # 服务实现（以 ServiceImpl 结尾）
│   ├── repo/                # 数据访问层（以 RepoProc 结尾）
│   └── manager/             # 管理层服务
├── utils/                     # 工具类（以 Util/Utils 结尾）
└── validater/                 # 验证器（以 Validater 结尾）

项目配置文件标准化

  • 构建配置: build.gradle、settings.gradle、gradle.properties
  • 应用配置: bootstrap.yaml、application-*.yaml

构建和部署规范

依赖管理规范

  • 统一排除不需要的依赖模块
  • 使用 dependencyManagement 统一管理依赖版本
  • 配置正确的 Maven 仓库和认证信息

安全和性能规范

安全规范

  • 实现 Spring Security 进行身份验证和授权
  • 使用正确的密码编码（BCrypt）
  • 实现 CORS 配置

性能优化

  • 实现缓存策略（Spring Cache）
  • 使用异步处理（@Async）
  • 优化数据库查询和索引
  • 实现连接池配置

微服务架构规范

服务间通信

  • 使用 Feign 进行服务间调用
  • 实现服务发现和负载均衡
  • 配置正确的超时和重试策略
  • 实现熔断和降级机制

配置管理

  • 使用 Nacos 进行配置管理
  • 实现配置的动态更新
  • 配置正确的环境隔离
  • 实现配置的版本管理

多模块协作和接口设计规范

模块间通信规范

基于对 5 个项目的分析，模块间通信应遵循以下规范：

RPC 服务接口设计

  • 接口定义: 在 xxx-api 模块中定义 RPC 服务接口
  • 接口命名: 接口名以 RpcService 结尾（如：StatisticsRpcService、TravelRpcService）
  • 接口实现: 在 xxx-core 模块中实现，实现类以 RpcServiceImpl 结尾
  • 统一返回格式: 使用 ApiResult<T> 或 UnifiedReturnRpcVO 等统一返回格式
  • 异常处理: 实现统一的异常处理和错误码规范

数据传输对象（DTO/VO）规范 

1
2
3
4
5
6
7
8
9

// DTO 命名规范示例
public class UserQueryDTO { }           // 查询参数
public class UserSaveDTO { }            // 保存参数
public class UserUpdateDTO { }          // 更新参数

// VO 命名规范示例
public class UserInfoVO { }              // 基础返回对象
public class UserListVO { }             // 列表返回对象
public class UserDetailVO { }           // 详情返回对象

服务间调用规范

  • 使用 Feign 客户端进行服务间调用
  • 配置统一的超时和重试策略
  • 实现熔断和降级机制
  • 使用统一的请求头和认证机制

业务对象转换规范

所有项目都使用 Convert/Converter 类进行对象转换：

转换器命名规范 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

public class UserConverter {
    // DO -> VO 转换
    public static UserInfoVO toVO(UserDO userDO) { }

    // DTO -> DO 转换
    public static UserDO toDO(UserSaveDTO saveDTO) { }

    // 批量转换
    public static List<UserInfoVO> toVOList(List<UserDO> userDOList) { }
}

转换器最佳实践

  • 每个业务模块创建对应的转换器类
  • 转换器方法使用 static 修饰，提高性能
  • 处理 null 值，避免空指针异常
  • 复杂转换逻辑抽取为私有方法

枚举和常量管理规范

枚举类设计规范 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

public enum TaskStatusEnum {
    PENDING(0, "待处理"),
    IN_PROGRESS(1, "处理中"),
    COMPLETED(2, "已完成"),
    CANCELLED(3, "已取消");

    private final Integer code;
    private final String desc;

    TaskStatusEnum(Integer code, String desc) {
        this.code = code;
        this.desc = desc;
    }

    // getter 方法和工具方法
    public static TaskStatusEnum getByCode(Integer code) { }
}

常量类设计规范 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

public class BusinessObjectConstant {
    /** 用户相关业务对象 */
    public static final String USER_OBJECT = "user";

    /** 订单相关业务对象 */
    public static final String ORDER_OBJECT = "order";

    // 私有构造函数，防止实例化
    private BusinessObjectConstant() { }
}

异常处理和错误管理规范

统一异常处理架构

所有项目都应实现统一的异常处理机制：

自定义业务异常 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

public class BusinessException extends RuntimeException {
    private String errorCode;
    private String errorMessage;

    public BusinessException(String errorMessage) {
        super(errorMessage);
        this.errorMessage = errorMessage;
    }

    public BusinessException(String errorCode, String errorMessage) {
        super(errorMessage);
        this.errorCode = errorCode;
        this.errorMessage = errorMessage;
    }
}

全局异常处理器 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BusinessException.class)
    public ApiResult<Void> handleBusinessException(BusinessException e) {
        return ApiResult.fail(e.getErrorCode(), e.getErrorMessage());
    }

    @ExceptionHandler(Exception.class)
    public ApiResult<Void> handleException(Exception e) {
        log.error("系统异常", e);
        return ApiResult.fail("系统异常，请联系管理员");
    }
}

错误码规范

  • 使用统一的错误码格式：模块代码 + 错误类型 + 序号（如：USER001、ORDER002）
  • 错误信息使用中文，便于用户理解
  • 重要错误记录详细日志，便于排查问题

代码审查和质量保证

代码质量标准

  • 遵循 SOLID 原则和设计模式
  • 保持高内聚和低耦合的模块设计
  • 实现代码复用和模块化架构
  • 使用静态代码分析工具进行代码检查
  • 单元测试覆盖率不低于 70%

文档和注释规范

  • 编写完整的 API 文档（Swagger/Knife4j）
  • 提供清晰的代码注释和说明
  • 维护项目架构文档和设计文档
  • 记录重要的设计决策和变更历史
  • 所有公共类和方法都要有标准的 JavaDoc 注释

类注释标准模板 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

/**
 * 用户服务接口
 * <p>
 * 提供用户相关的业务功能，包括用户查询、创建、更新等操作
 * </p>
 *
 * @author 开发者姓名
 * @since 2025-01-01
 * @version 1.0.0
 */
public class UserService {

    /**
     * 根据用户ID查询用户信息
     *
     * @param userId 用户ID，不能为空
     * @return 用户信息，如果用户不存在则返回null
     * @throws BusinessException 当用户ID格式不正确时抛出
     */
    public UserInfoVO findUserById(Long userId) {
        // 方法实现
    }
}

数据库操作规范

Repository 层设计

基于项目中的 repo 包结构，数据库操作应遵循：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

@Repository
public class UserRepoProc {

    @Autowired
    private UserRepository userRepository;

    /**
     * 根据用户ID查询用户信息
     */
    public UserDO findUserById(Long userId) {
        return userRepository.findById(userId).orElse(null);
    }

    /**
     * 批量查询用户信息
     */
    public List<UserDO> findUsersByIds(List<Long> userIds) {
        return userRepository.findAllById(userIds);
    }

    /**
     * 分页查询用户列表
     */
    public Page<UserDO> findUsersPage(UserQueryDTO queryDTO, Pageable pageable) {
        // 构建查询条件
        Specification<UserDO> spec = buildUserSpec(queryDTO);
        return userRepository.findAll(spec, pageable);
    }
}

数据库最佳实践

  • 使用 JPA Specification 进行动态查询
  • 合理使用索引，避免全表扫描
  • 批量操作使用 batch 操作提高性能
  • 复杂查询考虑使用原生 SQL
  • 开启 SQL 日志，便于性能调优

消息队列集成规范

MQ 监听器规范

基于项目中的 mq.listener 包结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

@Component
@Slf4j
public class UserEventListener {

    @RabbitListener(queues = "user.created.queue")
    public void handleUserCreated(UserCreatedEvent event) {
        try {
            log.info("接收到用户创建事件: {}", event);
            // 处理业务逻辑
            processUserCreated(event);
            log.info("用户创建事件处理完成: {}", event.getUserId());
        } catch (Exception e) {
            log.error("处理用户创建事件失败", e);
            // 根据业务需要决定是否重新抛出异常
        }
    }
}

MQ 发送规范 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

@Component
public class UserEventPublisher {

    @Autowired
    private RabbitTemplate rabbitTemplate;

    public void publishUserCreated(Long userId) {
        UserCreatedEvent event = UserCreatedEvent.builder()
            .userId(userId)
            .timestamp(LocalDateTime.now())
            .build();
        rabbitTemplate.convertAndSend("user.exchange", "user.created", event);
        log.info("发布用户创建事件: {}", event);
    }
}

性能优化和监控规范

缓存策略

基于项目中的缓存使用模式：

Redis 缓存规范 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

@Service
public class UserCacheService {

    @Autowired
    private RedisTemplate<String, Object> redisTemplate;

    private static final String USER_CACHE_KEY = "user:info:";
    private static final Duration CACHE_EXPIRE = Duration.ofHours(1);

    public UserInfoVO getUserFromCache(Long userId) {
        String key = USER_CACHE_KEY + userId;
        return (UserInfoVO) redisTemplate.opsForValue().get(key);
    }

    public void putUserToCache(Long userId, UserInfoVO userInfo) {
        String key = USER_CACHE_KEY + userId;
        redisTemplate.opsForValue().set(key, userInfo, CACHE_EXPIRE);
    }

    public void evictUserCache(Long userId) {
        String key = USER_CACHE_KEY + userId;
        redisTemplate.delete(key);
    }
}

缓存最佳实践

  • 使用统一的缓存键前缀，便于管理
  • 设置合适的过期时间，避免缓存雪崩
  • 重要数据更新时及时清除缓存
  • 使用分布式锁避免缓存击穿

异步处理规范 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

@Service
public class AsyncUserService {

    @Async("taskExecutor")
    public CompletableFuture<Void> processUserDataAsync(Long userId) {
        try {
            // 异步处理用户数据
            processUserData(userId);
            return CompletableFuture.completedFuture(null);
        } catch (Exception e) {
            log.error("异步处理用户数据失败", e);
            return CompletableFuture.failedFuture(e);
        }
    }
}

项目规范总结

架构一致性要求

微服务项目都必须遵循以下架构规范：

  1. 统一的项目结构: xxx-api、xxx-core、xxx-server 三层架构
  2. 统一的包命名: com.xx.xxx 包结构规范
  3. 统一的类命名: 严格按照后缀规范命名所有类
  4. 统一的构建配置: 使用标准化的 Gradle 配置

代码质量要求

  1. 规范的异常处理: 统一的异常处理机制和错误码规范
  2. 完善的日志记录: 使用 Log4j2 和操作日志记录
  3. 标准的注释文档: JavaDoc 注释和 API 文档
  4. 合理的测试覆盖: 单元测试和集成测试
  5. 性能优化考虑: 缓存、异步处理、数据库优化

团队协作要求

  1. 统一的开发规范: 所有团队成员必须遵循相同的编码规范
  2. 标准的代码审查: 代码提交前必须经过代码审查
  3. 完整的文档维护: 及时更新项目文档和设计文档
  4. 持续的质量改进: 定期重构和优化代码质量

最后更新时间: 2025年12月10日 规范版本: 1.0.0 适用项目: XX线所有微服务项目

工作
工具
本文由作者按照 CC BY 4.0 进行授权