Build a Simple Node.js Feature Flags Service: Deterministic Toggle Rollbacks

本文为原文前 6,000 字符的节选翻译，完整内容请查看原文。

Short answer: Build a small Node.js service around versioned flag snapshots, deterministic toggle evaluation, and one decision event per game AI turn; fail closed for risky behavior so rollback remains safe. The operational constraint changes the design: a toggle must remain safe when the AI loop is slow, expensive, or being rolled back during a live game event.

简短回答：围绕版本化标志快照、确定性切换评估以及每个游戏 AI 回合一个决策事件构建一个小型 Node.js 服务；针对风险行为采取“故障关闭”（fail closed）策略，以确保回滚安全。操作约束改变了设计：当 AI 循环缓慢、昂贵或在实时游戏事件中被回滚时，切换必须保持安全。

Keep the first service small. Store a versioned flag document, evaluate it deterministically, and emit one structured decision record for every agent turn. That is enough to build a simple Node.js feature flag service without turning the control plane into a second game backend. The important boundary is this: a flag service decides which behavior a request may use; it does not own the request’s retry policy, model call, or billing ledger.

保持第一个服务精简。存储一份版本化的标志文档，进行确定性评估，并为每个智能体回合发出一条结构化的决策记录。这足以构建一个简单的 Node.js 功能标志服务，而无需将控制平面变成第二个游戏后端。重要的界限在于：标志服务决定请求可以使用哪种行为；它不负责请求的重试策略、模型调用或计费账本。

I have seen scheduled work fail because a toggle was treated as configuration instead of an operational dependency. The fix is boring: cache the last known-good document, make evaluation fail closed for risky behavior, and make rollback a single version change. How can a Node.js feature flags service keep toggle decisions reversible? For a game AI experiment, a decision record should answer five questions: which flag was evaluated, for which game and player cohort, against which configuration version, with what result, and how long the evaluation took.

我曾见过预定任务失败，因为切换被当作配置而非操作依赖项来处理。解决方法很枯燥：缓存最后已知的良好文档，使评估在面对风险行为时“故障关闭”，并将回滚简化为单一版本变更。Node.js 功能标志服务如何保持切换决策的可逆性？对于游戏 AI 实验，决策记录应回答五个问题：评估了哪个标志、针对哪个游戏和玩家群体、基于哪个配置版本、结果如何，以及评估耗时多久。

A boolean alone cannot explain why an agent suddenly started taking a slower path. Use a small representation. A flag can have a key, an enabled value, an audience rule, and an expiry. The service should reject an unknown key rather than silently inventing a default. It should also reject malformed audience input before publishing a new version; a bad rule is a rollout problem, not a request-time surprise.

仅凭一个布尔值无法解释为什么智能体突然开始走较慢的路径。使用一种小型的表示方式。一个标志可以包含键、启用值、受众规则和过期时间。服务应拒绝未知键，而不是静默地创建一个默认值。它还应在发布新版本之前拒绝格式错误的受众输入；错误的规则是发布问题，而不是请求时的意外。

The reader asked for a Node.js service, but the contract matters more than the framework. The evaluation function needs only an immutable snapshot, a key, and a clock. The handler can parse and validate input, load the snapshot, evaluate it, and record the result. Keeping those steps separate makes unit tests useful without starting an HTTP server.

读者要求的是 Node.js 服务，但契约比框架更重要。评估函数只需要一个不可变快照、一个键和一个时钟。处理程序可以解析并验证输入、加载快照、评估它并记录结果。将这些步骤分开，使得单元测试无需启动 HTTP 服务器即可发挥作用。

A minimal implementation has a Snapshot containing a version and a map of flag keys to booleans. Evaluate reads the requested key, returns an error for an unknown key, and returns a Decision containing the key, value, snapshot version, and elapsed evaluation time. In Node.js, the same contract can be implemented with a plain object and a function that returns a Promise-free result; the important property is deterministic evaluation, not a framework abstraction.

最小化实现包含一个快照，其中包含版本和标志键到布尔值的映射。Evaluate 读取请求的键，对未知键返回错误，并返回一个包含键、值、快照版本和评估耗时的 Decision 对象。在 Node.js 中，同样的契约可以用普通对象和一个返回非 Promise 结果的函数来实现；重要的属性是确定性评估，而不是框架抽象。

package flags
import "fmt"
type Snapshot struct {
    Version uint64
    Flags map[string]bool
}
func Evaluate(snapshot Snapshot, key string) (bool, error) {
    enabled, ok := snapshot.Flags[key]
    if !ok {
        return false, fmt.Errorf("unknown flag %q", key)
    }
    return enabled, nil
}

My first design instinct is usually to add rollout rules immediately. The safer sequence is smaller: prove that one immutable snapshot can be evaluated and rolled back, then add cohorts only when their assignment and audit fields are defined. Tests should cover an unknown key, an expired rule, a disabled flag, and two evaluations with the same snapshot producing the same result. They should not depend on wall-clock timing except for checking that a duration is present. Keep the handler thin; validation and evaluation should be callable without an HTTP server.

我最初的设计直觉通常是立即添加发布规则。更安全的顺序是循序渐进：先证明一个不可变快照可以被评估和回滚，然后仅在定义了分配和审计字段后才添加群体。测试应涵盖未知键、过期规则、禁用标志，以及使用相同快照进行的两次评估产生相同结果的情况。除了检查是否存在持续时间外，测试不应依赖挂钟时间。保持处理程序精简；验证和评估应在没有 HTTP 服务器的情况下即可调用。

Where should latency and cost be measured? Measure the toggle lookup separately from the agent work. Put a trace or log event around flag evaluation, then attach the selected flag version to the span that covers retrieval, tool calls, and model inference. OpenTelemetry treats logs as a signal with structured records and correlation fields; use that shape rather than writing an unsearchable sentence to stdout.

延迟和成本应该在哪里测量？将切换查找与智能体工作分开测量。在标志评估周围放置跟踪或日志事件，然后将选定的标志版本附加到涵盖检索、工具调用和模型推理的跨度（span）中。OpenTelemetry 将日志视为带有结构化记录和关联字段的信号；使用这种形式，而不是向标准输出写入无法搜索的句子。

For each agent turn, record elapsed milliseconds, input and output token counts when the model exposes them, tool-call count, and the final decision version. Cost is a derived operational metric, so keep the raw quantities too. A price estimate can change; the event should still explain what happened. I keep the event schema deliberately narrow. An event can contain event name agent.flag_decision, flag planner_v2, enabled true, snapshot_version 42, game_id g-1842, latency_ms 3, model_latency_ms 812, and tool_calls 2.

对于每个智能体回合，记录经过的毫秒数、模型暴露时的输入和输出 Token 计数、工具调用次数以及最终决策版本。成本是一个派生的操作指标，因此也要保留原始数量。价格估算可能会变；但事件仍应解释发生了什么。我特意保持事件模式的狭窄。一个事件可以包含事件名称 agent.flag_decision、标志 planner_v2、启用 true、快照版本 42、游戏 ID g-1842、延迟 3 毫秒、模型延迟 812 毫秒以及工具调用 2 次。

These concrete values make a useful test fixture, not a benchmark claim. The game_id should be treated as an application identifier with an explicit retention policy, not as a license to log arbitrary player data. Sampling can reduce volume for healthy traffic, but rollback analysis needs complete decisions for the affected cohort. Keep those records long enough to compare the old and new behavior. Short logs are easier to trust.

这些具体值构成了一个有用的测试夹具，而不是基准测试声明。game_id 应被视为具有明确保留策略的应用程序标识符，而不是记录任意玩家数据的许可。采样可以减少健康流量的数据量，但回滚分析需要受影响群体的完整决策记录。保留这些记录的时间要足够长，以便比较新旧行为。简短的日志更容易被信任。

The rollback test should be more specific than “the flag turns off.” Start with snapshot 41 active on two application instances. Publish snapshot 42 with the experimental planner enabled, then make one instance lose contact with the control plane while a request is evaluating the flag. The expected result is that the instance continues using its last valid snapshot, records version 41, and does not claim that version 42 was applied.

回滚测试应比“标志关闭”更具体。从两个应用程序实例上激活快照 41 开始。发布启用了实验性规划器的快照 42，然后让一个实例在请求评估标志时与控制平面失去联系。预期的结果是该实例继续使用其最后有效的快照，记录版本 41，并且不声称应用了版本 42。

Next, move the active pointer back to 41 and check the other instance: new requests should stop selecting the experimental planner within the documented refresh bound, while the request already in flight may finish under its original decision. Finally, restore the connection and verify that the stale instance rejects a malformed candidate before it replaces version 41. This sequence checks atomic publication, stale-read policy, auditability, and the distinction between decision latency and model latency in one run. It also gives the on-call engineer a useful question to ask during a live rollback: which snapshot did this request actually evaluate? If the answer is absent from the event, the service has lost the evidence needed to distinguish propagation d

接下来，将活动指针移回 41 并检查另一个实例：新请求应在文档规定的刷新范围内停止选择实验性规划器，而已经在运行的请求可能会在其原始决策下完成。最后，恢复连接并验证过时的实例在替换版本 41 之前拒绝格式错误的候选版本。此序列在一次运行中检查了原子发布、过时读取策略、可审计性以及决策延迟与模型延迟之间的区别。它还为值班工程师在实时回滚期间提供了一个有用的问题：此请求实际评估了哪个快照？如果事件中缺少答案，服务就丢失了区分传播所需的证据。