vue-router3源码注解系列 /src/create-route-map.js

/* @flow */

/*
  用于路径匹配的正则表达式对象。
*/
import Regexp from 'path-to-regexp'
//用于清理 uri 上连续重复的 / 。
import {
    cleanPath } from './util/path'
//断言，警告。
import {
    assert, warn } from './util/warn'

/*
  createRouteMap() 函数: 
  第一个参数 routes 就是 new VueRouter( { routes: [xxxx] } ) 中的 routes。
*/
export function createRouteMap(
  routes: Array<RouteConfig>,
  oldPathList?: Array<string>,
  oldPathMap?: Dictionary<RouteRecord>,
  oldNameMap?: Dictionary<RouteRecord>,
  parentRoute?: RouteRecord
): {
   
  pathList: Array<string>,
  pathMap: Dictionary<RouteRecord>,
  nameMap: Dictionary<RouteRecord>,
} {
   
  // the path list is used to control path matching priority
  //存放所有路由的 path 。
  const pathList: Array<string> = oldPathList || []
  // $flow-disable-line
  //以 path 作为 key，存放所有的路由描述对象。
  const pathMap: Dictionary<RouteRecord> = oldPathMap || Object.create(null)
  // $flow-disable-line
  //以 name 作为 key，存放所有路由描述对象。
  const nameMap: Dictionary<RouteRecord> = oldNameMap || Object.create(null)

  //routes 是一个数组对象。也就是用户手写的 new VueRouter( { routes: [xxx] } ) 的 routes 配置数据
  //遍历routes数组的数据，将所有元素转化为 router record 对象。且会被记录到 pathMap, nameMap 对象中。
  routes.forEach((route) => {
   
    //pathList: 全局的 pathList，所有路由创建过程中是同一个 pathList.
    //pathMap:  全局的 pathMap, 所有路由创建过程中是同一个 pathMap.
    //nameMap:  全局的 nameMap, 所有路由创建过程中是同一个 nameMap.
    //route：    就是要转化为的 router record 对象的数据。
    //parentRoute：表示父 route 数据转化成的 router record 对象。
    addRouteRecord(pathList, pathMap, nameMap, route, parentRoute)
  })

  /**
   * 这一段主要处理 pathList 中的 path == ‘*’ 的路径，且移到数组末尾。
   */
  //依次遍历 pathList。 pathList 中元素都是完整绝对路径。
  // 如果 pathList 中存在 path 路径为 “*”，则移除该元素，并且追加到 pathList 数组末尾。
  for (let i = 0, l = pathList.length; i < l; i++) {
   
    if (pathList[i] === '*') {
   
      //先移除第 i 个元素，pathList.splice() 返回被移除元素的数组。
      //因为只移除了一个，则获取下标为0的元素，然后塞到数组的末尾。
      pathList.push(pathList.splice(i, 1)[0])
      //之所以要 l--, 是因为 l ~ length 的元素就是 * 号，已经处理过了。
      //如果 l 不 --， 存在多个 * 的情况，则会死循环。
      l--
      //此时i+1 ～ length-1 的元素已经迁移。后一个元素已经占在了 i 位置。
      //  所以需要 i--，然后下一轮循环就能取到下一个没有判断*的元素。
      i--
    }
  }

  /*
    如果是开发环境，且 pathList 中 path 元素，不是以 * 或者 / 开头，则报警告。
  */
  if (process.env.NODE_ENV === 'development') {
   
    // warn if routes do not include leading slashes
    const found = pathList
      // check for missing leading slash
      .filter(
        (path) => path && path.charAt(0) !== '*' && path.charAt