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

Spring Cloud 是构建微服务架构的标准框架，2025-2026 年主流版本基于 Spring Boot 3.x（兼容 Java 21+），强调零信任、分布式配置和动态路由。本教程从零开始，搭建一个包含Eureka 注册中心（服务发现）、Spring Cloud Gateway 网关（路由/负载/限流）和Spring Cloud Config 配置中心（统一配置管理）的微服务项目。

目标：运行后，你能看到服务注册、动态路由和配置拉取的全流程。假设你有 Java/Maven 基础，项目用 Spring Boot 3.3+ 和 Spring Cloud 2023.0.3（最新稳定版）。

第一步：环境准备（10 分钟）

安装 JDK 21+：从 Oracle 或 Adoptium 下载。
Maven 3.9+：配置好仓库（阿里云镜像推荐）。
IDE：IntelliJ IDEA 或 VS Code（Spring Boot 插件）。
依赖版本（pom.xml 中的版本管理）：

   <properties>
       <java.version>21</java.version>
       <spring-boot.version>3.3.0</spring-boot.version>
       <spring-cloud.version>2023.0.3</spring-cloud.version>
   </properties>
   <dependencyManagement>
       <dependencies>
           <dependency>
               <groupId>org.springframework.boot</groupId>
               <artifactId>spring-boot-dependencies</artifactId>
               <version>${spring-boot.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>

项目结构（多模块 Maven 项目）：

microservices-demo
├── eureka-server             ← 注册中心
├── config-server             ← 配置中心
├── api-gateway               ← 网关
├── user-service              ← 示例微服务1
├── order-service             ← 示例微服务2
└── pom.xml                   ← 父 POM

第二步：搭建 Eureka 注册中心（服务发现）

Eureka 是 Netflix 的服务注册组件，支持高可用。

创建 eureka-server 子模块（Spring Initializr：添加 spring-cloud-starter-netflix-eureka-server）。
pom.xml：

   <dependencies>
       <dependency>
           <groupId>org.springframework.cloud</groupId>
           <artifactId>spring-cloud-starter-netflix-eureka-server</artifactId>
       </dependency>
   </dependencies>

application.yml：

   server:
     port: 8761

   spring:
     application:
       name: eureka-server

   eureka:
     client:
       register-with-eureka: false    # 不注册自己
       fetch-registry: false          # 不拉取注册表
       service-url:
         defaultZone: http://localhost:8761/eureka/
     ```

4. **主类**：

java
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.netflix.eureka.server.EnableEurekaServer;

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

5. **启动**：访问 http://localhost:8761，看到 Eureka 控制台。

#### 第三步：搭建示例微服务（user-service 和 order-service）

每个微服务都需要注册到 Eureka。

1. **创建 user-service 子模块**（添加 spring-boot-starter-web、spring-cloud-starter-netflix-eureka-client）。
2. **pom.xml**（类似 order-service）：

xml
org.springframework.boot spring-boot-starter-web org.springframework.cloud spring-cloud-starter-netflix-eureka-client org.springframework.cloud spring-cloud-starter-config # 后续接入配置中心

3. **application.yml**：

yaml
server:
port: 8081 # order-service 用 8082

spring:
application:
name: user-service

eureka:
client:
service-url:
defaultZone: http://localhost:8761/eureka/

4. **主类**：

java
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.netflix.eureka.EnableEurekaClient;

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

5. **添加一个简单 Controller**（测试用）：

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

@RestController
public class UserController {
@GetMapping(“/users”)
public String getUsers() {
return “User List from user-service”;
}
}

6. **启动**：在 Eureka 控制台看到 user-service 和 order-service 已注册。

#### 第四步：搭建 Spring Cloud Config 配置中心

Config Server 支持 Git/Nacos 等后端存储统一配置。

1. **创建 config-server 子模块**（添加 spring-cloud-config-server）。
2. **pom.xml**：

xml
org.springframework.cloud spring-cloud-config-server

3. **application.yml**（用本地文件存储为例，生产用 Git）：

yaml
server:
port: 8888

spring:
application:
name: config-server
cloud:
config:
server:
native:
search-locations: classpath:/config # 本地配置目录

4. **主类**：

java
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.config.server.EnableConfigServer;

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

5. **添加配置文件**（resources/config/user-service.yml）：

yaml
message: “Hello from Config Server!”

6. **接入微服务**：在 user-service 的 bootstrap.yml（优先级更高）：

yaml
spring:
cloud:
config:
uri: http://localhost:8888

7. **测试**：在 user-service Controller 用 @Value("${message}") String msg; 输出配置值。

#### 第五步：搭建 Spring Cloud Gateway 网关

Gateway 基于 Reactor，支持动态路由。

1. **创建 api-gateway 子模块**（添加 spring-cloud-starter-gateway、spring-cloud-starter-netflix-eureka-client）。
2. **pom.xml**：

xml
org.springframework.cloud spring-cloud-starter-gateway org.springframework.cloud spring-cloud-starter-netflix-eureka-client

3. **application.yml**：

yaml
server:
port: 8080

spring:
application:
name: api-gateway
cloud:
gateway:
discovery:
locator:
enabled: true # 启用 Eureka 发现
routes:
– id: user-route
uri: lb://user-service # lb: 表示负载均衡
predicates:
– Path=/users/**
– id: order-route
uri: lb://order-service
predicates:
– Path=/orders/**

eureka:
client:
service-url:
defaultZone: http://localhost:8761/eureka/

4. **主类**：

java
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.netflix.eureka.EnableEurekaClient;

@SpringBootApplication
@EnableEurekaClient
public class ApiGatewayApplication {
public static void main(String[] args) {
SpringApplication.run(ApiGatewayApplication.class, args);
}
}
“`

测试：访问 http://localhost:8080/users → 路由到 user-service:8081/users

第六步：整合与测试（全链路验证）

启动顺序：Eureka → Config Server → 微服务 → Gateway
验证注册：Eureka 控制台看到所有服务。
验证配置：微服务日志/接口输出 Config Server 的配置。
验证路由：通过 Gateway 访问微服务（负载均衡自动）。
高可用扩展：Eureka 集群（多节点 defaultZone 互指）；Gateway 加限流/熔断（Resilience4J）。

第七步：常见坑 & 优化（企业级经验）

问题	解决方案
Eureka 不注册	检查 @EnableEurekaClient 和 service-url
Config 拉取失败	用 bootstrap.yml；检查 uri
Gateway 路由 404	路径匹配（/** vs /*）；lb:// 拼写
配置刷新不生效	加 spring-cloud-starter-bus-amqp（消息总线）
性能瓶颈	用 Nacos 替换 Eureka（更现代）
安全	加 Spring Security + JWT

恭喜！你已搭建完整微服务链路。想深入（如 Nacos 替换、OpenFeign 调用、Resilience4J 熔断、Docker 部署）？直接告诉我，我再展开代码。

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