返回

AsyncAPI Generator 选项无效?详解及解决之道

javascript

AsyncAPI Generator 选项传递问题解析

在使用 AsyncAPI Generator 时,开发者有时会遇到一个问题:在生成代码时,传递的生成器选项(generator options)似乎没有生效。这可能导致生成的代码不符合预期,需要仔细排查问题原因并找到解决方案。

问题剖析

当尝试利用 AsyncAPI Generator 根据规范生成代码,并同时设置如包名(packageName)、是否启用 Jackson 支持(javaJackson)、数组类型(javaArrayType)等参数时,实际生成的代码并未按照所提供的选项进行调整。整个项目结构正确创建,但其中的模型类却采用了模板默认配置,并非用户期望的自定义配置。问题的核心在于选项传递流程中存在未知的干扰因素,导致这些配置无法被正确解析和应用。

解决方案与实践

下面提供了几种解决此类问题的方法,并结合代码示例与步骤进行说明。

1. 检查 generatorOptions 的放置位置

generatorOptions 的放置位置至关重要。请确保将此对象作为 generateFromFile 方法的第二个参数传递。某些情况下,初学者容易将这些选项作为配置项传给 Generator 构造函数,这样不会生效。正确的用法是将它们传递给生成动作的具体方法,如 generateFromFile

const Generator = require('@asyncapi/generator');
const path = require('path');

const outputDir = path.resolve(__dirname, 'build/asyncapi');
const asyncApiFile = path.resolve('build/generated/asyncapi/', 'test.yaml');

const generatorOptions = {
   packageName: 'com.example.test',
   javaJackson: true,
   javaArrayType: 'List',
   noInteractive: true
};

const generator = new Generator('@asyncapi/java-spring-template', outputDir);

generator
  .generateFromFile(asyncApiFile, generatorOptions) // options在此处
  .then(() => {
    console.log('完成!');
  })
  .catch(error => {
    console.error('错误:', error);
  });

操作步骤:

  1. 确保你的AsyncAPI文件 (如 test.yaml) 已正确存在。
  2. 安装 AsyncAPI 生成器 @asyncapi/generator 以及相应的模板, 如 @asyncapi/java-spring-template
  3. 将代码示例复制粘贴到你项目的相应位置(如脚本文件 generator.js),并进行路径调整。
  4. 运行脚本。比如 node generator.js

说明: generatorOptions 对象必须作为第二个参数,传递给 generateFromFile 函数。这个参数定义了生成代码时需要使用的配置项。noInteractive: true 这个选项用于抑制交互提示,适用于自动化环境。

2. 查看模板是否支持所选项

部分模板可能并不完全支持所有可用的选项。仔细查阅所选模板的官方文档或仓库,确认模板是否提供了相关选项支持。一些模板可能会对选项命名或格式有特殊要求。如果文档没有清晰说明,可以查阅模板源代码或其测试用例来获得更多信息。

例如 @asyncapi/java-spring-template 的官方文档应该会支持哪些配置,或参考模板代码中对 this.parameters 的调用和如何使用它们。

操作步骤:

  1. 找到模板的 GitHub 仓库,例如 https://github.com/asyncapi/java-spring-template
  2. 在仓库内,寻找关于选项配置的文件。这通常位于 README 或 /templates 目录中,特别是处理参数 this.parameters 的代码块。
  3. 仔细查看参数的名称和期望值,并对照在代码中传递的选项名称。
  4. 如发现参数名称不同,或类型不匹配,进行修改以适配模板。

3. 使用 generate 函数处理直接字符串输入

有些情况,可以不依赖文件路径直接使用 generate 函数,把异步规范的内容当做字符串传给它。这样做在处理一些特殊文件系统权限或跨文件读取时很便利, 同时也更加方便直接debug和追踪配置的实际应用情况。

const Generator = require('@asyncapi/generator');
const path = require('path');
const fs = require('fs');

const outputDir = path.resolve(__dirname, 'build/asyncapi');
const asyncApiFile = path.resolve('build/generated/asyncapi/', 'test.yaml');

const generatorOptions = {
   packageName: 'com.example.test',
   javaJackson: true,
   javaArrayType: 'List',
   noInteractive: true
};


const generator = new Generator('@asyncapi/java-spring-template', outputDir);

fs.promises.readFile(asyncApiFile, 'utf8')
    .then(async apiSpecContent => {
      return generator.generate(apiSpecContent, generatorOptions)
    })
    .then(() => {
        console.log('生成完毕!');
    })
    .catch(error => {
        console.error('发生错误:', error);
    });

操作步骤:

  1. 参照前面的方式,创建或者获取 AsyncAPI 文件 test.yaml。
  2. 修改脚本代码,使用 fs.promises.readFile 方法读取文件内容,然后传递给 generate 函数。
  3. 运行该脚本,确保生成结果中使用了自定义选项。

说明: 读取文件后,我们使用 generate 方法,第一个参数为字符串形式的 AsyncAPI 文件内容,第二个参数依然是生成器配置 generatorOptions

额外提示

  1. 确保模板已正确安装,并和 Generator 版本匹配。
  2. 可以尝试使用更详细的输出选项 (例如设置环境变量DEBUG='asyncapi:generator:*'),查看日志输出, 可能会暴露更多问题线索。
  3. 测试前可以清除旧的生成文件夹,避免旧的缓存代码影响判断。

通过上述步骤,通常可以解决 AsyncAPI Generator 选项传递不生效的问题,获得按期望配置生成代码的目的。