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}
• 权限要求：需要相应的系统权限

通用响应格式

{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}

响应码说明

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

API 接口列表

1. 加载从库数据源

接口描述

加载从库数据源，从主库读取从库配置并动态创建数据源。

请求信息

• 请求方式：POST
• 请求路径：/system/datasource/loadSlave
• 权限要求：system:datasource:load

请求参数

无

请求示例

POST /system/datasource/loadSlave
Authorization: Bearer {token}
Content-Type: application/json

响应示例

成功响应

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

失败响应

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

错误码说明

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

---

2. 切换从库库名

接口描述

切换从库库名，更新从库配置并重新加载数据源。

请求信息

• 请求方式：POST
• 请求路径：/system/datasource/switchSlave/{dbName}
• 权限要求：system:datasource:switch

请求参数

参数名	类型	必填	说明
dbName	String	是	新的从库库名

请求示例

POST /system/datasource/switchSlave/new_slave_db
Authorization: Bearer {token}
Content-Type: application/json

响应示例

成功响应

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

失败响应

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

错误码说明

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

---

3. 获取从库配置

接口描述

获取从库配置信息。

请求信息

• 请求方式：GET
• 请求路径：/system/datasource/getSlaveConfig
• 权限要求：system:datasource:query

请求参数

无

请求示例

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"
  }
}

失败响应

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

错误码说明

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

---

4. 切换数据源

接口描述

切换到指定的数据源。

请求信息

• 请求方式：POST
• 请求路径：/system/datasource/switch/{dsName}
• 权限要求：system:datasource:switch

请求参数

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

请求示例

POST /system/datasource/switch/SLAVE
Authorization: Bearer {token}
Content-Type: application/json

响应示例

成功响应

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

失败响应

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

错误码说明

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

---

5. 移除数据源

接口描述

移除指定的数据源。

请求信息

• 请求方式：DELETE
• 请求路径：/system/datasource/{dsName}
• 权限要求：system:datasource:remove

请求参数

参数名	类型	必填	说明
dsName	String	是	数据源名称

请求示例

DELETE /system/datasource/SLAVE
Authorization: Bearer {token}
Content-Type: application/json

响应示例

成功响应

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

失败响应

{
  "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：首次加载从库数据源

# 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：切换从库库名

# 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：切换数据源

# 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：移除数据源

# 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	初始版本，支持动态数据源加载、切换、查询和移除

---

相关文档

• 需求文档
• 设计文档
• 决策记录
• SQL 脚本
• 提示词
• 会话记录
• 变更日志
• 复盘文档