扩展库协议 v1.0

1. 介绍

• 版本号：本协议版本号与当前 NASL 版本号一致
• 提案人：赵雨森
• 评审人：NASL 技术委员会全体成员

(1) 背景

NASL 中提供了模块化机制，支持以下三点：

1. 分解应用的复杂性
2. 提升相同实现的复用性
3. 支持对接其他通用语言的扩展性

本协议主要围绕上面 2、3 两点，确定开发扩展库的规范，包括：

• 专业开发者用传统代码编写好扩展库之后，需要提供的 NASL 声明描述所提供的类型、函数签名等 API 信息规范
• 专业开发者用传统代码编写时的工程规范

2. 结构描述

一套完整全栈的扩展库包含以下概念：

• 数据结构
• 枚举
• 全局逻辑
• 前端全局变量
• 前端组件

(1) 顶层结构

扩展库以 Module 节点为根节点。

结构如下：

interface Module {
    concept: 'Module'; // 产品概念
    type: 'extension';
    version: string; // version
    name: string; // 模块名称
    title: string; // 模块标题
    description: string; // 模块描述
    provider: string; // provider
    externalDependencyMap: { maven?: Array<{ groupId: string; artifactId: string; version: string }> }; // 外部语言依赖，目前仅在后端扩展模块中使用。
    dataSources: Array<DataSource>; // 数据源列表
    structures: Array<Structure>; // 数据结构列表
    enums: Array<Enum>; // 枚举列表
    logics: Array<Logic>; // 逻辑列表
    interfaces: Array<Interface>; // 接口列表
    views: Array<View>; // 页面列表
    frontendVariables: Array<Variable>; // 变量列表
    processes: Array<Process>; // 流程列表
    viewComponents: Array<ViewComponent>; // 页面组件列表
}

(2) 数据结构

遵循数据结构 Structure 的语法树节点。

(3) 枚举

遵循枚举 Enum 的语法树节点。

(4) 全局逻辑

遵循逻辑 Logic 的语法树节点。

(5) 前端全局变量

遵循变量 Variable 的语法树节点。

(6) 前端组件

遵循前端组件 ViewComponent 的语法树节点。

(7) 完整示例

比如描述一个解析 Excel 的库，需要添加 NASL 声明文件excel_parser.d.nast：

concept: Module
name: excel_parser
type: extension
version: 1.0.1
title: excel-parser
description: excel解析
provider: 资产中心-租户
externalDependencyMap:
  maven:
  - groupId: com.netease.lowcode.extension
    artifactId: excel-parser
    version: 1.0.1
structures:
- concept: Structure
  name: ExcelParseResult
  description: excel解析结果
  compilerInfoMap:
    java:
      packageName: com.netease.lowcode.extension.excel.dto
      className: ExcelParseResult
  typeParams:
  properties:
  - concept: StructureProperty
    name: errors
    typeAnnotation:
      concept: TypeAnnotation
      typeKind: generic
      typeNamespace: nasl.collection
      typeName: List
      typeArguments:
      - concept: TypeAnnotation
        typeKind: reference
        typeNamespace: extensions.excel_parser.structures
        typeName: ExcelParseError
        typeArguments:
  - concept: StructureProperty
    name: data
    typeAnnotation:
      concept: TypeAnnotation
      typeKind: generic
      typeNamespace: nasl.collection
      typeName: List
      typeArguments:
      - concept: TypeAnnotation
        typeKind: typeParam
        typeName: T
        typeArguments:
enums: []
logics:
- concept: Logic
  name: parseAllSheet
  description: 解析excel文件
  compilerInfoMap:
    java:
      packageName: com.netease.lowcode.extension.excel
      className: ExcelParser
  typeParams:
  - concept: TypeParam
    name: T
  params:
  - concept: Param
    name: path
    description: 文件路径
    typeAnnotation:
      concept: TypeAnnotation
      typeKind: primitive
      typeNamespace: nasl.core
      typeName: String
      typeArguments:
  - concept: Param
    name: rect
    description: 数据读取区域，可以为空
    typeAnnotation:
      concept: TypeAnnotation
      typeKind: reference
      typeNamespace: extensions.excel_parser.structures
      typeName: ExcelParseRect
      typeArguments:
  returns:
  - concept: Return
    name: result
    typeAnnotation:
      concept: TypeAnnotation
      typeKind: reference
      typeNamespace: extensions.excel_parser.structures
      typeName: ExcelParseResult
      typeArguments:
- viewComponents:
  - name: demo-button
    title: 演示按钮
    description: 请在这里添加描述
    labels: [Form]
    icon: default
    attrs:
    - name: value
        type: string
        default: ""
        description: 需要传入的值
    slots:
    - name: default
        description: 插入文本或 HTML。
    events:
    - name: change
        description: 修改时触发
        params:
        - name: $event.param1
            type: string
            description: 参数1
        - name: $event.param2
            type: number
            description: 参数2

3. 工程规范

(1) 目录结构

client
├─ docs/                            # 示例
│   ├─ blocks.md                    # 使用示例（可视化编辑器必须要用）
│   └─ examples.md                  # 基础示例
├─ api.yaml                         # API 文档（可视化编辑器必须要用）
├─ index.js                         # 组件入口文件
├─ index.vue                        # 组件开发文件（可视化编辑器必须要用）
├─ .npmignore                       # 需要 npm 忽略的文件
├─ package.json                     # npm 包配置
├─ usage.json                       # 低代码平台注册配置文件（自动生成）
└─ ...