knowai/auth

认证模块

概述

认证模块提供基于Session的认证机制，支持用户登录、注册、登出和会话管理功能。该模块采用适配器模式，支持多种存储方式（Cookie、LocalStorage、内存），以适应不同的运行环境（浏览器、SSR等）。

核心组件

1. 认证服务 (AuthService)

AuthService 接口定义了认证相关的核心功能：

• login(credentials): 用户登录
• register(userData): 用户注册
• logout(): 用户登出
• isAuthenticated(): 检查是否已认证
• getCurrentUser(): 获取当前用户信息
• refreshSession(): 刷新会话
• getSession(): 获取会话信息

2. 会话管理器 (SessionManager)

SessionManager 负责管理用户会话状态，包括：

• 会话的创建、验证、刷新和清除
• 用户信息的获取和缓存
• 会话状态的持久化存储

3. 存储适配器 (StorageAdapter)

StorageAdapter 提供统一的存储接口，支持多种存储方式：

• CookieStorageAdapter: 使用Cookie存储，适用于SSR环境
• LocalStorageAdapter: 使用浏览器LocalStorage存储
• MemoryStorageAdapter: 使用内存存储，适用于测试或临时会话

4. 事件管理器 (EventManager)

EventManager 负责管理认证相关事件：

• 登录事件 (login)
• 注册事件 (register)
• 登出事件 (logout)
• 错误事件 (error)

5. 类型定义

模块包含完整的TypeScript类型定义，确保类型安全。

使用方法

基本使用

import { authService } from '@/auth';

// 用户登录
const loginResult = await authService.login({
  username: 'user@example.com',
  password: 'password123'
});

if (loginResult.success) {
  console.log('登录成功', loginResult.data);
} else {
  console.error('登录失败', loginResult.error);
}

// 检查认证状态
if (await authService.isAuthenticated()) {
  // 获取当前用户信息
  const userResult = await authService.getCurrentUser();
  if (userResult.success) {
    console.log('当前用户:', userResult.data);
  }
}

// 用户登出
await authService.logout();

测试环境使用

import { getAuthService, resetAuthService } from '@/auth';

// 在测试前重置服务实例
resetAuthService();

// 获取新的服务实例
const authService = getAuthService();

自定义存储方式

import { createStorageAdapter } from '@/auth';

// 创建自定义存储适配器
const customStorage = createStorageAdapter('localStorage');

// 注意：当前版本使用单例模式，自定义存储需要修改auth-service.ts中的实现

使用自定义存储适配器

import { createAuthService, createStorageAdapter } from '@/auth';

// 创建自定义Cookie存储适配器
const cookieStorage = createStorageAdapter('cookie', {
  domain: '.example.com',
  secure: true,
  httpOnly: false,
  sameSite: 'strict'
});

// 使用自定义存储适配器
const authService = createAuthService(undefined, cookieStorage);

事件监听

import { createAuthService, createEventManager } from '@/auth';

const eventManager = createEventManager();
const authService = createAuthService();

// 监听登录事件
eventManager.on('login', (data) => {
  console.log('用户登录:', data.user);
});

// 监听登出事件
eventManager.on('logout', () => {
  console.log('用户已登出');
});

会话管理

会话存储

会话信息通过StorageAdapter存储，默认使用Cookie存储，以支持SSR环境。会话信息包括：

• sessionId: 会话ID
• userId: 用户ID
• expiresAt: 过期时间
• createdAt: 创建时间

会话验证

SessionManager会自动验证会话的有效性：

1. 检查本地是否存在会话ID
2. 验证会话是否过期
3. 向服务器验证会话有效性
4. 自动刷新过期会话

会话刷新

当会话即将过期时，SessionManager会自动尝试刷新会话：

1. 使用当前会话ID请求刷新
2. 更新本地存储的会话信息
3. 清除缓存的用户信息，下次获取时重新请求

API端点

认证模块需要以下API端点：

• POST /auth/login: 用户登录
• POST /auth/register: 用户注册
• POST /auth/logout: 用户登出
• GET /auth/session/:sessionId: 获取会话信息
• POST /auth/session/refresh: 刷新会话
• GET /auth/user/:userId: 获取用户信息

设计模式

认证模块采用以下设计模式：

1. 适配器模式: 通过StorageAdapter接口支持多种存储方式
2. 工厂模式: 提供createAuthService等工厂函数简化实例创建
3. 观察者模式: 通过EventManager实现事件发布订阅
4. 策略模式: 不同存储方式采用不同策略

安全考虑

1. 会话安全: 使用HttpOnly Cookie存储会话ID，防止XSS攻击
2. CSRF防护: 通过SameSite Cookie属性防止CSRF攻击
3. 会话过期: 设置合理的会话过期时间，并支持自动刷新
4. HTTPS: 在生产环境中使用HTTPS传输敏感数据

SSR支持

认证模块完全支持SSR环境：

1. 默认使用Cookie存储，可在服务器端读取
2. 提供统一的StorageAdapter接口，可针对不同环境实现
3. 会话状态可在服务器和客户端之间同步

测试

认证模块包含完整的单元测试，覆盖：

• 会话管理功能
• 存储适配器功能
• 认证服务功能
• 错误处理

运行测试：

npm test auth