npm package: @gulibs/plugin-react-autoroutes
Description: 一个基于文件系统的自动路由生成 Vite 插件，为 React 应用程序提供基于文件系统的自动路由生成功能
Author: HectorGu
Latest version: 0.0.10
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# @gulibs/plugin-react-autoroutes

一个基于文件系统的自动路由生成 Vite 插件，为 React 应用程序提供强大的自动路由功能。

## 特性

- **基于文件系统的路由** - 根据文件结构自动生成路由配置
- **灵活的目录结构** - 支持多种文件组织方式和命名约定
- **路由保护** - 内置认证、权限、角色守卫支持
- **中间件系统** - 支持路由级别的中间件
- **热更新** - 文件变化时自动重新生成路由
- **TypeScript 支持** - 完整的类型定义和智能提示
- **现代路由特性** - 支持动态路由、嵌套路由、错误边界
- **高度可配置** - 支持自定义文件模式和路由生成规则

## 安装

```bash
npm install @gulibs/plugin-react-autoroutes --save-dev
# 或
pnpm add @gulibs/plugin-react-autoroutes -D
# 或
yarn add @gulibs/plugin-react-autoroutes -D
```

### 对等依赖

```bash
npm install react react-dom react-router @gulibs/react-autoroutes-client
```

## 快速开始

### 1. 配置插件

```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
import autoRouter from '@gulibs/plugin-react-autoroutes';

export default defineConfig({
  plugins: [
    react(),
    autoRouter({
      dirs: [
        {
          dir: 'src/pages',
          baseRoute: '/'
        }
      ],
      debug: true,
      routeMode: 'flat' // 'flat' | 'nested'
    })
  ]
});
```

### 2. 创建页面文件

```
src/pages/
├── page.tsx              # 首页 (/)
├── about/
│   └── page.tsx          # 关于页 (/about)
├── users/
│   ├── page.tsx          # 用户列表 (/users)
│   ├── [id]/
│   │   └── page.tsx      # 用户详情 (/users/:id)
│   └── [...slug]/
│       └── page.tsx      # 捕获所有路由 (/users/*)
├── admin/
│   ├── layout.tsx        # 布局组件
│   ├── page.tsx          # 管理首页 (/admin)
│   ├── auth.tsx          # 认证守卫
│   └── users/
│       ├── page.tsx      # 管理用户 (/admin/users)
│       ├── loading.tsx   # 加载组件
│       └── error.tsx     # 错误边界
└── 404.tsx               # 404 页面 (*)
```

### 3. 在应用中使用

```typescript
// src/App.tsx
import { RouterProvider, createBrowserRouter } from 'react-router';
import { routes } from '@gulibs/react-autopages'; // 虚拟模块

const router = createBrowserRouter(routes);

function App() {
  return <RouterProvider router={router} />;
}

export default App;
```

## 文件约定

### 页面文件

| 文件名 | 说明 | 示例路径 |
|--------|------|----------|
| `page.tsx` | 页面组件 | `/users/page.tsx` → `/users` |
| `index.tsx` | 索引页面 | `/users/index.tsx` → `/users` |
| `layout.tsx` | 布局组件 | `/admin/layout.tsx` |
| `error.tsx` | 错误边界 | `/users/error.tsx` |
| `loading.tsx` | 加载组件 | `/users/loading.tsx` |
| `404.tsx` | 404 页面 | `/404.tsx` → `*` |

### 路由特性文件

| 文件名 | 说明 | 功能 |
|--------|------|------|
| `handle.tsx` | 路由配置 | 页面元数据、面包屑 |
| `middleware.tsx` | 中间件 | 路由拦截处理 |
| `guard.tsx` | 路由守卫 | 访问控制 |
| `auth.tsx` | 认证守卫 | 用户认证 |

### 动态路由

| 文件路径 | 路由路径 | 说明 |
|----------|----------|------|
| `[id]/page.tsx` | `/:id` | 单个参数 |
| `[...slug]/page.tsx` | `/*` | 捕获所有路由 |
| `[[optional]]/page.tsx` | `/:optional?` | 可选参数 |

## 路由保护

### 认证守卫

```typescript
// src/pages/admin/auth.tsx
import { defineAuth } from '@gulibs/react-autoroutes-client';

export default defineAuth({
  redirectTo: '/login',
  errorMessage: '请先登录',
  check: (context) => {
    return !!context.user && context.user.isAuthenticated;
  }
});
```

### 权限守卫

```typescript
// src/pages/admin/users/guard.tsx
import { defineGuard } from '@gulibs/react-autoroutes-client';

export default defineGuard({
  name: 'admin-permission',
  type: 'permission',
  redirectTo: '/forbidden',
  errorMessage: '需要管理员权限',
  condition: (context) => {
    return context.user?.permissions?.includes('admin');
  }
});
```

### 角色守卫

```typescript
// src/pages/admin/guard.tsx
import { defineRoleGuard } from '@gulibs/react-autoroutes-client';

export default defineRoleGuard(['admin', 'moderator'], '/login');
```

## 中间件

```typescript
// src/pages/api/middleware.tsx
import { defineMiddleware } from '@gulibs/react-autoroutes-client';

export default defineMiddleware({
  name: 'logging',
  priority: 100,
  handler: async (context, next) => {
    console.log(`访问路由: ${context.path}`);

    const start = Date.now();
    await next();
    const duration = Date.now() - start;

    console.log(`路由处理耗时: ${duration}ms`);
  }
});
```

## 页面配置

```typescript
// src/pages/users/handle.tsx
import { defineHandle } from '@gulibs/react-autoroutes-client';

export default defineHandle({
  meta: {
    title: 'users.title', // 支持国际化键
    description: '用户管理页面'
  },
  breadcrumbs: {
    href: '/users',
    children: '用户管理'
  },
  layoutSettings: {
    layout: true,
    footer: true
  }
});
```

## 配置选项

```typescript
interface UserOptions {
  /** 路由目录配置 */
  dirs: RouteOption[];
  /** 是否启用动态导入 */
  dynamic?: boolean;
  /** 是否启用缓存 */
  cache?: boolean;
  /** 缓存时间（毫秒） */
  cacheTime?: number;
  /** 是否启用调试模式 */
  debug?: boolean;
  /** 路由模式 */
  routeMode?: 'nested' | 'flat';
}

interface RouteOption {
  /** 路由目录路径 */
  dir: string;
  /** 基础路由路径 */
  baseRoute: string;
  /** 自定义文件匹配模式 */
  include?: string[];
  /** 排除的文件模式 */
  exclude?: string[];
}
```

### 配置示例

```typescript
// vite.config.ts
export default defineConfig({
  plugins: [
    autoRouter({
      dirs: [
        {
          dir: 'src/pages',
          baseRoute: '/',
          exclude: ['**/components/**', '**/_*'] // 排除组件和私有文件
        },
        {
          dir: 'src/admin',
          baseRoute: '/admin',
          include: ['**/*.{tsx,ts}'] // 只包含 TypeScript 文件
        }
      ],
      dynamic: true, // 启用代码分割
      cache: true,
      cacheTime: 60000, // 1分钟缓存
      debug: process.env.NODE_ENV === 'development',
      routeMode: 'flat' // 扁平路由模式
    })
  ]
});
```

## 高级用法

### 1. 嵌套路由

```typescript
// 配置嵌套路由模式
autoRouter({
  routeMode: 'nested',
  dirs: [{ dir: 'src/pages', baseRoute: '/' }]
});
```

嵌套路由会创建父子关系：

```
src/pages/
├── layout.tsx          # 根布局
├── page.tsx           # 首页
└── dashboard/
    ├── layout.tsx      # 仪表盘布局
    ├── page.tsx       # 仪表盘首页
    └── users/
        └── page.tsx    # 嵌套在仪表盘布局下的用户页
```

### 2. 嵌套路由继承

在嵌套路由模式下，子路由会自动继承父路由的保护机制：

```
src/pages/
├── admin/
│   ├── layout.tsx      # 管理员布局
│   ├── auth.tsx        # 管理员认证守卫（子路由会继承）
│   ├── middleware.tsx  # 管理员中间件（子路由会继承）
│   ├── page.tsx        # 管理首页
│   ├── users/
│   │   └── page.tsx    # 用户管理（自动继承 admin 的认证和中间件）
│   └── settings/
│       ├── page.tsx    # 设置页面（自动继承 admin 的认证和中间件）
│       └── guard.tsx   # 额外的权限守卫（与继承的守卫合并）
```

生成的路由会自动处理继承：

```typescript
{
  path: '/admin',
  element: AdminLayout,
  guards: [adminAuth],
  middleware: [adminMiddleware],
  children: [
    {
      path: '/admin/users',
      element: UsersPage,
      guards: [adminAuth], // 继承自父路由
      middleware: [adminMiddleware] // 继承自父路由
    },
    {
      path: '/admin/settings',
      element: SettingsPage,
      guards: [adminAuth, settingsGuard], // 继承的 + 自己的
      middleware: [adminMiddleware] // 继承自父路由
    }
  ]
}
```

### 3. 多目录支持

```typescript
autoRouter({
  dirs: [
    { dir: 'src/pages', baseRoute: '/' },        // 主要页面
    { dir: 'src/admin', baseRoute: '/admin' },   // 管理页面
    { dir: 'src/blog', baseRoute: '/blog' }      // 博客页面
  ]
});
```

### 4. 自定义文件匹配

```typescript
autoRouter({
  dirs: [{
    dir: 'src/routes',
    baseRoute: '/',
    include: ['**/*.route.{tsx,ts}'],          // 只匹配 .route 文件
    exclude: ['**/components/**', '**/_*']     // 排除组件和私有文件
  }]
});
```

## 性能优化

### 1. 代码分割

```typescript
// 启用动态导入
autoRouter({
  dynamic: true // 每个页面组件都会被动态导入
});
```

### 2. 缓存策略

```typescript
autoRouter({
  cache: true,
  cacheTime: 300000 // 5分钟缓存
});
```

### 3. 构建优化

```typescript
// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'react-vendor': ['react', 'react-dom'],
          'router-vendor': ['react-router']
        }
      }
    }
  }
});
```

## 调试

启用调试模式查看路由生成过程：

```typescript
autoRouter({
  debug: true
});
```

调试输出示例：

```
14:25:30 ▸ [react-auto-routes] Generated 15 route(s) with 28 import(s) in 45ms
14:25:30 ▸ [react-auto-routes] add src/pages/users/[id]/page.tsx reload server
14:25:30 ▸ [react-auto-routes] Route generation took 12ms
```

## 故障排除

### 常见问题

#### 1. 路由未生成

**检查步骤：**

```bash
# 1. 确认文件命名正确
ls src/pages/*/page.tsx

# 2. 检查插件配置
# 确保 dir 路径正确，baseRoute 不为空

# 3. 启用调试模式
# debug: true
```

#### 2. 动态路由不工作

确保文件命名使用正确的约定：

```
✅ [id]/page.tsx        → /:id
✅ [...slug]/page.tsx   → /*
❌ {id}/page.tsx        → 无效
❌ [id].tsx            → 无效（需要 page.tsx）
```

#### 3. 路由保护不生效

检查 `@gulibs/react-autoroutes-client` 是否正确安装：

```bash
npm list @gulibs/react-autoroutes-client
```

如果未安装，插件会显示警告并生成空路由。

#### 4. 热更新不工作

确保文件在监视目录内：

```typescript
// 检查文件是否在配置的目录中
autoRouter({
  dirs: [{ dir: 'src/pages', baseRoute: '/' }] // 确保路径正确
});
```

### 性能问题

如果路由生成缓慢：

```typescript
autoRouter({
  cache: true,        // 启用缓存
  cacheTime: 60000,   // 适当的缓存时间
  exclude: [          // 排除不必要的文件
    '**/node_modules/**',
    '**/dist/**',
    '**/.git/**'
  ]
});
```

## 与其他工具集成

### 与 @gulibs/vite-plugin-i18n 集成

```typescript
// vite.config.ts
import autoRouter from '@gulibs/plugin-react-autoroutes';
import i18nPlugin from '@gulibs/vite-plugin-i18n';

export default defineConfig({
  plugins: [
    autoRouter({
      dirs: [{ dir: 'src/pages', baseRoute: '/' }]
    }),
    i18nPlugin({
      basePath: 'src/locales',
      keysOutput: 'src/i18n-keys.ts'
    })
  ]
});
```

### 与状态管理库集成

```typescript
// src/pages/dashboard/handle.tsx
export default defineHandle({
  meta: {
    title: 'dashboard.title',
    description: 'dashboard.description'
  },
  // 可以添加自定义数据供状态管理使用
  storeConfig: {
    preloadData: ['user', 'settings']
  }
});
```

## 更新日志

### v0.0.3

- 🎉 **新增**：嵌套路由现在会自动继承父路由的 guards、middleware 和 handle 配置
- 🎉 **新增**：支持可选参数路由 `[[optional]]` -> `:optional?`
- 🔧 **优化**：重构路由创建逻辑，减少代码重复
- 🔧 **优化**：增强缓存策略，使用文件内容哈希进行更精确的缓存失效判断
- 🔧 **优化**：改进类型导入，提升代码健壮性
- 🐛 **修复**：修复嵌套路由中的类型错误

### v0.0.2

- 添加嵌套路由支持
- 增强路由保护功能
- 优化缓存策略
- 修复动态路由解析问题

### v0.0.1

- 初始版本发布
- 基础文件系统路由
- 中间件和守卫支持

## 许可证

MIT License - 详见 [LICENSE](./LICENSE) 文件

## 相关项目

- [@gulibs/react-autoroutes-client](../react-autoroutes-client) - React 路由客户端库
- [@gulibs/vite-plugin-i18n](../vite-plugin-i18n) - Vite 国际化插件

---

> **提示**：遇到问题时，请首先启用 `debug: true` 查看详细日志，这有助于快速定位问题。