开源项目推荐：SQL API Gateway —— 把 Doris / ClickHouse SQL 变成带审批、限流、熔断的 REST 数据接口

项目地址： github.com/knowcai/apigeneral
当前版本： v1.2.0 · Apache 2.0
技术栈： Spring Boot 3 · Vue 3 · PostgreSQL · Doris / ClickHouse

v1.2.0 20260708 加了 API 目录 + 策略增强 + CSRF，修了 审计/登录/熔断/连接池 等生产级 bug，并 简化了分页和 Key 授权模型
v1.1.0 20260630 初版

一、项目是什么？

SQL API Gateway 是一套面向数据团队的 动态 SQL API 网关。

传统做法是：每来一个报表需求、每接一个微服务取数，就单独写一套后端、直连数仓。SQL 散落在各处，难以审计，一改就炸，一出问题整库跟着抖。

这个项目的思路是：在管理台配置数据源 + SQL 模板，审批通过后统一对外提供 REST 接口。调用方只需带 API Key，不用关心底层是 Doris 还是 ClickHouse。

调用方 ──(API Key)──► 网关 /api/data/* ──► 连接池 ──► Doris / ClickHouse
                         ▲
管理台 /admin/* ──(JWT)──┘     元数据：PostgreSQL（配置、日志、审批）

二、解决什么问题？（痛点 → 方案）

痛点 传统做法的困境 本项目的解决方式
重复造轮子 每个业务服务各自封装 SQL，逻辑复制、接口风格不一 集中配置 SQL 模板，一次发布、多处调用，统一 ApiResponse 响应格式
权限与审计缺失 直连数仓，谁查了啥、改了啥说不清 主题隔离 + API Key 鉴权 + 访问日志 + 操作审计，全链路可追溯
变更无管控 开发改 SQL 直接上线，出问题难追责 主题级审批流：成员提交 → 管理员审批 → 生效，超管可兜底
单点故障扩散 一条烂 SQL 拖垮连接池，影响全库 按 apiCode 熔断隔离；全局 / 单 IP / 单 API 三层 QPS 限流
安全边界模糊 写操作、DDL 混入查询接口 对外数据 API 仅允许 SELECT / WITH，SQL 安全校验 + 只读数据源开关
密钥管理混乱 连接串密码明文落库、接口回传 密码 AES-GCM 加密存储，管理 API 永不回传明文
多团队共用数仓 权限难切、Key 难管 主题（Theme） 模型：API、连接串、Key 按主题归属，成员与管理员分权

三、闪光点（为什么值得用？）

1. 开箱即用的「数据开放平台」能力

不是简单的 SQL 代理，而是把 审批、鉴权、限流、熔断、审计、监控 打包成一套可落地的治理方案，适合对内数据服务化。

2. 主题隔离 + 细粒度权限矩阵

  • 超级管理员：全站配置、用户/主题/策略
  • API 编辑员：加入主题后可编辑 API、连接串（变更走审批）
  • API 只读用户：仅查看，菜单与路由按角色隐藏
  • 主题管理员 / 成员：主题内分权，Key 创建需审批 + 提交人 claim 领取

权限规则清晰，有完整的集成测试覆盖（138 个用例）。

3. 版本化 API，发布即切换

  • 支持 v1、v2… 多版本，每版独立 SQL、数据源、超时、分页配置
  • 同一 API 同时只有一个有效发布版，发布新版本自动废弃旧版
  • 有进行中请求时拒绝发布，避免切换冲突

4. 生产级网关防护

能力 说明
三层限流 全局 QPS / 单 IP QPS / 单 API QPS，可独立开关
单 API 熔断 按 apiCode 隔离，1 分钟滚动窗口，CLOSED → OPEN → HALF_OPEN
SQL 重试 可配置次数与间隔，业务异常与超时不重试
登录限流 防暴力破解，内存限流器

5. 安全加固（v1.1.0 重点）

  • SQL 仅允许 SELECT / WITH，移除 SHOW / EXPLAIN 等绕过路径
  • 500 错误脱敏，不泄露数据库内部信息
  • 生产环境启动校验 JWT、密钥、禁止 bootstrap-key
  • JWT Cookie SameSite=Strict，CORS 收紧，默认 denyAll 安全策略
  • 访问日志写入前脱敏敏感参数

6. 现代管理台体验

  • Vue 3 + Element Plus，支持 中文 / English 切换
  • API 管理上下分栏：上方 API 列表，下方版本列表
  • 按角色跳转首页（只读 → 仪表盘，编辑 → API 管理，超管 → 主题管理）
  • 审批提交后 Toast 提示，不强制跳转打断编辑流

7. 可观测性内置

  • 访问监控：IP、调用方、参数、行数、耗时、状态（SUCCESS / ERROR / RATE_LIMITED / CIRCUIT_OPEN 等）
  • 连接池大盘、Runtime 运行时指标
  • 可选 Grafana + Prometheus 一键部署（deploy/docker-compose.monitoring.yml）

8. 工程化成熟

  • Flyway 增量迁移，不删业务数据
  • GitHub Actions CI：后端 mvn test + 前端 npm run build
  • 双语 README、权限文档、E2E 测试脚本

四、功能点一览

4.1 连接串管理

  • 支持 Doris（MySQL 协议）、ClickHouse（HTTP / Native）
  • 连接池：最小空闲、最大连接、连接超时
  • ClickHouse 可选 HTTP 压缩；Doris 可配置查询超时
  • 只读开关：约束试跑与对外 API 的 SQL 类型
  • 连接测试；超管直接增删改，普通用户变更走审批
  • 密码 AES-GCM 加密，接口只返回 passwordConfigured 标志

4.2 主题与审批

  • 每个 API / 连接串归属一个主题
  • 超管指定主题管理员与普通成员（角色互斥）
  • 主题管理员维护成员；成员可提交新建/修改/发布/暂停/恢复
  • 任一其他主题管理员或超管审批通过即生效（无多级链）
  • 自己提交的变更需他人审批；仅一名管理员时由超管兜底

4.3 API / SQL 管理

  • API 定义：编码、名称、主题、描述
  • 版本管理：数据源、SQL 模板（:参数名 占位符）、分页模式
  • 响应配置：超时、单接口 QPS 覆盖、单页最大条数、最大偏移量
  • 管理端试跑 SQL；发布 / 暂停 / 恢复 / 废弃全生命周期

4.4 主题 API Key（调用方鉴权）

  • 每主题独立 API Key，创建/轮换走审批
  • 调用方式：X-Api-Key: <key> 或 Authorization: Bearer <key>
  • Key 自动授权该主题下全部已发布 API
  • 无 Key / 无效 Key → 401；主题禁用 → 403

4.5 动态数据 API

接口格式：

GET/POST /api/data/v{version}/{theme}/{apiCode}?page=1&pageSize=20&参数名=值
X-Api-Key: gw_xxxxxxxx

统一响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "rows": [],
    "total": 0,
    "page": 1,
    "pageSize": 20,
    "hasMore": false
  },
  "requestId": "..."
}
HTTP 含义
200 成功
401 缺少或无效 API Key
403 无权限或主题已禁用
429 限流
503 熔断中

4.6 网关策略

  • 全局 / 单 IP / 单 API 三层 QPS，可独立开关
  • 单 API 熔断：默认 20 次调用、失败率 ≥ 50% 触发，等待 30s 半开试探
  • 429 不计入熔断；可配置 fallback JSON
  • SQL 重试：默认最多 2 次、间隔 500ms

4.7 用户与权限

角色 能力
SUPER_ADMIN 用户/主题/调用方/连接串/策略全权限
API_EDITOR 主题内编辑 API、连接串（需审批）
API_VIEWER 只读查看

管理端 /admin/** 需 JWT 登录，默认管理员 admin / admin123（生产务必修改）。

4.8 监控与审计

  • 访问监控：异步记录每次数据 API 调用详情
  • 操作审计：登录、增删改、发布、废弃等管理操作
  • 主题 API Key 审计：Key 创建/删除/领取事件
  • 审批中心：待办、历史、撤回

4.9 国际化

  • 管理台支持 中文 / English 切换
  • 登录页、侧边栏、表单校验、错误提示均已 i18n

五、适用场景

  1. 对内数据 API 平台 — 报表、看板、微服务统一取数入口
  2. 需要审批 + 审计的数据开放 — 金融、政务、大厂数据中台常见诉求
  3. 快速 SQL 接口化 — 不想为每条查询写 Java Controller，又要生产级限流熔断
  4. 多团队共用 Doris / ClickHouse — 用主题隔离资源与 Key，避免互相踩脚

六、技术栈与部署要求

组件 版本/说明
JDK 21
后端 Spring Boot 3.3、Spring Security、JWT、Flyway
前端 Vue 3、Vite、Element Plus、vue-i18n
元数据库 PostgreSQL（存配置、日志、审批，非业务库）
业务数据源 Doris、ClickHouse（可扩展 Trino、StarRocks 等驱动注册）
Node.js 18+（前端构建）

快速体验：

# 后端
mvn spring-boot:run          # http://localhost:8088

# 前端
cd frontend && npm install && npm run dev   # http://localhost:5173
# 登录：admin / admin123

七、典型使用流程

  1. 主题管理 — 创建主题，指定管理员与成员，创建/轮换 API Key
  2. 连接串管理 — 添加 Doris / ClickHouse，测试连接
  3. API / SQL — 新建 API → 新建版本 → 配置 SQL 模板 → 发布（非超管需审批）
  4. 调用 — 业务方携带 API Key 请求 /api/data/v1/{theme}/{apiCode}
  5. 运维 — 在监控大盘查看 QPS、错误率；在策略页调整限流熔断

八、总结

SQL API Gateway 解决的核心问题可以概括为一句话：

让数仓 SQL 像 REST API 一样被治理——有审批、有鉴权、有限流、有熔断、有审计。

如果你正在做 Doris / ClickHouse 对内服务化，又不想从零搭一套数据开放平台，这个项目可以作为 开箱即用的起点。代码开源、文档齐全、CI 通过，欢迎 Star 和 Issue。

相关链接

如需转载，请注明出处与项目链接。

# python # java # json # sql # database
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

当 AI 修图师装上“万能插头“：MCP 如何改变修图工作流

avatar AI编程社区
cover

Claude API + Python实战：结构化输出后，如何拦住“看起来正确”的JSON

avatar AI编程社区
cover

AI Agent的应用场景

avatar AI编程社区