SuperAPI AI 工具集

services-extension-consumption

编程与开发

查看项目

更新于 10-16 10:15

技能介绍

用途

本技能为消费 salesforcedx-vscode-services 扩展 API 提供指南。适用于对 salesforcedx-vscode-services 具有 extensionDependency 的扩展,例如 salesforcedx-vscode-metadata、salesforcedx-vscode-org-browser。

获取 API

使用 @salesforce/effect-ext-utils 中的 ExtensionProviderService:

import { ExtensionProviderService, getServicesApi } from '@salesforce/effect-ext-utils';

const ExtensionProviderServiceLive = Layer.effect(
  ExtensionProviderService,
  Effect.sync(() => ({
    getServicesApi
  }))
);

// In an Effect.gen:
const api = yield * (yield * ExtensionProviderService).getServicesApi;

预构建服务与按扩展服务

api.services.prebuiltServicesDependencies 提供来自服务扩展激活时预构建的 Context.Context,用 Layer.succeedContext(...) 包装。它在扩展之间共享单例实例(缓存、监听器),避免重复构建有状态服务。

按扩展的层需要自行构建:

Layer 原因
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:

// services/extensionProvider.ts
import { buildAllServicesLayer } from '@salesforce/effect-ext-utils';

export let AllServicesLayer: ReturnType<typeof buildAllServicesLayer>;
export const setAllServicesLayer = (layer: ReturnType<typeof buildAllServicesLayer>) => {
  AllServicesLayer = layer;
};

在 activate 中传入 context 和本地化的回退通道名:

import { buildAllServicesLayer } from '@salesforce/effect-ext-utils';
import { nls } from './messages';
import { setAllServicesLayer } from './services/extensionProvider';

export const activate = async (context: vscode.ExtensionContext): Promise<void> => {
  setAllServicesLayer(buildAllServicesLayer(context, nls.localize('channel_name')));
  await getRuntime().runPromise(activateEffect(context));
};

遗留内联模式:本地 buildAllServicesLayer 工厂在 services/extensionProvider.ts 中把 Layer.unwrapEffect(...) 包装起来。改动这些代码时应迁移到共享 helper——去掉工厂,从 @salesforce/effect-ext-utils 导入 buildAllServicesLayer,在调用点传入回退名称。

运行时与 provide

  • 应做:构建 ManagedRuntime.make(AllServicesLayer) 并导出 getRuntime()。
  • 应做:使用 getRuntime().runPromise(effect) / runFork(effect) 进行临时执行。
  • 不应做:在调用点使用 Effect.provide(AllServicesLayer)——应改用运行时。
  • 例外:registerCommandWithLayer(AllServicesLayer)——保持传入 Layer,它在内部使用 provide。

注册命令

使用 registerCommandWithLayer(针对 Layer)或 registerCommandWithRuntime(针对运行时)。命令会自动注册到 ExtensionContext subscriptions、包装错误处理、用可观测 span 追踪、处理取消和成功处理。

Effect.fn 在 generator 之后接受中间件参数。把成功侧中间件放在 catchTag/catchAll 之前——否则被捕获的错误会变成成功。

调用 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 转换
  • EditorService — 活动编辑器变更及当前 URI
  • Prompts — QuickPick、InputBox 以及 UserCancellationError 处理
  • TerminalService — 运行 shell 命令(仅桌面)

监听器

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

配置监听:使用 PubSub.sliding 与 vscode.workspace.onDidChangeConfiguration 监听 VS Code 配置变更,配合 Effect.addFinalizer 清理 disposable,并可加 Stream.debounce。

目标组织变更:通过 TargetOrgRef(SubscriptionRef)监听组织变更。ref.changes 总是先发出当前值作为第 0 个元素,然后是后续变更,不要手动前置显式 get。如需抑制初始快照(例如避免在树提供器就绪前触发刷新),使用 Stream.drop(1)。

Ref 行为:默认组织更新时,若 User SOQL 中存在 username 则使用,否则使用连接上的 AuthInfo 登录用户名。无 username 的 TargetOrgRef 快照,在视为无目标组织之前可先尝试可选的 ConfigUtil.getUsername()(项目默认值)——参见 salesforcedx-vscode-org orgDisplay。TargetOrgRef 的值始终是对象(永不为 undefined);只有其中的 orgId 等字段是可选的。

常见模式

  • 从 Layer.succeedContext(api.services.prebuiltServicesDependencies) 开始——不要为已在其中的服务添加单独的 *.Default。
  • 只在其上添加按扩展的层。
  • 在 Effect 外使用 ICONS,在 Effect 内使用 MediaService。
  • ChannelServiceLayer 放在 ErrorHandlerService 之前。
  • 向 SdkLayerFor 传入 context(从 ExtensionContext 提取名称/版本)。
  • 使用 Effect.forkIn(..., yield* getExtensionScope()) 以便在停用时清理监听器。
  • 所有命令都用 registerCommandWithLayer(追踪 + 错误处理)。
  • 使用 getRuntime().runPromise / runFork 执行,而不是 Effect.provide(AllServicesLayer)。
  • 不要重建已在 prebuiltServicesDependencies 中的服务:对其中任一服务调用 .Default 会创建第二个实例,带来自己的缓存、监听器和状态,静默破坏跨扩展共享。

审查

对计划和 diff 调用 effect-advocate 子代理——其最高优先级的发现类别是“你重新实现了 salesforcedx-vscode-services 中已存在的东西”。

prebuiltServicesDependencies 包含约 27 个在服务扩展激活期间一次性构建的服务。