Feature Flag 登記表範本(Feature Flag Register)#
參照標準:OpenFeature 規格(CNCF)
文件用途:登記每個 Feature Flag 的用途、擁有者、預設值與移除日期,避免旗標變成無人管理的技術債
適用階段:開發、部署與維運階段
範本版本:v2.0(2026-10-06)|對應《軟體開發標準程序教學手冊》v2.0 第 8.4 節
📋 章節目錄#
- 旗標登記
- 變更紀錄
- 清理檢查
- 審查與驗證
1. 旗標登記#
📝 範本#
| 旗標名稱 | 類型 | 用途 | 擁有者 | 預設值(安全值) | 目前狀態 | 建立日 | 預計移除日 |
|---|
| {kebab-case 名稱} | {發布/營運開關/實驗/權限} | {說明} | {姓名} | {值與理由} | {各環境狀態} | {日期} | {日期} |
📖 使用說明#
| 類型 | 用途 | 生命週期 |
|---|
| 發布(Release) | 隱藏未完成功能、逐步開放 | 短:全面開放後 30 天內移除 |
| 營運開關(Ops) | 緊急關閉高耗能或不穩定功能(Kill Switch) | 長:需定期確認仍需要 |
| 實驗(Experiment) | A/B 測試 | 實驗結束即移除 |
| 權限(Permission) | 依客戶或方案開放功能 | 長:視同產品設定 |
- 預設值必須是「安全」的行為(通常是舊流程或關閉):旗標服務故障時不得啟用未完成的功能
- 名稱用 kebab-case,描述行為而非人名或工單號
💡 範例#
| 旗標名稱 | 類型 | 用途 | 擁有者 | 預設值(安全值) | 目前狀態 | 建立日 | 預計移除日 |
|---|
new-leave-quota-check | 發布 | 新版特休額度檢查 | Tech Lead 王 | false(走舊檢查) | DEV on/UAT on/PRD 25% | 2026-09-20 | 2026-11-15 |
admin-xml-import | 營運開關 | 管理後台 XML 匯入(RA-2026-07 期間關閉) | 資安 李 | false | 全環境 off | 2025-03-01 | 不移除(每季確認) |
2. 變更紀錄#
📝 範本#
| 時間 | 旗標 | 環境 | 變更 | 執行者 | 核准者 | 原因 |
|---|
| {YYYY-MM-DD HH:MM} | {名稱} | {環境} | {舊值 → 新值} | {姓名} | {姓名} | {原因/工單} |
📖 使用說明#
- 正式環境的旗標變更等同上線,必須留稽核紀錄並經核准
- 優先使用旗標平台內建的稽核日誌,本表作為摘要
💡 範例#
| 時間 | 旗標 | 環境 | 變更 | 執行者 | 核准者 | 原因 |
|---|
| 2026-10-06 10:00 | new-leave-quota-check | PRD | 0% → 25% | DevOps 林 | PO 王 | 漸進開放(CHG-2026-118) |
3. 清理檢查#
📝 範本#
| 旗標名稱 | 是否已全面開放或廢止 | 程式中引用處 | 清理 PR | 狀態 |
|---|
| {名稱} | {是/否} | {檔案:行數} | {PR 連結} | {待清理/已移除} |
📖 使用說明#
- 每個 Sprint 檢查過期的旗標;移除旗標時同時刪除舊流程程式碼與對應測試
- 長期不清理的旗標會產生無法測試的組合,並增加事故風險
💡 範例#
| 旗標名稱 | 是否已全面開放或廢止 | 程式中引用處 | 清理 PR | 狀態 |
|---|
leave-attachment-v2 | 是(2026-08-01 起 100%) | LeaveController.java:88、LeaveService.java:142 | #1301 | 已移除 |
4. 審查與驗證#
本節供審查者使用,也用來檢查 AI 依本範本產出的登記表是否正確。
自動檢查#
| 檢查項目 | 方法 |
|---|
| 程式中的旗標都已登記 | grep -rhoE "get(Boolean|String|Integer)Value\(\"[a-z0-9-]+\"" src/ 擷取旗標名稱,與本表比對 |
| 過期旗標 | CI 比對「預計移除日」已過但程式仍引用的旗標,輸出警告 |
| 兩種狀態都有測試 | 每個發布型旗標至少有開啟與關閉各一個測試 |
人工審查問題#
- 預設值是否為安全的行為?
- 每個旗標都有擁有者與移除日期嗎?
- 正式環境的變更是否有核准紀錄?
- 是否有長期 100% 開啟卻未清理的旗標?
AI 常見錯誤#
- 預設值設為
true,旗標服務故障時啟用未完成功能。 - 未登記移除日期。
- 移除旗標時只改設定,未刪除舊流程程式碼。
📌 範本使用注意事項
- 程式中只依賴 OpenFeature API,旗標平台可替換
- 搭配「部署指引範本」「回滾計畫範本」使用:旗標是比回滾更快的止血手段