Spring Boot + Spring Cloud Gateway + Nacos + Sentinel 网关最佳实践指南

在微服务架构中，API 网关是流量的统一入口。本文将结合 Spring Boot、Spring Cloud Gateway 与 Spring Cloud Alibaba（Nacos、Sentinel），为你构建一个高性能、可扩展、可观测的网关解决方案。

一、为什么是这套组合？

• Spring Cloud Gateway（Spring 官方）
  基于响应式 WebFlux 的高性能 API 网关，支持路由、负载均衡、过滤器链等。
• Nacos（Spring Cloud Alibaba 提供）
  服务发现 + 配置中心。Gateway 可从 Nacos 动态获取服务实例和路由配置。
• Sentinel（Spring Cloud Alibaba 提供）
  提供流量控制、熔断降级、系统保护，保护下游服务。

因此典型组合是：
Gateway (Spring) + Nacos (注册/配置中心) + Sentinel (流控保护)

二、项目初始化

1. pom.xml 依赖

<properties>
    <java.version>17</java.version>
    <spring-boot.version>3.2.4</spring-boot.version>
    <spring-cloud.version>2023.0.1</spring-cloud.version>
    <spring-cloud-alibaba.version>2023.0.1.0</spring-cloud-alibaba.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>${spring-cloud.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-alibaba-dependencies</artifactId>
            <version>${spring-cloud-alibaba.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- Spring Cloud Gateway -->
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-gateway</artifactId>
    </dependency>

    <!-- Nacos 服务发现 -->
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
    </dependency>

    <!-- Sentinel 网关流控 -->
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-alibaba-sentinel-gateway</artifactId>
    </dependency>
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
    </dependency>

    <!-- Sentinel 持久化到 Nacos（可选） -->
    <dependency>
        <groupId>com.alibaba.csp</groupId>
        <artifactId>sentinel-datasource-nacos</artifactId>
    </dependency>
</dependencies>

三、配置文件 application.yml

server:
  port: 8080

spring:
  application:
    name: api-gateway
  cloud:
    nacos:
      discovery:
        server-addr: 192.168.1.100:8848
        namespace: public
        group: DEFAULT_GROUP

    gateway:
      discovery:
        locator:
          enabled: false # 推荐关闭自动发现，使用自定义路由
      routes:
        - id: user-service-route
          uri: lb://user-service
          predicates:
            - Path=/api/users/**
          filters:
            - StripPrefix=1
        - id: order-service-route
          uri: lb://order-service
          predicates:
            - Path=/api/orders/**
          filters:
            - StripPrefix=1

    sentinel:
      eager: true
      transport:
        dashboard: localhost:8088
      datasource:
        ds1:
          nacos:
            server-addr: ${spring.cloud.nacos.discovery.server-addr}
            dataId: ${spring.application.name}-gateway-flow-rules
            groupId: SENTINEL_GROUP
            rule-type: gw-flow

四、主启动类

@SpringBootApplication
@EnableDiscoveryClient
public class GatewayApplication {
    public static void main(String[] args) {
        SpringApplication.run(GatewayApplication.class, args);
    }
}

五、接入 Sentinel

1. 启动 Sentinel Dashboard：

java -Dserver.port=8088 -Dcsp.sentinel.dashboard.server=localhost:8088 -jar sentinel-dashboard.jar

2. 访问 http://localhost:8088，默认账号密码 sentinel/sentinel
3. 触发路由后，控制台会出现 api-gateway 应用
4. 在控制台上配置网关 流控规则，并可持久化到 Nacos

六、自定义全局过滤器（鉴权）

@Component
@Slf4j
public class AuthGlobalFilter implements GlobalFilter, Ordered {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String token = exchange.getRequest().getHeaders().getFirst("Authorization");
        if (token == null) {
            exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
            return exchange.getResponse().setComplete();
        }
        return chain.filter(exchange.mutate()
            .request(builder -> builder.header("X-User-Id", "123"))
            .build());
    }

    @Override
    public int getOrder() {
        return 0;
    }
}

七、生产环境优化建议

1. 路由动态刷新

• 使用 Nacos 配置中心托管 spring.cloud.gateway.routes，实现无重启动态更新。

2. 灰度发布

• 使用自定义 Filter，根据 Header、版本号、用户ID 等进行灰度流量路由。

3. 统一鉴权

• 建议集成 JWT 校验，支持单点登录（SSO）或 OAuth2。

4. 监控与日志

• 接入 Prometheus + Grafana，结合 Sleuth/Zipkin 实现全链路追踪。

5. Sentinel 最佳实践

• 规则持久化到 Nacos，避免重启丢失。常用规则：

• API 分组限流
• 服务粒度限流
• 熔断降级

6. Nacos 高可用

• 至少 3 节点集群，配置 MySQL 存储，防止单点故障。

八、整体架构图

   ┌───────────┐
   │  Client   │
   └─────▲─────┘
         │
         ▼
 ┌──────────────────────┐
 │  Spring Cloud Gateway │  ← 全局入口，鉴权、限流、路由
 └───▲───────────────┘
     │       ▲
     │       │
     ▼       │
┌────────┐   │   ┌──────────┐
│  Nacos  │──┘   │ Sentinel │
│服务注册│       │ 流量控制 │
└────────┘       └──────────┘
     │
     ▼
┌───────────┐ ┌───────────┐
│ user-svc  │ │ order-svc │   ← 微服务
└───────────┘ └───────────┘

九、总结

• Spring Cloud Gateway：核心流量入口，负责路由、过滤器链
• Nacos：服务发现 + 配置中心，支撑动态路由和服务注册
• Sentinel：网关限流、熔断、系统保护
• 优化实践：动态路由、灰度发布、统一鉴权、全链路监控、持久化规则

这套组合已经成为国内 Java 微服务最主流、最成熟的网关解决方案。

完整代码仓库结构 整理出来，包含 gateway、user-service、order-service 三个服务，搭建一个最小可运行的 Spring Cloud Alibaba 网关示例。

示例项目结构

sca-gateway-demo/
├── gateway/                   # Spring Cloud Gateway 网关服务
│   ├── pom.xml
│   └── src/main/java/com/example/gateway/
│       ├── GatewayApplication.java
│       └── filter/
│           └── AuthGlobalFilter.java
│   └── src/main/resources/
│       └── application.yml
│
├── user-service/              # 用户服务
│   ├── pom.xml
│   └── src/main/java/com/example/user/
│       ├── UserServiceApplication.java
│       └── controller/
│           └── UserController.java
│   └── src/main/resources/
│       └── application.yml
│
├── order-service/             # 订单服务
│   ├── pom.xml
│   └── src/main/java/com/example/order/
│       ├── OrderServiceApplication.java
│       └── controller/
│           └── OrderController.java
│   └── src/main/resources/
│       └── application.yml
│
└── pom.xml                    # 父 POM，统一依赖管理

父项目 pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>sca-gateway-demo</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>

    <modules>
        <module>gateway</module>
        <module>user-service</module>
        <module>order-service</module>
    </modules>

    <properties>
        <java.version>17</java.version>
        <spring-boot.version>3.2.4</spring-boot.version>
        <spring-cloud.version>2023.0.1</spring-cloud.version>
        <spring-cloud-alibaba.version>2023.0.1.0</spring-cloud-alibaba.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <!-- Spring Boot -->
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring-boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>

            <!-- Spring Cloud -->
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>

            <!-- Spring Cloud Alibaba -->
            <dependency>
                <groupId>com.alibaba.cloud</groupId>
                <artifactId>spring-cloud-alibaba-dependencies</artifactId>
                <version>${spring-cloud-alibaba.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-maven-plugin</artifactId>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>
</project>

Gateway 服务

GatewayApplication.java

@SpringBootApplication
@EnableDiscoveryClient
public class GatewayApplication {
    public static void main(String[] args) {
        SpringApplication.run(GatewayApplication.class, args);
    }
}

AuthGlobalFilter.java

@Component
@Slf4j
public class AuthGlobalFilter implements GlobalFilter, Ordered {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String token = exchange.getRequest().getHeaders().getFirst("Authorization");
        if (token == null) {
            exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
            return exchange.getResponse().setComplete();
        }
        return chain.filter(exchange.mutate()
            .request(builder -> builder.header("X-User-Id", "123"))
            .build());
    }

    @Override
    public int getOrder() {
        return 0;
    }
}

application.yml

server:
  port: 8080

spring:
  application:
    name: api-gateway
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
    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

User Service

UserServiceApplication.java

@SpringBootApplication
@EnableDiscoveryClient
@RestController
@RequestMapping("/users")
public class UserServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(UserServiceApplication.class, args);
    }

    @GetMapping("/{id}")
    public String getUser(@PathVariable String id) {
        return "User-" + id;
    }
}

application.yml

server:
  port: 8081

spring:
  application:
    name: user-service
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848

Order Service

OrderServiceApplication.java

@SpringBootApplication
@EnableDiscoveryClient
@RestController
@RequestMapping("/orders")
public class OrderServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(OrderServiceApplication.class, args);
    }

    @GetMapping("/{id}")
    public String getOrder(@PathVariable String id) {
        return "Order-" + id;
    }
}

application.yml

server:
  port: 8082

spring:
  application:
    name: order-service
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848

启动步骤

1. 启动 Nacos

sh startup.sh -m standalone

默认地址
http://127.0.0.1:8848/nacos

2. 启动三个服务

• user-service（端口 8081）
• order-service（端口 8082）
• gateway（端口 8080）

3. 测试访问

• http://localhost:8080/api/users/1 → 通过网关访问 user-service
• http://localhost:8080/api/orders/99 → 通过网关访问 order-service