ServiceReference 声明、绑定与运行时交付

声明 Interface 属性，通过模块属性配置绑定目标服务，并由 Runtime 自动生成访问凭据和生命周期回调。

ServiceReference 用于把调用模块的一个 Interface 属性绑定到同一 Runtime 内的目标服务。这里的“绑定”就是设置模块属性值，不存在需要开发者额外调用的服务授权接口。属性写入成功后，Runtime 会根据引用自动生成来源服务到目标服务的访问关系和不透明 token，并在生命周期回调中交付可调用引用。

模块属性是唯一的绑定源事实

把 Interface 属性设置为 {"@type":"ServiceReference","serviceId":"完整 businessId"} 即完成绑定。Bundle dependencies 只确保目标 Bundle 先进入安装闭包，不设置属性，也不代替绑定。

声明 Interface 属性

调用方模块在 module.json 的 propertyDefinition 中声明 Interface 类型属性。接口中的方法定义是调用方编译期的期望契约；真正调用前仍应从目标 Runtime 服务回读当前方法和 paramDefinitions。

{
  "propertyDefinition": [
    {
      "name": "xiaoxiangService",
      "type": {
        "@type": "Interface",
        "name": "XiaoxiangService",
        "methods": [
          {
            "name": "listManagedShops",
            "returnType": {
              "@type": "DataType",
              "type": "object",
              "nullable": false
            },
            "paramDefinitions": [
              {
                "name": "params",
                "type": {
                  "@type": "DataType",
                  "type": "object",
                  "nullable": false
                }
              }
            ]
          }
        ]
      },
      "required": true,
      "defaultValue": "{\"@type\":\"ServiceReference\",\"serviceId\":\"<targetBusinessId>\"}"
    }
  ]
}

defaultValue 中的 JSON 字符串会在模块版本编译时变成类型化属性值，因此可以在安装时直接完成默认绑定。如果目标服务由部署环境或安装结果决定，不要把可变 businessId 写死在源码中；安装后使用下面的模块属性更新命令设置实际值。

逻辑属性值固定使用：

{
  "@type": "ServiceReference",
  "serviceId": "<targetBusinessId>"
}

serviceId 必须是目标服务完整的 businessId，不是模块名、Bundle 名、方法名、Hosted Backend 地址或调用方自行拼接的 URL。

安装后手动绑定或修改

CLI 0.2.8 起提供正式的默认 Runtime 模块属性命令。先把需要部分更新的属性保存为 properties.json；文件只包含属性对象，不包含工作区、调用服务或接口 URL：

{
  "xiaoxiangService": {
    "@type": "ServiceReference",
    "serviceId": "<targetBusinessId>"
  }
}

执行正式命令：

baijimu runtime app properties update \
  <workspaceId> \
  <callerBusinessId> \
  --properties @properties.json

<workspaceId> 决定目标工作区，<callerBusinessId> 是调用模块安装后的完整服务标识。
--properties 接受内联 JSON 对象或 @文件；这是部分更新，未出现的模块属性保持不变。
属性名必须已经存在于当前不可变模块版本的 propertyDefinition 中。该命令只改属性值，不修改属性定义。
目标 serviceId 必须在同一 Runtime 中可解析；解析或访问关系生成失败时，本次配置更新失败。
CLI 负责平台接口路径、工作区凭据和请求结构。开发者不得改用 baijimu api 拼接内部路径。

设置属性就是绑定；这也是手动修改绑定的正式操作，不需要另一套“ServiceReference 授权”命令或接口。

Runtime 自动执行的步骤

安装或属性更新会按同一个源事实收敛：

依赖 Bundle 已安装
  -> 写入调用模块的 ServiceReference 属性
  -> Runtime 校验调用服务、目标服务和属性定义
  -> Runtime 自动生成或更新引用访问关系和 token
  -> 安装触发 BEFORE_DEPLOY；属性修改触发 ON_CONFIG_UPDATE
  -> 生命周期 Endpoint 收到 ExternalServiceReference
  -> 调用模块的独立后端保存整组 url、serviceId、token

任一步失败都会让对应安装或配置更新失败；开发者不需要在依赖安装与生命周期 Hook 之间手工插入授权操作。

生命周期回调中的逻辑值会被展开为 ExternalServiceReference，包含 Runtime 网关 url、目标 serviceId 和不透明 token。HTTP 方法的 position: "property" 映射不参与这条链路。完整请求格式和 xiaoxiangService.listManagedShops(params) 的调用方式见模块服务间调用协议。

调用模块不得：

在独立后端解析逻辑 ServiceReference、推导凭据或自行拼接 Runtime 网关地址。
绕过 Runtime 网关，直接调用目标 Hosted Backend 的 Controller 或部署地址。
把生命周期请求中的操作 userId 保存成后续业务调用的固定最终用户身份。
输出、记录或依赖 token 的内部格式。

CLI 中两个历史参数

CLI 0.2.8 的 baijimu bundle module create --help 仍显示 --module-dependencies 和 --dependency-definition，因此文档不宣称它们已从 CLI 删除。

这两个模块创建输入既不能替代 Bundle Manifest dependencies，也不能替代上面的模块属性设置接口。

验证清单

依赖 Bundle 和调用 Bundle 已安装到同一 Runtime。
调用模块当前版本声明了目标 Interface 属性。
目标服务完整 businessId 和目标方法存在。
使用 baijimu runtime app properties update 写入逻辑 ServiceReference，确认命令成功。
安装时检查 BEFORE_DEPLOY，安装后修改时检查 ON_CONFIG_UPDATE；只确认展开后的字段存在，不输出 token。
调用模块后端使用下发引用通过 Runtime 网关调用目标方法。
修改或清除引用后，后端停止使用旧引用并清理本地副本。

不得为了验证而拼接内部网关地址、复用非公开凭据或直连目标 Hosted Backend。