# springboot-jwt

**Repository Path**: hu_kang/springboot-jwt

## Basic Information

- **Project Name**: springboot-jwt
- **Description**: Spring Boot 3.x + Security + JWT + MyBatis-Plus RBAC 权限认证服务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-05
- **Last Updated**: 2026-06-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring Boot 3.x + Security + JWT + MyBatis-Plus RBAC 权限认证服务

基于 Spring Boot 3.4、Spring Security、JWT、MyBatis-Plus 和 MySQL 的 RBAC（角色-权限）权限认证服务，集成 SpringDoc OpenAPI API 文档界面。

## 技术栈

- Spring Boot 3.4.7
- Spring Security 6.x
- MyBatis-Plus 3.5.9
- JJWT 0.12.6
- SpringDoc OpenAPI 2.8.15 (Swagger UI)
- MySQL 8.0+
- Lombok
- Bean Validation

## RBAC 数据库模型

```
sys_user (用户表)
    └── sys_user_role (用户-角色关联表)
            └── sys_role (角色表)
                    └── sys_role_menu (角色-菜单关联表)
                            └── sys_menu (菜单/权限表)
```

### 表结构说明

| 表名 | 说明 |
|------|------|
| `sys_user` | 系统用户，存储用户信息和账号状态 |
| `sys_role` | 系统角色，如超级管理员、普通用户等 |
| `sys_menu` | 菜单/权限，包含目录、菜单、按钮三种类型 |
| `sys_user_role` | 用户与角色的多对多关联 |
| `sys_role_menu` | 角色与菜单/权限的多对多关联 |

## 快速开始

### 1. 环境要求

- JDK 17+
- Maven 3.6+
- MySQL 8.0+

### 2. 创建数据库

在 MySQL 中执行 `sql/init.sql` 脚本创建数据库和表结构：

```bash
mysql -u root -p < sql/init.sql
```

测试数据会在项目首次启动时由 `DataInitializer` 自动插入，无需手动执行 INSERT 语句。

### 3. 修改数据库配置

编辑 `src/main/resources/application.yml` 中的数据库连接信息：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/rbac_db?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
    username: root      # 修改为你的MySQL用户名
    password: root      # 修改为你的MySQL密码
```

### 4. 启动项目

```bash
mvn spring-boot:run
```

启动后访问:
- 应用: `http://localhost:8080`
- **SpringDoc OpenAPI API 文档: `http://localhost:8080/swagger-ui.html`**

### 5. 生成密码哈希（可选）

如果需要手动生成 BCrypt 密码哈希值：

```bash
# 生成默认密码 123456 的哈希值
mvn spring-boot:run -Dspring-boot.main-class=com.example.security.PasswordGen

# 生成自定义密码的哈希值
mvn spring-boot:run -Dspring-boot.main-class=com.example.security.PasswordGen -Dspring-boot.run.arguments="你的密码"
```

## 测试账号

| 用户名 | 密码 | 角色 | 权限范围 |
|--------|------|------|----------|
| admin | 123456 | 超级管理员 + 普通用户 | 所有权限 |
| zhangsan | 123456 | 普通用户 | 查看用户和角色 |
| lisi | 123456 | 普通用户 | 查看用户和角色 |
| operator | 123456 | 运维人员 | 用户/角色管理（无删除） |

## API 接口

### 认证接口

```
POST /api/auth/login          # 用户登录，返回 JWT Token
```

请求示例:
```json
{
    "username": "admin",
    "password": "123456"
}
```

响应示例:
```json
{
    "code": 200,
    "message": "操作成功",
    "data": {
        "token": "eyJhbGciOiJIUzI1NiJ9...",
        "tokenType": "Bearer",
        "username": "admin",
        "userId": 1
    }
}
```

### 业务接口

```
GET  /api/user/profile?username=xxx    # 查看用户信息 [权限: user:view 或 admin:all]
GET  /api/admin/users                  # 查看所有用户   [权限: admin:all]
```

所有业务接口需要在请求头中携带 JWT Token：

```
Authorization: Bearer <token>
```

### SpringDoc OpenAPI 在线调试

启动项目后打开 `http://localhost:8080/swagger-ui.html`，可以：

1. 展开 **认证接口** → 调用登录接口获取 Token
2. 点击右上角 **Authorize** 按钮，填入 `Bearer <token>` 完成全局认证
3. 之后即可在线调试所有需要权限的接口

## 权限控制说明

权限标识基于 Spring Security 的 `@PreAuthorize` 注解实现方法级权限控制。

| 权限标识 | 说明 |
|----------|------|
| `admin:all` | 超级管理员全局权限 |
| `user:view` | 查看用户 |
| `user:add` | 新增用户 |
| `user:edit` | 编辑用户 |
| `user:delete` | 删除用户 |
| `role:view` | 查看角色 |
| `role:add` | 新增角色 |
| `role:edit` | 编辑角色 |
| `role:delete` | 删除角色 |

## JWT 配置

```yaml
jwt:
  secret: <Base64编码的密钥>    # 生产环境请更换为安全的随机密钥
  expiration: 86400000          # Token过期时间(毫秒) 默认24小时
```

生成安全的 Base64 密钥:
```bash
openssl rand -base64 64
```

## MyBatis-Plus 配置

```yaml
mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true    # 下划线转驼峰
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl  # SQL日志输出
  global-config:
    db-config:
      id-type: auto                       # 主键自增
```

## 项目结构

```
src/main/java/com/example/security/
├── SecurityApplication.java          # 启动类
├── PasswordGen.java                  # BCrypt 密码哈希生成工具（无需数据库）
├── config/
│   ├── SecurityConfig.java           # Spring Security 配置
│   ├── MyBatisPlusConfig.java        # MyBatis-Plus 配置（自动填充）
│   ├── OpenApiConfig.java              # SpringDoc OpenAPI 文档配置
│   └── DataInitializer.java          # 测试数据自动初始化
├── security/
│   ├── JwtAuthenticationFilter.java  # JWT 认证过滤器
│   ├── JwtTokenProvider.java         # JWT Token 工具类
│   └── UserDetailsServiceImpl.java   # 用户详情加载实现
├── controller/
│   ├── AuthController.java           # 认证接口
│   └── UserController.java           # 用户接口
├── service/
│   └── AuthService.java              # 认证服务
├── mapper/
│   ├── SysUserMapper.java            # 用户 Mapper
│   ├── SysRoleMapper.java            # 角色 Mapper
│   ├── SysMenuMapper.java            # 菜单 Mapper
│   ├── SysUserRoleMapper.java        # 用户角色关联 Mapper
│   └── SysRoleMenuMapper.java        # 角色菜单关联 Mapper
├── entity/
│   ├── SysUser.java                  # 用户实体
│   ├── SysRole.java                  # 角色实体
│   ├── SysMenu.java                  # 菜单/权限实体
│   ├── SysUserRole.java              # 用户角色关联实体
│   └── SysRoleMenu.java              # 角色菜单关联实体
├── dto/
│   ├── LoginRequest.java             # 登录请求 DTO
│   └── LoginResponse.java            # 登录响应 DTO
└── common/
    ├── Result.java                   # 统一响应格式
    └── GlobalExceptionHandler.java   # 全局异常处理
```