# spring-cloud-demo

**Repository Path**: netbuffer/spring-cloud-demo

## Basic Information

- **Project Name**: spring-cloud-demo
- **Description**: SpringCloud微服务相关技术测试
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2018-02-11
- **Last Updated**: 2026-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: SpringBoot, SpringCloud, Java, API, Rest-api

## README

# ☁️ 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. 构建

```bash
mvn clean package -DskipTests
```

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

```bash
# 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. 启动（手动）

按以下顺序逐个启动：

```bash
# 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` 互相调用：

```bash
# 先构建出 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 动态端口保留占用。启动前可核查：

```powershell
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](https://docs.spring.io/spring-cloud-release/reference/2025.1/index.html)
- [Spring Cloud Gateway](https://docs.spring.io/spring-cloud-gateway/reference/)
- [Spring Cloud LoadBalancer](https://docs.spring.io/spring-cloud-commons/reference/#spring-cloud-loadbalancer)
- [Spring Cloud OpenFeign](https://docs.spring.io/spring-cloud-openfeign/reference/)
- [Spring Cloud Config](https://docs.spring.io/spring-cloud-config/reference/)
- [Resilience4j](https://resilience4j.readme.io/docs)

## 📄 协议

[Apache License 2.0](LICENSE)