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

基本介绍​

配置相关能力不要按方法名理解，而应按领域边界选择：

配置领域源码插件入口动态服务说明
插件静态配置services.Plugins().Config()plugins.config.get读取当前插件自己的config.yaml
宿主配置读取services.HostConfig()hostconfig.get读取宿主配置值；动态插件必须声明resources.keys
运行时配置管理services.Admin().HostConfig()无普通动态服务可信源码插件写入受管控的运行时配置

其中Plugins().Config()属于插件治理能力的子能力；HostConfig()是普通能力目录中的宿主配置读取能力；Admin().HostConfig()属于可信源码插件管理命令。三者都叫配置，但来源、作用域、治理和使用者不同。

能力阶段：运行期

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

能力设计​

配置领域分层​

插件静态配置​

插件自己的静态配置由Plugins().Config()读取。它绑定当前插件ID，不会读取其他插件或宿主全局配置。

读取优先级为：

优先级来源说明
1生产配置根下plugins/<plugin-id>/config.yaml运维覆盖，生产环境优先
2开发期manifest/config/config.yaml源码插件开发默认配置
3动态插件产物绑定的manifest/config/config.yaml发布产物默认配置

manifest/config/config.example.yaml只是配置模板，不参与运行时默认读取。

宿主配置读取​

源码插件通过services.HostConfig()读取宿主配置值。当前源码实现通过宿主启动期注入的配置读取器取值，不再对源码插件套用硬编码公开键清单。

运行时配置管理​

运行时配置管理属于可信源码插件管理命令，不是普通读取能力。SetRuntimeConfigJSON需要调用方传入领域要求的CapabilityContext，宿主适配器继续负责配置键可见性、租户边界、审计原因和写入校验。

接口定义​

插件静态配置接口​

方法说明
Get返回原始配置值
Exists判断配置键是否存在
Scan将配置段扫描到目标结构体
String读取字符串值，缺失或空白时返回默认值
Bool读取布尔值，缺失时返回默认值
Int读取整数值，缺失时返回默认值
Duration读取时间间隔，缺失或空白时返回默认值

宿主配置接口​

方法说明
Get读取宿主配置原始值
Exists判断宿主配置键是否存在
String读取字符串值
Bool读取布尔值
Int读取整数值
Duration读取时间间隔

管理命令接口​

入口方法说明
Admin().HostConfig()SetRuntimeConfigJSON写入一个受管控的运行时配置值

动态插件接口​

动态服务方法说明
pluginsconfig.get读取当前插件作用域配置
hostconfigget读取宿主配置值，必须声明授权resources.keys

能力使用​

源码插件使用​

源码插件根据配置领域选择正确的入口：

// 读取插件自己的配置
value, err := services.Plugins().Config().String(ctx, "api.endpoint", "https://default.example.com")
enabled, err := services.Plugins().Config().Bool(ctx, "features.export", false)

// 读取宿主配置
basePath, err := services.HostConfig().String(ctx, "workspace.basePath", "")

// 写入运行时配置（可信源码插件）
err := services.Admin().HostConfig().SetRuntimeConfigJSON(ctx, capabilityCtx, "plugin.reports.maxExport", jsonValue)

动态插件使用​

动态插件在plugin.yaml中分别声明plugins和hostconfig服务：

hostServices:
  - service: plugins
    methods:
      - config.get
  - service: hostconfig
    methods:
      - get
    resources:
      keys:
        - workspace.basePath
        - i18n.default

plugins的config.get用于读取当前插件配置。hostconfig的授权边界由resources.keys控制；未声明键不应被宿主返回。在动态插件侧使用：

// 读取插件配置
endpoint, err := pluginbridge.Default().Plugins().Config().String(ctx, "api.endpoint", "https://default.example.com")

// 读取宿主配置
basePath, err := pluginbridge.Default().HostConfig().String(ctx, "workspace.basePath", "")

设计约束​

  • 插件业务参数放进插件配置。 不要为了读取插件自己的参数而使用HostConfig()或宿主g.Cfg()。
  • 宿主配置读取要谨慎。 源码插件虽然可以通过HostConfig()读取宿主配置，但插件文档和代码应只依赖明确约定的键。
  • 动态插件必须声明键。 hostconfig动态服务的授权来自resources.keys，不要声明根配置或模糊键作为常规做法。
  • 运行时写入走管理命令。 普通插件配置读取和宿主配置读取都是只读能力；写入配置只通过Admin().HostConfig()暴露给可信源码插件。
  • 模板不等于运行配置。 config.example.yaml用于说明和生成示例，不参与运行时优先级。

相关服务​