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

从零搭建 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 分钟）

1. 安装 JDK 21+：从 Oracle 或 Adoptium 下载。
2. Maven 3.9+：配置好仓库（阿里云镜像推荐）。
3. IDE：IntelliJ IDEA 或 VS Code（Spring Boot 插件）。
4. 依赖版本（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 的服务注册组件，支持高可用。

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

2. pom.xml：

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

3. application.yml：

   server:port:8761spring:application:name:eureka-servereureka:client:register-with-eureka:false# 不注册自己fetch-registry:false# 不拉取注册表service-url:defaultZone:http://localhost:8761/eureka/

4. 主类：

   importorg.springframework.boot.SpringApplication;importorg.springframework.boot.autoconfigure.SpringBootApplication;importorg.springframework.cloud.netflix.eureka.server.EnableEurekaServer;@SpringBootApplication@EnableEurekaServerpublicclassEurekaServerApplication{publicstaticvoidmain(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）：

   <dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-netflix-eureka-client</artifactId></dependency><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-config</artifactId># 后续接入配置中心</dependency></dependencies>

3. application.yml：

   server:port:8081# order-service 用 8082spring:application:name:user-serviceeureka:client:service-url:defaultZone:http://localhost:8761/eureka/

4. 主类：

   importorg.springframework.boot.SpringApplication;importorg.springframework.boot.autoconfigure.SpringBootApplication;importorg.springframework.cloud.netflix.eureka.EnableEurekaClient;@SpringBootApplication@EnableEurekaClientpublicclassUserServiceApplication{publicstaticvoidmain(String[]args){SpringApplication.run(UserServiceApplication.class,args);}}

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

   importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RestController;@RestControllerpublicclassUserController{@GetMapping("/users")publicStringgetUsers(){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：

   <dependencies><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-config-server</artifactId></dependency></dependencies>

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

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

4. 主类：

   importorg.springframework.boot.SpringApplication;importorg.springframework.boot.autoconfigure.SpringBootApplication;importorg.springframework.cloud.config.server.EnableConfigServer;@SpringBootApplication@EnableConfigServerpublicclassConfigServerApplication{publicstaticvoidmain(String[]args){SpringApplication.run(ConfigServerApplication.class,args);}}

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

   message:"Hello from Config Server!"

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

   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：

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

3. application.yml：

   server:port:8080spring:application:name:api-gatewaycloud:gateway:discovery:locator:enabled:true# 启用 Eureka 发现routes:-id:user-routeuri:lb://user-service# lb: 表示负载均衡predicates:-Path=/users/**-id:order-routeuri:lb://order-servicepredicates:-Path=/orders/**eureka:client:service-url:defaultZone:http://localhost:8761/eureka/

4. 主类：

   importorg.springframework.boot.SpringApplication;importorg.springframework.boot.autoconfigure.SpringBootApplication;importorg.springframework.cloud.netflix.eureka.EnableEurekaClient;@SpringBootApplication@EnableEurekaClientpublicclassApiGatewayApplication{publicstaticvoidmain(String[]args){SpringApplication.run(ApiGatewayApplication.class,args);}}

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

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

1. *启动顺序*：Eureka → Config Server → 微服务 → Gateway
2. 验证注册：Eureka 控制台看到所有服务。
3. 验证配置：微服务日志/接口输出 Config Server 的配置。
4. 验证路由：通过 Gateway 访问微服务（负载均衡自动）。
5. 高可用扩展：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 部署）？直接告诉我，我再展开代码。c