実装の進め方 分離の設計図

• 日程: Day 4 / セッション 1
• 時間: [9:00-9:30]
• 形式: 座学
• ゴール: 「情報の設計とシステムの設計の分離」「プレゼンテーションと機能の分離」を、今日の実装構成（モックAPI＋UI）に対応づけて説明できる。今日使うツール（APIモック、GitHub等）の役割をそれぞれ一言で言える
• 学習形式: 対話型解説＋デモンストレーション

いよいよ最終日です。今日はこれまでの3日間で作った成果物を「動くソフトウェア」にします。

ここで少し考えてみてください。Day 1 から Day 3 まで、あなたはコードを1行も書かずに設計を積み上げてきました。情報定義書、ペルソナ、情報モデル、状態遷移図、機能一覧、ワイヤーフレーム、API設計書。これらは無駄な回り道だったでしょうか？

答えは今日の夕方に出ます。設計が正しくできていれば、実装は「設計図を翻訳する作業」になります。逆に、設計なしで書き始めると、コードを書きながら設計をやり直すことになります。

このセッションは、研修全体の「ホール・パート・ホール」の最後のホールの入り口です。まず全体の地図を確認してから、手を動かし始めましょう。

3日間の成果物と、今日作るものの対応関係を地図にします。

読み方は単純です。

• 情報の設計（Day 1〜2 前半）は、モックAPIが返す「データの形」になる
• システムの設計（Day 3）は、モックAPIの「エンドポイント」になる
• プレゼンテーション（ワイヤーフレーム）は、UI のコードになる
• 機能とプレゼンテーションの間は、HTTP と JSON の通信でつなぐ

たとえるなら、Day 1〜3 は建築の設計図で、今日は施工です。設計図があるので、今日のあなたは「何を作るか」で迷いません。迷ってよいのは「どう作るか」だけです。

家計簿システムなら、対応はこうなります。

• 実装で迷ったら、必ず Day 1〜3 の成果物に戻る。「この画面に出す情報は情報定義書のどれか」「このAPIは機能一覧のどれか」と辿れる状態を保つ
• 逆に、成果物にない情報や機能を実装したくなったら、それは設計の変更。先に成果物側を直してから実装する

「アーキテクト（architect）」の語源はギリシャ語の archi（頭領）＋ tekton（大工）、つまり「大工の棟梁」です。ソフトウェアの世界がこの言葉を借りたのは、建築と同じく「作り始める前に構造を決める人」が必要だったから。ちなみに建築界からは「ソフトウェアは建築ほど簡単に壊してやり直せないはずなのに、気軽にアーキテクチャと呼ぶな」と言われることもあります。今日のあなたは棟梁と大工の一人二役です。

この研修で繰り返してきた2つの分離を、今日のディレクトリ構成に対応づけます。

• 情報の設計とシステムの設計の分離

  • 情報の設計: db.json のデータ構造（何を、どんな属性で持つか）はペルソナの価値から決まる
  • システムの設計: エンドポイントの形式や通信方式（REST/JSON）はコンピュータの都合から決まる
  • 分離できている状態: データ構造を変えずに、API の実装ツールを apiary から JSON Server に差し替えられる
• プレゼンテーションと機能の分離

  • プレゼンテーション: ui/ フォルダ（HTML と描画用 JavaScript）
  • 機能: api/ フォルダ（モックAPIの定義）
  • 分離できている状態: UI を作り直しても API は1文字も変わらない。API を本物に差し替えても UI は（接続先以外）変わらない

kakeibo/
├── api/
│   └── db.json          ← 機能側（情報モデル由来のデータと CRUD）
└── ui/
    ├── index.html       ← プレゼンテーション（構造）
    ├── app.js           ← プレゼンテーション（描画・イベント）
    └── api.js           ← 通信の窓口（fetch をここに集約）

ここで少し考えてみてください。もし app.js の中に「合計金額の計算ルール」を書いたら、それはどちら側の仕事でしょうか？　計算は機能です。UI に書くと分離が崩れます。今日は何度もこの問いを自分に投げかけることになります。

• 分離の判定基準はただ一つ。「片方だけを交換できるか」
• 完成度より分離の維持を優先する。動く機能が少なくても、分離が保たれていれば今日は合格

「関心の分離（Separation of Concerns）」という言葉は、1974年に計算機科学者エドガー・ダイクストラが論文の中で使ったのが始まりとされます。彼は「一度にすべてを考えるのは人間には無理だ。だから関心ごとに切り分けて、一つずつ完全に考えるのだ」と述べました。構造化プログラミングの父の悩みは、50年後の私たちの悩みと同じだったわけです。

今日使うツールの役割を確認します。

• APIモック

  • apiary: API Blueprint という Markdown 風の記法で API 仕様を書くと、クラウド上にモックサーバが立つサービス。設計書がそのまま動く点が強み
  • JSON Server: db.json を置いて起動するだけで REST API が動く npm パッケージ。ローカルで完結し、POST や DELETE で実際にデータが変わる。本研修の主教材はこちら
• UI 開発

  • 素の HTML ＋ JavaScript（fetch API）を基本にする。Monaca や React などのフレームワークは、同じ構成の発展形として位置づける
• GitHub

  • ソースコードの置き場と履歴管理。今日の成果物の提出先。git init から push までを Session 4 で行う

なぜモックなのか、も確認しておきます。本物のデータベースやサーバを作るには時間がかかります。モックなら「機能側の外形（API）」を数分で固定でき、UI 側の開発をすぐ始められます。分離ができているからこそ、片方をモックで代用できるのです。

• ツールは手段。今日の主役は「分離された構成」であって、JSON Server でも apiary でも本質は同じ
• ツールの操作で詰まったら、エラーメッセージごと AI に貼り付ける。それも今日の練習項目の一つ

apiary は英語で「養蜂場」という意味です。API という文字が入っていることに気づいたでしょうか（api-ary）。働き蜂のように小さな API たちが巣箱に収まっている、という洒落の効いた名前です。2017年にオラクルに買収されましたが、API 設計書（API Blueprint）を先に書いてモックを自動生成する「デザインファースト」の文化を広めた立役者でした。

• 「『プレゼンテーションと機能の分離』を、レストランの厨房とホールにたとえて説明して。そのたとえで API は何にあたる？」
• 「モックAPIを使う利点と、モックのまま本番に出してしまった場合に起きる問題を教えて」
• 「私の開発テーマは〇〇です。Day 3 で作った API 設計書（貼り付ける）は、今日 JSON Server で再現できる形になっている？　足りない情報があれば指摘して」

座学の締めとして、5分で「自分の分離マップ」を作ります。上の Mermaid 図をまねて、自分の開発テーマの成果物名で対応表（成果物 → 今日作るもの）を3行以上書き出してください。

• 分離マップ（メモで可。成果物 → 実装物の対応3行以上）

• 「情報モデル1つ → リソース1つ → 画面1〜2枚」の比率が目安
• 対応先が思いつかない成果物（例: 非機能要件一覧書）は「今日は使わない」と明記してよい。使わない判断も設計

今回学んだことを一言でまとめると「Day 1〜3 の成果物は、そのまま今日の実装の設計図になる」です。

• 情報の設計 → モックAPIのデータ構造
• システムの設計 → エンドポイントと通信方式
• プレゼンテーション → UI のコード
• 2つの分離は api/ と ui/ というフォルダの形で目に見える

次のセッションでは、いよいよ機能側＝モックAPIを作って動かします。設計書が「curl で叩くと JSON が返ってくる」に変わる瞬間です。

• 「情報の設計とシステムの設計の分離」は、今日の構成のどこに現れると説明できますか？
• 分離できているかを判定する基準を一言で言えますか？
• apiary・JSON Server・GitHub の役割をそれぞれ一言で言えますか？

• 参考リンク: JSON Server（npm）公式 README、apiary / API Blueprint 公式ドキュメント、GitHub Docs「Hello World」
• 発展課題: 自分の開発テーマで「もしモバイルアプリ版 UI を追加するとしたら、どのファイルは変更不要か」を考え、AI と答え合わせする