feature-flag-manager（功能标志管理器）

Feature Flag Manager

Implement comprehensive feature flag management for controlled feature rollouts and A/B testing in worldbuilding applications.

Overview

To add feature flag capabilities:

1. Choose between LaunchDarkly (cloud service) or JSON-based (local) implementation
2. Set up feature flag provider with configuration
3. Create feature flag components and hooks
4. Gate UI components and Server Actions behind flags
5. Implement user targeting and progressive rollouts

Implementation Options

LaunchDarkly Integration

To integrate LaunchDarkly:

1. Install LaunchDarkly SDK: npm install launchdarkly-react-client-sdk
2. Configure provider in app root with client-side ID
3. Create hooks for flag evaluation
4. Wrap components with feature flag checks
5. Configure flags in LaunchDarkly dashboard

Use scripts/setup_launchdarkly.py to scaffold LaunchDarkly configuration.

JSON-Based Feature Flags

To implement local JSON-based flags:

1. Create config/feature-flags.json with flag definitions
2. Build feature flag provider context
3. Create hooks to read flags from context
4. Implement environment-specific overrides
5. Support runtime flag updates

Use scripts/setup_json_flags.py to generate JSON flag structure.

Consult references/feature-flag-patterns.md for implementation patterns and best practices.

Feature Flag Provider Setup

LaunchDarkly Provider

To set up LaunchDarkly in Next.js:

// app/providers.tsx
import { LDProvider } from 'launchdarkly-react-client-sdk';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <LDProvider
      clientSideID={process.env.NEXT_PUBLIC_LD_CLIENT_ID}
      user={{
        key: 'user-id',
        email: 'user@example.com',
      }}
    >
      {children}
    </LDProvider>
  );
}

JSON Provider

To create custom JSON provider:

// lib/feature-flags/provider.tsx
import { createContext, useContext } from 'react';
import flags from '@/config/feature-flags.json';

const FeatureFlagContext = createContext(flags);

export function FeatureFlagProvider({ children }: { children: React.ReactNode }) {
  return (
    <FeatureFlagContext.Provider value={flags}>
      {children}
    </FeatureFlagContext.Provider>
  );
}

export function useFeatureFlags() {
  return useContext(FeatureFlagContext);
}

Reference assets/feature-flag-provider.tsx for complete provider implementation.

Using Feature Flags

Component Gating

To gate UI components behind flags:

import { useFeatureFlag } from '@/lib/feature-flags';

export function NewFeatureComponent() {
  const isEnabled = useFeatureFlag('new-timeline-view');

  if (!isEnabled) {
    return null;
  }

  return <div>New Timeline View</div>;
}

Conditional Rendering

To show different variants based on flags:

export function EntityList() {
  const useNewLayout = useFeatureFlag('entity-list-redesign');

  return useNewLayout ? <NewEntityList /> : <LegacyEntityList />;
}

Server Action Gating

To gate Server Actions:

// app/actions/entity-actions.ts
'use server';

import { getFeatureFlag } from '@/lib/feature-flags/server';

export async function createEntity(data: EntityData) {
  const allowBulkCreate = await getFeatureFlag('bulk-entity-creation');

  if (allowBulkCreate && data.items?.length > 1) {
    return bulkCreateEntities(data.items);
  }

  return createSingleEntity(data);
}

Reference assets/server-actions-with-flags.ts for server-side flag patterns.

Flag Configuration

Flag Structure

Define flags with metadata:

{
  "flags": {
    "new-timeline-view": {
      "enabled": true,
      "description": "Enable new timeline visualization",
      "rolloutPercentage": 100,
      "allowedUsers": [],
      "environments": {
        "development": true,
        "staging": true,
        "production": false
      }
    }
  }
}

Flag Types

Support different flag types:

• Boolean: Simple on/off toggle
• Percentage: Gradual rollout (0-100%)
• User Targeting: Specific users or groups
• Multivariate: Multiple variations (A/B/C testing)

Consult references/flag-types.md for detailed flag type specifications.

Progressive Rollout

To implement gradual feature rollouts:

1. Initial Release: Enable for 5% of users
2. Monitor Metrics: Track performance and errors
3. Increase Rollout: Gradually increase to 25%, 50%, 100%
4. Full Release: Enable for all users
5. Remove Flag: Clean up flag code after stable release

Use scripts/rollout_manager.py to automate rollout percentage updates.

User Targeting

To target specific user segments:

By User ID

const flags = evaluateFlags(userId, flagConfig);

By User Properties

const flags = evaluateFlags({
  userId: 'user-123',
  email: 'user@example.com',
  role: 'admin',
  tier: 'premium',
});

By Custom Rules

const flags = evaluateFlags(user, {
  rules: [
    { property: 'role', operator: 'equals', value: 'admin' },
    { property: 'tier', operator: 'in', values: ['premium', 'enterprise'] },
  ],
});

Environment-Specific Flags

To configure flags per environment:

{
  "flags": {
    "debug-mode": {
      "development": true,
      "staging": true,
      "production": false
    },
    "experimental-features": {
      "development": true,
      "staging": false,
      "production": false
    }
  }
}

Load environment-specific configuration at build time or runtime.

A/B Testing

To implement A/B tests:

export function EntityDetailPage() {
  const variant = useFeatureFlagVariant('entity-detail-layout', {
    control: 'grid',
    variantA: 'list',
    variantB: 'cards',
  });

  return variant === 'list' ? (
    <EntityListView />
  ) : variant === 'cards' ? (
    <EntityCardView />
  ) : (
    <EntityGridView />
  );
}

Track variant exposure for analytics:

useEffect(() => {
  trackExposure('entity-detail-layout', variant);
}, [variant]);

Flag Lifecycle Management

Creating New Flags

To add a new feature flag:

1. Define flag in configuration with metadata
2. Set initial state (usually disabled)
3. Implement flag checks in code
4. Deploy with flag disabled
5. Enable flag via dashboard or config update

Removing Old Flags

To clean up completed feature flags:

1. Ensure flag is at 100% rollout
2. Verify no incidents for 2+ weeks
3. Remove flag checks from code
4. Make flagged code permanent
5. Remove flag from configuration
6. Deploy cleanup changes

Use scripts/find_flag_usage.py to locate all usages of a flag before removal.

Testing with Feature Flags

Local Development

To override flags in development:

// .env.local
NEXT_PUBLIC_FEATURE_FLAGS_OVERRIDE='{"new-timeline-view":true}'

Testing Specific Variants

To test flag variations:

// test/setup.ts
import { mockFeatureFlags } from '@/lib/feature-flags/testing';

beforeEach(() => {
  mockFeatureFlags({
    'new-timeline-view': true,
    'bulk-entity-creation': false,
  });
});

Reference assets/testing-utils.ts for testing utilities.

Monitoring and Analytics

To track feature flag impact:

1. Exposure Tracking: Log when flags are evaluated
2. Performance Metrics: Monitor performance per variant
3. Error Rates: Track errors by flag state
4. User Engagement: Measure feature usage
5. Conversion Metrics: Track business metrics per variant

Integrate with analytics platform:

import { analytics } from '@/lib/analytics';

export function useFeatureFlagWithTracking(flagName: string) {
  const isEnabled = useFeatureFlag(flagName);

  useEffect(() => {
    analytics.track('feature_flag_exposure', {
      flag: flagName,
      enabled: isEnabled,
    });
  }, [flagName, isEnabled]);

  return isEnabled;
}

LaunchDarkly-Specific Features

To leverage LaunchDarkly capabilities:

• Targeting Rules: Create complex targeting rules in dashboard
• Flag Triggers: Automate flag changes based on metrics
• Scheduled Rollouts: Plan feature releases in advance
• Flag Dependencies: Define flag prerequisites
• Audit Logs: Track all flag changes
• Team Workflows: Require approvals for production changes

Consult LaunchDarkly documentation for advanced features.

Best Practices

1. Short-Lived Flags: Remove flags after rollout completes
2. Clear Naming: Use descriptive, consistent flag names
3. Documentation: Document flag purpose and timeline
4. Default Values: Provide safe defaults for missing flags
5. Testing: Test both enabled and disabled states
6. Monitoring: Track flag performance and errors
7. Cleanup: Regularly audit and remove unused flags

Troubleshooting

Common issues:

• Flag Not Updating: Check cache settings and invalidation
• Inconsistent State: Verify flag evaluation consistency
• Performance Impact: Minimize flag evaluation overhead
• Testing Challenges: Use proper mocking in tests
• Configuration Conflicts: Ensure environment-specific overrides work correctly