开发规范草案

本文件根据项目现有代码样本提取，目标是将隐含约定显式化，便于团队统一风格与快速上手。

1. 项目结构与包命名
- 采用标准 Spring Boot 项目结构，顶级包为 `work.baiyun.chronicdiseaseapp`。
- 分层清晰：`config`, `controller`, `service`, `mapper`, `model` (含 `po`, `vo`, `bo`), `common`, `exception`, `handler`, `util` 等。
- 包命名使用小写，按功能划分。

2. 类与命名约定
- 类名采用 PascalCase（大驼峰）。
- 接口与实现类分别放在 `service` 与 `service.impl` 或使用明确后缀 `*Service`/`*ServiceImpl`。
- Mapper 使用 `*Mapper` 命名，位于 `mapper` 包。

3. POJO 与数据库字段映射
- 建议 POJO 字段使用驼峰命名（camelCase）。
- 通过 `@TableField` 等注解映射数据库 snake_case 列名（项目 README 中已有建议）。

4. 控制器与返回结构
- 全局统一返回类型为 `work.baiyun.chronicdiseaseapp.common.R<T>`。
- `R` 提供 `success` / `fail` 静态方法，包含 `code`、`message`、`data` 字段。
- Controller 层尽量返回 `R<T>`，业务异常与验证异常由全局异常处理器处理。

5. 分页
- 分页封装使用 `work.baiyun.chronicdiseaseapp.common.Page<T>`，构造器接受 `pageNum`, `pageSize`, `list`，并使用 `PageInfo` 获取 total。

6. 异常处理
- 使用自定义 `CustomException` 抛出业务异常。
- 全局异常处理器 `CustomExceptionHandler`（使用 `@RestControllerAdvice`）统一处理：
  - 参数校验异常：`BindException`、`ConstraintViolationException` → 返回验证失败信息（合并消息）
  - 自定义异常：`CustomException` → 返回自定义消息
  - 其他异常：打印堆栈并返回通用错误码/信息（参考 `ExceptionResultCode`）

7. 依赖与自动配置
- 项目使用 Spring Boot，并排除了 Thymeleaf 的自动配置（见 `SpringAPP`）。
- 使用 Knife4j（API 文档）注解 `@EnableKnife4j`。

8. 注解与校验
- 参数校验使用 Jakarta Validation（见 `ConstraintViolationException` 的处理），并在 Controller/DTO 上使用注解进行字段校验。

9. 日志与调试
- 在全局未捕获异常时使用日志记录（已将 `printStackTrace()` 替换为 SLF4J 的 `log.error(...)`）。
- 推荐使用 SLF4J + Logback（项目中添加了 `logback-spring.xml`），控制台＋文件滚动保存日志。示例：

```java
private static final org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger(YourClass.class);
try {
  // ...
} catch (Exception e) {
  log.error("处理异常", e);
}
```

- 约定：不要在代码中使用 `e.printStackTrace()`；优先使用 `log.debug/info/warn/error` 并在生产环境避免过多的 DEBUG/TRACE 输出。

10. Lombok 使用
- 项目使用 Lombok（见 `@Data`, `@Getter`, `@Setter`），请在 IDE 中启用 Lombok 插件并配置编译器注解处理。

11. 风格建议（可选增强）
- 引入 Checkstyle / SpotBugs / PMD 做静态检查，统一代码风格。
- 使用 Git 钩子（pre-commit）自动格式化（例如使用 google-java-format 或者 Eclipse formatter）。
- 将 `R` 的 code/message 常量化到枚举（项目已有 `ExceptionResultCode`、`SuccessResultCode`、`FailResultCode`）。
- 用统一 Logger 替换 `printStackTrace()`，并在生产环境禁用 DEBUG/TRACE 日志。

附录：样本来源文件
- `src/main/java/work/baiyun/chronicdiseaseapp/SpringAPP.java`
- `src/main/java/work/baiyun/chronicdiseaseapp/common/Page.java`
- `src/main/java/work/baiyun/chronicdiseaseapp/common/R.java`
- `src/main/java/work/baiyun/chronicdiseaseapp/exception/CustomException.java`
- `src/main/java/work/baiyun/chronicdiseaseapp/exception/CustomExceptionHandler.java`

说明：这是初稿，可依据团队反馈补充 Controller 注解约定、事务管理、Service 层返回类型、单元测试约定（JUnit 版本、Mock 框架）等内容。