Quden Dev Doc

Appearance

Feature Flags ​

これは何？ ​

このドキュメントでは、Web アプリで利用している Feature Flags について説明します。

概要 ​

Feature flags とは、プロダクト開発時に、機能の公開を制御するための仕組みです。

Quden においては、Backend 側に Feature flags を返すエンドポイントを定義し、Web frontend 側や Chrome extension、Desktop app などで利用しています。

処理の流れは下記に示すとおりです。

mermaid
sequenceDiagram
participant Frontend
participant Backend (NestJS)
participant AWS AppConfig
Frontend->>Backend (NestJS): Request feature flags
Backend (NestJS)->>AWS AppConfig: Get values from AppConfig
AWS AppConfig-->>Backend (NestJS): Return values from AppConfig
Backend (NestJS)->>Backend (NestJS): Merge values with default values
Backend (NestJS)-->>Frontend: Return feature flags

データが定義されている場所 ​

Feature flags の値は、大きく2つの箇所に定義されています。

  • 1: Backend へのハードコーディング
  • 2: AWS AppConfig での管理

1: Backend へのハードコーディング ​

Backend コードベースにおいて、Feature flags の値は src/common/constants.ts に定義されています。

コードベースに直接記述する以上、変更を適用するには再デプロイが必要な点に注意が必要です。主に頻繁に値の変更を伴わないフラグや、フラグ導入の初期段階において利用することが多いです。基本的には、次に説明する 2 の AWS AppConfig での管理を利用することを推奨します。

2: AWS AppConfig での管理 ​

AWS AppConfig は、AWS が提供する構成管理サービスです。Quden では、Feature flags の値を AWS AppConfig で JSON として管理しています。

JSON 形式で設定内容を記述し、AWS AppConfig 上で値の更新をデプロイすることで、Backend を再デプロイすることなく Feature flags の値を変更することができます。

また、JSON の書き方を工夫することで下記のような機能を持たせています。（詳しくは「データ型」参照のこと）

  • フラグの ON/OFF
  • フラグを適用するワークスペースの Allowed List (White List)
  • フラグを有効化する期間の指定

データ型 ​

Feature flags の利用において、下記の大きく2つのデータ型を理解する必要があります。

  • FeatureFlag: 各機能の ON/OFF を管理するシンプルな型
  • AppConfigProfile: AppConfig で管理する際のデータ型

FeatureFlag ​

key として機能名のキャメルケースを、value として boolean を持つオブジェクトです。慣例的に IS_* と記述することが多いです。

src/common/constants.ts に定義されています。

例：

ts
export const FEATURE_FLAGS = {
  // ...
  IS_TRANSCRIBE_AUDIO_AVAILABLE: false,
  IS_IP_ADDRESS_FILTER_AVAILABLE: false,
  // ...
} as const;

AppConfigProfile ​

AppConfigProfile は下記のような type として定義されています。 src/aws-app-config/aws-app-config.service.ts に定義されています。

ts
export type AppConfigProfile = {
  allowedList: {
    // ...
    // その他、Feature flag として管理しない Allowed List の値を定義しています
  };
  featureFlags: {
    // ...
    IS_TRANSCRIBE_AUDIO_AVAILABLE: {
      enabled: boolean;
      allowedWorkspaceList: AvailableWorkspaceInfo[];
    };
    IS_IP_ADDRESS_FILTER_AVAILABLE?: {
      enabled: boolean;
      allowedWorkspaceList: AvailableWorkspaceInfo[];
      filterList: IpAddressFilterListItem[];
    };
    // ...
  };
};

上記をみて分かるように featureFlags に関しては以下の共通する key を持っています。

  • enabled: フラグの ON/OFF を管理する boolean 値
  • allowedWorkspaceList: フラグを適用するワークスペースの Allowed List (White List)

ここに値を指定することで、フラグの ON/OFF をワークスペースごとに制御することができます。

使い方 ​

Feature flags を追加する場合は、大きく下記の流れで行います。