整体包结构com.example.project │ ├── bean # 实体类统一目录 │ ├── entity # 数据库实体 │ ├── vo # 接口返回对象 │ ├── dto # 接口接收参数 │ ├── bo # 业务层聚合对象 │ ├── doc # MongoDB 文档实体 │ ├── cache # 缓存实体对象 │ ├── index # ES 索引实体 │ ├── message # MQ 消息体 │ └── event # Spring 事件对象 ├── controller # Web 接口层 ├── service # 业务逻辑接口 │ └── impl # 业务逻辑实现 ├── mapper # 数据访问层 ├── biz # 业务聚合处理 ├── client # Feign 客户端 ├── convert # 对象转换器 ├── aspect # AOP 切面 ├── config # 配置类 ├── constant # 常量类 ├── enums # 枚举类 ├── exception # 自定义异常 ├── util # 工具类目录含 Util 和 Kit └── job # 定时任务 ├── XxxJob.java └── XxxHelper.java # 辅助类放在对应功能包内分层命名规范层级职责类名后缀包名说明Web 接口层​xxxController​​controller​接收请求、参数校验、返回 VoService 接口​xxxService​​service​业务逻辑接口定义Service 实现​xxxServiceImpl​​service.impl​业务逻辑实现加事务注解数据访问层​xxxMapper​​mapper​MyBatis/MyBatis-Plus 映射接口业务聚合处理​xxxBiz​​biz​跨 Service 或外部调用的复杂业务编排远程服务客户端​xxxClient​​client​Feign 声明式 HTTP 客户端对象转换器​xxxConvert​​convert​统一处理对象转换AOP 切面​xxxAspect​​aspect​横切关注点日志、权限、监控等常量类​xxxConst​​constant​常量按业务拆分不堆在一个类中枚举类​xxxEnum​​enums​统一管理枚举定义自定义异常​xxxException​​exception​业务异常或系统异常配置类​xxxConfig​​config​如 RedisConfig​、SwaggerConfig​定时任务​xxxJob​​job​定时调度任务类辅助类业务/功能​xxxHelper​对应功能包内如 job.JobHelper​、mail.MailHelper​实体类命名规范业务实体对象类型类名后缀包路径说明数据库实体​xxx​ / XxxPo​​bean.entity​ / bean.po​与数据库表结构一一对应接口返回对象​xxxVo​​bean.vo​面向前端展示接口接收参数​xxxDto​​bean.dto​接收请求参数可含校验注解业务层聚合对象​xxxBo​​bean.bo​业务逻辑层内部使用MongoDB 文档实体​xxxDoc​​bean.doc​MongoDB 实体定义缓存实体对象​xxxCache​​bean.cache​Redis/Caffeine 缓存结构ES 索引实体​xxxIndex​​bean.index​Elasticsearch 文档映射MQ 消息体​xxxMessage​​bean.message​队列/主题传输的消息体Spring 事件对象​xxxEvent​​bean.event​领域事件或应用事件对象使用示例// 保存用户接收 Dto返回 Vo PostMapping(/save) public SysUserVo saveUser(RequestBody Valid SysUserSaveDto dto) { SysUserPo po userConvert.toPo(dto); userMapper.insert(po); return userConvert.toVo(po); }❌ 不要将 Entity​ / Po​ 直接返回给前端✅ 各层对象严格隔离降低变动影响面业务之外的实体对于独立于业务之外的实体如工具类、框架配置等需要的对象有以下两种处理方式方式适用场景示例使用内部类仅被当前类使用、逻辑简单、内聚性强Controller 内部的请求/响应类、Service 内部的中间对象放在业务类一起与某个业务紧密相关但不属于标准实体类型业务特有的参数封装、中间计算结果对象示例方式一使用内部类适用于仅当前类使用RestController public class UserController { PostMapping(/login) public Result login(RequestBody LoginRequest request) { // ... } // 内部类仅用于当前 Controller static class LoginRequest { private String username; private String password; } }方式二放在业务类一起适用于业务特有对象// 放在使用它的 Service 同包下但不属于标准 bean 类型 // service/OrderStatContext.java public class OrderStatContext { private Long userId; private LocalDateTime startTime; private LocalDateTime endTime; // 订单统计的中间计算对象 }选择建议仅当前类使用 → 内部类业务特有但不属于标准 Entity/Vo/Dto/Bo → 放在对应业务包下工具类命名规范类型命名后缀包位置是否静态是否依赖容器说明静态工具类​xxxUtil​​util​✅ 是❌ 否纯静态方法无状态不依赖 Spring容器化工具类​xxxKit​​util​❌ 否✅ 是需要注入 Bean加 Component​辅助类业务/功能​xxxHelper​对应功能包内❌ 否✅ 是业务或功能专用如 job.JobHelper​示例代码Util静态调用public class DateUtil { public static String format(LocalDateTime date, String pattern) { // 静态方法不依赖 Spring } } // 使用 String dateStr DateUtil.format(now, yyyy-MM-dd);Kit注入使用放在 util 包Component public class RedisKit { Autowired private RedisTemplateString, Object redisTemplate; public Object get(String key) { return redisTemplate.opsForValue().get(key); } } // 使用 Service public class UserService { Autowired private RedisKit redisKit; }Helper功能专用放在对应功能包内// job/JobHelper.java Component public class JobHelper { Autowired private MailService mailService; public void sendAlert(String jobName, Exception e) { mailService.send(Job Alert, jobName 执行失败 e.getMessage()); } }