Skip to main content
KISS TS版YAGNI TS版SoC TS版ADR TS版HC/LC TS版DRY TS版リファクタリング TS版テスタブル TS版TDD TS版エラーモデリング TS版レイヤー TS版MVC TS版依存関係ルール TS版DIP TS版DI TS版Is-a/Has-a TS版SOLID TS版GoFデザインパターン TS版Observer TS版CQS TS版状態機械 TS版不変条件 TS版Entity/VO TS版DDD TS版集約/境界 TS版ドメインイベント TS版モジュラーモノリス TS版ヘキサゴナル TS版クリーンアーキ TS版ACL TS版API Contract TS版SemVer TS版DbC TS版冪等性 TS版CAP定理 TS版Outbox TS版Saga TS版CQRS TS版イベントソーシング TS版BC TS版

第08章：“破壊変更”の定義を自分の教材に固定する📏🧾

Breaking Changes List

この章でできるようになること🎯✨​

  • 「破壊変更って何？」を、ブレない言葉で説明できる🙂📣
  • 変更が来たときに、破壊かどうかをサクッと判定できる🔍✅
  • 自分のプロジェクト用に、“破壊変更リスト”（ルール集）を作れる📝💖
  • 迷いがちなケース（型・挙動・エラー・データ形式）を具体例で判断できる🧠✨

8.1 まず「破壊変更」ってなに？💥🤝​

**破壊変更（Breaking Change）**はひとことで言うと👇

いま使っている人（利用者）が、アップデートしただけで困る変更😱 （コードが動かない / ビルドが通らない / 期待した結果が変わる など）

そして、バージョニングの世界では「互換性が壊れる変更＝MAJORを上げる」が基本の約束になってるよ🔢✨ (Semantic Versioning)

8.2 “誰が困るか”で決めるのがコツ👥🧠​

破壊かどうかは「変更の大きさ」じゃなくて、困る人がいるかで決まるよ🙂

✅ 破壊変更の判定で見るべき3つ​

  1. ビルドが落ちる？（型エラー・importできない等）🧱💥
  2. 実行時に落ちる？（例外・undefined・HTTPエラー等）🏃‍♀️💥
  3. 動くけど意味が変わる？（結果・副作用・ルールが変化）🌀💥

この3つのどれかが「利用者に起きる」なら、かなりの確率で破壊変更だよ⚠️✨

8.3 “固定化”ってどうやるの？📌🧾​

Required is Strict!

ここからが本題！ 破壊変更をブレなくするには、自分の教材（＝自分のプロジェクト）でのルールを文章にして固定しちゃうのが最強🦾✨

ステップ①：まず「公開API面」をはっきりさせる🎭🚪​

破壊変更は基本、**公開している約束（Public Surface）**に対してだけ発生するよ。

公開API面の例👇

  • npmパッケージなら：exportしてる関数/クラス/型、エントリポイント、型定義🧩📦
  • HTTP APIなら：URL、HTTPメソッド、リクエスト/レスポンスのJSON、ステータス、エラー形式🌐🧾
  • イベントなら：イベント名、payload形、意味、順序、リトライ方針📣🧠

👉 ここが曖昧だと「どこからが破壊？」が毎回ブレるよ〜😵‍💫

ステップ②：「破壊変更」を“カテゴリ”で固定する🗂️✨​

おすすめは、破壊変更を 4カテゴリ に分けて定義すること！

  1. 形が変わる破壊（シグネチャ/JSON形/必須項目など）🧱
  2. 意味が変わる破壊（挙動・ルール・計算結果の意味など）🌀
  3. エラーが変わる破壊（投げる例外/HTTPエラー/コード/メッセージなど）📛
  4. 配布・入口が変わる破壊（import経路/exports/ランタイム要件など）🚪📦

ステップ③：一文で「うちの破壊変更」を定義する📏🧡​

テンプレ（このまま使ってOK）👇

公開API面に対して、利用者の修正なしではビルド・実行・期待結果が維持できない変更を破壊変更とする。 破壊変更が入る場合はMAJORを上げる。 (Semantic Versioning)

ここまでが“固定化”の芯だよ📌✨

8.4 破壊変更カタログ（TypeScriptあるある）🟦💥​

ここからは「ありがち」を具体例で固めるよ〜😊✨ （※例は “公開API面” に出してる想定だよ）

A) exportが変わる（入口が壊れる）🚪💥​

  • exportを消す
  • 名前変更（リネーム）
  • exportの場所（パス）を変える
// v1
export function add(a: number, b: number): number;

// v2（名前変更）=> 既存利用者のimportが壊れる😱
export function sum(a: number, b: number): number;

✅ これは分かりやすく破壊！

B) 引数や戻り値の“契約”が変わる🧾💥​

  • 引数を削除する
  • 必須/任意が変わる（任意→必須は危険）
  • 型が変わる（string→number とか）
  • 戻り値の型・意味が変わる
// v1
export function greet(name?: string): string;

// v2（任意→必須）=> 呼び出し側が壊れる可能性大😱
export function greet(name: string): string;

C) “型だけ”の変更でも破壊になることある🧩💥​

特に危険なのが 型の“絞り込み”（広い→狭い）！

// v1（広い）
export type Mode = "easy" | "hard" | "auto";

// v2（auto削除）=> 既存コードで "auto" がエラーになる😱
export type Mode = "easy" | "hard";

D) 「動くけど意味が変わる」＝一番こわい🌀😱​

これ、型では検出できないことが多いから、破壊変更として扱う方が安全だよ⚠️💦

例👇

  • 返す配列の順序が変わる
  • 0件のとき [] だったのが null になる
  • 丸め/計算ルールが変わる
  • “成功扱い”の条件が変わる

そして重要ポイント👇 アップグレードで「新しいエラーが出る」「挙動が変わる」ことは実際に起きるので、公式のリリースノートでも「挙動変更・新しい制限・deprecation」などを注意してね、っていう書き方になってるよ📚⚠️ (TypeScript)

E) エラーの契約が変わる📛💥​

利用者は「エラーの種類」や「エラー形式」に依存してたりするよね😣

  • 例外の種類が変わる
  • エラーコードが変わる
  • HTTPならステータスが変わる（400→500 みたいなの）
  • JSONエラーの形が変わる

👉 **エラーも“仕様の一部”**って扱うと、運用が安定するよ🙂✨

F) 配布・入口の破壊（npmで地味に多い）📦💥​

  • エントリポイント変更（main/module/exports まわり）
  • 型定義の出し方が変わる（利用者の型解決が壊れる）
  • 依存関係の要求が上がる（利用者側が満たせない）

npmのドキュメントでも、依存関係が壊れるような変更は majorを上げるのがおすすめって書かれてるよ📦🔢 (npm ドキュメント)

8.5 “破壊かどうか”の超かんたん判定フロー🔍✅​

迷ったらこれでOK👇✨

  1. それ、公開API面？（利用者が触る？） 　- No 👉 まず破壊扱いしない（でも要注意）🙂 　- Yes 👉 次へ！

  2. 利用者は 修正なしで 使い続けられる？ 　- No 👉 破壊変更💥 　- Yes 👉 次へ！

  3. 結果の意味・エラー・データ形が「変わった」と言える？ 　- Yes 👉 原則 破壊変更 寄り（移行ガイドが必要）🌀🧾 　- No 👉 非破壊（minor/patch候補）🎀

補足：TypeScript自体も、バージョン更新での“破壊的な差分”をまとめて管理してたりするよ📚（読むと「こういうのが壊れ方なんだ」が身につく！） (GitHub)

8.6 ミニ演習：自分用「破壊変更リスト」を作ろう📝🌸​

演習①：あなたの公開API面を3つ書く🧾​

例：

  • exportしてる関数：○○ / △△ / □□
  • HTTP API：POST /login のリクエスト/レスポンス
  • JSONデータ：Userの形（必須/任意）

演習②：破壊変更を10個、分類してみる🗂️✨​

下の表を埋めてね👇（コピペして使ってOK！）

変更案カテゴリ破壊？理由（利用者が困るポイント）
引数を1つ増やす（任意）形？？
export名を変える入口？？
エラーコードを変更エラー？？
計算結果の丸めを変更意味？？

演習③：あなたの“破壊変更の定義文”を1つ完成させる📏💖​

テンプレ👇

公開API面に対して、利用者が修正しないと（ビルド/実行/期待結果）が維持できない変更を破壊変更とする。 破壊変更はMAJOR、それ以外は内容に応じてMINOR/PATCHで扱う。 (Semantic Versioning)

8.7 破壊変更チェックリスト（レビュー用）✅🧁​

リリース前に、ここだけ見ればかなり防げるよ〜！✨

✅ 入口・型（ビルド面）​

  • exportを消してない？リネームしてない？🚪
  • 引数の必須/任意を変えてない？🧾
  • 型を狭めてない？（Unionの要素削除など）🧩

✅ 実行時（ランタイム面）​

  • undefined / null の扱いが変わってない？🫥
  • 例外が増えてない？種類が変わってない？📛
  • タイミングや順序、デフォルト値が変わってない？⏱️

✅ データ・通信（JSON/HTTP）​

  • 必須フィールドを増やしてない？（受け側が死ぬことある）🧾💥
  • フィールド削除・型変更してない？🧬
  • ステータスやエラー形式、意味が変わってない？🌐📣

✅ “見た目は修正”でも要注意​

  • バグ修正のつもりでも、利用者にとっては「仕様変更」になることある⚠️ （公式のリリースノートでも、改善や修正が既存コードに影響する可能性があるよって扱いになってるよ📚） (TypeScript)

8.8 AI活用プロンプト（そのままコピペOK）🤖💖​

目的：迷いを減らす＆文章を整えるだよ✨

  • 破壊判定

    • 「この変更は破壊変更？利用者が困るパターンを3つ挙げて、カテゴリ（形/意味/エラー/入口）も付けて」🔍

  • 破壊変更リスト作り

    • 「このAPI（貼る）に対して、破壊変更になりうる変更を網羅的に列挙して、チェックリスト化して」🧾✅

  • ポリシー文の作成

    • 「初心者にも伝わるやさしい口調で、“破壊変更の定義”を100〜150文字で書いて」📏🧡

  • 移行ガイドの叩き台

    • 「破壊変更が入ったときの移行ガイドを、手順1〜5で書いて。利用者が迷わないように」🪜✨

まとめ📌✨​

この章のゴールは「破壊変更」を感覚じゃなくて、自分の言葉（文章）とカテゴリで固定して、毎回同じ判断ができるようにすることだよ🙂💖 迷ったら👇だけ守ればOK！

  • 公開API面を決める🎭
  • 破壊を 形/意味/エラー/入口 に分ける🗂️
  • 利用者が 修正なしで維持できるかで決める👥✅