接口与方法
Interface、MethodDefinition、事件和接口容器的公共类型结构。
接口描述可调用能力，不是 JSON 数据。Interface、InterfaceMap、InterfaceList 和 MethodDefinition 不能作为普通数据或模型结构化输出类型，包括嵌套在数组和对象中的情况。
Interface
methods 和 events 都是必填数组；不用的一项写 []，两项不能同时为空。方法名在方法集合中唯一，事件名在事件集合中唯一；每个签名的参数名也必须唯一。
{
"@type": "Interface",
"name": "ProductProvider",
"methods": [
{
"@type": "MethodDefinition",
"name": "find",
"async": false,
"param_definitions": [
{
"name": "sku",
"type": {
"@type": "JsonSchema",
"schema": {
"type": "string"
}
},
"required": true
}
],
"return_type": {
"@type": "JsonSchema",
"schema": {
"type": [
"object",
"null"
]
}
},
"error_type_map": {}
}
],
"events": [
{
"name": "changed",
"paramDefinitions": [
{
"name": "sku",
"type": {
"@type": "JsonSchema",
"schema": {
"type": "string"
}
},
"required": true
}
]
}
]
}name、description 和 nullable 是 Interface 的可选字段。methods 不能写成以方法名为键的对象；每个方法在自己的 name 中声明名称。事件的参数字段是 paramDefinitions。
MethodDefinition
| 字段 | 规则 |
|---|---|
@type | 独立作为 Type 时为 MethodDefinition；Interface 的方法数组项解析时也允许省略此标签 |
name | 必填方法名 |
param_definitions | 必填参数数组，无参数用 []；参数使用 name、type、可选 description、required、default_value |
return_type | 必填完整 Type，不能用字符串 unknown 代替 |
async | 必填布尔值，属于签名兼容性，不是自动推断的实现细节 |
error_type_map | 可选，错误码到数据 Type 的映射；未声明与显式空映射在序列化中保留区别 |
description、nullable | 可选说明和类型可空声明 |
方法字段也接受 paramDefinitions、returnType、errorTypeMap 作为输入别名；规范序列化使用 snake_case。字段命名以各结构为准，不能把方法字段规则套用到事件上。
error_type_map 未声明表示没有提供错误映射，显式 {} 表示提供了空映射；都不能被理解为允许任意业务错误。实现声明的每个错误码都必须在调用方契约中存在，且对应错误类型兼容。不要为统一格式而批量补空映射。响应 envelope 与错误码的传输方式见 CModel 错误模型。
接口容器与引用值
| 类型 | 类型成员字段 | 用途 |
|---|---|---|
Interface | methods / events | 单个服务所需契约 |
InterfaceMap | valueInterface | 以业务键绑定同一接口的多个服务 |
InterfaceList | elementInterface | 按列表绑定同一接口的多个服务 |
容器成员必须是 Interface，或精确解析为 Interface 的 RefType；容器还可声明 nullable。数据字典使用 JSON Schema 的 additionalProperties，不能与 InterfaceMap.valueInterface 混用。
逻辑服务绑定值由 Runtime 的 ServiceReference 系列协议表达，不放进类型声明。Module 场景的完整声明和绑定步骤见 ServiceReference 与 InterfaceMap。