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

声明 Interface 属性，通过模块属性配置绑定目标服务，并由 Runtime 管理访问关系，插件按新协议解析当前引用的访问信息凭据。

ServiceReference 用于把调用模块的一个 Interface 属性绑定到同一 Runtime 内的目标服务。这里的“绑定”就是设置模块属性值，不存在需要开发者额外调用的服务授权接口。属性写入成功后，Runtime 会根据引用自动生成来源服务到目标服务的访问关系。插件生命周期只接收无凭据的引用描述，业务调用前按需领取当前凭据，完整方式见生命周期与引用协议。

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

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

需要用稳定业务键绑定多个同接口服务时，使用 InterfaceMap 属性和 ServiceReferenceMap 值；不要把多个目标塞进单值 ServiceReference。完整声明、更新和引用描述示例见 InterfaceMap 与 ServiceReferenceMap。

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

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

执行正式命令：

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

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

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

Runtime 自动执行的步骤

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

依赖 Bundle 已安装
  -> 写入调用模块的 ServiceReference 属性
  -> Runtime 校验调用服务、目标服务和属性定义
  -> Runtime 自动生成或更新引用访问关系
  -> 新插件生命周期接收无 token 的 references 描述
  -> 插件在每次业务操作前按授权属性解析当前引用的访问信息凭据
  -> 当前操作通过 Runtime 网关调用目标服务

安装或配置更新中的校验失败会让对应操作失败；引用访问解析失败则停止当前业务操作。开发者不需要在依赖安装与生命周期回调之间手工插入授权操作。

生命周期回调的 references 保留逻辑 ServiceReference 及其 Map/List 结构，不含地址或密钥。插件保存安装定位，在业务调用前按授权属性解析当前引用。响应中的 reference 给出当前目标关系， access[serviceId] 给出当前 Runtime 网关 url 和调用 token，只用于本次操作，不持久化。HTTP 方法的 position: "property" 映射不参与这条链路。完整请求格式和 xiaoxiangService.listManagedShops(params) 的调用方式见模块服务间调用协议。

引用 token 只授权来源服务、目标服务和方法，不携带最终用户。需要代表当前用户调用时，外部后端另外转发 Runtime 在本次业务请求中注入的短期 Actor assertion；该值不是逻辑引用字段，也不通过生命周期保存。见 Runtime 用户委托。

调用模块不得：

在独立后端自行把逻辑 ServiceReference 转换为地址、推导凭据或自行拼接 Runtime 网关地址。
绕过 Runtime 网关，直接调用目标 Hosted Backend 的 Controller 或部署地址。
把生命周期请求中的操作 userId 保存成后续业务调用的固定最终用户身份。
把请求级 Actor assertion 保存到引用配置、数据库、缓存、队列或后台任务。
输出、记录或依赖 token 的内部格式。

CLI 中两个历史参数

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

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

验证清单

依赖 Bundle 和调用 Bundle 已安装到同一 Runtime。
调用模块当前版本声明了目标 Interface 属性。
目标服务完整 businessId 和目标方法存在。
使用 baijimu runtime app properties update 写入逻辑 ServiceReference，确认命令成功。
检查插件收到当前无凭据引用描述；在业务操作前领取该属性的当前引用，验证授权与返回结构，不输出 token。
调用模块后端使用本次领取的引用通过 Runtime 网关调用目标方法。
修改或清除引用后，下一次操作重新解析当前引用的访问信息；撤销后不能再使用旧凭据。

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