SpringBoot代码风格推荐

整体包结构

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.ja va
    └── XxxHelper.ja va        # 辅助类，放在对应功能包内

先说说整体包结构这件事。很多团队刚开始做项目时，包结构往往随手一搭，后续随着业务膨胀就变得难以维护。这里给出一个比较成熟的实践方案：按功能职责分层，而不是按技术框架分层。这样做的最大好处是，新成员拿到项目就能快速定位——看到“controller”知道是接口层，“service”是业务逻辑层，一目了然。

值得注意的是，这个结构里特别区分了“bean”目录。很多新手会把所有实体类都塞在一个“model”或“pojo”包里，但实际项目中，数据库实体、接口返回对象、接口接收参数这些对象的变化频率和维度完全不同，混在一起只会让依赖关系变得混乱。分开管理是从源头上控制耦合。

分层命名规范

分层命名的核心逻辑其实很清晰：每个类名后缀都代表了它的职责和生命周期。比如 Controller 只做请求转发和参数校验，不写业务逻辑；ServiceImpl 负责具体实现，但不直接操作数据库——通过 Mapper 接口做数据访问。这样拆开之后，每层的修改范围都被限定了，改动一个层不会波及到其他层。

需要特别说明的是“Biz”层。很多时候业务逻辑并不是简单的 CRUD堆砌，而是要协调多个 Service 调用外部接口，这时候就应该用 Biz把这些编排逻辑收拢起来。很多团队把这个和 ServiceImpl混淆,结果ServiceImpl越来越臃肿，变成了大泥球。

实体类命名规范

业务实体

使用示例

// 保存用户：接收 Dto，返回 Vo
@PostMapping("/sa ve")
public SysUserVo sa veUser(@RequestBody @Valid SysUserSa veDto dto) {
    SysUserPo po = userConvert.toPo(dto);
    userMapper.insert(po);
    return userConvert.toVo(po);
}

❌ 不要将 Entity / Po 直接返回给前端

✅ 各层对象严格隔离，降低变动影响面

实体类这一块其实很容易踩坑。很多人嫌麻烦，直接把数据库实体（Po）返回给前端，省去了转换的步骤。这种做法在简单项目里看似高效，但随着需求迭代，你有天突然发现需要给某字段重命名，或者要隐藏一些敏感字段，改动就成了噩梦——因为前端、数据库、内部逻辑全绑在一个类上了。

严格区分 Vo、Dto、Po、Bo 这几个对象类型，本质上是在不同边界处设置“防火墙”。即使每个实体多写几个转换方法，但长期来看收益远远大于成本。特别是用了 MapStruct 等转换工具后，代码量其实并没有增加多少。

业务之外的实体

对于独立于业务之外的实体，如工具类、框架配置等需要的对象，有两种常见处理方式：

示例

方式一：使用内部类（适用于仅当前类使用）

@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.ja va
public class OrderStatContext {
    private Long userId;
    private LocalDateTime startTime;
    private LocalDateTime endTime;
    // 订单统计的中间计算对象
}

选择建议

• 仅当前类使用 → 内部类
• 业务特有但不属于标准 Entity/Vo/Dto/Bo → 放在对应业务包下

这一部分可能容易产生分歧。对于非标准实体对象，有些人倾向于全部放在一个公共包里，但实际经验表明，紧耦合的业务对象放在业务包下更合理：当业务模块被重构或拆分时，这些对象可以跟着迁移，不会产生大的牵扯。

工具类命名规范

示例代码

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 RedisTemplate redisTemplate;
    
    public Object get(String key) {
        return redisTemplate.opsForValue().get(key);
    }
}
// 使用
@Service
public class UserService {
    @Autowired
    private RedisKit redisKit;
}

Helper（功能专用，放在对应功能包内）

// job/JobHelper.ja va
@Component
public class JobHelper {
    @Autowired
    private MailService mailService;
    
    public void sendAlert(String jobName, Exception e) {
        mailService.send("Job Alert", jobName + " 执行失败：" + e.getMessage());
    }
}

工具类的命名看起来是小细节，但实际影响代码的可读性和可维护性。很多项目里的工具类命名很随意，有的叫Utils，有的叫Tools，还有的干脆叫XxxHelper。这里给出明确区分逻辑：纯静态、不依赖Spring的用Util，需要注入容器的用Kit，功能专用的用Helper。区分清楚后，使用者看到类名就能判断它的使用方式，不需要阅读源码或文档。

特别提醒一点：Kit 和 Helper 虽然都是注入使用，但 Kit 是通用的、跨业务的工具性组件（比如封装了对Redis的操作），而 Helper 是业务专用的辅助类（比如定时任务失败发送邮件的逻辑）。这个区别不只是概念上的，更体现在包位置和职责上——Kit放在全局的 util 包，Helper放在具体业务包内，避免通用层与业务层的依赖关系错乱。