---
docStatus: current
---

# Bundle 与 Module 属性

使用一致的属性声明、类型化属性值和可选的自动绑定。

本页适用于已支持统一属性协议的目标环境。CLI 升级不会单独启用 Runtime 自动绑定；使用前确认目标环境已完成该能力的交付。

Bundle 和 Module 使用相同的声明结构，但自动绑定的缺省规则不同：`propertyDefinition` 声明属性，Runtime 中的 `properties` 保存赋值。
Bundle 在数据库 BundleDefinition 的根级 `propertyDefinition` 中声明；Module 在 `module.json` 的
`propertyDefinition` 中声明。Bundle 定义使用 `23.0.0`，编辑与发布共用一份结构，见[定义流程](/development/bundle-development/manifest/)。

## 声明

每项包含 `name` 和 `type`，可声明 `description`、`required`、`isSensitive`、`defaultValue`、
`readOnly`、`isExternalManaged` 和 `autoBinding`。类型使用同一套[类型系统](/development/type-system/interfaces/)。
属性名在所在对象中唯一。默认值是 JSON 字面值，例如 `false`、`0` 或 `null`，不增加 `value` 包装。
只有 `JsonSchema` 数据属性允许默认值；引用属性必须省略 `defaultValue`。

下面的声明既可用于 Bundle，也可用于 Module：

```json
{
  "propertyDefinition": [
    {
      "name": "enabled",
      "type": { "@type": "JsonSchema", "schema": { "type": "boolean" } },
      "defaultValue": false
    },
    {
      "name": "providers",
      "type": {
        "@type": "InterfaceMap",
        "valueInterface": {
          "@type": "Interface",
          "methods": [],
          "events": [{ "name": "Changed", "paramDefinitions": [] }]
        }
      },
      "autoBinding": true
    }
  ]
}
```

接口应声明调用方需要的方法和事件；上例发现支持 `Changed` 事件的提供方。

## 自动绑定

`autoBinding` 可省略，也可明确声明 `true` 或 `false`。Module 的 `Interface`、`InterfaceMap`
（包括指向接口的精确 `RefType`）省略时默认自动绑定；显式 `false` 关闭默认自动绑定。
Bundle 参数省略时仍默认手动，需要 `true` 才启用自动绑定。
自动绑定不能用于普通数据、List 或方法属性，也不能与 `isExternalManaged: true` 同时声明。
普通值属性的默认规则不变。

实例已有的显式手动目标、`autoBinding: false` 和明确清空配置优先于定义默认；
未配置的 Module 引用才继承自动默认。历史不可变定义不改写，已有手动选择不会在升级后被自动替换。

发现范围固定为同一个 Application Runtime，没有 `scope` 配置。候选来自 Runtime Owner 当前资源及其精确编译声明，
不由 Bundle 安装记录决定；匹配使用声明的接口契约。单值零匹配保持未绑定，唯一匹配时绑定，多匹配明确报冲突；
Map 收集全部匹配，键使用完整 `ResourceLocator`，避免不同 Bundle 的同名资源互相覆盖。

已生效的自动值由平台维护。安装后可在属性配置中切换自动／手动；生命周期输出不能暗中改变已生效的自动策略。资源安装、升级、卸载导致候选变化时，平台重新计算，
并经正常配置交付流程更新消费者；失败会保留明确的配置失败结果。不会自动安装提供方或授予额外业务权限。

## Bundle 属性传递给资源

`configuration.resourceBindings` 将 Bundle 属性传给已声明资源的可配置字段。数据和引用都使用 `Expression` 来源，
表达式结果按目标字段类型还原，引用完整保留类型和 `ResourceLocator`；同一个 Bundle 属性可以供多个资源消费。

```json
{
  "configuration": {
    "resourceBindings": [
      {
        "resourceType": "MODULE",
        "resourceKey": "<清单中的 Module resourceKey>",
        "fields": {
          "providers": { "@type": "Expression", "expression": "bundle.properties.providers" },
          "enabled": { "@type": "Expression", "expression": "bundle.properties.enabled" }
        }
      }
    ]
  }
}
```

表达式读取 `bundle.properties` 中的数据属性和类型化引用属性。引用在表达式中是不透明的类型化值，
Map 和 List 保留引用元素的类型；普通 JSON 不能伪造引用，引用也不能被当作数据输出。值来源只有 `Expression` 和 `Data` 两种。
常量数据使用 `{"@type":"Data","value":false}`。目标字段的类型、只读和敏感策略仍由资源 Owner 校验；
敏感属性不能流入普通公开字段。

手动引用、运行时调用和凭据交付见[ServiceReference](/development/bundle-development/module-development/service-reference/)。

## 配置与应用

Bundle 参数和 Module 属性使用相同的属性配置结构。读取、保存和应用分别执行：

- Bundle 参数：`GET/PATCH /api/application-runtimes/{runtimeId}/configuration/parameters?environmentKey={来源环境}&bundleId={Bundle}`。
- Module 属性：`GET/PATCH /api/application-runtimes/{runtimeId}/configuration/resources?resourceLocator={完整资源Locator}`。
- 应用配置：`POST /api/application-runtimes/{runtimeId}/configuration/apply?environmentKey={来源环境}&bundleId={Bundle}`。

读取响应的 `ETag` 是当前配置修订。写入和应用使用该值作为 `If-Match`；写入正文直接是属性映射，不包含 `changes/action`、定义版本或额外的配置来源版本。
保存只修改草稿，应用成功才切换运行值与已生效绑定策略。应用失败保留草稿和原策略，通过普通应用重试。

应用始终以当前 Runtime 中来源身份明确的完整 Bundle 为单位。请求正文为 `{}`，不接受资源或字段 `selection`，CLI 不提供 `--selection`。可以分别编辑、保存参数和资源属性；执行应用时，当前 Bundle 的全部已保存配置一起生效。

取消引用后，通过同一个 Bundle 应用命令解除运行时绑定；重复应用或重建不会恢复已经取消的引用。其他 Bundle 的草稿和运行配置不受本次应用影响。

## 安装后切换绑定方式

Bundle 和 Module 的 `Interface`、`InterfaceMap` 属性可通过独立的 `autoBinding` 字段选择绑定策略。它属于属性配置，不是属性值的类型；自动模式不能同时提供 `value`。

```json
{
  "providers": { "autoBinding": true }
}
```

手动绑定使用 `value` 中的具体资源引用：

```json
{
  "service": {
    "autoBinding": false,
    "value": {
      "@type": "ServiceReference",
      "resourceLocator": "<环境>/<Bundle>/MODULE/<资源key>"
    }
  }
}
```

- **继承默认**：删除整个属性覆盖，PATCH 中写 `"service": null`。默认模式取自属性定义，读取响应的 `automaticDefaults` 可用于展示。
- **自动绑定**：`{ "autoBinding": true }` 保留发现意图，应用时依据当前 Runtime Owner 发现目标。
- **手动绑定**：`{ "autoBinding": false, "value": ... }`；配置中省略 `autoBinding` 同样表示手动。
- **手动未绑定**：`{ "autoBinding": false }` 或 `{}`，显式抑制默认自动绑定。
- **字面 null**：`{ "value": { "@type": "Data", "value": null } }` 是数据值，与删除覆盖、手动未绑定不同。

单个属性对象完整替换该属性配置；正文中未出现的其他属性保持原值。`autoBinding` 仅适用于解析后的 `Interface`、`InterfaceMap`，不适用于普通数据或接口列表。

未应用的自动草稿不会提前启用自动发现；未应用的手动草稿不会停止已有自动发现。单值首次开启时如有多个候选，开启失败；已生效自动模式遇到候选歧义时记录失败，并在后续真实资源变化时重新发现。

Bundle 自动属性可通过 `Expression` 供多个 Module 消费。成功应用 Module 字段的直接手动覆盖后，该字段按自己的策略执行。作者声明的 `readOnly`、`isExternalManaged`、原生凭据保护和授权继续生效。

历史记录保留审计原件。恢复支持的历史配置会建立新修订，自动值在应用时按当前资源重新发现，不恢复失效的执行地址。