跳到主要内容

UI 扩展版本化的最佳实践

为了保持稳定性并在更新 UI 扩展时确保平稳过渡，请在扩展点或暴露组件的 ID 中包含版本后缀。这种做法可以在保持兼容性的同时，让开发者以可控的方式管理破坏性变更。

在 ID 中使用版本后缀​

每个扩展点 ID/组件 ID 应包含一个后缀，指示扩展的主要版本。

示例

// Initial version
export const EXTENSION_POINT_OR_COMPONENT_ID_V1 = 'my-plugin-id/feature/v1';

// Breaking change introduced
export const EXTENSION_POINT_OR_COMPONENT_ID_V2 = 'my-plugin-id/feature/v2';
  • 非破坏性变更（例如，添加可选属性）无需新的版本后缀。
  • 破坏性变更（例如，修改行为或移除属性）必须引入新的版本后缀。

在过渡期间支持多个版本​

在引入新的主要版本时，应用程序应在过渡期内同时提供旧版本和新版本。这使得消费者有时间进行迁移，而不会立即中断。

示例

  • 在引入 my-plugin-id/feature/v2 的同时，my-plugin-id/feature/v1 继续运行。
  • 消费者逐步迁移到 v2。
  • 在 v1 的弃用期过后，你可以安全地将其移除。

清晰地传达弃用信息​

应向消费者清晰地传达弃用信息，以确保平稳过渡。

  • 在发布的类型中使用 @deprecated 关键字，并参考变更日志或迁移指南。

    示例

    /**
     * @deprecated Use FeatureConfigV2 instead. See migration guide: https://example.com/migration-guide
     */
    export type FeatureContextV1 = {
      /* ... */
    };

  • 在变更日志或迁移指南中记录变更。

  • 提供弃用旧版本的时间表。

  • 通知消费者即将到来的变更，以防止意外破坏。

发布带有版本后缀的类型​

注意

此选项目前仅适用于在 grafana 组织内部开发的插件。

为了支持同时消费多个版本，请使用相同的版本后缀将类型发布到 @grafana/plugin-types。这使得开发者可以导入不同版本的类型而不会发生冲突。

示例

// Extension point context
import { FeatureContextV1 } from '@grafana/plugin-types/my-plugin-id';
import { FeatureContextV2 } from '@grafana/plugin-types/my-plugin-id';

// Exposed component props
import { ComponentPropsV1 } from '@grafana/plugin-types/my-plugin-id';
import { ComponentPropsV2 } from '@grafana/plugin-types/my-plugin-id';
  • 确保在使用不同扩展版本时的类型安全。
  • 在引入变更时避免破坏现有消费者。

总结​

通过遵循这种对扩展和扩展点进行版本化的方法，你可以确保它们的稳定性，同时允许迭代改进、平稳迁移和更安全的类型管理。