surpass - API权限开放平台新手入门指南项目概览属性信息项目名称surpass组织DromaraStars3.4K ⭐⭐⭐Forks1.4K语言Java (56.4%) Vue (30.9%) TypeScript (9.1%)Gitee 仓库https://gitee.com/dromara/surpass[1]最新版本2.0.0开源协议Apache-2.0认证标识GVP (Gitee 最有价值开源项目)项目简介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 │└─────────────────────────────────────────────────────────────┘适用场景 典型应用场景场景说明推荐功能企业 API 网关统一管理企业所有 APIAPI 代理、权限控制低代码平台通过 SQL 快速生成 APISQL 转 API微服务架构统一权限认证JWT、RBAC数据开放平台对外提供数据接口API 签名、频率限制内部系统集成多系统接口统一管理接口编排 目标用户•企业架构师•后端开发者•DevOps 工程师•需要快速构建 API 服务的团队学习曲线难度评估中等 ⭐⭐- 需要一定的 Spring Boot 和数据库基础优势1.零代码开发- SQL 即可定义 API无需编写代码2.文档完善- 提供 SETUP.md 和详细文档3.可视化管理- 管理后台操作直观4.社区活跃- Dromara 社区支持前置知识•Java 基础语法•Spring Boot 基础知识•SQL 基础•了解 RESTful API 概念快速开始1. 环境要求依赖版本要求JDK21Maven3.6数据库MySQL 8.0 / PostgreSQL / SQLite2. 下载与安装# 克隆项目git clone https://gitee.com/dromara/surpass.git # 进入目录cd surpass # 编译项目mvn clean package -DskipTests3. 配置数据库修改application.ymlspring: datasource: url: jdbc:mysql://localhost:3306/surpass?useUnicodetruecharacterEncodingutf-8serverTimezoneAsia/Shanghai username: root password: password driver-class-name: com.mysql.cj.jdbc.Driver4. 启动项目# 运行主类java -jar surpass/target/surpass.jar5. 访问管理后台打开浏览器访问http://localhost:8080默认账号admin/admin6. 快速创建 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 # 安装部署文档使用示例创建一个简单的查询接口接口配置:字段值接口名称查询用户列表请求路径/api/user/list请求方法GET数据源defaultSQL 语句见下方SQL 配置:SELECT id, username, email, phone, status, create_timeFROM sys_userWHERE 11 !--#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?usernameadminstatus1pageNum0pageSize10返回结果:{ code: 200, message: success, data: { list: [ { id: 1, username: admin, email: adminexample.com, phone: 13800138000, status: 1, create_time: 2024-01-01 10:00:00 } ], total: 1 }}优势对比vs 传统 API 开发方面surpass传统方式开发效率高SQL 即可低需编写代码学习成本低高维护成本低高接口文档自动生成手动编写权限控制内置支持需自行开发vs 其他 API 网关方面surpassSpring Cloud GatewayKong上手难度⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐配置复杂度低中高可视化管理✅❌✅SQL 转 API✅❌❌轻量级✅❌❌常见问题Q1: 如何部署到生产环境建议1.使用 MySQL 数据库推荐2.配置 Redis 缓存可选3.使用 Nginx 反向代理4.配置 HTTPSQ2: 支持哪些数据库支持•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 网关设计社区支持⭐⭐⭐⭐⭐Dromara 社区支持综合推荐指数⭐⭐⭐⭐⭐强烈推荐适用人群总结✅ 最适合•需要快速构建 API 的团队•企业级 API 网关需求•低代码平台建设•统一权限管理需求⚠️ 不适合•超大规模分布式场景•需要极致性能的场景建议使用专业网关更新日志v2.0.0 (最新)•✅ 重构架构设计•✅ 优化 SQL 解析引擎•✅ 增强权限控制•✅ 完善 API 编排功能v1.x 版本•基础 API 管理功能•JWT 认证支持•Swagger 集成贡献指南欢迎提交 Issue 和 Pull Request1.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