特性开关与渐进发布

// 最朴素的开关：一个配置项 + 一个 if
if (_options.EnableNewCheckout)
{
    return await _newCheckout.ProcessAsync(order);
}
return await _legacyCheckout.ProcessAsync(order);

// 用枚举明确开关类型，让治理脚本能按类型施加不同策略
public enum FlagKind
{
    Release,   // 发布开关：必须有 owner 与过期日
    Experiment,// 实验开关：必须关联实验编号
    Ops,       // 运维开关：长期保留，变更需审批
    Permission // 权限开关：与租户能力表同源
}

public sealed record FeatureFlagDefinition(
    string Name,
    FlagKind Kind,
    bool DefaultValue,
    string Owner,
    DateOnly? ExpiresOn,
    IReadOnlyList<FlagRule>? Rules = null);

// 规则模型：按顺序求值，命中即返回
public sealed record FlagRule(
    int Priority,
    string? TenantId = null,
    string? UserId = null,
    double? PercentageRollout = null,
    bool Value = true,
    string? Segment = null);

// 粘性哈希：userId + flagName 决定分桶，用户始终落在同一边
public static bool IsInRollout(string userId, string flagName, double percentage)
{
    var input = $"{flagName}:{userId}";
    var hash = System.Security.Cryptography.SHA256.HashData(
        System.Text.Encoding.UTF8.GetBytes(input));
    // 取前 4 字节转无符号整数，映射到 [0, 100)
    var bucket = BitConverter.ToUInt32(hash, 0) % 100;
    return bucket < percentage;
}

// 规则求值器：优先级从高到低，第一个命中的规则决定结果
public bool Evaluate(FeatureFlagDefinition flag, EvaluationContext ctx)
{
    if (flag.Rules is null) return flag.DefaultValue;

    foreach (var rule in flag.Rules.OrderBy(r => r.Priority))
    {
        if (rule.TenantId is not null && rule.TenantId != ctx.TenantId) continue;
        if (rule.UserId is not null && rule.UserId != ctx.UserId) continue;
        if (rule.Segment is not null && !ctx.Segments.Contains(rule.Segment)) continue;
        if (rule.PercentageRollout is { } pct &&
            !IsInRollout(ctx.UserId ?? ctx.TenantId ?? "anonymous", flag.Name, pct))
            continue;

        return rule.Value;   // 命中即返回
    }
    return flag.DefaultValue;
}

// 后台服务：定时拉取 + 变更推送，把快照写入内存
public sealed class FlagSyncService(
    IFlagProvider provider,
    IFeatureFlagStore store,
    ILogger<FlagSyncService> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        await RefreshAsync(ct);              // 启动时先拉一次，保证可用
        using var timer = new PeriodicTimer(TimeSpan.FromSeconds(30));
        while (await timer.WaitForNextTickAsync(ct))
        {
            try { await RefreshAsync(ct); }
            catch (Exception ex) { logger.LogWarning(ex, "开关同步失败，继续用本地快照"); }
        }
    }

    private async Task RefreshAsync(CancellationToken ct)
    {
        var flags = await provider.GetAllAsync(ct);
        store.Replace(flags);                 // 原子替换整个快照
    }
}

// 本地存储：不可变字典 + 原子引用替换，读无锁
public sealed class FeatureFlagStore : IFeatureFlagStore
{
    private volatile IReadOnlyDictionary<string, FeatureFlagDefinition> _snapshot
        = new Dictionary<string, FeatureFlagDefinition>();

    public void Replace(IReadOnlyDictionary<string, FeatureFlagDefinition> next)
        => _snapshot = next;   // 引用赋值是原子的

    public FeatureFlagDefinition? Find(string name)
        => _snapshot.TryGetValue(name, out var f) ? f : null;
}

// 治理扫描：找出应清理的开关，输出报告供 CI 消费
public static class FlagGovernance
{
    public static IEnumerable<FlagAudit> Audit(
        IEnumerable<FeatureFlagDefinition> flags,
        IReadOnlyDictionary<string, FlagUsage> usage,
        DateOnly today)
    {
        foreach (var f in flags)
        {
            var u = usage.GetValueOrDefault(f.Name) ?? FlagUsage.Empty;

            if (f.Kind == FlagKind.Release && f.ExpiresOn is { } exp && exp < today)
                yield return new FlagAudit(f.Name, "已过期待清理", f.Owner);

            if (u.Evaluations == 0 && u.LastSeen < today.AddDays(-30))
                yield return new FlagAudit(f.Name, "三十天未被求值", f.Owner);

            if (u.TrueCount > 0 && u.FalseCount == 0 && u.DaysSinceChange > 14)
                yield return new FlagAudit(f.Name, "长期恒为真，可移除分支", f.Owner);

            if (f.Owner is null or "")
                yield return new FlagAudit(f.Name, "缺少负责人", "unknown");
        }
    }
}

// 清理动作：把恒为真的开关内联，删除开关与旧分支
// 清理前
if (await _flags.IsEnabledAsync("new-checkout", ctx))
    return await _newCheckout.ProcessAsync(order);
return await _legacyCheckout.ProcessAsync(order);

// 清理后：开关与旧分支一并消失，代码回到单一事实
return await _newCheckout.ProcessAsync(order);

// 发布编排：分阶段放量，每阶段观察窗口结束后检查健康指标
public sealed class ProgressiveRollout(
    IFeatureFlagAdmin admin,
    IHealthProbe probe,
    ILogger<ProgressiveRollout> logger)
{
    private static readonly int[] Stages = { 1, 5, 25, 50, 100 };

    public async Task RunAsync(string flag, CancellationToken ct)
    {
        foreach (var pct in Stages)
        {
            await admin.SetRolloutAsync(flag, pct, ct);
            logger.LogInformation("已放量到 {Pct}%", pct);

            await Task.Delay(TimeSpan.FromMinutes(10), ct);   // 观察窗口

            var health = await probe.CheckAsync(flag, ct);
            if (!health.IsHealthy)
            {
                await admin.SetRolloutAsync(flag, 0, ct);      // 立即回滚
                logger.LogError("指标异常，已回滚：{Reason}", health.Reason);
                return;
            }
        }
        logger.LogInformation("全量完成，可安排开关清理");
    }
}

# 流水线中的发布阶段：手动批准 + 自动放量
stages:
  - stage: Deploy
    jobs:
      - job: DeployApp
        steps:
          - script: dotnet publish -c Release -o out
          - script: ./deploy.sh --env prod --flags-off new-checkout
  - stage: Rollout
    dependsOn: Deploy
    jobs:
      - deployment: ProgressiveFlag
        environment: production     # 关联审批
        strategy:
          runOnce:
            deploy:
              steps:
                - script: dotnet run --project tools/Rollout -- --flag new-checkout

// 用 xUnit 的 Theory 覆盖开关两态，避免只测了「开」的那条路径
public class CheckoutFlagTests
{
    [Theory]
    [InlineData(true)]
    [InlineData(false)]
    public async Task 两种开关状态都能正确结算(bool flagEnabled)
    {
        var flags = new StubFlags(("new-checkout", flagEnabled));
        var svc = new CheckoutService(flags, _newCheckout, _legacyCheckout);

        var result = await svc.ProcessAsync(TestOrder());

        Assert.NotNull(result);
        Assert.Equal(flagEnabled, result.UsedNewPath);
    }
}