服务引用完整操作示例

使用正式 CLI 验证空引用安装、绑定、换绑、清空和再绑定，分别确认配置与真实业务结果。

本例操作同一个调用方 Module 的 xiaoxiangService 单值 Interface 属性。定义中没有默认值，即使 required: true，也允许先安装、后绑定。若 Bundle 使用生命周期插件，保持 FAIL_FAST，插件按未绑定引用与失败策略处理当前配置。

选择本次目标

从有权限的 Bundle 目录选择调用方和提供方的精确已发布版本，以及目标工作区、Runtime 和各自来源环境。以下 $... 变量由本次目录查询结果填写，不使用示例 ID，不选择 latest，也不拼接 businessId。在隔离验收 Runtime 执行完整流程；它会安装资源并修改所选属性。

变量	来源
`WORKSPACE_ID`、`RUNTIME_ID`	本次获准的工作区与 Application Runtime
`CALLER_BUNDLE_ID`、`CALLER_VERSION_ID`、`CALLER_ENVIRONMENT_KEY`	调用方精确 Bundle 版本及来源
`PROVIDER_BUNDLE_ID`、`PROVIDER_VERSION_ID`、`PROVIDER_ENVIRONMENT_KEY`	提供方精确 Bundle 版本及来源
`CALLER_BUSINESS_ID`	安装后从调用方服务目录选择的真实服务
`FIRST_TARGET_ID`、`SECOND_TARGET_ID`	同一 Runtime 中两个满足业务需要、结果可区分的真实提供方服务
`READ_METHOD`、`READ_PARAMS_FILE`	调用方中实际依赖该引用的只读方法及符合其合同的参数 JSON 文件

先查本机命令帮助：

baijimu bundle install --help
baijimu runtime services list --help
baijimu runtime service get --help
baijimu runtime app properties update --help
baijimu runtime service call --help

1. 空引用安装调用方

在提供方尚未安装、调用方引用尚未配置时安装所选精确版本：

baijimu bundle install "$CALLER_BUNDLE_ID" \
  --workspace-id "$WORKSPACE_ID" \
  --application-runtime-id "$RUNTIME_ID" \
  --version-id "$CALLER_VERSION_ID"

baijimu runtime services list \
  --workspace-id "$WORKSPACE_ID" \
  --application-runtime-id "$RUNTIME_ID" \
  --environment-key "$CALLER_ENVIRONMENT_KEY" \
  --bundle-id "$CALLER_BUNDLE_ID" --json

预期安装成功，Owner 服务目录返回调用方。按精确资源身份选择 CALLER_BUSINESS_ID。若安装预览要求确认未经市场验证的精确分发版本，先核对该预览，再按本机帮助显式确认。这项确认不提供服务引用，也不改变插件阶段校验。

从服务目录查询调用方方法合同，选择实际依赖该属性的只读业务入口，准备 READ_PARAMS_FILE：

baijimu runtime service get "$CALLER_BUSINESS_ID" \
  --workspace-id "$WORKSPACE_ID" \
  --application-runtime-id "$RUNTIME_ID" --method "$READ_METHOD" --json

baijimu runtime service call "$CALLER_BUSINESS_ID" "$READ_METHOD" \
  --workspace-id "$WORKSPACE_ID" \
  --application-runtime-id "$RUNTIME_ID" \
  --params "@$READ_PARAMS_FILE" --json

此时相关业务调用应明确返回未绑定，不能因此把定义安装判成失败。错误码由该业务方法的公开合同定义。

2. 安装提供方并绑定

baijimu bundle install "$PROVIDER_BUNDLE_ID" \
  --workspace-id "$WORKSPACE_ID" \
  --application-runtime-id "$RUNTIME_ID" \
  --version-id "$PROVIDER_VERSION_ID"

baijimu runtime services list \
  --workspace-id "$WORKSPACE_ID" \
  --application-runtime-id "$RUNTIME_ID" \
  --environment-key "$PROVIDER_ENVIRONMENT_KEY" \
  --bundle-id "$PROVIDER_BUNDLE_ID" --json

从目录取得 FIRST_TARGET_ID 和 SECOND_TARGET_ID，分别读取相关方法定义，确认参数和返回满足业务需要。本例的两个目标须有可区分的只读结果；如果所选 Bundle 只提供一个目标，先按其公开流程准备第二个验收目标。平台绑定不替使用者比较提供方实际方法，不能把绑定成功当成接口兼容证明。

保存 bind-first.json，将其中占位值替换为 FIRST_TARGET_ID 的真实完整值：

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

baijimu runtime app properties update "$CALLER_BUSINESS_ID" \
  --workspace-id "$WORKSPACE_ID" \
  --application-runtime-id "$RUNTIME_ID" --properties @bind-first.json

baijimu runtime service call "$CALLER_BUSINESS_ID" "$READ_METHOD" \
  --workspace-id "$WORKSPACE_ID" \
  --application-runtime-id "$RUNTIME_ID" --params "@$READ_PARAMS_FILE" --json

分别确认属性命令、插件配置通知和真实业务结果成功；业务结果应来自第一个目标。其他授权引用保持未绑定，不要求一次绑定全部属性。

3. 换绑第二个目标

复制 bind-first.json 为 bind-second.json，仅把 serviceId 改成 SECOND_TARGET_ID 的真实值：

baijimu runtime app properties update "$CALLER_BUSINESS_ID" \
  --workspace-id "$WORKSPACE_ID" \
  --application-runtime-id "$RUNTIME_ID" --properties @bind-second.json

baijimu runtime service call "$CALLER_BUSINESS_ID" "$READ_METHOD" \
  --workspace-id "$WORKSPACE_ID" \
  --application-runtime-id "$RUNTIME_ID" --params "@$READ_PARAMS_FILE" --json

预期新调用返回第二个目标的业务结果。只看属性命令成功或 HTTP 200 不足以证明切换。

4. 清空引用

保存 clear-reference.json：

{
  "xiaoxiangService": null
}

baijimu runtime app properties update "$CALLER_BUSINESS_ID" \
  --workspace-id "$WORKSPACE_ID" \
  --application-runtime-id "$RUNTIME_ID" --properties @clear-reference.json

baijimu runtime service call "$CALLER_BUSINESS_ID" "$READ_METHOD" \
  --workspace-id "$WORKSPACE_ID" \
  --application-runtime-id "$RUNTIME_ID" --params "@$READ_PARAMS_FILE" --json

预期配置与通知成功，调用方和插件业务实例保留；相关调用明确返回未绑定，第二个目标不再收到调用。部分更新省略该属性只会保留原值，不能用省略代替显式清空。

5. 再绑定与插件验收

再次执行步骤 2 的属性命令和只读调用，预期恢复第一个目标的业务结果，插件不重复创建实例。插件开发者还须在隔离测试中重放相同安装、操作、阶段和执行顺序的通知，确认幂等、迟到请求隔离、错误身份和越权输入拒绝。业务调用不能为重试临时解析引用或领取凭据。

同一套载荷状态见可下载样例，真实验收范围见引用生命周期验收。记录每一步实际结果，失败或未执行的步骤保持原状态；文档示例与 SDK 校验通过不代表目标环境业务已通过。