代码规范

本节代码示例以 EasyPro 驱动模块（SaveDriverDTO / modbus-01）为样板，分层规范适用于所有产品。

分层职责：

// Controller：只接收+组装
@PostMapping
public Result<Long> save(@Validated @RequestBody SaveDTO dto) {
    return Result.ok(service.save(dto));
}
// ServiceImpl：业务+事务
@Transactional(rollbackFor = Exception.class)
public Long save(SaveDTO dto) { ... }

// Controller 里写业务+直连DB
@PostMapping
public Result save(@RequestBody SaveDTO dto) {
    if (dto.getName()==null) // 校验散落
        return Result.fail();
    mapper.insert(dto); // 跳层
    // 业务逻辑全堆这里...
}

参数校验：

• Controller 入参统一用 @Validated（支持方法级参数校验，功能超集）。
• 实体类字段用 JSR-303 注解：@NotNull @NotBlank @Size @Min @Max @Pattern。
• 校验失败由全局异常处理器统一兜底，Controller 内不写 if (xxx == null) 防御。

// DTO
@Data
public class SaveDriverDTO {
    @Schema(description = "驱动名称", example = "modbus-01")
    @NotBlank(message = "驱动名称不能为空")
    private String name;

    @Schema(description = "端口", example = "502")
    @Min(value = 1, message = "端口非法")
    private Integer port;
}

// Controller
@PostMapping
public Result<Void> save(@Validated @RequestBody SaveDriverDTO dto) {
    driverService.save(dto);
    return Result.success();
}

异常处理（统一由全局异常处理器 GlobalExceptionHandler 兜底）：

• 业务异常：抛 ServiceException（或项目既有的业务异常基类），由全局处理器转 Result.fail(msg)。
• 校验异常：MethodArgumentNotValidException / ConstraintViolationException 由全局处理器拦截，提取首个错误信息返回。
• Controller 与 Service 禁止 try-catch 吞异常后返回 null/默认值；让异常向上传播由全局处理器统一处理。
• 禁止用返回值表达"失败"（如返回 null 表示出错），改用异常。

Controller 内禁止：

• 直接 @Autowired Mapper 或 SqlSession。
• 多个不相关业务方法堆在一个 Controller（按资源拆分）。
• 在 Controller 拼 SQL 或写循环逻辑。

日志（统一用 Lombok @Slf4j）：

• 类上加 @Slf4j，用 log.info()/log.error()，禁止手动 LoggerFactory.getLogger()。
• 用占位符 {}，禁止字符串拼接（性能与可读性）：

// [✓] 占位符
log.info("驱动实例启动成功, id={}, name={}", id, name);

// [✗] 字符串拼接
log.info("驱动实例启动成功, id=" + id + ", name=" + name);

• 日志级别：error（异常堆栈）/ warn（可恢复异常）/ info（关键业务节点）/ debug（调试，生产关闭）。
• 循环内禁止 info 级日志，用 debug 或聚合后打印。
• 敏感信息脱敏：密码、token、加密狗 key、客户密钥等禁止明文打印；必要时用脱敏工具或 ***。

事务：

• @Transactional 加在 ServiceImpl 方法上（非 Controller、非 Service 接口）。
• 默认 rollbackFor = Exception.class（否则只回滚 RuntimeException）。
• 事务方法内禁止：远程调用（HTTP/RPC，会拉长事务持锁时间）、长时间循环、文件 IO。
• 只读查询用 @Transactional(readOnly = true)。

常量与枚举：

• 魔法值禁止硬编码，提取为 static final 常量或枚举：

// [✗]
if (status == 1) { ... }

// [✓] 常量 / 枚举
if (Objects.equals(status, DriverStatus.ENABLED.getCode())) { ... }

• 状态码、类型标识统一用枚举（<语义>Enum，实现带 code/desc 字段），禁止散落的 int 常量。
• 字符串常量集中到各模块的 Constants 类，命名 UPPER_SNAKE_CASE。

注释与 JavaDoc：

• 公共类、公共方法、抽象方法必须有 JavaDoc，含 @param @return @throws（参考现有 Result.java、SwaggerConfig.java 风格，含 @author 与创建时间）。
• 注释解释 why（为什么这么做），而非 what（代码本身已表达）。
• 临时调试代码（System.out.println、注释掉的代码块）禁止提交，由 §2.7 Hook 拦截。
• TODO/FIXME 需带责任人：// TODO(zhangsan 2026-08): xxx。

Lombok 使用约定：

• 实体/DTO/VO：@Data（含 getter/setter/toString）。
• 链式调用场景：@Accessors(chain = true)（参考 Result.java）。
• 构造器：@RequiredArgsConstructor 用于注入 final 依赖，替代 @Autowired 字段注入。

@Service
@RequiredArgsConstructor
public class DriverServiceImpl implements DriverService {
    private final DriverMapper driverMapper;   // final + 构造器注入，优于 @Autowired
}