Spring Cloud 微服务项目搭建：注册中心、网关与配置中心全流程

2.1.2 创建子模块

基于父工程创建 3 个子模块：

1. service-provider：服务提供者，提供具体业务接口。
2. gateway-server：API 网关，负责路由与拦截。
3. （可选）service-consumer：服务消费者，本文可通过网关直接测试服务提供者，暂不单独创建。

创建方式：右键父工程 → New → Module → 选择 Maven，依次创建上述模块。

2.2 搭建 Nacos 注册中心

Nacos 是阿里开源的一站式服务发现与配置管理平台，支持单机与集群部署，本文采用单机模式用于开发测试。

2.2.1 下载与启动 Nacos

1. 下载 Nacos：从 Nacos 官网 下载稳定版本（本文选用 2.2.3 版本），选择 zip 包（Windows）或 tar.gz 包（Linux/Mac）。
2. 启动 Nacos：
   • Windows：解压后进入 bin 目录，双击 startup.cmd（默认单机模式）。
   • Linux/Mac：解压后执行命令 sh startup.sh -m standalone（指定单机模式）。
3. 验证启动：访问 http://localhost:8848/nacos，默认账号密码均为 nacos，登录成功即启动正常。

2.2.2 Nacos 基础配置（可选）

单机模式下无需额外配置，若需修改端口、数据库等，可编辑 conf/application.properties 文件：

# 修改 Nacos 端口，默认 8848
server.port=8848
# 单机模式下使用嵌入式数据库，集群模式需配置 MySQL
spring.datasource.platform=mysql
# 集群模式下 MySQL 配置（单机可忽略）
db.num=1
db.url.0=jdbc:mysql://localhost:3306/nacos?useUnicode=true&characterEncoding=utf8&useSSL=false
db.user.0=root
db.password.0=123456

2.3 创建服务提供者并注册到 Nacos

开发 service-provider 模块，实现基础接口并注册到 Nacos。

2.3.1 引入依赖

修改 service-provider/pom.xml，添加 Nacos 服务发现依赖：

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

2.3.2 配置 application.yml

在 src/main/resources 下创建 application.yml，配置服务信息与 Nacos 地址：

server:
  port: 8081
spring:
  application:
    name: service-provider # 服务名，网关路由与注册中心识别依赖此名称
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848 # Nacos 注册中心地址
        username: nacos # Nacos 登录账号
        password: nacos # Nacos 登录密码

2.3.3 编写主启动类

创建 com.example.provider.ProviderApplication.java，添加 @EnableDiscoveryClient 注解开启服务注册与发现：

package com.example.provider;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;

@SpringBootApplication
@EnableDiscoveryClient // 开启服务注册与发现（Spring Cloud Alibaba 可省略，默认开启）
public class ProviderApplication {
    public static void main(String[] args) {
        SpringApplication.run(ProviderApplication.class, args);
    }
}

2.3.4 编写测试接口

创建 com.example.provider.controller.HelloController.java，提供简单的 GET 接口：

package com.example.provider.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {
    // 测试接口：根据传入的姓名返回问候语
    @GetMapping("/hello/{name}")
    public String hello(@PathVariable String name) {
        return "Hello " + name + "! This is service-provider response.";
    }
}

2.3.5 验证服务注册

1. 启动 ProviderApplication。
2. 登录 Nacos 控制台 → 服务管理 → 服务列表，可看到 service-provider 服务已注册，健康状态为 UP。

2.4 搭建 Spring Cloud Gateway 网关

开发 gateway-server 模块，实现路由转发功能，对接 Nacos 注册中心获取服务列表。

2.4.1 引入依赖

修改 gateway-server/pom.xml，添加网关与 Nacos 依赖：

<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>
</dependencies>

注意：Gateway 基于 WebFlux 实现，不可引入 spring-boot-starter-web 依赖，否则会冲突。

2.4.2 配置 application.yml

创建 application.yml，配置网关端口、Nacos 地址与路由规则：

server:
  port: 8080 # 网关端口，客户端统一访问此端口
spring:
  application:
    name: gateway-server # 网关服务名
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848 # Nacos 注册中心地址
        username: nacos
        password: nacos
    gateway:
      discovery:
        locator:
          enabled: true # 开启服务发现自动路由（根据服务名转发）
          lower-case-service-id: true # 服务名转为小写（默认大写，需与服务提供者名称一致）
      routes:
        - id: service-provider-route # 路由 ID，唯一即可
          uri: lb://service-provider # 目标服务地址，lb:// 表示负载均衡
          predicates:
            - Path=/provider/** # 路由匹配规则：访问 /provider/** 路径转发至 service-provider
          filters:
            - StripPrefix=1 # 过滤规则：去掉路径前缀 /provider（如 /provider/hello/xxx → /hello/xxx）

2.4.3 编写主启动类

创建 com.example.gateway.GatewayApplication.java：

package com.example.gateway;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;

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

2.4.4 验证网关路由

1. 启动 GatewayApplication（确保 Nacos 与 service-provider 已启动）。
2. 测试接口：
   • 通过自定义路由访问：http://localhost:8080/provider/hello/Java
   • 通过自动路由访问：http://localhost:8080/service-provider/hello/Java
3. 若返回 Hello Java! This is service-provider response.，说明网关路由生效。

2.5 集成 Nacos 配置中心

基于 service-provider 模块集成 Nacos 配置中心，实现配置集中管理与动态更新。

2.5.1 引入依赖

修改 service-provider/pom.xml，添加 Nacos 配置中心依赖：

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>

2.5.2 创建 bootstrap.yml

Nacos 配置中心的配置需在 bootstrap.yml 中加载（优先级高于 application.yml），创建 src/main/resources/bootstrap.yml：

spring:
  application:
    name: service-provider # 服务名，与 Nacos 配置文件前缀对应
  cloud:
    nacos:
      config:
        server-addr: localhost:8848 # Nacos 配置中心地址
        username: nacos
        password: nacos
        file-extension: yaml # 配置文件格式（yaml 或 properties）
        group: DEFAULT_GROUP # 配置分组，默认 DEFAULT_GROUP
        namespace: # 命名空间，默认 public（用于环境隔离，可选）
        profiles:
          active: dev # 激活环境，对应 Nacos 配置文件后缀

配置说明：Nacos 配置文件命名规则为 ${spring.application.name}-${spring.profiles.active}.${file-extension}，本文对应 service-provider-dev.yaml。

2.5.3 在 Nacos 控制台创建配置

1. 登录 Nacos 控制台 → 配置管理 → 配置列表 → 点击'+'新增配置。
2. 填写配置信息：
   • Data ID：service-provider-dev.yaml
   • Group：DEFAULT_GROUP
   • 配置格式：YAML
   • 配置内容（示例：自定义问候语前缀）：

     custom:
       greeting: "Hi" # 自定义配置项
     

3. 点击'发布'，完成配置创建。

2.6 用 @RefreshScope 实现配置热更新

通过 @RefreshScope 注解，使服务在不重启的情况下感知配置变更，更新接口逻辑引用新配置。

2.6.1 改造 HelloController

注入 Nacos 配置项，添加 @RefreshScope 注解：

package com.example.provider.controller;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RefreshScope // 开启配置热更新
public class HelloController {
    // 注入 Nacos 中的配置项
    @Value("${custom.greeting:Hello}") // 冒号后为默认值，配置未加载时使用
    private String greeting;

    @GetMapping("/hello/{name}")
    public String hello(@PathVariable String name) {
        // 使用配置项拼接返回结果
        return greeting + " " + name + "! This is service-provider response.";
    }
}

2.6.2 验证热更新

1. 重启 service-provider（首次加载 Nacos 配置需重启）。
2. 访问接口 http://localhost:8081/hello/Java，返回 Hi Java! This is service-provider response.，说明配置加载成功。
3. 在 Nacos 控制台修改配置：将 custom.greeting 改为 Welcome，点击'发布'。
4. 再次访问接口，返回 Welcome Java! This is service-provider response.，无需重启服务，配置已动态更新。

三、系统交互流程图

以下为 Mermaid 格式流程图，展示客户端、网关、服务提供者与 Nacos 的注册、配置加载及请求调用全流程：

graph TD
    Client[客户端] -->|1.请求 | Gateway[Spring Cloud Gateway]
    Gateway -->|2.获取服务列表 | NacosReg[Nacos 注册中心]
    NacosReg -->|3.返回服务实例 | Gateway
    Gateway -->|4.路由转发 | Provider[Service Provider]
    Provider -->|11.返回响应 | Gateway
    Gateway -->|12.返回响应 | Client
    Provider -->|5.启动时注册服务 | NacosReg
    Provider -->|6.加载配置 | NacosConfig[Nacos 配置中心]
    NacosConfig -->|7.返回配置信息 | Provider
    Console[Nacos 控制台] -->|8.修改配置 | NacosConfig
    NacosConfig -->|9.推送配置变更 | Provider
    Provider -->|10.热更新配置 | Provider

流程图说明：

• 注册流程：服务提供者启动后向 Nacos 注册中心登记自身信息。
• 配置流程：服务提供者启动时从 Nacos 配置中心拉取配置，配置变更时 Nacos 主动推送更新。
• 调用流程：客户端请求经网关转发，网关从注册中心获取服务地址，实现动态路由与负载均衡。

四、验证与测试建议

4.1 组件启动顺序

需按以下顺序启动组件，避免依赖缺失导致异常：

1. Nacos 服务（注册中心 + 配置中心）。
2. 服务提供者（service-provider）。
3. 网关服务（gateway-server）。

4.2 功能验证清单

1. 服务注册验证：Nacos 控制台 → 服务列表，确认 service-provider、gateway-server 均为 UP 状态。
2. 网关路由验证：通过网关访问服务接口，验证路由转发与负载均衡（可启动多个 service-provider 实例测试）。
3. 配置加载验证：服务启动后，访问接口确认 Nacos 配置项已生效。
4. 配置热更新验证：修改 Nacos 配置并发布，无需重启服务，访问接口确认配置已更新。

4.3 常见问题排查

• 服务注册失败：检查 Nacos 地址、账号密码是否正确，服务名是否一致，防火墙是否放行 8848 端口。
• 网关路由失败：检查 Gateway 依赖是否冲突（无 spring-boot-starter-web），路由规则是否正确，服务是否已注册到 Nacos。
• 配置加载失败：检查 bootstrap.yml 配置是否正确，Nacos 中 Data ID、Group 是否与配置一致，配置文件格式是否正确。
• 热更新失效：确保类上添加了 @RefreshScope 注解，配置项注入方式为 @Value 或 @ConfigurationProperties。

五、总结

本文基于 Spring Cloud Alibaba 生态，完成了微服务三大核心组件的搭建与集成，涵盖 Nacos 注册中心/配置中心、Spring Cloud Gateway 网关的核心功能实现。通过本文实操，读者可掌握微服务项目的基础搭建流程，理解服务注册与发现、配置集中管理、网关路由等核心概念。

后续可基于此架构扩展，如集成 Sentinel 实现流量控制、Seata 实现分布式事务、OpenFeign 实现服务调用等，构建更完整的微服务体系。