極狐GitLab 功能標志詳解

極狐GitLab 是 GitLab 在中國的發行版，關于中文參考文檔和資料有：

極狐GitLab 中文文檔
極狐GitLab 中文論壇
極狐GitLab 官網

功能標志 (BASIC ALL)

使用功能標志，您可以將應用程序的新功能小批量部署到生產環境中。您可以為部分用戶打開和關閉功能，幫助您實現持續交付。功能標志有助于降低風險，允許您進行受控測試，并將功能交付與客戶發布分開。

工作原理

極狐GitLab 使用 Unleash，一種功能切換服務。
通過在極狐GitLab 中啟用或禁用標志，您的應用程序可以確定啟用或禁用哪些功能。

您可以在極狐GitLab 中創建功能標志并使用應用程序中的 API 來獲取功能標志列表及其狀態。應用程序必須配置為與極狐GitLab 通信，因此開發人員可以使用兼容的客戶端庫并在您的應用程序中集成功能標志。

創建功能標志

要創建和啟用功能標志：

1.在左側邊欄中，選擇搜索或轉到并找到您的項目。
2.在左側邊欄中，選擇部署 > 功能標志。
3.選擇新建功能標志。
4.輸入名稱。以字母開頭且僅包含小寫字母、數字、下劃線（）或破折號（-），且不以破折號（-）或下劃線（）結尾。
5.可選。輸入說明（最多 255 個字符）。
6.添加功能標志策略，定義應如何應用標志。對于每個策略，包括類型（默認為所有用戶）和環境（默認為所有環境）。
7.選擇創建功能標志。

要更改這些設置，請在列表中的任何功能標志旁邊，選擇編輯 ({pencil})。

最大功能標志數

私有化部署實例上每個項目的最大功能標志數為 200。

功能標志策略

您可以跨多個環境應用功能標志策略，而無需多次定義策略。
極狐GitLab 功能標志使用 Unleash 作為功能標志引擎。在 Unleash 中，策略用于細粒度的功能標志控制。極狐GitLab 功能標志可以有多種策略，支持的策略有：

所有用戶
用戶百分比
用戶 ID
用戶列表

可以在創建功能標志時將策略添加到功能標志，或者在創建后通過導航到部署 > 功能標志并選擇編輯（{pencil}）來編輯現有功能標志。

所有用戶

為所有用戶啟用該功能，它使用標準（默認）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 選擇一致性的功能與用戶百分比推出功能相同。

WARNING:
選擇隨機將為個別用戶提供不一致的應用程序行為。

用戶百分比

為一定比例的經過身份驗證的用戶啟用該功能。它使用 Unleash 激活策略 gradualRolloutUserId。

例如，將值設置為 15% 可為 15% 的經過身份驗證的用戶啟用該功能。
上線百分比可以從 0% 到 100%。

粘性（同一用戶的一致應用行為）對登錄用戶有保證，但對匿名用戶則不保證。

請注意，具有基于用戶 ID 的一致性的上線百分比具有相同的行為。我們建議使用百分比部署，因為它比用戶百分比更靈活。

WARNING:
如果選擇了用戶百分比策略，則必須為 Unleash 客戶端提供一個用戶 ID 才能啟用該功能。請參閱下面的 Ruby 示例。

用戶 ID

為目標用戶列表啟用該功能。它是使用 Unleash UserIDs (userWithId) 激活策略。

以逗號分隔的值列表形式輸入用戶 ID（例如，user@example.com、user2@example.com 或 username1,username2,username3 等）。請注意，用戶 ID 是應用程序用戶的標識符。他們不需要是極狐GitLab 用戶。

WARNING:
Unleash 客戶端必須被賦予一個用戶 ID，以便為目標用戶啟用該功能。請參閱下面的 Ruby 示例。

用戶列表

為在功能標志 UI 中或使用功能標志用戶列表 API 創建的用戶列表啟用功能。

與用戶 ID 類似，它使用 Unleash UsersID (userWithId) 激活策略。
不可能禁用用戶列表成員的功能，但您可以通過為不包含排除用戶的用戶列表，啟用功能來實現相同的效果。
例如：

Full-user-list = User1A, User1B, User2A, User2B, User3A, User3B, …
Full-user-list-excluding-B-users = User1A, User2A, User3A, …

創建用戶列表

要創建用戶列表：

1.在左側邊欄中，選擇搜索或轉到并找到您的項目。
2.在左側邊欄中，選擇部署 > 功能標志。
3.選擇查看用戶列表
4.選擇新建用戶列表。
5.輸入列表名稱。
6.選擇創建。

您可以通過選擇列表旁邊的編輯 ({pencil}) 來查看列表的用戶 ID。查看列表時，您可以通過選擇編輯 ({pencil}) 對其進行重命名。

添加用戶到用戶列表

要將用戶添加到用戶列表：

1.在左側邊欄中，選擇搜索或轉到并找到您的項目。
2.在左側邊欄中，選擇部署 > 功能標志。
3.選擇要添加用戶的列表旁邊的編輯 ({pencil})。
4.選擇添加用戶。
5.以逗號分隔的值列表的形式輸入用戶 ID。例如，user@example.com、user2@example.com 或username1,username2,username3 等。
6.選擇添加。

從用戶列表刪除用戶

從用戶列表中刪除用戶：

1.在左側邊欄中，選擇搜索或轉到并找到您的項目。
2.在左側邊欄中，選擇部署 > 功能標志。
3.選擇要更改的列表旁邊的編輯 ({pencil})。
4.選擇要刪除的 ID 旁邊的刪除 ({remove})。

搜索代碼引用 (PREMIUM ALL)

搜索您的項目并在您的代碼中找到任何功能標志的引用，以便您在需要刪除功能標志時清理它。
要搜索功能標志的代碼引用：

1.在左側邊欄中，選擇搜索或轉到并找到您的項目。
2.在左側邊欄中，選擇部署 > 功能標志。
3.編輯要刪除的功能標志。
4.選擇更多操作 ({ellipsis_v})。
5.選擇搜索代碼引用。

禁用特定環境的功能標志

要禁用特定環境的功能標志：

1.在左側邊欄中，選擇搜索或轉到并找到您的項目。

2.在左側邊欄中，選擇部署 > 功能標志。

3.對于要禁用的功能標志，選擇編輯 ({pencil})。

4.禁用標志：

對每一種應用的策略，在環境下，刪除環境。

5.選擇保存修改。

為所有環境禁用功能標志

要為所有環境禁用功能標志：

1.在左側邊欄中，選擇搜索或轉到并找到您的項目。
2.在左側邊欄中，選擇部署 > 功能標志。
3.對于要禁用的功能標志，將狀態切換開關滑動到已禁用。

功能標志顯示在已禁用選項卡上。

將功能標志與您的應用程序集成

要在您的應用程序中使用功能標志，請從極狐GitLab 獲取訪問憑證。
然后使用客戶端庫準備您的應用程序。

獲取訪問憑證

要獲取您的應用程序與極狐GitLab 通信所需的訪問憑據：

1.在左側邊欄中，選擇搜索或轉到并找到您的項目。
2.在左側邊欄中，選擇部署 > 功能標志。
3.選擇配置查看以下內容：

API URL：客戶端（應用程序）連接以獲取功能標志列表的 URL。
實例 ID：授權檢索功能標志的唯一令牌。
應用程序名稱：應用程序運行的環境名稱（不是應用程序本身的名稱）。

例如，如果應用程序為生產服務器運行，應用程序名稱可以是 production 或類似名稱。該值用于環境 spec 評估。

請注意，這些字段的含義可能會隨著時間而改變。例如，我們不確定實例 ID 是分配給環境的單個令牌還是多個令牌。此外，應用程序名稱可以描述應用程序版本而不是運行環境。

選擇客戶端庫

極狐GitLab 實現了一個與 Unleash 客戶端兼容的后端。
使用 Unleash 客戶端，開發人員可以在應用程序代碼中定義標志的默認值。

如果提供的配置文件中不存在標志，則每個功能標志評估都可以表達所需的結果。

Unleash 目前為各種語言和框架提供了許多 SDK。

功能標志 API 文檔

對 API 內容，可以查看：

功能標志 API
功能標志用戶列表 API

Go 應用示例

以下是如何在 Go 應用程序中集成功能標志的示例：

package mainimport ("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"), // Set to the running environment of your applicationunleash.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 rubyrequire 'unleash'
require 'unleash/context'unleash = Unleash::Client.new({url: 'http://gitlab.com/api/v4/feature_flags/unleash/42',app_name: 'production', # Set to the running environment of your applicationinstance_id: '29QmjsW6KngPR5JNPMWx'
})unleash_context = Unleash::Context.new
# Replace "123" with the ID of an authenticated user.
# Note that the context's user ID must be a string:
# https://unleash.github.io/docs/unleash_context
unleash_context.user_id = "123"if unleash.is_enabled?("my_feature_name", unleash_context)puts "Feature enabled"
elseputs "hello, world!"
end

Unleash 代理示例

從 Unleash Proxy 0.2 版開始，代理與功能標志兼容。要運行 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 代理，但不用于連接到極狐GitLab。可以設置為任何值。

使用 Unleash 代理時存在一個限制，其中每個代理實例只能為 UNLEASH_APP_NAME 中命名的環境請求標志。Proxy 代表客戶端將其發送到極狐GitLab，客戶端無法覆蓋它。