# way-example

**Repository Path**: lewis2951/way-example

## Basic Information

- **Project Name**: way-example
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-08-01
- **Last Updated**: 2026-05-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Way Example - Spring Boot/Cloud 示例项目集合

基于 Spring Boot 4.x 和 Spring Cloud 2025.x 的全栈示例项目，涵盖微服务架构的核心技术栈。

## 📋 项目简介

本项目是一个综合性的 Spring Boot/Cloud 学习与实践项目，包含以下技术领域：
- **Spring Boot** 核心功能（监控、文档、Excel、定时任务）
- **Spring Cloud** 微服务（服务注册发现、配置中心、流量控制）
- **Spring Cloud Alibaba**（Nacos 服务治理）
- **Spring Data**（MyBatis-Plus、Redis）
- **公共组件**（通用工具库）

## 🏗️ 项目结构

```
way-example/
├── spring-boot/              # Spring Boot 示例模块
│   ├── admin/                # Spring Boot Admin 监控示例
│   │   ├── admin-server/     # 监控服务端 (端口: 8000)
│   │   └── admin-client/     # 监控客户端 (端口: 8001)
│   ├── knife4j/              # Knife4j API 文档示例
│   │   ├── knife4j-webmvc/   # WebMVC 版本 (端口: 8002)
│   │   └── knife4j-webflux/  # WebFlux 版本 (端口: 8003)
│   ├── excel/                # EasyExcel 导入导出示例
│   │   └── easyexcel/        # Excel 读写与模板填充
│   └── task/                 # 定时任务示例
│       ├── quartz/           # Quartz 定时任务
│       └── xxl-job/          # XXL-Job 分布式任务调度
│
├── spring-cloud/             # Spring Cloud 微服务模块
│   └── consul/               # Consul 相关
│       ├── consul-discovery/ # 服务注册与发现 (端口: 8401)
│       └── consul-config/    # 分布式配置中心 (端口: 8400)
│
├── spring-cloud-alibaba/     # Spring Cloud Alibaba 模块
│   ├── nacos/                # Nacos 服务治理
│   │   ├── nacos-config/     # Nacos 配置中心 (端口: 8200)
│   │   ├── nacos-discovery/  # Nacos 服务发现
│   │   │   ├── nacos-provider/  # 服务提供者 (端口: 8201)
│   │   │   └── nacos-consumer/  # 服务消费者 (端口: 8202)
│   └── sentinel/             # Sentinel 流量控制 (端口: 8203)
│
├── spring-data/              # 数据访问层示例
│   ├── mybatis-plus/         # MyBatis-Plus 增强功能 (端口: 8100)
│   ├── mybatis-generator/    # MyBatis 代码生成器
│   └── redis/                # Redis 缓存与工具类
│
├── way-common/               # 公共组件模块
│   ├── way-common-core/      # 核心通用工具
│   └── way-common-mybatis-plus/  # MyBatis-Plus 通用配置
│
├── db/                       # 数据库脚本
│   └── tables.sql            # 示例表结构
│
├── pom.xml                   # 父 POM（版本管理）
└── README.md                 # 本文档
```

## 🚀 快速开始

### 环境要求

- **JDK**: 17 或更高版本
- **Maven**: 3.6+ 
- **Docker** (可选，用于中间件服务)
- **Consul** (可选，用于 Consul 模块)
- **Nacos** (可选，用于 Nacos 模块)
- **Redis** (可选，用于 Redis 模块)
- **MySQL** (可选，用于数据库模块)

### 编译项目

```bash
# 克隆项目
git clone <repository-url>
cd way-example

# 编译所有模块
mvn clean install -DskipTests
```

### 运行示例模块

每个模块都是独立的 Spring Boot 应用，可以单独运行：

```bash
# 进入具体模块目录
cd spring-boot/knife4j/knife4j-webmvc

# 运行应用
mvn spring-boot:run
```

## 📦 模块详细说明

### 1️⃣ Spring Boot 模块

#### Spring Boot Admin (监控)
- **功能**: 应用监控、健康检查、日志查看
- **技术**: Spring Boot Admin Server/Client
- **文档**: [admin/README.md](spring-boot/admin/README.md)

#### Knife4j (API 文档)
- **功能**: OpenAPI 3.0 文档生成、在线调试
- **技术**: Knife4j + SpringDoc
- **文档**: [knife4j/README.md](spring-boot/knife4j/README.md)

#### EasyExcel (Excel 处理)
- **功能**: Excel 导入导出、模板填充、样式定制
- **技术**: Alibaba EasyExcel
- **文档**: [excel/README.md](spring-boot/excel/easyexcel/README.md)

#### Task (定时任务)
- **功能**: 定时任务调度、分布式任务
- **技术**: Quartz / XXL-Job
- **文档**: 
  - [quartz/README.md](spring-boot/task/quartz/README.md)
  - [xxl-job/README.md](spring-boot/task/xxl-job/README.md)

### 2️⃣ Spring Cloud 模块

#### Consul (服务治理)
- **功能**: 服务注册发现、分布式配置中心
- **技术**: Spring Cloud Consul
- **文档**:
  - [consul-discovery/README.md](spring-cloud/consul/consul-discovery/README.md)
  - [consul-config/README.md](spring-cloud/consul/consul-config/README.md)

### 3️⃣ Spring Cloud Alibaba 模块

#### Nacos (服务治理)
- **功能**: 服务注册发现、分布式配置中心
- **技术**: Spring Cloud Alibaba Nacos
- **文档**: [nacos/README.md](spring-cloud-alibaba/nacos/README.md)

#### Sentinel (流量控制)
- **功能**: 限流、熔断降级、系统负载保护
- **技术**: Alibaba Sentinel
- **文档**: [sentinel/README.md](spring-cloud-alibaba/sentinel/README.md)

### 4️⃣ Spring Data 模块

#### MyBatis-Plus
- **功能**: ORM 增强、代码生成、分页插件
- **技术**: MyBatis-Plus 3.5.x
- **文档**: [mybatis-plus/README.md](spring-data/mybatis-plus/README.md)

#### MyBatis Generator
- **功能**: 代码自动生成（Entity、Mapper、Service）
- **技术**: MyBatis Generator
- **文档**: [mybatis-generator/README.md](spring-data/mybatis-generator/README.md)

#### Redis
- **功能**: 缓存管理、分布式锁、工具类
- **技术**: Spring Data Redis
- **文档**: [redis/README.md](spring-data/redis/README.md)

### 5️⃣ Way Common 公共组件

#### way-common-core
- **功能**: 通用工具类、常量、异常处理

#### way-common-mybatis-plus
- **功能**: MyBatis-Plus 通用配置、自动填充、分页

## 🛠️ 技术栈

### 核心框架
- **Spring Boot**: 4.0.6
- **Spring Cloud**: 2025.1.1
- **Spring Cloud Alibaba**: 2025.1.0.0
- **JDK**: 17+

### 微服务组件
- **Consul**: 服务注册与配置中心
- **Nacos**: 服务治理与配置管理
- **Sentinel**: 流量控制与熔断降级

### 数据访问
- **MyBatis-Plus**: 3.5.16 (ORM 增强)
- **Redis**: 缓存与分布式锁
- **MySQL**: 关系型数据库

### 工具组件
- **Knife4j**: 4.5.0 (API 文档)
- **EasyExcel**: 4.0.3 (Excel 处理)
- **Spring Boot Admin**: 4.0.4 (应用监控)
- **XXL-Job**: 3.4.0 (分布式任务调度)
- **Fastjson2**: 2.0.60 (JSON 处理)
- **JJWT**: 0.13.0 (JWT 认证)

## 📖 使用指南

### 场景 1: 学习 Spring Boot 核心功能

```bash
# 1. 运行 Knife4j 查看 API 文档
cd spring-boot/knife4j/knife4j-webmvc
mvn spring-boot:run
# 访问: http://localhost:8002/doc.html

# 2. 运行 EasyExcel 学习 Excel 处理
cd spring-boot/excel/easyexcel
mvn spring-boot:run
```

### 场景 2: 搭建微服务架构

```bash
# 1. 启动 Nacos
# 访问 https://github.com/alibaba/nacos/releases
# Windows: startup.cmd -m standalone

# 2. 启动服务提供者
cd spring-cloud-alibaba/nacos/nacos-discovery/nacos-provider
mvn spring-boot:run

# 3. 启动服务消费者
cd spring-cloud-alibaba/nacos/nacos-discovery/nacos-consumer
mvn spring-boot:run
```

### 场景 3: 数据库开发

```bash
# 1. 执行数据库脚本
mysql -u root -p < db/tables.sql

# 2. 运行 MyBatis-Plus 示例
cd spring-data/mybatis-plus
mvn spring-boot:run
```

### 场景 4: 使用公共组件

在项目中引入 way-common 依赖：

```xml
<dependency>
    <groupId>com.way</groupId>
    <artifactId>way-common-core</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

<dependency>
    <groupId>com.way</groupId>
    <artifactId>way-common-mybatis-plus</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>
```

## 🔧 配置说明

### 环境变量

各模块的配置在各自的 `application.yml` 或 `bootstrap.yml` 中：

- **数据库配置**: 修改 `spring.datasource.*`
- **Redis 配置**: 修改 `spring.data.redis.*`
- **Consul 配置**: 修改 `spring.cloud.consul.*`
- **Nacos 配置**: 修改 `spring.cloud.nacos.*`

### 端口规划

| 模块 | 端口 | 说明 |
|------|------|------|
| admin-server | 8000 | 监控服务端 |
| admin-client | 8001 | 监控客户端 |
| knife4j-webmvc | 8002 | API 文档 (WebMVC) |
| knife4j-webflux | 8003 | API 文档 (WebFlux) |
| mybatis-plus | 8100 | MyBatis-Plus 示例 |
| nacos-config | 8200 | Nacos 配置中心 |
| nacos-provider | 8201 | Nacos 服务提供者 |
| nacos-consumer | 8202 | Nacos 服务消费者 |
| sentinel | 8203 | 流量控制 |
| consul-config | 8400 | 配置中心 |
| consul-discovery | 8401 | 服务注册发现 |

## ❓ 常见问题

### Q1: 如何单独运行某个模块？

```bash
# 进入模块目录
cd spring-boot/knife4j/knife4j-webmvc

# 直接运行
mvn spring-boot:run

# 或者打包后运行
mvn clean package
java -jar target/knife4j-webmvc-1.0-SNAPSHOT.jar
```

### Q2: Consul/Nacos 未启动时应用无法启动？

各模块已配置容错机制（`fail-fast: false`），中间件未启动时会使用本地配置继续运行。

### Q3: 如何添加新模块？

1. 在对应分类目录下创建新模块
2. 在父 `pom.xml` 中添加 module 引用
3. 继承父 POM 的依赖管理
4. 创建 `application.yml` 和启动类

### Q4: 数据库连接失败？

1. 检查 MySQL 是否启动
2. 修改 `application.yml` 中的数据库配置
3. 执行 `db/tables.sql` 创建表结构

## 📚 学习资源

- [Spring Boot 官方文档](https://spring.io/projects/spring-boot)
- [Spring Cloud 官方文档](https://spring.io/projects/spring-cloud)
- [Spring Cloud Alibaba](https://sca.aliyun.com/)
- [MyBatis-Plus 文档](https://baomidou.com/)
- [Knife4j 文档](https://doc.xiaominfo.com/)
- [EasyExcel 文档](https://easyexcel.opensource.alibaba.com/)

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

## 📄 开源协议

本项目基于 MIT 协议开源 - 详见 [LICENSE](LICENSE) 文件

## 👨‍💻 作者

**Lewis**  
创建于 2026-05-19

## ⭐ 支持项目

如果这个项目对你有帮助，请给一个 Star ⭐