基于自定义注解和代码生成实现路由框架

场景描述

在应用开发中无论是出于工程组织效率还是开发体验的考虑，开发者都需要对项目进行模块间解耦，此时需要构建一套用于模块间组件跳转、数据通信的路由框架。

业界常见的实现方式是在编译期生成路由表。

1. 实现原理及流程

• 在编译期通过扫描并解析ets文件中的自定义注解来生成路由表和组件注册类
• Har中的rawfile文件在Hap编译时会打包在Hap中，通过这一机制来实现路由表的合并
• 自定义组件通过wrapBuilder封装来实现动态获取
• 通过NavDestination的Builder机制来获取wrapBuilder封装后的自定义组件

2. 使用ArkTS自定义装饰器来代替注解的定义

由于TS语言特性，当前只能使用自定义装饰器

使用@AppRouter装饰器来定义路由信息

// 定义空的装饰器 
export function AppRouter(param:AppRouterParam) { 
  return Object; 
} 
 
export interface AppRouterParam{ 
  uri:string; 
}

自定义组件增加路由定义

@AppRouter({ uri: "app://login" }) 
@Component 
export struct LoginView { 
  build(){ 
    //... 
  } 
}

3. 实现动态路由模块

定义路由表（该文件为自动生成的路由表）

{ 
  "routerMap": [ 
    { 
      "name": "app://login",   /* uri定义  */ 
      "pageModule": "loginModule",  /* 模块名  */ 
      "pageSourceFile": "src/main/ets/generated/RouterBuilder.ets",  /* Builder文件  */ 
      "registerFunction": "LoginViewRegister"  /* 组件注册函数  */ 
    } 
  ] 
}

应用启动时，在EntryAbility.onCreate中加载路由表

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 
  DynamicRouter.init({ 
    libPrefix: "@app", mapPath: "routerMap" 
  }, this.context); 
}
export class DynamicRouter { 
  // 路由初始化配置 
  static config: RouterConfig; 
  // 路由表 
  static routerMap: Map<string, RouterInfo> = new Map(); 
  // 管理需要动态导入的模块，key是模块名，value是WrappedBuilder对象，动态调用创建页面的接口 
  static builderMap: Map<string, WrappedBuilder<Object[]>> = new Map(); 
  // 路由栈 
  static navPathStack: NavPathStack = new NavPathStack(); 
  // 通过数组实现自定义栈的管理 
  static routerStack: Array<RouterInfo> = new Array(); 
  static referrer: string[] = []; 
 
  public static init(config: RouterConfig, context: Context) { 
    DynamicRouter.config = config; 
    DynamicRouter.routerStack.push(HOME_PAGE) 
    RouterLoader.load(config.mapPath, DynamicRouter.routerMap, context) 
  } 
  //... 
}

路由表存放在src/main/resources/rawfile目录中，通过ResourceManager进行读取

export namespace RouterLoader { 
 
  export function load(dir: string, routerMap: Map<string, RouterInfo>, context: Context) { 
    const rm: resourceManager.ResourceManager = context.resourceManager; 
    try { 
      rm.getRawFileList(dir) 
        .then((value: Array<string>) => { 
          let decoder: util.TextDecoder = util.TextDecoder.create('utf-8', { 
            fatal: false, ignoreBOM: true 
          }) 
          value.forEach(fileName => { 
            let fileBytes: Uint8Array = rm.getRawFileContentSync(`${dir}/${fileName}`) 
            let retStr = decoder.decodeWithStream(fileBytes) 
            let routerMapModel: RouterMapModel = JSON.parse(retStr) as RouterMapModel 
            loadRouterMap(routerMapModel, routerMap) 
          }) 
        }) 
        .catch((error: BusinessError) => { 
          //... 
        }); 
    } catch (error) { 
      //... 
    } 
  } 
}

根据URI跳转页面时，通过动态import并执行路由表中定义的registerFunction方法来实现动态注册组件

Button("跳转") 
  .onClick(()=>{ 
    DynamicRouter.pushUri("app://settings") 
  })
export class DynamicRouter { 
  //... 
  public static pushUri(uri: string, param?: Object, onPop?: (data: PopInfo) => void): void { 
    if (!DynamicRouter.routerMap.has(uri)) { 
      return; 
    } 
    let routerInfo: RouterInfo = DynamicRouter.routerMap.get(uri)!; 
    if (!DynamicRouter.builderMap.has(uri)) { 
      // 动态加载模块 
      import(`${DynamicRouter.config.libPrefix}/${routerInfo.pageModule}`) 
        .then((module: ESObject) => { 
          module[routerInfo.registerFunction!](routerInfo)   // 进行组件注册，实际执行了下文中的LoginViewRegister方法 
          DynamicRouter.navPathStack.pushDestination({ name: uri, onPop: onPop, param: param }); 
          DynamicRouter.pushRouterStack(routerInfo); 
        }) 
        .catch((error: BusinessError) => { 
          console.error(`promise import module failed, error code: ${error.code}, message: ${error.message}.`); 
        }); 
    } else { 
      DynamicRouter.navPathStack.pushDestination({ name: uri, onPop: onPop, param: param }); 
      DynamicRouter.pushRouterStack(routerInfo); 
    } 
  } 
}

组件注册实际执行的方法为LoginViewRegister（该文件为自动生成的模版代码）

// auto-generated RouterBuilder.ets 
import { DynamicRouter, RouterInfo } from '@app/dynamicRouter/Index' 
import { LoginView } from '../components/LoginView' 
 
@Builder 
function LoginViewBuilder() { 
  LoginView() 
} 
 
export function LoginViewRegister(routerInfo: RouterInfo) { 
  DynamicRouter.registerRouterPage(routerInfo, wrapBuilder(LoginViewBuilder)) 
}

通过wrapBuilder将自定义组件保存在组件表

export class DynamicRouter { 
  //... 
  // 通过URI注册builder 
  public static registerRouterPage(routerInfo: RouterInfo, wrapBuilder: WrappedBuilder<Object[]>): void { 
     const builderName: string = routerInfo.name; 
     if (!DynamicRouter.builderMap.has(builderName)) { 
       DynamicRouter.registerBuilder(builderName, wrapBuilder); 
     } 
   } 
 
   private static registerBuilder(builderName: string, builder: WrappedBuilder<Object[]>): void { 
     DynamicRouter.builderMap.set(builderName, builder); 
   } 
 
  // 通过URI获取builder 
  public static getBuilder(builderName: string): WrappedBuilder<Object[]> { 
    const builder = DynamicRouter.builderMap.get(builderName); 
    return builder as WrappedBuilder<Object[]>; 
  } 
}

首页Navigation通过组件表获取自定义组件Builder

@Entry 
@Component 
struct Index { 
  build() { 
    Navigation(DynamicRouter.getNavPathStack()) { 
      //... 
    } 
    .navDestination(this.PageMap) 
    .hideTitleBar(true) 
  } 
 
  @Builder 
  PageMap(name: string, param?: ESObject) { 
    NavDestination() { 
      DynamicRouter.getBuilder(name).builder(param); 
    } 
  } 
}

4. 实现路由表生成插件

新建插件目录etsPlugin，建议创建在HarmonyOS工程目录之外

mkdir etsPlugin 
cd etsPlugin

创建npm项目

npm init

安装依赖

npm i --save-dev @types/node @ohos/hvigor @ohos/hvigor-ohos-plugin 
npm i typescript handlebars

初始化typescript配置

./node_modules/.bin/tsc --init

修改tsconfig.json

{ 
  "compilerOptions": { 
    "target": "es2021",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */ 
    "module": "commonjs",                                /* Specify what module code is generated. */ 
    "strict": true,                                      /* Enable all strict type-checking options. */ 
    "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */ 
    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */ 
    "skipLibCheck": true,                                 /* Skip type checking all .d.ts files. */ 
    "sourceMap": true, 
    "outDir": "./lib", 
  }, 
  "include": [".eslintrc.js", "src/**/*"], 
  "exclude": ["node_modules", "lib/**/*"], 
}

创建插件文件src/index.ts

export function etsGeneratorPlugin(pluginConfig: PluginConfig): HvigorPlugin { 
  return { 
    pluginId: PLUGIN_ID, 
    apply(node: HvigorNode) { 
      pluginConfig.moduleName = node.getNodeName(); 
      pluginConfig.modulePath = node.getNodePath(); 
      pluginExec(pluginConfig); 
    }, 
  }; 
}

修改package.json

{ 
  //... 
  "main": "lib/index.js", 
  "scripts": { 
    "test": "echo \"Error: no test specified\" && exit 1", 
    "dev": "tsc && node lib/index.js", 
    "build": "tsc" 
  }, 
  //... 
}

插件实现流程

• 通过扫描自定义组件的ets文件，解析语法树，拿到注解里定义的路由信息
• 生成路由表、组件注册类，同时更新Index.ets

定义插件配置

const config: PluginConfig = { 
  builderFileName: "RouterBuilder.ets",  // 生成的组件注册类文件名 
  builderDir: "src/main/ets/generated",  // 代码生成路径 
  routerMapDir: "src/main/resources/rawfile/routerMap",  // 路由表生成路径 
  scanDir: "src/main/ets/components",  // 自定义组件扫描路径 
  annotation: "AppRouter",  // 路由注解 
  viewKeyword: "struct",  // 自定义组件关键字 
  builderTpl: "viewBuilder.tpl",  // 组件注册类模版文件 
};

插件核心代码：

function pluginExec(config: PluginConfig) { 
  // 读取指定自定义组件目录下的文件 
  const scanPath = `${config.modulePath}/${config.scanDir}`; 
  const files: string[] = readdirSync(scanPath); 
  files.forEach((fileName) => { 
    // 对每个文件进行解析 
    const sourcePath = `${scanPath}/${fileName}`; 
    const importPath = path 
      .relative(`${config.modulePath}/${config.builderDir}`, sourcePath) 
      .replaceAll("\\", "/") 
      .replaceAll(".ets", ""); 
 
    // 执行语法树解析器 
    const analyzer = new EtsAnalyzer(config, sourcePath); 
    analyzer.start(); 
 
    // 保存解析结果 
    console.log(JSON.stringify(analyzer.analyzeResult)); 
    console.log(importPath); 
    templateModel.viewList.push({ 
      viewName: analyzer.analyzeResult.viewName, 
      importPath: importPath, 
    }); 
    routerMap.routerMap.push({ 
      name: analyzer.analyzeResult.uri, 
      pageModule: config.moduleName, 
      pageSourceFile: `${config.builderDir}/${config.builderFileName}`, 
      registerFunction: `${analyzer.analyzeResult.viewName}Register`, 
    }); 
  }); 
 
  // 生成组件注册类 
  generateBuilder(templateModel, config); 
  // 生成路由表 
  generateRouterMap(routerMap, config); 
  // 更新Index文件 
  generateIndex(config); 
}

语法树解析流程

• 遍历语法树节点，找到自定义注解@AppRouter
• 读取URI的值
• 通过识别struct关键字来读取自定义组件类名
• 其他节点可以忽略

核心代码：

export class EtsAnalyzer { 
  sourcePath: string; 
  pluginConfig: PluginConfig; 
  analyzeResult: AnalyzeResult = new AnalyzeResult(); 
  keywordPos: number = 0; 
 
  constructor(pluginConfig: PluginConfig, sourcePath: string) { 
    this.pluginConfig = pluginConfig; 
    this.sourcePath = sourcePath; 
  } 
 
  start() { 
    const sourceCode = readFileSync(this.sourcePath, "utf-8"); 
    // 创建ts语法解析器 
    const sourceFile = ts.createSourceFile( 
      this.sourcePath, 
      sourceCode, 
      ts.ScriptTarget.ES2021, 
      false 
    ); 
    // 遍历语法节点 
    ts.forEachChild(sourceFile, (node: ts.Node) => { 
      this.resolveNode(node); 
    }); 
  } 
 
  // 根据节点类型进行解析 
  resolveNode(node: ts.Node): NodeInfo | undefined { 
    switch (node.kind) { 
      case ts.SyntaxKind.ImportDeclaration: { 
        this.resolveImportDeclaration(node); 
        break; 
      } 
      case ts.SyntaxKind.MissingDeclaration: { 
        this.resolveMissDeclaration(node); 
        break; 
      } 
      case ts.SyntaxKind.Decorator: { 
        this.resolveDecorator(node); 
        break; 
      } 
      case ts.SyntaxKind.CallExpression: { 
        this.resolveCallExpression(node); 
        break; 
      } 
      case ts.SyntaxKind.ExpressionStatement: { 
        this.resolveExpression(node); 
        break; 
      } 
      case ts.SyntaxKind.Identifier: { 
        return this.resolveIdentifier(node); 
      } 
      case ts.SyntaxKind.StringLiteral: { 
        return this.resolveStringLiteral(node); 
      } 
      case ts.SyntaxKind.PropertyAssignment: { 
        return this.resolvePropertyAssignment(node); 
      } 
    } 
  } 
 
  resolveImportDeclaration(node: ts.Node) { 
    let ImportDeclaration = node as ts.ImportDeclaration; 
  } 
 
  resolveMissDeclaration(node: ts.Node) { 
    node.forEachChild((cnode) => { 
      this.resolveNode(cnode); 
    }); 
  } 
 
  resolveDecorator(node: ts.Node) { 
    let decorator = node as ts.Decorator; 
    this.resolveNode(decorator.expression); 
  } 
 
  resolveIdentifier(node: ts.Node): NodeInfo { 
    let identifier = node as ts.Identifier; 
    let info = new NodeInfo(); 
    info.value = identifier.escapedText.toString(); 
    return info; 
  } 
 
  resolveCallExpression(node: ts.Node) { 
    let args = node as ts.CallExpression; 
    let identifier = this.resolveNode(args.expression); 
    this.parseRouterConfig(args.arguments, identifier); 
  } 
 
  resolveExpression(node: ts.Node) { 
    let args = node as ts.ExpressionStatement; 
    let identifier = this.resolveNode(args.expression); 
    if (identifier?.value === this.pluginConfig.viewKeyword) { 
      this.keywordPos = args.end; 
    } 
    if (this.keywordPos === args.pos) { 
      this.analyzeResult.viewName = identifier?.value; 
    } 
  } 
 
  resolveStringLiteral(node: ts.Node): NodeInfo { 
    let stringLiteral = node as ts.StringLiteral; 
    let info = new NodeInfo(); 
    info.value = stringLiteral.text; 
    return info; 
  } 
 
  resolvePropertyAssignment(node: ts.Node): NodeInfo { 
    let propertyAssignment = node as ts.PropertyAssignment; 
    let propertyName = this.resolveNode(propertyAssignment.name)?.value; 
    let propertyValue = this.resolveNode(propertyAssignment.initializer)?.value; 
    let info = new NodeInfo(); 
    info.value = { key: propertyName, value: propertyValue }; 
    return info; 
  } 
 
}

使用模版引擎生成组件注册类

使用Handlebars生成组件注册类

const template = Handlebars.compile(tpl); 
const output = template({ viewList: templateModel.viewList });

模版文件viewBuilder.tpl示例：

// auto-generated RouterBuilder.ets 
import { DynamicRouter, RouterInfo } from '@app/dynamicRouter/Index' 
{{#each viewList}} 
import { {{viewName}} } from '{{importPath}}' 
{{/each}} 
 
{{#each viewList}} 
@Builder 
function {{viewName}}Builder() { 
  {{viewName}}() 
} 
 
export function {{viewName}}Register(routerInfo: RouterInfo) { 
  DynamicRouter.registerRouterPage(routerInfo, wrapBuilder({{viewName}}Builder)) 
} 
 
{{/each}}

生成的RouterBuilder.ets代码示例：

// auto-generated RouterBuilder.ets 
import { DynamicRouter, RouterInfo } from '@app/dynamicRouter/Index' 
import { LoginView } from '../components/LoginView' 
 
@Builder 
function LoginViewBuilder() { 
  LoginView() 
} 
 
export function LoginViewRegister(routerInfo: RouterInfo) { 
  DynamicRouter.registerRouterPage(routerInfo, wrapBuilder(LoginViewBuilder)) 
}

将路由表和组件注册类写入文件

• 路由表保存在rawfile目录
• 组件注册类保存在ets代码目录
• 更新模块导出文件Index.ets

核心代码：

function generateBuilder(templateModel: TemplateModel, config: PluginConfig) { 
  console.log(JSON.stringify(templateModel)); 
  const builderPath = path.resolve(__dirname, `../${config.builderTpl}`); 
  const tpl = readFileSync(builderPath, { encoding: "utf8" }); 
  const template = Handlebars.compile(tpl); 
  const output = template({ viewList: templateModel.viewList }); 
  console.log(output); 
  const routerBuilderDir = `${config.modulePath}/${config.builderDir}`; 
  if (!existsSync(routerBuilderDir)) { 
    mkdirSync(routerBuilderDir, { recursive: true }); 
  } 
  writeFileSync(`${routerBuilderDir}/${config.builderFileName}`, output, { 
    encoding: "utf8", 
  }); 
} 
 
function generateRouterMap(routerMap: RouterMap, config: PluginConfig) { 
  const jsonOutput = JSON.stringify(routerMap, null, 2); 
  console.log(jsonOutput); 
  const routerMapDir = `${config.modulePath}/${config.routerMapDir}`; 
  if (!existsSync(routerMapDir)) { 
    mkdirSync(routerMapDir, { recursive: true }); 
  } 
  writeFileSync(`${routerMapDir}/${config.moduleName}.json`, jsonOutput, { 
    encoding: "utf8", 
  }); 
} 
 
function generateIndex(config: PluginConfig) { 
  const indexPath = `${config.modulePath}/Index.ets`; 
  const indexContent = readFileSync(indexPath, { encoding: "utf8" }); 
  const indexArr = indexContent 
    .split("\n") 
    .filter((value) => !value.includes(config.builderDir!)); 
  indexArr.push( 
    `export * from './${config.builderDir}/${config.builderFileName?.replace( 
      ".ets", 
      "" 
    )}'` 
  ); 
  writeFileSync(indexPath, indexArr.join("\n"), { 
    encoding: "utf8", 
  }); 
}

5. 在应用中使用

修改项目的hvigor/hvigor-config.json文件，导入路由表插件

{ 
  "hvigorVersion": "4.2.0", 
  "dependencies": { 
    "@ohos/hvigor-ohos-plugin": "4.2.0", 
    "@app/ets-generator" : "file:../../etsPlugin"   // 插件目录的本地相对路径，或者使用npm仓版本号 
  }, 
  //... 
}

修改loginModule模块的hvigorfile.ts文件(loginModule/hvigorfile.ts)，加载插件

import { harTasks } from '@ohos/hvigor-ohos-plugin'; 
import {PluginConfig,etsGeneratorPlugin} from '@app/ets-generator' 
 
const config: PluginConfig = { 
    builderFileName: "RouterBuilder.ets", 
    builderDir: "src/main/ets/generated", 
    routerMapDir: "src/main/resources/rawfile/routerMap", 
    scanDir: "src/main/ets/components", 
    annotation: "AppRouter", 
    viewKeyword: "struct", 
    builderTpl: "viewBuilder.tpl", 
} 
 
export default { 
    system: harTasks,  /* Built-in plugin of Hvigor. It cannot be modified. */ 
    plugins:[etsGeneratorPlugin(config)]         /* Custom plugin to extend the functionality of Hvigor. */ 
}

在loginModule模块的oh-package.json5中引入动态路由模块依赖

{ 
  "name": "loginmodule", 
  "version": "1.0.0", 
  "description": "Please describe the basic information.", 
  "main": "Index.ets", 
  "author": "", 
  "license": "Apache-2.0", 
  "dependencies": { 
    "@app/dynamicRouter": "file:../routerModule" 
  } 
}

在loginModule模块的自定义组件中使用@AppRouter定义路由信息

@AppRouter({ uri: "app://login" }) 
@Component 
export struct LoginView { 
  build(){ 
    //... 
  } 
}
在entry中的oh-package.json5中引入依赖
{ 
  "name": "entry", 
  "version": "1.0.0", 
  "description": "Please describe the basic information.", 
  "main": "", 
  "author": "", 
  "license": "", 
  "dependencies": { 
    "@app/loginModule": "file:../loginModule", 
    "@app/commonModule": "file:../commonModule", 
    "@app/dynamicRouter": "file:../routerModule" 
  } 
}

在entry中的build-profile.json5中配置动态import

{ 
  "apiType": "stageMode", 
  "buildOption": { 
    "arkOptions": { 
      "runtimeOnly": { 
        "packages": [ 
          "@app/loginModule",  // 仅用于使用变量动态import其他模块名场景，静态import或常量动态import无需配置。 
          "@app/commonModule"  // 仅用于使用变量动态import其他模块名场景，静态import或常量动态import无需配置。 
        ] 
      } 
    } 
  }, 
  //... 
}

在entry中的EntryAbility.onCreate中初始化路由组件

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 
  DynamicRouter.init({ 
    libPrefix: "@app", mapPath: "routerMap" 
  }, this.context); 
}

组件内使用pushUri进行跳转

Button("立即登录", { buttonStyle: ButtonStyleMode.TEXTUAL }) 
  .onClick(() => { 
    DynamicRouter.pushUri("app://login") 
  }) 
  .id("button")

在entry模块执行Run/Debug，即可在编译时自动生成路由表配置并打包运行。