hzdyjs/docs/开发文档/移动端路由守卫使用指南.md

# 移动端路由守卫使用指南

## 📋 概述

移动端路由守卫是一个全局的权限控制系统，确保用户未登录或登录失效时，访问需要权限的页面会自动跳转到登录页。

## 🎯 核心功能

### 1. 自动权限检查

-   **页面加载时检查** → `onLoad()` 生命周期
-   **页面显示时检查** → `onShow()` 生命周期
-   **页面跳转前检查** → 使用守卫跳转方法
-   **HTTP 请求拦截** → 401 响应自动处理

### 2. 多层次验证

-   ✅ 检查登录状态 `userStorage.isLoggedIn()`
-   ✅ 检查 Token 存在 `userStorage.getToken()`
-   ✅ 检查 Token 过期 `userState.checkTokenExpiration()`
-   ✅ 区分公开页面和受保护页面

### 3. 优雅的用户体验

-   🎨 友好的错误提示
-   🎨 自动清理失效信息
-   🎨 延迟跳转确保提示显示
-   🎨 使用 `reLaunch` 清除页面栈

## 🔧 使用方法

### 在页面中使用

```javascript
<script>
import { checkPageAccess } from '@/utils/route-guard';

export default {
    onLoad() {
        // 页面加载时检查权限
        if (!checkPageAccess()) {
            return; // 权限检查失败，自动跳转登录页
        }

        // 页面初始化逻辑
        this.initPageData();
    },

    onShow() {
        // 页面显示时再次检查权限（防止后台切换回来时失效）
        if (!checkPageAccess()) {
            return;
        }

        // 刷新页面数据
        this.refreshData();
    },

    methods: {
        initPageData() {
            // 需要登录权限的初始化逻辑
        },

        refreshData() {
            // 需要登录权限的数据刷新逻辑
        }
    }
}
</script>
```

### 带权限检查的页面跳转

```javascript
<script>
import { guardedNavigate, guardedSwitchTab } from '@/utils/route-guard';

export default {
    methods: {
        // 普通页面跳转
        goToProfile() {
            guardedNavigate('/pages/profile/index');
        },

        // Tab页面切换
        switchToWorkbench() {
            guardedSwitchTab('/pages/workbench/index');
        },

        // 带参数跳转
        goToDetail(id) {
            guardedNavigate(`/pages/detail/index?id=${id}`);
        }
    }
}
</script>
```

### 使用页面混入（可选）

```javascript
<script>
import { routeGuardMixin } from '@/utils/route-guard';

export default {
    // 使用混入，自动添加权限检查
    mixins: [routeGuardMixin],

    onLoad() {
        // 混入会自动调用权限检查
        // 这里只需要写业务逻辑
        this.loadData();
    }
}
</script>
```

## ⚙️ 配置说明

### 公开页面配置

在 `mobile/src/utils/route-guard.js` 中配置无需登录的页面：

```javascript
// 无需登录验证的页面列表
const PUBLIC_PAGES = [
    '/pages/login/index', // 登录页
    '/pages/index/index', // 首页（功能受限但可访问）
];
```

### 自定义登录页路径

```javascript
// 登录页路径
const LOGIN_PAGE = '/pages/login/index';
```

## 🧪 测试功能

访问测试页面验证路由守卫功能：

```
页面路径: /pages/test-route/index
```

测试页面提供：

-   📊 实时登录状态显示
-   🔧 测试按钮（清除 Token、跳转等）
-   📋 详细的操作日志
-   🎯 权限检查结果验证

## 🔄 工作流程

### 权限检查流程

```mermaid
graph TD
    A[页面访问] --> B{是否公开页面?}
    B -->|是| C[允许访问]
    B -->|否| D{用户已登录?}
    D -->|否| E[跳转登录页]
    D -->|是| F{Token存在?}
    F -->|否| E
    F -->|是| G{Token未过期?}
    G -->|否| E
    G -->|是| C
```

### HTTP 拦截流程

```mermaid
graph TD
    A[API请求] --> B[发送请求]
    B --> C{响应状态}
    C -->|200| D[正常处理]
    C -->|401| E[清除登录信息]
    E --> F[显示提示]
    F --> G[跳转登录页]
```

## 📝 最佳实践

### 1. 页面权限设计原则

-   **最小权限原则**：只有必要的页面才需要登录
-   **用户友好原则**：首页等入口页面可以部分访问
-   **安全优先原则**：敏感操作必须验证权限

### 2. 错误处理建议

```javascript
onLoad() {
    try {
        if (!checkPageAccess()) {
            return;
        }

        // 业务逻辑
        await this.loadUserData();

    } catch (error) {
        console.error('页面初始化失败:', error);
        uni.showToast({
            title: '页面加载失败',
            icon: 'none'
        });
    }
}
```

### 3. 性能优化建议

-   权限检查放在业务逻辑之前
-   避免在权限检查失败后继续执行后续逻辑
-   合理使用页面缓存减少重复检查

## 🚨 注意事项

### 1. 公开页面处理

```javascript
// ❌ 错误：在公开页面中强制检查权限
onLoad() {
    if (!checkPageAccess()) return; // 首页不应该强制登录
}

// ✅ 正确：区分功能的权限要求
onLoad() {
    // 首页可以访问，但部分功能需要登录
    this.checkLoginForFeatures();
}
```

### 2. 避免循环跳转

```javascript
// ❌ 错误：在登录页中调用权限检查
// pages/login/index.vue
onLoad() {
    checkPageAccess(); // 会导致循环跳转
}

// ✅ 正确：登录页无需权限检查
onLoad() {
    // 直接执行登录页逻辑
}
```

### 3. Token 刷新处理

```javascript
// 建议在HTTP拦截器中处理Token刷新
// 避免在页面级别处理复杂的Token逻辑
```

## 🔗 相关文档

-   [移动端用户管理工具](./移动端用户管理工具使用指南.md)
-   [移动端 API 请求规范](./移动端API请求规范.md)
-   [移动端开发规范总结](./移动端开发规范总结.md)

## 💡 常见问题

### Q: 如何添加新的公开页面？

A: 在 `route-guard.js` 的 `PUBLIC_PAGES` 数组中添加页面路径。

### Q: 权限检查失败但没有跳转到登录页？

A: 检查控制台日志，确认 `reLaunch` 是否执行成功，必要时检查页面路径配置。

### Q: 如何自定义权限检查逻辑？

A: 可以扩展 `checkPageAccess` 函数，添加更复杂的权限验证逻辑。

### Q: 在什么情况下需要使用 `routeGuardMixin`？

A: 当页面逻辑复杂，希望自动化权限检查时使用，但通常建议手动调用以保持代码清晰。