企业官网建设流程全解析

Surpass快速上手教程：从0到1，30分钟跑通你的第一个零代码SQL OpenAPI接口

【免费下载链接】surpass基于springboot+sureness的面向REST API资源无状态认证权限管理系统项目地址: https://gitcode.com/gh_mirrors/bo/surpass

Surpass是一个基于 Spring Boot 的 API 权限开放平台，核心能力是零代码、用 SQL 定义 RESTful OpenAPI 接口：不用写一行 Java 业务代码，在管理页面填写 SQL 模板就能发布一个标准 API，并自带无状态 Token 认证、RBAC 权限控制和调用审计。本教程面向新手，带你从 0 到 1，30 分钟跑通第一个"只写 SQL"的 OpenAPI 接口。

一、1分钟认识 Surpass

Surpass 的定位可以用一句话概括：把数据库里的表，通过 SQL 模板，变成带权限管控的 REST API。

登录后即可看到仪表盘，集中展示应用、客户端、接口与调用量等核心数据：

二、环境准备与一键安装步骤

环境要求

• JDK 17+
• MySQL 8.4+
• Gradle（项目已内置 wrapper，无需单独安装）

快速安装步骤

1. 克隆仓库：

git clone https://gitcode.com/gh_mirrors/bo/surpass cd surpass

2. 创建数据库并初始化脚本（表结构 + 基础数据），脚本位于 db/surpass_v2.0.0.sql：

mysql -uroot -p < db/surpass_v2.0.0.sql

3. 修改数据源配置后，启动管理端（surpass-web）与 API 网关端（surpass-web-api）：

./gradlew :surpass:surpass-web:bootRun ./gradlew :surpass:surpass-web-api:bootRun

启动后浏览器访问管理端，使用初始账号 admin 登录即可进入控制台。

三、30分钟上手：发布你的第一个 OpenAPI

整个流程只有 5 步，全部在页面上完成。

步骤1：配置数据源

进入「数据源」页面，填写 MySQL 连接信息（地址、库名、账号、密码），保存后平台会校验连接是否可用。这是后续 SQL 模板执行的目标库：

步骤2：创建应用

在「应用管理」中创建应用（例如demo），填写应用名称、编码和上下文路径（如/demo）。API 最终发布后会挂载在应用上下文路径 + 接口路径下：

步骤3：编写 SQL，定义 OpenAPI 接口

进入「OpenAPI 配置」页面，这是整个平台的核心。你只需要做三件事：

1. 填写接口信息：名称、HTTP 方法（GET/POST）、路径；
2. 编写 SQL 模板，用#{参数名}声明入参，例如：

select * from surpass_userinfo where username=#{username}

3. 定义参数规则（必填、取值范围）与响应结构，还可以开启分页与限流。

界面上还能直接看到 SQL 编辑器、参数定义和版本状态：

对应的前端页面源码在 Version.vue，SQL 模板、参数定义等数据结构可参考 db/surpass_v2.0.0.sql 中的surpass_api_version表。

步骤4：提交版本并发布

接口保存后是"草稿"状态，走草稿 → 待发布 → 已发布的版本流。发布后，网关端即刻生效，无需重启服务；之后修改 SQL 会产生新版本，支持版本对比与回退。

步骤5：创建客户端并真实调用

接口发布还差最后一步——认证。进入「客户端」页面创建调用方，获得clientId/clientSecret，按需设置 IP 白名单：

客户端先调用/token端点换取访问令牌（支持过期刷新）：

curl -X POST http://localhost:port/token \ -d "clientId=xxx" -d "clientSecret=xxx"

令牌签发逻辑见 TokenEndpoint.java。拿到 accessToken 后，请求时带上令牌即可访问接口，网关会完成解析、鉴权与 SQL 执行，核心入口在 ApiGatewayController.java：

curl "http://localhost:port/demo/user?username=admin" \ -H "Authorization: Bearer <accessToken>"

平台自带 Debug 面板，发布前就能在页面上直接试跑接口、查看入参与返回：

四、配置权限：让接口"只对对的人开放"

Surpass 基于经典 RBAC 模型（用户-角色-应用-资源），全部页面化配置：

• 角色管理：创建角色，为角色勾选应用与资源权限；
• 客户端权限：控制某个客户端能调用哪些接口；
• 用户授权：把用户挂到角色下，自动继承权限。

五、调用审计：每一次调用都有记录

接口上线后，「审计日志」会记录每次 OpenAPI 调用的接口地址、调用方、IP 归属地、权限校验结果与耗时，出问题时可快速定位：

前端对应页面见 audit-openapi-logs.vue。

六、项目目录速览

七、常见问题 FAQ

Q1：接口发布后为什么调不通？检查三点：客户端是否已授权该接口、请求是否带了有效 accessToken、IP 是否在客户端白名单内。

Q2：SQL 里能写复杂查询吗？可以，SQL 模板走 MyBatis 解析，支持多参数与动态条件；开启"允许分页"后平台会自动注入分页参数。

Q3：改了 SQL 需要重启吗？不需要。走"新版本 → 发布"流程即时生效，旧版本可下线或回退。

八、总结

到这里，你已经完成了 Surpass 的完整上手：

1. 配置数据源 → 2. 创建应用 → 3. 写 SQL 定义接口 → 4. 发布版本 → 5. 客户端认证调用。

整个过程没有写一行后端业务代码，却得到一个带认证、限流、审计和 Swagger 文档的标准 OpenAPI——这正是 Surpass"零代码 SQL 定义 API + 企业统一权限管理"的价值所在。接下来不妨试试给自己的业务表再配一个分页查询接口，体验一下版本管理与权限管控的完整闭环。

【免费下载链接】surpass基于springboot+sureness的面向REST API资源无状态认证权限管理系统项目地址: https://gitcode.com/gh_mirrors/bo/surpass