React / 系统课时

路由守卫与异常页面

路由守卫与异常页面

本课解决“哪些用户可以进入哪些页面,以及失败后显示什么”的问题。你将实现登录守卫和角色守卫,并用 401、403、404 页面区分未登录、无权限和路由不存在,让页面访问逻辑清晰且可验证。

学习目标

  • 使用包装路由实现登录与角色校验
  • 正确区分 401、403 和 404 页面
  • 保留原访问地址,并在登录后返回目标页面

先区分三类访问失败

未登录表示系统还不知道用户身份,应引导用户登录;已登录但权限不足表示身份已确认,只是不能访问当前资源;路由不存在则表示地址没有匹配到任何页面。

场景 页面 推荐处理
未登录访问受保护页面 401 或登录页 记录原地址并跳转登录
已登录但角色不匹配 403 展示无权限说明和返回入口
地址没有对应路由 404 展示未找到页面和首页入口

路由守卫只负责前端页面访问体验,不能替代服务端权限校验。即使按钮和页面都被隐藏,后端接口仍必须验证身份与权限。

受保护路由判定流程

实现登录守卫与角色守卫

下面的示例用内存状态模拟当前用户。RequireAuth 负责检查登录状态,RequireRole 在已登录的基础上继续检查角色。登录页读取原访问地址,登录成功后再跳回去。

tsx
import React, { createContext, useContext, useMemo, useState } from "react";
import {
  BrowserRouter,
  Link,
  Navigate,
  Route,
  Routes,
  useLocation,
  useNavigate,
} from "react-router-dom";
import { createRoot } from "react-dom/client";

type Role = "USER" | "ADMIN";

type User = {
  name: string;
  role: Role;
};

type AuthContextValue = {
  user: User | null;
  login: (role: Role) => void;
  logout: () => void;
};

// 认证上下文只暴露当前用户和登录状态修改方法。
const AuthContext = createContext<AuthContextValue | null>(null);

function useAuth() {
  const context = useContext(AuthContext);
  if (!context) throw new Error("useAuth 必须在 AuthProvider 内使用");
  return context;
}

function AuthProvider({ children }: { children: React.ReactNode }) {
  const [user, setUser] = useState<User | null>(null);

  const value = useMemo<AuthContextValue>(
    () => ({
      user,
      login: (role) => setUser({ name: "Simon", role }),
      logout: () => setUser(null),
    }),
    [user],
  );

  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
}

function RequireAuth({ children }: { children: React.ReactNode }) {
  const { user } = useAuth();
  const location = useLocation();

  if (!user) {
    // 保存原始 location,登录成功后可恢复路径、查询参数和哈希。
    return <Navigate to="/unauthorized" replace state={{ from: location }} />;
  }

  return <>{children}</>;
}

function RequireRole({
  allow,
  children,
}: {
  allow: Role[];
  children: React.ReactNode;
}) {
  const { user } = useAuth();

  if (!user) {
    return <Navigate to="/unauthorized" replace />;
  }

  // 身份已确认但角色不匹配时进入 403 页面。
  if (!allow.includes(user.role)) {
    return <Navigate to="/forbidden" replace />;
  }

  return <>{children}</>;
}

function HomePage() {
  const { user, logout } = useAuth();

  return (
    <main>
      <h2>首页</h2>
      <p>当前用户:{user ? `${user.name} / ${user.role}` : "未登录"}</p>
      <nav>
        <Link to="/profile">个人中心</Link>{" "}
        <Link to="/admin">管理后台</Link>
      </nav>
      {user && <button onClick={logout}>退出登录</button>}
    </main>
  );
}

function LoginPage() {
  const { login } = useAuth();
  const navigate = useNavigate();
  const location = useLocation();
  const from = (
    location.state as {
      from?: { pathname: string; search: string; hash: string };
    } | null
  )?.from;
  const target = from
    ? `${from.pathname}${from.search}${from.hash}`
    : "/";

  function handleLogin(role: Role) {
    login(role);
    navigate(target, { replace: true });
  }

  return (
    <main>
      <h2>登录</h2>
      <button onClick={() => handleLogin("USER")}>以普通用户登录</button>
      <button onClick={() => handleLogin("ADMIN")}>以管理员登录</button>
    </main>
  );
}

function ProfilePage() {
  return <h2>个人中心</h2>;
}

function AdminPage() {
  return <h2>管理后台</h2>;
}

function UnauthorizedPage() {
  const location = useLocation();
  const from = (
    location.state as {
      from?: { pathname: string; search: string; hash: string };
    } | null
  )?.from;

  return (
    <main>
      <h2>401 未授权</h2>
      <Link to="/login" state={{ from }}>
        前往登录
      </Link>
    </main>
  );
}

function ForbiddenPage() {
  return (
    <main>
      <h2>403 无权限</h2>
      <Link to="/">返回首页</Link>
    </main>
  );
}

function NotFoundPage() {
  return (
    <main>
      <h2>404 页面不存在</h2>
      <Link to="/">返回首页</Link>
    </main>
  );
}

function App() {
  return (
    <AuthProvider>
      <BrowserRouter>
        <Routes>
          <Route path="/" element={<HomePage />} />
          <Route path="/login" element={<LoginPage />} />
          <Route path="/unauthorized" element={<UnauthorizedPage />} />
          <Route path="/forbidden" element={<ForbiddenPage />} />
          <Route
            path="/profile"
            element={
              <RequireAuth>
                <ProfilePage />
              </RequireAuth>
            }
          />
          {/* 先校验登录,再校验角色,职责保持单一。 */}
          <Route
            path="/admin"
            element={
              <RequireAuth>
                <RequireRole allow={["ADMIN"]}>
                  <AdminPage />
                </RequireRole>
              </RequireAuth>
            }
          />
          <Route path="*" element={<NotFoundPage />} />
        </Routes>
      </BrowserRouter>
    </AuthProvider>
  );
}

createRoot(document.getElementById("root")!).render(<App />);

预期结果

text
1. 未登录访问 /profile 或 /admin 时进入 401 页面。
2. 从 401 页面前往登录后,登录成功会返回原目标地址。
3. 以普通用户登录后可进入 /profile;访问 /admin 时进入 403 页面。
4. 以管理员登录后可进入 /admin。
5. 访问不存在的地址时进入 404 页面。

示例中的用户状态保存在内存,刷新后会恢复为未登录。真实项目通常通过 Cookie、Token 或会话接口恢复身份,并在恢复完成前显示加载状态,避免页面先跳登录再立即跳回。

为什么要保存原访问地址

用户直接访问 /admin?tab=users 时,守卫不应只记住 /admin。保存完整的 location 可以保留路径、查询参数和哈希,使登录后的返回结果与用户原始意图一致。

返回地址必须来自应用内部路由,不能直接信任外部传入的完整 URL,否则可能形成开放重定向。最稳妥的做法是保存 React Router 的 location 对象,而不是读取任意 redirect 参数后直接跳转。

异步鉴权与加载状态

真实应用常在启动时请求“当前用户”接口。此时鉴权状态至少应区分“检查中、已登录、未登录”,不能把尚未完成的请求直接当成未登录。

片段示例:以下守卫复用上文的 React、Navigate 和 useLocation 导入,并由认证上下文把 status 传入。

tsx
type AuthStatus = "loading" | "authenticated" | "anonymous";

function RequireAuth({
  status,
  children,
}: {
  status: AuthStatus;
  children: React.ReactNode;
}) {
  const location = useLocation();

  if (status === "loading") {
    return <p>正在验证登录状态...</p>;
  }

  if (status === "anonymous") {
    return <Navigate to="/unauthorized" replace state={{ from: location }} />;
  }

  return <>{children}</>;
}

预期结果

text
鉴权请求未完成时显示加载提示;确认未登录后才进入 401 页面;确认已登录后渲染受保护页面。

这样可以避免刷新页面时出现短暂的错误跳转,也能防止受保护内容在权限结果返回前闪现。

异常页面的设计边界

401 页面应告诉用户需要登录,并提供明确的登录入口。403 页面应说明当前账号没有权限,但不要暴露后台角色规则、资源标识或安全策略细节。404 页面应帮助用户回到首页或常用页面,不应自动猜测并跳转到不确定的地址。

前端守卫用于改善导航体验,真正的数据安全必须由后端接口完成。后端返回 401 时通常清理失效会话并重新登录;返回 403 时保留当前身份,展示无权限提示即可。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

路由守卫与异常页面

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通