认证模块文档

认证模块文档

功能概述

本系统实现了完整的用户认证功能，采用JWT Token方案，兼容前后端分离和非分离场景。

主要功能

• ✅ 用户注册
• ✅ 用户登录
• ✅ 图形验证码
• ✅ JWT Token认证
• ✅ Token刷新
• ✅ 登录日志记录
• ✅ 多种Token传递方式(Header/Cookie/参数)

---

API接口文档

1. 获取验证码

接口地址 : GET /api/auth/captcha

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "image": "data:image/png;base64,iVBORw0KG...",
    "expiresIn": 300
  }
}

---

2. 用户注册

接口地址 : POST /api/auth/register

请求参数:

{
  "username": "testuser",
  "password": "123456",
  "confirmPassword": "123456",
  "realName": "测试用户",
  "phone": "13800138000",
  "email": "test@example.com",
  "captchaUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "captchaCode": "1234"
}

响应示例:

{
  "code": 200,
  "message": "注册成功",
  "data": null
}

---

3. 用户登录

接口地址 : POST /api/auth/login

请求参数:

{
  "username": "admin",
  "password": "123456",
  "captchaUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "captchaCode": "1234",
  "rememberMe": false
}

响应示例:

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "userId": 1,
    "username": "admin",
    "realName": "管理员",
    "avatar": "/upload/avatar/default.png",
    "roles": ["admin"],
    "permissions": [],
    "expiresIn": 86400
  }
}

---

4. 用户登出

接口地址 : POST /api/auth/logout

请求头:

Authorization: Bearer {token}

响应示例:

{
  "code": 200,
  "message": "登出成功",
  "data": null
}

---

5. 刷新Token

接口地址 : POST /api/auth/refresh

请求头:

Authorization: Bearer {token}

响应示例:

{
  "code": 200,
  "message": "刷新成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "userId": 1,
    "username": "admin",
    "realName": "管理员",
    "avatar": "/upload/avatar/default.png",
    "expiresIn": 86400
  }
}

---

Token传递方式

本系统支持三种Token传递方式，兼容前后端分离和非分离场景:

1. Authorization Header (推荐 - 前后端分离)

GET /api/user/profile
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

2. Cookie (非分离场景)

GET /api/user/profile
Cookie: token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

3. URL参数 (兼容旧系统)

GET /api/user/profile?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

优先级: Header > Cookie > 参数

---

白名单配置

以下接口不需要Token验证:

• /api/auth/login - 登录
• /api/auth/register - 注册
• /api/auth/captcha - 验证码
• /api/doc.html - 接口文档
• /api/swagger-resources/** - Swagger资源
• /api/v3/api-docs/** - API文档
• 静态资源文件

---

数据库表

sys_captcha - 验证码表

CREATE TABLE `sys_captcha` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '验证码ID',
  `uuid` varchar(100) NOT NULL COMMENT '验证码UUID',
  `code` varchar(10) NOT NULL COMMENT '验证码',
  `expire_time` datetime NOT NULL COMMENT '过期时间',
  `create_time` datetime NOT NULL COMMENT '创建时间',
  `used` tinyint NOT NULL DEFAULT '0' COMMENT '是否已使用:0未使用 1已使用',
  `client_ip` varchar(50) DEFAULT NULL COMMENT '使用的IP',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_uuid` (`uuid`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='验证码表';

sys_login_log - 登录日志表

CREATE TABLE `sys_login_log` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '日志ID',
  `user_id` bigint DEFAULT NULL COMMENT '用户ID',
  `username` varchar(50) DEFAULT NULL COMMENT '用户名',
  `login_ip` varchar(50) DEFAULT NULL COMMENT '登录IP',
  `login_location` varchar(255) DEFAULT NULL COMMENT '登录地点',
  `browser` varchar(50) DEFAULT NULL COMMENT '浏览器类型',
  `os` varchar(50) DEFAULT NULL COMMENT '操作系统',
  `status` tinyint NOT NULL COMMENT '登录状态:0失败 1成功',
  `msg` varchar(255) DEFAULT NULL COMMENT '提示消息',
  `login_time` datetime NOT NULL COMMENT '登录时间',
  PRIMARY KEY (`id`),
  KEY `idx_username` (`username`),
  KEY `idx_login_time` (`login_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='登录日志表';

---

前端使用示例

Vue.js + Axios

import axios from 'axios';

// 创建axios实例
const service = axios.create({
  baseURL: '/api',
  timeout: 10000
});

// 请求拦截器 - 添加Token
service.interceptors.request.use(
  config => {
    const token = localStorage.getItem('token');
    if (token) {
      config.headers['Authorization'] = `Bearer ${token}`;
    }
    return config;
  },
  error => {
    return Promise.reject(error);
  }
);

// 响应拦截器 - 处理Token过期
service.interceptors.response.use(
  response => {
    return response.data;
  },
  error => {
    if (error.response && error.response.status === 401) {
      // Token过期，跳转到登录页
      localStorage.removeItem('token');
      window.location.href = '/login';
    }
    return Promise.reject(error);
  }
);

// 登录
export function login(data) {
  return service.post('/auth/login', data);
}

// 获取验证码
export function getCaptcha() {
  return service.get('/auth/captcha');
}

// 注册
export function register(data) {
  return service.post('/auth/register', data);
}

原生JavaScript

// 设置Token
function setToken(token) {
  localStorage.setItem('token', token);
  // 或者设置Cookie
  document.cookie = `token=${token}; path=/`;
}

// 获取Token
function getToken() {
  return localStorage.getItem('token');
}

// 发送请求
function fetchWithToken(url, options = {}) {
  const token = getToken();
  options.headers = options.headers || {};
  if (token) {
    options.headers['Authorization'] = `Bearer ${token}`;
  }
  return fetch(url, options);
}

// 使用示例
fetchWithToken('/api/user/profile')
  .then(res => res.json())
  .then(data => console.log(data));

jQuery

// 设置全局Ajax设置
$.ajaxSetup({
  beforeSend: function(xhr) {
    const token = localStorage.getItem('token');
    if (token) {
      xhr.setRequestHeader('Authorization', `Bearer ${token}`);
    }
  }
});

// 登录
$.ajax({
  url: '/api/auth/login',
  type: 'POST',
  data: JSON.stringify({
    username: 'admin',
    password: '123456',
    captchaUuid: 'uuid',
    captchaCode: '1234'
  }),
  contentType: 'application/json',
  success: function(response) {
    if (response.code === 200) {
      localStorage.setItem('token', response.data.token);
    }
  }
});

---

安全建议

1. HTTPS: 生产环境必须使用HTTPS
2. Token有效期: 建议设置为2-24小时
3. 密码强度: 强制用户使用复杂密码
4. 登录限制: 实现登录失败次数限制
5. Token黑名单: 实现Token黑名单机制(使用Redis)
6. IP白名单: 敏感操作可以添加IP白名单
7. 双因素认证: 关键操作建议添加2FA

---

注意事项

1. 验证码默认5分钟过期
2. 密码使用BCrypt加密存储
3. Token过期时间可在配置文件中修改
4. 登录失败不会删除验证码
5. 同一验证码只能使用一次