vue router 4 源码篇：路由诞生——createRouter原理探索

.
├── .github
├── .gitignore
├── .npmrc               // 项目的配置文件
├── .prettierignore
├── .prettierrc
├── LICENSE
├── README.md
├── netlify.toml
├── package.json
├── packages             // 项目分包
│   ├── docs             // vue router API文档
│   ├── playground       // 本地调试项目
│   └── router           // vue router源码
├── pnpm-lock.yaml       // 依赖版本控制
├── pnpm-workspace.yaml  // 工作空间根目录
└── scripts              // 工程脚本

import Vue from 'vue'
import { createRouter, createWebHistory } from 'vue-router'

// 创建和挂载
const routes = [
  { path: '/', component: { template: '<div>Home</div>' } },
  { path: '/about', component: { template: '<div>About</div>' } },
]

const router = createRouter({
  history: createWebHistory(),
  routes,
})

const app = Vue.createApp({})

app.use(router)

app.mount('#app')


// 组件内使用
import { useRouter } from 'vue-router';

const router = useRouter();
console.log(router.currentRoute)
router.back()
// ...

createRouter(options: RouterOptions): Router { /**/ }

export interface Router {
  // 当前路由
  readonly currentRoute: Ref<RouteLocationNormalizedLoaded>
  // 路由配置项
  readonly options: RouterOptions
  // 是否监听
  listening: boolean
  // 添加路由
  addRoute(parentName: RouteRecordName, route: RouteRecordRaw): () => void
  addRoute(route: RouteRecordRaw): () => void
  // 删除路由
  removeRoute(name: RouteRecordName): void
  // 是否存在路由name=xxx
  hasRoute(name: RouteRecordName): boolean
  // 获取所有路由matcher
  getRoutes(): RouteRecord[]
  // 返回路由地址的标准化版本
  resolve(
    to: RouteLocationRaw,
    currentLocation?: RouteLocationNormalizedLoaded
  ): RouteLocation &amp; { href: string }
  // 路由push跳转
  push(to: RouteLocationRaw): Promise<NavigationFailure | void | undefined>
  // 路由replace跳转
  replace(to: RouteLocationRaw): Promise<NavigationFailure | void | undefined>
  // 路由回退
  back(): ReturnType<Router['go']>
  // 路由前进
  forward(): ReturnType<Router['go']>
  // 路由跳页
  go(delta: number): void
  // 全局导航守卫
  beforeEach(guard: NavigationGuardWithThis<undefined>): () => void
  beforeResolve(guard: NavigationGuardWithThis<undefined>): () => void
  afterEach(guard: NavigationHookAfter): () => void
  // 路由错误处理
  onError(handler: _ErrorHandler): () => void
  // 路由器是否完成初始化导航
  isReady(): Promise<void>
  // vue2.x版本路由安装方法
  install(app: App): void
}

import {
  createRouterMatcher,
  createWebHistory,
} from 'vue-router'

export const routerHistory = createWebHistory()
const options = { 
    // your options... 
}
console.log('matchers:', createRouterMatcher(options.routes, options).getRoutes())

const beforeGuards = useCallbacks<NavigationGuardWithThis<undefined>>()
const beforeResolveGuards = useCallbacks<NavigationGuardWithThis<undefined>>()
const afterGuards = useCallbacks<NavigationHookAfter>()

// ...

const router: Router = {
  // ...
  beforeEach: beforeGuards.add,
  beforeResolve: beforeResolveGuards.add,
  afterEach: afterGuards.add,
}

/**
 * Create a list of callbacks that can be reset. Used to create before and after navigation guards list
 */
export function useCallbacks<T>() {
  let handlers: T[] = []

  function add(handler: T): () => void {
    handlers.push(handler)
    return () => {
      const i = handlers.indexOf(handler)
      if (i > -1) handlers.splice(i, 1)
    }
  }

  function reset() {
    handlers = []
  }

  return {
    add,
    list: () => handlers,
    reset,
  }
}

function addRoute(
  parentOrRoute: RouteRecordName | RouteRecordRaw,
  route?: RouteRecordRaw
) {
  let parent: Parameters<typeof matcher['addRoute']>[1] | undefined
  let record: RouteRecordRaw
  if (isRouteName(parentOrRoute)) {
    parent = matcher.getRecordMatcher(parentOrRoute)
    record = route!
  } else {
    record = parentOrRoute
  }

  return matcher.addRoute(record, parent)
}

function removeRoute(name: RouteRecordName) {
  const recordMatcher = matcher.getRecordMatcher(name)
  if (recordMatcher) {
    matcher.removeRoute(recordMatcher)
  } else if (__DEV__) {
    warn(`Cannot remove non-existent route "${String(name)}"`)
  }
}

function getRoutes() {
  return matcher.getRoutes().map(routeMatcher => routeMatcher.record)
}

function hasRoute(name: RouteRecordName): boolean {
  return !!matcher.getRecordMatcher(name)
}

// 浏览器带参数跳转有三种写法

router.push('/user?name=johnny')
router.push({path: '/user', query: {name: 'johnny'}})
router.push({name: 'user', query: {name: 'johnny'}})

// function pushWithRedirect

const targetLocation: RouteLocation = (pendingLocation = resolve(to))
const from = currentRoute.value
const data: HistoryState | undefined = (to as RouteLocationOptions).state
const force: boolean | undefined = (to as RouteLocationOptions).force
// to could be a string where `replace` is a function
const replace = (to as RouteLocationOptions).replace === true

// 寻找重定向的路由
const shouldRedirect = handleRedirectRecord(targetLocation)

if (shouldRedirect)
  return pushWithRedirect(
    assign(locationAsObject(shouldRedirect), {
      state: data,
      force,
      replace,
    }),
    // keep original redirectedFrom if it exists
    redirectedFrom || targetLocation
  )

// if it was a redirect we already called `pushWithRedirect` above
const toLocation = targetLocation as RouteLocationNormalized

toLocation.redirectedFrom = redirectedFrom
let failure: NavigationFailure | void | undefined

if (!force && isSameRouteLocation(stringifyQuery, from, targetLocation)) {
  failure = createRouterError<NavigationFailure>(
    ErrorTypes.NAVIGATION_DUPLICATED,
    { to: toLocation, from }
  )
  // trigger scroll to allow scrolling to the same anchor
  handleScroll(
    from,
    from,
    // this is a push, the only way for it to be triggered from a
    // history.listen is with a redirect, which makes it become a push
    true,
    // This cannot be the first navigation because the initial location
    // cannot be manually navigated to
    false
  )
}

return (failure ? Promise.resolve(failure) : navigate(toLocation, from))

function navigate(
  to: RouteLocationNormalized,
  from: RouteLocationNormalizedLoaded
): Promise<any> {
  let guards: Lazy<any>[]

  /**
   * extractChangingRecords根据to（跳转到的路由）和from（即将离开的路由）到matcher里匹配，把结果存到3个数组中
   * leavingRecords：即将离开的路由
   * updatingRecords：要更新的路由，一般只同路由更新
   * enteringRecords：要进入的路由，一般用于不同路由互跳
   */
  const [leavingRecords, updatingRecords, enteringRecords] =
    extractChangingRecords(to, from)

  /**
   * extractComponentsGuards用于提取路由的钩子（为beforeRouteEnter、beforeRouteUpdate、beforeRouteLeave之一，通过第二参数决定）
   * 因为路由跳转前要把原路由的beforeRouteLeave钩子要执行一遍，因此要提取leavingRecords里所有路由的钩子
   * 有由于vue组件销毁顺序是从子到父，因此要reverse反转路由数组保证子路由钩子的高优先级
   */
  guards = extractComponentsGuards(
    leavingRecords.reverse(),
    'beforeRouteLeave',
    to,
    from
  )

  /**
   * 将组件内用onBeforeRouteLeave方法注册的导航守卫添加到guards里面
   */
  for (const record of leavingRecords) {
    record.leaveGuards.forEach(guard => {
      guards.push(guardToPromiseFn(guard, to, from))
    })
  }

  // 如果过程有任何路由触发canceledNavigationCheck，则跳过后续所有的导航守卫执行
  const canceledNavigationCheck = checkCanceledNavigationAndReject.bind(
    null,
    to,
    from
  )

  guards.push(canceledNavigationCheck)

  /**
   * 执行所有beforeRouteLeave钩子函数，并在后续按vue组件生命周期执行新路由组件挂载完成前的所有导航守卫
   */
  return (
    runGuardQueue(guards)
      .then(() => {
        // 执行全局 beforeEach 钩子
        guards = []
        for (const guard of beforeGuards.list()) {
          guards.push(guardToPromiseFn(guard, to, from))
        }
        guards.push(canceledNavigationCheck)

        return runGuardQueue(guards)
      })
      .then(() => {
        // 执行组件内 beforeRouteUpdate 钩子
        guards = extractComponentsGuards(
          updatingRecords,
          'beforeRouteUpdate',
          to,
          from
        )

        for (const record of updatingRecords) {
          record.updateGuards.forEach(guard => {
            guards.push(guardToPromiseFn(guard, to, from))
          })
        }
        guards.push(canceledNavigationCheck)

        // run the queue of per route beforeEnter guards
        return runGuardQueue(guards)
      })
      .then(() => {
        // 执行全局 beforeEnter 钩子
        guards = []
        for (const record of to.matched) {
          // do not trigger beforeEnter on reused views
          if (record.beforeEnter &amp;&amp; !from.matched.includes(record)) {
            if (isArray(record.beforeEnter)) {
              for (const beforeEnter of record.beforeEnter)
                guards.push(guardToPromiseFn(beforeEnter, to, from))
            } else {
              guards.push(guardToPromiseFn(record.beforeEnter, to, from))
            }
          }
        }
        guards.push(canceledNavigationCheck)

        // run the queue of per route beforeEnter guards
        return runGuardQueue(guards)
      })
      .then(() => {
        // NOTE: at this point to.matched is normalized and does not contain any () => Promise<Component>

        // 清除已经存在的enterCallbacks, 因为这些已经在 extractComponentsGuards 里面添加
        to.matched.forEach(record => (record.enterCallbacks = {}))

        // check in-component beforeRouteEnter
        guards = extractComponentsGuards(
          enteringRecords,
          'beforeRouteEnter',
          to,
          from
        )
        guards.push(canceledNavigationCheck)

        // run the queue of per route beforeEnter guards
        return runGuardQueue(guards)
      })
      .then(() => {
        // 执行全局 beforeResolve 钩子
        guards = []
        for (const guard of beforeResolveGuards.list()) {
          guards.push(guardToPromiseFn(guard, to, from))
        }
        guards.push(canceledNavigationCheck)

        return runGuardQueue(guards)
      })
      // 捕获其他错误
      .catch(err =>
        isNavigationFailure(err, ErrorTypes.NAVIGATION_CANCELLED)
          ? err
          : Promise.reject(err)
      )
  )
}

return (failure ? Promise.resolve(failure) : navigate(toLocation, from))
  .catch((error: NavigationFailure | NavigationRedirectError) =>
    isNavigationFailure(error)
      ? // navigation redirects still mark the router as ready，这部分会进入下面的.then()逻辑
        isNavigationFailure(error, ErrorTypes.NAVIGATION_GUARD_REDIRECT)
        ? error
        : markAsReady(error) // also returns the error
      : // 未知错误时直接抛出异常
        triggerError(error, toLocation, from)
  )
  .then((failure: NavigationFailure | NavigationRedirectError | void) => {
    if (failure) {
      // 重定向错误，进入10次重试
      if (
        isNavigationFailure(failure, ErrorTypes.NAVIGATION_GUARD_REDIRECT)
      ) {
        // ...
      }
    } else {
      /**
       * 如果在navigate过程中没有抛出错误信息，则确认本次跳转
       * 这时会调用finalizeNavigation函数，它会处理浏览器url、和页面滚动行为，
       * 完成后调用markAsReady方法，将路由标记为准备状态，执行isReady钩子里面的逻辑
       */
      failure = finalizeNavigation(
        toLocation as RouteLocationNormalizedLoaded,
        from,
        true,
        replace,
        data
      )
    }
    // 最后触发全局afterEach钩子，至此push操作全部完成
    triggerAfterEach(
      toLocation as RouteLocationNormalizedLoaded,
      from,
      failure
    )
    return failure
  })

function replace(to: RouteLocationRaw) {
  return push(assign(locationAsObject(to), { replace: true }))
}

  // on the initial navigation, we want to reuse the scroll position from
  // history state if it exists
  if (replace || isFirstNavigation)
    routerHistory.replace(
      toLocation.fullPath,
      assign(
        {
          scroll: isFirstNavigation && state && state.scroll,
        },
        data
      )
    )
  else routerHistory.push(toLocation.fullPath, data)

beforeEach: beforeGuards.add,
beforeResolve: beforeResolveGuards.add,
afterEach: afterGuards.add,