クリーンアーキテクチャ設計書 — Feature Flag 管理システム¶

package domain

import "time"

type FeatureFlag struct {
    FlagKey     string
    Name        string
    Description string
    Enabled     bool
    FailMode    FailMode  // OPEN or CLOSE
    CreatedAt   time.Time
    UpdatedAt   time.Time
}

func (f *FeatureFlag) IsEnabled() bool {
    return f.Enabled
}

type FlagRule struct {
    RuleID     string // UUID
    FlagKey    string
    RuleType   RuleType // PERCENTAGE, SEGMENT, IP_RANGE, ALWAYS
    RuleConfig map[string]interface{} // JSON
    Priority   int
}

type EvaluationContext struct {
    EntityID   string
    OrgID      string
    IPAddress  string
    Attributes map[string]interface{}
}

type FailMode string

const (
    FailModeOpen  FailMode = "OPEN"  // 失敗時 true 返却
    FailModeClose FailMode = "CLOSE" // 失敗時 false 返却（デフォルト）
)

type RuleType string

const (
    RuleTypePercentage RuleType = "PERCENTAGE"
    RuleTypeSegment    RuleType = "SEGMENT"
    RuleTypeIPRange    RuleType = "IP_RANGE"
    RuleTypeAlways     RuleType = "ALWAYS"
)

package usecase

type EvaluateFlagInput struct {
    FlagKey string
    Context EvaluationContext
}

type EvaluateFlagOutput struct {
    Enabled     bool
    Reason      string // FLAG_DISABLED, RULE_MATCHED, DEFAULT, FAIL_OPEN, FAIL_CLOSE
    RuleMatched string // matched rule_id or ""
}

type EvaluateFlagUseCase struct {
    flagRepo    FlagRepository
    ruleRepo    FlagRuleRepository
    cache       Cache
    evalLogger  FlagEvaluationLogger
}

func (uc *EvaluateFlagUseCase) Execute(ctx context.Context, in EvaluateFlagInput) (*EvaluateFlagOutput, error) {
    // 1. キャッシュから取得
    cacheKey := fmt.Sprintf("ff:flag:%s", in.FlagKey)
    flag, err := uc.cache.GetFlag(cacheKey)
    if err != nil {
        flag, err = uc.flagRepo.FindByKey(ctx, in.FlagKey)
        if err != nil {
            // Flipt/DB 接続失敗 → FailMode に従って返却
            return uc.handleFailure(in.FlagKey)
        }
        uc.cache.SetFlag(cacheKey, flag, 60*time.Second)
    }

    // 2. フラグ無効なら即座に false
    if !flag.IsEnabled() {
        return &EvaluateFlagOutput{Enabled: false, Reason: "FLAG_DISABLED"}, nil
    }

    // 3. ルールを priority 順に評価
    rules, _ := uc.ruleRepo.FindByFlagKey(ctx, in.FlagKey)
    for _, rule := range rules {
        if matched, result := uc.evaluateRule(rule, in.Context); matched {
            go uc.evalLogger.Log(in.FlagKey, in.Context.EntityID, result, rule.RuleID)
            return &EvaluateFlagOutput{Enabled: result, Reason: "RULE_MATCHED", RuleMatched: rule.RuleID}, nil
        }
    }

    // 4. マッチなし → フラグデフォルト（enabled の現在値）
    return &EvaluateFlagOutput{Enabled: flag.Enabled, Reason: "DEFAULT"}, nil
}

type TriggerKillSwitchInput struct {
    FlagKey string
    Reason  string // MANUAL or AUTO_KILLSWITCH
    TriggeredBy string
}

type TriggerKillSwitchUseCase struct {
    flagRepo       FlagRepository
    auditRepo      FlagAuditRepository
    cache          Cache
    eventPublisher EventPublisher
    notifier       NotificationGateway
}

func (uc *TriggerKillSwitchUseCase) Execute(ctx context.Context, in TriggerKillSwitchInput) error {
    flag, err := uc.flagRepo.FindByKey(ctx, in.FlagKey)
    if err != nil {
        return err
    }
    flag.Enabled = false
    flag.UpdatedAt = time.Now()

    if err := uc.flagRepo.Update(ctx, flag); err != nil {
        return err
    }

    // キャッシュ即時無効化
    uc.cache.Delete(fmt.Sprintf("ff:flag:%s", in.FlagKey))

    // 監査ログ
    uc.auditRepo.Save(ctx, &FlagAuditLog{
        FlagKey:   in.FlagKey,
        ChangedBy: in.TriggeredBy,
        OldValue:  "enabled=true",
        NewValue:  "enabled=false",
        ChangedAt: time.Now(),
    })

    // イベント発行 → 管理者通知
    uc.eventPublisher.PublishKillSwitchTriggered(in.FlagKey, in.Reason)
    return nil
}

// Outbound Ports

type FlagRepository interface {
    Save(ctx context.Context, flag *FeatureFlag) error
    Update(ctx context.Context, flag *FeatureFlag) error
    FindByKey(ctx context.Context, flagKey string) (*FeatureFlag, error)
    List(ctx context.Context) ([]*FeatureFlag, error)
}

type FlagRuleRepository interface {
    Save(ctx context.Context, rule *FlagRule) error
    Update(ctx context.Context, rule *FlagRule) error
    FindByFlagKey(ctx context.Context, flagKey string) ([]*FlagRule, error)
    Delete(ctx context.Context, ruleID string) error
}

type FlagAuditRepository interface {
    Save(ctx context.Context, log *FlagAuditLog) error
    ListByFlagKey(ctx context.Context, flagKey string) ([]*FlagAuditLog, error)
}

type FlagEvaluationLogger interface {
    Log(flagKey string, entityID string, result bool, ruleMatched string) error
}

type Cache interface {
    GetFlag(key string) (*FeatureFlag, error)
    SetFlag(key string, flag *FeatureFlag, ttl time.Duration) error
    Delete(key string) error
}

type EventPublisher interface {
    PublishFlagEnabled(flagKey string, changedBy string) error
    PublishFlagDisabled(flagKey string, reason string) error
    PublishKillSwitchTriggered(flagKey string, reason string) error
}

type NotificationGateway interface {
    NotifyAdmins(subject string, body string) error
}

package adapter

import (
    "context"
    flipt "go.flipt.io/flipt/sdk/go"
)

type FliptEvaluationAdapter struct {
    client *flipt.Client
}

func NewFliptEvaluationAdapter(address string) (*FliptEvaluationAdapter, error) {
    client, err := flipt.New(flipt.WithAddress(address))
    if err != nil {
        return nil, err
    }
    return &FliptEvaluationAdapter{client: client}, nil
}

// FliptAdapter はフラグ評価を Flipt に委譲する（OpenFeature SDK Provider として機能）
func (a *FliptEvaluationAdapter) Evaluate(ctx context.Context, flagKey string, entityID string, context map[string]string) (bool, error) {
    resp, err := a.client.EvaluationService().Boolean(ctx, &flipt.BooleanEvaluationRequest{
        FlagKey:  flagKey,
        EntityId: entityID,
        Context:  context,
    })
    if err != nil {
        return false, err
    }
    return resp.Enabled, nil
}

package adapter

import (
    "context"
    "encoding/json"
    "time"
    "github.com/redis/go-redis/v9"
)

type RedisFlagCache struct {
    client *redis.Client
}

func (c *RedisFlagCache) GetFlag(key string) (*domain.FeatureFlag, error) {
    val, err := c.client.Get(context.Background(), key).Result()
    if err != nil {
        return nil, err
    }
    var flag domain.FeatureFlag
    if err := json.Unmarshal([]byte(val), &flag); err != nil {
        return nil, err
    }
    return &flag, nil
}

func (c *RedisFlagCache) SetFlag(key string, flag *domain.FeatureFlag, ttl time.Duration) error {
    data, _ := json.Marshal(flag)
    return c.client.Set(context.Background(), key, data, ttl).Err()
}

func (c *RedisFlagCache) Delete(key string) error {
    return c.client.Del(context.Background(), key).Err()
}

func TestEvaluateFlag_Disabled(t *testing.T) {
    mockRepo := &MockFlagRepository{
        flag: &FeatureFlag{FlagKey: "feature.album.v2", Enabled: false},
    }
    uc := &EvaluateFlagUseCase{flagRepo: mockRepo, cache: &MockCache{}}

    out, err := uc.Execute(context.Background(), EvaluateFlagInput{
        FlagKey: "feature.album.v2",
        Context: EvaluationContext{EntityID: "user123"},
    })

    assert.NoError(t, err)
    assert.False(t, out.Enabled)
    assert.Equal(t, "FLAG_DISABLED", out.Reason)
}

func TestEvaluateFlag_PercentageRollout_Deterministic(t *testing.T) {
    // 同一 user_id は常に同じ結果になることを確認
    uc := buildEvaluateFlagUCWith50Percent()

    out1, _ := uc.Execute(ctx, EvaluateFlagInput{FlagKey: "feature.x", Context: EvaluationContext{EntityID: "userABC"}})
    out2, _ := uc.Execute(ctx, EvaluateFlagInput{FlagKey: "feature.x", Context: EvaluationContext{EntityID: "userABC"}})

    assert.Equal(t, out1.Enabled, out2.Enabled) // 決定論的
}