vue-router源码：create-route-map

发表于 | 分类于 ， ，

vue-router源码解析系列。这是第二篇。本篇介绍源码中的create-route-map.js，它在vue-router中的作用是将路由配置数据routes解析为路由匹配时需要的数据，了解它的源码之后，能够加强对于routes配置的理解和使用。本系列解析的是官方git库中3.1.6的版本源码。

源码链接：create-route-map.js。源码里面用的是typescript，但是不影响阅读。

预备知识

首先我们要知道，vue-router实例是通常在router/index.js这个文件中进行实例化的，如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
import Vue from 'vue'
import Router from 'vue-router'

const Index = r => require.ensure([], () => r(require('../pages/Index.vue')), 'Index')
const List = r => require.ensure([], () => r(require('../pages/List.vue')), 'List')
const Detail = r => require.ensure([], () => r(require('../pages/Detail.vue')), 'Detail')

Vue.use(Router)

const router = new Router({
  mode: 'history',
  routes: [
    {
      path: '/',
      component: Index
    },
    {
      path: '/index',
      redirect: '/'
    },
    {
      name: 'list',
      path: '/list',
      component: List
    },
    {
      name: 'detail',
      path: '/detail/:id',
      component: Detail,
      alias: ['/query/:id'],
      children: [
        {
          name: 'detail_more',
          path: 'more',
          components: {
            bar: () => import(/* webpackChunkName: "group-bar" */ '../pages/Bar.vue')
          }
        }
      ]
    }
  ]
})
export default router

vue-router的实例所对应的源码是：index.js，在这个文件内，可以看到Router的构造函数：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
export default class VueRouter {
  // 省略了一部分代码

  constructor (options: RouterOptions = {}) {
    this.app = null
    this.apps = []
    this.options = options
    this.beforeHooks = []
    this.resolveHooks = []
    this.afterHooks = []
    this.matcher = createMatcher(options.routes || [], this)
    // 省略了一部分代码
  }

  // 省略了一部分代码
}

本篇还不涉及到学习index.js，所以不过多介绍。此处引入，只是为了说明create-route-map这个文件的生效入口。在router构造函数内，这行代码是create-route-map文件生效的入口：

1
this.matcher = createMatcher(options.routes || [], this)

这个createMatcher对应的源码文件是：create-matcher.js，这个文件是下一步学习的内容，所以本篇也不深入。它的作用，顾名思义，应该跟路由匹配有关系，在它的代码里，有引用create-route-map的地方：

1
2
3
4
5
6
7
8
9
10
import { createRouteMap } from './create-route-map'

// 省略了很多代码
export function createMatcher (
  routes: Array<RouteConfig>,
  router: VueRouter
): Matcher {
  const { pathList, pathMap, nameMap } = createRouteMap(routes)
  // 省略了很多代码
}

由此可见，create-route-map会返回一个对象，并且包含了pathList pathMap nameMap这三份数据。 这三个数据是什么呢，在分析之前，我们先看下结果：

  • pathList实际上是根据route/index.js文件内routes数组的配置，解析出的所有路径
  • pathMap实际上是路径与route记录的映射表，路径作为键名
  • nameMap实际上是路由名称（route配置上的name属性）与route记录的映射表，name作为键名

createRouteMap

先看第一段代码，重要的后面单独拆分解析，不重要的直接写注释：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
// 这是一个库，做路径解析的库，github搜“path-to-regexp”
import Regexp from 'path-to-regexp'
// cleanPath是个很简单的函数，就是将字符串双斜线替换为单斜线，如//asd 替换为 /asd
import { cleanPath } from './util/path'
// assert warn都是与调试、日志有关
import { assert, warn } from './util/warn'

export function createRouteMap (
  routes: Array<RouteConfig>,
  oldPathList?: Array<string>,
  oldPathMap?: Dictionary<RouteRecord>,
  oldNameMap?: Dictionary<RouteRecord>
): {
  pathList: Array<string>,
  pathMap: Dictionary<RouteRecord>,
  nameMap: Dictionary<RouteRecord>
} {
  // the path list is used to control path matching priority
  const pathList: Array<string> = oldPathList || []
  // $flow-disable-line
  const pathMap: Dictionary<RouteRecord> = oldPathMap || Object.create(null)
  // $flow-disable-line
  const nameMap: Dictionary<RouteRecord> = oldNameMap || Object.create(null)

  routes.forEach(route => {
    addRouteRecord(pathList, pathMap, nameMap, route)
  })

  // ensure wildcard routes are always at the end
  for (let i = 0, l = pathList.length; i < l; i++) {
    if (pathList[i] === '*') {
      pathList.push(pathList.splice(i, 1)[0])
      l--
      i--
    }
  }

  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(0) !== '/')

    if (found.length > 0) {
      const pathNames = found.map(path => `- ${path}`).join('\n')
      warn(false, `Non-nested routes must include a leading slash character. Fix the following routes: \n${pathNames}`)
    }
  }

  return {
    pathList,
    pathMap,
    nameMap
  }
}

Array<RouteConfig> Dictionary<RouteRecord>这些都是参数的类型声明，这是typescript语言特有的写法。createRouteMap函数有四个参数： routes oldPathList oldPathMap oldNameMap，它的返回值是一个包含pathList pathMap nameMap的对象，这些都是从这个函数的声明部分可以读出来的信息。

oldPathList oldPathMap oldNameMap三个参数都是可选的，它们有什么作用呢？一般情况下它们没什么用，但如果在app中需要动态添加route配置，它们就有用了。因为createRouteMap一旦被调用过一次，那么就已经创建好了pathList pathMap nameMap并且返回去了，当app需要动态添加路由时，意味着就要做新的路由配置解析，也就是重新调用createRouteMap，那一个app实例，肯定只需要一份pathList pathMap nameMap，所以再次调用createRouteMap时，再把app里面已经持有的数据，带回来就行了。

1
2
3
routes.forEach(route => {
  addRouteRecord(pathList, pathMap, nameMap, route)
})

这是核心逻辑，遍历routes的配置，然后依次调用addRouteRecord，进行配置解析，把配置记录，解析为route record，并关联存储到pathList pathMap nameMap。后面介绍。

1
2
3
4
5
6
7
8
// ensure wildcard routes are always at the end
for (let i = 0, l = pathList.length; i < l; i++) {
  if (pathList[i] === '*') {
    pathList.push(pathList.splice(i, 1)[0])
    l--
    i--
  }
}

这段注释写清楚了，就是把pathList里面，通配符的记录，移动到数组最后，应该是vue-router路由匹配时的优先级有关。 vue-router的路由匹配，是按照定义的先后顺序来匹配的，谁先匹配到就用谁，所以把通配符的移动到最后，就保证了只有在通配符路由，前面所有的路由都没有匹配到，才会匹配到通配符路由。

1
2
3
4
5
6
7
8
9
10
11
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(0) !== '/')

  if (found.length > 0) {
    const pathNames = found.map(path => `- ${path}`).join('\n')
    warn(false, `Non-nested routes must include a leading slash character. Fix the following routes: \n${pathNames}`)
  }
}

这段是对pathList进行一遍数据检查，要求我们在配置routes的时候，非children内的配置，在配置path的时候，除了*开头的path，其它path都要有/开头。

addRouteRecord

代码是这些：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
function addRouteRecord (
  pathList: Array<string>,
  pathMap: Dictionary<RouteRecord>,
  nameMap: Dictionary<RouteRecord>,
  route: RouteConfig,
  parent?: RouteRecord,
  matchAs?: string
) {

  // 解构出route里面的path和name数据
  const { path, name } = route

  // 下面做了些断言检测
  // 可以没有name，但是不能没有path
  // 而且component不能是字符串
  if (process.env.NODE_ENV !== 'production') {
    assert(path != null, `"path" is required in a route configuration.`)
    assert(
      typeof route.component !== 'string',
      `route config "component" for path: ${String(
        path || name
      )} cannot be a ` + `string id. Use an actual component instead.`
    )
  }

  const pathToRegexpOptions: PathToRegexpOptions =
    route.pathToRegexpOptions || {}
  const normalizedPath = normalizePath(path, parent, pathToRegexpOptions.strict)

  if (typeof route.caseSensitive === 'boolean') {
    pathToRegexpOptions.sensitive = route.caseSensitive
  }

  const record: RouteRecord = {
    path: normalizedPath,
    regex: compileRouteRegex(normalizedPath, pathToRegexpOptions),
    components: route.components || { default: route.component },
    instances: {},
    name,
    parent,
    matchAs,
    redirect: route.redirect,
    beforeEnter: route.beforeEnter,
    meta: route.meta || {},
    props:
      route.props == null
        ? {}
        : route.components
          ? route.props
          : { default: route.props }
  }

  if (route.children) {
    // Warn if route is named, does not redirect and has a default child route.
    // If users navigate to this route by name, the default child will
    // not be rendered (GH Issue #629)
    if (process.env.NODE_ENV !== 'production') {
      if (
        route.name &&
        !route.redirect &&
        route.children.some(child => /^\/?$/.test(child.path))
      ) {
        warn(
          false,
          `Named Route '${route.name}' has a default child route. ` +
            `When navigating to this named route (:to="{name: '${
              route.name
            }'"), ` +
            `the default child route will not be rendered. Remove the name from ` +
            `this route and use the name of the default child route for named ` +
            `links instead.`
        )
      }
    }
    route.children.forEach(child => {
      const childMatchAs = matchAs
        ? cleanPath(`${matchAs}/${child.path}`)
        : undefined
      addRouteRecord(pathList, pathMap, nameMap, child, record, childMatchAs)
    })
  }

  if (!pathMap[record.path]) {
    pathList.push(record.path)
    pathMap[record.path] = record
  }

  if (route.alias !== undefined) {
    const aliases = Array.isArray(route.alias) ? route.alias : [route.alias]
    for (let i = 0; i < aliases.length; ++i) {
      const alias = aliases[i]
      if (process.env.NODE_ENV !== 'production' && alias === path) {
        warn(
          false,
          `Found an alias with the same value as the path: "${path}". You have to remove that alias. It will be ignored in development.`
        )
        // skip in dev to make it work
        continue
      }

      const aliasRoute = {
        path: alias,
        children: route.children
      }
      addRouteRecord(
        pathList,
        pathMap,
        nameMap,
        aliasRoute,
        parent,
        record.path || '/' // matchAs
      )
    }
  }

  if (name) {
    if (!nameMap[name]) {
      nameMap[name] = record
    } else if (process.env.NODE_ENV !== 'production' && !matchAs) {
      warn(
        false,
        `Duplicate named routes definition: ` +
          `{ name: "${name}", path: "${record.path}" }`
      )
    }
  }
}

先来看它的参数：

1
2
3
4
5
6
pathList: Array<string>,
pathMap: Dictionary<RouteRecord>,
nameMap: Dictionary<RouteRecord>,
route: RouteConfig,
parent?: RouteRecord,
matchAs?: string

前三个不用解释了，第四个route表示当前要处理的那条配置对象，parent则代表的是一个route record，addRouteRecord就是创建route record的函数，如果某个route record被创建后，发现它的route配置里面有children，则会对children也进行addRouteRecord的处理，而它自身会作为一个parent参数传入到children的addRouteRecord处理；matchAs跟路由别名有关，后面用实例来解析。

下面这段代码是创建route record的过程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
const pathToRegexpOptions: PathToRegexpOptions =
    route.pathToRegexpOptions || {}
  const normalizedPath = normalizePath(path, parent, pathToRegexpOptions.strict)

  if (typeof route.caseSensitive === 'boolean') {
    pathToRegexpOptions.sensitive = route.caseSensitive
  }

  const record: RouteRecord = {
    path: normalizedPath,
    regex: compileRouteRegex(normalizedPath, pathToRegexpOptions),
    components: route.components || { default: route.component },
    instances: {},
    name,
    parent,
    matchAs,
    redirect: route.redirect,
    beforeEnter: route.beforeEnter,
    meta: route.meta || {},
    props:
      route.props == null
        ? {}
        : route.components
          ? route.props
          : { default: route.props }
  }

从这里可以看到在routes配置中，还可以添加pathToRegexpOptions caseSensitive这些option，这些options是干什么的呢？它与path-to-regexp有关，在vue-router的官方文档有介绍过：

pathToRegexpOptions就是给path-to-regexp这个库用的。这个库怎么用呢，可以去看github，也可以去看我写的另外一篇博客：

path-to-regexp使用小结

这里有一行代码，对path进行了一些处理：

1
const normalizedPath = normalizePath(path, parent, pathToRegexpOptions.strict)

它调用了这个函数：

1
2
3
4
5
6
7
8
9
10
function normalizePath (
  path: string,
  parent?: RouteRecord,
  strict?: boolean
): string {
  if (!strict) path = path.replace(/\/$/, '')
  if (path[0] === '/') return path
  if (parent == null) return path
  return cleanPath(`${parent.path}/${path}`)
}

其实也比较简单，在js中normalize这个词的含义都是正规化，比如ES6开始有了对于字符串的正规化处理，所以normalizePath也就是一个对path进行正规化处理的作用。注意最后那个${parent.path}/${path}，假如你有一个这个route：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  name: 'detail',
  path: '/detail/:id',
  component: Detail,
  alias: ['/query/:id'],
  children: [
    {
      name: 'detail_more',
      path: 'more',
      components: {
        bar: () => import(/* webpackChunkName: "group-bar" */ '../pages/Bar.vue')
      }
    }
  ]
}

在children中，path不需要把parent的path加上，因为在normalizePath里通过${parent.path}/${path}，为你处理好了。

接下来看RouteRecord的结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
const record: RouteRecord = {
    path: normalizedPath, 
    regex: compileRouteRegex(normalizedPath, pathToRegexpOptions),
    components: route.components || { default: route.component },
    instances: {},
    name,
    parent,
    matchAs,
    redirect: route.redirect,
    beforeEnter: route.beforeEnter,
    meta: route.meta || {},
    props:
      route.props == null
        ? {}
        : route.components
          ? route.props
          : { default: route.props }
  }

先看这个regex，它是调用compileRouteRegex返回的一个正则表达式，这个进行路由匹配时，肯定是要用到的，compileRouteRegex内部其实就是使用path-to-regexp的过程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
function compileRouteRegex (
  path: string,
  pathToRegexpOptions: PathToRegexpOptions
): RouteRegExp {
  // Regexp就是path-to-regexp 顶部有import
  const regex = Regexp(path, [], pathToRegexpOptions)
  if (process.env.NODE_ENV !== 'production') {
    const keys: any = Object.create(null)
    regex.keys.forEach(key => {
      warn(
        !keys[key.name],
        `Duplicate param keys in route with path: "${path}"`
      )
      keys[key.name] = true
    })
  }
  return regex
}

它加了一个命名参数不允许重复的处理，比如这样的path:/some/:name/:name，是会触发警告的。其它的属性作用如下：

  • path是当前路由正规化处理之后的路径
  • component是当前路由配置的组件定义，从route.components || { default: route.component }可以看到，路由视图默认的名字之所以是default的原因
  • instances是最终要用来存放当前渲染的节点实例的，理解完上一篇博客，对这个instances的数据就不会陌生了
  • name是路由配置的名字
  • parent是父级的route record引用，只有当前是children中的路由才会有值
  • matchAs是传递进来的参数，只有别名路由才会有
  • redirect beforeEnter meta都是从route上直接读取的配置数据
  • props本质上也是要从route上读取的配置数据，但是做了些额外的处理，也比较好懂

后面还有些处理：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
if (!pathMap[record.path]) {
  pathList.push(record.path)
  pathMap[record.path] = record
}

if (name) {
  if (!nameMap[name]) {
    nameMap[name] = record
  } else if (process.env.NODE_ENV !== 'production' && !matchAs) {
    warn(
      false,
      `Duplicate named routes definition: ` +
        `{ name: "${name}", path: "${record.path}" }`
    )
  }
}

这两段实际上就是完成了pathList nameMap pathMap这三个数据的关联和填充。在nameMap那里，额外做了一些开发提示，最终的作用就是为了检查是否有name相同的路由配置，如果有，就给出警告提醒开发者。

以上的一些代码，在一些基础路由配置处理的时候，就已经够了，比如这些：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
[
    {
      path: '/',
      component: Index
    },
    {
      path: '/index',
      redirect: '/'
    },
    {
      name: 'list',
      path: '/list',
      component: List
    }
]

只要路由配置里面，没有别名和children，addRouteRecord的其它代码就不会执行。

下面就来看有别名和有children的代码处理。先看别名的：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
if (route.alias !== undefined) {
  const aliases = Array.isArray(route.alias) ? route.alias : [route.alias]
  for (let i = 0; i < aliases.length; ++i) {
    const alias = aliases[i]
    if (process.env.NODE_ENV !== 'production' && alias === path) {
      warn(
        false,
        `Found an alias with the same value as the path: "${path}". You have to remove that alias. It will be ignored in development.`
      )
      // skip in dev to make it work
      continue
    }

    const aliasRoute = {
      path: alias,
      children: route.children
    }
    addRouteRecord(
      pathList,
      pathMap,
      nameMap,
      aliasRoute,
      parent,
      record.path || '/' // matchAs
    )
  }
}

如果route.alias不为undefined，以上代码就会执行。从代码看到，原来route.alias是可以配置数组的，并且别名不能与path配置相同，而且别名跟redirect不一样，别名必须跟path一样，是路径字符串，不能写配置为alis: {name: 'some'}这种。

最关键就是这段处理：

1
2
3
4
5
6
7
8
9
10
11
12
const aliasRoute = {
  path: alias,
  children: route.children
}
addRouteRecord(
  pathList,
  pathMap,
  nameMap,
  aliasRoute,
  parent,
  record.path || '/' // matchAs
)

当路由配置了别名，就会把所有的别名遍历一遍，挨个调用addRouteRecord，也就是把每个别名，都创建额外一条的route record。只不过这个创建过程，有两个特殊的地方：

  1. aliasRoute是这里单独定义的，不是routes里面那种配置，只保留了原有的children配置，以便children也能全部支持别名
  2. record.path || '/'也就是当前route record的路径，被设置为了别名的route record的match as，猜想一下，在后续路由匹配的时候，如果匹配到了某个路由，发现它有matchAs，接下来只要拿matchAs，重新做一次路由匹配，就能找到原始的路由了。

正因为以上代码的作用，如果你有这个routes：

1
2
3
4
5
6
7
[
    {
      path: '/',
      component: Index,
      alias: '/index'
    }
  ]

则会生成两条route record:

如果路由配置chidlren，则下面的代码会运行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
if (route.children) {
    // Warn if route is named, does not redirect and has a default child route.
    // If users navigate to this route by name, the default child will
    // not be rendered (GH Issue #629)
    if (process.env.NODE_ENV !== 'production') {
      if (
        route.name &&
        !route.redirect &&
        route.children.some(child => /^\/?$/.test(child.path))
      ) {
        warn(
          false,
          `Named Route '${route.name}' has a default child route. ` +
            `When navigating to this named route (:to="{name: '${
              route.name
            }'"), ` +
            `the default child route will not be rendered. Remove the name from ` +
            `this route and use the name of the default child route for named ` +
            `links instead.`
        )
      }
    }
    route.children.forEach(child => {
      const childMatchAs = matchAs
        ? cleanPath(`${matchAs}/${child.path}`)
        : undefined
      addRouteRecord(pathList, pathMap, nameMap, child, record, childMatchAs)
    })
  }

中间那段是为了应对下面这种配置场景：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  name: 'detail',
  path: '/detail/:id',
  component: Detail,
  children: [
    {
      name: 'detail_more',
      path: '',
      components: {
        bar: () => import(/* webpackChunkName: "group-bar" */ '../pages/Bar.vue')
      }
    }
  ]
}

detail_more是一个path为空的子路由，可被看成是detail的默认路由，当在app中使用{name: 'detail'}的方式访问时，这个情形下，尽管detail_more是detail的默认路由，它对应的component也不会被渲染，所以vue-router给出了开发期间的警告提醒。可以改用{name: 'detail_more'}的方式访问。

接下来这段:

1
2
3
4
5
6
route.children.forEach(child => {
  const childMatchAs = matchAs
    ? cleanPath(`${matchAs}/${child.path}`)
    : undefined
  addRouteRecord(pathList, pathMap, nameMap, child, record, childMatchAs)
})

主要是那个childMatchAs的处理，当matchAs为空的时候，上面的代码是很好理解的，就是遍历children，挨个创建route record的过程。假如有matchAs，说明当前是正在进行别名的route record的创建过程，而且这个别名路由，还是有一个有children的别名路由。 假如这个route是这样的：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  name: 'detail',
  path: '/detail/:id',
  component: Detail,
  alias: ['/query/:id'],
  children: [
    {
      name: 'detail_more',
      path: 'more',
      components: {
        bar: () => import(/* webpackChunkName: "group-bar" */ '../pages/Bar.vue')
      }
    }
  ]
}

最终一共会添加4条路由，非别名的路由两条，其中1条是另外1条的子路由；别名的路由也是2条，其中1条是另外1条的子路由:

childMatchAs的作用，就是让children里的路由，也有了别名，比如/detail/:id/more会有一条/query/:id/more。

（完）