☁️ spring-cloud-demo

Spring Cloud 微服务最小可用技术演示工程 —— Eureka 注册中心 / Gateway 网关 / Config 配置中心 / OpenFeign 声明式客户端 / Resilience4j 熔断 / Spring Cloud LoadBalancer 客户端负载均衡

🛠️ 技术栈

类别	技术	版本
语言	Java (Alibaba Dragonwell)	21
框架	Spring Boot	4.1.1
微服务	Spring Cloud	2025.1.3
注册中心	Spring Cloud Netflix Eureka	5.0.2
网关	Spring Cloud Gateway (WebFlux)	5.0.3
配置中心	Spring Cloud Config	5.0.5
声明式客户端	Spring Cloud OpenFeign	5.0.3
熔断	Resilience4j	2.4.0
构建工具	Maven	3.9.6

🧩 模块 & 端口

模块	端口	应用名	角色
eureka-demo	8761	eureka-server	📡 Eureka 注册中心（@EnableEurekaServer）
spring-cloud-config-server-demo	8800	spring-cloud-config-server-demo	⚙️ Spring Cloud Config 服务端
user-service-provider	8700	user-service-provider	👤 用户服务提供方（实例 1）
user-service-provider2	—	user-service-provider2	👥 用户服务提供方（实例 2，演示负载均衡）
user-service-invoker	8701	user-service-invoker	📞 服务调用方（RestTemplate + Feign + Resilience4j）
spring-cloud-gateway-demo	8760	gateway-demo-app	🚪 Gateway 网关（lb:// 服务发现路由）
third-api	20000	third-api	🔌 第三方接口示例（请求信息 dump）

🚀 快速开始

📋 0. 前置依赖

• JDK 21（推荐 Alibaba Dragonwell 21）
• Maven 3.9.6+

🔨 1. 构建

mvn clean package -DskipTests

▶️ 2. 启动（推荐：一键脚本）

# Linux / macOS / Git Bash
sh startup.sh start       # 启动全部 4 个核心服务（已内置安全端口 18761/18760/18700/18701）
sh startup.sh status      # 查看状态
sh startup.sh stop        # 停止全部

# Windows CMD
startup.bat start

✨ 脚本特性：

• 🔀 端口被占用时自动切换到安全端口 187xx（解决 Hyper-V/WinNAT 端口保留问题）
• 📦 后台进程托管（.run/ 目录保存 pid/log）
• 🔢 启动顺序自动按依赖关系排好

✋ 3. 启动（手动）

按以下顺序逐个启动：

# 1. 注册中心（最先）
java -jar eureka-demo/target/eureka-demo.jar --server.port=8761

# 2. 服务提供方
java -jar user-service-provider/target/user-service-provider.jar --server.port=8700

# 3. 服务调用方 + 网关
java -jar user-service-invoker/target/user-service-invoker.jar --server.port=8701
java -jar spring-cloud-gateway-demo/target/spring-cloud-gateway-demo.jar --server.port=8760

✅ 4. 验证

启动后访问：

用例	URL	期望
Eureka 控制台	http://localhost:8761	看到 3 个已注册应用
provider 直连	http://localhost:8700/user/1	user:1
RestTemplate + LB	http://localhost:8701/invoke/user/11	user:11
Feign	http://localhost:8701/invoke/feign/user/22	user:22
Resilience4j 熔断	http://localhost:8701/invoke/hystrix/user/33	user:33
网关 → provider	http://localhost:8760/up/user/44	user:44
网关 → invoker	http://localhost:8760/ui/invoke/user/55	user:55

🐳 5. Docker 部署（可选）

采用 supervisord 单容器多进程方案，7 个服务运行在同一容器内、通过 localhost 互相调用：

# 先构建出 7 个 jar
mvn clean package -DskipTests

# 构建并启动
docker compose up -d --build

# 查看日志
docker compose logs -f

暴露端口：8761（Eureka）/ 8760（Gateway）/ 8800（Config）/ 8801（provider2）/ 8700（provider）/ 8701（invoker）/ 20000（third-api）。

🏗️ 架构示意

                            ┌──────────────────────────┐
                            │   spring-cloud-gateway   │
                            │   (WebFlux, lb:// 路由)  │
                            └─────────────┬────────────┘
                                          │
              ┌───────────────────────────┼───────────────────────────┐
              │                           │                           │
              ▼                           ▼                           ▼
   ┌────────────────────┐     ┌────────────────────────┐    ┌──────────────────┐
   │ user-service-      │     │ user-service-invoker   │    │ third-api        │
   │ provider (Rest)    │◄────│  (RestTemplate/Feign/  │    │ (请求信息 dump)  │
   │ provider2 (LB)     │     │   Resilience4j)        │    └──────────────────┘
   └──────────┬─────────┘     └────────────┬───────────┘
                 │                           │
                 └───────────┬───────────────┘
                             ▼
                  ┌──────────────────────┐         ┌─────────────────────────────┐
                  │  eureka-demo (8761)  │◄────│ spring-cloud-config-   │
                  │  Eureka Server        │         │  server-demo (8800)         │
                  └──────────────────────┘         └─────────────────────────────┘

⚠️ Windows 端口冲突

项目默认端口（8760–8763、8700、8701）常被 Hyper-V / WinNAT 动态端口保留占用。启动前可核查：

netsh interface ipv4 show excludedportrange protocol=tcp

如发现端口落在排除区间：

• 🥇 首选：使用 sh/startup.sh（内置安全端口 18761/18760/18700/18701）
• 🥈 手动启动：用 --server.port=187xx 临时改端口

📁 项目结构

spring-cloud-demo/
├── eureka-demo/                  # 注册中心
├── spring-cloud-gateway-demo/    # 网关（WebFlux）
├── spring-cloud-config-server-demo/  # 配置中心
├── user-service-provider/        # 用户服务（实例 1）
├── user-service-provider2/       # 用户服务（实例 2）
├── user-service-invoker/         # 服务调用方（Feign/RestTemplate/Resilience4j）
├── third-api/                    # 第三方接口示例
├── sh/                           # 一键启动脚本（start/stop/status）
├── help/                         # 架构图与配套脚本
├── .github/workflows/            # CI（build/release/docker 三个 job）
├── Dockerfile                    # supervisord 单容器镜像定义
├── docker-compose.yml            # 一键编排启动
├── spring-cloud-demo.ini         # supervisord 七程序配置
├── AGENTS.md                     # AI 编码助手开发规范
├── pom.xml                       # Maven 根 POM（模块聚合）
└── LICENSE                       # Apache License 2.0

📚 参考

• Spring Cloud 2025.1.x Reference
• Spring Cloud Gateway
• Spring Cloud LoadBalancer
• Spring Cloud OpenFeign
• Spring Cloud Config
• Resilience4j

📄 协议

Apache License 2.0