＜span class=“js_title_inner“＞Surpass API权限开放平台 完全使用手册＜/span＞
🚀 Surpass API权限开放平台 完全使用手册
📖 项目简介
Surpass 是一个企业级API权限开放平台，专为REST API资源提供无状态认证和调用服务。该平台实现了企业统一权限管理，支持通过SQL配置即可定义RESTful OpenAPI接口，无需编写代码。
✨ 核心特性
• 🔐 无状态认证：支持JWT令牌认证
• 🛡️ RBAC权限管理：基于角色的访问控制
• 📝 SQL配置接口：无需代码开发，SQL配置即可定义API
• 📚 Swagger自动生成：自动生成API文档
• 🎯 REST API标准化：符合RESTful规范
• 🏢 企业级统一管理：集中管理所有API资源
🏗️ 系统架构
核心组件
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 前端UI │ │ API网关 │ │ 数据库 │
│ Vue.js │◄──►│ Spring Boot │◄──►│ MySQL 8.4.2+ │
│ Element Plus │ │ JWT认证 │ │ 权限存储 │
└─────────────────┘ └─────────────────┘ └─────────────────┘数据库表结构
• auth_resource：API资源表
• auth_role：角色表
• auth_user：用户表
• auth_role_resource_bind：角色资源绑定表
• auth_user_role_bind：用户角色绑定表
🛠️ 快速部署指南
环境要求
• JDK: 17+
• MySQL: 8.4.2+
• Node.js: 推荐16+
• 操作系统: Windows/Linux/macOS
第一步：数据库初始化
-- 创建数据库
CREATE DATABASE surpass CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-- 导入表结构（执行 db/1.0.0/schema.sql）
-- 导入初始数据（执行 db/1.0.0/data.sql）第二步：后端服务启动
# 1. 克隆项目
git clone https://gitee.com/dromara/surpass.git
cd surpass
# 2. 修改配置文件
# 编辑 application.yml 配置数据库连接信息
# 3. 启动服务
mvn spring-boot:run
# 或打包运行
mvn clean package
java -jar target/surpass-*.jar第三步：前端服务启动
# 1. 进入前端目录
cd surpass-ui
# 2. 安装依赖
npm install
# 3. 启动开发服务器
npm run dev
# 4. 生产环境构建
npm run build访问地址：http://localhost:3154
📋 核心功能使用
🔐 用户认证
1. 用户注册登录
• 支持用户名、手机号、邮箱登录
• 密码采用MD5+盐值加密存储
• 支持多端登录（Web、Android、iOS、Windows、Mac、Linux）
2. JWT令牌获取
POST /auth/login
{
"username": "admin",
"password": "password"
}
# 返回JWT令牌
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires": 3600
}🛡️ 权限管理
1. 角色管理
• 创建角色：管理员、开发者、访客等
• 角色权限配置：细粒度权限控制
• 角色状态管理：启用/禁用角色
2. 资源管理
• API资源注册：支持GET、POST、PUT、DELETE、PATCH方法
• 资源分类管理：按业务模块分类
• 访问控制：基于URL路径的权限控制
3. 用户授权
• 用户-角色绑定：一个用户可拥有多个角色
• 角色-资源绑定：一个角色可访问多个资源
• 权限继承：支持角色层级管理
📝 OpenAPI配置
1. SQL配置API
-- 示例：查询用户列表
INSERT INTO auth_resource (
name, code, uri, type, method, description
) VALUES (
'用户列表查询',
'user.list',
'/api/users',
'SELECT',
'GET',
'查询系统用户列表'
);
-- 对应的SQL配置
-- SELECT id, username, email, phone FROM auth_user WHERE status = 12. API调试
• Swagger UI集成：可视化API调试
• 在线测试：支持参数传递和响应查看
• 认证测试：支持JWT令牌认证测试
📊 监控与日志
1. 访问日志
• 用户操作日志：登录、注册、登出记录
• API调用日志：接口访问成功/失败记录
• 异常日志：系统错误和异常信息
2. 实时监控
• 在线用户统计
• API调用频率监控
• 系统性能指标
⚙️ 高级配置
JWT配置
jwt:
secret: your-secret-key
expiration: 3600 # 令牌过期时间（秒）
refresh-expiration: 604800 # 刷新令牌过期时间数据库连接配置
spring:
datasource:
url: jdbc:mysql://localhost:3306/surpass?useUnicode=true&characterEncoding=utf8
username: root
password: your-password
driver-class-name: com.mysql.cj.jdbc.DriverCORS配置
cors:
allowed-origins: "*"
allowed-methods: "GET,POST,PUT,DELETE,OPTIONS"
allowed-headers: "*"
allow-credentials: true🔄 常见操作流程
1. 新API接入流程
创建API资源
配置SQL语句
设置访问权限
测试API接口
生成Swagger文档
发布API2. 用户权限配置流程
创建用户
分配角色
配置角色权限
权限验证测试
正式授权🚨 注意事项
安全配置
1. JWT密钥：使用强密钥，定期更换
2. 数据库安全：限制数据库访问权限
3. HTTPS部署：生产环境必须使用HTTPS
4. 密码策略：强制复杂密码要求
性能优化
1. 数据库索引：为常用查询字段添加索引
2. 缓存策略：使用Redis缓存热点数据
3. 连接池配置：合理配置数据库连接池
4. API限流：防止API恶意调用
🆘 故障排查
常见问题
1. JWT令牌过期
问题：API调用返回401未授权
解决：刷新令牌或重新登录
2. 权限不足
问题：API调用返回403禁止访问
解决：检查用户角色和资源权限配置
3. 数据库连接失败
问题：启动时数据库连接异常
解决：检查数据库服务状态和连接配置
日志查看
# 查看应用日志
tail -f logs/surpass.log
# 查看错误日志
grep ERROR logs/surpass.log📚 相关资源
官方文档
• Gitee仓库：https://gitee.com/dromara/surpass
• GitHub仓库：https://github.com/tomsun28/surpass
技术栈
• 后端：Spring Boot + MyBatis + JWT
• 前端：Vue.js + Element Plus + Axios
• 数据库：MySQL 8.4.2+
• 文档：Swagger/OpenAPI 3.0
开源协议
本项目采用 Apache License 2.0 开源协议
🎯 最佳实践
开发建议
1. API设计：遵循RESTful设计原则
2. 权限粒度：按业务需求细化权限控制
3. 版本管理：API版本控制策略
4. 文档维护：及时更新API文档
运维建议
1. 定期备份：数据库定期备份策略
2. 监控告警：设置系统监控和告警
3. 安全审计：定期进行安全审计
4. 性能监控：持续监控系统性能指标
📞 技术支持
如遇到问题，可以通过以下方式获取帮助：
• 提交Issue到Gitee仓库
• 查看项目文档和FAQ
• 参与社区讨论和交流
Surpass API权限开放平台 - 让API管理更简单！ 🎉
本文档基于Surpass项目最新版本编写，如有更新请以官方文档为准。
更多推荐
10
0- 0
已为社区贡献4条内容
所有评论(0)