Spring Cloud Alibaba：从零搭建你的第一个微服务项目

大家好，我是掘金上经常写入门教程的全栈工程师。最近很多刚学完 Spring Boot 的小伙伴问我：“微服务到底怎么用？Spring Cloud Alibaba 到底是啥？有没有适合零基础的实战教程？”

我当初学的时候，也是一头雾水——文档太专业，视频讲得太快，连“注册中心”“配置中心”这些词都听不懂。所以今天，我就用最通俗的语言、最完整的步骤，带你从零开始，亲手搭建一个基于 Spring Cloud Alibaba 的微服务项目。

无论你是刚学完 Java 基础，还是只会写点前端页面，只要你愿意动手，这篇教程都能让你跑通第一个微服务！

---

一、Spring Cloud Alibaba 是什么？能干啥？

简单说：它是一套帮你轻松构建微服务系统的工具箱。

想象一下，你开发一个电商网站：

• 用户服务（管登录注册）
• 商品服务（管商品信息）
• 订单服务（管下单）

如果全写在一个项目里，代码会越来越臃肿，改一处可能崩全局。这时候，我们就把系统拆成多个“小服务”，每个服务独立运行、独立部署——这就是微服务架构。

但拆开后问题来了：

• 服务之间怎么互相发现？
• 配置文件怎么统一管理？
• 某个服务挂了怎么办？

Spring Cloud Alibaba 就是为了解决这些问题而生的！它集成了阿里巴巴开源的一系列中间件，比如：

• Nacos：做服务注册与发现 + 配置中心
• Sentinel：做流量控制和熔断降级
• Seata：处理分布式事务

📚 小贴士：如果你对微服务完全陌生，建议先看《Spring 微服务实战》这类书籍的前两章，建立基本概念。但别担心，本教程会手把手带你实操！

---

二、环境准备：5 分钟搭好开发环境

我们要用到以下工具，请提前安装：

工具	版本建议	作用
JDK	1.8 或 17	Java 运行环境
Maven	3.6+	项目依赖管理
IntelliJ IDEA	最新版	开发 IDE
Nacos Server	2.2.3	服务注册与配置中心

第一步：下载并启动 Nacos

1. 访问 Nacos GitHub Releases
2. 下载 nacos-server-2.2.3.zip
3. 解压后进入 bin 目录
4. Windows 用户：双击 startup.cmd -m standalone
   Mac/Linux 用户：终端执行 sh startup.sh -m standalone

💡 注意：-m standalone 表示以单机模式启动，适合本地开发。生产环境要用集群模式。

启动成功后，浏览器访问 http://localhost:8848/nacos，账号密码都是 nacos，看到登录页就说明 OK 了！

---

三、核心概念：用大白话讲清楚

1. 服务注册与发现

• 注册：每个微服务启动时，把自己的名字和地址告诉 Nacos。
• 发现：当 A 服务想调用 B 服务时，先问 Nacos：“B 在哪？” Nacos 返回地址，A 就能调用了。

就像你去公司前台登记（注册），别人想找你，就问前台你在哪个工位（发现）。

2. 配置中心

以前每个服务都有自己的 application.yml，改配置要重启服务。
现在把配置统一存在 Nacos 里，改完自动生效，不用重启！

3. 服务调用（Feign）

不用手动写 HTTP 请求，用接口 + 注解就能远程调用其他服务，像调本地方法一样简单。

---

四、实战：创建两个微服务并互相调用

我们来做一个超简单的例子：

• user-service：提供用户信息
• order-service：调用 user-service 获取用户信息

步骤 1：创建父工程（Maven 聚合项目）

在 IDEA 中新建一个空项目，命名为 sc-alibaba-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>sc-alibaba-demo</artifactId>
    <version>1.0</version>
    <packaging>pom</packaging>

    <modules>
        <module>user-service</module>
        <module>order-service</module>
    </modules>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.14</version>
        <relativePath/>
    </parent>

    <properties>
        <java.version>1.8</java.version>
        <spring-cloud.version>2021.0.8</spring-cloud.version>
        <spring-cloud-alibaba.version>2021.0.5.0</spring-cloud-alibaba.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>
            <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>
        </dependencies>
    </dependencyManagement>
</project>

步骤 2：创建 user-service

右键项目 → New → Module → Spring Initializr
选择：

• Dependencies: Spring Web, Nacos Discovery

创建完成后，修改 application.yml：

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

再写一个 Controller：

@RestController
public class UserController {
    @GetMapping("/user/{id}")
    public String getUser(@PathVariable String id) {
        return "User-" + id;
    }
}

步骤 3：创建 order-service

同样方式创建新模块，依赖选 Spring Web, Nacos Discovery, OpenFeign

application.yml：

server:
  port: 8082
spring:
  application:
    name: order-service
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848

定义 Feign 接口（远程调用 user-service）：

@FeignClient(name = "user-service")
public interface UserClient {
    @GetMapping("/user/{id}")
    String getUser(@PathVariable("id") String id);
}

再写 OrderController：

@RestController
public class OrderController {

    @Autowired
    private UserClient userClient;

    @GetMapping("/order/{userId}")
    public String createOrder(@PathVariable String userId) {
        String user = userClient.getUser(userId);
        return "Created order for " + user;
    }
}

最后，在主启动类加上 @EnableFeignClients：

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

步骤 4：启动并测试

1. 启动 Nacos（前面已做）
2. 启动 user-service
3. 启动 order-service

打开浏览器访问：
http://localhost:8082/order/123

你会看到：Created order for User-123

✅ 成功！order-service 通过 Feign 调用了 user-service！

🔍 验证服务注册：登录 Nacos 控制台（http://localhost:8848），在“服务列表”里能看到 user-service 和 order-service 两个服务。

---

五、新手常见问题 & 避坑指南

Q1：启动报错 “Cannot resolve com.alibaba.cloud...”

原因：Maven 依赖没配对版本。
解决：严格使用本文推荐的 Spring Boot 2.7.x + Spring Cloud 2021.0.8 + Alibaba 2021.0.5.0 组合。版本不匹配是最大坑！

Q2：服务没注册到 Nacos？

• 检查 application.yml 中 spring.cloud.nacos.discovery.server-addr 是否写对
• 确保 Nacos 已启动（端口 8848）
• 查看控制台日志是否有连接拒绝错误

Q3：Feign 调用返回 404？

• 检查 @FeignClient(name = "user-service") 中的 name 是否和服务名一致
• 被调用方的接口路径是否正确（如 /user/{id}）
• 路径参数要用 @PathVariable("id") 显式指定变量名

Q4：前端怎么调微服务？

微服务本身是后端架构，前端依然通过 HTTP 请求后端 API。
通常我们会加一个 API 网关（如 Spring Cloud Gateway），前端只调网关，网关再路由到具体服务。这是进阶内容，后续可学。

---

六、下一步学习建议

你已经迈出了微服务的第一步！接下来可以：

1. 深入 Nacos：尝试把配置放到 Nacos，实现动态刷新（用 @RefreshScope）
2. 加入 Sentinel：给接口加限流规则，防止被刷爆
3. 学习 Seata：模拟分布式事务场景（如下单扣库存）
4. 阅读官方文档：Spring Cloud Alibaba 官网
5. 结合前端实践：用 Vue/React 写个前端页面，调用你的 order-service 接口，完成全栈闭环！

📖 推荐书籍：

• 《Spring Cloud 微服务实战》——翟永超（国内作者，案例丰富）
• 《微服务架构设计模式》——理论扎实，适合进阶

---

结语

技术分享的意义，就是让复杂的东西变得简单。希望这篇教程能帮你打破对微服务的恐惧。记住：所有大神，都是从“Hello World”开始的。

如果你照着做了，却卡在某一步，欢迎在评论区留言——我会一一解答。也欢迎关注我的掘金主页，后续我会更新更多 Spring Cloud Alibaba 生产实践 系列教程，包括配置中心、熔断降级、链路追踪等真实场景。

动手吧！你的第一个微服务，正在等待启动！🚀