React / 系统课时
前端登录状态管理
前端登录状态管理
本课完成 React 应用中的登录状态闭环:启动时恢复会话,登录后保存当前用户,接口返回 401 时清除失效状态,并在主动退出后让页面立即回到未登录界面。
学习目标
- 用明确状态区分会话检查中、已登录和未登录
- 在应用启动时从服务端恢复当前用户
- 统一处理 401、登录成功与主动退出
把登录状态设计成有限状态
只用一个 isLoggedIn 布尔值会把“尚未检查会话”和“确认未登录”混为一谈,页面容易先闪现登录框,再突然跳到用户首页。更稳妥的模型至少包含 checking、authenticated 和 guest 三种状态。

状态切换必须由服务端结果驱动。浏览器中的用户对象只是界面缓存,真正有效的登录状态仍由服务端会话或令牌校验决定。
用 Zustand 维护会话
下面示例适用于 React 18、TypeScript 和 Zustand。它假设后端提供 /api/auth/session、/api/auth/login、/api/auth/logout 与 /api/profile,并通过 HttpOnly Cookie 保存会话,因此前端不需要把访问令牌写入 localStorage。
import { FormEvent, useEffect, useState } from "react";
import { create } from "zustand";
type SessionStatus = "checking" | "authenticated" | "guest";
interface User {
id: string;
name: string;
email: string;
}
interface AuthStore {
status: SessionStatus;
user: User | null;
restoreSession: () => Promise<void>;
login: (email: string, password: string) => Promise<void>;
logout: () => Promise<void>;
}
async function api(path: string, init: RequestInit = {}) {
return fetch(path, {
...init,
credentials: "include",
headers: {
"Content-Type": "application/json",
...init.headers,
},
});
}
const useAuthStore = create<AuthStore>((set) => ({
status: "checking",
user: null,
async restoreSession() {
try {
const response = await api("/api/auth/session");
if (response.status === 401) {
set({ status: "guest", user: null });
return;
}
if (!response.ok) {
throw new Error(`恢复会话失败:${response.status}`);
}
const user = (await response.json()) as User;
set({ status: "authenticated", user });
} catch (error) {
console.error(error);
set({ status: "guest", user: null });
}
},
async login(email, password) {
const response = await api("/api/auth/login", {
method: "POST",
body: JSON.stringify({ email, password }),
});
if (!response.ok) {
throw new Error("邮箱或密码错误");
}
const user = (await response.json()) as User;
set({ status: "authenticated", user });
},
async logout() {
try {
await api("/api/auth/logout", { method: "POST" });
} finally {
// 即使退出接口失败,也先清除本地展示状态。
set({ status: "guest", user: null });
}
},
}));
async function authFetch(path: string, init?: RequestInit) {
const response = await api(path, init);
if (response.status === 401) {
useAuthStore.setState({ status: "guest", user: null });
}
return response;
}
function LoginForm() {
const login = useAuthStore((state) => state.login);
const [email, setEmail] = useState("demo@example.com");
const [password, setPassword] = useState("demo-password");
const [message, setMessage] = useState("");
async function handleSubmit(event: FormEvent) {
event.preventDefault();
try {
await login(email, password);
} catch (error) {
setMessage(error instanceof Error ? error.message : "登录失败");
}
}
return (
<form onSubmit={handleSubmit}>
<input value={email} onChange={(event) => setEmail(event.target.value)} />
<input
type="password"
value={password}
onChange={(event) => setPassword(event.target.value)}
/>
<button type="submit">登录</button>
<p>{message}</p>
</form>
);
}
export default function App() {
const { status, user, restoreSession, logout } = useAuthStore();
const [profileMessage, setProfileMessage] = useState("");
useEffect(() => {
void restoreSession();
}, [restoreSession]);
async function loadProfile() {
const response = await authFetch("/api/profile");
setProfileMessage(response.ok ? "资料加载成功" : `请求失败:${response.status}`);
}
if (status === "checking") {
return <p>正在恢复会话...</p>;
}
if (status === "guest") {
return <LoginForm />;
}
return (
<main>
<h1>你好,{user?.name}</h1>
<button onClick={loadProfile}>加载资料</button>
<button onClick={() => void logout()}>退出登录</button>
<p>{profileMessage}</p>
</main>
);
}在已配置 Zustand 的 React 18 项目中运行后,预期页面行为如下:
首次进入:显示“正在恢复会话...”
会话有效:显示“你好,<用户名>”
会话无效或接口返回 401:切换到登录表单
主动退出:立即清除用户信息并显示登录表单动态用户名取决于后端返回值,因此示例使用 <用户名> 表示实际内容可能不同。
恢复会话的正确时机
会话恢复应在应用根组件挂载时执行一次,并在完成前保持 checking。受保护页面不要在检查结束前渲染,否则会产生内容闪烁,还可能短暂展示不属于当前用户的数据。
刷新页面后不要仅从本地存储恢复用户对象。更可靠的做法是请求服务端会话接口,让服务端重新校验 Cookie、令牌有效期和用户状态,再返回最小化的用户信息。
统一处理登录失效与退出
所有受保护请求应经过统一封装。示例中的 authFetch 在遇到 401 时立即把状态切换为 guest,这样任意页面都能同步退出,而不需要每个组件分别处理。
不要把 403 当成登录失效。403 表示用户仍然有效,只是缺少当前资源权限;此时应保留登录状态,并展示无权限提示。主动退出则应调用服务端接口使会话失效,再清理本地用户数据。
验收登录状态闭环
验证时至少覆盖四个场景:刷新已登录页面后仍保持用户信息;无会话进入时直接显示登录表单;会话过期后下一次受保护请求自动回到未登录状态;点击退出后刷新页面也不能恢复原会话。
还要检查浏览器存储中是否出现明文访问令牌。使用 HttpOnly Cookie 时,前端脚本读取不到 Cookie,可以降低令牌被跨站脚本窃取的风险,但仍需配合 SameSite、HTTPS 和 CSRF 防护。