Skip to content

Latest commit

 

History

History
executable file
·
346 lines (273 loc) · 9.16 KB

传给模板的数据格式说明.md

File metadata and controls

executable file
·
346 lines (273 loc) · 9.16 KB
Raw

传给模板的数据说明

在使用 handlebars 渲染模板的时候，会传入以下数据:

{
    "args": {},
    "config": {},
    "project": {},
    "spec": {},
    "interfaceMockRules": [],
    "datatypeEnums": [],
    "ds":{
        "views": [],
        "templates": [],
        "interfaces": [],
        "datatypes": []
    }
}

约定术语

为后文表述简洁起见，现约定如下:

1."参数数组": 表示它的值是一个数组，数组元素是参数，参数的格式如下:

{
    "name": "参数名称",
    "type": "参数类型名称，如果参数是数组，则它是数组元素的类型名称",
    "originalType": "同 type, 是参数的初始名称, 即映射前的名称",
    "arrDim": "如果参数是数组或者多维数组, 则它表示数组的维数值, 0 表示非数组, 1 表示一维数组, 依此类推",
    "defaultValue": "参数默认值",
    "required": "布尔值， true 表示必需，false 表示非必需",
    "ignored": "布尔值，true 表示该参数已被忽略，false 表示未被忽略，忽略操作请参考 NEI 网站平台",
    "genExp": "参数生成规则",
    "description": "描述"
}

2."值的类别": 它的值是整数，含义如下:

值 含义
0 映射
1 枚举
2 数组
3 字符
4 数值
5 布尔
6 文件

3."业务分组": 它的格式如下:

{
    "name": "所在业务分组名称",
    "description": "所在业务分组描述"
}

4."键值对数组": 表示它的值是一个数组，数组元素是键值对，格式如下:

{
    "key": "名称",
    "value": "值",
    "description": "描述"
}

args

命令行参数对象，它的值来自三部分:

1.命令行参数

指的是用户在命令行中输入的参数，可以是用于构建工具自身的参数，也可以是用于模板填充的数据

2.在项目中设置的命令行参数列表

在项目的"工具设置"中，我们可以设置"命令行参数"，它们以键值对的形式展示

3.在工程规范中指定的命令行参数文件

在创建工程规范的工程结构时，我们可以指定某个文件是"命令行参数配置文件"，该文件的内容须是有效的 json。如果指定了多个这样的文件，则取第一个文件的内容

它们三者的优先级关系如下:

命令行参数 > 在项目中设置的命令行参数列表 > 在工程规范中指定的命令行参数文件

以 nei build 命令举例来说，假设用户在命令行中输入:

nei build -k xxx -ProductName nei

在项目中设置的命令行参数列表为:

名称 值
o ./webpro
specType web
ProductName youfan

在工程规范中指定的命令行参数文件的内容为:

{
    "o": "./",
    "specType": "ios"
}

则最终计算得到的 args 值为:

{
    "key": "xxx",
    "ProductName": "nei",
    "output": "./webpro",
    "specType": "web"
}

注意1: 如果输入的参数值是简写形式的，则传给模板的数据中会转换成相应的全写形式

注意2: 由于在命令行参数输入的值以及在项目中设置的命令行参数列表的值都是字符串，无法区分布尔和数值类型，本工具会对这些值进行特殊处理:

// 在命令行中输入
--A false   // 值为布尔类型的 false
--A 'false' // 值为字符串类型的 "false"
--A "false" // 值为布尔类型的 false, 这种写法等价于 --A false, 此时 Node 给出的值和第一种相同, 无法处理成字符串

// 在项目中设置的命令行参数列表
A false   // 值为布尔类型的 false
A 'false' // 值为字符串类型的 "false"
A "false" // 值为字符串类型的 "false"

// 数值类型的处理过程和上面的相同

config

项目的一些配置信息，格式如下:

{
    "webRoot": "静态资源根路径，相对于项目根目录，例如: /public",
    "viewRoot": "模板根路径，相对于项目根目录，例如: /view",
    "mockApiRoot": "异步接口mock数据的根路径，相对于项目根目录，例如: /mock.data/interface",
    "mockViewRoot": "页面模板mock数据的根路径，相对于项目根目录，例如: /mock.data/template",
}

project

项目数据对象，格式如下:

{
    "id": "唯一标识",
    "name": "名称",
    "description": "描述",
    "creator": {
       "name": "创建者姓名",
       "email": "创建者email"
    }
}

spec

规范信息，格式如下:

{
    "name": "名称",
    "description": "描述",
    "document": "文档",
    "language": "实现语言"
}

如果是 Web 规范，除了上面的字段外，还会有以下字段:

{
    "engine": "模板引擎",
    "viewExt": "模板扩展名"
}

interfaceMockRules

异步接口的 mock 规则列表，列表元素的格式如下:

{
    "path": "请求地址",
    "method": "请求方法",
    "mockFile": "mock 数据路径",
}

注: 该数据可以用来生成 Fiddler 或者 Charles 的规则

datatypeEnums

枚举数据模型列表，包含所有枚举类型的数据模型，列表元素的格式如下:

{
    "name": "名称",
    "type": "类型",
    "members": "键值对数组，见约定术语4"
}

如果要使用枚类数据列表填充,只需在文件名后面加上!!enum, 并选择数据类型列表填充.

ds

Handlebars 模板的数据源。

在 NEI 上的工程规范中，当某个文件选择以某种资源数据来填充时，NEI 构建会遍历相应的数据源列表，列表的每项元素都会生成相应的文件。此时，会额外传入列表项对象。

比如，我们选择 "文件 A" 以 "异步接口列表填充"，则此时传给模板的数据中会增加一个字段"interface"，它就是 ds 字段中相应的列表项:

{
    "args": {},
    "project": {},
    "spec": {},
    "interfaceMockRules": [],
    "datatypeEnums": [],
    "interface": {},
    "ds": {}
}

列表名称和列表项名称对应关系如下:

列表 列表项
views view
templates template
interfaces interface
datatypes datatype

views

视图数据列表，列表元素的格式如下:

{
    "name": "名称",
    "path": "路径，如果路径没有后缀，则会加上规范中指定的模板扩展名",
    "tag": "标签，以逗号分隔",
    "title": "标题",
    "className": "类名",
    "description": "描述",
    "group": "业务分组，见约定术语3",
    "templates": "页面引用的页面模板数组, 数组元素的格式和下面的 templates 列表元素相同"
}

templates

页面模板数据列表，列表元素的格式如下:

{
    "name": "名称",
    "path": "访问地址",
    "filename": "文件名，不包括后缀",
    "tag": "标签，以逗号分隔",
    "description": "描述",
    "group": "业务分组，见约定术语3",
    "params": "参数数组，见约定术语1"
}

注意，改列表中的每个模板都是被页面引用的，也就是说如果模板没有被页面引用，则不会生成相应的文件

interfaces

异步接口列表，列表元素的格式如下:

{
    "name": "名称",
    "description": "描述",
    "tag": "标签，以逗号分隔",
    "path": "请求地址",
    "method": "方法",
    "className": "类名",
    "group": "业务分组，见约定术语3",
    "inputs": "参数数组，见约定术语1",
    "outputs": "参数数组，见约定术语1",
    "outputModel": "输出参数模型的名称",
    "outputModelArrDim": "如果输出参数模型是数组或者多维数组, 则它表示数组的维数值, 0 表示非数组, 1 表示一维数组, 依此类推",
    "reqHeaders": "请求头，键值对数组，见约定术语4",
    "reqFormat": "值的类别，见约定术语2",
    "resFormat": "值的类别，见约定术语2",
    "reqClassName": "请求接口名,优先级因此为:合法的className>合法的name>path,当为path时,会将path转为驼峰命名方法,如/test/login->TestLogin",
    "reqConstHeaders": "Header为常量的数组",
    "reqVarHeaders": "Header为变量的数组"
}

outputModel 和 outputModelArrDim 字段值的计算规则详见代码注释: outputModel计算规则

datatypes

数据模型列表，列表元素要么是哈希类型，要么是枚举类型，枚举类型的格式同 datatypeEnums 的元素的格式，哈希类型的格式如下:

{
    "name": "名称",
    "description": "描述",
    "tag": "标签，以逗号分隔",
    "group": "业务分组，见约定术语3",
    "fields": "参数数组，见约定术语1",
    "depModels": "依赖类的哈希表，为{name:type}。"
}

数据模型要同时满足以下条件才会生成文件:

  1. 是映射类别或者枚举类型
  2. 非隐藏类型
  3. 所有字段中没有可变类型
  4. 名称不以下划线开头