メインコンテンツへスキップ

5. エラーモデル設計

5. エラーモデル設計

本章では、本ツールにおけるエラーの分類、扱い方、および どこで捕捉し、どこで処理を終了するかの境界を定義する。

本ツールは「安全側・再実行可能」を最優先とし、 エラー発生時は即時終了する fail-fast 方針を採用する。

5.1 エラー種別の分類

5.1.1 入力エラー（YAML / バリデーション）

YAML の内容に問題があり、再実行しても成功しないエラーを入力エラーとする。

対象

  • YAML ファイルが読めない

  • YAML 構文エラー

  • YAML定義書.md に定義された以下の違反

    • 必須キー欠落（book_id, wip_markdown 等）
    • 型不一致
    • 空禁止項目の空文字
    • 推奨ルールに基づく重複（ページ名・章名）

扱い

  • 入力エラー発生時は 即時終了
  • API 処理は一切行わない
  • 標準出力に ERROR を1行出力する
ERROR: invalid input (YAML validation error)

入力エラーは「YAML を直さない限り必ず失敗する」ため、 部分継続や回復を考慮せず fail-fast とする。

5.1.2 API エラー（通信・HTTP）

BookStack API との通信中に発生するエラーを API エラーとする。

対象

  • 通信エラー（接続失敗、タイムアウト等）
  • HTTP 5xx
  • requests が例外を送出するケース
  • API レスポンス形式不正（想定フィールド欠落等）

リトライ方針

  • 最大 3回リトライ
  • すべて失敗した場合は API エラーとして扱う

扱い

  • エラーが発生した操作を ERROR として出力
  • その時点で 処理を即時終了
ERROR: ISO 26262 / 21434 とA-SPICEの役割分担 (API error)

既存ページ・章は SKIP される設計のため、 API エラー後も 再実行すれば自然復旧できる。

5.1.3 想定外エラー

上記いずれにも該当しない、設計上想定していない例外。

対象例

  • プログラムバグ
  • 想定していない None
  • ライブラリの予期しない例外

扱い

  • 標準出力に ERROR を1行出力
  • 詳細はログに出力
  • 即時終了
ERROR: unexpected error occurred

想定外エラーは回復不能として扱い、 例外を握りつぶさず必ず終了させる。

5.2 エラー捕捉の責務分離

エラーは 層ごとに責務を分離して捕捉・変換する。

5.2.1 YAMLロード・バリデーション層

責務

  • YAML 読み込み
  • スキーマ・型・重複チェック

方針

  • 低レベル例外を 入力エラーとして正規化して送出
  • この層では終了判断を行わない

5.2.2 API クライアント層

責務

  • BookStack API 呼び出し
  • リトライ制御

方針

  • 通信例外・HTTP エラーを API エラーとして正規化
  • リトライ回数超過時に例外送出

5.2.3 ユースケース層（処理フロー）

責務

  • YAML 定義に従った処理順制御
  • OK / SKIP / ERROR の判定

方針

  • 原則として例外を捕捉しない
  • エラー発生時は ERROR を出力後、例外を上位へ送出

1件ごとの継続処理も理論上可能だが、 本ツールでは fail-fast を仕様として固定する。

5.2.4 CLI / main

責務

  • 例外の最終捕捉
  • 終了コード決定
  • プロセス終了

捕捉対象と終了コード

種別 終了コード
正常終了 0
入力エラー 2
API / 想定外 1

5.3 標準出力との関係

エラー発生時の標準出力ルールを以下に固定する。

  • 入力エラー

    • 処理開始前に ERROR を1行出力

  • API エラー

    • 失敗した対象を ERROR として出力

  • 想定外エラー

    • 汎用的な ERROR を出力

ID（Book / Chapter / Page）は出力しない。 人間が YAML と照らして挙動を判断できることを優先する。

5.4 設計上のまとめ

  • エラーは 入力 / API / 想定外 の3分類

  • 終了判断は CLI / main に集約

  • fail-fast により

    • 安全側
    • 再実行可能
    • 挙動が予測可能 な設計を維持する

このエラーモデルは、 既存構造を壊さず、YAML を直せば必ず成功する という本ツールの思想と整合している。

この形式なら、

  • BookStack Markdownモードで 背景色＋アイコン付きコールアウトが有効
  • 後から仕様だけ抜いても意味が崩れない

という状態になっている。 次は 6. CLI設計 に進むか、**例外クラス定義（Python）**を詰めるか、どちらにする？

上に戻る