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

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

[从零搭建 Spring Cloud 微服务项目：注册中心 + 网关 + 配置中心全流程](#从零搭建 Spring Cloud 微服务项目：注册中心 + 网关 + 配置中心全流程)
一、项目整体架构说明
二、技术选型
三、分步搭建流程
- [3.1 创建父工程与子模块结构](#3.1 创建父工程与子模块结构)
- - [3.1.1 创建父工程（spring-cloud-demo）](#3.1.1 创建父工程（spring-cloud-demo）)
  - [3.1.2 创建子模块](#3.1.2 创建子模块)
- [3.2 搭建 Nacos 注册中心](#3.2 搭建 Nacos 注册中心)
- - [3.2.1 下载与启动 Nacos](#3.2.1 下载与启动 Nacos)
  - [3.2.2 Nacos 基础配置（可选）](#3.2.2 Nacos 基础配置（可选）)
- [3.3 创建服务提供者并注册到 Nacos](#3.3 创建服务提供者并注册到 Nacos)
- - [3.3.1 引入依赖](#3.3.1 引入依赖)
  - [3.3.2 配置 application.yml](#3.3.2 配置 application.yml)
  - [3.3.3 编写主启动类](#3.3.3 编写主启动类)
  - [3.3.4 编写测试接口](#3.3.4 编写测试接口)
  - [3.3.5 验证服务注册](#3.3.5 验证服务注册)
- [3.4 搭建 Spring Cloud Gateway 网关](#3.4 搭建 Spring Cloud Gateway 网关)
- - [3.4.1 引入依赖](#3.4.1 引入依赖)
  - [3.4.2 配置 application.yml](#3.4.2 配置 application.yml)
  - [3.4.3 编写主启动类](#3.4.3 编写主启动类)
  - [3.4.4 验证网关路由](#3.4.4 验证网关路由)
- [3.5 集成 Nacos 配置中心](#3.5 集成 Nacos 配置中心)
- - [3.5.1 引入依赖](#3.5.1 引入依赖)
  - [3.5.2 创建 bootstrap.yml](#3.5.2 创建 bootstrap.yml)
  - [3.5.3 在 Nacos 控制台创建配置](#3.5.3 在 Nacos 控制台创建配置)
- [3.6 用 @RefreshScope 实现配置热更新](#3.6 用 @RefreshScope 实现配置热更新)
- - [3.6.1 改造 HelloController](#3.6.1 改造 HelloController)
  - [3.6.2 验证热更新](#3.6.2 验证热更新)
四、系统交互流程图
五、验证与测试建议
- [5.1 组件启动顺序](#5.1 组件启动顺序)
- [5.2 功能验证清单](#5.2 功能验证清单)
- [5.3 常见问题排查](#5.3 常见问题排查)
六、总结

本文面向具备 Java 基础与 Spring Boot 实战经验的开发者，以 Spring Cloud Alibaba 生态为核心，从零搭建包含注册中心、API 网关、配置中心的微服务项目，全程附带可运行代码与实操说明，读者可边读边动手实现。

一、项目整体架构说明

微服务架构中，注册中心、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 版本需严格适配，本文选用的组合经过实测稳定，避免版本冲突导致的异常。

三、分步搭建流程

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

采用 Maven 多模块结构，父工程统一管理依赖版本，子模块按功能拆分，便于维护与扩展。

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

通过 IDEA 创建 Maven 项目，打包方式设为 pom。
修改 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> <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> <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> <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>`

3.1.2 创建子模块

基于父工程创建 3 个子模块，分别对应服务提供者、网关、配置客户端（服务提供者可复用为配置客户端）：

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

创建方式：右键父工程 → New → Module → 选择 Maven，依次创建上述模块，无需额外勾选骨架。

3.2 搭建 Nacos 注册中心

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

3.2.1 下载与启动 Nacos

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

3.2.2 Nacos 基础配置（可选）

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

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

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

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

3.3.1 引入依赖

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

xml 复制代码

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

3.3.2 配置 application.yml

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

yaml 复制代码

server:
  port: 8081 # 服务端口

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

3.3.3 编写主启动类

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

java 复制代码

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);
    }
}

3.3.4 编写测试接口

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

java 复制代码

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.";
    }
}

3.3.5 验证服务注册

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

3.4 搭建 Spring Cloud Gateway 网关

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

3.4.1 引入依赖

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

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

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

3.4.2 配置 application.yml

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

yaml 复制代码

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）

3.4.3 编写主启动类

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

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);
    }
}

3.4.4 验证网关路由

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

3.5 集成 Nacos 配置中心

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

3.5.1 引入依赖

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

xml 复制代码

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

3.5.2 创建 bootstrap.yml

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

yaml 复制代码

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。

3.5.3 在 Nacos 控制台创建配置

登录 Nacos 控制台 → 配置管理 → 配置列表 → 点击"+"新增配置。
填写配置信息：
- Data ID：service-provider-dev.yaml
- Group：DEFAULT_GROUP
- 配置格式：YAML
- 配置内容（示例：自定义问候语前缀）：
  custom: greeting: "Hi" # 自定义配置项
点击"发布"，完成配置创建。

3.6 用 @RefreshScope 实现配置热更新

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

3.6.1 改造 HelloController

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

java 复制代码

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.";
    }
}

3.6.2 验证热更新

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

四、系统交互流程图

以下为 Mermaid 格式流程图，展示客户端、网关、服务提供者与 Nacos 的注册、配置加载及请求调用全流程：
1.请求
2.获取服务列表
3.返回服务实例
4.路由转发（负载均衡）
5.启动时注册服务
6.加载配置
7.返回配置信息
8.修改配置
9.推送配置变更
10.热更新配置
11.返回响应
12.返回响应
客户端
Spring Cloud Gateway
Nacos 注册中心
Service Provider
Nacos 配置中心
Nacos 控制台

流程图说明：

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

五、验证与测试建议

5.1 组件启动顺序

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

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

5.2 功能验证清单

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

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