功能开关

通过功能开关，你可以将应用的新功能以更小的批次部署到生产环境。你可以对部分用户开启或关闭某个功能，帮助你实现持续交付。功能开关有助于降低风险，让你能够进行受控测试，并将功能交付与客户发布分开。

GitLab 中也有完整的功能开关列表。

要查看功能开关的实际示例，请参阅Eliminating risk with feature flags。

要查看点击演示，请参阅Feature Flags。

使用功能开关

GitLab 为功能开关提供了兼容 Unleash 的 API。

通过在 GitLab 中启用或禁用某个标志，你的应用可以决定启用或禁用哪些功能。

你可以在 GitLab 中创建功能开关，并使用应用的 API 获取功能开关及其状态的列表。应用必须配置为与 GitLab 通信，因此开发者需要使用兼容的客户端库并将功能开关集成到你的应用中。

创建功能开关

要创建并启用功能开关：

1. 在左侧边栏中，选择“搜索或前往”并找到你的项目。
2. 选择“部署 > 功能开关”。
3. 选择“新建功能开关”。
4. 输入一个以字母开头且仅包含小写字母、数字、下划线（）或短横线（-），并且不以短横线（-）或下划线（）结尾的名称。
5. 可选。输入描述（最多 255 个字符）。
6. 添加功能开关策略，定义该开关应如何应用。对于每个策略，包括类型（默认为所有用户）和环境（默认为所有环境）。
7. 选择“创建功能开关”。

要更改这些设置，请在列表中选择任意功能开关旁边的编辑（ ）。

功能开关的最大数量

GitLab 自托管项目中每个项目的功能开关最大数量为 200。对于 GitLab.com，最大数量由tier决定：

功能开关策略

你可以将功能开关策略应用于多个环境，而无需多次定义该策略。

GitLab 功能开关基于 Unleash。在 Unleash 中，有strategies 用于细粒度的功能开关控制。GitLab 功能开关可以有多个策略，支持的策略包括：

• 所有用户
• 百分比用户
• 用户 ID
• 用户列表

策略可在创建功能开关时添加到功能开关中，或在创建后通过导航至部署 > 功能开关并选择编辑（ ）来编辑现有功能开关。

所有用户

启用该功能的所有用户。它使用标准（default）Unleash 激活strategy。

百分比发布（Percent Rollout）

为一定比例的页面浏览量启用功能，并提供可配置的行为一致性。这种一致性也被称为粘性（stickiness）。它使用渐进式发布（flexibleRollout）Unleash激活策略。

你可以将一致性配置为基于以下内容：

• 用户ID：每个用户ID都有稳定的行为，忽略会话ID。
• 会话ID：每个会话ID都有稳定的行为，忽略用户ID。
• 随机：不保证行为一致性。功能会按选定的百分比随机启用，忽略用户ID和会话ID。
• 可用ID：尝试根据用户状态实现行为一致性：
  • 如果用户已登录，基于用户ID保持行为一致。
  • 如果用户是匿名用户，基于会话ID保持行为一致。
  • 如果没有用户ID或会话ID，则功能会按选定百分比随机启用。

例如，设置为15%基于可用ID来为15%的页面浏览量启用功能。对于认证用户，这基于他们的用户ID；对于有会话ID的匿名用户，则会基于其会话ID（因为他们没有用户ID）；如果没有提供会话ID，就会回退到随机模式。

发布百分比范围为0%到100%。

选择基于用户ID的一致性与用户百分比发布的功能相同。

用户百分比（Percent of Users）

为一定比例的认证用户启用功能。它使用Unleash激活策略gradualRolloutUserId。

例如，设置为15%来为15%的认证用户启用功能。

发布百分比范围为0%到100%。

粘性（同一用户的稳定应用行为）对认证用户有保证，但对匿名用户没有。

百分比发布中基于用户ID的一致性行为相同。我们建议使用百分比发布，因为它比用户百分比更灵活。

用户ID（User IDs）

为目标用户列表启用功能。它通过Unleash UserIDs (userWithId)激活策略实现。

以逗号分隔的值列表形式输入用户ID（例如，user@example.com, user2@example.com，或username1,username2,username3等）。用户ID是应用程序用户的标识符，不需要是GitLab用户。

用户列表（User List）

为在功能标志UI中创建的用户列表，或通过功能标志用户列表API创建的列表启用功能。与用户ID类似，它使用Unleash UsersIDs (userWithId)激活策略。

您不能禁用特定用户的功能，但可以通过为用户列表启用功能来实现类似效果。

例如：

• 完整用户列表 = User1A, User1B, User2A, User2B, User3A, User3B, ...
• 排除B用户的完整用户列表 = User1A, User2A, User3A, ...

创建用户列表

要创建用户列表：

1. 在左侧边栏，选择搜索或前往并找到您的项目。
2. 选择部署 > 功能标志。
3. 选择查看用户列表。
4. 选择新建用户列表。
5. 输入列表名称。
6. 选择创建。

您可以通过点击旁边的编辑（ ）查看列表的用户ID。当查看列表时，您可以点击编辑（ ）重命名它。

向用户列表添加用户

要向用户列表添加用户：

1. 在左侧边栏，选择搜索或前往并找到您的项目。
2. 选择部署 > 功能标志。
3. 选择要添加用户的列表旁边的编辑（ ）。
4. 选择添加用户。
5. 以逗号分隔的值列表形式输入用户ID。例如，user@example.com, user2@example.com，或username1,username2,username3等。
6. 选择添加。

从用户列表中移除用户

若要从用户列表中移除用户：

1. 在左侧边栏中，选择「搜索或前往」并找到您的项目。
2. 选择「部署 > 功能标记」。
3. 选择您要修改的列表旁边的「编辑」（ ）。
4. 选择您要移除的ID旁边的「移除」（ ）。

搜索代码引用

若要在清理期间从代码中移除功能标记，请查找任何对它的项目引用。

若要搜索功能标记的代码引用：

1. 在左侧边栏中，选择「搜索或前往」并找到您的项目。
2. 选择「部署 > 功能标记」。
3. 编辑您要移除的功能标记。
4. 选择「更多操作」（ ）。
5. 选择「搜索代码引用」。

为特定环境禁用功能标记

若要为特定环境禁用功能标记：

1. 在左侧边栏中，选择「搜索或前往」并找到您的项目。
2. 选择「部署 > 功能标记」。
3. 对于您要禁用的功能标记，选择「编辑」（ ）。
4. 若要禁用该标记：
   • 对于它应用的每个策略，在「环境」下删除该环境。
5. 选择「保存更改」。

为所有环境禁用功能标记

若要为所有环境禁用功能标记：

1. 在左侧边栏中，选择「搜索或前往」并找到您的项目。
2. 选择「部署 > 功能标记」。
3. 对于您要禁用的功能标记，将状态切换开关滑动到「已禁用」。

该功能标记会显示在「已禁用」选项卡上。

将功能标记与您的应用程序集成

若要将功能标记用于您的应用程序，需从 GitLab 获取访问凭证。然后使用客户端库准备您的应用程序。

获取访问凭证

若要获取您的应用程序与 GitLab 通信所需的访问凭证：

1. 在左侧边栏中，选择「搜索或前往」并找到您的项目。
2. 选择「部署 > 功能标记」。
3. 选择「配置」以查看以下内容：

   • 「API URL」：客户端（应用程序）连接以获取功能标记列表的 URL。

   • 「实例 ID」：授权检索功能标记的唯一令牌。

   • 「应用名称」：应用程序运行的环境名称（而非应用程序本身的名称）。

     例如，如果应用程序在生产服务器上运行，「应用名称」可以是 production 或类似的值。此值用于环境规范评估。

这些字段的意义可能会随时间变化。例如，我们不确定「实例 ID」是单个令牌还是多个令牌，分配给「环境」。此外，「应用名称」可能描述应用程序版本而不是运行环境。

选择客户端库

GitLab 实现了一个兼容 Unleash 客户端的单一后端。

通过 Unleash 客户端，开发人员可以在应用程序代码中定义标志的默认值。每个功能标记评估都可以表达所需的结果，如果该标志不在提供的配置文件中。

Unleash 目前提供了适用于各种语言和框架的许多 SDK。

功能标记 API 信息

有关 API 内容，请参阅：

• 功能标记 API
• 功能标记用户列表 API

Go 应用程序示例

以下是如何在 Go 应用程序中集成功能标记的示例：

package main

import (
    "io"
    "log"
    "net/http"

    "github.com/Unleash/unleash-client-go/v3"
)

type metricsInterface struct {
}

func init() {
    unleash.Initialize(
        unleash.WithUrl("https://gitlab.com/api/v4/feature_flags/unleash/42"),
        unleash.WithInstanceId("29QmjsW6KngPR5JNPMWx"),
        unleash.WithAppName("production"), // 设置为您应用程序的运行环境
        unleash.WithListener(&metricsInterface{}),
    )
}

func helloServer(w http.ResponseWriter, req *http.Request) {
    if unleash.IsEnabled("my_feature_name") {
        io.WriteString(w, "Feature enabled\n")
    } else {
        io.WriteString(w, "hello, world!\n")
    }
}

func main() {
    http.HandleFunc("/", helloServer)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

Ruby应用示例

以下是如何在Ruby应用中集成功能开关的示例。

Unleash客户端会获取一个用户ID，用于百分比发布（已登录用户）发布策略或目标用户列表。

#!/usr/bin/env ruby

require 'unleash'
require 'unleash/context'

unleash = Unleash::Client.new({
  url: 'http://gitlab.com/api/v4/feature_flags/unleash/42',
  app_name: 'production', # 设置为应用的运行环境
  instance_id: '29QmjsW6KngPR5JNPMWx'
})

unleash_context = Unleash::Context.new

# 将 "123" 替换为已认证用户的ID。

# 上下文的用户ID必须是字符串：

# https://unleash.github.io/docs/unleash_context
unleash_context.user_id = "123"

if unleash.is_enabled?("my_feature_name", unleash_context)
  puts "功能已启用"
else
  puts "hello, world!"
end

Unleash代理示例

从Unleash Proxy版本0.2开始，该代理与功能开关兼容。

在生产环境中使用GitLab.com时，应使用Unleash Proxy。有关详情，请参阅性能注意事项。

若要通过Docker容器连接到项目的功能开关，请运行以下命令：

docker run \
  -e UNLEASH_PROXY_SECRETS=<secret> \
  -e UNLEASH_URL=<项目功能开关URL> \
  -e UNLEASH_INSTANCE_ID=<项目功能开关实例ID> \
  -e UNLEASH_APP_NAME=<项目环境> \
  -e UNLEASH_API_TOKEN=<tokenNotUsed> \
  -p 3000:3000 \
  unleashorg/unleash-proxy

使用Unleash Proxy时存在一个限制：每个代理实例只能请求UNLEASH_APP_NAME所命名环境的功能开关。代理代表客户端向GitLab发送此信息，这意味着客户端无法覆盖它。

功能开关相关问题

你可以将相关的问题关联到功能开关上。在功能开关的关联问题部分，选择+按钮并输入问题的引用编号或完整URL。这些问题随后会出现在相关的功能开关以及反向关联中。

此功能类似于关联问题功能。

性能因素

GitLab功能开关可用于任何应用。大型应用可能需要高级配置。 本节解释了影响性能的因素，帮助你的组织在使用前确定需要做什么。 更多信息，请参见使用功能开关。

应用程序节点支持的最大客户端数量

GitLab会尽可能接受来自客户端的请求，直到达到速率限制。 功能开关API被视为未认证流量（来自给定IP地址）。对于GitLab.com，请参阅GitLab.com特定限制。

轮询频率可在SDK中配置。假设所有客户端都从同一IP请求：

• 每分钟请求一次 … 可支持500个客户端。
• 每15秒请求一次 … 可支持125个客户端。

对于寻求更可扩展解决方案的应用，应使用Unleash Proxy。 在GitLab.com上，应使用Unleash Proxy以减少跨端点被速率限制的可能性。 该代理服务器位于服务器和客户端之间。它会代表客户端组向服务器发出请求，从而大幅减少出站请求数量。如果仍收到429响应，请在Unleash Proxy中增加UNLEASH_FETCH_INTERVAL的值。

目前还有一个问题旨在提升当前速率限制的容量。

从网络错误中恢复

一般来说，Unleash 客户端在服务器返回错误代码时具有回退机制。 例如，unleash-ruby-client会从本地备份读取标志数据，以便应用程序能够保持当前状态运行。

有关更多信息，请参阅 SDK 项目中的文档。

GitLab 自托管

功能上没有区别。GitLab.com 和 GitLab Self-Managed 的行为相同。

就可扩展性而言，这取决于 GitLab 实例的规格。 例如，GitLab.com 使用高可用架构，因此可以处理许多并发请求。然而，配置不足的机器上的 GitLab Self-Managed 实例无法提供可比的性能。 有关更多信息，请参见参考架构。