# spring-security

**Repository Path**: java-lesson/spring-security

## Basic Information

- **Project Name**: spring-security
- **Description**: spring boot + spring security + token
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-29
- **Last Updated**: 2026-05-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring Boot JWT 用户管理系统

## 项目简介

这是一个基于 Spring Boot 4.x 构建的前后端分离用户管理系统，集成了 Spring Security、JWT Token、MyBatis 等技术栈，实现了完整的用户认证、授权和管理功能。系统采用 RESTful API 设计，支持管理员和普通用户的角色区分，提供用户注册、登录、Token 刷新以及后台管理等功能。前端通过 JWT Token 进行身份验证和接口调用。

## 技术栈

- **后端框架**: Spring Boot 4.0.6
- **安全框架**: Spring Security 7.x + OAuth2 Resource Server
- **认证方式**: JWT (JSON Web Token)
- **持久层**: MyBatis 4.0.1
- **数据库**: H2 内存数据库（开发环境）
- **前端技术**: 原生 HTML5/CSS3/JavaScript (前后端分离)
- **构建工具**: Maven
- **Java 版本**: Java 26

## 主要功能

### 1. JWT Token 认证与授权
- 用户注册与登录（返回 JWT Token）
- Access Token 和 Refresh Token 双令牌机制
- Token 自动刷新功能
- 基于角色的访问控制（RBAC）
- 密码加密存储（BCrypt）
- 无状态会话管理

### 2. 用户管理
- 用户信息查看
- 用户编辑与删除
- 密码修改
- 最后登录时间记录

### 3. 前端页面（静态资源）
- 响应式登录/注册页面（HTML5）
- 用户管理界面（HTML5 + JavaScript）
- HTTP 请求封装工具（axios/fetch）
- CSS 样式文件

## 项目结构

```
src/
├── main/java/org/example/springboot/
│   ├── config/                    # 配置类
│   │   ├── JwtConfig.java         # JWT 配置（编码器/解码器）
│   │   └── SecurityConfig.java    # Spring Security 配置
│   ├── controller/api/            # REST API 控制器（前后端分离）
│   │   ├── AuthController.java          # 认证相关接口（登录/注册/刷新Token）
│   │   ├── SystemProfileController.java # 系统配置接口
│   │   └── SystemUserController.java    # 用户管理接口（CRUD）
│   ├── dto/                       # 数据传输对象
│   │   ├── ApiResponse.java       # 统一响应格式
│   │   ├── LoginRequest.java      # 登录请求
│   │   ├── LoginResponse.java     # 登录响应（包含 Token）
│   │   ├── PasswordChangeRequest.java # 密码修改请求
│   │   └── RegisterRequest.java   # 注册请求
│   ├── entity/                    # 实体类
│   │   └── SystemUser.java        # 用户实体
│   ├── mapper/                    # 数据访问层
│   │   └── SystemUserMapper.java  # 用户 Mapper 接口
│   ├── service/                   # 业务逻辑层
│   │   ├── JwtTokenService.java   # JWT Token 服务接口
│   │   ├── SystemUserService.java # 用户服务接口
│   │   └── impl/                  # 服务实现
│   │       ├── JwtTokenServiceImpl.java   # JWT Token 服务实现
│   │       ├── SecurityUserDetailsService.java # 安全用户详情服务
│   │       └── SystemUserServiceImpl.java      # 用户服务实现
│   └── Application.java           # 应用启动类
├── main/resources/
│   ├── mapper/                    # MyBatis XML 映射文件
│   │   └── SystemUserMapper.xml
│   ├── static/                    # 静态资源（前端页面）
│   │   ├── css/                   # 样式文件
│   │   │   ├── auth.css           # 认证页面样式
│   │   │   ├── common.css         # 通用样式
│   │   │   └── users.css          # 用户管理页面样式
│   │   ├── js/                    # JavaScript 文件
│   │   │   └── http.js            # HTTP 请求工具（Token 管理）
│   │   ├── index.html             # 首页/登录页
│   │   ├── register.html          # 注册页面
│   │   └── users.html             # 用户管理页面
│   ├── application.yaml           # 主配置文件
│   ├── application-dev.yaml       # 开发环境配置
│   ├── application-prod.yaml      # 生产环境配置
│   ├── application-test.yaml      # 测试环境配置
│   ├── data.sql                   # 初始化数据
│   └── schema.sql                 # 数据库表结构
└── test/                          # 测试代码
```

## JWT Token 机制

### Token 类型说明

| Token 类型 | 用途 | 有效期 | 特点 |
|-----------|------|--------|------|
| Access Token | 访问受保护资源 | 1 小时 | 短效，用于 API 请求认证 |
| Refresh Token | 刷新 Access Token | 7 天 | 长效，用于获取新的 Access Token |

**工作流程：**
1. 用户登录成功后，服务器返回 Access Token 和 Refresh Token
2. 前端在后续请求中携带 Access Token（Authorization: Bearer <token>）
3. Access Token 过期后，使用 Refresh Token 调用 `/api/auth/refresh` 接口获取新的 Access Token
4. Refresh Token 过期后，需要重新登录

### 前端集成示例

```javascript
// 登录并保存 Token
async function login(username, password) {
  const response = await fetch('/api/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username, password })
  });
  
  const result = await response.json();
  if (result.code === 200) {
    // 保存 Token
    localStorage.setItem('accessToken', result.data.accessToken);
    localStorage.setItem('refreshToken', result.data.refreshToken);
  }
}

// 使用 Token 访问受保护接口
async function getUsers() {
  const token = localStorage.getItem('accessToken');
  const response = await fetch('/api/users', {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    }
  });
  return await response.json();
}

// 刷新 Token
async function refreshToken() {
  const refreshToken = localStorage.getItem('refreshToken');
  const response = await fetch('/api/auth/refresh', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ refreshToken })
  });
  
  const result = await response.json();
  if (result.code === 200) {
    localStorage.setItem('accessToken', result.data.accessToken);
  }
}
```

## 数据库设计

### sys_user 表结构

| 字段名             | 类型           | 说明             |
|-----------------|--------------|----------------|
| id              | BIGINT       | 主键，自增          |
| username        | VARCHAR(50)  | 用户名，唯一         |
| password        | VARCHAR(255) | 密码（BCrypt 加密）  |
| email           | VARCHAR(100) | 邮箱             |
| phone           | VARCHAR(20)  | 手机号            |
| avatar          | VARCHAR(255) | 头像 URL         |
| nickname        | VARCHAR(50)  | 昵称             |
| role            | VARCHAR(20)  | 角色（ADMIN/USER） |
| status          | TINYINT      | 状态（1:正常, 0:禁用） |
| created_at      | TIMESTAMP    | 创建时间           |
| updated_at      | TIMESTAMP    | 更新时间           |
| last_login_time | TIMESTAMP    | 最后登录时间         |

## 快速开始

### 环境要求

- JDK 26+
- Maven 3.6+
- Git

### 安装步骤

1. 克隆项目
```bash
git clone <repository-url>
cd spring-boot
```

2. 编译项目
```bash
mvn clean install
```

3. 运行应用
```bash
mvn spring-boot:run
```

或者打包后运行：
```bash
mvn package
java -jar target/security-token-0.0.1-SNAPSHOT.jar
```

4. 访问应用（前端静态页面）
- 首页/登录: http://localhost:8080/index.html
- 注册页面: http://localhost:8080/register.html
- 用户管理: http://localhost:8080/users.html

### 默认账户

系统预置了两个测试账户：

**管理员账户:**
- 用户名: admin
- 密码: admin123

**普通用户账户:**
- 用户名: user
- 密码: user123

## API 接口文档

### 📖 SpringDoc OpenAPI 交互式文档

本项目已集成 **SpringDoc OpenAPI 3.0.3**（支持 Spring Boot 4.x），自动生成交互式 API 文档。

#### 访问地址

启动应用后，可以通过以下地址访问 API 文档：

1. **Swagger UI（推荐）** - http://localhost:8080/swagger-ui.html
   - 可视化的交互式文档界面
   - 可以直接测试 API 接口
   - 支持 JWT Token 认证

2. **OpenAPI JSON** - http://localhost:8080/v3/api-docs
   - 标准的 OpenAPI 3.0 JSON 格式
   - 可用于导入到 Postman、Insomnia 等工具

3. **OpenAPI YAML** - http://localhost:8080/v3/api-docs.yaml
   - YAML 格式的 API 文档

#### 🔐 使用 JWT Token 测试

在 Swagger UI 中测试需要认证的接口时：

1. 先调用 `/api/auth/login` 接口获取 Access Token
2. 复制返回的 `accessToken`
3. 在 Swagger UI 右上角点击 **Authorize** 按钮
4. 输入：`Bearer {your-access-token}`
5. 点击 **Authorize** 确认
6. 现在可以测试需要认证的接口了

#### 🎯 API 分组

文档按功能分为以下几个模块：

1. **认证管理** (`/api/auth`)
   - 用户登录
   - 用户注册
   - Token 刷新

2. **用户管理** (`/api/users`)
   - 获取所有用户
   - 根据 ID 获取用户
   - 更新用户信息
   - 删除用户
   - 修改密码

3. **个人资料** (`/api/system/profile`)
   - 获取当前用户资料

### 📝 核心接口说明

以下是系统的主要 API 接口概览，详细信息请访问 Swagger UI 查看完整文档。

### ⚙️ 配置说明

API 文档的配置位于 `application.yaml`：

```yaml
springdoc:
  api-docs:
    path: /v3/api-docs
    enabled: true
  swagger-ui:
    path: /swagger-ui.html
    enabled: true
    tags-sorter: alpha
    operations-sorter: alpha
  default-flat-param-object: true
```

### 🚀 生产环境建议

在生产环境中，建议禁用 API 文档以避免信息泄露：

```yaml
# application-prod.yaml
springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false
```

或通过环境变量控制：

```bash
SPRINGDOC_SWAGGER_UI_ENABLED=false
SPRINGDOC_API_DOCS_ENABLED=false
```

## 安全特性

1. **JWT Token 认证**: 无状态认证，适合前后端分离架构
2. **双令牌机制**: Access Token（短效）+ Refresh Token（长效）
3. **密码加密**: 使用 BCrypt 算法对密码进行加密存储
4. **角色权限**: 基于 Spring Security 的角色访问控制（SCOPE_ADMIN）
5. **HTTPS 建议**: 生产环境建议使用 HTTPS 传输 Token

## 开发指南

### 添加新功能

1. 在 `entity` 包中定义实体类
2. 在 `mapper` 包中创建 Mapper 接口和对应的 XML 文件
3. 在 `service` 包中定义服务接口和实现
4. 在 `controller/api` 包中创建 REST API 控制器
5. 在 `static` 目录中添加前端页面（HTML/CSS/JS）

### 前端集成说明

前端需要在每个 API 请求中携带 JWT Token：

```javascript
// 示例：使用 fetch 发送请求
const token = localStorage.getItem('accessToken');
fetch('/api/users', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});
```

**Token 存储建议：**
- Access Token: 存储在内存或 sessionStorage
- Refresh Token: 存储在 localStorage（注意 XSS 防护）
- 实现 Token 自动刷新逻辑

### JWT 配置

在 `application.yaml` 中配置 JWT 相关参数：

```yaml
app:
  jwt:
    secret: "your-secret-key-at-least-32-bytes"  # 至少 32 字节
    issuer: "http://localhost:8080"               # Token 签发者
    access-token-expiration: 3600000              # Access Token 有效期（1小时）
    refresh-token-expiration: 604800000           # Refresh Token 有效期（7天）
```

**生产环境建议：**
- 使用环境变量或配置中心管理 JWT Secret
- 定期更换密钥

## 部署

### 本地部署
按照快速开始部分的步骤即可在本地运行。

### 生产部署
1. 设置 `SPRING_PROFILES_ACTIVE=prod` 环境变量
2. 配置生产环境的数据库连接
3. 使用 `mvn package` 打包应用
4. 部署到服务器或使用 Docker 容器化部署

## 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目！

## 许可证

本项目采用 MIT 许可证。