# cloud

**Repository Path**: my919/cloud

## Basic Information

- **Project Name**: cloud
- **Description**: No description available
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-21
- **Last Updated**: 2026-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cloud

基于 **Spring Boot 4**、**Spring Cloud 2025** 与 **Spring Cloud Alibaba** 的微服务示例工程：网关、应用聚合层、用户服务、公共模块，使用 **Nacos** 做服务发现与配置中心。

仓库地址：https://gitee.com/my919/cloud

---

## 运行环境

| 项 | 要求 |
|----|------|
| **JDK** | 21（与 `maven.compiler` 一致） |
| **Maven** | 3.9+（建议） |
| **Nacos** | 2.2+ 或 3.x（需同时支持 Naming + Config；客户端为 Nacos 3.x） |
| **操作系统** | Windows / Linux / macOS 均可 |

可选环境变量（默认值见各模块 `application-*.yml`）：

| 变量 | 说明 |
|------|------|
| `SPRING_PROFILES_ACTIVE` | 激活配置，默认 `dev` |
| `NACOS_SERVER_ADDR` | Nacos 地址，默认 `192.168.1.22:30010` |
| `NACOS_USERNAME` / `NACOS_PASSWORD` | Nacos 鉴权，默认 `nacos` / `admin` |
| `SERVER_PORT` | `cloud-app` / `cloud-user` 端口覆盖（默认 8002 / 8001） |

---

## 技术栈与版本（父 POM 管理）

| 组件 | 版本 |
|------|------|
| Spring Boot | 4.0.0 |
| Spring Cloud | 2025.1.0 |
| Spring Cloud Alibaba | 2025.1.0.0 |
| 代码格式化 | Spotless + Palantir Java Format（`mvn verify` 会跑检查） |
| API 文档（微服务） | springdoc-openapi **3.0.1**（`springdoc-openapi-starter-webmvc-ui`，OpenAPI 3 + Swagger UI；**cloud-user**、**cloud-app**） |

---

## 项目结构

```
cloud/                          # 父工程（packaging=pom）
├── pom.xml
├── cloud-common/               # 公共模块：统一返回体 Result、classpath 共享配置（含 springdoc 公共项）
│   └── src/main/resources/
│       └── application-shared.yml
├── cloud-gateway/              # API 网关（Spring Cloud Gateway + WebFlux；不含 Swagger UI）
│   └── 默认端口 9000
├── cloud-app/                  # 聚合 / BFF（Spring MVC + OpenFeign + LoadBalancer）
│   └── 默认端口 8002；注册名 cloud-app；对外路径前缀 /web
└── cloud-user/                 # 用户域示例服务（Spring MVC）
    └── 默认端口 8001；注册名 cloud-user；对外路径前缀 /user
```

**配置约定（dev / test / prod）**

- 各模块 `application.yml`：应用名、激活 profile、引入 `application-shared.yml`。
- `application-dev.yml` / `application-test.yml` / `application-prod.yml`：**三份中 Nacos 段内容一致（冗余）**，含：
  - **注册中心**：`spring.cloud.nacos.discovery`
  - **配置中心**：`spring.config.import: optional:nacos:application.yml` 与 `spring.cloud.nacos.config`（远程 `dataId: application.yml`，`DEFAULT_GROUP`）

网关路由（见 `cloud-gateway/.../application.yml`）：`/web/**` → `cloud-app`，`/user/**` → `cloud-user`（`lb://` 依赖 Nacos 注册）。

---

## Quickstart

### 1. 准备 Nacos

1. 启动 Nacos Server，保证本机能访问（与 `NACOS_SERVER_ADDR` 一致）。
2. 在 **配置管理** 中创建（若暂无内容可先建空文件，工程使用 `optional:nacos:`，一般仍可启动）：
   - **DataId**：`application.yml`
   - **Group**：`DEFAULT_GROUP`
   - **命名空间**：与配置中一致（当前为 public / 默认）

按需开启鉴权，并保证 `NACOS_USERNAME` / `NACOS_PASSWORD` 与控制台一致。

### 2. 克隆与构建

```bash
git clone https://gitee.com/my919/cloud.git
cd cloud
mvn clean package -DskipTests
```

（可选）统一 Java 代码风格后再提交：

```bash
mvn spotless:apply
```

### 3. 启动顺序建议

在三个终端分别启动（或 IDE 运行主类）：

1. **cloud-user** — `org.my919.UserApplication`
2. **cloud-app** — `org.my919.app.CloudApplication`
3. **cloud-gateway** — `org.my919.gateway.GatewayApplication`

确保 Nacos **服务列表** 中出现 `cloud-user`、`cloud-app`、`cloud-gateway` 后再测网关。

### 4. 验证

#### 4.1 HTTP 接口

| 场景 | 地址 |
|------|------|
| 用户服务直连 | `http://localhost:8001/user/info` |
| 应用直连（含 Feign 调 user） | `http://localhost:8002/web/test` |
| 经网关 | `http://localhost:9000/user/info`、`http://localhost:9000/web/test` |

#### 4.2 Swagger / OpenAPI（各微服务）

**springdoc-openapi**（WebMVC）挂在 **cloud-user**、**cloud-app** 上：根据各自 Controller 扫描生成文档；**Try it out** 的请求发往**当前打开的文档所在服务**（直连端口），不是经网关。

| 服务 | 默认端口 | Swagger UI | OpenAPI 3 JSON |
|------|----------|--------------|----------------|
| **cloud-user** | 8001 | http://localhost:8001/swagger-ui.html | http://localhost:8001/v3/api-docs |
| **cloud-app** | 8002 | http://localhost:8002/swagger-ui.html | http://localhost:8002/v3/api-docs |

（部分浏览器或版本会重定向到 `/swagger-ui/index.html`，与 `/swagger-ui.html` 等价入口。）

**使用步骤**

1. 启动对应微服务（查看 user 文档只需 **cloud-user**；查看 app 与 Feign 联调示例需 **cloud-user** + **cloud-app**）。  
2. 在浏览器打开上表中的 **Swagger UI** 地址。  
3. 使用 **Try it out** → **Execute**：请求发往 `http://localhost:8001` 或 `http://localhost:8002`（与文档所属服务一致）。  
4. 若需验证 **经网关** 的访问，仍用上一节 **HTTP 接口** 表格中的网关地址手动调用或使用 Postman 等工具；网关进程内**不**暴露 Swagger UI。

**公共配置**：`springdoc` 段写在 **`cloud-common/src/main/resources/application-shared.yml`**，各模块通过 `spring.config.import: optional:classpath:application-shared.yml` 引入；仅当模块 POM 中声明 **`springdoc-openapi-starter-webmvc-ui`** 时 springdoc 才会生效（当前为 **cloud-user**、**cloud-app**）。父 POM 的 **`dependencyManagement`** 统一管理 **`springdoc.version`**。

| 配置项 | 含义 |
|--------|------|
| `springdoc.api-docs.path` | OpenAPI JSON 路径，默认 `/v3/api-docs` |
| `springdoc.swagger-ui.path` | Swagger UI 入口，默认 `/swagger-ui.html` |
| `springdoc.show-actuator` | 是否在文档中展示 Actuator 接口，当前为 `false` |

可在各服务的 Controller 上使用 **`@Tag`、`@Operation`** 等注解丰富说明；网关 **cloud-gateway** 无 springdoc 依赖，加载共享 YAML 中的 `springdoc` 键不会启用文档。

### 5. 切换环境

```bash
# Windows PowerShell 示例：以 test 配置启动 user
$env:SPRING_PROFILES_ACTIVE="test"
mvn -pl cloud-user spring-boot:run
```

（当前父工程未配置 `spring-boot-maven-plugin` 打可执行 fat jar，本地开发推荐 **`mvn -pl <模块> spring-boot:run`**。）

---

## 参与贡献

1. Fork 本仓库  
2. 新建功能分支  
3. 提交前执行 `mvn spotless:apply` 与 `mvn verify -DskipTests`  
4. 发起 Pull Request  

英文说明见 [README.en.md](README.en.md)。