AIと育てる型定義 Part 5: UIとデータ層を繋ぐ『生きた仕様書』の完成

著者: ClaudeMix Team |

UIコンポーネントのPropsとデータ層の戻り値が別々の型で定義されていると、層をまたぐたびに変換コードが必要になる。中央の型定義から共通の型をexportし、全層で参照する形に統合した。

① やったこと

Before: 記事一覧ページのProps型・記事詳細ページのProps型が、それぞれのコンポーネントファイル内にローカルで定義されていた。データアクセス層の戻り値型もUI層のページネーション計算を意識したプロパティを持ち、責務が曖昧だった。

- interface PostsSectionProps {
-   posts: PostSummary[];
-   pagination: {
-     currentPage: number;
-     totalPages: number;
-   };
-   // ... and more
- }
- const PostsSection: React.FC<PostsSectionProps> = ({...}) => {
+ import type { PostsPageData } from '~/specs/blog/types';
+
+ const PostsSection: React.FC<PostsPageData> = ({...}) => {

After: 中央の型定義ファイルにPostsPageDataとRenderedPostを新設し、各コンポーネントのローカルProps型を削除してこれを参照する形に統一した。

export interface PostsPageData {
  posts: PostSummary[];
  pagination: Pick<PaginationInfo, 'currentPage' | 'totalPages'>;
  availableFilters: AvailableFilters;
  selectedFilters: FilterOptions;
}

// Post型のcontent(markdown)をhtmlContent(html)に置き換えたもの
export type RenderedPost = Omit<Post, 'content' | 'summary' | 'testOnly'> & {
  htmlContent: string;
};

RenderedPostはOmitと&を組み合わせ、基底のPost型から不要なプロパティを除外しつつUI専用のデータモデルを派生させている。

② 設計判断

  • 【優先した価値】: Remixのloaderが返すデータ構造とコンポーネントが受け取るデータ構造を単一の型で一致させ、データフローを型レベルで保証すること
  • 【犠牲にした価値】: 各コンポーネントが自分専用のProps型を持つ自律性。中央のドメイン型に依存する分、コンポーネント単体では完結しなくなった

③ 技術的負債

  • 【解消した負債】: データアクセス層の戻り値型・記事一覧ページのProps型・記事詳細ページのProps型という3箇所にバラバラに存在していた型定義を、PostsPageData/RenderedPostという中央の型への参照に統合した。独立した定義元は3箇所→1箇所(中央の型定義ファイル)に減った
  • 【新たに生まれた負債】: 中央の型定義ファイルへの依存が強まり、この型を変更した際の影響範囲がプロジェクト全体に広がるようになった

④ 経営翻訳

「記事一覧」「記事詳細」「データ取得」という3つの窓口が、それぞれ独自の様式でデータをやり取りしていた状態を、共通の様式(中央のドメイン型)に統一した。これにより、窓口間でデータを受け渡すたびに発生していた「書式変換の手作業」がなくなった。一方で、この共通様式を変更する際は、それを使う全ての窓口に影響が及ぶようになった。

型で「生きた仕様書」を作ったのと同様に、E2EテストのセレクタもextractTestIdパターンでspec.yamlから動的に取得する仕組みを整えている。型・YAML・テストセレクタが同一のSSOTを参照することで、UIを変更してもテストが壊れない構造になっている。

このシリーズの記事

3つの窓口(記事一覧・記事詳細・データ取得)が、それぞれ独自の様式で書類をやり取りしていた。 窓口間で書類を受け渡すたびに、様式を変換する手作業が発生していた。

独立した様式(型定義)の数: 3箇所