如何搭建Spring Cloud微服务案例？

wen java案例 2026-06-06 300

本文目录导读：

技术选型栈
第一步：创建父工程（管理依赖）
第二步：搭建基础设施（Nacos Server）
第三步：创建子模块（具体微服务）
第四步：搭建 API 网关（Gateway）
第五步：验证整个链路
第六步（进阶）：集成配置中心
常见问题与解决

搭建一个完整的Spring Cloud微服务案例，通常需要包含服务注册与发现、配置中心、网关、远程调用以及服务间通信等核心组件。

下面是一个基于 Spring Cloud Alibaba（使用 Nacos 作为注册中心和配置中心）的经典案例搭建步骤，适合初学者理解和实践。

技术选型栈

Spring Boot 2.6.x / 2.7.x（兼容性较好）
Spring Cloud 2021.0.x (代号 Jubilee)
Spring Cloud Alibaba 2021.0.5.0
Nacos 2.x（服务注册与配置中心）
OpenFeign（服务间调用）
Spring Cloud Gateway（API网关）

第一步：创建父工程（管理依赖）

创建一个 Maven 项目作为父模块，pom.xml 中定义统一的版本管理。

<!-- pom.xml -->
<groupId>com.example</groupId>
<artifactId>cloud-demo</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>pom</packaging>
<properties>
    <java.version>8</java.version>
    <spring.boot.version>2.6.13</spring.boot.version>
    <spring.cloud.version>2021.0.5</spring.cloud.version>
    <spring.cloud.alibaba.version>2021.0.5.0</spring.cloud.alibaba.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>
        <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>

第二步：搭建基础设施（Nacos Server）

Nacos 是阿里巴巴开源的中间件，整合了注册中心和配置中心。

下载 Nacos Server（推荐 2.2.3 版本）

启动 Nacos（单机模式）：

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

访问控制台：http://localhost:8848/nacos，默认账号密码 nacos/nacos

第三步：创建子模块（具体微服务）

本例创建3个服务：user-service、order-service、gateway-service

user-service（用户服务，提供者）

依赖（pom.xml）

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- Nacos 服务注册发现 -->
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
    </dependency>
    <!-- Nacos 配置管理（可选） -->
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
    </dependency>
</dependencies>

配置文件 bootstrap.yml（使用 Nacos 配置时用，也可直接用 application.yml）

# bootstrap.yml（优先加载）
spring:
  application:
    name: user-service
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
      config:
        server-addr: 127.0.0.1:8848
        file-extension: yaml

启动类

@SpringBootApplication
@EnableDiscoveryClient  // 开启服务发现（Spring Cloud 通用）
public class UserApplication {
    public static void main(String[] args) {
        SpringApplication.run(UserApplication.class, args);
    }
}

测试接口

@RestController
@RequestMapping("/user")
public class UserController {
    @GetMapping("/{id}")
    public String getUser(@PathVariable String id) {
        return "用户信息: ID=" + id + ", Name=张三";
    }
}

order-service（订单服务，消费者）

依赖与 user-service 类似，额外添加 OpenFeign 用于远程调用。

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>

Feign 客户端接口（声明式调用 user-service）

@FeignClient(name = "user-service") // name 对应目标服务的 application name
public interface UserClient {
    @GetMapping("/user/{id}")
    String getUser(@PathVariable("id") String id);
}

调用接口测试

@RestController
@RequestMapping("/order")
public class OrderController {
    @Autowired
    private UserClient userClient;
    @GetMapping("/{userId}")
    public String createOrder(@PathVariable String userId) {
        String userInfo = userClient.getUser(userId);
        return "订单创建成功，关联用户：" + userInfo;
    }
}

配置和启动类

# application.yml
spring:
  application:
    name: order-service
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
server:
  port: 8082

@SpringBootApplication
@EnableDiscoveryClient
@EnableFeignClients  // 启用 Feign
public class OrderApplication {
    public static void main(String[] args) {
        SpringApplication.run(OrderApplication.class, args);
    }
}

第四步：搭建 API 网关（Gateway）

统一入口,路由转发、权限校验、限流等。

依赖

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>

配置文件（基于服务名路由）

server:
  port: 8080
spring:
  application:
    name: gateway-service
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
    gateway:
      routes:
        - id: user-route
          uri: lb://user-service  # lb 表示负载均衡
          predicates:
            - Path=/user/**
        - id: order-route
          uri: lb://order-service
          predicates:
            - Path=/order/**
# 排除某些自动配置（避免冲突）
  main:
    web-application-type: reactive

启动类

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

第五步：验证整个链路

启动顺序：Nacos -> user-service(8081) -> order-service(8082) -> gateway(8080)
测试注册中心：访问 http://localhost:8848/nacos → 服务列表 → 应能看到 user-service、order-service、gateway-service
直接调用：
- http://localhost:8081/user/1 ✅
- http://localhost:8082/order/1 ✅
通过网关调用（最好方式）：
- http://localhost:8080/user/1 ✅
- http://localhost:8080/order/1 ✅

第六步（进阶）：集成配置中心

如果希望动态修改配置（如数据库连接、开关）而不重启服务，可以使用 Nacos 作为配置中心。

在 Nacos 控制台添加配置：Data ID = user-service.yaml（与 spring.application.name + 扩展名一致），Group = DEFAULT_GROUP，配置内容：

user:
  defaultName: 动态配置文件中的张三

user-service 添加配置刷新注解：

@RestController
@RequestMapping("/user")
@RefreshScope  // 允许动态刷新
public class UserController {
    @Value("${user.defaultName:默认名}")
    private String defaultName;
    @GetMapping("/config")
    public String getConfig() {
        return "当前默认用户名: " + defaultName;
    }
}

测试：修改 Nacos 中对应的配置项，无需重启服务，调用 /user/config 即可看到更新。

常见问题与解决

问题	原因	解决
服务启动后无法注册到 Nacos	版本不兼容或网络不通	检查依赖版本（Spring Cloud 与 Alibaba 版匹配），确保 Nacos 已启动
Gateway 访问报 503	服务未启动或负载均衡配置错误	确认目标服务已注册，`uri` 使用了 `lb://` 协议
Feign 调用失败	服务名错误或没有开启 `@EnableFeignClients`	检查 `@FeignClient` 的 name 与目标服务名一致
配置中心不生效	Data ID 格式不对或没有 `bootstrap` 配置	确认使用 `bootstrap.yml` 且 Data ID 为 `{服务名}.{扩展名}`