UmiJS 约定式路由配置与权限拦截实战

一、约定式路由映射机制与目录拓扑规范

当工程中不存在 .umirc.ts 或 config/routes.ts 中的 routes 配置项时，UmiJS 会自动启动约定式路由机制。框架通过递归扫描 src/pages 目录，根据特定的文件命名模式在内存中生成标准 React 路由对象。

理解约定式路由的关键在于掌握文件名称到 URL 路径的转换规则以及嵌套路由的识别逻辑。规范命名不仅决定了页面访问路径，还决定了页面父子层级与公用布局的生效范围：

• 主入口文件：src/pages/index.tsx 映射为网站根路径 /。任意子目录下的 index.tsx 则映射为该子目录对应的根路由，如 src/pages/system/index.tsx 对应 /system。
• 同名目录与页面：若存在 src/pages/users.tsx 和 src/pages/users/index.tsx，users.tsx 将自动被视作嵌套父级容器（或布局），其内部通过 <Outlet /> 挂载子路由视图。
• 动态参数路由：动态参数通过中括号表示。例如 src/pages/users/[id].tsx 编译为 /users/:id，页面中可使用 useParams() 获取动态路径参数。
• 特殊排除目录：以 _ 或 . 开头的文件及目录不会被解析为路由，如 _components/、_models/，这为页面私有模块提供了隔离存放空间。

二、约定式路由下的权限拦截方案选型

在配置式路由中，开发者通常在路由数组中显式配置 wrappers: ['@/wrappers/auth'] 或 access: 'canAdmin'。而在约定式路由下，文件由构建期自动生成，无法直接向隐藏的路由表字段插入属性。解决该问题的工程方案主要有以下三种：

在实际生产环境中，最稳健的架构是采用“分层布局守卫 + 全局状态判定”模式：外层全局布局只做基础身份鉴别（如 Token 存在性与会话维持），各受控业务子目录下的 _layout.tsx（或公共包装组件）执行细粒度 RBAC 角色与权限码匹配。

三、实战开发：构建约定式路由鉴权守卫体系

下面基于真实业务场景，分步实施一套开箱即用的约定式路由权限拦截体系。代码涵盖白名单过滤、全局 Token 状态同步、基于路由前缀的权限字典以及 403 友好降级。

步骤 1：建立权限定义矩阵 (src/access.ts)

权限判定的前提是维护统一的“权限矩阵”。定义当前系统所支持的角色、权限码以及路由前缀访问策略：

// src/constants/auth.ts - 权限码与白名单定义
export const AUTH_WHITE_LIST = ['/login', '/register', '/403', '/404'];

// 路由路径与所需权限码的对应关系映射
export const ROUTE_PERMISSION_MAP: Record<string, string[]> = {
  '/admin': ['ROLE_ADMIN', 'SYS_VIEW'],
  '/admin/users': ['USER_MANAGE'],
  '/finance': ['FINANCE_AUDIT'],
};

步骤 2：创建路由守卫包装组件 (src/wrappers/auth.tsx)

在 UmiJS 中，包装组件本质上是一个高阶组件。在约定式路由体系中，我们将该包装逻辑直接应用于 src/layouts/index.tsx 或作为子目录的 _layout.tsx，以代理目标视图的渲染：

// src/wrappers/auth.tsx - 路由权限拦截守卫
import React, { useEffect, useState } from 'react';
import { useLocation, useNavigate, Outlet } from 'umi';
import { AUTH_WHITE_LIST, ROUTE_PERMISSION_MAP } from '@/constants/auth';

export default function AuthWrapper() {
  const location = useLocation();
  const navigate = useNavigate();
  const [isAuthorized, setIsAuthorized] = useState<boolean | null>(null);

  useEffect(() => {
    const currentPath = location.pathname;

    // 1. 命中白名单直接放行
    if (AUTH_WHITE_LIST.includes(currentPath)) {
      setIsAuthorized(true);
      return;
    }

    // 2. 检查本地认证令牌 (Token)
    const token = localStorage.getItem('auth_token');
    if (!token) {
      // 未登录，携带当前目标重定向至登录页
      navigate(`/login?redirect=${encodeURIComponent(currentPath)}`, { replace: true });
      return;
    }

    // 3. 从缓存或状态中读取当前用户拥有的权限码
    const userPermissions: string[] = JSON.parse(
      localStorage.getItem('user_permissions') || '[]'
    );

    // 4. 匹配当前路由所需权限
    const requiredPermissions = ROUTE_PERMISSION_MAP[currentPath];
    if (requiredPermissions && requiredPermissions.length > 0) {
      const hasPermission = requiredPermissions.some((code) =>
        userPermissions.includes(code)
      );
      if (!hasPermission) {
        navigate('/403', { replace: true });
        return;
      }
    }

    setIsAuthorized(true);
  }, [location.pathname]);

  // 未完成判定前展示轻量骨架屏或加载占位，避免画面撕裂与闪烁
  if (isAuthorized === null) {
    return <div style={{ padding: 40, textAlign: 'center' }}>正在校验权限...</div>;
  }

  return <Outlet />;
}

步骤 3：在约定式布局中挂载守卫 (src/layouts/index.tsx)

在 UmiJS 约定式路由下，src/layouts/index.tsx 自动包裹所有页面。将 AuthWrapper 作为顶层容器，即可使整个约定式路由树受到保护：

// src/layouts/index.tsx - 约定式全局布局入口
import React from 'react';
import AuthWrapper from '@/wrappers/auth';

export default function GlobalLayout() {
  return (
    <div className="app-layout-container">
      <AuthWrapper />
    </div>
  );
}

四、工程实战关键避坑指南与状态异常处理

在真实业务工程中实施约定式路由鉴权，往往会遇到异步网络延迟、路由跳转闪烁及路由元数据缺失等深层问题。以下给出排查依据与针对性应对方案：

五、实战验证与落地效果

在完成上述步骤后，可通过以下标准测试用例进行权限系统的有效性验证，确保每一种用户状态和访问行为均符合系统设计预期：

综上所述，UmiJS 的约定式路由虽弱化了显式配置文件的存在，但借助基于 src/layouts/index.tsx 或局部 _layout.tsx 的守卫包装器机制，开发者依然能够构建出结构清晰、权限细化且具有高度鲁棒性的企业级鉴权拦截系统。