# shardingsphere-rw-delay-demo

**Repository Path**: xcOschina/shardingsphere-rw-delay-demo

## Basic Information

- **Project Name**: shardingsphere-rw-delay-demo
- **Description**: 这是一个演示如何使用 Apache ShardingSphere 实现读写分离，并检测和处理主从复制延迟的示例项目。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-12-11
- **Last Updated**: 2025-12-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

#  Apache ShardingSphere 实现读写分离 ShardingSphere Read/Write Splitting with Delay Detection Demo 

这是一个演示如何使用 Apache ShardingSphere 实现读写分离，并检测和处理主从复制延迟的示例项目。

## 项目概述

本项目展示了在使用 MySQL 主从复制架构时，如何通过 Apache ShardingSphere 4.1.1 实现智能的读写分离策略，特别是当从库出现复制延迟时，能够自动将读请求路由到健康的从库或主库，从而保证数据一致性。

## 技术栈

- Java 11
- Spring Boot 2.3.5.RELEASE
- Apache ShardingSphere 4.1.1
- MyBatis Plus 3.4.2
- MySQL 8.0
- Docker & Docker Compose

## 架构设计

### 数据库架构

项目使用 Docker Compose 启动一个包含以下组件的 MySQL 主从复制环境：

- 1 个 MySQL 主库 (master)
- 2 个 MySQL 从库 (slave1 和 slave2)

### 读写分离机制

通过 ShardingSphere 的读写分离功能实现：

- 写操作定向到主库
- 读操作在从库之间负载均衡

### 延迟检测与处理

项目实现了自定义的健康检查机制：

1. 定期检查从库的复制延迟 (`Seconds_Behind_Master`)
2. 当从库延迟超过阈值时，将其标记为不健康
3. 使用自定义的负载均衡算法，只将读请求路由到健康的从库
4. 如果所有从库都不健康，则回退到主库执行读操作

## 项目结构

```
├── docker-compose.yml          # MySQL 主从复制环境定义
├── pom.xml                     # Maven 依赖配置
├── init-master/
│   └── setup.sql               # 主库初始化脚本
├── init-slave/
│   └── replication-setup.sh    # 从库复制配置脚本
├── src/
│   └── main/
│       ├── java/
│       │   └── com/example/rwdemo/
│       │       ├── config/                 # 配置类
│       │       ├── controller/             # 控制器
│       │       ├── entity/                 # 实体类
│       │       ├── health/                 # 健康检查组件
│       │       ├── loadbalance/            # 自定义负载均衡算法
│       │       └── mapper/                 # MyBatis Mapper
│       └── resources/
│           ├── application.yml             # 主配置文件
│           ├── application-local.yml       # 本地环境配置
│           └── schema.sql                  # 数据库表结构
└── start.sh                                # 启动脚本
```

## 快速开始

### 环境准备

确保系统已安装以下软件：
- Docker & Docker Compose
- Java 11
- Maven

### 启动步骤

1. 启动 MySQL 主从复制环境：
   ```bash
   docker-compose up -d
   ```

2. 配置主从复制（首次启动时需要）：
   ```bash
   docker exec mysql-slave1 /init-slave/replication-setup.sh
   docker exec mysql-slave2 /init-slave/replication-setup.sh
   ```

3. 构建并启动 Spring Boot 应用：
   ```bash
   mvn clean spring-boot:run
   ```

### 配置说明

#### 数据库连接配置

在 [application-local.yml](src/main/resources/application-local.yml) 中配置了三个数据源：
- `ds-master`: 主库连接信息
- `ds-slave1`: 从库1连接信息
- `ds-slave2`: 从库2连接信息

#### 延迟阈值设置

在 [application.yml](src/main/resources/application.yml) 中可以配置复制延迟阈值：
```yaml
replication:
  delay-threshold: 5000  # 5秒
```

## 核心组件介绍

### HealthyRandomMasterSlaveLoadBalanceAlgorithm

自定义的负载均衡算法，继承自 [MasterSlaveLoadBalanceAlgorithm](file:///D:/Users/%E5%BE%90%E9%99%B3/IdeaProjects/shardingsphere-rw-delay-demo/shardingsphere-rw-delay-demo/src/main/java/org/apache/shardingsphere/spi/masterslave/MasterSlaveLoadBalanceAlgorithm.java#L27-L27)，实现以下功能：
- 获取健康从库列表
- 在健康从库中随机选择一个进行读操作
- 当无健康从库时回退到主库

### SlaveHealthManager

从库健康检查管理器，定期执行以下操作：
- 查询每个从库的 `SHOW SLAVE STATUS`
- 检查 `Seconds_Behind_Master` 是否超过阈值
- 维护健康从库列表

## API 接口

应用提供了 RESTful API 用于测试读写分离功能：

- `POST /test/write`: 执行写操作（路由到主库）
- `GET /test/read`: 执行读操作（路由到从库）
- `GET /test/all`: 获取所有数据（读操作）

## 监控与运维

通过 Spring Boot Actuator 提供健康检查端点：
- `/actuator/health`: 查看应用整体健康状态

## 常见问题与解决方案

### 连接认证问题

MySQL 8.0 默认使用 `caching_sha2_password` 认证插件，可能导致连接问题。项目中已通过在配置中指定 `mysql_native_password` 插件解决。

### 复制状态异常

如果从库复制状态异常，可使用以下命令检查和修复：
```bash
# 检查复制状态
docker exec -it mysql-slave1 mysql -uroot -proot123456 -e "SHOW SLAVE STATUS\G"

# 跳过错误事件（如有必要）
docker exec -it mysql-slave1 mysql -uroot -proot123456 -e "STOP SLAVE; SET GLOBAL SQL_SLAVE_SKIP_COUNTER = 1; START SLAVE;"
```

## 扩展与定制

1. 调整延迟阈值以适应具体业务需求
2. 修改负载均衡算法实现更复杂的路由逻辑
3. 集成监控系统收集复制延迟指标
4. 实现更完善的健康检查机制

## 许可证

本项目基于 Apache License 2.0 开源协议。