offerpai_backend/.kiro/steering/代码开发风格文档.md

inclusion

inclusion
manual

代码开发风格文档

本项目为 Spring Boot + MyBatis-Plus 的 Java 17 多模块后端项目，基础包名 org.jiayunet。

项目结构

• common — 公共模块：配置、拦截器、工具类、统一响应、异常体系
• client-api — C 端接口模块，依赖 manager
• manager — 业务共享模块：实体、Mapper、业务服务，B 端和 C 端共用，依赖 common
• 各模块内按职责分包：controller、service、pojo（dto/vo/po/param）、mapper、config、aop、annotation、tool、constant、interceptor

命名约定

类命名

• 服务层以 Service 结尾，如 LoginService、SmsService
• DTO 以 Dto 结尾，VO 以 Vo 结尾，Param 以 Param 结尾，PO 无后缀直接用业务名
• Controller 以 Controller 结尾
• 工具类以 Tool 结尾，如 RedisServerTool、HttpIpTool
• 配置类以 Config 或 Conf 结尾
• 切面以 Aspect 结尾，拦截器以 Interceptor 结尾，过滤器以 Filter 结尾
• 能力/抽象类以 Ability 结尾，如 EmailAbility
• 枚举以 Enum 结尾，枚举接口以 Operations 结尾

常量

• Redis key 前缀用 interface 定义常量，集中在 PreRedisKeyName 中
• 自定义配置属性统一用 app. 前缀分组

注解与依赖注入

• Controller 层：@RestController + @RequestMapping，构造器注入（@AllArgsConstructor）
• Service 层：@Service，字段注入（@Autowired）
• 配置值：@Value("${app.xxx:默认值}")，始终提供默认值
• 参数校验：类上 @Validated，字段上 @NotBlank、@Pattern 等
• 写操作方法加 @Transactional(rollbackFor = Exception.class)
• 所有 POJO 使用 @Data，需要日志的类加 @Slf4j

注释规范

• 类注释 Javadoc 格式，标注 @author zk
• 方法注释 /** */，简洁描述功能
• 字段注释 /** */ 单行格式

PO 实体类注释

• 类注释说明对应的表名和用途
• 特殊字段（状态码、标志位、枚举值等）在注释中说明每个值的含义，如 /** 状态 0=正常 1=禁用 */

Service 类注释

• 类注释说明该服务的主要功能
• 类注释中列出依赖的其他模块/服务，以及使用到的表和使用目的，格式示例：

  /**
   * 登录服务
   * <p>依赖：SmsService（验证码发送与校验）、UserRegisterService（自动注册）</p>
   * <p>使用表：bg_user（查询/创建用户）</p>
   *
   * @author zk
   */
  

• 每个方法用 /** */ 简要说明逻辑流程，复杂方法可分步骤描述，格式示例：

  /**
   * 短信验证码登录
   * <p>1. 校验验证码 2. 查询用户，不存在则自动注册 3. 检查用户状态 4. 生成JWT并写入Redis 5. 设置Cookie</p>
   */
  

POJO 规范

• DTO：入参对象 + 校验注解，放在 pojo/dto/{功能模块}/ 下，功能模块一般是对应 Service 类名的简写，如 pojo/dto/login/SmsLoginDto.java
• VO：出参对象，放在 pojo/vo/{功能模块}/ 下，如 pojo/vo/login/LoginVo.java
• PO：对应数据库表字段，统一放在 manager 模块的 pojo/po/ 下
• Param：查询参数对象，放在 pojo/param/{功能模块}/ 下

获取当前登录用户

• 通过 UserSecurityTool.getUserId() 静态方法获取当前登录用户 ID
• 底层从 SecurityContextHolder 中取值，无需传参，任何层都可直接调用

分页规范

• 分页入参继承或组合 PageParam（位于 common 模块），包含 pageNum（默认1）和 pageSize（默认10，最大100）
• 通过 pageParam.toPage() 转换为 MyBatis-Plus 的 Page<T> 对象
• 分页出参统一使用 PageResult<T>，通过 PageResult.from(page) 从 MyBatis-Plus 分页结果构建
• 带业务筛选条件的分页查询，Param 对象中包含分页参数和筛选字段，放在 pojo/param/{功能模块}/ 下

接口规范

• Controller 只负责参数接收和调用 Service，不写业务逻辑
• 无需鉴权的接口放在 /public 前缀下
• POST 用 @PostMapping，GET 用 @GetMapping ...
• 复杂参数 @Validated @RequestBody，简单参数 @RequestParam
• Controller 方法直接返回业务对象，由 UnifiedResponseBodyAdvice 自动包装为 UnifiedResponse

异常处理

• 业务异常统一使用 throw new BusinessException(BusinessExpCodeEnum.XXX, "描述") 抛出
• 简单断言使用 Spring 的 Assert.hasText()、Assert.notNull() 等
• 不要 catch 后吞掉异常，交由 GlobalExceptionAdvice 统一处理

Redis 使用规范

• 统一通过 RedisServiceTool 操作，不直接使用 RedisTemplate
• key 自动拼接应用名前缀：{appName}:{业务key}
• 值统一 JSON 序列化
• 设置 TTL 时使用 TimeUnit 明确单位

数据库设计风格

• 表名以 bg_ 前缀，下划线命名，如 bg_user、bg_route_menu
• 主键 id，类型 Long，策略 ASSIGN_ID（雪花算法）
• 时间字段使用 Instant 类型，包含 createTime 和 updateTime
• 逻辑删除字段 isDelete，类型 Long，0=正常，非0=删除（@TableLogic(value = "0", delval = "new()")）
• 状态字段用 Integer，0/1 表示，注释中说明含义
• PO 类加 @TableName(value = "bg_xxx")，主键加 @TableId(type = IdType.ASSIGN_ID)
• 查询使用 LambdaQueryWrapper 构建条件，避免硬编码字段名
• 简单的 CRUD 直接使用 MyBatis-Plus 的 BaseMapper 方法和 LambdaQueryWrapper，只有复杂查询（多表关联、子查询等）才写 Mapper XML SQL
• Mapper 接口继承 BaseMapper<T>