Spring Cloud 从零开始：微服务入门指南

开篇：Spring Cloud 是什么，用来做什么？

你可能听说过“微服务”这个词，它是现代后端开发中非常流行的一种架构风格。在传统的单体应用中，所有功能都集中在一个项目里，随着业务增长，代码越来越复杂，维护也变得困难。

而 微服务（Microservices） 就是把一个大系统拆分成多个独立的小系统，每个小系统负责一个具体的功能模块。比如电商系统可以分为用户管理、订单处理、商品库存等多个微服务。

Spring Cloud 是一套构建微服务的工具集，它基于我们熟悉的 Spring Boot 框架，提供了一系列开箱即用的组件，例如：

• 注册中心（Eureka、Nacos）
• 负载均衡（Ribbon）
• 网关（Gateway 或 Zuul）
• 配置中心（Config）
• 分布式链路追踪（Sleuth + Zipkin）
• 熔断器（Hystrix）

有了这些组件，你就能轻松地搭建起一套高效的微服务系统。这篇教程将带你从零开始，一步一步完成一个简单的 Spring Cloud 微服务项目。

---

环境准备：开发环境搭建步骤

所需工具清单：

工具	版本	官网
Java	17+	https://www.oracle.com/java/technologies/javase-downloads.html
Maven	3.8+	https://maven.apache.org/download.cgi
IntelliJ IDEA	2021.3+	https://www.jetbrains.com/idea/download/
Spring Initializr	在线	https://start.spring.io
Nacos（注册中心）	2.2.x	https://github.com/alibaba/nacos/releases

第一步：安装 Java 和 Maven

请确保你的电脑已经安装好 Java 17 及以上版本，并配置好 JAVA_HOME 环境变量。

然后下载 Maven 并解压到你喜欢的目录（例如 C:\Program Files\maven），设置 MAVEN_HOME 并添加 bin 目录到系统 PATH 中。

验证是否安装成功：

java -version
mvn -v

你应该看到类似输出。

第二步：安装 IntelliJ IDEA

推荐使用 IntelliJ IDEA Community Edition，这是一个功能强大的 IDE，非常适合 Java 开发。

安装完成后打开软件，准备好创建我们的第一个 Spring Boot 项目。

第三步：安装 Nacos（服务注册中心）

你可以下载 Nacos 的压缩包并解压。进入解压后的 bin 目录，运行如下命令启动 Nacos：

startup.cmd -m standalone   # Windows
sh startup.sh -m standalone # Linux/Mac

浏览器访问：http://localhost:8848/nacos，默认账号密码都是 nacos/nacos。

现在你的开发环境就准备好了！

---

核心概念：什么是微服务中的关键组件？

1. 服务注册与发现（Service Registry & Discovery）

想象一下你在小区里开了一家便利店，顾客要想知道这家店在哪，就得查地图或问人。在微服务中也是如此，其他服务要想找到这个服务的位置，就需要通过注册中心来查找。

常见的注册中心有 Eureka（Netflix 提供）、Consul、Zookeeper、以及我们今天要用的 Nacos。

通俗理解：

类似于电话簿或地图导航，告诉其他服务：“我在这里”。

---

2. 客户端负载均衡（Client-Side Load Balancing）

当某个功能被很多服务调用时，我们就需要让请求分发到多个实例上，避免单一节点过载。客户端负载均衡就是由调用方根据规则选择目标服务器。

常用的工具有 Ribbon 和 Spring Cloud LoadBalancer。

通俗理解：

像点外卖一样，同一个店铺可能会分配给你最近的不同门店。

---

3. API 网关（API Gateway）

所有的请求都先经过“网关”，再由网关转发给对应的服务。它还可以做权限校验、限流、日志记录等统一操作。

常见的网关有 Zuul（Netflix）和 Spring Cloud Gateway。

通俗理解：

类似于公司前台，所有来访者都要先经过他。

---

4. 配置中心（Configuration Center）

微服务部署到多个环境中（开发、测试、生产），每个环境下的配置不同。配置中心就可以集中管理这些配置信息。

常用的配置中心有 Spring Cloud Config、携程的 Apollo、阿里巴巴的 Nacos。

通俗理解：

类似于全局开关控制面板，哪里需要配哪里改。

---

5. 熔断机制（Circuit Breaker）

当某个服务不可用时，防止整个系统崩溃。熔断机制可以快速失败、自动恢复或切换备用方案。

常用库：Hystrix（已不维护）、Resilience4j。

通俗理解：

像家里的电路保险丝，在电压过高时断电保护设备。

---

实战项目：一步步完成一个简单 Spring Cloud 微服务系统

我们将构建一个最简化的系统结构：

• 用户服务（User Service）
• 商品服务（Product Service）
• 注册中心（Nacos）
• 网关（Gateway）

项目的结构如下图所示：

springcloud-demo/
├── user-service/
├── product-service/
├── gateway/
└── nacos-server/  （外部启动）

接下来我们依次创建这四个模块。

---

第一步：创建父工程 springcloud-demo（Maven）

新建一个空文件夹，比如叫做 springcloud-demo，在这个目录下创建一个 pom.xml 文件：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>springcloud-demo</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>

    <modules>
        <module>user-service</module>
        <module>product-service</module>
        <module>gateway</module>
    </modules>

    <properties>
        <java.version>17</java.version>
        <spring-cloud.version>2023.0.0</spring-cloud.version>
        <nacos.version>2.2.3</nacos.version>
    </properties>

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

</project>

这样我们就有了一个聚合项目的基础框架。

---

第二步：创建用户服务 user-service

使用 Spring Initializr 创建 Spring Boot 项目

访问官网：https://start.spring.io，填写如下参数：

• Project: Maven
• Language: Java
• Spring Boot Version: 最新稳定版（如 3.2）
• Group: com.example
• Artifact: user-service
• Dependencies:
  • Spring Web
  • Spring Cloud Alibaba Nacos Discovery

点击 Generate 下载 zip 包，解压后放在 springcloud-demo/user-service 路径下。

修改配置文件 application.yml

server:
  port: 8081

spring:
  application:
    name: user-service
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848

编写一个简单的 Controller

创建文件 src/main/java/com/example/userservice/controller/UserController.java

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping("/{id}")
    public String getUserById(@PathVariable Long id) {
        return "User ID: " + id;
    }
}

启动类 Application.java

确保自动生成的 Application 类上有以下注解：

@EnableDiscoveryClient // 启用服务注册发现
@SpringBootApplication
public class UserServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(UserServiceApplication.class, args);
    }
}

现在运行这个服务，你应该能在 Nacos 控制台看到名为 user-service 的服务注册成功。

---

第三步：创建商品服务 product-service

同样方式生成另一个 Spring Boot 项目：

• Project: Maven
• Artifact: product-service
• Dependencies: Spring Web, Spring Cloud Alibaba Nacos Discovery

修改 application.yml：

server:
  port: 8082

spring:
  application:
    name: product-service
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848

创建控制器：

@RestController
@RequestMapping("/products")
public class ProductController {

    @GetMapping("/{id}")
    public String getProductById(@PathVariable Long id) {
        return "Product ID: " + id;
    }
}

别忘了加上 @EnableDiscoveryClient 和启动类。

启动后你也应该在 Nacos 中看到 product-service 注册成功。

---

第四步：创建 API 网关 gateway

我们需要创建一个新的模块作为网关，它会接收所有请求，并将它们路由到正确的微服务。

使用 Spring Initializr 创建 gateway 项目

依赖项加入：

• Spring WebFlux
• Spring Cloud Gateway
• Spring Cloud Alibaba Nacos Discovery

注意：Spring Cloud Gateway 不能与 Spring MVC 共存，请选择合适的 starter。

application.yml：

server:
  port: 9000

spring:
  application:
    name: api-gateway
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
    gateway:
      routes:
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/users/**
          filters:
            - StripPrefix=1
        - id: product-service
          uri: lb://product-service
          predicates:
            - Path=/products/**
          filters:
            - StripPrefix=1

解释几个关键字：

• uri: 目标服务地址（lb 表示负载均衡访问）
• predicates: 匹配路径的条件
• filters: 请求前要处理的内容（StripPrefix 是去掉第一个路径层级）

创建启动类即可，无需 controller。

运行后访问：

• http://localhost:9000/users/1 → 返回 User ID: 1
• http://localhost:9000/products/1001 → 返回 Product ID: 1001

🎉 至此，我们的第一个 Spring Cloud 微服务系统就初步完成了！

---

常见问题：新手容易遇到的问题和解决方案

❓ Q1：我的服务注册不到 Nacos 怎么办？

• ✅ 确保 Nacos 服务正在运行。
• ✅ application.yml 中的 server-addr 是否正确？
• ✅ 服务名是否拼写错误？是否启用了 @EnableDiscoveryClient 注解？

❓ Q2：网关返回 404，但直接访问服务却没问题？

• ✅ 检查网关中的路径匹配规则。
• ✅ 路由是否启用了负载均衡（lb://）？
• ✅ 查看 Spring Cloud Gateway 日志是否有异常。

❓ Q3：IDEA 中运行多个模块冲突怎么办？

• 使用多窗口分别打开每个模块。
• 或者使用 Spring Boot 的 Run Dashboard 插件管理多个模块启动。
• 每个服务指定不同的端口号。

❓ Q4：为什么不用 Eureka，要用 Nacos？

• Nacos 支持服务注册与发现的同时，还支持配置中心功能。
• 社区活跃，中文文档友好。
• 更适合国内开发者使用。

---

学习建议：下一步的学习路径建议

恭喜你完成了这篇《Spring Cloud 从零开始》的入门教程！你现在应该已经掌握了：

• 如何搭建微服务的基础环境
• 如何使用 Nacos 做服务注册中心
• 如何通过 Spring Cloud Gateway 构建 API 网关
• 如何组织多个模块进行协作开发

接下来你可以学习进阶内容，比如：

1. 配置中心（Config Server / Nacos Config）
2. 服务熔断（Sentinel or Hystrix）
3. 分布式链路追踪（Sleuth + Zipkin）
4. 安全认证（Spring Security / OAuth2 / JWT）
5. 消息队列集成（RabbitMQ / Kafka / RocketMQ）

同时建议你：

• 多做实践练习，比如为网上商城添加订单服务
• 阅读官方文档：https://spring.io/projects/spring-cloud
• 参考开源项目，观察大型微服务是怎么搭建的

如果你喜欢动手写，不妨尝试自己设计一个电商系统的微服务架构图，再逐步实现。

---

继续加油吧！你已经踏上了通往高级后端工程师的大道 🚀