五、前端集成

5.1 Token存储

token-storage.ts - 统一管理Token存储:

文件位置:knowledge-base-frontend/src/utils/token-storage.ts

/**
 * Token信息接口
 */
export interface TokenInfo {
  /** 访问令牌 */
  accessToken: string;
  /** 刷新令牌 */
  refreshToken: string;
  /** Token类型(通常为'Bearer') */
  tokenType: string;
  /** 过期时间(秒) */
  expiresIn: number;
  /** 过期时间戳 */
  expiresAt: number;
}

/**
 * 用户信息接口
 */
export interface UserInfo {
  userId: number;
  username: string;
  nickname?: string;
  email?: string;
  phone?: string | null;
  avatar?: string;
}

/**
 * 登录响应接口(必须与后端LoginVO匹配)
 */
export interface LoginResponse {
  accessToken: string;
  refreshToken: string;
  tokenType: string;
  expiresIn: number;
  userInfo: UserInfo;
}

/**
 * Token存储服务类
 */
class TokenStorageService {
  /**
   * 保存Token信息
   *
   * <p>同时保存到Cookie和LocalStorage</p>
   */
  saveToken(loginResponse: LoginResponse): void {
    const { accessToken, refreshToken, tokenType, expiresIn, userInfo } = loginResponse;

    // 计算过期时间戳
    const expiresAt = Date.now() + expiresIn * 1000;

    // 保存到LocalStorage(备用)
    localStorage.setItem('access_token', accessToken);
    localStorage.setItem('refresh_token', refreshToken);
    localStorage.setItem('token_type', tokenType);
    localStorage.setItem('expires_at', String(expiresAt));
    localStorage.setItem('user_info', JSON.stringify(userInfo));

    // 保存到Cookie(主要存储方式)
    const cookieOptions = {
      expires: expiresIn / 86400, // 转换为天数
      path: '/',
      sameSite: 'lax' as const,
    };

    cookieManager.set('access_token', accessToken, cookieOptions);
    cookieManager.set('refresh_token', refreshToken, cookieOptions);
  }

  /**
   * 获取访问令牌
   */
  getAccessToken(): string | null {
    // 优先从Cookie获取
    const tokenFromCookie = cookieManager.get('access_token');
    if (tokenFromCookie) {
      return tokenFromCookie;
    }

    // 从LocalStorage获取(备用)
    return localStorage.getItem('access_token');
  }

  /**
   * 获取完整的Authorization Header值
   */
  getAuthorizationHeader(): string {
    const token = this.getAccessToken();
    const tokenType = localStorage.getItem('token_type') || 'Bearer';
    return token ? `${tokenType} ${token}` : '';
  }

  /**
   * 清除Token信息
   */
  clearToken(): void {
    // 清除LocalStorage
    localStorage.removeItem('access_token');
    localStorage.removeItem('refresh_token');
    localStorage.removeItem('token_type');
    localStorage.removeItem('expires_at');
    localStorage.removeItem('user_info');

    // 清除Cookie
    cookieManager.remove('access_token');
    cookieManager.remove('refresh_token');
  }

  /**
   * 检查是否已登录
   */
  isAuthenticated(): boolean {
    const token = this.getAccessToken();
    return token !== null && !this.isTokenExpired();
  }

  /**
   * 检查Token是否已过期
   */
  isTokenExpired(): boolean {
    const expiresAt = localStorage.getItem('expires_at');
    if (!expiresAt) {
      return true;
    }

    return Date.now() >= parseInt(expiresAt, 10);
  }

  /**
   * 获取用户信息
   */
  getUserInfo(): UserInfo | null {
    const userInfoStr = localStorage.getItem('user_info');
    if (!userInfoStr) {
      return null;
    }

    try {
      return JSON.parse(userInfoStr) as UserInfo;
    } catch {
      return null;
    }
  }
}

// 导出单例
export const tokenStorage = new TokenStorageService();

cookie.ts - Cookie管理工具:

文件位置:knowledge-base-frontend/src/utils/cookie.ts

interface CookieOptions {
  expires?: number; // 过期天数
  path?: string;
  domain?: string;
  secure?: boolean;
  sameSite?: 'strict' | 'lax' | 'none';
}

class CookieManager {
  set(name: string, value: string, options: CookieOptions = {}): void {
    let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;

    if (options.expires) {
      const date = new Date();
      date.setDate(date.getDate() + options.expires);
      cookie += `; expires=${date.toUTCString()}`;
    }

    if (options.path) {
      cookie += `; path=${options.path}`;
    }

    if (options.domain) {
      cookie += `; domain=${options.domain}`;
    }

    if (options.secure) {
      cookie += '; secure';
    }

    if (options.sameSite) {
      cookie += `; samesite=${options.sameSite}`;
    }

    document.cookie = cookie;
  }

  get(name: string): string | null {
    const encodedName = encodeURIComponent(name);
    const cookies = document.cookie.split(';');

    for (const cookie of cookies) {
      const [key, value] = cookie.trim().split('=');
      if (key === encodedName) {
        return decodeURIComponent(value);
      }
    }

    return null;
  }

  remove(name: string, options: Pick<CookieOptions, 'path' | 'domain'> = {}): void {
    this.set(name, '', { ...options, expires: -1 });
  }
}

export const cookieManager = new CookieManager();

5.2 请求拦截器

request.ts - Axios配置和拦截器:

文件位置:knowledge-base-frontend/src/services/request.ts

import axios, { AxiosInstance, AxiosError, InternalAxiosRequestConfig, AxiosResponse } from 'axios';
import { message } from 'antd';
import { tokenStorage } from '@/utils/token-storage';

/**
 * 自定义请求配置
 */
interface CustomAxiosRequestConfig extends InternalAxiosRequestConfig {
  skipAuth?: boolean; // 跳过认证(用于刷新Token等接口)
}

/**
 * 创建Axios实例
 */
const http: AxiosInstance = axios.create({
  baseURL: '/api',
  timeout: 30000,
  withCredentials: false, // 不自动携带Cookie,手动添加Authorization Header
});

/**
 * 请求拦截器
 */
http.interceptors.request.use(
  (config: CustomAxiosRequestConfig) => {
    // 如果不是跳过认证的请求,添加Token到Header
    if (!config.skipAuth) {
      const authHeader = tokenStorage.getAuthorizationHeader();
      if (authHeader && config.headers) {
        config.headers.Authorization = authHeader;
      }
    }

    return config;
  },
  (error: AxiosError) => {
    console.error('请求拦截器错误:', error);
    return Promise.reject(error);
  }
);

/**
 * 响应拦截器
 */
http.interceptors.response.use(
  (response: AxiosResponse) => {
    // 后端返回格式:{ code, message, data }
    const { code, message: msg, data } = response.data;

    if (code === 200) {
      return data;
    } else if (code === 401) {
      // Token过期或无效,清除本地信息并跳转到登录页
      message.error('登录已过期,请重新登录');
      tokenStorage.clearToken();
      window.location.href = '/login';
      return Promise.reject(new Error(msg || '未授权'));
    } else {
      message.error(msg || '请求失败');
      return Promise.reject(new Error(msg || '请求失败'));
    }
  },
  (error: AxiosError) => {
    if (error.response) {
      const status = error.response.status;

      switch (status) {
        case 401:
          message.error('登录已过期,请重新登录');
          tokenStorage.clearToken();
          window.location.href = '/login';
          break;
        case 403:
          message.error('没有权限访问');
          break;
        case 404:
          message.error('请求的资源不存在');
          break;
        case 500:
          message.error('服务器错误');
          break;
        default:
          message.error(`请求失败: ${status}`);
      }
    } else if (error.request) {
      message.error('网络错误,请检查网络连接');
    } else {
      message.error('请求配置错误');
    }

    return Promise.reject(error);
  }
);

export { http };
export type { CustomAxiosRequestConfig };

关键点说明:

  1. withCredentials: false:不自动携带Cookie,手动添加Token到Authorization Header
  2. skipAuth配置:支持跳过Token验证的接口(如刷新Token接口)
  3. Token获取:从tokenStorage获取Authorization Header
  4. 401处理:Token过期时清除本地信息并跳转到登录页
  5. 统一错误处理:处理各种HTTP错误状态码

5.3 登录流程

auth.store.ts - Zustand状态管理:

文件位置:knowledge-base-frontend/src/stores/auth.store.ts

interface AuthState {
  user: User | null;
  token: string | null;
  isAuthenticated: boolean;
  isLoading: boolean;

  // Actions
  login: (username: string, password: string) => Promise<void>;
  logout: () => Promise<void>;
  updateUser: (user: User) => void;
  checkAuth: () => Promise<void>;
  clearAuth: () => void;
}

export const useAuthStore = create<AuthState>()(
  persist(
    (set, get) => ({
      user: null,
      token: null,
      isAuthenticated: false,
      isLoading: false,

      login: async (username: string, password: string) => {
        set({ isLoading: true });
        try {
          // 1. 调用登录接口
          const loginResponse = await authService.login({ username, password });

          console.log('登录响应:', loginResponse);

          // 2. 保存Token到Cookie和LocalStorage
          tokenStorage.saveToken(loginResponse as LoginResponse);

          // 3. 更新状态
          set({
            user: loginResponse.userInfo as User,
            token: loginResponse.accessToken,
            isAuthenticated: true,
            isLoading: false,
          });

          console.log('登录成功,Token已保存');
        } catch (error) {
          set({ isLoading: false });
          throw error;
        }
      },

      logout: async () => {
        try {
          await authService.logout();
        } finally {
          get().clearAuth();
        }
      },

      updateUser: (user: User) => {
        set({ user });
      },

      checkAuth: async () => {
        // 优先从Cookie获取Token
        const token = tokenStorage.getAccessToken() || get().token;

        if (!token) {
          set({ isAuthenticated: false, user: null, token: null });
          return;
        }

        set({ isLoading: true, token });
        try {
          const user = await authService.getCurrentUser();
          set({
            user,
            isAuthenticated: true,
            isLoading: false,
          });
        } catch (error) {
          get().clearAuth();
          set({ isLoading: false });
        }
      },

      clearAuth: () => {
        // 清除Token
        tokenStorage.clearToken();

        set({
          user: null,
          token: null,
          isAuthenticated: false,
        });
      },
    }),
    {
      name: 'auth-storage',
      partialize: (state) => ({
        user: state.user,
        token: state.token,
        isAuthenticated: state.isAuthenticated,
      }),
    }
  )
);

auth.service.ts - 认证服务:

文件位置:knowledge-base-frontend/src/services/auth.service.ts

export const authService = {
  /**
   * 用户登录
   */
  login: (data: LoginRequest): Promise<LoginResponse> => {
    return http.post<LoginResponse>('/auth/auth/login', data);
  },

  /**
   * 用户退出
   */
  logout: (): Promise<void> => {
    return http.post<void>('/auth/auth/logout').then(() => {
      tokenStorage.clearToken();
    });
  },

  /**
   * 获取当前用户信息
   */
  getCurrentUser: (): Promise<User> => {
    return http.get<User>('/auth/auth/me');
  },

  /**
   * 刷新Token
   */
  refreshToken: (refreshToken: string): Promise<LoginResponse> => {
    return http.post<LoginResponse>('/auth/auth/refresh', null, {
      params: { refreshToken },
      skipAuth: true,
    });
  },
};

stores/index.ts - Zustand Store统一导出:

文件位置:knowledge-base-frontend/src/stores/index.ts

/**
 * Zustand Store统一导出
 *
 * <p>集中导出所有状态管理store,方便使用</p>
 *
 * 使用示例:
 * ```typescript
 * import { useAuthStore, useDocumentStore } from '@/stores';
 * ```
 */

// 认证相关状态
export { useAuthStore } from './auth.store';

// 文档相关状态
export { useDocumentStore } from './document.store';

// AI功能相关状态
export { useAIStore } from './ai.store';

// 通知相关状态
export { useNotificationStore } from './notification.store';

// 版本管理相关状态
export { useVersionStore } from './version.store';

// 用户管理相关状态
export { useUserStore } from './user.store';

// 分类管理相关状态
export { useCategoryStore } from './category.store';

前端登录页面调用示例:

// 1. 用户点击登录
const handleLogin = async (values: LoginForm) => {
  try {
    // 2. 调用登录接口
    const { login } = useAuthStore.getState();
    await login(values.username, values.password);

    // 3. 跳转到主页
    navigate('/');
  } catch (error) {
    message.error('登录失败:' + error.message);
  }
};

关键点说明:

  1. 登录响应:后端返回{ accessToken, refreshToken, tokenType, expiresIn, userInfo }
  2. Token保存:同时保存到Cookie和LocalStorage
  3. 状态更新:更新Zustand store中的用户信息和认证状态
  4. 路由跳转:登录成功后跳转到主页

5.4 路由守卫组件

ProtectedRoute.tsx - 路由守卫组件:

文件位置:knowledge-base-frontend/src/router/index.tsx

import React from 'react';
import { Navigate } from 'react-router-dom';
import { tokenStorage } from '@/utils/token-storage';

/**
 * 路由守卫组件
 *
 * <p>职责说明:</p>
 * <ul>
 *   <li>检查用户是否已登录</li>
 *   <li>未登录用户自动跳转到登录页</li>
 *   <li>已登录用户允许访问受保护的路由</li>
 *   <li>支持管理员权限检查</li>
 * </ul>
 */
interface ProtectedRouteProps {
  children: React.ReactElement;
  requireAdmin?: boolean;
}

const ProtectedRoute = ({ children, requireAdmin = false }: ProtectedRouteProps) => {
  // 优先从Cookie获取Token,然后从LocalStorage获取
  const token = tokenStorage.getAccessToken() || localStorage.getItem('token');

  console.log('🔐 ProtectedRoute - 检查登录状态:');
  console.log('  - 从Cookie获取Token:', tokenStorage.getAccessToken() ? '✅ 有' : '❌ 无');
  console.log('  - 从LocalStorage获取Token:', localStorage.getItem('token') ? '✅ 有' : '❌ 无');
  console.log('  - 最终Token:', token ? `✅ 有 (长度: ${token.length})` : '❌ 无');

  // 如果没有token,跳转到登录页
  if (!token) {
    console.log('❌ 未找到Token,跳转到登录页');
    return <Navigate to="/login" replace />;
  }

  console.log('✅ 用户已认证,允许访问');

  // 管理员权限检查
  if (requireAdmin) {
    // TODO: 添加角色检查逻辑
    console.log('✅ 管理员权限检查通过');
  }

  return children;
};

export default ProtectedRoute;

路由配置示例:

文件位置:knowledge-base-frontend/src/router/index.tsx

import { createBrowserRouter, Navigate } from 'react-router-dom';
import { lazy, Suspense } from 'react';
import ProtectedRoute from './ProtectedRoute';

// 懒加载页面组件
const LoginPage = lazy(() => import('@/pages/LoginPage'));
const MainLayout = lazy(() => import('@/layouts/MainLayout'));
const DashboardPage = lazy(() => import('@/pages/DashboardPage'));

const routes = [
  {
    path: '/login',
    element: (
      <Suspense fallback={<div>加载中...</div>}>
        <LoginPage />
      </Suspense>
    ),
  },
  {
    path: '/',
    element: (
      <ProtectedRoute>
        <MainLayout />
      </ProtectedRoute>
    ),
    children: [
      {
        index: true,
        element: (
          <Suspense fallback={<div>加载中...</div>}>
            <DashboardPage />
          </Suspense>
        ),
      },
      // 其他路由...
    ],
  },
  {
    path: '*',
    element: <Navigate to="/" replace />,
  },
];

export const router = createBrowserRouter(routes);
export default router;

关键点说明:

  1. Token检查:优先从Cookie获取Token,兼容LocalStorage
  2. 自动跳转:未登录用户自动跳转到登录页
  3. 权限控制:支持requireAdmin参数进行管理员权限检查
  4. 懒加载:使用React.lazy进行组件懒加载,提升性能

5.5 登录页面组件

LoginPage.tsx - 登录页面组件:

文件位置:knowledge-base-frontend/src/pages/LoginPage.tsx

import React from 'react';
import { Form, Input, Button, Typography, Tabs, message } from 'antd';
import { UserOutlined, LockOutlined, MailOutlined } from '@ant-design/icons';
import { useNavigate, Link } from 'react-router-dom';
import { useAuthStore } from '@/stores';

const { Text } = Typography;

export const LoginPage: React.FC = () => {
  const navigate = useNavigate();
  const { login } = useAuthStore();
  const [loading, setLoading] = React.useState(false);

  const handleLogin = async (values: any) => {
    setLoading(true);
    try {
      await login(values.username, values.password);
      message.success('登录成功');
      navigate('/');
    } catch (error) {
      // Error already handled in store
    } finally {
      setLoading(false);
    }
  };

  const handleRegister = async (_values: any) => {
    setLoading(true);
    try {
      // Implement registration logic
      message.success('注册成功,请登录');
      // Switch to login tab
    } catch (error) {
      // Error already handled
    } finally {
      setLoading(false);
    }
  };

  return (
    <div style={{
      minHeight: '100vh',
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
      background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
    }}>
      <div style={{
        width: 400,
        padding: 40,
        background: 'white',
        borderRadius: 16,
        boxShadow: '0 20px 60px rgba(0, 0, 0, 0.3)',
      }}>
        <div style={{ textAlign: 'center', marginBottom: 32 }}>
          <h1 style={{ fontSize: 28, fontWeight: 700, marginBottom: 8 }}>
            知识库系统
          </h1>
          <p style={{ color: '#666' }}>欢迎回来,请登录您的账户</p>
        </div>
        <Tabs
          defaultActiveKey="login"
          centered
          items={[
            {
              key: 'login',
              label: '登录',
              children: (
                <Form
                  name="login"
                  onFinish={handleLogin}
                  autoComplete="off"
                  layout="vertical"
                >
                  <Form.Item
                    name="username"
                    rules={[{ required: true, message: '请输入用户名' }]}
                  >
                    <Input
                      prefix={<UserOutlined />}
                      placeholder="用户名"
                      size="large"
                    />
                  </Form.Item>
                  <Form.Item
                    name="password"
                    rules={[{ required: true, message: '请输入密码' }]}
                  >
                    <Input.Password
                      prefix={<LockOutlined />}
                      placeholder="密码"
                      size="large"
                    />
                  </Form.Item>
                  <Form.Item>
                    <Button
                      type="primary"
                      htmlType="submit"
                      loading={loading}
                      block
                      size="large"
                      style={{
                        background: 'linear-gradient(135deg, #1890ff, #722ed1)',
                        border: 'none',
                        height: 44,
                        borderRadius: 8,
                        fontWeight: 600,
                      }}
                    >
                      登录
                    </Button>
                  </Form.Item>
                  <div style={{ textAlign: 'center' }}>
                    <Text type="secondary" style={{ fontSize: 12 }}>
                      忘记密码? <Link to="/forgot-password">找回密码</Link>
                    </Text>
                    </div>
                </Form>
              ),
            },
            {
              key: 'register',
              label: '注册',
              children: (
                <Form
                  name="register"
                  onFinish={handleRegister}
                  autoComplete="off"
                  layout="vertical"
                >
                  <Form.Item
                    name="username"
                    rules={[
                      { required: true, message: '请输入用户名' },
                      { min: 3, message: '用户名至少3个字符' },
                    ]}
                  >
                    <Input
                      prefix={<UserOutlined />}
                      placeholder="用户名"
                      size="large"
                    />
                  </Form.Item>
                  <Form.Item
                    name="email"
                    rules={[
                      { required: true, message: '请输入邮箱' },
                      { type: 'email', message: '请输入有效的邮箱地址' },
                    ]}
                  >
                    <Input
                      prefix={<MailOutlined />}
                      placeholder="邮箱"
                      size="large"
                    />
                  </Form.Item>
                  <Form.Item
                    name="password"
                    rules={[
                      { required: true, message: '请输入密码' },
                      { min: 6, message: '密码至少6个字符' },
                    ]}
                  >
                    <Input.Password
                      prefix={<LockOutlined />}
                      placeholder="密码"
                      size="large"
                    />
                  </Form.Item>
                  <Form.Item
                    name="confirmPassword"
                    dependencies={['password']}
                    rules={[
                      { required: true, message: '请确认密码' },
                      ({ getFieldValue }) => ({
                        validator(_, value) {
                          if (!value || getFieldValue('password') === value) {
                            return Promise.resolve();
                          }
                          return Promise.reject(new Error('两次输入的密码不一致'));
                        },
                      }),
                    ]}
                  >
                    <Input.Password
                      prefix={<LockOutlined />}
                      placeholder="确认密码"
                      size="large"
                    />
                  </Form.Item>
                  <Form.Item>
                    <Button
                      type="primary"
                      htmlType="submit"
                      loading={loading}
                      block
                      size="large"
                      style={{
                        background: 'linear-gradient(135deg, #1890ff, #722ed1)',
                        border: 'none',
                        height: 44,
                        borderRadius: 8,
                        fontWeight: 600,
                      }}
                    >
                      注册
                    </Button>
                  </Form.Item>
                </Form>
              ),
            },
          ]}
        />
      </div>
    </div>
  );
};

export default LoginPage;

关键点说明:

  1. UI设计:使用Ant Design组件库,现代化的渐变背景
  2. 表单验证:使用Form.Item的rules进行表单验证
  3. 状态管理:使用useAuthStore进行登录状态管理
  4. 错误处理:统一的错误处理和提示
  5. 路由跳转:登录成功后自动跳转到主页

5.6 前端类型定义

types/index.ts - TypeScript类型定义:

文件位置:knowledge-base-frontend/src/types/index.ts

/**
 * 用户信息接口
 */
export interface User {
  id?: string | number;
  userId?: number;
  username: string;
  nickname?: string;
  email?: string;
  phone?: string | null;
  avatar?: string;
  realName?: string;
  department?: string;
  position?: string;
  status?: number;
}

/**
 * 登录请求接口
 */
export interface LoginRequest {
  username: string;
  password: string;
}

/**
 * 登录响应接口(必须与后端LoginVO完全匹配)
 *
 * <p>重要:此接口必须与后端LoginVO的字段名完全一致</p>
 * <p>后端LoginVO位于:kb-user-auth/src/main/java/com/knowledge/base/userauth/vo/LoginVO.java</p>
 */
export interface LoginResponse {
  /** 访问令牌 */
  accessToken: string;
  /** 刷新令牌 */
  refreshToken: string;
  /** 令牌类型 */
  tokenType: string;
  /** 过期时间(秒) */
  expiresIn: number;
  /** 用户信息 */
  userInfo: UserInfo;
}

/**
 * 用户信息接口(与后端LoginVO.UserInfo匹配)
 */
export interface UserInfo {
  /** 用户ID */
  userId: number;
  /** 用户名 */
  username: string;
  /** 昵称 */
  nickname?: string;
  /** 邮箱 */
  email?: string;
  /** 手机号 */
  phone?: string | null;
  /** 头像URL */
  avatar?: string;
}

/**
 * 注册请求接口
 */
export interface RegisterRequest {
  username: string;
  email: string;
  password: string;
}

重要提示:

  1. LoginResponse接口必须与后端LoginVO的字段名完全匹配
  2. 使用accessToken而不是token
  3. 使用userInfo而不是user
  4. 字段类型必须一致(如userId是number类型)

六、完整文件清单

6.1 后端文件清单

文件路径说明必需
kb-common/src/main/java/com/knowledge/base/common/utils/JwtTokenUtil.javaJWT工具类,负责Token生成、验证、解析✅ 必需
kb-common/src/main/java/com/knowledge/base/common/config/JwtConfig.javaJWT配置类,定义密钥、过期时间等参数✅ 必需
kb-common/src/main/java/com/knowledge/base/common/utils/UserContextUtil.javaThreadLocal上下文工具,存储当前登录用户信息✅ 必需
kb-common/src/main/java/com/knowledge/base/common/exception/BusinessException.java业务异常类✅ 必需
kb-common/src/main/java/com/knowledge/base/common/result/Result.java统一响应结果封装✅ 必需
kb-common/src/main/java/com/knowledge/base/common/result/ResultCode.java响应状态码枚举✅ 必需
kb-user-auth/src/main/java/com/knowledge/base/userauth/filter/JwtAuthenticationFilter.javaJWT认证过滤器✅ 必需
kb-user-auth/src/main/java/com/knowledge/base/userauth/config/SecurityConfig.javaSpring Security配置类✅ 必需
kb-user-auth/src/main/java/com/knowledge/base/userauth/controller/AuthController.java认证接口Controller✅ 必需
kb-user-auth/src/main/java/com/knowledge/base/userauth/service/UserService.java用户Service接口✅ 必需
kb-user-auth/src/main/java/com/knowledge/base/userauth/service/impl/UserServiceImpl.java用户Service实现类✅ 必需
kb-user-auth/src/main/java/com/knowledge/base/userauth/entity/User.java用户实体类✅ 必需
kb-user-auth/src/main/java/com/knowledge/base/userauth/mapper/UserMapper.java用户Mapper接口✅ 必需
kb-user-auth/src/main/java/com/knowledge/base/userauth/vo/LoginVO.java登录响应VO✅ 必需
kb-user-auth/src/main/java/com/knowledge/base/userauth/vo/UserVO.java用户信息VO✅ 必需
kb-user-auth/src/main/resources/application.yml应用配置文件(包含JWT配置)✅ 必需
kb-user-auth/src/main/resources/db/schema.sql数据库建表SQL✅ 必需

6.2 前端文件清单

文件路径说明必需
knowledge-base-frontend/src/utils/token-storage.tsToken存储服务✅ 必需
knowledge-base-frontend/src/utils/cookie.tsCookie管理工具✅ 必需
knowledge-base-frontend/src/services/request.tsAxios配置和拦截器✅ 必需
knowledge-base-frontend/src/services/auth.service.ts认证服务API✅ 必需
knowledge-base-frontend/src/stores/auth.store.ts认证状态管理(Zustand)✅ 必需
knowledge-base-frontend/src/types/index.tsTypeScript类型定义✅ 必需
knowledge-base-frontend/src/router/index.tsx路由配置(包含ProtectedRoute)✅ 必需

6.3 依赖配置

后端pom.xml依赖:

  • spring-boot-starter-security
  • jjwt-api / jjwt-impl / jjwt-jackson
  • spring-boot-starter-data-redis
  • mybatis-plus-boot-starter
  • knife4j-openapi3-jakarta-spring-boot-starter

前端package.json依赖:

  • axios
  • zustand
  • react-router-dom
  • antd

6.4 配置文件模板

application.yml配置模板:

文件位置:kb-user-auth/src/main/resources/application.yml

server:
  port: 8081

spring:
  application:
    name: kb-user-auth

  # 数据源配置
  datasource:
    type: com.alibaba.druid.pool.DruidDataSource
    druid:
      driver-class-name: com.mysql.cj.jdbc.Driver
      url: jdbc:mysql://localhost:3306/kb_user?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true
      username: root
      password: your_password
      initial-size: 5
      min-idle: 5
      max-active: 20
      max-wait: 60000
      time-between-eviction-runs-millis: 60000
      min-evictable-idle-time-millis: 300000
      validation-query: SELECT 1
      test-while-idle: true
      test-on-borrow: false
      test-on-return: false

  # Redis配置
  data:
    redis:
      host: localhost
      port: 6379
      password:
      database: 0
      timeout: 3000
      lettuce:
        pool:
          max-active: 8
          max-idle: 8
          min-idle: 0
          max-wait: -1

  # Nacos配置
  cloud:
    nacos:
      config:
        namespace: knowledge
        server-addr: 117.72.88.11:8848
        enabled: true
      discovery:
        server-addr: 117.72.88.11:8848
        namespace: mall

# MyBatis Plus配置
mybatis-plus:
  mapper-locations: classpath:mapper/*.xml
  type-aliases-package: com.knowledge.base.userauth.entity
  configuration:
    map-underscore-to-camel-case: true
    cache-enabled: false
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
  global-config:
    db-config:
      id-type: ASSIGN_ID
      logic-delete-field: deleted
      logic-delete-value: 1
      logic-not-delete-value: 0

# JWT配置
jwt:
  secret: aW52ZW50ZW1lLWtub3dsZWRnZS1iYXNlLXNlY3JldC1rZXktZm9yLWp3dC10b2tlbi1nZW5lcmF0aW9uLW11c3QtYmUtbG9uZy1lbm91Z2g=
  expiration: 7200
  refresh-expiration: 604800
  issuer: knowledge-base

# 日志配置
logging:
  level:
    com.knowledge.base.userauth: debug
    com.knowledge.base.userauth.mapper: debug
  pattern:
    console: '%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{50} - %msg%n'

vite.config.ts配置:

文件位置:knowledge-base-frontend/vite.config.ts

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
  server: {
    port: 5173,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
        // 不要移除 /api 前缀,因为网关需要它来路由
        // rewrite: (path) => path.replace(/^\/api/, '')
      },
    },
  },
});

tsconfig.json配置:

文件位置:knowledge-base-frontend/tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src"],
  "references": [{ "path": "./tsconfig.node.json" }]
}

七 测试

启动后端服务

cd kb-user-auth
mvn clean install
mvn spring-boot:run

验证服务启动成功:

curl http://localhost:8081/actuator/health

启动前端服务

步骤1:安装依赖

cd knowledge-base-frontend
npm install

步骤2:配置环境变量

创建.env文件:

VITE_API_BASE_URL=http://localhost:8080
VITE_API_TIMEOUT=30000

步骤3:启动开发服务器

npm run dev

访问:http://localhost:3002/login

图片.png

10.4 测试登录功能

使用测试账号登录:

用户名密码角色
admin123456管理员
user123456普通用户
test123456测试用户

用admin账号登录成功之后的首页效果:

图片.png

总结

本文详细介绍了用户登录认证功能的完整实现过程,涵盖:

JWT Token生成与验证:使用JJWT库生成和验证Token
用户认证流程:登录、Token校验、权限控制
Spring Security集成:无状态会话、自定义认证过滤器
前端集成:Token存储、请求拦截、自动刷新
安全防护:密码加密、Token安全、防攻击措施

最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏