---
docStatus: current
---

# 服务引用完整操作示例

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

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

## 选择本次目标

从有权限的 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 文件  |

先查本机命令帮助：

```bash
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. 空引用安装调用方

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

```bash
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`：

```bash
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. 安装提供方并绑定

```bash
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` 的真实完整值：

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

```bash
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` 的真实值：

```bash
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`：

```json
{
  "xiaoxiangService": null
}
```

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

同一套载荷状态见[可下载样例](/examples/bundle-plugin-references/states.json)，
真实验收范围见[引用生命周期验收](/development/lifecycle-plugin-development/verification-and-release/#引用生命周期验收)。
记录每一步实际结果，失败或未执行的步骤保持原状态；文档示例与 SDK 校验通过不代表目标环境业务已通过。