surpass - API权限开放平台新手入门指南

项目概览

项目简介

surpass 是 Dromara 开源社区推出的一款 API 权限开放平台，面向 REST API 资源提供无状态认证和调用能力，实现企业统一权限管理。

核心价值

•零代码开发 - 通过 SQL 定义 RESTful OpenAPI 接口•统一权限管理 - 支持 JWT、RBAC 资源权限管理•开箱即用 - 内置 Swagger 自动生成•企业级能力 - 支持 API 代理、权限认证、接口编排

核心功能特性

1. API 开放平台

•✅ SQL 转 API - 通过 SQL 语句快速定义 RESTful 接口•✅ API 代理 - 支持代理转发外部 API•✅ 接口编排 - 支持多接口组合调用•✅ Swagger 自动生成 - 文档自动生成，便于接口调试

2. 权限管理

•✅ JWT 认证 - 无状态 Token 认证•✅ RBAC 权限 - 基于角色的访问控制•✅ 统一权限 - 企业级统一权限管理•✅ 资源权限 - 细粒度的资源级权限控制

3. 安全特性

•✅ 接口签名 - API 请求参数签名验证•✅ 访问频率限制 - 防止恶意请求•✅ IP 白名单 - 限制访问来源•✅ 敏感数据脱敏 - 保护敏感信息

4. 管理后台

•✅ 可视化管理 - 友好的 Web 管理界面•✅ 实时监控 - API 调用统计和监控•✅ 日志审计 - 完整的操作日志记录•✅ 配置管理 - 灵活的系统配置

技术架构

┌─────────────────────────────────────────────────────────────┐│                      surpass                              │├─────────────────────────────────────────────────────────────┤│  surpass-ui (前端)                                        ││  ├── Vue 3 + TypeScript                                   ││  ├── Element Plus 组件库                                  ││  └── 管理后台界面                                         │├─────────────────────────────────────────────────────────────┤│  surpass (后端)                                           ││  ├── Spring Boot 3.x                                     ││  ├── Spring Security                                     ││  ├── MyBatis Plus                                        ││  ├── JWT Token                                          ││  └── Swagger UI                                          │├─────────────────────────────────────────────────────────────┤│  db (数据库)                                             ││  └── MySQL / PostgreSQL / SQLite                         │└─────────────────────────────────────────────────────────────┘

适用场景

🌟 典型应用场景

🎯 目标用户

•企业架构师•后端开发者•DevOps 工程师•需要快速构建 API 服务的团队

学习曲线

难度评估

中等 ⭐⭐ - 需要一定的 Spring Boot 和数据库基础

优势

1.零代码开发 - SQL 即可定义 API，无需编写代码2.文档完善 - 提供 SETUP.md 和详细文档3.可视化管理 - 管理后台操作直观4.社区活跃 - Dromara 社区支持

前置知识

•Java 基础语法•Spring Boot 基础知识•SQL 基础•了解 RESTful API 概念

快速开始

1. 环境要求

2. 下载与安装

# 克隆项目git clone https://gitee.com/dromara/surpass.git
# 进入目录cd surpass
# 编译项目mvn clean package -DskipTests

3. 配置数据库

修改 application.yml：

spring:  datasource:    url: jdbc:mysql://localhost:3306/surpass?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai    username: root    password: password    driver-class-name: com.mysql.cj.jdbc.Driver

4. 启动项目

# 运行主类java -jar surpass/target/surpass.jar

5. 访问管理后台

打开浏览器访问：http://localhost:8080

默认账号：admin / admin

6. 快速创建 API

步骤 1: 登录管理后台

步骤 2: 进入「API管理」→「新增接口」

步骤 3: 填写接口信息

-- SQL 示例：查询用户列表SELECT id, username, email, create_time FROM sys_user WHERE status = 1 ORDER BY create_time DESC

步骤 4: 保存并测试接口

项目结构

surpass/├── db/                    # 数据库初始化脚本│   └── init.sql           # 初始化 SQL├── image/                 # 项目图片资源├── surpass-ui/            # 前端项目│   ├── src/│   │   ├── components/    # 组件│   │   ├── views/         # 页面│   │   └── api/           # API 调用│   ├── package.json│   └── vite.config.ts├── surpass/               # 后端项目│   ├── src/│   │   ├── main/│   │   │   ├── java/│   │   │   │   └── com/dromara/surpass/│   │   │   │       ├── controller/   # 控制器│   │   │   │       ├── service/     # 服务层│   │   │   │       ├── mapper/      # 数据访问│   │   │   │       ├── entity/      # 实体类│   │   │   │       ├── config/      # 配置类│   │   │   │       ├── security/    # 安全认证│   │   │   │       └── SurpassApplication.java│   │   │   └── resources/│   │   │       ├── application.yml  # 配置文件│   │   │       └── schema.sql      # 数据库DDL│   └── pom.xml├── .gitignore├── LICENSE├── README.md└── SETUP.md               # 安装部署文档

使用示例

创建一个简单的查询接口

接口配置:

SQL 配置:

SELECT     id,    username,    email,    phone,    status,    create_timeFROM sys_userWHERE 1=1    <!--#if( ${username} )-->    AND username LIKE CONCAT('%', #{username}, '%')    <!--#end-->    <!--#if( ${status} )-->    AND status = #{status}    <!--#end-->ORDER BY create_time DESCLIMIT #{pageSize} OFFSET #{pageNum}

测试调用:

# 不带参数curl http://localhost:8080/api/user/list
# 带参数curl "http://localhost:8080/api/user/list?username=admin&status=1&pageNum=0&pageSize=10"

返回结果:

{  "code": 200,  "message": "success",  "data": {    "list": [      {        "id": 1,        "username": "admin",        "email": "admin@example.com",        "phone": "13800138000",        "status": 1,        "create_time": "2024-01-01 10:00:00"      }    ],    "total": 1  }}

优势对比

vs 传统 API 开发

vs 其他 API 网关

常见问题

Q1: 如何部署到生产环境？

建议：

1.使用 MySQL 数据库（推荐）2.配置 Redis 缓存（可选）3.使用 Nginx 反向代理4.配置 HTTPS

Q2: 支持哪些数据库？

支持：

•MySQL 8.0+•PostgreSQL•SQLite（适合开发测试）

Q3: 如何添加自定义业务逻辑？

方式：

1.在 surpass/src/main/java/com/dromara/surpass/service/ 下添加服务类2.创建自定义 Controller3.通过 API 编排功能组合调用

Q4: 如何配置 JWT 过期时间？

sa-token:  # Token 有效期（秒）  timeout: 86400  # 活跃时间（秒）  activity-timeout: 1800

学习资源

官方资源

•🌐 Gitee 仓库：https://gitee.com/dromara/surpass^[2]•📖 安装文档：SETUP.md•💬 技术交流：Dromara 社区•📦 示例项目：项目内置 demo

推荐学习路径

1.第一天：环境搭建，运行项目，熟悉管理后台2.第二天：学习 SQL 转 API 功能3.第三天：学习权限管理和 JWT 配置4.第四天：学习 API 代理和接口编排5.第五天：部署到测试环境

项目推荐指数

综合推荐指数：⭐⭐⭐⭐⭐ 强烈推荐！

适用人群总结

✅ 最适合

•需要快速构建 API 的团队•企业级 API 网关需求•低代码平台建设•统一权限管理需求

⚠️ 不适合

•超大规模分布式场景•需要极致性能的场景（建议使用专业网关）

更新日志

v2.0.0 (最新)

•✅ 重构架构设计•✅ 优化 SQL 解析引擎•✅ 增强权限控制•✅ 完善 API 编排功能

v1.x 版本

•基础 API 管理功能•JWT 认证支持•Swagger 集成

贡献指南

欢迎提交 Issue 和 Pull Request！

1.Fork 本项目2.创建功能分支 (git checkout -b feature/xxx)3.提交更改 (git commit -m 'Add xxx')4.推送到分支 (git push origin feature/xxx)5.创建 Pull Request

结语

surpass 是一款优秀的企业级 API 权限开放平台，通过零代码方式快速构建 RESTful API，非常适合企业内部系统集成和数据开放场景。

对于需要快速搭建 API 服务的团队来说，surpass 是一个理想的选择！

报告生成时间：2026年5月 数据来源：Gitee 官方数据

References

[1]: https://gitee.com/dromara/surpass
[2]: https://gitee.com/dromara/surpass