📚 课程目录第2章 Spring Boot BFF项目初始化

2. Spring Boot BFF 项目初始化：使用 Spring Initializr 创建 BFF 项目、核心依赖配置

BFF（Backend For Frontend）模式要求网关层与前端应用紧密配合，因此项目初始化阶段需要精准选择依赖，确保路由转发、负载均衡、健康检查与指标暴露等能力开箱即用。本节将演示如何通过 Spring Initializr 快速搭建 BFF 项目骨架，并逐一说明 Spring Web、Spring Cloud Gateway、Actuator 三个核心依赖的作用与配置要点。

2.1 使用 Spring Initializr 生成项目骨架

推荐使用 https://start.spring.io 或 IDE 内置的 Initializr 向导生成项目。关键选择项如下：

配置项	推荐值	说明
Project	Maven	便于依赖管理与构建
Language	Java	版本 17 或 21
Spring Boot	3.2.x	选择最新稳定版
Group	com.yourcompany	按组织命名
Artifact	bff-gateway	项目标识
Packaging	Jar	BFF 通常以独立 Jar 部署
Java Version	17	LTS 版本，长期支持

提示： 如果团队使用 Spring Cloud 2023.0.x 版本，请确保 Spring Boot 版本为 3.2.x，避免版本不兼容导致路由失效。

2.2 核心依赖配置详解

在 pom.xml 中需要添加以下三个核心 Starter，它们共同构成了 BFF 网关的基础能力：

<dependencies>
    <!-- 1. Spring Web：提供 REST 端点与嵌入式 Tomcat -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- 2. Spring Cloud Gateway：路由转发、过滤器、限流 -->
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-gateway</artifactId>
    </dependency>

    <!-- 3. Actuator：健康检查、指标暴露、线程池监控 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
</dependencies>

2.3 依赖职责与配置要点

Spring Web：提供 @RestController、@RequestMapping 等注解，用于 BFF 对外暴露聚合接口；同时内嵌 Tomcat 作为 HTTP 容器，连接池参数（如 server.tomcat.threads.max）在此层配置。
Spring Cloud Gateway：基于 WebFlux 的非阻塞网关，负责将前端请求路由到下游微服务；支持断言（Predicate）与过滤器（Filter）链，是 BFF 的核心路由引擎。
Actuator：暴露 /actuator/health、/actuator/metrics 等端点，用于监控 BFF 实例的健康状态与连接池使用情况，是性能调优的数据来源。

注意： Spring Cloud Gateway 基于 WebFlux（Netty），而 Spring Web 默认使用 Tomcat。两者在同一个 BFF 项目中可以共存，但 Gateway 的路由处理由 Netty 线程模型接管，Tomcat 仅用于 Actuator 或自定义 REST 端点。不要将业务逻辑直接放在 Gateway 的路由处理器中，避免阻塞事件循环。

2.4 BFF 项目初始化架构图

下图展示了 BFF 项目初始化后的核心组件与依赖关系：

2.5 关键配置文件示例

在 application.yml 中配置 Gateway 路由与 Actuator 端点暴露：

server:
  port: 8080
  tomcat:
    threads:
      max: 200          # Tomcat 最大工作线程数
      min-spare: 20     # 最小空闲线程数
    max-connections: 8192
    accept-count: 100

spring:
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/api/users/**
          filters:
            - StripPrefix=1
        - id: order-service
          uri: lb://order-service
          predicates:
            - Path=/api/orders/**
          filters:
            - StripPrefix=1

management:
  endpoints:
    web:
      exposure:
        include: health,metrics,prometheus
  endpoint:
    health:
      show-details: always

  关键点： server.tomcat.threads.max 控制 Tomcat 线程池大小，直接影响 BFF 处理 REST 请求的并发能力；management.endpoints.web.exposure.include 必须包含 metrics 和 prometheus，后续连接池监控依赖这些端点。

2.6 依赖版本兼容性速查表

Spring Boot 版本	Spring Cloud 版本	Gateway 兼容性	推荐 Java 版本
3.2.x	2023.0.x	完全兼容	17 / 21
3.1.x	2022.0.x	兼容	17
3.0.x	2022.0.x	兼容（需注意 WebFlux 变更）	17

最佳实践： 生产环境建议使用 Spring Boot 3.2.x + Spring Cloud 2023.0.x 组合，该组合对虚拟线程（Virtual Threads）有更好的支持，可进一步提升 BFF 的吞吐能力。

2.7 初始化后的项目结构

项目生成后，典型的包结构如下：

bff-gateway/
├── src/main/java/com/yourcompany/bff/
│   ├── BffGatewayApplication.java        # 启动类
│   ├── config/
│   │   └── GatewayConfig.java            # 路由与过滤器配置
│   ├── controller/
│   │   └── BffController.java            # 聚合 REST 端点
│   └── filter/
│       └── CustomGlobalFilter.java       # 自定义全局过滤器
├── src/main/resources/
│   ├── application.yml                   # 主配置文件
│   └── bootstrap.yml                     # 配置中心引导（可选）
└── pom.xml