Vue Router中的错误处理与重定向：实现后端错误码到客户端友好页面的映射 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

Vue Router 中的错误处理与重定向：实现后端错误码到客户端友好页面的映射

大家好，今天我们来深入探讨 Vue Router 在错误处理和重定向方面的应用，重点是如何将后端返回的错误码优雅地映射到前端友好的页面上，提升用户体验。这不仅仅是简单地展示一个“404 Not Found”页面，而是要根据不同的错误类型，提供更具针对性的反馈，甚至引导用户完成后续操作。

1. 错误处理的需求与挑战

在单页应用(SPA)中，所有路由切换都由前端控制，因此错误处理也更多地由前端负责。我们需要处理以下几种常见的错误情况：

客户端路由错误: 用户访问了不存在的路由，例如输入错误的 URL。
服务端返回错误: 前端请求后端接口时，后端返回了错误码，例如 403 Forbidden, 500 Internal Server Error 等。
权限验证失败: 用户尝试访问需要特定权限才能访问的路由，但未通过验证。
数据加载失败: 组件在加载数据时发生错误，例如网络请求失败或数据解析错误。

挑战在于，我们需要统一处理这些不同来源的错误，并且提供一致的用户体验。简单的alert弹窗并不可取，理想的做法是：

用户友好: 展示清晰、易懂的错误信息，避免让用户感到困惑。
引导性: 根据错误类型，引导用户进行后续操作，例如返回首页、重新登录、联系客服等。
可维护性: 错误处理逻辑应该集中管理，方便修改和扩展。
可测试性: 能够方便地对错误处理逻辑进行单元测试和集成测试。

2. Vue Router 提供的机制

Vue Router 提供了一些内置的机制来帮助我们处理错误：

通配符路由 (Wildcard Route): 可以定义一个匹配所有未知路由的路由，用于处理 404 Not Found 错误。
beforeEach 导航守卫: 在每次路由切换前执行，可以用于进行权限验证、重定向等操作。
afterEach 导航守卫: 在每次路由切换后执行，可以用于记录日志、更新页面标题等操作。
next(error): 在导航守卫中，可以通过 next(error) 来中断路由导航，并将错误传递给错误处理函数。

这些机制为我们构建灵活的错误处理流程提供了基础。

3. 实现后端错误码到前端页面的映射

下面我们来详细讲解如何实现后端错误码到前端页面的映射。

3.1 定义错误码与页面映射关系

首先，我们需要定义一个错误码与页面之间的映射关系。这可以通过一个简单的 JavaScript 对象来实现：

// error-code-mapping.js
const errorCodeMapping = {
  400: {
    path: '/error/bad-request',
    message: '请求错误，请检查您的输入。',
  },
  401: {
    path: '/error/unauthorized',
    message: '您未登录或登录已过期，请重新登录。',
  },
  403: {
    path: '/error/forbidden',
    message: '您没有权限访问该页面。',
  },
  404: {
    path: '/error/not-found',
    message: '您访问的页面不存在。',
  },
  500: {
    path: '/error/internal-server-error',
    message: '服务器内部错误，请稍后再试。',
  },
  // 其他错误码...
};

export default errorCodeMapping;

这个 errorCodeMapping 对象包含了常见的 HTTP 状态码，以及对应的页面路径和错误提示信息。可以根据实际需要添加更多的错误码。

3.2 创建错误页面组件

接下来，我们需要创建对应的错误页面组件，例如：

// ErrorBadRequest.vue
<template>
  <div class="error-page">
    <h1>400 Bad Request</h1>
    <p>{{ message }}</p>
    <button @click="$router.push('/')">返回首页</button>
  </div>
</template>

<script>
export default {
  props: {
    message: {
      type: String,
      default: '请求错误，请检查您的输入。',
    },
  },
};
</script>

<style scoped>
.error-page {
  text-align: center;
  padding: 20px;
}
</style>

其他的错误页面组件 ( ErrorUnauthorized.vue, ErrorForbidden.vue, ErrorNotFound.vue, ErrorInternalServerError.vue) 结构类似，只是错误码和标题有所不同。都可以接收一个 message prop，用于显示错误提示信息。

3.3 配置 Vue Router

现在，我们需要在 Vue Router 中配置这些错误页面。

// router/index.js
import Vue from 'vue';
import VueRouter from 'vue-router';
import Home from '../views/Home.vue';
import ErrorBadRequest from '../components/ErrorBadRequest.vue';
import ErrorUnauthorized from '../components/ErrorUnauthorized.vue';
import ErrorForbidden from '../components/ErrorForbidden.vue';
import ErrorNotFound from '../components/ErrorNotFound.vue';
import ErrorInternalServerError from '../components/ErrorInternalServerError.vue';
import errorCodeMapping from '../error-code-mapping';

Vue.use(VueRouter);

const routes = [
  {
    path: '/',
    name: 'Home',
    component: Home,
  },
  {
    path: '/error/bad-request',
    name: 'ErrorBadRequest',
    component: ErrorBadRequest,
    props: { message: errorCodeMapping[400].message },
  },
  {
    path: '/error/unauthorized',
    name: 'ErrorUnauthorized',
    component: ErrorUnauthorized,
    props: { message: errorCodeMapping[401].message },
  },
  {
    path: '/error/forbidden',
    name: 'ErrorForbidden',
    component: ErrorForbidden,
    props: { message: errorCodeMapping[403].message },
  },
  {
    path: '/error/not-found',
    name: 'ErrorNotFound',
    component: ErrorNotFound,
    props: { message: errorCodeMapping[404].message },
  },
  {
    path: '/error/internal-server-error',
    name: 'ErrorInternalServerError',
    component: ErrorInternalServerError,
    props: { message: errorCodeMapping[500].message },
  },
  {
    path: '*', // 通配符路由，匹配所有未定义的路由
    name: 'NotFound',
    component: ErrorNotFound,
    props: { message: '您访问的页面不存在。' },
  },
];

const router = new VueRouter({
  mode: 'history',
  base: process.env.BASE_URL,
  routes,
});

router.beforeEach((to, from, next) => {
  // 可以在这里进行权限验证等操作
  // 例如：
  // if (to.meta.requiresAuth && !isAuthenticated()) {
  //   next('/error/unauthorized');
  // } else {
  //   next();
  // }
  next();
});

export default router;

这里配置了所有错误页面的路由，并将 errorCodeMapping 中对应的 message 传递给组件作为 props。还添加了一个通配符路由 *，用于处理 404 Not Found 错误。 beforeEach 导航守卫可以用于进行权限验证，根据验证结果重定向到对应的错误页面。

3.4 处理后端返回的错误

当后端返回错误码时，我们需要在前端进行处理，并将用户重定向到对应的错误页面。这通常在 axios 等 HTTP 客户端的拦截器中完成：

// api.js (使用 Axios)
import axios from 'axios';
import router from './router';
import errorCodeMapping from './error-code-mapping';

axios.interceptors.response.use(
  (response) => {
    return response;
  },
  (error) => {
    const status = error.response ? error.response.status : null;

    if (status && errorCodeMapping[status]) {
      const { path, message } = errorCodeMapping[status];
      router.push({ path, query: { message } }); // 传递 message 作为 query 参数
      return Promise.reject(error); // 重要：需要 reject error，否则后续的 then 会执行
    } else {
      // 处理其他类型的错误，例如网络错误
      console.error('网络错误或未知错误：', error);
      router.push({ path: '/error/internal-server-error', query: { message: '网络错误或未知错误，请稍后再试。' } });
      return Promise.reject(error);
    }
  }
);

export default axios;

这段代码拦截了 axios 的响应，如果响应状态码存在于 errorCodeMapping 中，则将用户重定向到对应的错误页面，并将错误提示信息作为 query 参数传递。 注意，这里必须 reject(error)，否则Promise会继续执行后续的.then语句，可能会导致难以预料的错误。

修改Error页面组件，让其从query参数中获取message：

// ErrorBadRequest.vue
<template>
  <div class="error-page">
    <h1>400 Bad Request</h1>
    <p>{{ message }}</p>
    <button @click="$router.push('/')">返回首页</button>
  </div>
</template>

<script>
export default {
  props: {
    // message: { // 删除 props 定义
    //   type: String,
    //   default: '请求错误，请检查您的输入。',
    // },
  },
  computed: {
    message() {
      return this.$route.query.message || '请求错误，请检查您的输入。'; // 从 query 参数中获取 message
    },
  },
};
</script>

<style scoped>
.error-page {
  text-align: center;
  padding: 20px;
}
</style>

修改router配置，不再使用props传递message：

// router/index.js
// ...
const routes = [
  // ...
  {
    path: '/error/bad-request',
    name: 'ErrorBadRequest',
    component: ErrorBadRequest,
    // props: { message: errorCodeMapping[400].message }, // 删除 props 定义
  },
  {
    path: '/error/unauthorized',
    name: 'ErrorUnauthorized',
    component: ErrorUnauthorized,
    // props: { message: errorCodeMapping[401].message }, // 删除 props 定义
  },
  {
    path: '/error/forbidden',
    name: 'ErrorForbidden',
    component: ErrorForbidden,
    // props: { message: errorCodeMapping[403].message }, // 删除 props 定义
  },
  {
    path: '/error/not-found',
    name: 'ErrorNotFound',
    component: ErrorNotFound,
    // props: { message: errorCodeMapping[404].message }, // 删除 props 定义
  },
  {
    path: '/error/internal-server-error',
    name: 'ErrorInternalServerError',
    component: ErrorInternalServerError,
    // props: { message: errorCodeMapping[500].message }, // 删除 props 定义
  },
  {
    path: '*', // 通配符路由，匹配所有未定义的路由
    name: 'NotFound',
    component: ErrorNotFound,
    // props: { message: '您访问的页面不存在。' }, // 删除 props 定义
  },
];

3.5 错误处理组件的使用

在组件中，我们可以像这样发起请求：

<template>
  <div>
    <button @click="fetchData">获取数据</button>
  </div>
</template>

<script>
import axios from '../api';

export default {
  methods: {
    async fetchData() {
      try {
        const response = await axios.get('/api/data'); // 假设后端返回 403 错误
        console.log(response.data);
      } catch (error) {
        // 错误已经在 axios 拦截器中处理，这里不需要再次处理
        console.error('请求失败：', error);
      }
    },
  },
};
</script>

如果后端返回了错误码，axios 拦截器会自动将用户重定向到对应的错误页面。

4. 优化和扩展

自定义错误页面: 可以根据项目的具体需求，设计更加美观、用户友好的错误页面。
错误日志记录: 可以将错误信息记录到日志服务器，方便排查问题。
重试机制: 对于某些类型的错误，可以尝试自动重试请求。
全局错误处理: 可以使用 Vue 的 errorHandler 选项来捕获全局错误，并进行统一处理。
i18n 支持: 可以为错误提示信息提供多语言支持。
错误类型细化： 可以根据业务需求，自定义更具体的错误码，例如 USER_NOT_FOUND，INVALID_PASSWORD 等，并在 errorCodeMapping 中进行映射。
错误上报： 可以集成像 Sentry 这样的错误监控平台，将错误信息上报，方便及时发现和解决问题。

5. 代码示例总结

为了方便大家理解，下面是主要代码片段的汇总：

error-code-mapping.js:

const errorCodeMapping = {
  400: {
    path: '/error/bad-request',
    message: '请求错误，请检查您的输入。',
  },
  401: {
    path: '/error/unauthorized',
    message: '您未登录或登录已过期，请重新登录。',
  },
  403: {
    path: '/error/forbidden',
    message: '您没有权限访问该页面。',
  },
  404: {
    path: '/error/not-found',
    message: '您访问的页面不存在。',
  },
  500: {
    path: '/error/internal-server-error',
    message: '服务器内部错误，请稍后再试。',
  },
  // 其他错误码...
};

export default errorCodeMapping;

ErrorBadRequest.vue (示例):

<template>
  <div class="error-page">
    <h1>400 Bad Request</h1>
    <p>{{ message }}</p>
    <button @click="$router.push('/')">返回首页</button>
  </div>
</template>

<script>
export default {
  computed: {
    message() {
      return this.$route.query.message || '请求错误，请检查您的输入。'; // 从 query 参数中获取 message
    },
  },
};
</script>

<style scoped>
.error-page {
  text-align: center;
  padding: 20px;
}
</style>

router/index.js (片段):

import Vue from 'vue';
import VueRouter from 'vue-router';
import ErrorNotFound from '../components/ErrorNotFound.vue';

Vue.use(VueRouter);

const routes = [
  // ... 其他路由
  {
    path: '/error/not-found',
    name: 'ErrorNotFound',
    component: ErrorNotFound,
  },
  {
    path: '*', // 通配符路由，匹配所有未定义的路由
    name: 'NotFound',
    component: ErrorNotFound,
  },
];

api.js (Axios 拦截器):

import axios from 'axios';
import router from './router';
import errorCodeMapping from './error-code-mapping';

axios.interceptors.response.use(
  (response) => {
    return response;
  },
  (error) => {
    const status = error.response ? error.response.status : null;

    if (status && errorCodeMapping[status]) {
      const { path, message } = errorCodeMapping[status];
      router.push({ path, query: { message } }); // 传递 message 作为 query 参数
      return Promise.reject(error); // 重要：需要 reject error
    } else {
      console.error('网络错误或未知错误：', error);
      router.push({ path: '/error/internal-server-error', query: { message: '网络错误或未知错误，请稍后再试。' } });
      return Promise.reject(error);
    }
  }
);

export default axios;

6. 总结

通过上述讲解，我们了解了如何使用 Vue Router 来实现后端错误码到前端友好页面的映射。核心思想是定义错误码与页面的映射关系，创建对应的错误页面组件，并在 HTTP 客户端的拦截器中进行处理。这种方法能够有效地提升用户体验，并且方便维护和扩展。希望这篇分享对大家有所帮助！

更多IT精英技术系列讲座，到智猿学院