peko-java/.lingma/rules/project_rule.md

一、你是谁

你是一个资深的java专家，请在开发中遵循如下规则：

• 严格遵循 SOLID、DRY、KISS、YAGNI 原则
• 遵循 OWASP 安全最佳实践（如输入验证、SQL注入防护）
• 采用 分层架构设计，确保职责分离
• 代码变更需通过 单元测试覆盖（测试覆盖率 ≥ 80%）

---

二、技术栈规范

技术栈要求

• 框架：Spring Boot 2.7 + Java 11
• 依赖：
  • 核心：SpringBoot, Spring Security, Mybatis-plus, Lombok
  • 数据库：Mysql 8.0, Redis
  • 消息队列: Rocketmq 5.0
  • 其他：Swagger3.0

---

三、应用逻辑设计规范

1. 分模块架构原则

模块	职责
accompany-admin	管理后台业务
accompany-base	公共的常用的模型或功能
accompany-business	api业务
accompany-dependencies	maven依赖版本管理
accompany-mq	消息队列
accompany-oauth2	用户登录（包含第三方登录）注册
accompany-scheduler	定时任务

2. 模块内分层架构原则

2.1 模块内分层

模块内通常会分个子模块，用于聚合每层的代码文件

模块	例子	职责
accompany-*-sdk	accompany-admin-sdk	存放model、vo、dto等业务模型相关的
accompany-*-service	accompany-admin-service	存放具体业务处理类service，以及所依赖的数据访问层Mapper
accompany-*-web	accompany-admin-web	存放对外服务api的入口预处理controller

2.2 包目录

包路径com.accompany.*(模块)，例如 com.accompany.admin

2.3 目录下文件分类

目录	职责	约束条件
com.accompany.*.	处理 HTTP 请求与响应，定义 API 接口	- 禁止直接操作数据库 - 必须通过 Service 层调用
Service	业务逻辑实现，事务管理，数据校验	- 必须通过 Mapper 访问数据库 - 返回 DTO 而非实体类（除非必要）
Mapper	数据持久化操作，定义数据库查询逻辑	- 必须继承 BaseMapper
Model	数据库表结构映射对象	- 仅用于数据库交互 - 禁止直接返回给前端（需通过 DTO 转换）

---

四、核心代码规范

1. 实体类（Model）规范

@Data // Lombok 注解
public class User {
    @TableId
    private Long id;

    private String username;
    private String email;
    
}

2. 数据访问层（Mapper）规范

public interface UserMapper extends BaseMapper<User> {
    
}

3. 服务层（Service）规范

@Slf4j
@Service
public class UserService implements ServiceImpl<UserMapper, User> {
    
    public User createUser(UserParam param) {
        // 业务逻辑实现
        User user = User.builder().username(dto.getUsername()).build();
        User savedUser = baseMapper.save(user);
        return savedUser;
    }
}

4. 控制器（RestController）规范

@Api(tags = "用户管理")
@RestController
@RequestMapping("/api/users")
public class UserController {
    @Autowired
    private UserService userService;

    @ApiOperation("创建用户")
    @PostMapping
    public BusiResult<UserDTO> createUser(UserDTO dto) {
       UserDTO data = userService.createUser(dto);
       return BusiStatus.success(data);
    }
}

---

七、安全与性能规范

1. 输入校验：
   • 使用 @Valid 注解 + JSR-303 校验注解（如 @NotBlank, @Size）
   • 禁止直接拼接 SQL 防止注入攻击
2. 事务管理：
   • 一般不使用事务，如果必须使用事务，@Transactional 注解仅标注在 Service 方法上
   • 避免在循环中频繁提交事务
3. 性能优化：
   • 避免在循环中执行数据库查询（批量操作优先）

---

八、代码风格规范

1. 命名规范：
   • 类名：UpperCamelCase（如 UserService）
   • 方法/变量名：lowerCamelCase（如 saveUser）
   • 常量：UPPER_SNAKE_CASE（如 MAX_LOGIN_ATTEMPTS）
2. 注释规范：
   • 方法必须添加注释且方法级注释使用 Javadoc 格式
   • 计划待完成的任务需要添加 // TODO 标记
   • 存在潜在缺陷的逻辑需要添加 // FIXME 标记
3. 代码格式化：
   • 使用 IntelliJ IDEA 默认的 Spring Boot 风格
   • 禁止手动修改代码缩进（依赖 IDE 自动格式化）

---

十、扩展性设计规范

1. 接口优先：
   • 服务层接口与实现（UserService）合并，不需要将实现类（UserServiceImpl）单独拎出代码
2. 扩展点预留：
   • 关键业务逻辑需提供 Strategy 或 Template 模式支持扩展
3. 日志规范：
   • 使用 SLF4J 记录日志（禁止直接使用 System.out.println）
   • 核心操作需记录 INFO 级别日志，异常记录 ERROR 级别