Bundle 与 Module 属性

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

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

声明

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

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

{
  "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 属性可以供多个资源消费。

{
  "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。

配置与应用

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、定义版本或额外的配置来源版本。保存只修改草稿，应用成功才切换运行值与已生效绑定策略。应用失败保留草稿和原策略，通过普通应用重试。

安装后切换绑定方式

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

{
  "providers": { "autoBinding": true }
}

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

{
  "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、原生凭据保护和授权继续生效。

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

声明

自动绑定

Bundle 属性传递给资源

配置与应用

安装后切换绑定方式

本页内容