@esydoc/resolver-demo

resolver-demo

一个解析Api源码生成Demo代码的解析器

Installation

npm i @esydoc/resolver-qa -D

Usage

在 esydoc.config.js文件中的resolves字段添加@esydoc/resolver-demo对应的配置就ok拉。

// for example in esydoc.config.js
{
  resolves: {
    '@esydoc/resolver-demo': {
      excludes: [], // glob Exp
      includes: [], // glob Exp
      output: {
        template: 'hyext-demo-miniapp',
        dist: path.join(__dirname, 'demo-miniapp'),
        hostContext: {
          projectName: 'esydoc-demo'
        }
      }
    }
  }
}

Esydoc Extra Config

无。

API配置文件对应配置

我们知道，esydoc会为每个标记了@eapi标签的接口源码，生成一份以接口命名的配置文件，这里的对应配置是指resolver-demo输出的相应配置。

For example:

// some.api.js
{
  demo: {
    args: [], // 参数描述节点
    validate: true, // 表单校验
    interceptors: {} // hooks
  }
}

接下来，我们来说说这几个参数的作用

args

args由resolver动态生成，它是一个数组，代表调用这个API所用的参数队列，参数队列，里面包含的是一种称为ValueDesciption的节点，它包含这个参数的值相关的信息，为UI层数据可视化提供了基础，在一般情况下，不需要用户修改它。

ValueDesciption数据结构

export type ValueDescriptionNode = {
  id: string // id 
  name: string // 参数名字
  valueType: string // 参数值类型
  description: string // 参数描述
  value: any // 参数值
  defaultValue: any // 默认值
  formItemType: 'input' | 'select' | 'switch' | 'slef-impliment' // 表单类型
  options?: FormItemOptions // formItemType = select | checkbox存在 // 参数选项
  parentNodeType?: string // 父节点类型
}

下面挑一些比较有内涵的参数介绍一下

description

description是一个有约定的参数注释，具体请看下面图片解析：

formItemType

resolver的模板会根据formItemType的不同生成不一样的表单控件

• 'input' - 输入框
• 'select' - 选择框
• 'switch' - 开关
• 'slef-impliment' - 自我实现

slef-impliment

为什么会有这个选项？

因为参数的类型多种多样，有一些特殊的情况，你就无法用到那些表单控件，所以这里用slef-impliment去跳过控件的渲染

我目前总结的特殊情况有如下:

1. 当参数是一个函数，你不能直接用ui控件去展示
2. 当参数是一个很复杂的对象，我不建议你直接去展示，你可以设置slef-impliment，直接或间接修改value
3. 当参数需要的数据不适合从表单控件中获取的时候（例如：我需要一个原型对象），直接或间接修改value

如何直接或间接修改value?

• 直接，在配置中修改ValueDescriptionNode的value值
• 间接，通过interceptors提供的hooks去修改

interceptors

在调用api这个流程中，留了一些hooks给用户做一些事情，它的数据结构大致为：

type Interceptors = {
  this: {
    onCall: (helper: any, ...args: any[]) => any[]
  },
  [key: string]: {
    onCall: (helper: any, value: any) => any
  }
}

其中this是一个特殊key，它第二参数是整个接口调用的参数队列, 而其他key代表的是参数名，它第二参数是它的值

// stream.getStreamingInfo.js为例
{
  demo: {
     interceptors: {
      keys: {
        onCall: (heler, value) => {
          const keys = value.split(',').map((v) => v.trim())
          return { keys }
        }
      },
      this: {
        onCall: (heler, keys) => {
          // 这里传的是整次调用的参数keys了

          // 返回修改过后的参数args
          return [
            keys
          ]
        }
      }
    },
  }
}

helper

从上文得知，interceptor的回调函数会传入一个helper对象，这个helper封装了一些接口，方面用户获取运行时的一些资源。

• helper.getJceInfo() - 返回一个jce信息对象，用于jce相关接口调用，数据结构具体如下：

{
  uri: '8856',
  class: HUYA // 结构体wrapper
}

• helper.tip(msg:string) - 弹出toast

validate

validate配置提供高定制表单验证功能

所有字段验证

• 当validate：true时，所有字段都会被验证，验证规则为'required'
• 当validate：${rules}时，所有字段都会使用被验证，验证规则为rules, rules可以是单个规则也可以是多个，例如：'required'或者'required|date|some rule'

指定某些字段验证

输出默认错误模式，每个规则都有默认的错误语句

{
  validate：{
    [name]: true | 'date' | 'required|date' // true - 默认使用’required‘, {rule} - 动态指定规则
  }
}

自定义错误模式

{
  validate：{
    [name]: {
      rules: 'required',
      errors: ['这个xx字段你必须要填哦~']
    }
  }
}

内置规则

• required - 判断字段是否空白
• date - 检查日期 格式：YYYY-MM-DD hh:mm:ss
• phone - 检查手机号码格式

内置模板

• hyext-demo-miniapp - Demo虎牙小程序模板