跳到主要内容
版本：0.4.x(Latest)

基本介绍​

Infra()用于读取宿主基础设施组件的状态视图。它关注“某个组件当前是否可服务、处于什么状态、展示什么标签”，不暴露连接池、健康检查实现、监控客户端或具体运行后端。

基础设施状态能力有三个入口：

入口使用者说明
services.Infra()源码插件读取可见组件状态视图
service: infra动态插件声明读取基础设施组件状态的动态宿主服务
services.Admin().Infra()可信源码插件刷新指定组件的状态缓存或状态快照

动态插件的Runtime()是另一类专属能力，用于日志、插件运行状态、宿主时间、UUID和节点身份读取，不属于Infra()领域能力。

能力阶段：运行期

类型支持：源码插件、动态插件

设计思路​

状态视图而非实现入口​

Infra()只提供基础设施组件状态视图。插件可以用它判断某个宿主组件是否可用，但不能通过它取得底层客户端、连接配置、健康检查任务或运行时缓存对象。

与Runtime()的边界​

Infra()和Runtime()都可能涉及宿主运行状态，但它们表达的职责不同：

能力所属边界主要职责
Infra()源码插件和动态插件共享的普通领域能力读取基础设施组件状态视图
Runtime()动态插件专属能力写日志、读写插件运行状态、读取宿主时间、生成UUID和读取节点身份

因此，动态插件如果要读取组件状态，应声明service: infra；如果要写运行时日志或读写插件作用域状态，应声明service: runtime。

主要能力​

普通读取能力​

入口方法说明
Infra()BatchGetStatus批量读取可见基础设施组件状态

StatusProjection包含以下字段：

字段说明
ID组件标识
Available组件当前是否可服务
Status组件拥有的状态值
LabelKey稳定的运行时翻译键
Label可选的当前语言标签

管理命令​

入口方法说明
Admin().Infra()RefreshStatus刷新指定组件的状态缓存或状态快照

RefreshStatus属于可信源码插件管理命令，不通过动态插件普通hostServices开放。

能力使用​

源码插件读取状态​

源码插件通过services.Infra()读取组件状态，并显式传入领域要求的CapabilityContext：

result, err := services.Infra().BatchGetStatus(ctx, capabilityCtx, componentIDs)
if err != nil {
    return err
}

for _, status := range result.Items {
    if !status.Available {
        logger.Warningf(ctx, "infra component unavailable id=%s status=%s", status.ID, status.Status)
    }
}

可信源码插件刷新组件状态：

err := services.Admin().Infra().RefreshStatus(ctx, capabilityCtx, componentID)

动态插件读取状态​

动态插件在plugin.yaml中声明infra服务：

hostServices:
  - service: infra
    methods:
      - status.batch_get

infra是none资源类型，不声明paths、tables、keys或resources。在动态插件侧通过pluginbridge.Default().Infra()读取状态：

services := pluginbridge.Default()
result, err := services.Infra().BatchGetStatus(ctx, capabilityCtx, componentIDs)

设计约束​

  • 组件状态是只读视图。 Infra()不暴露具体运行后端、连接池、监控客户端、健康检查实现或宿主内部对象。
  • 批量读取优先。 插件应通过BatchGetStatus一次读取多个组件状态，避免逐项调用造成不必要开销。
  • 刷新是管理命令。 RefreshStatus可能触发宿主状态重算，只对可信源码插件开放。
  • 动态读取使用service: infra。 动态插件读取基础设施组件状态时声明infra，不要误用runtime。
  • 运行时原语使用Runtime()。 日志、插件运行状态、时间、UUID和节点身份属于动态Runtime能力。

相关服务​