Python 功能管理

Python 功能管理库提供了一种基于功能标志来开发和公开应用功能的方法。 开发新功能后，许多应用程序都有特殊要求，例如应何时启用此功能以及在哪些条件下启用该功能。 该库提供了一种方式来定义这些关系，并集成到常见的 Python 代码模式中，从而实现这些功能的公开。

功能标志为 Python 应用程序提供了一种动态启用或禁用功能的方式。 开发人员可以在简单的用例（如条件语句）中使用功能标志。

以下是使用 Python 功能管理库的一些优势：

• 功能管理的常见约定

• 入门门槛低

  • 支持基于 JSON 的功能标志设置

• 功能标志生存期管理

  • 配置值可以实时更改；功能标志可以在整个请求中保持一致

• 涵盖从简单到复杂的方案

  • 通过声明性配置文件打开/关闭功能
  • 基于对服务器的调用来动态评估功能的状态

  Python 功能管理库是开源的。 有关详细信息，请访问 GitHub 存储库。

功能标志

功能标志由两个部分组成，即名称和用于打开功能的功能筛选器列表。

功能筛选器

功能筛选器定义应启用功能的场景。 当评估某项功能是应打开还是关闭时，将遍历其功能筛选器列表，直到其中一个筛选器确定应启用该功能。 此时，该功能被视为已启用，并停止遍历功能筛选器。 如果没有功能筛选器指示应启用该功能，则它被视为已禁用。

例如，可以设计 Microsoft Edge 浏览器功能筛选器。 只要 HTTP 请求来自 Microsoft Edge，此功能筛选器就会激活附加到它的所有功能。

功能标志配置

使用 Python 字典来定义功能标志。 该字典以功能名称作为键，以功能标志对象作为值。 功能标志对象是一个字典，其中包含一个 conditions 键，而该键本身又包含 client_filters 键。 client_filters 键是一个功能筛选器列表，用于确定是否应启用该功能。

功能标志声明

功能管理库支持使用 JSON 作为功能标志源。 下面是一个在 JSON 文件中设置功能标志所使用格式的示例。

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureT",
                "enabled": true
            },
            {
                "id": "FeatureU",
                "enabled": false
            },
            {
                "id": "FeatureV",
                "enabled": true,
                "conditions": {
                    "client_filters": [
                        {
                            "name": "Microsoft.TimeWindow",
                            "parameters": {
                                "Start": "Wed, 01 May 2019 13:59:59 GMT",
                                "End": "Mon, 01 Jul 2019 00:00:00 GMT"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

按照约定，json 文档的 feature_management 部分用于加载功能标志设置。 feature_flags 部分是加载到库中的功能标志的列表。 在上面的部分中，我们看到了三个不同的功能。 功能使用 client_filters 属性定义其功能过滤器，而不是 conditions。 在 FeatureT 的功能筛选器中，我们看到 enabled 为 true,且没有定义筛选器，导致 FeatureT 始终返回 true。 FeatureU 与 FeatureT 相同，但 enabled 设置为 false，因此该功能始终返回 false。 FeatureV 用于指定一个名为 Microsoft.TimeWindow 的功能筛选器。 FeatureV 是一个可配置功能筛选器的示例。 在该示例中可以看到筛选器具有 parameters 属性。 parameters 属性用于配置该筛选器。 在本例中，将配置功能处于活动状态的开始和结束时间。

可在此处找到 feature_management 部分的详细架构。

高级：功能标志名称中禁止使用冒号“:”。

启用/禁用声明

以下代码片段演示了一种替代方法来定义可用于开/关功能的功能。

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureT",
                "enabled": "true"
            },
            {
                "id": "FeatureX",
                "enabled": "false"
            }
        ]
    }
}

要求类型

功能标志的 requirement_type 属性用于确定筛选器在评估功能状态时应使用 Any 还是 All 逻辑。 如果未指定 requirement_type，则默认值为 Any。

• Any 表示只需有一个筛选器计算结果为 true，即可启用该功能。
• All 表示所有筛选器的计算结果都必须为 true，功能才会启用。

如果 requirement_type 为 All，则会更改遍历。 首先，如果没有筛选器，则该功能处于禁用状态。 然后，将遍历功能筛选器，直到其中一个筛选器确定应禁用该功能。 如果没有筛选器指示应禁用该功能，则它被视为已启用。

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureW",
                "enabled": "true",
                "conditions": {
                    "requirement_type": "All",
                    "client_filters": [
                        {
                            "name": "Microsoft.TimeWindow",
                            "parameters": {
                                "Start": "Wed, 01 May 2019 13:59:59 GMT",
                                "End": "Mon, 01 Jul 2019 00:00:00 GMT"
                            }
                        },
                        {
                            "name": "Percentage",
                            "parameters": {
                                "Value": "50"
                            }
                        }
                    ]
                }
            },
        ]
    }
}

在上面的示例中，FeatureW 指定 requirement_type 为 All，这意味着所有筛选器都必须评估为 true 才能启用该功能。 在本例中，在指定时间范围内为 50% 的用户启用了该功能。

消耗

功能管理的基本形式是检查是否启用了功能标志，然后根据结果执行操作。 通过 FeatureManager 的 is_enabled 方法检查功能标志的状态。

…
feature_manager = FeatureManager(feature_flags)
…
if feature_manager.is_enabled("FeatureX"):
    # Do something

提供给 FeatureManager 的 feature_flags 可以是 AzureAppConfigurationProvider，也可以是功能标志字典。

实现功能筛选器

创建功能筛选器提供了一种基于所定义条件启用功能的方法。 若要实现功能筛选器，必须实现 FeatureFilter 接口。 FeatureFilter 只有一个名为 evaluate 的方法。 当功能指定可为功能筛选器启用它时，将调用 evaluate 方法。 如果 evaluate 返回 true，则表示应启用该功能。

以下代码片段演示如何添加自定义功能筛选器 MyCustomFilter。

feature_manager = FeatureManager(feature_flags, feature_filters=[MyCustomFilter()])

通过在创建 FeatureManager 时提供属性 feature_filters 来注册功能筛选器。 如果自定义功能筛选器需要任何上下文，可以在调用 is_enabled 时通过 kwargs 传入。

筛选器别名属性

当为某个功能标志注册功能筛选器时，默认使用筛选器名称作为其别名。

可以使用 @FeatureFilter.alias("MyFilter") 来覆盖功能筛选器的标识符。 可以使用此属性修饰功能筛选器，以声明应在配置中使用的名称，从而在功能标志中引用此功能筛选器。

缺少功能筛选器

如果某个功能被配置为针对特定功能筛选器启用，但该功能筛选器未注册，则在评估该功能时会引发 ValueError 异常。

内置功能筛选器

FeatureManagement 包中内置了两个功能筛选器：TimeWindowFilter和 TargetingFilter。

每个内置功能筛选器都有自己的参数。 以下是功能筛选器的列表和示例。

Microsoft.TimeWindow

该 Microsoft.TimeWindow 筛选器提供了一种基于时间窗口启用功能的方法。

• 如果您仅指定一个 End 值，则该功能被视为开启直到该时间。
• 如果仅指定一个 Start 值，则在该时间后的所有时间点，功能将被视为开启。

{
    "id": "EnhancedPipeline",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "Microsoft.TimeWindow",
                "parameters": {
                    "Start": "Sun, 01 Jun 2025 13:59:59 GMT",
                    "End": "Fri, 01 Aug 2025 00:00:00 GMT"
                }
            }
        ]
    }
}

可以将筛选器配置为定期应用时间窗口。 在一天中或一周的特定日子里，如果需要在低流量或高流量时段启用某个功能，此功能非常有用。 若要将单个时间范围扩展到定期时间窗口，请使用参数 Recurrence 来指定重复规则。

{
    "id": "EnhancedPipeline",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "Microsoft.TimeWindow",
                "parameters": {
                    "Start": "Fri, 22 Mar 2024 20:00:00 GMT",
                    "End": "Sat, 23 Mar 2024 02:00:00 GMT",
                    "Recurrence": {
                        "Pattern": {
                            "Type": "Daily",
                            "Interval": 1
                        },
                        "Range": {
                            "Type": "NoEnd"
                        }
                    }
                }
            }
        ]
    }
}

这些 Recurrence 设置由两个部分组成：

• Pattern 设置用于指定时间窗口的重复频率。
• Range 设置指定定期模式的重复持续时间。

定期模式

有两种可能的重复执行模式类型：Daily 和 Weekly。 例如，时间窗口可以每天、每三天、每个星期一或每隔一个星期五重复一次。

根据类型，Pattern 设置的某些字段是必需的、可选的或可忽略的。

• Daily

  每天的重复模式会导致时间窗口根据每次发生之间指定的天数来重复。

  properties	相关性	说明
  Type	必选	重复模式类型。 必须设置为 Daily。
  Interval	可选	每次发生之间的天数。 默认值为 1。

• Weekly

  每周重复模式会导致时间窗口在一周中的同一天或几天重复。 但是，您可以指定每组发生情况之间的周数。

  properties	相关性	说明
  Type	必选	重复模式类型。 必须设置为 Weekly。
  DaysOfWeek	必选	事件发生在一周中的天数。
  Interval	可选	每组事件之间的周数。 默认值为 1。
  FirstDayOfWeek	可选	作为一周第一天使用的日期。 默认值为 Sunday。

  以下示例每隔一周的星期一和星期二重复一次时间窗口：

  "Pattern": {
      "Type": "Weekly",
      "Interval": 2,
      "DaysOfWeek": ["Monday", "Tuesday"]
  }
  

重复范围

有三种可能的重复范围类型： NoEnd、 EndDate和 Numbered。

• NoEnd

  NoEnd 范围会导致重复执行无限期地发生。

  properties	相关性	说明
  Type	必选	重复范围类型。 必须设置为 NoEnd。

• EndDate

  EndDate 范围会导致时间窗口在符合适用模式的所有日期发生，直到结束日期为止。

  properties	相关性	说明
  Type	必选	重复范围类型。 必须设置为 EndDate。
  EndDate	必选	停止应用模式的日期和时间。 如果最后一个匹配项的开始时间在结束日期之前，该匹配项的结束时间可能会超出该时间。

  在以下示例中，时间窗口每天重复到 2024 年 4 月 1 日的最后一次发生。

  "Start": "Fri, 22 Mar 2024 18:00:00 GMT",
  "End": "Fri, 22 Mar 2024 20:00:00 GMT",
  "Recurrence":{
      "Pattern": {
          "Type": "Daily",
          "Interval": 1
      },
      "Range": {
          "Type": "EndDate",
          "EndDate": "Mon, 1 Apr 2024 20:00:00 GMT"
      }
  }
  

• Numbered

  该 Numbered 范围导致时间窗口出现指定的次数。

  properties	相关性	说明
  Type	必选	重复范围类型。 必须设置为 Numbered。
  NumberOfOccurrences	必选	出现次数。

  在以下示例中，时间窗口在星期一和星期二重复，共发生三次，这些事件发生在以下日期：

  • 4 月 1 日星期一
  • 4 月 2 日星期二
  • 4 月 8 日星期一

  "Start": "Mon, 1 Apr 2024 18:00:00 GMT",
  "End": "Mon, 1 Apr 2024 20:00:00 GMT",
  "Recurrence":{
      "Pattern": {
          "Type": "Weekly",
          "Interval": 1,
          "DaysOfWeek": ["Monday", "Tuesday"]
      },
      "Range": {
          "Type": "Numbered",
          "NumberOfOccurrences": 3
      }
  }
  

若要创建重复规则，必须同时指定 Pattern 和 Range 设置。 任何模式类型都可以与任何范围类型一起使用。

高级：Start 属性的时区偏移量将应用于重复执行设置。

Microsoft.Targeting

此筛选器提供为目标受众启用某项功能的功能。 下面的目标定位部分将对目标定位进行深入解释。 筛选器参数包括一个 Audience 对象，该对象描述用户、组、已排除的用户/组，以及应该有权访问该功能的用户群的默认百分比。 Groups 部分中列出的每个组对象还必须指定应具有访问权限的组成员的百分比。 如果直接在 Exclusion 部分中指定了用户，或者该用户在排除的组中，则该功能将被禁用。 否则，如果用户直接在 Users 部分中指定，或者如果用户处于任何组推出中包含的百分比中，或者如果用户属于默认设定的推出百分比，则该用户将启用该功能。

"client_filters": [
    {
        "name": "Microsoft.Targeting",
        "parameters": {
            "Audience": {
                "Users": [
                    "Jeff",
                    "Alicia"
                ],
                "Groups": [
                    {
                        "Name": "Ring0",
                        "RolloutPercentage": 100
                    },
                    {
                        "Name": "Ring1",
                        "RolloutPercentage": 50
                    }
                ],
                "DefaultRolloutPercentage": 20,
                "Exclusion": {
                    "Users": [
                        "Ross"
                    ],
                    "Groups": [
                        "Ring2"
                    ]
                }
            }
        }
    }
]

目标

目标定位是一种功能管理策略，使开发人员能够逐步向其用户群推出新功能。 该策略建立在面向一组称为目标受众的用户的概念之上。 受众由特定用户、组、已排除的用户/组和占整个用户群的指定百分比的人数组成。 受众中包含的组可以进一步细分为其成员总数的百分比。

以下步骤演示了新“Beta 版”功能的渐进式推出示例：

1. 个人用户 Jeff 和 Alicia 有权访问 Beta 版。
2. 另一个用户 Mark 要求加入并包含在内。
3. Beta 版中包含名为“Ring1”用户的组的 20%。
4. Beta 版中包含的“Ring1”用户数高达 100%。
5. Beta 版中包含 5% 的用户群。
6. 推出百分比将提升到 100%，该功能已完全推出。

此用于推出功能的策略通过包含的 Microsoft.Targeting 功能筛选器内置到库中。

将用户设为目标

可以直接在 is_enabled 调用中指定用户，或者使用 TargetingContext 来指定用户及其可选的组。

# Directly specifying the user
result = is_enabled(feature_flags, "test_user")

# Using a TargetingContext
result = is_enabled(feature_flags, TargetingContext(user_id="test_user", groups=["Ring1"]))

目标排除

在定义受众时，可以将用户和组从受众中排除。 在将功能逐步发布给一组用户时，如果需要排除少数用户或用户组，排除项会非常有用。 通过将用户和组列表添加到访问群体 Exclusion 属性来定义排除。

"Audience": {
    "Users": [
        "Jeff",
        "Alicia"
    ],
    "Groups": [
        {
            "Name": "Ring0",
            "RolloutPercentage": 100
        }
    ],
    "DefaultRolloutPercentage": 0,
    "Exclusion": {
        "Users": [
            "Mark"
        ]
    }
}

在上面的示例中，为名为 Jeff 和 Alicia 的用户启用功能。 此外，还为名为 Ring0 的组中的用户启用该功能。 但是，如果用户命名为 Mark，则会禁用该功能，而不考虑其是否位于组 Ring0 中。 排除项优先于目标定位过滤器的其他部分。

变量

将新功能添加到应用程序时，有时某项功能具有多个不同的建议设计选项。 在进行设计决策时，一种常见的解决方案是采用某种形式的 A/B 测试。 A/B 测试通过向不同用户群体提供不同版本的功能，并根据用户交互来选择合适的版本。 在此库中，通过用变体表示功能的不同配置来启用此功能。

变体使功能标志变得不仅仅是一个简单的开/关标志。 变体表示功能标志的值，可以是字符串、数字、布尔值，甚至是配置对象。 用于声明变体的功能标志应定义每个变体的使用条件，这将在分配变体部分中进行更详细的介绍。

class Variant:
    def __init__(self, name: str, configuration: Any):
        self._name = name
        self._configuration = configuration

    @property
    def name(self) -> str:
        """
        The name of the variant.
        :rtype: str
        """
        return self._name

    @property
    def configuration(self) -> Any:
        """
        The configuration of the variant.
        :rtype: Any
        """
        return self._configuration

获取变体

对于每个功能，可以使用 FeatureManager 的 get_variant 方法检索变体。

…
variant = print(feature_manager.get_variant("TestVariants", TargetingContext(user_id="Adam"))

variantConfiguration = variant.configuration;

// Do something with the resulting variant and its configuration

返回的变体取决于当前正在评估的用户，并且该信息是从 TargetingContext 的实例中获取的。

变体功能标志声明

与普通功能标志相比，变体功能标志多了两个属性： variants 和 allocation。 variants 属性是一个数组，其中包含为此功能定义的变体。 allocation 属性定义为该功能分配这些变体的方式。 与声明普通功能标志类似，也可以在 JSON 文件中设置变体功能标志。 下面是一个变体功能标志的示例。

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyVariantFeatureFlag",
                "enabled": true,
                "allocation": {
                    "default_when_enabled": "Small",
                    "group": [
                        {
                            "variant": "Big",
                            "groups": [
                                "Ring1"
                            ]
                        }
                    ]
                },
                "variants": [
                    { 
                        "name": "Big"
                    },  
                    { 
                        "name": "Small"
                    } 
                ]
            }
        ]
    }
}

定义变体

每个变体都有两个属性：名称和配置。 名称用于引用特定变体，而配置则是该变体的值。 可以使用 configuration_value 属性设置配置。 configuration_value 是一种内联配置，可以是字符串、数字、布尔值或配置对象。 如果未指定 configuration_value，则返回的变体的 Configuration 属性将为 None。

已为 variants 属性下的每个功能定义所有可能的变体的列表。

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyVariantFeatureFlag",
                "variants": [
                    { 
                        "name": "Big", 
                        "configuration_value": {
                            "Size": 500
                        }
                    },  
                    { 
                        "name": "Small", 
                        "configuration_value": {
                            "Size": 300
                        }
                    } 
                ]
            }
        ]
    }
}

分配变体

分配功能变体的过程由该功能的 allocation 属性确定。

"allocation": { 
    "default_when_enabled": "Small", 
    "default_when_disabled": "Small",  
    "user": [ 
        { 
            "variant": "Big", 
            "users": [ 
                "Marsha" 
            ] 
        } 
    ], 
    "group": [ 
        { 
            "variant": "Big", 
            "groups": [ 
                "Ring1" 
            ] 
        } 
    ],
    "percentile": [ 
        { 
            "variant": "Big", 
            "from": 0, 
            "to": 10 
        } 
    ], 
    "seed": "13973240" 
},
"variants": [
    { 
        "name": "Big", 
        "configuration_value": "500px"
    },  
    { 
        "name": "Small", 
        "configuration_value": "300px"
    } 
]

功能的 allocation 设置具有以下属性：

如果功能未启用，功能管理器会将标记为 default_when_disabled 的变体分配给当前用户，在本例中为 Small。

如果启用了该功能，功能管理器会按顺序检查 user、group 和 percentile 分配，以确定要分配的变体。 对于此特定示例，如果接受评估的用户在名为 Ring1 的组中命名为 Marsha，或者该用户恰好位于 0 和第 10 个百分位数之间，则会将指定的变体分配给该用户。 在这种情况下，所有被分配的用户都会返回 Big 变体。 如果这些分配都不匹配，则会为用户分配 default_when_enabled 变体，它是 Small。

分配逻辑类似于 Microsoft.Targeting 功能筛选器，但有些参数在目标定位中存在，但在分配中不存在，反之亦然。 目标和分配的结果不相关。

使用变体替代已启用状态

可以使用变体来替代功能标志的已启用状态。 替代使变体有机会扩展功能标志的评估。 使用变体对标志调用 is_enabled 时，功能管理器将检查分配给当前用户的变体是否已配置为替代结果。 使用可选变量属性 status_override 进行覆盖。 默认情况下，此属性设置为 None，这意味着变体不会影响标志是被视为已启用还是已禁用。 将 status_override 设置为 Enabled 允许变体（选中时）替代要启用的标志。 将 status_override 设置为 Disabled 会提供相反的功能，因此在选择变体时会禁用标志。 enabled 状态为 false 的功能无法被覆盖。

如果你使用的是具有二进制变体的功能标志，status_override 属性会非常有用。 它使你能够在应用中继续使用诸如 is_enabled 之类的 API，同时还能受益于变体带来的新特性，例如百分比分配和种子。

{
    "id": "MyVariantFeatureFlag",
    "enabled": true,
    "allocation": {
        "percentile": [
            {
                "variant": "On",
                "from": 10,
                "to": 20
            }
        ],
        "default_when_enabled":  "Off",
        "seed": "Enhanced-Feature-Group"
    },
    "variants": [
        {
            "name": "On"
        },
        {
            "name": "Off",
            "status_override": "Disabled"
        }
    ]
}

在上面的示例中，始终启用该功能。 如果当前用户在计算出的第 10 到第 20 百分位数范围内，则会返回 On 变体。 否则，将返回 Off 变体，因为 status_override 等于 Disabled，因此该功能现在被视为已禁用。

遥测

部署功能标志更改时，分析其对应用程序的影响通常很重要。 例如，可能会出现以下几个问题：

• 我的标志是否按预期启用/禁用？
• 目标用户是否按预期获得对特定功能的访问权限？
• 特定用户看到的是哪个变体？

可以通过功能标志评估事件的发出和分析来回答这些类型的问题。 此库可以选择性地使 AzureMonitor 能够通过 OpenTelemetry 在功能标志评估期间生成跟踪遥测。

启用遥测

默认情况下，功能标志不发出遥测。 若要发布给定功能标志的遥测，该标志必须声明它已启用遥测发出。

对于在 JSON 中定义的功能标志，是通过使用 telemetry 属性来启用的。

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyFeatureFlag",
                "enabled": true,
                "telemetry": {
                    "enabled": true
                }
            }
        ]
    }
}

上述代码段定义了一个名为 MyFeatureFlag 的功能标志，表示已启用遥测。 telemetry 对象的 enabled 属性被设置为 true。 enabled 属性的值必须为 true 才能发布标志的遥测。

功能标志的 telemetry 部分具有以下属性：

此外，创建 FeatureManager 时，必须注册回调来处理遥测事件。 每当评估功能标志并为该标志启用遥测时，都会调用此回调。

feature_manager = FeatureManager(feature_flags, on_feature_evaluated=publish_telemetry)

Application Insights 遥测

功能管理库提供了一个内置的遥测发布器，用于将功能标志评估数据发送到 Application Insights。 要启用 Application Insights，可以通过 pip install FeatureManagement[AzureMonitor] 将功能管理库与 Azure Monitor 一起安装。 该命令会安装 azure-monitor-events-extension 包，用于通过 OpenTelemetry 将遥测数据格式化并发送到 Application Insights。

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
        connection_string="InstrumentationKey=00000000-0000-0000-0000-000000000000"
    )

自定义遥测发布

由于遥测回调是一个函数，因此可以对其进行自定义，将遥测发布到任何所需的目标。 例如，可以将遥测发布到日志服务、数据库或自定义遥测服务。

当评估某个功能标志且启用了遥测时，功能管理器会使用 EvaluationEvent 参数调用遥测回调。 EvaluationEvent 包含以下属性：

Next steps

若要了解如何在应用程序中使用功能标志，请继续阅读以下快速入门。

若要了解如何使用功能筛选器的信息，请继续学习以下教程。