DEVELOPMENT_GUIDELINES.md 3.4 KB
开发规范草案
本文件根据项目现有代码样本提取，目标是将隐含约定显式化，便于团队统一风格与快速上手。
- 项目结构与包命名
- 采用标准 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字段。Controller 层尽量返回
R<T>，业务异常与验证异常由全局异常处理器处理。分页
分页封装使用
work.baiyun.chronicdiseaseapp.common.Page<T>，构造器接受pageNum,pageSize,list，并使用PageInfo获取 total。异常处理
使用自定义
CustomException抛出业务异常。全局异常处理器
CustomExceptionHandler（使用@RestControllerAdvice）统一处理：- 参数校验异常：
BindException、ConstraintViolationException→ 返回验证失败信息（合并消息） - 自定义异常：
CustomException→ 返回自定义消息 - 其他异常：打印堆栈并返回通用错误码/信息（参考
ExceptionResultCode）
- 参数校验异常：
依赖与自动配置
项目使用 Spring Boot，并排除了 Thymeleaf 的自动配置（见
SpringAPP）。使用 Knife4j（API 文档）注解
@EnableKnife4j。注解与校验
参数校验使用 Jakarta Validation（见
ConstraintViolationException的处理），并在 Controller/DTO 上使用注解进行字段校验。日志与调试
在全局未捕获异常时打印堆栈（当前实现为
exception.printStackTrace()）。建议使用日志框架（如 SLF4J + Logback）替换直接打印。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.javasrc/main/java/work/baiyun/chronicdiseaseapp/common/Page.javasrc/main/java/work/baiyun/chronicdiseaseapp/common/R.javasrc/main/java/work/baiyun/chronicdiseaseapp/exception/CustomException.javasrc/main/java/work/baiyun/chronicdiseaseapp/exception/CustomExceptionHandler.java
说明：这是初稿，可依据团队反馈补充 Controller 注解约定、事务管理、Service 层返回类型、单元测试约定（JUnit 版本、Mock 框架）等内容。