refactor(core): 引入内部模块与安装覆盖机制，重构安装流程核心实现

Author: l246804

src/create-router.ts

@@ -1,8 +1,7 @@
 import type { RouterOptions as _RouterOptions, Router } from 'vue-router'
 import type { RouterPlugin } from './plugin'
 import { createRouter as _createRouter } from 'vue-router'
-import { RUN_WITH_APP_HANDLERS_KEY } from './meta-keys'
-import { prepareInstall } from './prepare-install'
+import { overrideRouterInstall } from './override-router-install'
 import { setupPlugin } from './setup-plugin'
 
 export interface RouterOptions extends _RouterOptions {
@@ -33,17 +32,7 @@ export function createRouter(options: RouterOptions): Router {
   const router = _createRouter(options)
 
   // 重写 install 方法
-  const { install } = router
-  router.install = (...args) => {
-    const [app] = args
-    prepareInstall({ app, router })
-    install.apply(router, args)
-
-    // 运行缓存的 runWithApp 函数
-    const runWithAppHandlers = (router[RUN_WITH_APP_HANDLERS_KEY] ??= [])
-    runWithAppHandlers.forEach(handler => handler(app))
-    runWithAppHandlers.length = 0
-  }
+  overrideRouterInstall(router)
 
   // 安装插件
   const { plugins = [] } = options

src/index.ts

@@ -1,4 +1,5 @@
-export * from './as-vue-plugin'
 export * from './create-router'
-export * from './create-vue-router-plugin'
+export * from './deprecated/as-vue-plugin'
+export * from './deprecated/create-vue-router-plugin'
 export * from './plugin'
+export * from './with-install'

src/internals.ts

@@ -0,0 +1,19 @@
+import type { Router } from 'vue-router'
+import type { RouterPluginSystemInternals } from './types/vue-router'
+import { effectScope } from 'vue'
+
+export const INTERNALS_KEY = '__VUE_ROUTER_PLUGIN_SYSTEM_INTERNALS__' as const
+
+export function getInternals(router: Router): RouterPluginSystemInternals {
+  if (!router[INTERNALS_KEY]) {
+    router[INTERNALS_KEY] = {
+      isInstallOverridden: false,
+      isPrepared: false,
+      app: undefined,
+      effectScope: effectScope(true),
+      uninstallHandlers: [],
+      runWithAppHandlers: [],
+    }
+  }
+  return router[INTERNALS_KEY]
+}

src/meta-keys.ts

@@ -0,0 +1,33 @@
+import type { Router } from 'vue-router'
+import { getInternals } from './internals'
+import { prepareInstall } from './prepare-install'
+
+/**
+ * 重写路由器的 install 方法
+ *
+ * @param router 路由器实例
+ */
+export function overrideRouterInstall(router: Router): void {
+  const internals = getInternals(router)
+  if (internals.isInstallOverridden) {
+    return
+  }
+
+  // 避免重复重写
+  internals.isInstallOverridden = true
+
+  // 重写 install 方法
+  const { install } = router
+  router.install = (...args) => {
+    const [app] = args
+
+    // 准备安装
+    prepareInstall({ app, router })
+    // 执行原始 install 方法
+    install.apply(router, args)
+
+    // 运行缓存的 runWithApp 函数
+    internals.runWithAppHandlers.forEach(handler => handler(app))
+    internals.runWithAppHandlers.length = 0
+  }
+}

src/override-router-install.ts

@@ -1,12 +1,6 @@
 import type { App } from 'vue'
 import type { Router } from 'vue-router'
-import {
-  APP_KEY,
-  EFFECT_SCOPE_KEY,
-  PREPARED_FLAG_KEY,
-  RUN_WITH_APP_HANDLERS_KEY,
-  UNINSTALL_HANDLERS_KEY,
-} from './meta-keys'
+import { getInternals } from './internals'
 
 /**
  * 在正式安装到 vue app 前运行此函数，以准备安装
@@ -18,28 +12,24 @@ export function prepareInstall({
   app: App
   router: Router
 }): void {
-  if (router[PREPARED_FLAG_KEY]) {
+  const internals = getInternals(router)
+  if (internals.isPrepared) {
     return
   }
 
   // 避免重复执行后续操作
-  router[PREPARED_FLAG_KEY] = true
+  internals.isPrepared = true
 
   // 用于 setupPlugin 内访问 vue app
-  router[APP_KEY] = app
+  internals.app = app
 
   // 注册卸载函数
-  // TODO: use https://github.com/vuejs/core/pull/8801 if merged
   const { unmount } = app
   app.unmount = () => {
-    router[EFFECT_SCOPE_KEY]?.stop()
-    router[UNINSTALL_HANDLERS_KEY]?.forEach(handler => handler())
-
-    delete router[PREPARED_FLAG_KEY]
-    delete router[APP_KEY]
-    delete router[EFFECT_SCOPE_KEY]
-    delete router[UNINSTALL_HANDLERS_KEY]
-    delete router[RUN_WITH_APP_HANDLERS_KEY]
+    internals.effectScope.stop()
+    internals.uninstallHandlers.forEach(handler => handler())
+    internals.uninstallHandlers.length = 0
+    internals.runWithAppHandlers.length = 0
 
     return unmount.call(app)
   }

src/prepare-install.ts

@@ -1,12 +1,6 @@
 import type { Router } from 'vue-router'
 import type { RouterPlugin } from './plugin'
-import { effectScope } from 'vue'
-import {
-  APP_KEY,
-  EFFECT_SCOPE_KEY,
-  RUN_WITH_APP_HANDLERS_KEY,
-  UNINSTALL_HANDLERS_KEY,
-} from './meta-keys'
+import { getInternals } from './internals'
 
 /**
  * 安装单一插件
@@ -18,28 +12,26 @@ export function setupPlugin({
   router: Router
   plugin: RouterPlugin
 }): void {
-  const scope = (router[EFFECT_SCOPE_KEY] ??= effectScope(true))
+  const internals = getInternals(router)
   // 在 scope 中运行插件
-  scope.run(() => {
+  internals.effectScope.run(() => {
     plugin({
       router,
       onUninstall(handler) {
-        const handlers = (router[UNINSTALL_HANDLERS_KEY] ??= [])
-        handlers.push(handler)
+        internals.uninstallHandlers.push(handler)
       },
       runWithApp(handler) {
         // 在 scope 中运行 handler
         const rawHandler = handler
         handler = (...args) => {
-          return scope.run(() => rawHandler(...args))
+          return internals.effectScope.run(() => rawHandler(...args))
         }
 
-        if (router[APP_KEY]) {
-          handler(router[APP_KEY])
+        if (internals.app) {
+          handler(internals.app)
         }
         else {
-          const handlers = (router[RUN_WITH_APP_HANDLERS_KEY] ??= [])
-          handlers.push(handler)
+          internals.runWithAppHandlers.push(handler)
         }
       },
     })

src/setup-plugin.ts

@@ -0,0 +1,25 @@
+import type { App, EffectScope } from 'vue'
+import type { INTERNALS_KEY } from '../internals'
+import type {
+  RouterPluginRunWithAppHandler,
+  RouterPluginUninstallHandler,
+} from '../plugin'
+
+export interface RouterPluginSystemInternals {
+  isInstallOverridden: boolean
+  isPrepared: boolean
+  app: App | undefined
+  effectScope: EffectScope
+  uninstallHandlers: RouterPluginUninstallHandler[]
+  runWithAppHandlers: RouterPluginRunWithAppHandler[]
+}
+
+declare module 'vue-router' {
+  export interface Router {
+    /**
+     * Internal data for vue-router-plugin-system.
+     * @internal
+     */
+    [INTERNALS_KEY]?: RouterPluginSystemInternals
+  }
+}

src/types/vue-router.d.ts

@@ -0,0 +1,60 @@
+import type { App } from 'vue'
+import type { Router } from 'vue-router'
+import type { RouterPlugin } from './plugin'
+import { overrideRouterInstall } from './override-router-install'
+import { prepareInstall } from './prepare-install'
+import { setupPlugin } from './setup-plugin'
+
+export interface RouterPluginInstall {
+  /**
+   * Install the plugin.
+   * @param instance App or Router instance
+   */
+  install: (instance: App | Router) => void
+}
+
+/**
+ * Add an `install` method to the plugin to adapt it to Vue's plugin registration mechanism,
+ * or to manually install the plugin with an router instance.
+ *
+ * @example
+ * ```ts
+ * const SomePlugin = withInstall((ctx) => {
+ *   // plugin implementation
+ * })
+ *
+ * // install with router
+ * SomePlugin.install(router)
+ *
+ * // install with app
+ * // must be installed after the router
+ * app.use(router).use(SomePlugin)
+ * ```
+ */
+export function withInstall(
+  plugin: RouterPlugin,
+): RouterPlugin & RouterPluginInstall {
+  return Object.assign(plugin, {
+    install(instance: App | Router) {
+      if (isRouter(instance)) {
+        overrideRouterInstall(instance)
+        setupPlugin({ router: instance, plugin })
+      }
+      else {
+        const router = instance.config.globalProperties.$router
+        if (!router) {
+          throw new Error(
+            '[vue-router-plugin-system] Please install vue-router first.',
+          )
+        }
+
+        prepareInstall({ app: instance, router })
+        setupPlugin({ router, plugin })
+      }
+    },
+  })
+}
+
+function isRouter(instance: any): instance is Router {
+  return !!instance.install && !!instance.options && !!instance.currentRoute
+}