---
docStatus: current
---

# 接口与方法

Interface、MethodDefinition、事件和接口容器的公共类型结构。

接口描述可调用能力，不是 JSON 数据。`Interface`、`InterfaceMap`、`InterfaceList` 和 `MethodDefinition` 不能作为普通数据或模型结构化输出类型，包括嵌套在数组和对象中的情况。

## Interface

`methods` 和 `events` 都是必填数组；不用的一项写 `[]`，两项不能同时为空。方法名在方法集合中唯一，事件名在事件集合中唯一；每个签名的参数名也必须唯一。

```json
{
  "@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 错误模型](/integration/cmodel-error-model/)。

## 接口容器与引用值

| 类型              | 类型成员字段             | 用途              |
| --------------- | ------------------ | --------------- |
| `Interface`     | methods / events   | 单个服务所需契约        |
| `InterfaceMap`  | `valueInterface`   | 以业务键绑定同一接口的多个服务 |
| `InterfaceList` | `elementInterface` | 按列表绑定同一接口的多个服务  |

容器成员必须是 Interface，或精确解析为 Interface 的 RefType；容器还可声明 `nullable`。数据字典使用 JSON Schema 的 `additionalProperties`，不能与 `InterfaceMap.valueInterface` 混用。

逻辑服务绑定值由 Runtime 的 ServiceReference 系列协议表达，不放进类型声明。Module 场景的完整声明和绑定步骤见 [ServiceReference](/development/bundle-development/module-development/service-reference/) 与 [InterfaceMap](/development/bundle-development/module-development/interface-map/)。