什么是 SAP Spartacus UI 的 code deprecation

JerryWang_汪子熙 - 2021-11-17 23:47:06

---

对于复杂且快速发展的库，在改进现有功能的同时保持向后兼容性可能具有挑战性。 代码弃用允许您正确标记过时的代码，并通过警告用户，帮助他们过渡到更好的替代方案。

要将函数、类、方法或属性标记为已弃用，请使用 @deprecated 标记。 下面是一个例子：

/**
* @deprecated since 1.0.2
* Use better alternative instead
*/

根据实际的弃用政策，此类代码将成为下一个主要版本之一中删除的候选代码。

Marking Deprecated Logic

通常，为了适应向后兼容性，一些间接相关的代码需要包含额外的逻辑，当相关的弃用功能被删除时，这些逻辑应该被删除。 当不清楚应该删除哪些附加逻辑时，确保删除过时代码的最佳方法是用正确的 TODO 注释标记它，最好链接到带有附加详细信息的 GitHub 问题。 应正确标记这些票证（例如，具有 deprecated-1.x 的标签），以便将来更容易将其作为删除的候选对象引用。

以下是 TODO 注释的示例：

// TODO(issue:3313) Deprecated since 1.1.1

Feature Flags

每个新的次要版本都会发布新功能。 有时，新功能被添加到客户已经可以使用的现有组件中，这使得这些更改成为破坏性更改，因为添加到 DOM 或因为不同的行为。 为了避免破坏客户的代码，并在不需要过于频繁地发布新的主要版本的情况下灵活地改进现有组件的功能，Spartacus 使用了功能标志。

功能标志允许我们执行以下操作：

根据功能级别区分功能，对应小版本号基于显式特征标志区分特征

注意：显式功能标志可以链接到功能级别，这意味着默认情况下为该特定级别启用它们。

Deciding If You Need a Feature Flag

如果不需要，最好避免创建新的功能标志。这有助于保持我们的配置干净并使最终的维护更容易。

以下指南可以帮助您决定应该使用哪个功能标志（如果有）：

(1) 如果可能，尽量避免使用功能标志。

相反，将您的功能实现为一个单独的模块，可以由客户选择导入。

(2) 如果您的功能已经有单独的配置，请确定以下哪个更方便：

a. 在模块配置中创建一个新选项（对于一般功能，使它们可切换具有实际价值）。
b. 使用功能标志（特别是当标志的唯一原因是向后兼容时）。

如果可能，尽量避免创建明确的功能标志。相反，尝试启用特定功能级别的功能，例如次要版本。
如果要创建显式功能标志，请确保这样做的原因是合理的（例如，该功能非常重要，可以显式禁用或启用）。

Detecting the Feature Level

如果您的服务或组件已经注入了全局配置，您可以使用一个简单的实用程序函数来检查功能级别，如以下示例所示：

if (isFeatureLevel(this.config, '1.1')) {
  // code that is meant to be executed for feature level 1.1 and above
}

如果您的组件或服务无权访问全局配置，您可以注入 FeatureConfigService 并使用它，如下例所示：

 constructor(
    // ...
    protected featureConfig: FeatureConfigService
  ) {}

  // set a feature flag based on the feature level
  readonly isSomeNewFeatureEnabled = this.featureConfig.isLevel('1.1');

如果要在模板中有条件地显示组件，可以使用 cxFeatureLevel 指令，如下例所示：

<newComponent *cxFeatureLevel="'1.1'"></newComponent>

您可以在没有额外配置的情况下引入显式标志，但建议您将它们包含在店面配置的类型定义中，以将它们公开给客户。 为此，请将您的标志作为布尔类型的新属性添加到 feature-toggles.ts 文件中的 FeatureToggles 接口。 下面是一个例子：

export interface FeatureToggles {
  features?: {
    // ...

    /**
     * Sample feature description
     */
    consignmentTracking: boolean;
  };
}

通过这种方式，您还可以在标志中添加描述，如果需要，甚至可以添加弃用注释。

Linking the Feature Flag to the Feature Level

通过将您的功能标志链接到功能级别，默认情况下将为该功能级别和所有更高级别启用您的标志。 为此，请将功能标志的默认值作为表示功能级别的字符串提供。 您可以将此配置添加到您的模块配置中，如以下示例所示：

ConfigModule.withConfig({
  // ...
  features: {
    consignmentTracking: '1.1',
  },
})

在此示例中，如果功能级别设置为至少“1.1”，则默认情况下启用寄售跟踪功能。

Disabling a Feature for a Specific Feature Level

您可以通过包含感叹号来禁用特定功能级别的功能！ 在版本号之前。 下面是一个例子：

<newComponent *cxFeatureLevel="'!1.1'"></newComponent>

Tags 标签

sapsaprfcjavascripttypescriptnode.js

扩展阅读