blog

宣言的フォームバインディング

NEXTREE.

• 5 min read
宣言的フォームバインディング

1. はじめに

Webアプリケーション開発において、ダイアログ（Dialog）やモーダル画面を通じたデータ編集フォーム（Form）を実装することは、最も一般的でありながら複雑度の高い作業の一つです。特に管理画面やダッシュボードの「コンテンツ詳細情報編集画面」のように、画面が開くタイミングでバックエンドAPIから非同期に詳細データを取得し、フォームの初期値としてバインドする構造では、より綿密な状態制御が求められます。

初期のコンポーネント設計では、最も直感的な方法であるuseEffectフックを利用して、外部Propsとして渡された詳細データの変更を検知し、フォーム管理状態に手動で値を注入する命令型（Imperative）アプローチを採用しました。しかし、この方式は高度化の段階で予期せぬ同時実行性の問題を引き起こしました。ユーザーがダイアログを素早く閉じて別のアイテムを選択し、再び開いた際、非同期データのフェッチタイミングが重なることで、以前のデータの残骸が入力フィールドに一時的に残ったり、フックの呼び出し順序とコンポーネントのレンダリングライフサイクルがずれることで状態が失われたりするバグが頻繁に確認されました。

UIレイヤーの可読性を低下させ、データの整合性を脅かすこの根深い問題を解決するため、手続き型のuseEffectを思い切って排除し、React Hook Formライブラリの中核アーキテクチャを活用して宣言型（Declarative）の状態同期を実現した、実務でのリファクタリング事例を共有します。

2. 技術選定の背景

Reactでフォームの状態を制御する際によくあるアンチパターンの一つは、データの流れをuseEffect内で制御しようとすることです。Propsとして受け取ったデータが変更されるたびに特定の状態を手動で同期する構造には、次のような限界があります。

  1. 状態同期タイミングの不一致：Reactの状態更新は非同期でバッチ（Batch）処理されるため、useEffectが実行されてフォームの値が更新される前に、ブラウザが以前の状態に基づいて画面を一度描画してしまい、視覚的な残像やバリデーションエラーを引き起こします。

  2. 命令型コードの肥大化：入力フィールドが増えるほど、各フィールドの初期化ロジックや条件分岐がコンポーネント内部のあちこちに分散し、1,000行を超える肥大化した読みにくいスパゲッティコンポーネントを生み出すことになります。

React Hook Formは、こうした限界を克服できる宣言型のプロパティであるvaluesオプションを提供します。コンポーネント内部に状態をリセットする命令を直接記述する代わりに、フォームが参照するデータソースをオブジェクトとして明示的に宣言しておけば、ライブラリがReactのレンダリングパイプラインと同期し、状態の残骸を安全に取り除きながら新しいデータインスタンスを維持してくれます。

そのため、コンポーネントのライフサイクルに安全に適合しつつ、コードの可読性と開発者体験を最大化できるソリューションとして、宣言型バインディングパターンを導入することにしました。

3. 実際の適用過程とトラブルシューティング

本プロジェクトにおける実際の詳細情報編集ダイアログの設計思想に基づき、バグを引き起こしていた手続き型構造を宣言型構造へリファクタリングした過程を、具体的なコードブロックとともに説明します。

3.1 useEffectベースの命令型バインディング構造（Before）

従来の構造では、外部からAPIリクエストの結果であるitemDetailオブジェクトが渡されるたびに、子ダイアログ内部のuseEffectフックが毎回実行され、setValueメソッドを通じてフォームの各フィールドを手動で埋めていました。

export const ModifyItemDialogBefore = ({ itemDetail, onClose }) => {
  const { register, handleSubmit, setValue } = useForm({
    defaultValues: {
      title: '',
      category: '',
      description: '',
    },
  });

  // 외부 데이터가 바뀔 때마다 수동으로 상태를 주입하는 안티 패턴
  useEffect(() => {
    if (itemDetail) {
      setValue('title', itemDetail.title ?? '');
      setValue('category', itemDetail.category ?? '');
      setValue('description', itemDetail.description ?? '');
    }
  }, [itemDetail, setValue]);

  const onSubmit = (data) => {
    console.log('서버 전송 데이터:', data);
  };

  return (
    <Dialog open={true} onClose={onClose}>
      <form onSubmit={handleSubmit(onSubmit)}>
        <input {...register('title')} placeholder="제목" />
        <button type="submit"> 수정 </button>
      </form>
    </Dialog>
  );
};

この構造では、非同期フェッチの速度が遅延したり、ユーザーがダイアログを素早く閉じたり開いたりした際に、itemDetailがまだ到達していない一瞬の間、以前のコンポーネントの古いデータがフォームにそのまま残って表示されるデータ汚染現象が発生しました。

3.2 valuesプロパティを活用した宣言型バインディング構造（After）

これを解決するため、useForm内のvaluesリアクティブプロパティを導入し、インターフェースをModifyItemFormValue構造に一本化して、フォーム自身がデータ変更に対応できるようリファクタリングしました。

interface ModifyItemFormValue {
  title: string;
  category: string;
  date: Dayjs | null;
  description: string;
  details: string;
}

export const ModifyItemDialogAfter = ({ itemDetail, onClose }) => {
  // values 옵션을 선언해 두면, useEffect 없이도 데이터 변경 시 내부 상태가 자동 동기화됨
  const methods = useForm<ModifyItemFormValue>({
    values: {
      date: itemDetail?.updatedAt ? dayjs(itemDetail.updatedAt) : dayjs(),
      title: itemDetail?.title ?? '',
      category: itemDetail?.category ?? '',
      description: itemDetail?.description ?? '',
      details: itemDetail?.details ?? '',
    },
  });

  const { handleSubmit, register } = methods;

  const onSubmit = handleSubmit((data: ModifyItemFormValue) => {
    const baseDate = dayjs(data.date).startOf('day').valueOf();
    console.log('정합성이 보장된 타임스탬프 데이터 전송:', baseDate);
  });

  return (
    <Dialog open={true} onClose={onClose}>
      <Form methods={methods} onSubmit={onSubmit}>
        <div className="flexColumn gap16">
          <Field.Text name="title" placeholder="제목" />
          <Field.Text name="details" placeholder="상세 내용" multiline rows={2} />
        </div>
        <button type="submit">수정 완료</button>
      </Form>
    </Dialog>
  );
};

このようにリファクタリングすると、React Hook FormライブラリがReactの仮想DOM更新タイミングに合わせてデータセットをアトミック（Atomically）に置き換えるため、画面に以前のデータの残骸が表示されたり、フォームの状態が混乱したりするレースコンディションのバグを根本的に完全排除できます。

4. 適用結果と成果

人事情報編集画面を含む社内の主要な入力フォームレイヤー全体に、React Hook Formのvalues宣言型バインディングアーキテクチャを展開・適用した結果、次のような成果を達成しました。

  1. 状態の混乱およびUI残像バグのゼロ化：ダイアログの呼び出し速度や非同期通信の可用性に関係なく、データの残骸が表示される現象を完全に解決し、これに起因する誤動作に関する問い合わせ件数も従来と比べてゼロに近い水準まで改善されました。

  2. コードベースの可読性および生産性の向上：無秩序に記述され、可読性を損なっていたコンポーネント内部のuseEffect構文を削除したことで、モーダル関連の全ソースコードの行数を平均25%以上削減し、スリム化を実現しました。

結合度の緩和とデータ安定性の確保：ビジネスフォームデータの加工（ModifyItemFormValue）ロジックをビュー層から一方向の流れに沿って徹底的に分離（Decoupling）し、以前の状態による副作用に影響されない、純粋なコンポーネントの隔離性を確保しました。

5. おわりに

今回のプロジェクトで直面した状態混乱バグとリファクタリングの経験は、フロントエンドアーキテクチャを設計する際、状態の変化の流れを開発者が副作用（Side Effect）によって無理に命令・追跡するよりも、フレームワークやライブラリが提供する宣言型の思想に沿って依存関係を明確に宣言しておくことが、いかに強力であるかを証明する良い機会となりました。

React Hook Formのvaluesプロパティを活用したライフサイクルマッピング手法は、単なるバグ修正を超え、システムのアーキテクチャ上の堅牢性を一段階高める資産となりました。大規模なデータを扱い、入力フィールドが複雑に絡み合うエンタープライズ環境ほど、このようなデータ整合性を保証するパターンは不可欠です。今回確立した宣言型フォームアーキテクチャのチューニング経験を社内の技術コンポーネント標準ガイドラインとして資産化し、全社的な開発エコシステムの複雑度を低減することに積極的に貢献したいと考えています。

* 参考資料

- React Hook Form - useForm API Document

- React Official Document - Synchronizing with Effects

- React Official Document - You Might Not Need an Effect

D.Hyeok

Site footer