【Java】微服务架构 Java 实战：Spring Cloud Gateway + Nacos 全链路搭建指南

lbb 小魔仙2026-01-20 8:18

微服务架构 Java 实战：Spring Cloud Gateway + Nacos 全链路搭建指南


🌸你好呀！我是 lbb小魔仙
🌟 感谢陪伴～ 小白博主在线求友
🌿 跟着小白学Linux/Java/Python
📖 专栏汇总：
《Linux》专栏 | 《Java》专栏 | 《Python》专栏

  • [微服务架构 Java 实战：Spring Cloud Gateway + Nacos 全链路搭建指南](#微服务架构 Java 实战：Spring Cloud Gateway + Nacos 全链路搭建指南)
    • 一、环境准备
      • [1.1 版本栈说明（强制统一，避免兼容性问题）](#1.1 版本栈说明（强制统一，避免兼容性问题）)
      • [1.2 Nacos 环境部署](#1.2 Nacos 环境部署)
    • 二、核心组件搭建
      • [2.1 公共依赖管理（父工程 POM）](#2.1 公共依赖管理（父工程 POM）)
      • [2.2 服务提供者（nacos-provider）](#2.2 服务提供者（nacos-provider）)
        • [2.2.1 子工程 POM 依赖](#2.2.1 子工程 POM 依赖)
        • [2.2.2 配置文件（bootstrap.yml）](#2.2.2 配置文件（bootstrap.yml）)
        • [2.2.3 启动类与业务接口](#2.2.3 启动类与业务接口)
      • [2.3 服务消费者（nacos-consumer）](#2.3 服务消费者（nacos-consumer）)
        • [2.3.1 子工程 POM 依赖](#2.3.1 子工程 POM 依赖)
        • [2.3.2 配置文件（bootstrap.yml）](#2.3.2 配置文件（bootstrap.yml）)
        • [2.3.3 启动类与 Feign 客户端](#2.3.3 启动类与 Feign 客户端)
      • [2.4 API 网关（spring-cloud-gateway）](#2.4 API 网关（spring-cloud-gateway）)
        • [2.4.1 子工程 POM 依赖](#2.4.1 子工程 POM 依赖)
        • [2.4.2 配置文件（bootstrap.yml）](#2.4.2 配置文件（bootstrap.yml）)
        • [2.4.3 启动类](#2.4.3 启动类)
    • 三、系统架构流程图
    • 四、功能验证
      • [4.1 启动顺序](#4.1 启动顺序)
      • [4.2 接口测试](#4.2 接口测试)
    • 五、生产级注意事项
      • [5.1 健康检查优化](#5.1 健康检查优化)
      • [5.2 配置热更新](#5.2 配置热更新)
      • [5.3 跨服务认证上下文传递](#5.3 跨服务认证上下文传递)
      • [5.4 网关优化](#5.4 网关优化)
      • [5.5 Nacos 生产部署](#5.5 Nacos 生产部署)
    • 六、总结

本文面向中高级 Java 开发者，聚焦 Spring Boot 3.x + Spring Cloud 2022.x + Nacos 2.x 技术栈，实战搭建微服务全链路架构。全程以"可运行、可复现"为核心，跳过冗余理论，直击服务注册发现、网关路由、负载均衡等核心环节，同时覆盖生产级优化要点。

一、环境准备

1.1 版本栈说明（强制统一，避免兼容性问题）

  • JDK：17+（Spring Boot 3.x 最低要求）

  • Spring Boot：3.1.8

  • Spring Cloud：2022.0.4（与 Spring Boot 3.1.x 兼容）

  • Spring Cloud Alibaba：2022.0.0.0-RC2（适配上述版本栈）

  • Nacos：2.2.3（注册中心 + 配置中心双角色）

1.2 Nacos 环境部署

  1. 下载 Nacos 2.2.3 安装包：https://github.com/alibaba/nacos/releases/tag/2.2.3

  2. 解压后启动（单机模式，适合开发测试）：

    • Linux/Mac：执行 sh startup.sh -m standalone

    • Windows：双击 startup.cmd（需提前配置 JAVA_HOME）

  3. 验证：访问 http://localhost:8848/nacos，默认账号密码均为 nacos，登录成功即部署完成。

二、核心组件搭建

整体架构分为三部分：服务提供者（provider）、服务消费者（consumer）、API 网关（gateway），均接入 Nacos 实现注册与配置管理。

2.1 公共依赖管理（父工程 POM）

创建 Maven 父工程，统一管理依赖版本，子工程继承后无需重复声明版本号：

Java 复制代码 
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.1.8</version>
    <relativePath/>
</parent>

<properties>
    <java.version>17</java.version>
    <spring-cloud.version>2022.0.4</spring-cloud.version>
    <spring-cloud-alibaba.version>2022.0.0.0-RC2</spring-cloud-alibaba.version>
</properties>

<dependencyManagement>
    <dependencies>
        <!-- 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>

2.2 服务提供者（nacos-provider）

实现基础接口，注册到 Nacos，供消费者调用。

2.2.1 子工程 POM 依赖
Java 复制代码 
<dependencies>
    <!-- Spring Boot Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- Nacos 服务注册与发现 -->
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
    </dependency>
    <!-- Nacos 配置中心 -->
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
    </dependency>
    <!-- 健康检查（生产级必备） -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
</dependencies>
2.2.2 配置文件（bootstrap.yml）

优先级高于 application.yml，用于加载 Nacos 配置中心信息：

yaml 复制代码 
spring:
  application:
    name: nacos-provider # 服务名，网关路由、负载均衡以此为标识
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848 # Nacos 注册中心地址
        namespace: public # 命名空间，默认public，生产环境建议按环境划分（dev/test/prod）
        health-check-enabled: true # 开启健康检查，Nacos 会定期检测服务状态
      config:
        server-addr: ${spring.cloud.nacos.discovery.server-addr} # 配置中心地址，与注册中心一致
        file-extension: yaml # 配置文件格式
        group: DEFAULT_GROUP # 配置分组，默认DEFAULT_GROUP
  profiles:
    active: dev # 激活环境

# 服务端口（多实例部署时修改端口，如8081、8082）
server:
  port: 8081

# 健康检查端点配置（暴露所有端点，生产可按需调整）
management:
  endpoints:
    web:
      exposure:
        include: '*'
  endpoint:
    health:
      show-details: always
2.2.3 启动类与业务接口
java 复制代码 
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

// 开启服务注册发现（Spring Cloud 2022.x 可省略，默认自动开启）
@EnableDiscoveryClient
@SpringBootApplication
@RestController
public class NacosProviderApplication {

    public static void main(String[] args) {
        SpringApplication.run(NacosProviderApplication.class, args);
    }

    // 测试接口，返回服务端口与参数，用于验证负载均衡
    @GetMapping("/provider/hello/{name}")
    public String hello(@PathVariable String name) {
        // 获取当前服务端口
        String port = System.getProperty("server.port");
        return String.format("Hello %s! From provider (port: %s)", name, port);
    }
}

2.3 服务消费者（nacos-consumer）

通过 OpenFeign 调用提供者接口，依托 Nacos 实现服务发现与负载均衡。

2.3.1 子工程 POM 依赖

在父工程依赖基础上，增加 OpenFeign 依赖：

Java 复制代码 
<dependencies>
    <!-- 同 provider 依赖（web、nacos-discovery、nacos-config、actuator） -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
    </dependency>
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
    <!-- OpenFeign 服务调用 -->
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-openfeign</artifactId>
    </dependency>
    <!-- 负载均衡（Spring Cloud LoadBalancer，默认集成） -->
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-loadbalancer</artifactId>
    </dependency>
</dependencies>
2.3.2 配置文件（bootstrap.yml）
yaml 复制代码 
spring:
  application:
    name: nacos-consumer # 消费者服务名
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
        namespace: public
        health-check-enabled: true
      config:
        server-addr: ${spring.cloud.nacos.discovery.server-addr}
        file-extension: yaml
  profiles:
    active: dev

server:
  port: 8083 # 消费者端口，避免与提供者冲突

management:
  endpoints:
    web:
      exposure:
        include: '*'
  endpoint:
    health:
      show-details: always
2.3.3 启动类与 Feign 客户端
java 复制代码 
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.openfeign.EnableFeignClients;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

// 开启 Feign 客户端扫描
@EnableFeignClients
@SpringBootApplication
@RestController
public class NacosConsumerApplication {

    public static void main(String[] args) {
        SpringApplication.run(NacosConsumerApplication.class, args);
    }

    // 注入 Feign 客户端
    private final ProviderFeignClient providerFeignClient;

    public NacosConsumerApplication(ProviderFeignClient providerFeignClient) {
        this.providerFeignClient = providerFeignClient;
    }

    // 消费者接口，转发请求到提供者
    @GetMapping("/consumer/hello/{name}")
    public String hello(@PathVariable String name) {
        // 调用提供者接口
        return providerFeignClient.hello(name);
    }

    // Feign 客户端，对应提供者服务
    @org.springframework.cloud.openfeign.FeignClient(name = "nacos-provider") // 目标服务名
    public interface ProviderFeignClient {
        // 与提供者接口签名一致
        @GetMapping("/provider/hello/{name}")
        String hello(@PathVariable("name") String name);
    }
}

2.4 API 网关（spring-cloud-gateway）

基于 Spring Cloud Gateway 实现路由转发、统一入口，对接 Nacos 感知服务列表。

2.4.1 子工程 POM 依赖

Gateway 基于 WebFlux，禁止引入 spring-boot-starter-web（会冲突）：

xml 复制代码 
<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>
    <!-- Nacos 配置中心 -->
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
    </dependency>
    <!-- 负载均衡（适配 Gateway） -->
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-loadbalancer</artifactId>
    </dependency>
    <!-- 健康检查 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
</dependencies>
2.4.2 配置文件（bootstrap.yml）
yaml 复制代码 
spring:
  application:
    name: spring-cloud-gateway # 网关服务名
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
        namespace: public
        health-check-enabled: true
      config:
        server-addr: ${spring.cloud.nacos.discovery.server-addr}
        file-extension: yaml
    gateway:
      # 启用服务发现路由（自动适配 Nacos 中的服务）
      discovery:
        locator:
          enabled: true # 开启基于服务名的路由转发
          lower-case-service-id: true # 服务名转为小写（默认大写，与配置一致）
      # 自定义路由规则（优先级高于服务发现路由）
      routes:
        # 路由1：转发到提供者服务
        - id: provider-route # 路由唯一标识
          uri: lb://nacos-provider # lb 表示负载均衡，目标服务名
          predicates: # 路由断言（满足条件转发）
            - Path=/api/provider/** # 匹配路径
          filters: # 路由过滤器（修改请求/响应）
            - StripPrefix=1 # 移除路径前缀（/api/provider/hello → /provider/hello）
        # 路由2：转发到消费者服务
        - id: consumer-route
          uri: lb://nacos-consumer
          predicates:
            - Path=/api/consumer/**
          filters:
            - StripPrefix=1
  profiles:
    active: dev

server:
  port: 8080 # 网关端口，作为客户端统一入口

management:
  endpoints:
    web:
      exposure:
        include: '*'
  endpoint:
    health:
      show-details: always
2.4.3 启动类
java 复制代码 
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;

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

三、系统架构流程图

以下为客户端、网关、Nacos、微服务之间的完整交互流程，使用 Mermaid 语法绘制：
HTTP请求
1.服务列表查询
2.返回可用服务实例
3.负载均衡转发请求
3.负载均衡转发请求
3.负载均衡转发请求
4.调用提供者接口（Feign）
4.调用提供者接口（Feign）
5.推送配置（热更新）
5.推送配置（热更新）
5.推送配置（热更新）
5.推送配置（热更新）
6.健康状态上报
6.健康状态上报
6.健康状态上报
6.健康状态上报
客户端
Spring Cloud Gateway
Nacos 注册中心
nacos-provider 实例1
nacos-provider 实例2
nacos-consumer
Nacos 配置中心

流程图说明：

  • 客户端所有请求通过网关进入系统，网关作为统一入口；

  • 网关从 Nacos 获取服务实例列表，通过负载均衡算法转发请求；

  • Nacos 同时承担注册中心（服务上下线管理）和配置中心（配置热更新）角色；

  • 所有服务定期向 Nacos 上报健康状态，Nacos 剔除异常实例，保证服务可用性。

四、功能验证

4.1 启动顺序

Nacos → nacos-provider（多实例可修改端口启动多个）→ nacos-consumer → spring-cloud-gateway

4.2 接口测试

  1. 直接调用提供者接口：http://localhost:8081/provider/hello/Java，返回：Hello Java! From provider (port: 8081)。

  2. 通过消费者调用：http://localhost:8083/consumer/hello/Java，返回同上（转发到提供者）。

  3. 通过网关调用提供者：http://localhost:8080/api/provider/hello/Java，返回同上（网关转发）。

  4. 通过网关调用消费者：http://localhost:8080/api/consumer/hello/Java，返回同上（网关→消费者→提供者）。

  5. 负载均衡验证：启动 8081、8082 两个提供者实例，多次访问网关接口，端口会交替显示 8081 和 8082。

五、生产级注意事项

5.1 健康检查优化

默认健康检查依赖心跳，生产环境建议结合业务健康检查：

  • 自定义健康检查接口，继承 HealthIndicator，检查数据库、缓存等核心依赖是否可用。

  • 调整 Nacos 健康检查间隔：spring.cloud.nacos.discovery.heart-beat-interval=5000（心跳间隔5秒），heart-beat-timeout=15000（超时时间15秒）。

5.2 配置热更新

Nacos 支持配置热更新，无需重启服务，生产使用需注意：

  • 在需要热更新的配置类上添加@RefreshScope 注解。

  • 敏感配置（如数据库密码）建议使用 Nacos 加密功能，配置 spring.cloud.nacos.config.encrypt.enabled=true。

  • 按环境、分组划分配置，避免配置混乱（如 dev 环境命名空间、业务分组）。

5.3 跨服务认证上下文传递

微服务间调用需传递用户Token、请求ID等上下文，实现方式：

  1. Gateway 拦截请求，提取 Token 放入请求头，通过过滤器传递。

  2. Feign 调用时通过 RequestInterceptor 拦截请求，复制上下文信息到 Feign 请求头。

    import feign.RequestInterceptor;
    import feign.RequestTemplate;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.context.request.RequestContextHolder;
    import org.springframework.web.context.request.ServletRequestAttributes;

    import javax.servlet.http.HttpServletRequest;
    import java.util.Enumeration;

    @Configuration
    public class FeignConfig {
    @Bean
    public RequestInterceptor requestInterceptor() {
    return template -> {
    // 获取当前请求上下文
    ServletRequestAttributes attributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
    if (attributes != null) {
    HttpServletRequest request = attributes.getRequest();
    // 复制所有请求头（或指定Token、TraceId等）
    Enumeration<String> headerNames = request.getHeaderNames();
    while (headerNames.hasMoreElements()) {
    String headerName = headerNames.nextElement();
    String headerValue = request.getHeader(headerName);
    template.header(headerName, headerValue);
    }
    }
    };
    }
    }

5.4 网关优化

  • 限流熔断：集成 Sentinel 或 Resilience4j，防止服务雪崩（如网关对高频接口限流）。

  • 日志追踪：集成 Sleuth + Zipkin，实现全链路日志追踪，便于问题排查。

  • SSL 配置：网关层统一配置 SSL，对外提供 HTTPS 访问，内部服务使用 HTTP 减少开销。

5.5 Nacos 生产部署

  • 集群部署：至少3个节点，避免单点故障，配置 MySQL 持久化数据。

  • 权限控制：开启 Nacos 权限认证，创建不同角色账号（如开发、测试、生产），限制配置读写权限。

  • 监控告警：集成 Prometheus + Grafana，监控 Nacos 服务状态、配置变更、服务上下线情况。

六、总结

本文基于 Spring Boot 3.x + Spring Cloud 2022.x + Nacos 2.x 技术栈，完成了微服务全链路搭建，涵盖服务注册发现、网关路由、负载均衡、配置管理等核心功能。通过实战案例验证了架构可用性，并补充了生产级优化要点。实际项目中可在此基础上扩展限流、熔断、分布式事务等高级功能，结合业务场景迭代优化架构。

📕个人领域 ：Linux/C++/java/AI

🚀 个人主页 ：有点流鼻涕 · CSDN

💬 座右铭 ： "向光而行，沐光而生。"

相关推荐
十六年开源服务商2 小时前
WordPress多语言支持系统搭建指南
java·大数据·数据库
可爱又迷人的反派角色“yang”2 小时前
k8s（七）
java·linux·运维·docker·云原生·容器·kubernetes
填满你的记忆2 小时前
【从零开始——Redis 进化日志|Day6】缓存的三剑客：穿透、击穿、雪崩，到底怎么防？（附生产级代码实战）
java·数据库·redis·缓存·面试
侧耳4292 小时前
android9_box hdmi铺不满的问题
android·java
Allen_LVyingbo2 小时前
多智能体协作驱动的多模态医疗大模型系统：RAG–KAG双路径知识增强与架构的设计与验证（下）
人工智能·算法·架构·系统架构·知识图谱·健康医疗
风象南2 小时前
像 ChatGPT 一样丝滑：Spring Boot 如何实现大模型流式（Streaming）响应？
java·spring boot·后端
jiaguangqingpanda2 小时前
Day23-20260119
java·开发语言
Java程序员威哥2 小时前
Spring Boot 3.x 云原生终极适配：GraalVM 原生镜像构建 + Serverless 生产级部署（完整实战+最优模板）
java·开发语言·spring boot·后端·云原生·serverless·maven
黛玉晴雯子0012 小时前
Kubernets-Helm&发布模式（持续更新）
java·开发语言
热门推荐
01GitHub 镜像站点022025 Telegram 最新免费社工库机器人（LetsTG可[特殊字符]）搭建指南（含 Python 脚本）03OpenCode 入门教程：介绍 · 安装 · 配置第三方 API (如 Claude)04Linux下V2Ray安装配置指南05安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）06UV安装并设置国内源07BongoCat - 跨平台键盘猫动画工具08网站改了域名，如何查找？09Claude Code Skills 实用使用手册10AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南