# springboot-rabc-demo **Repository Path**: gethug/springboot-rabc-demo ## Basic Information - **Project Name**: springboot-rabc-demo - **Description**: 基于Springboot的 “用户/角色/权限“系统（Role-Based Access Control system）。基于该场景构建一个Springboot应用开发的入门代码框架。 - **Primary Language**: Java - **License**: MulanPSL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-03-09 - **Last Updated**: 2026-03-24 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # RBAC权限管理系统 - Spring Boot教学项目 ## 📖 项目简介 这是一个基于 **Spring Boot + MyBatis + Spring Security + JWT** 的角色访问控制系统（RBAC），专用于教学目的，展示如何从零开始构建一个完整的企业级权限管理系统。 ### 🎯 适用对象 - 学习Spring Boot框架的开发者 - 需要理解RBAC权限模型的学生 - 希望掌握JWT认证的开发者 - 学习MyBatis和Spring Security整合的开发者 ### 📚 项目特点 - ✅ **教学导向**：详细的代码注释和教学说明 - ✅ **循序渐进**：从环境搭建到测试验证的完整流程 - ✅ **实战项目**：真实的业务场景和代码示例 - ✅ **最佳实践**：遵循Spring Boot和RESTful设计规范 - ✅ **完整文档**：包含9个章节的详细教程 ## 🚀 快速开始 ### 环境要求 - JDK 17+ - Gradle 9.x - IDE: IntelliJ IDEA / Eclipse / VS Code ### 运行项目 ```bash # 1. 进入项目目录 cd backend # 2. 构建项目 ./gradlew build # 3. 运行项目 ./gradlew bootRun # 4. 访问Swagger UI 浏览器打开: http://localhost:8080/swagger-ui.html ``` ### 测试API ```bash # 注册新用户 curl -X POST http://localhost:8080/api/auth/register \ -H 'Content-Type: application/json' \ -d '{ "username": "testuser", "password": "password123", "confirmPassword": "password123", "email": "testuser@example.com" }' # 登录获取Token curl -X POST http://localhost:8080/api/auth/login \ -H 'Content-Type: application/json' \ -d '{ "username": "testuser", "password": "password123" }' # 使用Token访问受保护的接口 curl -X GET http://localhost:8080/api/users/me \ -H 'Authorization: Bearer <你的JWT_TOKEN>' ``` ## 📖 教程文档 详细的step-by-step教程位于 `backend/docs/` 目录下： | 章节 | 标题 | 内容 | 文件大小 | |------|------|------|----------| | 第0章 | [项目概述](./backend/docs/00-项目概述.md) | 项目介绍、技术栈、学习路径 | 8.1K | | 第1章 | [环境搭建与项目初始化](./backend/docs/01-环境搭建与项目初始化.md) | JDK、Gradle、Spring Boot项目创建 | 11K | | 第2章 | [数据模型设计](./backend/docs/02-数据模型设计.md) | User、Role、Permission实体类设计 | 22K | | 第3章 | [数据库设计与配置](./backend/docs/03-数据库设计与配置.md) | H2数据库、表结构、初始化数据 | 19K | | 第4章 | [MyBatis数据访问层](./backend/docs/README.md#第4章mybatis数据访问层) | Mapper接口、XML映射、动态SQL | 文档中 | | 第5章 | [Spring Security基础配置](./backend/docs/README.md#第5章spring-security基础配置) | 安全配置、认证授权 | 文档中 | | 第6章 | [JWT认证实现](./backend/docs/README.md#第6章jwt认证实现) | JWT工具类、认证过滤器 | 文档中 | | 第7章 | [REST API控制器](./backend/docs/README.md#第7章rest-api控制器) | Controller开发、请求验证 | 文档中 | | 第8章 | [Swagger API文档集成](./backend/docs/08-SwaggerAPI文档集成.md) | SpringDoc集成、API文档注解 | 13K | | 第9章 | [测试与验证](./backend/docs/09-测试与验证.md) | 单元测试、接口测试、功能验证 | 17K | **总文档量**: 约100KB的详细教学文档 ### 📚 文档索引 查看 [backend/docs/README.md](./backend/docs/README.md) 获取完整的文档索引和学习路径。 ## 🛠️ 技术栈 | 技术 | 版本 | 用途 | |------|------|------| | Java | 17 | 开发语言 | | Spring Boot | 4.0.3 | 应用框架 | | MyBatis | 4.0.1 | ORM框架 | | Spring Security | 7.0.3 | 安全框架 | | JWT (jjwt) | 0.12.3 | Token生成与验证 | | H2 Database | - | 开发数据库（内存） | | SpringDoc | 2.8.0 | API文档生成 | | Lombok | - | 代码简化 | | Gradle | 9.3.1 | 构建工具 | ## 📁 项目结构 ``` backend/ ├── src/main/java/cn/edu/swu/rbac/ │ ├── Application.java # 启动类 │ ├── config/ # 配置类 │ │ ├── JwtConfig.java # JWT配置 │ │ └── SpringDocConfig.java # Swagger配置 │ ├── controller/ # 控制器层 │ │ ├── AuthController.java # 认证接口 │ │ ├── UserController.java # 用户管理 │ │ ├── RoleController.java # 角色管理 │ │ └── PermissionController.java # 权限管理 │ ├── service/ # 服务层 │ │ ├── AuthService.java │ │ ├── UserService.java │ │ └── impl/ │ ├── mapper/ # 数据访问层 │ │ ├── UserMapper.java │ │ ├── RoleMapper.java │ │ ├── PermissionMapper.java │ │ ├── UserRoleMapper.java │ │ └── RolePermissionMapper.java │ ├── model/ # 实体类 │ │ ├── User.java # 用户实体 │ │ ├── Role.java # 角色实体 │ │ └── Permission.java # 权限实体 │ ├── dto/ # 数据传输对象 │ │ ├── request/ │ │ └── response/ │ ├── security/ # 安全相关 │ │ ├── jwt/ │ │ │ ├── JwtTokenProvider.java # JWT工具类 │ │ │ └── JwtAuthenticationFilter.java # JWT过滤器 │ │ ├── config/ │ │ │ └── SecurityConfig.java # 安全配置 │ │ ├── handler/ │ │ │ ├── JwtAuthenticationEntryPoint.java │ │ │ └── JwtAccessDeniedHandler.java │ │ └── services/ │ │ ├── CustomUserDetailsService.java │ │ └── CustomUserDetails.java │ └── exception/ # 异常处理 │ └── GlobalExceptionHandler.java ├── src/main/resources/ │ ├── application.yaml # 配置文件 │ ├── schema.sql # 数据库表结构 │ ├── data.sql # 初始化数据 │ └── mapper/ # MyBatis映射文件 ├── src/test/ # 测试代码 ├── build.gradle # Gradle构建配置 ├── settings.gradle # Gradle设置 └── docs/ # 项目文档 ├── 00-项目概述.md ├── 01-环境搭建与项目初始化.md ├── 02-数据模型设计.md ├── 03-数据库设计与配置.md ├── 08-SwaggerAPI文档集成.md ├── 09-测试与验证.md └── README.md # 文档索引 ``` ## 🎯 核心功能 ### 1. 用户认证与授权 - ✅ 用户注册（BCrypt密码加密） - ✅ 用户登录（JWT token生成） - ✅ Token验证（自动刷新） - ✅ 基于角色的访问控制 - ✅ 基于权限的细粒度控制 ### 2. RBAC权限模型 ``` 用户 (User) ↓ 多对多 角色 (Role) ↓ 多对多 权限 (Permission) ``` **示例**： - 用户 `admin` 拥有角色 `ROLE_ADMIN` - 角色 `ROLE_ADMIN` 拥有权限 `user:read`, `user:create`, `user:update`, `user:delete` - 因此用户 `admin` 可以进行用户的所有操作 ### 3. RESTful API设计 | 接口 | 方法 | 路径 | 说明 | 权限 | |------|------|------|------|------| | 用户注册 | POST | /api/auth/register | 注册新用户 | 公开 | | 用户登录 | POST | /api/auth/login | 获取JWT token | 公开 | | 当前用户 | GET | /api/users/me | 获取当前用户信息 | 需认证 | | 用户列表 | GET | /api/users | 获取所有用户 | user:read | | 创建用户 | POST | /api/users | 创建新用户 | user:create | | 删除用户 | DELETE | /api/users/{id} | 删除指定用户 | user:delete | | 角色列表 | GET | /api/roles | 获取所有角色 | role:read | | 权限列表 | GET | /api/permissions | 获取所有权限 | permission:read | ### 4. API文档（Swagger） - 📖 Swagger UI: http://localhost:8080/swagger-ui.html - 📄 OpenAPI JSON: http://localhost:8080/v3/api-docs - 🔐 支持JWT认证配置 - 📝 详细的接口说明和示例 ### 5. 数据库 - **开发环境**: H2内存数据库（自动初始化） - **H2控制台**: http://localhost:8080/h2-console - **表结构**: 用户、角色、权限、关联表 - **初始数据**: 4个测试用户、3个角色、13个权限 ## 🧪 测试账户 | 用户名 | 密码 | 角色 | 说明 | |--------|------|------|------| | admin | password123 | ROLE_ADMIN | 管理员（全部权限） | | user | password123 | ROLE_USER | 普通用户（只读权限） | | guest | password123 | ROLE_GUEST | 访客（只读权限） | | disabled | password123 | - | 禁用账户（用于测试） | **注意**: 由于BCrypt哈希的差异，建议使用注册接口创建新用户进行测试。 ## 📊 系统架构 ``` ┌─────────────────┐ │ Swagger UI │ ← API文档界面 └────────┬────────┘ │ ↓ ┌─────────────────┐ │ Controllers │ ← REST API层 └────────┬────────┘ │ ↓ ┌─────────────────┐ │ Spring │ ← 安全过滤层 │ Security │ ← JWT认证 └────────┬────────┘ │ ↓ ┌─────────────────┐ │ Services │ ← 业务逻辑层 └────────┬────────┘ │ ↓ ┌─────────────────┐ │ Mappers │ ← 数据访问层 └────────┬────────┘ │ ↓ ┌─────────────────┐ │ H2 Database │ ← 数据存储层 └─────────────────┘ ``` ## 🎓 学习重点 通过本项目，你将学习到： 1. **Spring Boot核心** - 自动配置原理 - 依赖注入和IoC容器 - Bean生命周期管理 2. **MyBatis使用** - 注解方式开发 - XML映射文件 - 动态SQL编写 - 结果映射 3. **Spring Security** - 认证流程 - 授权机制 - 过滤器链 - JWT集成 4. **RESTful API** - REST设计原则 - HTTP方法使用 - 状态码规范 - API版本管理 5. **数据库设计** - 多对多关系 - 外键约束 - 索引优化 - 数据完整性 6. **测试** - 单元测试 - 集成测试 - API测试 - 安全测试 ## 📖 学习资源 ### 官方文档 - [Spring Boot Documentation](https://spring.io/projects/spring-boot) - [MyBatis Documentation](https://mybatis.org/mybatis-3/) - [Spring Security Reference](https://docs.spring.io/spring-security/reference/) - [SpringDoc Documentation](https://springdoc.org/) ### 推荐阅读 - 《Spring Boot实战》 - 《深入理解Spring Security》 - 《MyBatis从入门到精通》 ## 🤝 贡献指南 欢迎贡献代码和建议！ ### 开发流程 1. Fork本仓库 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 开启Pull Request ### 代码规范 - 遵循阿里巴巴Java开发手册 - 使用Lombok减少样板代码 - 添加详细的注释和文档 - 编写单元测试 ## 📄 许可证 本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件 ## 👥 作者 西南大学 - 计算机与信息科学学院 ## 📞 联系方式 - 项目地址: [GitHub Repository] - 问题反馈: [Issues] --- **开始学习**: 查看 [backend/docs/00-项目概述.md](./backend/docs/00-项目概述.md) 开始你的RBAC系统学习之旅！ **祝你学习愉快！** 🚀