Spring Cloud 项目搭建指南

一份学习记录，记录从零搭建 Spring Cloud 微服务项目的结构、配置和踩过的坑。

一、项目结构（最优解）

spring-cloud-again (父 pom，聚合模块)
│
├── common                → 公共代码（工具类、通用实体、统一返回）
│
├── module                → 业务模块聚合（pom 类型，管 service 公共依赖）
│   ├── order-service     → 订单服务
│   └── user-service      → 用户服务
│
└── gateway               → 网关（需要时再加，直接继承父 pom）

继承链

spring-boot-starter-parent (Spring 官方，管 Boot 版本)
        ↓
spring-cloud-again (自己的父 pom，管 Cloud 版本 + 全局依赖)
        ↓
module (业务聚合，管 service 公共依赖)
        ↓
order-service / user-service

各模块职责

关于 common 的位置

• common 直接继承父 pom（和 module、gateway 平级）
• 因为 gateway 也可能引用 common，所以 common 不能塞进 module 里

二、父 pom 配置

pom.xml

<properties>
    <java.version>17</java.version>
    <spring-cloud.version>2025.1.2</spring-cloud.version>
</properties>

<!-- 全局依赖：所有模块都要的 -->
<dependencies>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
    </dependency>
</dependencies>

<!-- 版本管理：只声明版本，不强制引入 -->
<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>

<modules>
    <module>module</module>
    <module>common</module>
</modules>

关键点

• packaging 必须是 pom（父 pom 是聚合模块，不打包成 jar）
• dependencyManagement 里必须写 <type>pom</type> 和 <scope>import</scope>，否则 Maven 会当普通 jar 下载报错
• dependencies（强制继承）vs dependencyManagement（只定版本）的区别：
  • dependencies：子模块不想要也得要
  • dependencyManagement：子模块想用自己引入，不用写版本号

三、module（业务聚合）pom 配置

module/pom.xml

<parent>
    <groupId>org.example</groupId>
    <artifactId>spring-cloud-again</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</parent>

<artifactId>module</artifactId>
<packaging>pom</packaging>

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

<!-- service 公共依赖 -->
<dependencies>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

为什么 web 放 module 不放父 pom？
因为不是所有模块都要 web（比如 gateway 用 webflux 不用 web），放 module 只给 service 用。

四、service 模块 pom 配置

module/user-service/pom.xml

<parent>
    <groupId>org.example</groupId>
    <artifactId>module</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</parent>

<artifactId>user-service</artifactId>

• 继承 module，自动获得 web、lombok 等公共依赖
• 只写自己特殊的依赖，<dependencies> 可以留空

五、入口类（启动类）

每个 service 一个，@SpringBootApplication + package

package com.example.user;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class UserServiceApplication {

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

目录要与包名一致

src/main/java/com/example/user/UserServiceApplication.java

规范

• 入口类必须放在最外层包，才能扫到它下面所有 Controller / Service / Component
• 包名 = reverse(域名) + 模块名，例如 com.example.user
• 包名里不能有 -（连字符），com.example.user-service 是错的，会编译报错

在 IDEA 里重命名/移动入口类的正确方式：
右键类名 → Refactor → Move（中文：重构 → 移动），填新包名，IDEA 自动建目录并同步包名。
不要用 IDEA 关于"默认包"的快速修复，它会删掉 @SpringBootApplication，反而坏了。

六、配置文件

每个 service 在 src/main/resources/application.yml 下建自己的配置。

module/user-service/src/main/resources/application.yml

server:
  port: 8081

spring:
  application:
    name: user-service

⚠️ 端口冲突：多个服务都没配端口时默认都是 8080，一起启动会冲突。每个服务要配不同端口。

七、踩坑记录

八、下一步（Spring Cloud 主线）

按顺序学习，每个功能 = 依赖 + 配置 + 注解：

1. 服务注册发现（Nacos / Eureka）→ @EnableDiscoveryClient
2. 远程调用（OpenFeign）
3. 网关（Spring Cloud Gateway）
4. 负载均衡（Spring Cloud LoadBalancer）
5. 配置中心（Nacos Config）
6. 熔断降级（Resilience4j / Sentinel）