269 lines
8.0 KiB
Markdown
269 lines
8.0 KiB
Markdown
# video-auth模块目录架构、功能及接口文档
|
|
|
|
## 一、目录架构
|
|
|
|
```
|
|
video-auth/
|
|
├── src/
|
|
│ ├── main/
|
|
│ │ ├── java/
|
|
│ │ │ └── com/nuaa/video/auth/
|
|
│ │ │ ├── config/ # 配置类
|
|
| | | │ ├── RedisConfig.java # Redis配置
|
|
│ │ │ │ └── SecurityConfig.java # 安全配置
|
|
│ │ │ ├── controller/ # 控制器
|
|
│ │ │ │ └── AuthController.java # 认证控制器
|
|
│ │ │ ├── dto/ # 数据传输对象
|
|
│ │ │ │ ├── LoginDTO.java # 登录请求DTO
|
|
│ │ │ │ ├── RegisterDTO.java # 注册请求DTO
|
|
│ │ │ │ └── TokenInfoDTO.java # 令牌信息DTO
|
|
│ │ │ ├── entity/ # 实体类
|
|
│ │ │ │ ├── AuthUser.java # 用户实体
|
|
│ │ │ │ ├── AuthRole.java # 角色实体
|
|
│ │ │ │ ├── AuthPermission.java # 权限实体
|
|
│ │ │ │ ├── AuthUserRole.java # 用户角色关联实体
|
|
│ │ │ │ └── AuthRolePermission.java # 角色权限关联实体
|
|
│ │ │ ├── filter/ # 过滤器
|
|
│ │ │ │ └── JwtAuthenticationFilter.java # JWT认证过滤器
|
|
│ │ │ ├── mapper/ # MyBatis映射接口
|
|
│ │ │ │ ├── AuthUserMapper.java # 用户Mapper
|
|
│ │ │ │ ├── AuthRoleMapper.java # 角色Mapper
|
|
│ │ │ │ ├── AuthPermissionMapper.java # 权限Mapper
|
|
│ │ │ │ ├── AuthUserRoleMapper.java # 用户角色Mapper
|
|
│ │ │ │ └── AuthRolePermissionMapper.java # 角色权限Mapper
|
|
│ │ │ ├── service/ # 服务层
|
|
│ │ │ │ ├── AuthUserService.java # 用户服务接口
|
|
│ │ │ │ ├── CaptchaService.java # 验证码服务接口
|
|
│ │ │ │ └── impl/ # 实现类
|
|
│ │ │ │ ├── AuthUserServiceImpl.java
|
|
│ │ │ │ └── CaptchaServiceImpl.java
|
|
│ │ │ ├── utils/ # 工具类
|
|
│ │ │ │ ├── RedisUtils.java # Redis工具类
|
|
│ │ │ │ └── JwtUtils.java # JWT工具类
|
|
│ │ │ └── AuthApplication.java # 启动类
|
|
│ │ └── resources/
|
|
│ │ ├── mapper/ # MyBatis XML映射文件
|
|
│ │ │ └── AuthUserMapper.xml
|
|
│ │ ├── application.yml # 配置文件
|
|
│ │ ├── application-dev.yml # 开发环境配置
|
|
└── pom.xml
|
|
```
|
|
|
|
## 二、功能概述
|
|
|
|
### 1. 核心功能
|
|
|
|
- **用户认证**：登录、注册、令牌刷新、登出
|
|
- **安全管理**：JWT生成与验证、密码加密
|
|
- **角色权限**：用户角色和权限的管理
|
|
- **验证码服务**：生成和验证图形验证码
|
|
|
|
### 2. 业务流程
|
|
|
|
1. **用户注册**：用户提交注册信息 → 验证码验证 → 创建用户 → 分配默认角色
|
|
2. **用户登录**：用户提交登录信息 → 验证用户凭证 → 生成JWT令牌 → 缓存用户认证信息
|
|
3. **认证鉴权**：请求携带JWT令牌 → JWT过滤器验证令牌 → 提取用户信息 → 设置安全上下文 → 授权访问
|
|
|
|
## 三、接口文档
|
|
|
|
### 1. 用户登录
|
|
|
|
- **URI**: `/auth/login`
|
|
- **方法**: POST
|
|
- **描述**: 用户登录并获取令牌
|
|
- **请求Body**:
|
|
```json
|
|
{
|
|
"username": "admin",
|
|
"password": "admin123",
|
|
"captcha": "1a2b",
|
|
"captchaKey": "abcd1234"
|
|
}
|
|
```
|
|
- **响应**:
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "操作成功",
|
|
"data": {
|
|
"accessToken": "eyJhbGciOiJIUzI1NiJ9...",
|
|
"refreshToken": "nQs6NGPzAJbfw5ddsSVGY2iqAomOmGW9",
|
|
"tokenType": "Bearer",
|
|
"expiresIn": 86400,
|
|
"userId": 1,
|
|
"username": "admin"
|
|
}
|
|
}
|
|
```
|
|
- **错误码**:
|
|
- `400`: 参数错误(如验证码错误)
|
|
- `401`: 用户名或密码错误
|
|
- `403`: 账号已被禁用
|
|
|
|
### 2. 用户注册
|
|
|
|
- **URI**: `/auth/register`
|
|
- **方法**: POST
|
|
- **描述**: 注册新用户
|
|
- **请求Body**:
|
|
```json
|
|
{
|
|
"username": "newuser",
|
|
"password": "password123",
|
|
"confirmPassword": "password123",
|
|
"email": "user@example.com",
|
|
"phone": "13800138000",
|
|
"captcha": "1a2b",
|
|
"captchaKey": "abcd1234"
|
|
}
|
|
```
|
|
- **响应**:
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "操作成功",
|
|
"data": "注册成功"
|
|
}
|
|
```
|
|
- **错误码**:
|
|
- `400`: 参数错误(如密码不匹配、验证码错误)
|
|
- `1002`: 用户名已存在
|
|
|
|
### 3. 获取验证码
|
|
|
|
- **URI**: `/auth/captcha`
|
|
- **方法**: GET
|
|
- **描述**: 生成图形验证码
|
|
- **响应**:
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "操作成功",
|
|
"data": {
|
|
"captchaKey": "abcd1234",
|
|
"captchaImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEU..."
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4. 刷新令牌
|
|
|
|
- **URI**: `/auth/refresh`
|
|
- **方法**: POST
|
|
- **描述**: 使用刷新令牌获取新的访问令牌
|
|
- **请求参数**:
|
|
- `refreshToken`: 刷新令牌字符串
|
|
- **响应**:
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "操作成功",
|
|
"data": {
|
|
"accessToken": "eyJhbGciOiJIUzI1NiJ9...",
|
|
"refreshToken": "new_refresh_token",
|
|
"tokenType": "Bearer",
|
|
"expiresIn": 86400,
|
|
"userId": 1,
|
|
"username": "admin"
|
|
}
|
|
}
|
|
```
|
|
- **错误码**:
|
|
- `401`: 刷新令牌无效或已过期
|
|
|
|
### 5. 用户登出
|
|
|
|
- **URI**: `/auth/logout`
|
|
- **方法**: POST
|
|
- **描述**: 用户登出，清除令牌
|
|
- **请求头**:
|
|
- `Authorization`: Bearer {accessToken}
|
|
- **响应**:
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "操作成功",
|
|
"data": null
|
|
}
|
|
```
|
|
|
|
### 6. 获取当前用户信息
|
|
|
|
- **URI**: `/auth/current`
|
|
- **方法**: GET
|
|
- **描述**: 获取当前登录用户的详细信息
|
|
- **请求头**:
|
|
- `Authorization`: Bearer {accessToken}
|
|
- **响应**:
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "操作成功",
|
|
"data": {
|
|
"id": 1,
|
|
"username": "admin",
|
|
"email": "admin@example.com",
|
|
"phone": "13800138000",
|
|
"status": 1,
|
|
"lastLoginTime": "2024-03-30T12:30:45",
|
|
"lastLoginIp": "192.168.1.1",
|
|
"roles": ["USER_ADMIN"]
|
|
}
|
|
}
|
|
```
|
|
- **错误码**:
|
|
- `401`: 未授权
|
|
- `404`: 用户不存在
|
|
|
|
## 四、数据库设计
|
|
|
|
认证模块涉及的主要数据库表：
|
|
|
|
### 1. auth_user (用户表)
|
|
- `id`: 用户ID (主键)
|
|
- `username`: 用户名
|
|
- `password`: 加密密码
|
|
- `salt`: 加密盐值
|
|
- `email`: 邮箱
|
|
- `phone`: 手机号
|
|
- `status`: 状态(0:禁用,1:正常)
|
|
- `last_login_time`: 最后登录时间
|
|
- `last_login_ip`: 最后登录IP
|
|
|
|
### 2. auth_role (角色表)
|
|
- `id`: 角色ID (主键)
|
|
- `name`: 角色名称
|
|
- `code`: 角色编码
|
|
- `description`: 角色描述
|
|
|
|
### 3. auth_permission (权限表)
|
|
- `id`: 权限ID (主键)
|
|
- `name`: 权限名称
|
|
- `code`: 权限编码
|
|
- `description`: 权限描述
|
|
|
|
### 4. auth_user_role (用户角色关联表)
|
|
- `id`: 主键
|
|
- `user_id`: 用户ID (外键)
|
|
- `role_id`: 角色ID (外键)
|
|
|
|
### 5. auth_role_permission (角色权限关联表)
|
|
- `id`: 主键
|
|
- `role_id`: 角色ID (外键)
|
|
- `permission_id`: 权限ID (外键)
|
|
|
|
## 五、认证流程说明
|
|
|
|
1. **JWT认证流程**:
|
|
- 用户登录成功后，服务端生成JWT令牌和刷新令牌
|
|
- 客户端请求时在请求头中携带JWT令牌
|
|
- 服务端通过JwtAuthenticationFilter验证令牌
|
|
- 验证通过后，设置SecurityContext并放行请求
|
|
|
|
2. **权限校验流程**:
|
|
- 用户登录时加载其角色和权限
|
|
- 将权限信息缓存到Redis中
|
|
- 请求鉴权时从SecurityContext获取用户信息
|
|
- 根据用户角色和权限决定是否允许访问
|
|
|
|
video-auth模块提供了完整的用户认证、授权和安全管理功能，为整个视频平台提供统一的身份验证服务。 |