百积木文档
开发指南Bundle 生命周期插件开发

验证与发布 Bundle 插件

验证协议、操作恢复、资源归属、引用撤销和实际安装效果。

协议状态(2026-10-21):资源凭据领取与生命周期通知是已确认、尚未实现和定版的目标设计。插件在 AFTER_RESOURCES 按安装与资源主动领取自己的入口和凭据,回调不携带秘密;配置变化仍走生命周期通知,业务请求不解析引用。Backend 保留插件身份关联,轮换只撤销自己的旧凭据;ACS 不改,不做多插件协调。下文版本化示例保留用于现有协议维护,不能把新 API 字段发送给旧接收端。

插件后端发布、目录注册、Bundle 版本创建与目标安装是不同结果。全部完成并验证实际业务效果后,才能确认可用。

首次接入验收

按首次接入流程与验收记录后端部署、插件接入、凭据恢复与安全、Bundle 业务四层证据。 确认授权已消费、无引导配置重启后代次仍有效、线上轮换成功和错误凭据被拒绝。 响应丢失、并发交换、过期与撤销在隔离环境验证,不随意中断生产授权。 未执行的层级明确标为未验收;健康检查或目录记录存在均不能替代这些结果。

先确认接入方式

直接接入时,协议 Endpoint 由业务插件服务提供。采用 独立 Adapter Hosted Service时, 协议与凭据测试针对 Adapter;业务归属、数据库事务、幂等和执行顺序测试针对业务 Hosted Service。 还需验证 Module 到 Adapter API、Adapter 到业务回调、回调内引用解析的授权、超时与响应丢失。 使用方 Runtime、提供方 Runtime 与 Adapter Environment 的身份分别记录,不得互相替代。 Hosted Service 健康、Module 编译、Bundle 安装和插件接入成功需要分别取证。

协议验证

  1. 按权威规范和实际注册声明选择公开 SDK Codec,验证请求、响应及 Bundle 授权;业务 payload 不能混入旧的 contractVersion。
  2. 验证安装、操作、阶段、执行顺序与响应关联;按权威规范测试顶层未知字段被拒绝、嵌套元数据按 SDK 处理,错误类型、缺失字段、未登记版本和越权资源仍被拒绝。
  3. 验证每个阶段携带原安装人的 installation.installedBy,升级操作者和资源执行用户不能覆盖该值;DETACH 重试保留原安装快照。
  4. 验证 CModel 只有 contractVersion、errorCode、data,并测试真实 HTTP Endpoint 的成功与错误分支。
  5. 验证逻辑引用包括 Map/List 都不带地址密钥,业务调用材料来自最近成功生命周期解析并保存的 access。
  6. 验证业务输出只写授权属性;不确定结果不产生输出且不会被当成安装成功。

引用生命周期验收

保持 failurePolicy: "FAIL_FAST",按服务引用完整操作示例 执行以下场景。每次记录准确 Runtime、来源资源、插件程序版本、配置结果、两个阶段的通知与真实业务响应;不记录秘密。

场景必须观察到的结果
空引用安装,提供方尚未安装定义和插件业务实例正常初始化;Owner 返回本包资源;依赖引用的调用明确失败
安装或升级时仅部分引用已绑定不要求其他授权引用同时存在;无关功能可正常使用
安装后绑定正式属性命令成功,插件收到当前配置,真实只读调用得到预先约定的业务结果
换绑新调用使用新绑定;用两个目标可区分的业务结果证明切换,不能只看命令返回成功
清空单值引用配置与通知成功;插件仍存在,旧目标不再被调用,对应功能明确返回未绑定
再绑定原业务实例保持,相关功能恢复,不自动补回旧目标
相同通知重复执行业务实例不重复创建;配置不回退,业务重试不临时解析引用
越权属性、错误安装身份、非法引用格式或真实插件执行错误明确拒绝;FAIL_FAST 仍阻止把失败当成功

公开 SDK 的状态样例测试只验证文档载荷与授权合同,文档构建只验证内容和静态产物。 它们不证明任何目标环境已支持全部行为;真实业务链路尚未执行时明确记录为未验收。

应用绑定与配置生命周期

在 Module 已安装的工作区,只更改应用绑定,验证 BEFORE_RESOURCES 与 AFTER_RESOURCES 均实际调用。 插件需要能读取声明授权的 Module 属性,通过 credentialProperties 解析当前引用的访问地址和凭证, 并将允许回写的业务属性保存成功;Module 不必被重新安装,也不必作为本次直接修改的资源。

记录同一次绑定请求的生命周期关联标识、阶段结果与业务配置读回。仅有应用 READY、静态页面成功, 或另外执行一次 Bundle 升级成功,均不能替代应用绑定触发生命周期的验收。 验证 Owner 中资源缺失、引用撤销、未授权属性及回写类型错误会明确失败;失败后重新绑定应创建新执行, 重新获取当前上下文并幂等完成,不能复用旧凭证或把缺失资源当成空配置。

恢复与业务归属

场景需要验证的真实结果
同一操作、阶段重试不重复创建实例、不重复产生业务副作用
外部成功但响应丢失以相同操作身份和阶段重试 APPLY,恢复结果,验证无重复资源及未使用凭据得到回收
已完成 A,再执行 B,再重放 A不能覆盖 B 的当前业务配置
两个安装或两个环境完整安装身份隔离,不能用相同实例编号接管
管理员停用后同步按业务配置所有权保留管理员决定
Map 移除成员再添加明确验证配置保留或删除重建的业务语义
DETACH新引用访问失败;业务入口停止、关联清理分别验证
新安装复用业务键不误占旧归属或其他安装的业务配置
业务配置正在被使用遵守业务所有者的绑定和删除约束

停用后取不到回发凭据,只能证明回发授权失效;不能据此认定业务入站入口也停止。 卸载的关联清理不能用未授权的空引用响应替代。不得为重试直接伪造 Applied 或空 Map。

引用与日志

分别测试重绑、Token 轮换、撤销、过期、环境不匹配、缺失目标、Map 多键、List 重复目标以及 HTTP 重定向。 生命周期重试可重新解析并幂等更新运行配置;业务重试保留幂等键,读取已生效的本地配置,不调用解析接口。 验证一次生命周期解析后连续业务调用和进程重启均不回源;后续配置生命周期更新后使用新地址与 Token。 验证失败升级不清空旧有效配置、迟到回调不覆盖新配置,以及移除、撤销、过期后停止使用。 凭据只存在受保护的运行配置中,不得进入错误、日志、公开响应或普通业务数据。

发布验收

按注册与管理回读 bundleExecution, 核对协议、执行地址和支持阶段。通过Bundle 绑定 创建不可变 Bundle 版本,实际安装、升级、配置和解除。 安装前分别验证两个调用方向的认证、错误凭据拒绝、轮换及撤销;目录记录存在不能代替认证接入验收。 历史业务配置先由所有者依据权威安装记录完成迁移,独立配置不得被接管。 保存源码提交、制品证明、目录版本、安装操作结果及业务验证证据;制品已发布不等于环境已经激活。

本页内容