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

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

在微服务架构中，注册中心、API 网关和配置中心是三大核心基础设施。它们协同工作，保障微服务集群的有序运行。

• 注册中心：作为服务的'通讯录'，负责服务注册与发现。服务启动时主动登记自身信息（IP、端口等），消费者通过注册中心获取地址列表，避免硬编码。
• API 网关：作为集群'入口'，统一接收请求，承担路由转发、负载均衡、权限校验等功能。客户端只需访问网关，降低耦合度。
• 配置中心：作为'配置仓库'，集中管理所有服务的配置信息。支持动态更新，无需重启即可生效，解决分布式环境配置分散问题。

三者协作流程：服务启动时从配置中心拉取配置并向注册中心注册；客户端请求经网关路由，网关从注册中心获取实例列表进行转发；配置更新时，配置中心推送变更实现热更新。

一、技术选型

本项目采用 Spring Cloud Alibaba 生态，组件成熟且适配国内场景。

组件类型	选用组件	核心作用
注册中心	Nacos	服务注册、发现与健康检测
配置中心	Nacos	集中式配置管理与动态更新
API 网关	Spring Cloud Gateway	路由转发、负载均衡、过滤拦截
基础框架	Spring Boot 2.7.x + Spring Cloud Alibaba 2021.0.4.0	微服务基础依赖与版本适配

注：Spring Boot 与 Spring Cloud Alibaba 版本需严格适配，本文组合经过实测稳定。

二、分步搭建流程

2.1 创建父工程与子模块结构

采用 Maven 多模块结构，父工程统一管理依赖版本，子模块按功能拆分。

2.1.1 创建父工程（spring-cloud-demo）

1. 通过 IDEA 创建 Maven 项目，打包方式设为 pom。
2. 修改 pom.xml，统一管理依赖版本：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.15</version>
    <relativePath/>
</parent>
<groupId>com.example</groupId>
<artifactId>spring-cloud-demo</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>pom</packaging>
<name>spring-cloud-demo</name>
<!-- 统一管理版本号 -->
<properties>
    <java.version>1.8</java.version>
    <spring-cloud-alibaba.version>2021.0.4.0</spring-cloud-alibaba.version>
    <spring-cloud.version>2021.0.4</spring-cloud.version>
</properties>
<!-- 依赖管理，子模块可直接引用无需指定版本 -->
<dependencyManagement>
    <dependencies>
        <!-- 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>
        <!-- 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>
    </dependencies>
</dependencyManagement>
<dependencies>
    <!-- Spring Boot 基础依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- 测试依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

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 实现服务调用等，构建更完整的微服务体系。