实战二：企业级 Boot 工程骨架（目录/配置/异常/返回体/安全）

上一章是单服务最小范式，本章给出企业级工程骨架：目录约定、多环境配置、统一返回体与错误码、统一异常、安全基线。这些约定让多个团队写出风格一致的代码，是工程化的分水岭。

目录约定

backend/
├── pom.xml
└── src/main/java/com/example/platform/
    ├── PlatformApplication.java
    ├── common/          # 返回体 Result、错误码 ErrorCode、常量
    ├── config/          # 配置类：Security、Jackson、OpenAPI、线程池
    ├── security/        # JWT 过滤器、UserDetailsService、认证入口
    ├── controller/  service/  repository/  entity/  dto/
    ├── exception/       # BizException 与 GlobalExceptionHandler
    └── util/            # 无状态工具类
src/main/resources/
├── application.yml          # 公共配置
├── application-dev.yml      # 环境差异配置
├── application-prod.yml
└── logback-spring.xml

分层铁律：controller 不写 SQL、repository 不写业务、entity 不直接出参（用 DTO），依赖单向向下。

多环境配置

# application.yml
spring:
  profiles:
    active: ${SPRING_PROFILES_ACTIVE:dev}   # 环境由外部变量决定，代码零改动

差异项（数据源、日志级别、外部地址）放各 profile 文件；密钥不进仓库，用环境变量/配置中心（第 35 章）注入。

统一返回体与错误码

public record Result<T>(int code, String message, T data) {
    public static <T> Result<T> ok(T data) {
        return new Result<>(0, "ok", data);
    }
    public static <T> Result<T> fail(int code, String message) {
        return new Result<>(code, message, null);
    }
}

public enum ErrorCode {
    PARAM_ERROR(400), UNAUTHORIZED(401), FORBIDDEN(403), NOT_FOUND(404), BIZ_ERROR(500);
    // 构造器、getCode 省略
}

约定：HTTP 状态码管传输层，业务 code 管业务层；成功统一 code=0；Controller 全部返回 Result，不再裸返回对象。文档（第 28 章）与前端都按这个契约联调。

统一异常体系

public class BizException extends RuntimeException {
    private final int code;
    private final int httpStatus;
    // 构造器省略：BizException(ErrorCode.NOT_FOUND, "用户不存在")
}

GlobalExceptionHandler 统一兜底五类：参数校验（MethodArgumentNotValidException）、BizException、无权限、404、兜底 Exception（记 error 日志后返回"系统繁忙"，不把堆栈泄露给客户端）。Security 的 401/403 由第 33 章的两个 Handler 输出同样结构的 Result JSON。

安全与质量基线

• 认证：JWT 无状态（第 31 章），密码 BCrypt（第 30 章），写接口 @PreAuthorize（第 32 章）；
• Actuator 不公网暴露、敏感端点按最小权限放行（第 26 章）；
• 接口文档随代码生成（第 28 章），生产按需关闭；
• 依赖用 spring-boot-dependencies BOM 管版本，插件固定版本，CI 里跑单元/集成测试（第 24/25 章）；
• 打包部署走第 39 章：Docker 镜像 + graceful 停机 + 健康探针；
• 上线后指标与 traceId 日志齐备（第 40 章），告警阈值按基线配置。

骨架能帮你省掉的决策

• 新人不用猜"返回体长什么样、异常在哪抛、配置放哪个文件"——看骨架即知；
• 跨服务调用、加新模块都照目录结构复制粘贴，保持一致性；
• 敏感操作（改密、删除）额外留审计日志，属骨架标配。

小结：企业级骨架 = 目录分层 + profile 多环境 + Result/ErrorCode 契约 + 全局异常 + 安全与可观测基线；工程化比拼的不是单点技巧，而是统一约定被严格执行。