开源项目推荐SQL API Gateway —— 把 Doris / ClickHouse SQL 变成带审批、限流、熔断的 REST 数据接口项目地址github.com/knowcai/apigeneral当前版本v1.1.0 · Apache 2.0技术栈Spring Boot 3 · Vue 3 · PostgreSQL · Doris / ClickHouse一、项目是什么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/WITHSQL 安全校验 只读数据源开关密钥管理混乱连接串密码明文落库、接口回传密码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_OPENSQL 重试可配置次数与间隔业务异常与超时不重试登录限流防暴力破解内存限流器5. 安全加固v1.1.0 重点SQL 仅允许SELECT/WITH移除SHOW/EXPLAIN等绕过路径500 错误脱敏不泄露数据库内部信息生产环境启动校验 JWT、密钥、禁止 bootstrap-keyJWT CookieSameSiteStrictCORS 收紧默认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.yml8. 工程化成熟Flyway 增量迁移不删业务数据GitHub Actions CI后端mvn test 前端npm run build双语 README、权限文档、E2E 测试脚本四、功能点一览4.1 连接串管理支持DorisMySQL 协议、ClickHouseHTTP / 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 keyKey 自动授权该主题下全部已发布 API无 Key / 无效 Key →401主题禁用 →4034.5 动态数据 API接口格式GET/POST /api/data/v{version}/{theme}/{apiCode}?page1pageSize20参数名值 X-Api-Key: gw_xxxxxxxx统一响应{code:0,message:success,data:{rows:[],total:0,page:1,pageSize:20,hasMore:false},requestId:...}HTTP含义200成功401缺少或无效 API Key403无权限或主题已禁用429限流503熔断中4.6 网关策略全局 / 单 IP / 单 API 三层 QPS可独立开关单 API 熔断默认 20 次调用、失败率 ≥ 50% 触发等待 30s 半开试探429 不计入熔断可配置 fallback JSONSQL 重试默认最多 2 次、间隔 500ms4.7 用户与权限角色能力SUPER_ADMIN用户/主题/调用方/连接串/策略全权限API_EDITOR主题内编辑 API、连接串需审批API_VIEWER只读查看管理端/admin/**需 JWT 登录默认管理员admin/admin123生产务必修改。4.8 监控与审计访问监控异步记录每次数据 API 调用详情操作审计登录、增删改、发布、废弃等管理操作主题 API Key 审计Key 创建/删除/领取事件审批中心待办、历史、撤回4.9 国际化管理台支持中文 / English切换登录页、侧边栏、表单校验、错误提示均已 i18n五、适用场景对内数据 API 平台— 报表、看板、微服务统一取数入口需要审批 审计的数据开放— 金融、政务、大厂数据中台常见诉求快速 SQL 接口化— 不想为每条查询写 Java Controller又要生产级限流熔断多团队共用 Doris / ClickHouse— 用主题隔离资源与 Key避免互相踩脚六、技术栈与部署要求组件版本/说明JDK21后端Spring Boot 3.3、Spring Security、JWT、Flyway前端Vue 3、Vite、Element Plus、vue-i18n元数据库PostgreSQL存配置、日志、审批非业务库业务数据源Doris、ClickHouse可扩展 Trino、StarRocks 等驱动注册Node.js18前端构建快速体验# 后端mvn spring-boot:run# http://localhost:8088# 前端cd frontend npm install npm run dev# http://localhost:5173# 登录admin / admin123七、典型使用流程主题管理— 创建主题指定管理员与成员创建/轮换 API Key连接串管理— 添加 Doris / ClickHouse测试连接API / SQL— 新建 API → 新建版本 → 配置 SQL 模板 → 发布非超管需审批调用— 业务方携带 API Key 请求/api/data/v1/{theme}/{apiCode}运维— 在监控大盘查看 QPS、错误率在策略页调整限流熔断八、总结SQL API Gateway解决的核心问题可以概括为一句话让数仓 SQL 像 REST API 一样被治理——有审批、有鉴权、有限流、有熔断、有审计。如果你正在做 Doris / ClickHouse 对内服务化又不想从零搭一套数据开放平台这个项目可以作为开箱即用的起点。代码开源、文档齐全、CI 通过欢迎 Star 和 Issue。相关链接GitHubknowcai/apigeneral权限说明docs/PERMISSIONS.mdLicenseApache 2.0如需转载请注明出处与项目链接。