提供远程 SQL 执行能力，支持动态数据源切换、SQL 安全校验、事务管理和内置 Web 管理界面，适用于运维管理和数据排查场景。

仓库坐标

Maven

<dependency>
    <groupId>com.luamas.thinkbridge</groupId>
    <artifactId>database-manger-spring-boot-starter</artifactId>
</dependency>

Gradle

implementation("com.luamas.thinkbridge:database-manger-spring-boot-starter")

快速开始

  1. 引入 database-manger-spring-boot-starter 依赖

  2. 在配置文件中开启执行端点：think.database.manger.execute.enabled=true

  3. 启动应用后访问内置管理界面：http://localhost:8100/database-manger/index.html

  4. 使用默认账号 sql_execution / sql_execution 登录执行 SQL

配置

think:
  database:
    manger:
      # 是否启用数据库管理模块，默认关闭
      enabled: true
      # 数据源类型：base（普通数据源）或 baomidou（动态数据源）
      database-type: baomidou
      # SQL 执行端点配置
      execute:
        # 是否启用 SQL 执行端点，默认关闭
        enabled: true
        # SQL 执行端点 URL，默认 /sql/execute
        path: /sql/execute
        # 是否使用自定义 UserDetailsService 认证，默认 false 使用内置内存用户
        use-custom-auth: false
        # 权限校验标识，默认 sql_execution
        check-authority: sql_execution
        # 内置认证用户配置（use-custom-auth=false 时生效）
        user:
          username: sql_execution
          # 明文密码，或加前缀的加密密码（如 {noop}sql_execution）
          password: "{noop}sql_execution"

配置属性一览

属性 默认值 说明

think.database.manger.enabled

false

是否启用数据库管理模块

think.database.manger.database-type

baomidou

数据源类型：base 或 baomidou

think.database.manger.execute.enabled

false

是否启用 SQL 执行端点

think.database.manger.execute.path

/sql/execute

SQL 执行端点 URL

think.database.manger.execute.use-custom-auth

false

是否使用自定义 UserDetailsService

think.database.manger.execute.check-authority

sql_execution

权限校验标识

think.database.manger.execute.user.username

sql_execution

内置认证用户名

think.database.manger.execute.user.password

{noop}sql_execution

内置认证密码

API 接口

所有接口位于 execute.path 下（默认 /sql/execute），使用 HTTP Basic Auth 认证。

执行 SQL

路径 方法 说明

/{type}

POST

根据执行类型分发 SQL 操作

type 为路径变量，支持以下取值（大小写不敏感）：

类型 说明 返回值

QUERY

查询单行结果

Map<String, Object>

QUERY_LIST

查询多行结果

List<Map<String, Object>>

UPDATE

更新操作

影响行数 int

UPDATE_LIST

批量更新操作

各语句影响行数 int[]

EXECUTE

执行 DDL/DML

无返回值

请求示例

curl -X POST 'http://localhost:8100/sql/execute/QUERY' \
  -u 'sql_execution:sql_execution' \
  -H 'Content-Type: text/plain' \
  --data-raw 'SELECT id, name FROM user WHERE id = 1'

响应示例

{
  "success": true,
  "data": [
    {
      "ID": 1,
      "NAME": "Alice"
    }
  ]
}

动态数据源切换

当 database-type=baomidou 且项目中存在 DynamicDataSourceProvider 时，自动启用动态数据源支持。通过请求参数 datasource 指定数据源名称：

curl -X POST 'http://localhost:8100/sql/execute/QUERY?datasource=slave' \
  -u 'sql_execution:sql_execution' \
  -H 'Content-Type: text/plain' \
  --data-raw 'SELECT * FROM user'

模块会在执行前将数据源推入 DynamicDataSourceContextHolder，执行后自动弹出清理，保证 ThreadLocal 不泄漏。

SQL 安全校验

为防止误操作破坏数据库结构，控制器内置 SQL 前缀黑名单校验，以下操作会被拦截并返回 400 错误：

拦截关键字 说明

drop

删除表/库

truncate

清空表

alter

修改表结构

create

创建表/库

grant

授权

revoke

收回权限

shutdown

关闭数据库

use

切换数据库

校验对 SQL 大小写不敏感，并会先 trim 去除首尾空白。被拦截时返回：

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Forbidden SQL operation: drop"
  }
}

事务管理

DatabaseMangerService 的所有方法均使用 @Transactional 注解：

  • query / queryList：@Transactional(readOnly = true)，只读事务

  • execute / update / updateList：@Transactional，读写事务，异常自动回滚

自动配置类 DatabaseMangerAutoConfiguration 会在 DataSourceAutoConfiguration 之后加载，事务管理器由 Spring Boot 自动装配。如需自定义事务管理器，可自行注册 PlatformTransactionManager Bean。

前端管理界面

模块内置一个自包含的 Web 管理界面（纯 HTML/CSS/JS，无外部依赖），位于 static/database-manger/index.html。

访问方式

启动应用后浏览器访问：

http://localhost:8100/database-manger/index.html

功能特性

  • SQL 编辑器：支持 Ctrl+Enter 快捷执行，内置常用 SQL 模板

  • 五种执行类型：QUERY / QUERY_LIST / UPDATE / UPDATE_LIST / EXECUTE

  • 结果展示：查询结果自动渲染为表格，更新操作显示影响行数

  • 动态数据源：界面提供数据源输入框，对应 datasource 请求参数

  • 历史记录：最近 50 条执行记录保存在 localStorage，可重新加载

  • 认证管理：凭据保存在本地，避免重复输入

  • 错误提示：SQL 安全拦截、认证失败、网络错误等均有友好提示

管理界面页面本身（/database-manger/）不经过安全过滤链，可公开访问；所有 API 调用 /sql/execute/ 均需 Basic Auth 认证。

安全说明

此模块提供了直接执行 SQL 的能力，生产环境请谨慎开启。建议：

  1. 仅在内网环境或 VPN 网络启用

  2. 修改默认用户名和密码

  3. 设置强密码并使用加密前缀（如 {bcrypt}$2a$10$…​）

  4. 启用 use-custom-auth=true 接入项目自身的 UserDetailsService

  5. 结合 OAuth2 资源服务器进行权限控制

  6. 通过 check-authority 配置最小权限标识

扩展说明

与 mybatis-plus 集成

在 build.gradle 中引入 mybatis-plus 依赖即可，模块会自动检测 DynamicDataSourceProvider 并启用动态数据源支持。

implementation 'com.baomidou:mybatis-plus-spring-boot4-starter'
implementation 'com.baomidou:dynamic-datasource-spring-boot4-starter'

自定义认证

设置 think.database.manger.execute.use-custom-auth=true 后，模块会使用项目中注册的 UserDetailsService Bean 进行认证，此时内置用户配置不生效。需确保 UserDetailsService 加载的用户拥有 check-authority 对应的权限。

自定义 JdbcTemplate

模块优先使用容器中已存在的 JdbcTemplate Bean，避免重复创建。如未注册则内部创建一个。可通过以下方式自定义：

@Bean
public JdbcTemplate jdbcTemplate(DataSource dataSource) {
    JdbcTemplate template = new JdbcTemplate(dataSource);
    template.setQueryTimeout(30);
    return template;
}

测试

模块包含完整的单元测试和集成测试，覆盖以下场景：

测试类 覆盖范围 用例数

SqlExecutionTest

枚举解析、大小写不敏感、非法类型

9

DatabaseMangerServiceTest

增删改查、事务回滚、事务提交

12

DynamicDatabaseMangerServiceTest

数据源切换、ThreadLocal 清理、非 Web 线程防护

12

SqlExecutionControllerTest

SQL 安全校验、类型分发、认证、动态数据源

19

测试使用 H2 内存数据库 + Mockito + Spring Boot Test，可通过以下命令运行：

./gradlew :thinkbridge-common-database-manger:test