Ballerina中map<json>参数传入时出现IncompatibleArguments错误的解决方法

问题背景 #

我们在Ballerina中定义了以下record类型与constructGraphQLQuery函数：

public type Field record {|
    string name;
    FieldType 'type;
|};

public type QueryType record {|
    string name;
    string description?;
    Field[] args;
|};

public type ObjectType record {|
    string name;
    Field[] fields;
|};

public type ConstructQueryInput record {|
    string task;
    QueryType querySchema;
    ObjectType[] objectTypeSchemas;
|};

public function constructGraphQLQuery(ConstructQueryInput input) returns json|error {
    // 函数实现省略
    return {"output": "successfully executed function"};
}

当通过function:call调用该函数时：

any|error observation = function:call(constructGraphQLQuery, input); 

若传入的input类型为map<json> & readonly，且其中querySchema的可选字段description被显式设为null（示例输入如下），会触发IncompatibleArguments错误：

{
    "objectTypeSchemas": [
        {
            "name": "",
            "fields": [
                {
                    "name": "",
                    "type": "TWO"
                }
            ]
        }
    ],
    "task": "test",
    "querySchema": {
        "name": "",
        "description": null, // 可选字段设为NULL
        "args": [
            {
                "name": "",
                "type": "TWO"
            }
        ]
    }
}

问题原因 #

Ballerina中，QueryType里的description?属于可选字段，其类型等价于string?（即string | ()）：它允许两种情况——要么字段完全不存在（缺失状态），要么字段存在且值为非null的string。但显式传入description: null违反了这个类型约束，导致map<json>无法转换为ConstructQueryInput类型，触发参数不兼容错误。

解决方案 #

方案1：移除输入中的description: null字段 #

如果业务逻辑不需要显式传递null，直接删除输入里的description字段即可，此时可选字段处于缺失状态，符合类型约束：

{
    "objectTypeSchemas": [
        {
            "name": "",
            "fields": [
                {
                    "name": "",
                    "type": "TWO"
                }
            ]
        }
    ],
    "task": "test",
    "querySchema": {
        "name": "",
        "args": [
            {
                "name": "",
                "type": "TWO"
            }
        ]
    }
}

方案2：修改QueryType定义，允许description为null #

如果业务需要支持显式传入null作为description的值，可修改QueryType的字段类型，允许字段存在时为string或null：

public type QueryType record {|
    string name;
    string|null description?; // 允许字段缺失，或存在时为string/null
    Field[] args;
|};

修改后，显式传入description: null会符合类型约束，类型检查可正常通过。

方案3：调用前手动处理输入中的null值 #

若无法修改输入数据和record定义，可在调用函数前将description: null转换为字段缺失的状态：

// 将只读map转为可变map以修改内容
map<json> mutableInput = input.clone();

// 检查并移除querySchema中值为null的description字段
if mutableInput["querySchema"] is map<json> {
    map<json> querySchema = mutableInput["querySchema"] as map<json>;
    if querySchema.hasKey("description") && querySchema["description"] is null {
        querySchema.remove("description");
    }
}

// 使用处理后的输入调用函数
any|error observation = function:call(constructGraphQLQuery, mutableInput);

内容的提问来源于stack exchange，提问作者Kavindu Gimhan Zoysa