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

基本介绍​

源码插件通过services.Dict()解析宿主字典值，动态插件通过plugin.yaml声明service: dict后使用pluginbridge.Default().Dict()客户端访问。它适合把业务状态、类型编码和枚举值展示为当前语言下的标签，避免插件直接依赖宿主字典表或缓存实现。

能力阶段：运行期

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

能力设计​

标签视图模型​

Dict能力将宿主字典值解析为稳定的标签视图，支持运行时翻译键和当前语言标签：

字段说明
Type字典类型
Value字典值
LabelKey稳定运行时翻译键
Label可选的当前语言解析标签

ResolveInput.IncludeLabel控制是否解析Label。当只需要稳定键或后续自行本地化时，可以不请求标签文本。

解析流程​

使用边界​

  • 只解析一个字典类型。 一次ResolveInput围绕一个Type解析多个Value。
  • 刷新是管理命令。 字典刷新可能影响宿主缓存和多插件展示结果，只通过Admin().Dict()暴露。
  • 字典不是配置。 字典值用于业务枚举展示；插件运行参数应使用配置管理能力。
  • 字典不是国际化目录。 LabelKey可以交给运行时翻译能力解析，但字典能力本身不负责维护语言包。

接口定义​

源码插件接口​

入口方法说明
Dict()ResolveLabels批量解析一个字典类型下的多个值，返回标签视图和不透露具体原因的缺失集合
Admin().Dict()Refresh刷新指定字典类型的视图或缓存

动态插件接口​

动态插件通过hostServices.dict声明授权的方法：

动态方法说明
labels.resolve批量解析一个字典类型下的多个值，返回标签视图

能力使用​

源码插件使用​

源码插件通过services.Dict()解析字典值：

// 批量解析字典值标签
result, err := services.Dict().ResolveLabels(ctx, capabilityCtx, dictcap.ResolveInput{
    Type:         "order_status",
    Values:       []dictcap.Value{"pending", "processing", "completed"},
    IncludeLabel: true,
})

// 使用标签视图
for _, proj := range result.Projections {
    fmt.Printf("%s -> %s\n", proj.Value, proj.Label)
}

可信源码插件刷新字典视图：

err := services.Admin().Dict().Refresh(ctx, capabilityCtx, "order_status")

动态插件使用​

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

hostServices:
  - service: dict
    methods:
      - labels.resolve

动态插件通过pluginbridge.Default().Dict()客户端调用：

dictSvc := pluginbridge.Default().Dict()

// 批量解析字典值标签
result, err := dictSvc.ResolveLabels(ctx, capabilityCtx, dictcap.ResolveInput{
    Type:         "order_status",
    Values:       []dictcap.Value{"pending", "processing", "completed"},
    IncludeLabel: true,
})

设计约束​

  • 不暴露字典表结构。 插件只能看到Type、Value和标签视图。
  • 缺失结果不透露具体原因。 返回缺失值时不区分不存在、不可见或被拒绝。
  • 刷新需要审计上下文。 可信源码插件调用刷新命令时应提供调用来源、操作者、租户和原因。
  • 动态插件只读。 动态插件通过hostServices.dict声明labels.resolve方法，只读取标签视图，不涉及字典刷新。

相关服务​