datai/docs/api-docs/2026-01-21-001-api.md

# 动态数据源延迟加载 API 文档

## 元数据
- 需求编号：2026-01-21-001
- 创建时间：2026-01-21
- 创建人：SSOT 架构师
- 状态：已完成
- API 版本：v1.0.0
- 基础路径：/system/datasource

## 概述

### API 描述
动态数据源延迟加载 API 提供了数据源的动态加载、切换、查询和移除功能，支持运行时动态管理数据源，无需重启应用。

### 认证方式
- 认证类型：JWT Token
- 认证头：Authorization: Bearer {token}
- 权限要求：需要相应的系统权限

### 通用响应格式
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}
```

### 响应码说明
| 响应码 | 说明 |
| ---- | ---- |
| 200 | 操作成功 |
| 401 | 未认证 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

## API 接口列表

### 1. 加载从库数据源

#### 接口描述
加载从库数据源，从主库读取从库配置并动态创建数据源。

#### 请求信息
- **请求方式**：POST
- **请求路径**：/system/datasource/loadSlave
- **权限要求**：system:datasource:load

#### 请求参数
无

#### 请求示例
```bash
POST /system/datasource/loadSlave
Authorization: Bearer {token}
Content-Type: application/json
```

#### 响应示例
**成功响应**
```json
{
  "code": 200,
  "msg": "从库数据源加载成功",
  "data": null
}
```

**失败响应**
```json
{
  "code": 500,
  "msg": "加载从库数据源失败：从库配置不存在",
  "data": null
}
```

#### 错误码说明
| 错误码 | 说明 |
| ---- | ---- |
| 500 | 从库配置不存在 |
| 500 | 从库已停用，无法加载 |
| 500 | 数据源已存在 |
| 500 | 添加动态数据源失败 |

---

### 2. 切换从库库名

#### 接口描述
切换从库库名，更新从库配置并重新加载数据源。

#### 请求信息
- **请求方式**：POST
- **请求路径**：/system/datasource/switchSlave/{dbName}
- **权限要求**：system:datasource:switch

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
| ---- | ---- | ---- | ---- |
| dbName | String | 是 | 新的从库库名 |

#### 请求示例
```bash
POST /system/datasource/switchSlave/new_slave_db
Authorization: Bearer {token}
Content-Type: application/json
```

#### 响应示例
**成功响应**
```json
{
  "code": 200,
  "msg": "从库切换成功",
  "data": null
}
```

**失败响应**
```json
{
  "code": 500,
  "msg": "切换从库失败：从库配置不存在",
  "data": null
}
```

#### 错误码说明
| 错误码 | 说明 |
| ---- | ---- |
| 500 | 从库配置不存在 |
| 500 | 从库已停用，无法切换 |
| 500 | 移除数据源失败 |
| 500 | 添加动态数据源失败 |

---

### 3. 获取从库配置

#### 接口描述
获取从库配置信息。

#### 请求信息
- **请求方式**：GET
- **请求路径**：/system/datasource/getSlaveConfig
- **权限要求**：system:datasource:query

#### 请求参数
无

#### 请求示例
```bash
GET /system/datasource/getSlaveConfig
Authorization: Bearer {token}
Content-Type: application/json
```

#### 响应示例
**成功响应**
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "dsName": "SLAVE",
    "dbName": "slave_db",
    "dbHost": "localhost",
    "dbPort": 3306,
    "username": "root",
    "password": "******",
    "dbType": "mysql",
    "status": "0",
    "remark": "从库配置",
    "createBy": "admin",
    "createTime": "2026-01-21 10:00:00",
    "updateBy": "admin",
    "updateTime": "2026-01-21 10:00:00"
  }
}
```

**失败响应**
```json
{
  "code": 500,
  "msg": "获取从库配置失败：从库配置不存在",
  "data": null
}
```

#### 错误码说明
| 错误码 | 说明 |
| ---- | ---- |
| 500 | 从库配置不存在 |

---

### 4. 切换数据源

#### 接口描述
切换到指定的数据源。

#### 请求信息
- **请求方式**：POST
- **请求路径**：/system/datasource/switch/{dsName}
- **权限要求**：system:datasource:switch

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
| ---- | ---- | ---- | ---- |
| dsName | String | 是 | 数据源名称（如：MASTER、SLAVE） |

#### 请求示例
```bash
POST /system/datasource/switch/SLAVE
Authorization: Bearer {token}
Content-Type: application/json
```

#### 响应示例
**成功响应**
```json
{
  "code": 200,
  "msg": "数据源切换成功",
  "data": null
}
```

**失败响应**
```json
{
  "code": 500,
  "msg": "切换数据源失败：数据源不存在",
  "data": null
}
```

#### 错误码说明
| 错误码 | 说明 |
| ---- | ---- |
| 500 | 数据源不存在 |

---

### 5. 移除数据源

#### 接口描述
移除指定的数据源。

#### 请求信息
- **请求方式**：DELETE
- **请求路径**：/system/datasource/{dsName}
- **权限要求**：system:datasource:remove

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
| ---- | ---- | ---- | ---- |
| dsName | String | 是 | 数据源名称 |

#### 请求示例
```bash
DELETE /system/datasource/SLAVE
Authorization: Bearer {token}
Content-Type: application/json
```

#### 响应示例
**成功响应**
```json
{
  "code": 200,
  "msg": "数据源移除成功",
  "data": null
}
```

**失败响应**
```json
{
  "code": 500,
  "msg": "移除数据源失败：数据源不存在",
  "data": null
}
```

#### 错误码说明
| 错误码 | 说明 |
| ---- | ---- |
| 500 | 数据源不存在 |

---

## 数据模型

### SysDatasourceConfig（数据源配置）

| 字段名 | 类型 | 必填 | 说明 |
| ---- | ---- | ---- | ---- |
| id | Long | 是 | 主键ID |
| dsName | String | 是 | 数据源名称（如：SLAVE） |
| dbName | String | 是 | 数据库名称 |
| dbHost | String | 是 | 数据库主机 |
| dbPort | Integer | 是 | 数据库端口 |
| username | String | 是 | 用户名 |
| password | String | 是 | 密码（加密存储） |
| dbType | String | 是 | 数据库类型（mysql/postgresql/oracle等） |
| status | String | 是 | 状态（0正常 1停用） |
| remark | String | 否 | 备注 |
| createBy | String | 否 | 创建者 |
| createTime | DateTime | 否 | 创建时间 |
| updateBy | String | 否 | 更新者 |
| updateTime | DateTime | 否 | 更新时间 |

---

## 使用示例

### 场景 1：首次加载从库数据源

```bash
# 1. 加载从库数据源
POST /system/datasource/loadSlave
Authorization: Bearer {token}
Content-Type: application/json

# 响应
{
  "code": 200,
  "msg": "从库数据源加载成功",
  "data": null
}

# 2. 验证从库配置
GET /system/datasource/getSlaveConfig
Authorization: Bearer {token}
Content-Type: application/json

# 响应
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "dsName": "SLAVE",
    "dbName": "slave_db",
    "dbHost": "localhost",
    "dbPort": 3306,
    "username": "root",
    "password": "******",
    "dbType": "mysql",
    "status": "0",
    "remark": "从库配置",
    "createBy": "admin",
    "createTime": "2026-01-21 10:00:00",
    "updateBy": "admin",
    "updateTime": "2026-01-21 10:00:00"
  }
}
```

### 场景 2：切换从库库名

```bash
# 1. 切换从库库名
POST /system/datasource/switchSlave/new_slave_db
Authorization: Bearer {token}
Content-Type: application/json

# 响应
{
  "code": 200,
  "msg": "从库切换成功",
  "data": null
}

# 2. 验证从库配置
GET /system/datasource/getSlaveConfig
Authorization: Bearer {token}
Content-Type: application/json

# 响应
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "dsName": "SLAVE",
    "dbName": "new_slave_db",
    "dbHost": "localhost",
    "dbPort": 3306,
    "username": "root",
    "password": "******",
    "dbType": "mysql",
    "status": "0",
    "remark": "从库配置",
    "createBy": "admin",
    "createTime": "2026-01-21 10:00:00",
    "updateBy": "admin",
    "updateTime": "2026-01-21 10:00:00"
  }
}
```

### 场景 3：切换数据源

```bash
# 1. 切换到从库
POST /system/datasource/switch/SLAVE
Authorization: Bearer {token}
Content-Type: application/json

# 响应
{
  "code": 200,
  "msg": "数据源切换成功",
  "data": null
}

# 2. 切换到主库
POST /system/datasource/switch/MASTER
Authorization: Bearer {token}
Content-Type: application/json

# 响应
{
  "code": 200,
  "msg": "数据源切换成功",
  "data": null
}
```

### 场景 4：移除数据源

```bash
# 1. 移除从库数据源
DELETE /system/datasource/SLAVE
Authorization: Bearer {token}
Content-Type: application/json

# 响应
{
  "code": 200,
  "msg": "数据源移除成功",
  "data": null
}
```

---

## 注意事项

### 1. 权限要求
所有接口都需要相应的系统权限，确保用户已获得授权。

### 2. 数据源切换
- 数据源切换操作是线程安全的
- 切换过程不会影响其他请求
- 切换失败时会自动回滚到原数据源

### 3. 主库保护
- MASTER 数据源不可删除和停用
- MASTER 数据源不可切换

### 4. 密码安全
- 数据库密码加密存储
- API 响应中密码字段会被脱敏显示

### 5. 异常处理
- 所有接口都有完善的异常处理
- 异常信息会返回给调用方
- 建议调用方根据错误码进行相应的处理

---

## 版本历史

| 版本 | 日期 | 说明 |
| ---- | ---- | ---- |
| v1.0.0 | 2026-01-21 | 初始版本，支持动态数据源加载、切换、查询和移除 |

---

## 相关文档
- [需求文档](../requirements/2026-01-21-001-动态数据源延迟加载.md)
- [设计文档](../design/2026-01-21-001-动态数据源延迟加载设计.md)
- [决策记录](../decisions/2026-01-21-001-ADR-动态数据源延迟加载.md)
- [SQL 脚本](../sql/2026-01-21-001-sys_datasource_config.sql)
- [提示词](../prompts/2026-01-21-001-动态数据源延迟加载代码生成提示词.md)
- [会话记录](../sessions/2026-01-21-001-session.md)
- [变更日志](../changelog/2026-01-21-001-changelog.md)
- [复盘文档](../retros/2026-01-21-001-retro.md)