跳到內容
FortressFlag Docs

Node.js 快速入門

幾分鐘之內，你的 Node 服務就會在行程內評估 feature flags：每次檢查不走網路、你的請求路徑上沒有延遲，一次輪詢服務你的行程處理的每一個請求。

零執行期相依：這個套件的 dependencies 區塊根本不存在，而且會一直保持這樣。

1. 安裝

Section titled “1. 安裝”

這個 SDK 放在 GitHub 上的公開儲存庫裡，直接從那裡安裝，並固定在發布版本：

Terminal window
npm install github:FortressFlag/FortressFlag_SDK_node#v1.0.0

省略 #v1.0.0 就會改為追蹤 development 分支，試一個修正時很方便，但不是你在正式環境想要的。

這個套件是純 ESM。在 Node 22 及之後的版本，CommonJS 程式碼也可以用普通的 require("@fortressflag/sdk-node") 載入它。

2. 伺服器金鑰：貨真價實的機密

Section titled “2. 伺服器金鑰：貨真價實的機密”

這個 SDK 使用伺服器金鑰（ffs_…），它和行動與 Web SDK 隨附出貨的用戶端金鑰正好相反：它可以下載你的完整 ruleset，包含鎖定規則。把它完全當成資料庫密碼來對待：環境變數或機密管理器，永遠不放進程式碼、永遠不放進儲存庫、永遠不放進日誌。兩類金鑰，並排比較。

3. 啟動用戶端

Section titled “3. 啟動用戶端”
import { create } from "@fortressflag/sdk-node";


let client;
try {
  client = create({ key: process.env.FF_SERVER_KEY });
} catch (error) {
  // SDK 唯一會拋出例外的地方：格式錯誤的金鑰，在任何東西開始提供之前。
  console.error(error);
  process.exit(1);
}


await client.start(AbortSignal.timeout(15_000)); // 在第一份 ruleset 到達（或期限到了）時解析


// ... 你的服務執行；flag 檢查現在是記憶體內的函式呼叫。

start 永遠不會被拒絕：如果第一次抓取無法及時完成，用戶端會在背景持續重試，而你的呼叫者在此期間拿到他們的回退值。而且輪詢器永遠不會讓你的行程一直活著：你的程式碼結束時，Node 照常退出。

4. 評估一個 flag

Section titled “4. 評估一個 flag”
const enabled = client.bool(
  "new-checkout",
  {
    key: "user-42", // 你的穩定內容鍵：使用者 id、工作階段 id，由你決定
    tags: { cohort: "beta" },
  },
  false, // flag 未知或從未抓取到任何東西時的回退值
);

client.string 和 client.number 的用法一樣。內容 key 是百分比發布分桶的依據：始終傳入同一個識別碼，每位使用者就會得到穩定的分群。那是你的資料：SDK 永遠不驗證、不儲存、也不記錄它。

就這樣，你的服務正在本地評估 flag。儀表板的變更會在大約一分鐘內送達每一個行程。

評估永遠不會失敗

Section titled “評估永遠不會失敗”

bool、string 和 number 永遠會回答，永遠不會拋出例外：flag 出問題絕不能拖垮你的服務。重新啟動的行程在第一次抓取完成之前提供你呼叫處的回退值（或者在設定裡指定 cachePath，把最後一份 ruleset 持久化到你選的檔案，重新啟動就會立即從它恢復）。就連被撤銷的金鑰也不會弄壞任何東西：SDK 會繼續用它最後下載的 ruleset 評估，直到你交給它一把新金鑰。

接下來

Section titled “接下來”