# 动态数据源延迟加载 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)