この記事のポイント

  • Annotated型の設計意図をレビューで正しく読み取れる
  • 型安全と付加情報を両立させる設計責務を整理できる
  • バリデーション・シリアライズ基盤への応用設計をレビューできる

そもそもAnnotatedとは

Python 3.9以降で正式導入された typing.Annotated は、型ヒントにメタ情報（補助注釈）を追加できる仕組みです。

from typing import Annotated

Age = Annotated[int, "年齢は0歳以上"]

特徴は以下です。

  • 静的型自体は int のまま変化しない
  • 補助情報を複数積層可能
  • バリデーション・API生成・ドキュメント生成などで利用
  • 型システムには影響せず、周辺処理で参照される

型安全は維持しつつ、追加情報を型定義に埋め込むのが設計上の主目的です。

なぜこれをレビューするのか

現場での失敗例は以下です。

  • Annotatedを安易に使い責務分離崩壊
  • バリデーションと型定義の境界不明瞭化
  • 実行系バリデータと型注釈が設計的に絡みすぎる
  • 情報冗長化・多重責務化

レビューアーは「型定義の責務は何を持つべきか？」を冷静に読み取る必要があります。

レビューアー視点

  • Annotated導入理由が設計責務と一致しているか
  • 型定義と検証責務が分離維持されているか
  • Annotatedの補助情報は周辺基盤が活用可能か
  • バリデーション情報を型定義に過剰移譲していないか
  • Annotated肥大化が起きていないか

開発者視点

  • 型定義の責務は型情報のみ保持が原則
  • Annotatedは外部バリデーション層の補助情報として活用
  • 型安全と検証処理の実行責務を明確に分離
  • 定義肥大防止・再利用性重視で設計
  • 周辺利用（OpenAPI, Pydantic等）での実用想定整理

良い実装例

なぜこの実装が良いのか

  • 型定義は型情報本体を保持
  • Annotated情報は外部バリデーション層用
  • 検証責務は型システムに持たせず実行時側に任せる
  • 再利用性・責務分離性が高い設計
# user_schema.py

from typing import Annotated
from dataclasses import dataclass

class PositiveInt:
    """0以上であるべき意図を表現"""
    pass

@dataclass
class User:
    user_id: Annotated[int, PositiveInt]
    name: str
# validator.py

def validate_user(user: User):
    if user.user_id < 0:
        raise ValueError("user_idは0以上でなければなりません")
補足

型情報（int）と検証情報（PositiveInt）が分離され、型注釈の拡張用途に留まっている構造です。レビューアーはこの責務線引きを読む必要があります。

レビュー観点

  • Annotatedは型定義の補助情報用途に限定されているか
  • 実行時検証責務が型定義から漏洩していないか
  • 情報肥大化していないか
  • 周辺基盤利用可能な情報粒度になっているか
  • 再利用性が保たれているか

良くない実装例: ケース1（型定義が検証責務を持ちすぎ）

# bad_validation_inside_type.py

from typing import Annotated

@dataclass
class User:
    user_id: Annotated[int, ">= 0"]
    name: str

@Reviewer
検証条件が型注釈に直接記述されています。検証ロジックは外部責務として分離してください。

問題点

  • バリデーション表現を型定義内に埋め込み
  • 型定義の責務肥大化
  • 可読性・再利用性低下

改善例

# good_validation_separation.py

class PositiveInt:
    """意図情報のみ型注釈で表現"""

@dataclass
class User:
    user_id: Annotated[int, PositiveInt]
    name: str

型情報は常に純粋な型表現を保つのが基本原則です。レビューでは責務肥大化を即座に検出します。

良くない実装例: ケース2（Annotated乱用による情報過剰混在）

# bad_annotated_overuse.py

from typing import Annotated

@dataclass
class Product:
    product_id: Annotated[int, "必須", "0以上", "最大桁数6"]

@Reviewer
付加情報が注釈に過剰混在し始めています。注釈責務を分離・整理してください。

問題点

  • Annotated情報が多目的混在
  • 各注釈の責務粒度崩壊
  • バリデーション・ドキュメント・制約が区別不能

改善例

# good_annotated_responsibility.py

class Required:
    pass

class PositiveInt:
    pass

class MaxDigits6:
    pass

@dataclass
class Product:
    product_id: Annotated[int, Required, PositiveInt, MaxDigits6]

注釈粒度をクラス単位で明確化することで責務分離しやすくなります。レビューでは責務識別性を重点確認します。

良くない実装例: ケース3（Annotated未使用で周辺基盤利用機会を逃す）

# bad_no_annotated_usage.py

@dataclass
class User:
    user_id: int
    name: str

@Reviewer
型定義に付加情報が一切含まれていません。周辺基盤活用可能性も含めて補助注釈設計を検討してください。

問題点

  • 型情報が純粋すぎて補助情報不足
  • OpenAPI生成・Pydantic自動検証等で不足
  • 実務基盤活用機会損失

改善例

# good_annotated_minimal_extension.py

class PositiveInt:
    pass

@dataclass
class User:
    user_id: Annotated[int, PositiveInt]
    name: str

Annotatedは実行系ではなく周辺自動生成系向けの補助設計で有効活用できます。レビューでは基盤全体観点で読み取ります。

良くない実装例: ケース4（Annotatedの責務を外部で過剰利用）

# bad_reflection_abuse.py

from typing import Annotated, get_type_hints

class PositiveInt:
    pass

@dataclass
class User:
    user_id: Annotated[int, PositiveInt]
    name: str

# 実行時リフレクションで注釈解釈
annotations = get_type_hints(User)

@Reviewer
実行系ロジックが型注釈情報に過剰依存し始めています。責務混在リスクを警戒してください。

問題点

  • 実行時処理で型注釈解析過剰活用
  • 型定義側の修正が即座に実行系へ波及
  • 責務線引きが曖昧化

改善例

# good_reflection_boundary.py

# リフレクションは極力固定情報に限定
SAFE_ANNOTATIONS = {
    "user_id": PositiveInt
}

型注釈情報は設計資料として留め、実行系は別途構成が責務整理として安定します。レビューでは運用リスク観点で評価します。

観点チェックリスト

まとめ

Annotated型は「型情報の中心性を壊さず、補助情報を型に紐付ける道具」です。
レビューアーは常に

  • 型情報本体は純粋に保たれているか
  • 責務混在が起きていないか
  • 補助情報粒度は適正か
  • 実行系影響範囲は最小か

を読み解き、「型定義は設計資料であって実行依存ではない」設計原則を守らせるレビュー力を養います。
Annotatedレビューは現場型設計教育で非常に強力な教材になります。