ChronicDisease_APP/ChronicDisease_SpringBoot @ 021d4ec0e33554ea13f564ddaad5c70812180c51

开发规范草案

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

项目结构与包命名
采用标准 Spring Boot 项目结构，顶级包为 work.baiyun.chronicdiseaseapp。
分层清晰：config, controller, service, mapper, model (含 po, vo, bo), common, exception, handler, util 等。
包命名使用小写，按功能划分。
类与命名约定
类名采用 PascalCase（大驼峰）。
接口与实现类分别放在 service 与 service.impl 或使用明确后缀 *Service/*ServiceImpl。
Mapper 使用 *Mapper 命名，位于 mapper 包。
POJO 与数据库字段映射
建议 POJO 字段使用驼峰命名（camelCase）。
通过 @TableField 等注解映射数据库 snake_case 列名（项目 README 中已有建议）。
控制器与返回结构
全局统一返回类型为 work.baiyun.chronicdiseaseapp.common.R<T>。
R 提供 success / fail 静态方法，包含 code、message、data 字段；success/fail 有带/不带 data 的重载方法，返回类型以 R<Void> 表示无数据的情况。
推荐 Controller 层返回 R<T>。业务异常与参数校验异常由全局异常处理器 work.baiyun.chronicdiseaseapp.exception.CustomExceptionHandler 处理；文中有更多异常类型及其返回码的说明（见“异常处理”一节）。
分页
分页封装使用 work.baiyun.chronicdiseaseapp.common.Page<T>，构造器接受 pageNum, pageSize, list，并使用 com.github.pagehelper.PageInfo 从 list 中获取 total。注意：传入的 list 应当是经过 PageHelper 分页查询后的结果（例如在 mapper 层调用 PageHelper.startPage(...) 之后的查询结果）。
异常处理
业务异常：项目使用 work.baiyun.chronicdiseaseapp.exception.CustomException（继承自 Exception）来表示可控的业务错误，直接抛出 new CustomException("...") 即可。
全局异常处理器为 work.baiyun.chronicdiseaseapp.exception.CustomExceptionHandler，已使用 @RestControllerAdvice，并按类型处理：
- BindException：从 BindingResult 拼接 ObjectError 的 defaultMessage，以 R.fail(ExceptionResultCode.VALID_EXCEPTION.getCode(), <merged message>) 返回；
- ConstraintViolationException：收集 ConstraintViolation::getMessage 并合并为逗号分隔字符串，返回 R.fail(ExceptionResultCode.VALID_EXCEPTION.getCode(), <message>)；
- CustomException：返回 R.fail(ExceptionResultCode.EXCEPTION.getCode(), customException.getMessage())；
- Exception（兜底）：使用 SLF4J 记录错误日志（logger.error("Unhandled exception", exception)），并返回 R.fail(ExceptionResultCode.EXCEPTION.getCode(), ExceptionResultCode.EXCEPTION.getMsg())。

注意：当前 CustomException 继承自已检查异常 Exception（非 RuntimeException），在 Service/Controller 中抛出时须显式声明或在方法签名中处理；如需改为运行时异常以简化调用栈，可以考虑改为继承 RuntimeException（这是可选的 API 设计决策）。

依赖与自动配置
项目使用 Spring Boot，启动类 work.baiyun.chronicdiseaseapp.SpringAPP 标注了 @SpringBootApplication(exclude = {ThymeleafAutoConfiguration.class})，因此 Thymeleaf 自动配置被显式排除；如使用模板相关功能需要移除该排除项。
使用 Knife4j（API 文档）并在启动类上加了 @EnableKnife4j 注解以启用扩展功能。
注解与校验
参数校验使用 Jakarta Validation（见 ConstraintViolationException 的处理），并在 Controller/DTO 上使用注解进行字段校验。
日志与调试
在全局未捕获异常时使用日志记录（已将 printStackTrace() 替换为 SLF4J 的 log.error(...)）。

推荐使用 SLF4J + Logback（项目中添加了 logback-spring.xml），控制台＋文件滚动保存日志。示例：

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 输出。

Lombok 使用
项目使用 Lombok（见 @Data, @Getter, @Setter），请在 IDE 中启用 Lombok 插件并配置编译器注解处理。
风格建议（可选增强）
引入 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 框架）等内容。

DEVELOPMENT_GUIDELINES.md 5.4 KB Түүх Анхны өгөгдөл

DEVELOPMENT_GUIDELINES.md 5.4 KB

Түүх Анхны өгөгдөл