@edoc/core

辅助代码生成器

安装

  $ npm i @esydoc/core -D

使用

1. 命令式

  $ [npx] esydoc --config [configFilePath]

configFilePath 可以是相对于process.cwd()的路径片段或绝对路径

2. 编程式

const esydoc = require('@esydoc/core')
const esydocConfig = {
  /* some esydoc config */
}

esydoc(esydocConfig, (err: null | Error, stats: { errors: ScheduledErrors; results: ResolverScheduledResult[] }) => {
  // 系统错误
  if (err) {
    throw err
  }

  const { errors, results } = stats

  // 调度接口发生的错误将会被收集于此数组，用户自行控制报错与否
  if  (errors.length > 0) {

  } else {

  }
})

// 数据结构
export type ScheduledErrors = { source: ApiSource, error: Error }[]

export type ResolverScheduledResult = {
  hostContext?: { [key: string]: any }
  dist: string
  templatePath: string
  sourceUpdateRsp: SourceUpdateRsp
  belong: string
  filterFileList?: string []
}

esydoc 配置

• context: string, 上下文路径，多用于相对路径的拼接。

• source - 源配置

  • source.include: string | string[]，包含被扫描源码文件的路径（必填）。
  • source.exclude？: string | string[]，排除被扫描源码文件的路径。

• apiConfigPaths: string[]， api 配置路径。

• apiConfigDefaultOutputPath: string[]， api 配置默认生成路径。

• include?: string[]，包括需要处理的接口

• exclude？: string[]，不包括需要处理的接口

• plugins？: (path | plugin instance)[], schduler的插件注册字段

• resolves: Object，resolves 配置的对象是以 key 为 resolver 名字，value 为 resolver 配置，数据结构会在Resolver章节详细介绍。

完整示例

module.exports = {
  source: {
    include: ['src/modules'],
    exclude: ['src/modules/edoc-api-config']
  },
  context: __dirname,
  apiConfigPaths: ['src/modules/edoc-api-config/**.js'],
  apiConfigDefaultOutputPath: 'src/modules/edoc-api-config',
  resolves: {
    '@esydoc/resolver-demo': {
      includes: ['src/modules/edoc-api-config/advance.*.js'],
      excludes: [],
      output: {
        template: 'hyext-demo-miniapp',
        dist: path.join(__dirname, 'demo-miniapp'),
        hostContext: {
          projectName: 'esydoc-demo'
        }
      }
    }
  }
}

标签

esydoc 提供一些专有注释标签，辅助代码的生成。

@eapi

标记该 API 是一个需要被解析的接口。

DEMO

  /**
   * 发送小程序消息
   * @eapi
   * @param {OnPostLocalMessage} params
   * @returns {Promise<any>}
   */
  postLocalMessage({ eventName, message }) {
    return extsdk.core.callEvent(MODULE_NAME, "postLocalMessage", {
      eventName,
      message,
    });
  },

@edata

标记该 数据 是一个类型定义声明，常用于生成配置模板。

  /**
   * @edata
   * @typedef {Object} LayoutInfo
   * @property {number} screenWidth 容器宽度
   * @property {number} screenHeight 容器高度
   * @property {boolean} isLandscape 是否横屏，web端固定为true
   */
  /**
   * @edata
   * @callback LayoutChange
   * @param {LayoutInfo} info
   */
  /**
   * 监听当前直播间小程序容器布局变化消息
   * @eapi
   * @param {LayoutChange} callback
   * @returns {Promise<any>} reject为失败
   */
  onLayoutChange(callback) {
    return extsdk.core.onEvent(MODULE_NAME, 'onLayoutChange', callback);
  },

@shared

表示这个@edata是被共享的，默认情况下edata都有一个以文件为单位的作用域，如果将它共享给其他文件使用，可以加上该标签。

API

esydoc(config: EsydocConfig, cb: (err: Error|null, stats: { errors: Error[], result: any }))

其中 config 为 esydoc 的配置对象，在上面有详细说明，cb 为传入一个回调函数，主要为了告知用户esydoc已经执行结束，并提供一些编译的信息

Resolver

Resolver负责解析接口的注释生成配置和代码，是esydoc整套体系必不可少的部分。

配置

配置从esydoc配置的resolves字段中获取。

基本配置

• excludes?:string[] - 需要过滤的接口文件，支持 glob 表达式。
• includes？:string[] - 需要包含的接口文件，支持 glob 表达式。
• output.template:string - 模板名
• output.dist:string - 代码生成安置路径
• output.hostContext - 生成代码运行时的上下文
• filterFileList:string[] - 在生成项目已存在的时候，我们可能只需要更新某些文件而不是整个项目被覆盖，此时可以通过这个选项指令哪个文件需要被更新。
• plugins？: (path | plugin instance)[], Resolver 的插件注册字段

额外配置

因为每个 resolver 都是独立的存在，所以它除了基本配置，应该还有额外的配置去处理它自己的事情，所以我们可以在基本配置上额外添加属性透传给 resolver。

for example:

// esydoc.config.js
{
  resolves: {
    '@esydoc/resolver-qa': {
      pathPrefix: 'global.hyExt', // 透传一个额外属性`pathPrefix给qa-resolver`
      output: {
        hostContext: {
          mocha: { timeout: 8 * 1000 }, // mocha额外字段
          projectName: "qa-effect",
        },
      }
    },
  }
}

Resolver 列表

• resolver-qa - 解析源码，生成QA相关的配置和代码
• resolver-demo - 解析源码, 生成Demo相关的配置和代码

如何开发一个 Resolver?

详情请查看开发Resolver教程