SuperAPI AI 工具集

finfocus-plugin-dev

编程与开发

查看项目

更新于 10-28 23:22

技能介绍

用途

用于开发 FinFocus 成本插件:在 finfocus plugin init 脚手架生成的仓库中新增或修改定价逻辑。FinFocus 插件是一个独立二进制程序,通过 github.com/rshade/finfocus-spec/sdk/go/pluginsdk 提供 CostSourceService gRPC API。finfocus CLI 启动插件后先调用 Supports,再针对每个资源调用 GetProjectedCost,并可选调用 GetActualCost、GetRecommendations 等接口。

核心规则

  • 不手工修改 SDK 版本相关状态(go.mod 中的 finfocus-spec、SpecVersion、workflow 固定版本),应运行 finfocus plugin upgrade 并遵循 finfocus-plugin-upgrade 技能。
  • 不得虚构价格。无法定价时,在 Supports 返回“not supported”,或在 GetProjectedCost 返回错误,不要猜测或返回默认值。脚手架中 calculateEC2InstanceCost 的示例费率是占位值,需要替换;v0.4.0 及更早脚手架会把缺失实例类型默认为 t3.micro 并按该费率计价,需删除。
  • 价格须来自真实数据:带来源和日期说明的本地价格表,或服务商的定价 API,并在 billing_detail 中记录来源。
  • 未经用户要求,不执行 git commit 或 git add。
  • SpecVersion 必须带 v 前缀(如 v0.7.2),使用 pluginsdk.SpecVersion。
  • 不得向 stdout 写入任何内容,SDK 会在那里输出唯一一行 PORT=<n> 握手信息;日志写到 stderr 或 SDK 日志写入器。

仓库结构

  • cmd/plugin/main.go:构建 pricing.NewCalculator() 并调用 pluginsdk.Serve,读取 --port 与 FINFOCUS_PLUGIN_PORT,可选健康检查服务;很少改动。
  • internal/pricing/calculator.go:Calculator 内嵌 *pluginsdk.BasePlugin,包含 GetPluginInfo、Supports、GetProjectedCost、GetActualCost;主要工作文件。
  • internal/pricing/data.go:定价数据加载/保存辅助与示例数据。
  • internal/client/client.go:服务商 API 客户端桩(GetResourceCost、ValidateCredentials、GetSupportedRegions),调用实时 API 时使用。
  • internal/pricing/calculator_test.go:使用 pluginsdk.NewTestPlugin 的示例测试,可扩展。
  • manifest.yaml、manifest.json:插件元数据(名称、版本、服务商、能力),需保持同步。
  • Makefile:build、test、lint、install、cover、security。
  • .golangci-lint.yml:lint 配置。
  • .github/workflows/:CI、发布等,仅通过 upgrade 修改。
  • docs/、docker/、issues.md、examples/:按需使用。

二进制名为 finfocus-plugin-<name>,make build 输出到 bin/。SDK 细节见 references/sdk-api.md。

端到端新增资源类型

  1. 确认真实输入:运行 plan 查看插件收到什么。核心发送 Pulumi 类型 token(如 aws:ec2/instance:Instance)、provider、sku、region,以及作为 tags 的资源输入。v0.4.0 及更早脚手架匹配 aws:ec2:Instance,核心不会发送该形式,需修正。
  2. 注册支持:在 NewCalculator 的 matcher 中调用 base.Matcher().AddProvider、AddResourceType,并扩展 Supports。
  3. 提取输入:从 req.GetResource() 读取 SKU 和 region,回退到 pluginsdk/mapping 的 Extractor(ExtractAWSSKU、ExtractAzureSKU、ExtractGCPSKU 及对应 Region 形式)从 Tags 提取。
  4. 定价:计算小时费率并调用 c.Calculator().CreateProjectedCostResponse(currency, hourly, detail),其设置 CostPerMonth = hourly * 730;月价可用 pluginsdk.NewGetProjectedCostResponse(pluginsdk.WithProjectedCostDetails(...))。
  5. 测试:为新类型添加表驱动用例,另加不支持与缺失 SKU 用例。
  6. 运行真实测试回路,并与服务商公开价格页对比。
  7. 能力变化时更新 manifest 与 README 资源列表。

Supports 约定

Supports 属可选接口 SupportsProvider。无法支持时应返回 Supported: false 并给出 Reason,而不是返回错误,因为核心把 RPC 错误视为 fail-open 并仍调用插件。未实现 Supports 的插件得到 SDK 默认值(false 与 DefaultSupportsNotImplementedReason),核心同样按 fail-open 处理,因此应真正实现。核心会按 client、provider、type、region、SKU、feature 缓存结果;限定区域的插件须在此拒绝其他区域,以便路由到其他插件。Supports 必须轻量且离线,不调用 API。

成本响应约定

GetProjectedCost 返回 Currency、UnitPrice(小时)、CostPerMonth 和 BillingDetail,后者用于说明假设(OS、租期、默认值、价格来源)。使用 pluginsdk.ValidateProjectedCostRequest 校验(需要 provider、type、SKU、region);若 tags 含 ref.* 键且 SKU 为空,核心使用 ValidateProjectedCostRequestLenient,插件应同样处理,再从 ref.<property>.sku 定价或在 BillingDetail 说明缺失项。$0 是有效结果且不会触发下一个插件,仅在资源确实免费时返回 $0,否则返回错误以便其他插件尝试。不支持资源返回 pluginsdk.NotSupportedError(resource),无账单数据返回 pluginsdk.NoDataError(id)。缓存提示可用 pluginsdk.WithProjectedCostExpiresAt 设置 ExpiresAt,过去时间不缓存,核心 TTL 上限 7 天。可选额外接口 GetRecommendations、GetPricingSpec、EstimateCost、BatchCost、DryRun 仅在能正确实现时提供。

测试回路

  • make test:单元测试,经 pluginsdk.NewTestPlugin 进程内 gRPC。
  • 一致性测试:在测试中调用 pluginsdk.RunBasicConformance(以及 Standard、Advanced)。
  • make install 将二进制复制到 ~/.finfocus/plugins/<name>/<version>/。
  • 运行 finfocus plugin list 与 finfocus plugin validate。
  • 对真实 plan 计价:finfocus cost projected --pulumi-json plan.json(用 pulumi preview --json > plan.json 生成),加 --debug 查看调用。
  • 完成前运行 make lint。

常见易错点

  • 核心不设置 PORT,应使用 --port 或 FINFOCUS_PLUGIN_PORT。
  • Pulumi token 形式多样,不要只匹配单一固定拼写。
  • 嵌套输入以点分 tag 键出现(如 sku.capacity、rootBlockDevice.0.volumeType),与折叠键并存。
  • PluginVersion、manifest.* 版本与安装目录不一致会导致 plugin list 混乱,应保持一致。
  • plugin.metadata.json 中的 region 键会让核心优先查找 finfocus-plugin-<name>-<region>,按区域分包插件应遵循该命名。
  • make install 必须写入扁平 JSON 的 plugin.manifest.json,其 name 与 version 须与安装目录一致,否则 validate 失败;v0.4.0 及更早脚手架在此复制 manifest.yaml,需替换为当前脚手架的 printf。