SuperAPI AI 工具集

services-extension-consumption

编程与开发

查看项目

更新于 10-16 11:56

技能介绍

用途

本文档说明如何消费 salesforcedx-vscode-services 扩展所提供的 API,面向那些依赖该 services 扩展的 VS Code 扩展开发者。文档举出的示例扩展包括 salesforcedx-vscode-metadata 与 salesforcedx-vscode-org-browser。

获取 API

通过 @salesforce/effect-ext-utils 中的 ExtensionProviderService 与 getServicesApi 获取服务 API。示例代码展示了用 Layer.effect 构建 ExtensionProviderServiceLive,并在 Effect.gen 中调用 getServicesApi 得到 api。

预构建服务与每扩展服务

api.services.prebuiltServicesDependencies 是来自 services 扩展激活的预构建 Context.Context,需用 Layer.succeedContext(...) 包装。它跨扩展共享单例实例(缓存、watcher),避免重复构建有状态服务。

必须自行构建的每扩展层包括:

  • ChannelServiceLayer(displayName):自有输出通道
  • ErrorHandlerService.Default:依赖自有 ChannelService
  • ExtensionContextServiceLayer(context):自有 ExtensionContext
  • SdkLayerFor(context):自有 tracer(资源属性中包含扩展名与版本)
  • ExtensionProviderServiceLive:本地单例

ExtensionContext 搭建

推荐从 @salesforce/effect-ext-utils 导入 buildAllServicesLayer,它会从 package.json 读取 displayName,读取失败时回退到第二个参数。services/extensionProvider.ts 只需可变的 AllServicesLayer 与其 setter。

激活时传入 context 与本地化的回退通道名。文档指出存在两种模式:

  • 仅共享基础:直接从 @salesforce/effect-ext-utils 导入 buildAllServicesLayer 并在激活时传给 setAllServicesLayer,无需本地工厂。属于此类的有 core、apex、apex-testing、lightning、lwc、org、visualforce。
  • 添加扩展专属服务:在 services/extensionProvider.ts 中定义本地 buildAllServicesLayer,调用 buildSharedServicesLayer 并通过 Layer.mergeAll 合并扩展自身的 Effect 服务。例如 apex-oas 添加 ApexMetadataService 与 LLMService;带通知系统的扩展添加 NotificationModeService.Default;org-browser 添加 OrgBrowserRetrieveService。

Runtime 与 provide

  • 应做:构建 ManagedRuntime.make(AllServicesLayer) 并导出 getRuntime()。
  • 应做:导出 runtime 释放、清空 memo,并在扩展 deactivate 时调用。
  • 应做:用 getRuntime().runPromise(effect) / runFork(effect) 做临时执行。
  • 不应做:在调用点使用 Effect.provide(AllServicesLayer),而应使用 runtime。

资源生命周期

优先使用 Effect scope 掌控在 Effect 服务/层内创建的资源:用 scoped 定义拥有资源的服务;用 Effect.addFinalizer 注册 VS Code Disposables;用 Effect.forkIn 将长生命周期 fiber 挂到所属 scope;在 deactivation 时释放所属 ManagedRuntime 以触发层 finalizer。不要仅为让消费者加入 context.subscriptions 而暴露 runDispose/dispose。对于在 Effect scope 之外创建的资源,保留 context.subscriptions。分配与清理应放在一起。

注册命令

使用 registerCommandWithRuntime。命令会自动注册到 ExtensionContext subscriptions、包装错误处理、并带有可观测 span 追踪。

处理取消与成功

Effect.fn 在 generator 之后接受中间件参数。成功侧中间件应放在 catchTag/catchAll 之前,否则被捕获的错误会变成成功。withConfigurableSuccessNotification 用 Effect.tap 包装 effect,只在成功时触发。

调用 sf.org.login.web

跨扩展 / executeCommand 方式为 vscode.commands.executeCommand('sf.org.login.web', instanceUrl?, reauthAliasOrUsername?)。无参数时为交互式流程(命令面板);提供 instanceUrl 时跳过组织类型快速选择;第二个参数仅在提供 instanceUrl 时生效,非空字符串成为认证别名(access-token 重新认证),否则别名默认为 reauth-vscodeOrg。

基础服务

访问器模式:直接调用方法,不要先赋值给变量。文档列出以下服务:

  • ChannelService:输出通道
  • ComponentSetService:构建组件集(source、manifest、URI)
  • MediaService:图标(ICONS)与 NLS 描述
  • WorkspaceService:工作区信息
  • ConnectionService:组织连接
  • ProjectService:项目解析、packageDirectories
  • SettingsService:设置读写
  • FsService:文件操作(web 兼容)、uri/path 转换、HashableUri(基于值的 URI 相等性,用于 HashSet/HashMap 键)
  • EditorService:活动编辑器变更与当前 URI
  • Prompts:QuickPick、InputBox 与 UserCancellationError 处理
  • TerminalService:运行 shell 命令(仅桌面)
  • NotificationModeService:可配置成功通知

Watchers

文件监听:FileWatcherService 暴露所有工作区文件变更(**/*)的 PubSub,可订阅并过滤,事件含 create/change/delete 与 uri。

配置监听:使用 vscode.workspace.onDidChangeConfiguration 结合 PubSub.sliding,用 Effect.addFinalizer 释放 disposable,通过 Stream 过滤 affectsConfiguration 并 debounce。

目标组织变更:通过 TargetOrgRef(SubscriptionRef)监听。ref.changes 会先发出当前值,因此不要额外前置 get。默认组织更新时,用户名优先取 User SOQL;否则取连接上的 AuthInfo 登录用户名。无用户名快照时会先尝试可选的 ConfigUtil.getUsername()(项目默认),再判定为无目标组织。TargetOrgRef 的值始终是对象(不会 undefined),仅其中如 orgId 等字段可选。

清除默认组织:调用 ClearDefaultOrgRef() 重置进程内组织 ref(例如删除默认组织后)。它清空响应式 ref 但不重写配置,适用于 CLI 已修改配置但进程内 ref 需重置以通知观察者的场景,示例为 orgDeleteDefaultCommand。

完整示例模式

文档给出 services/extensionProvider.ts、services/runtime.ts、index.ts 三个文件的完整示例,展示 setAllServicesLayer、getRuntime、activate、activateEffect 的写法,包括注册命令与向 ChannelService 追加日志。

测试

通过 Layer.succeed 与 Layer.mergeAll 模拟服务。对于静态访问器(如 api.services.WorkspaceService.getWorkspaceInfo()),需同时装配 provider 与服务。对于直接服务模拟(无访问器),单独使用 Layer.succeed(Service, mockImpl) 即可。

常见模式

  • 从 Layer.succeedContext(api.services.prebuiltServicesDependencies) 开始,不要再为其中已有的服务添加各个 *.Default。
  • 只在其上添加每扩展层。
  • ICONS 在 Effect 外导入,MediaService 在 Effect 内使用。
  • ChannelServiceLayer 在 ErrorHandlerService 之前。
  • 向 SdkLayerFor 传入 context(从 ExtensionContext 提取名称/版本)。
  • 用 Effect.forkIn(..., yield* getExtensionScope()) 以便 watcher 在 deactivation 时清理。
  • scoped 服务通过 finalizer 拥有其 VS Code disposable;runtime 释放会运行它们。
  • 所有命令使用 registerCommandWithRuntime(追踪 + 错误处理)。
  • 用 getRuntime().runPromise / runFork 执行,而不是 Effect.provide(AllServicesLayer)。
  • 不要:重建已在 prebuiltServicesDependencies 中的服务。文档给出反面示例,指出对其中任何服务调用 .Default 会创建带自己缓存、watcher 与状态的第二个实例,静默破坏跨扩展共享。prebuiltServicesDependencies 包含约 27 个在 services 扩展激活时构建一次的服务。

审查

建议对计划与 diff 调用 effect-advocate 子代理,其最高优先级发现类别是「你重新实现了 salesforcedx-vscode-services 中已有的东西」。