框架会扫描注册的组件，根据以下约定自动生成组件表单配置，用于可视化编辑器渲染组件配置表单。

自动生成规则

1. 根据组件结构体名，生成组件名称（首字母小写）
2. 根据组件结构体的 Config 字段定义的结构体，生成表单项（字段名首字母小写或通过 json tag 自定义）
3. 根据 New() 方法返回的组件实例 Config 字段生成表单项默认值
4. 根据组件包名生成分类。标准分类有：transform、action、filter、external、flow、common、ci、ai、aiot
5. Endpoint 组件 Type 以 endpoint/ 作为前缀

Config 结构体 Tag

表单项的显示名称、描述、校验规则等通过 Config 结构体字段的 tag 定义：

type RestApiCallNodeConfiguration struct {
    RestEndpointUrlPattern string            `json:"restEndpointUrlPattern" label:"请求地址" desc:"REST API 地址，支持 ${metadata.key} 表达式" required:"true"`
    RequestMethod          string            `json:"requestMethod" label:"请求方法" desc:"HTTP 请求方法" component:"{\"type\":\"select\",\"options\":[{\"label\":\"GET\",\"value\":\"GET\"},{\"label\":\"POST\",\"value\":\"POST\"}]}"`
    Headers                map[string]string `json:"headers" label:"请求头" desc:"自定义 HTTP 请求头"`
    ReadTimeoutMs          int               `json:"readTimeoutMs" label:"超时时间(ms)" desc:"请求超时时间，默认 2000ms"`
    InsecureSkipVerify     bool              `json:"insecureSkipVerify" label:"跳过TLS验证" desc:"是否跳过 HTTPS 证书验证"`
}

支持的 Tag 列表

Tag	说明	示例
json	字段名，对应 JSON 配置中的 key	json:"delayMs"
label	显示名称，在编辑器中展示	label:"延迟时间(ms)"
desc	字段描述，作为提示信息	desc:"延迟时间，单位毫秒"
required	是否必填	required:"true"
rules	前端校验规则，JSON 数组格式	rules:"[{\"required\":true,\"message\":\"不能为空\"}]"
validate	校验规则（已废弃，使用 rules）	validate:"required"
component	UI 组件类型和配置，JSON 格式	component:"{\"type\":\"select\",\"options\":[...]}"
ref	共享节点池关联标识	ref:"primary" 或 ref:"shared"
deprecated	标记字段已废弃	deprecated:"true"

字段类型映射

Config 结构体中 Go 字段类型会自动映射为表单字段类型：

Go 类型	表单 type	说明
string	string	文本输入
bool	bool	开关/复选框
int, int8...int64	int	数字输入
uint, uint8...uint64	uint	无符号数字输入
float32, float64	float	浮点数输入
[]T	array	数组编辑器
map[string]T	map	键值对编辑器
struct	struct	嵌套对象，递归提取子字段

component tag — UI 组件类型

通过 component tag 可以覆盖默认的 UI 渲染方式：

select（下拉选择）

RequestMethod string `json:"requestMethod" label:"请求方法"
    component:"{\"type\":\"select\",\"options\":[{\"label\":\"GET\",\"value\":\"GET\"},{\"label\":\"POST\",\"value\":\"POST\"},{\"label\":\"PUT\",\"value\":\"PUT\"},{\"label\":\"DELETE\",\"value\":\"DELETE\"}]}"`

codeEditor（代码编辑器）

JsScript string `json:"jsScript" label:"脚本"
    component:"{\"type\":\"codeEditor\",\"language\":\"javascript\"}"`

textarea（多行文本）

Content string `json:"content" label:"内容"
    component:"{\"type\":\"textarea\"}"`

number（数字输入，带步长）

Port int `json:"port" label:"端口"
    component:"{\"type\":\"number\",\"step\":1,\"min\":1,\"max\":65535}"`

ref tag — 共享节点池

对于支持共享节点池的组件（如 mqttClient、dbClient），通过 ref tag 标识字段与共享节点的关系：

type MqttClientNodeConfiguration struct {
    Server   string `json:"server" label:"服务器地址" required:"true" ref:"primary"` // ref:// 引用字段
    Username string `json:"username" label:"用户名" ref:"shared"`                   // 由共享节点提供
    Password string `json:"password" label:"密码" ref:"shared"`                   // 由共享节点提供
    Topic    string `json:"topic" label:"Topic" required:"true"`                  // 组件自身字段，始终显示
}

ref 值	含义
"primary"	共享节点引用字段（如服务器地址），使用 ref:// 时只需填此项
"shared"	由共享节点提供的字段，使用 ref:// 时隐藏
不设置	组件自身的业务字段，始终显示

可选接口覆盖

组件可以通过实现以下可选接口，覆盖自动生成的表单信息：

ComponentDefGetter — 完全自定义表单

type ComponentDefGetter interface {
    Def() ComponentForm
}

返回的 ComponentForm 中非空字段会覆盖自动生成的值，空字段保留自动生成的值。

示例——自定义 RelationTypes 和描述：

func (x *IteratorNode) Def() types.ComponentForm {
    return types.ComponentForm{
        Desc:          "遍历数组/对象的每个元素，支持条件过滤",
        RelationTypes: &[]string{types.Success, types.Failure, types.True, types.False},
    }
}

CategoryGetter — 自定义分类

type CategoryGetter interface {
    Category() string
}

DescGetter — 自定义描述

type DescGetter interface {
    Desc() string
}

Endpoint 组件约定

Endpoint 组件在以上约定基础上，还有额外结构：

ComponentKind

Endpoint 组件的 ComponentKind 自动设为 "ec"（普通组件为 "nc"，动态组件为 "dc"）。

RouterForm

Endpoint 组件通过 Def() 返回 RouterForm，定义路由器的表单配置：

普通路由（需配置路径）——如 HTTP、MQTT：

func (rest *Rest) Def() types.ComponentForm {
    return types.ComponentForm{
        Desc: "HTTP/REST 服务器端点",
        RouterForm: &types.RouterForm{
            From: &types.RouterFormField{
                Path: types.ComponentFormField{
                    Name: "path", Type: "string", Label: "路径",
                    Desc: "HTTP 路由路径，如 /api/device/{deviceId}", Required: true,
                },
            },
        },
    }
}

隐藏路由（自动生成默认路由）——如定时调度：

func (schedule *Schedule) Def() types.ComponentForm {
    return types.ComponentForm{
        Desc: "定时调度端点",
        RouterForm: &types.RouterForm{
            Hide: true, // 自动生成 from.path="*"，用户无需配置
        },
    }
}

RelationTypes

Endpoint 组件的 RelationTypes 自动设为空数组（不显示连线关系）。

DynamicNode — JSON Schema 定义表单

动态组件（通过 DSL 创建，无需编写 Go 代码）使用 additionalInfo.inputSchema 定义表单字段，格式遵循 JSON Schema：

{
  "additionalInfo": {
    "inputSchema": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "title": "请求地址",
          "description": "API 地址",
          "default": "http://localhost:8080"
        },
        "method": {
          "type": "string",
          "title": "请求方法",
          "enum": ["GET", "POST", "PUT", "DELETE"]
        },
        "timeout": {
          "type": "integer",
          "title": "超时时间(ms)",
          "default": 5000,
          "minimum": 100
        }
      },
      "required": ["url"]
    }
  }
}

JSON Schema 中的 title 映射为 label，description 映射为 desc，default 映射为 defaultValue，enum 自动渲染为下拉选择。

完整示例

组件定义：

package transform

type JsTransformNodeConfiguration struct {
    JsScript string
}

type JsTransformNode struct {
    Config   JsTransformNodeConfiguration
    jsEngine types.JsEngine
}

func (x *JsTransformNode) Type() string {
    return "jsTransform"
}

func (x *JsTransformNode) New() types.Node {
    return &JsTransformNode{Config: JsTransformNodeConfiguration{
        JsScript: "return {'msg':msg,'metadata':metadata,'msgType':msgType};",
    }}
}

自动生成的组件配置表单：

{
    "type": "jsTransform",
    "category": "transform",
    "fields": [
        {
            "name": "jsScript",
            "type": "string",
            "defaultValue": "return {'msg':msg,'metadata':metadata,'msgType':msgType};",
            "label": "",
            "desc": ""
        }
    ],
    "label": "JsTransformNode",
    "desc": "",
    "icon": "",
    "relationTypes": ["Success", "Failure"]
}

相关文档

• 获取组件配置表单 — ComponentForm 和 ComponentFormField 完整字段说明
• 自定义组件 — 开发自定义组件的完整指南
• RuleGo-Editor — 可视化编辑器