{{< details >}}

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: JihuLab.com, 私有化部署

{{< /details >}}

使用功能标记，可以将应用程序的新功能以较小的批次部署到生产环境。您可以将功能在用户子集间打开和关闭，帮助您实现持续交付。功能标记有助于降低风险，允许您进行受控测试，并将功能交付与客户发布分离。

极狐 GitLab 中还有功能标记的完整列表。

{{< alert type=”note” >}}

要为极狐 GitLab 产品开发做贡献，请查看此功能标记内容。

{{< /alert >}}

如何运作

极狐 GitLab 提供了一个与 Unleash 兼容的功能标记 API。

通过在极狐 GitLab 中启用或禁用标记，您的应用程序可以确定要启用或禁用哪些功能。

您可以在极狐 GitLab 中创建功能标记，并使用来自应用程序的 API 来获取功能标记及其状态的列表。应用程序必须配置为与极狐 GitLab 通信，因此开发人员需要使用兼容的客户端库并将功能标记集成到您的应用程序中。

创建功能标记

要创建并启用功能标记：

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

要更改这些设置，请选择列表中任何功能标记旁的 编辑 ({{< icon name=”pencil” >}})。

功能标记的最大数量

极狐 GitLab 私有化部署每个项目的功能标记最大数量为 200。对于 JihuLab.com，最大数量由级别决定：

级别 每个项目的功能标记（JihuLab.com） 每个项目的功能标记（极狐 GitLab 私有化部署）
基础版 50 200
专业版 150 200
旗舰版 200 200

功能标记策略

您可以在多个环境中应用功能标记策略，而无需多次定义策略。

极狐 GitLab 功能标记基于 Unleash。在 Unleash 中，有用于细化功能标记控制的策略。极狐 GitLab 功能标记可以有多个策略，支持的策略包括：

策略可以在创建功能标记时添加到功能标记中，也可以在创建后通过导航到 部署 > 功能标记 并选择 编辑 ({{< icon name=”pencil” >}}) 来编辑现有功能标记。

所有用户

为所有用户启用功能。它使用标准 (default) Unleash 激活策略。

百分比发布

为一定比例的页面浏览启用功能，具有可配置的一致性行为。这种一致性也被称为粘性。它使用渐进发布 (flexibleRollout) Unleash 激活策略。

您可以配置一致性基于：

  • 用户 ID：每个用户 ID 都有一致的行为，忽略会话 ID。
  • 会话 ID：每个会话 ID 都有一致的行为，忽略用户 ID。
  • 随机：不保证一致行为。功能为随机选定的页面浏览比例启用。忽略用户 ID 和会话 ID。
  • 可用 ID：根据用户状态尝试一致行为：
    • 如果用户已登录，则根据用户 ID 保持行为一致。
    • 如果用户是匿名的，则根据会话 ID 保持行为一致。
    • 如果没有用户 ID 或会话 ID，则根据随机选定的页面浏览比例启用功能。

例如，设置基于 可用 ID 的 15% 值以启用 15% 页面浏览的功能。对于已认证用户，这是基于其用户 ID。对于拥有会话 ID 的匿名用户，则会基于其会话 ID，因为他们没有用户 ID。如果没有提供会话 ID，则回退到随机。

发布百分比可以从 0% 到 100%。

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

{{< alert type=”warning” >}}

选择 随机 为单个用户提供不一致的应用行为。

{{< /alert >}}

用户百分比

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

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

发布百分比可以从 0% 到 100%。

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

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

{{< alert type=”warning” >}}

如果选择用户百分比策略，则 Unleash 客户端 必须 提供用户 ID 才能启用功能。请参阅下面的 Ruby 示例。

{{< /alert >}}

用户 ID

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

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

{{< alert type=”warning” >}}

Unleash 客户端 必须 提供用户 ID 才能为目标用户启用功能。请参阅下面的 Ruby 示例。

{{< /alert >}}

用户列表

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

您无法为用户禁用特定功能，但可以通过为用户列表启用它来实现类似结果。

例如：

  • 完整用户列表 = 用户1A, 用户1B, 用户2A, 用户2B, 用户3A, 用户3B, ...
  • 完整用户列表，排除 B 用户 = 用户1A, 用户2A, 用户3A, ...

创建用户列表

要创建用户列表：

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

您可以通过选择列表旁边的 编辑 ({{< icon name=”pencil” >}}) 查看列表的用户 ID。 查看列表时，可以通过选择 编辑 ({{< icon name=”pencil” >}}) 重命名它。

将用户添加到用户列表

要将用户添加到用户列表：

  1. 在左侧边栏，选择 搜索或前往 并找到您的项目。
  2. 选择 部署 > 功能标记。
  3. 选择您要添加用户的列表旁边的 编辑 ({{< icon name=”pencil” >}})。
  4. 选择 添加用户。
  5. 输入用户 ID 作为逗号分隔的值列表。例如，user@example.com, user2@example.com 或 username1,username2,username3 等等。
  6. 选择 添加。

从用户列表中移除用户

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

  1. 在左侧边栏，选择 搜索或前往 并找到您的项目。
  2. 选择 部署 > 功能标记。
  3. 选择您要更改的列表旁边的 编辑 ({{< icon name=”pencil” >}})。
  4. 选择您要移除的 ID 旁边的 移除 ({{< icon name=”remove” >}})。

搜索代码引用

{{< details >}}

  • Tier: 专业版, 旗舰版
  • Offering: JihuLab.com, 私有化部署

{{< /details >}}

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

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

  1. 在左侧边栏，选择 搜索或前往 并找到您的项目。
  2. 选择 部署 > 功能标记。
  3. 编辑您要移除的功能标记。
  4. 选择 更多操作 ({{< icon name=”ellipsis_v” >}})。
  5. 选择 搜索代码引用。

为特定环境禁用功能标记

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

  1. 在左侧边栏，选择 搜索或前往 并找到您的项目。
  2. 选择 部署 > 功能标记。
  3. 对于您要禁用的功能标记，选择 编辑 ({{< icon name=”pencil” >}})。
  4. 要禁用标记：
    • 对于应用的每个策略，在 环境 下删除该环境。
  5. 选择 保存更改。

为所有环境禁用功能标记

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

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

功能标记显示在 已禁用 选项卡上。

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

要在您的应用程序中使用功能标记，请从极狐 GitLab 获取访问凭证。然后使用客户端库准备您的应用程序。

获取访问凭证

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

  1. 在左侧边栏，选择 搜索或前往 并找到您的项目。
  2. 选择 部署 > 功能标记。
  3. 选择 配置以查看以下内容：
    • API URL：客户端（应用程序）连接以获取功能标记列表的 URL。
    • 实例 ID：授权检索功能标记的唯一令牌。

    • 应用程序名称：应用程序运行的环境的名称（不是应用程序本身的名称）。

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

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

选择客户端库

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

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

Unleash 目前为各种语言和框架提供许多 SDK。

功能标记 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, "功能已启用\n")
    } else {
        io.WriteString(w, "你好，世界！\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 "你好，世界！"
end

Unleash Proxy 示例

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

您应该在 JihuLab.com 上为生产使用 Unleash Proxy。有关详细信息，请参阅性能说明。

要运行 Docker 容器以连接到您的项目功能标记，请运行以下命令：

docker run \
  -e UNLEASH_PROXY_SECRETS=<secret> \
  -e UNLEASH_URL=<project feature flags URL> \
  -e UNLEASH_INSTANCE_ID=<project feature flags instance ID> \
  -e UNLEASH_APP_NAME=<project environment> \
  -e UNLEASH_API_TOKEN=<tokenNotUsed> \
  -p 3000:3000 \
  unleashorg/unleash-proxy
变量 值
UNLEASH_PROXY_SECRETS 用于配置 Unleash Proxy 客户端的共享密钥。
UNLEASH_URL 您项目的 API URL。有关详细信息，请阅读获取访问凭证。
UNLEASH_INSTANCE_ID 您项目的实例 ID。有关详细信息，请阅读获取访问凭证。
UNLEASH_APP_NAME 应用程序运行的环境名称。有关详细信息，请阅读获取访问凭证。
UNLEASH_API_TOKEN 启动 Unleash Proxy 所需，但不用于连接极狐 GitLab。可以设置为任何值。

使用 Unleash Proxy 时有一个限制，即每个代理实例只能请求 UNLEASH_APP_NAME 中命名的环境的标记。代理将此发送给极狐 GitLab 代表客户端，这意味着客户端无法覆盖它。

与功能标记相关的议题

{{< details >}}

  • Tier: 专业版, 旗舰版
  • Offering: JihuLab.com,私有化部署

{{< /details >}}

您可以将相关议题链接到功能标记。在功能标记 链接议题 部分中，选择 + 按钮并输入议题参考编号或议题的完整 URL。议题然后显示在相关功能标记中，反之亦然。

此功能类似于链接议题功能。

性能因素

极狐 GitLab 功能标记可以用于任何应用程序。大型应用程序可能需要高级配置。此部分解释性能因素，以帮助您的组织识别使用此功能之前需要做什么。阅读如何运作部分，然后深入了解细节。

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

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

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

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

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

从网络错误中恢复

一般来说，Unleash 客户端有一个后备机制，当服务器返回错误代码时。例如，unleash-ruby-client 从本地备份读取标记数据，以便应用程序可以在当前状态下继续运行。

阅读 SDK 项目的文档以获取更多信息。

极狐 GitLab 私有化部署

在功能方面，没有区别。JihuLab.com 和极狐 GitLab 私有化部署表现相同。

在扩展性方面，这取决于极狐 GitLab 实例的规格。例如，JihuLab.com 使用 HA 架构，因此可以处理许多并发请求。然而，极狐 GitLab 私有化部署实例在性能不足的机器上无法提供可比的性能。有关更多信息，请参阅参考架构。