# コード例1: 破壊的変更の具体例
 
# === フィールド削除 ===
# v1レスポンス
{
    "user": {
        "id": 123,
        "name": "田中太郎",
        "email": "tanaka@example.com",
        "phone": "03-1234-5678"    # v2で削除 → 破壊的
    }
}
 
# v2レスポンス（phoneフィールドが消失）
{
    "user": {
        "id": 123,
        "name": "田中太郎",
        "email": "tanaka@example.com"
        # phone が存在しない → クライアントのuser.phoneがnull/undefinedに
    }
}
 
# === 型変更 ===
# v1: idがinteger
{"id": 123, "name": "田中太郎"}
 
# v2: idがstring（破壊的変更）
{"id": "usr_123", "name": "田中太郎"}
# → クライアントがidを数値として処理している場合に障害発生
 
# === 必須パラメータの追加 ===
# v1: POST /api/v1/users
# Body: {"name": "田中太郎"}  ← nameだけでOK
 
# v2: POST /api/v2/users
# Body: {"name": "田中太郎", "email": "tanaka@example.com"}
# ← emailが必須に → 旧クライアントのリクエストが400エラーに
 
# === エンドポイントの変更 ===
# v1: GET /api/v1/users/{id}/orders
# v2: GET /api/v2/customers/{id}/purchases  ← パスもリソース名も変更

# コード例2: グレーゾーン変更の具体例と判断基準
 
# === デフォルト値の変更 ===
# v1: GET /api/v1/users → ソート順がデフォルトで created_at ASC
# v2: GET /api/v1/users → ソート順がデフォルトで updated_at DESC
# 判断: クライアントがデフォルトのソート順に依存している場合は破壊的
 
# === ページネーションのデフォルトサイズ変更 ===
# v1: デフォルトで1ページ100件
# v2: デフォルトで1ページ20件
# 判断: 全件取得前提のクライアントにとっては破壊的
 
# === レスポンスフィールドの並び順変更 ===
# v1: {"id": 1, "name": "foo", "email": "bar"}
# v2: {"name": "foo", "email": "bar", "id": 1}
# 判断: JSON仕様上は順序不定だが、位置ベースのパーサーには影響する
 
# === エラーコードの追加 ===
# v1: 認証エラーは常に 401
# v2: 認証エラーを 401（認証なし）と 403（権限不足）に分離
# 判断: クライアントが401のみをハンドリングしている場合は影響あり
 
# === Null許容性の変更 ===
# v1: "address"フィールドは常にオブジェクト
# v2: "address"フィールドがnullになり得る
# 判断: null チェックなしのクライアントでNullPointerException等が発生
 
# === 判断フローチャート ===
# 1. クライアントのコード変更が必要か？
#    → Yes: 破壊的変更として扱う
#    → No:  次のチェックへ
# 2. クライアントの動作が変わるか？
#    → Yes: グレーゾーン（保守的に判断）
#    → No:  非破壊的変更
# 3. 影響を受けるクライアントの割合は？
#    → 多い: 破壊的変更として扱う
#    → 少ない: ケースバイケースで判断

# コード例3: URI パスバージョニングの実装（Python / Flask）
 
from flask import Flask, jsonify, request
from functools import wraps
 
app = Flask(__name__)
 
# --- バージョンルーティングの基本実装 ---
 
# v1: ユーザーリソース
@app.route('/api/v1/users', methods=['GET'])
def get_users_v1():
    """v1ではシンプルなユーザー情報を返す"""
    users = fetch_users_from_db()
    return jsonify({
        "users": [
            {
                "id": u.id,
                "name": u.name,
                "email": u.email
            }
            for u in users
        ]
    })
 
# v2: ユーザーリソース（拡張版）
@app.route('/api/v2/users', methods=['GET'])
def get_users_v2():
    """v2ではページネーション付きのレスポンスを返す"""
    page = request.args.get('page', 1, type=int)
    per_page = request.args.get('per_page', 20, type=int)
 
    pagination = fetch_users_paginated(page, per_page)
 
    return jsonify({
        "data": [
            {
                "id": u.id,
                "full_name": u.name,        # name → full_name に変更
                "email": u.email,
                "profile": {                  # v2で追加されたネスト構造
                    "avatar_url": u.avatar_url,
                    "bio": u.bio,
                    "created_at": u.created_at.isoformat()
                }
            }
            for u in pagination.items
        ],
        "pagination": {                       # v2で追加されたメタ情報
            "current_page": pagination.page,
            "total_pages": pagination.pages,
            "total_items": pagination.total,
            "per_page": pagination.per_page
        }
    })
 
# --- Blueprintによるバージョン分離（推奨パターン） ---
 
from flask import Blueprint
 
# バージョンごとにBlueprintを作成
v1_bp = Blueprint('v1', __name__, url_prefix='/api/v1')
v2_bp = Blueprint('v2', __name__, url_prefix='/api/v2')
 
@v1_bp.route('/users', methods=['GET'])
def v1_get_users():
    return jsonify({"version": "v1", "users": []})
 
@v2_bp.route('/users', methods=['GET'])
def v2_get_users():
    return jsonify({"version": "v2", "data": [], "pagination": {}})
 
# アプリケーションに登録
app.register_blueprint(v1_bp)
app.register_blueprint(v2_bp)
 
# --- バージョン非推奨ミドルウェア ---
 
DEPRECATED_VERSIONS = {'v1'}
SUNSET_DATES = {'v1': 'Sat, 01 Jan 2026 00:00:00 GMT'}
 
@app.before_request
def add_deprecation_headers():
    """非推奨バージョンへのリクエストに警告ヘッダーを付与"""
    path = request.path
    for version in DEPRECATED_VERSIONS:
        if f'/api/{version}/' in path:
            # RFC 8594 Sunset Header
            from flask import g
            g.deprecated_version = version
 
@app.after_request
def inject_sunset_header(response):
    """レスポンスにSunsetヘッダーを挿入"""
    from flask import g
    version = getattr(g, 'deprecated_version', None)
    if version:
        response.headers['Deprecation'] = 'true'
        response.headers['Sunset'] = SUNSET_DATES.get(version, '')
        response.headers['Link'] = (
            f'<https://api.example.com/api/v2/docs>; '
            f'rel="successor-version"'
        )
    return response

# コード例4: ヘッダーバージョニングの実装（Python / Flask）
 
from flask import Flask, jsonify, request, abort
from functools import wraps
 
app = Flask(__name__)
 
# --- メディアタイプパーサー ---
 
def parse_api_version(accept_header: str) -> int:
    """
    Acceptヘッダーからバージョンを抽出する。
 
    対応フォーマット:
      - application/vnd.example.v1+json → 1
      - application/vnd.example.v2+json → 2
      - application/json; version=1     → 1
      - application/json                → デフォルト（最新安定版）
    """
    if not accept_header:
        return get_default_version()
 
    # vnd フォーマットの解析
    import re
    vnd_match = re.search(
        r'application/vnd\.example\.v(\d+)\+json',
        accept_header
    )
    if vnd_match:
        return int(vnd_match.group(1))
 
    # パラメータフォーマットの解析
    param_match = re.search(
        r'application/json;\s*version=(\d+)',
        accept_header
    )
    if param_match:
        return int(param_match.group(1))
 
    return get_default_version()
 
def get_default_version() -> int:
    """バージョン未指定時のデフォルトバージョンを返す"""
    return 2  # 最新安定版
 
# --- バージョンデコレータ ---
 
def api_version(version: int):
    """指定バージョンでのみアクセス可能にするデコレータ"""
    def decorator(f):
        @wraps(f)
        def wrapper(*args, **kwargs):
            requested_version = parse_api_version(
                request.headers.get('Accept', '')
            )
            if requested_version != version:
                return None  # このハンドラではない
 
            response = f(*args, **kwargs)
 
            # Content-Typeにバージョン情報を含める
            if hasattr(response, 'headers'):
                response.headers['Content-Type'] = (
                    f'application/vnd.example.v{version}+json'
                )
            return response
        return wrapper
    return decorator
 
# --- マルチバージョンディスパッチャー ---
 
class VersionedEndpoint:
    """複数バージョンのハンドラを管理するディスパッチャー"""
 
    def __init__(self):
        self.handlers = {}
 
    def version(self, v: int):
        """バージョンごとのハンドラを登録するデコレータ"""
        def decorator(f):
            self.handlers[v] = f
            return f
        return decorator
 
    def dispatch(self):
        """リクエストのバージョンに応じて適切なハンドラを呼び出す"""
        requested_version = parse_api_version(
            request.headers.get('Accept', '')
        )
        handler = self.handlers.get(requested_version)
        if handler is None:
            abort(406, description=(
                f"API version {requested_version} is not supported. "
                f"Supported versions: {list(self.handlers.keys())}"
            ))
        return handler()
 
# 使用例
users_endpoint = VersionedEndpoint()
 
@users_endpoint.version(1)
def get_users_v1():
    return jsonify({"users": [{"id": 1, "name": "田中太郎"}]})
 
@users_endpoint.version(2)
def get_users_v2():
    return jsonify({
        "data": [{"id": 1, "full_name": "田中太郎", "profile": {}}],
        "pagination": {"page": 1, "total": 1}
    })
 
@app.route('/api/users', methods=['GET'])
def users():
    return users_endpoint.dispatch()

# コード例5: CHANGELOG.mdの構成例
 
# Changelog
 
All notable changes to the Example API will be documented in this file.
This project adheres to [Semantic Versioning](https://semver.org/).
 
## [2.1.0] - 2025-06-15
 
### Added
- `GET /api/v2/users/{id}/preferences` エンドポイントを追加
- ユーザーレスポンスに `timezone` フィールドを追加（オプショナル）
- バッチ取得 `POST /api/v2/users/batch` をサポート
 
### Changed
- `GET /api/v2/users` のデフォルトページサイズを50から20に変更
 
### Deprecated
- `GET /api/v2/users/{id}/settings` は v2.3.0 で削除予定
  代替: `GET /api/v2/users/{id}/preferences`
 
## [2.0.0] - 2025-01-10 [BREAKING]
 
### Breaking Changes
- ユーザーレスポンスの `name` フィールドを `full_name` に変更
- `GET /api/v1/users` のフラットレスポンスを
  `data` + `pagination` のラッパー構造に変更
- 認証方式を API Key から OAuth 2.0 に変更
 
### Added
- ユーザープロフィール情報（avatar_url, bio）を追加
- ページネーションメタ情報をレスポンスに含める
 
### Migration Guide
- 詳細は v1→v2 移行ガイド を参照
 
## [1.2.1] - 2024-11-20
 
### Fixed
- `GET /api/v1/users` でメールアドレスが null の場合に
  500 エラーが返る問題を修正
 
## [1.2.0] - 2024-10-01
 
### Added
- ユーザー検索 `GET /api/v1/users?search=keyword` をサポート
- レスポンスに `created_at` フィールドを追加

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: true
Sunset: Sat, 01 Jul 2026 00:00:00 GMT
Link: <https://api.example.com/v2/docs>; rel="successor-version"
Link: <https://api.example.com/v1-to-v2-migration>; rel="deprecation"
X-API-Version: 1.2.1
X-API-Warn: "This API version is deprecated. Please migrate to v2."
 
{
  "data": { ... },
  "_deprecation_notice": {
    "message": "API v1 は 2026年7月1日に廃止されます。v2への移行をお願いします。",
    "migration_guide": "https://api.example.com/v1-to-v2-migration",
    "sunset_date": "2026-07-01T00:00:00Z"
  }
}

# コード例6: 日付ベースバージョニングの実装概念
 
from datetime import date
from flask import Flask, jsonify, request
 
app = Flask(__name__)
 
# バージョン定義: 日付 → 変更内容のマッピング
VERSION_CHANGES = {
    '2024-01-15': {
        'description': 'Initial GA release',
        'changes': []
    },
    '2024-06-01': {
        'description': 'Add profile field to user response',
        'changes': [
            {
                'type': 'field_added',
                'endpoint': '/users',
                'field': 'profile',
                'default': None
            }
        ]
    },
    '2025-01-10': {
        'description': 'Rename name to full_name',
        'changes': [
            {
                'type': 'field_renamed',
                'endpoint': '/users',
                'old_field': 'name',
                'new_field': 'full_name'
            }
        ]
    },
    '2025-06-15': {
        'description': 'Change id from integer to string',
        'changes': [
            {
                'type': 'field_type_changed',
                'endpoint': '/users',
                'field': 'id',
                'old_type': 'integer',
                'new_type': 'string',
                'transform': lambda v: f'usr_{v}'
            }
        ]
    }
}
 
SUPPORTED_VERSIONS = sorted(VERSION_CHANGES.keys())
DEFAULT_VERSION = SUPPORTED_VERSIONS[-1]  # 最新
 
def get_requested_version() -> str:
    """リクエストからAPIバージョンを取得する"""
    # Stripe-Version ヘッダーを確認
    version = request.headers.get('Stripe-Version',
              request.headers.get('API-Version'))
 
    if version and version in VERSION_CHANGES:
        return version
 
    # アカウントのデフォルトバージョンを使用
    # （実際のStripeではアカウント作成時のバージョンが固定される）
    return DEFAULT_VERSION
 
def transform_response(data: dict, endpoint: str,
                       requested_version: str) -> dict:
    """
    リクエストされたバージョンに合わせてレスポンスを変換する。
    最新のデータ構造を基準に、古いバージョン向けに変換を適用する。
    """
    result = data.copy()
 
    # 新しいバージョンの変更を逆順に適用（巻き戻し）
    for version_date in reversed(SUPPORTED_VERSIONS):
        if version_date <= requested_version:
            break  # リクエストされたバージョンまで到達
 
        changes = VERSION_CHANGES[version_date]['changes']
        for change in changes:
            if change.get('endpoint') != endpoint:
                continue
 
            if change['type'] == 'field_renamed':
                # 新名→旧名に巻き戻す
                new_field = change['new_field']
                old_field = change['old_field']
                if new_field in result:
                    result[old_field] = result.pop(new_field)
 
            elif change['type'] == 'field_added':
                # 追加されたフィールドを除去
                field = change['field']
                result.pop(field, None)
 
            elif change['type'] == 'field_type_changed':
                # 型変更を巻き戻す（string → integer）
                field = change['field']
                if field in result and isinstance(result[field], str):
                    result[field] = int(
                        result[field].replace('usr_', '')
                    )
 
    return result
 
@app.route('/api/users/<user_id>', methods=['GET'])
def get_user(user_id):
    """日付ベースバージョニングによるユーザー取得"""
    requested_version = get_requested_version()
 
    # 内部では常に最新のデータ構造を使用
    user_data = {
        'id': f'usr_{user_id}',
        'full_name': '田中太郎',
        'email': 'tanaka@example.com',
        'profile': {
            'avatar_url': 'https://example.com/avatar.jpg',
            'bio': 'ソフトウェアエンジニア'
        }
    }
 
    # リクエストされたバージョンに合わせて変換
    response_data = transform_response(
        user_data, '/users', requested_version
    )
 
    response = jsonify(response_data)
    response.headers['API-Version'] = requested_version
    return response
 
# --- 使用例 ---
# 最新バージョン（2025-06-15）:
#   curl -H "API-Version: 2025-06-15" https://api.example.com/api/users/123
#   → {"id": "usr_123", "full_name": "田中太郎", ...}
 
# 古いバージョン（2024-01-15）:
#   curl -H "API-Version: 2024-01-15" https://api.example.com/api/users/123
#   → {"id": 123, "name": "田中太郎", ...}  # 旧構造で返る

# コード例7: フィールド選択の実装
 
from flask import Flask, jsonify, request
 
app = Flask(__name__)
 
def filter_fields(data: dict, fields: list) -> dict:
    """指定されたフィールドのみを含むレスポンスを構築する"""
    if not fields:
        return data  # fieldsが未指定なら全フィールドを返す
 
    result = {}
    for field in fields:
        # ドット記法によるネストフィールドのサポート
        # 例: "profile.avatar_url"
        parts = field.split('.')
        source = data
        target = result
        for i, part in enumerate(parts):
            if i == len(parts) - 1:
                # 最後のパート: 値をコピー
                if part in source:
                    target[part] = source[part]
            else:
                # 中間パート: ネスト構造を構築
                if part in source and isinstance(source[part], dict):
                    if part not in target:
                        target[part] = {}
                    source = source[part]
                    target = target[part]
                else:
                    break
    return result
 
@app.route('/api/users', methods=['GET'])
def get_users():
    """
    フィールド選択パラメータの使用例:
      GET /api/users?fields=id,full_name,email
      GET /api/users?fields=id,profile.avatar_url
    """
    fields_param = request.args.get('fields', '')
    fields = [f.strip() for f in fields_param.split(',')
              if f.strip()] if fields_param else []
 
    users = [
        {
            'id': 'usr_1',
            'full_name': '田中太郎',
            'email': 'tanaka@example.com',
            'profile': {
                'avatar_url': 'https://example.com/avatar1.jpg',
                'bio': 'エンジニア',
                'phone_number': '03-1234-5678'
            }
        },
        {
            'id': 'usr_2',
            'full_name': '佐藤花子',
            'email': 'sato@example.com',
            'profile': {
                'avatar_url': 'https://example.com/avatar2.jpg',
                'bio': 'デザイナー',
                'phone_number': '03-9876-5432'
            }
        }
    ]
 
    filtered_users = [filter_fields(u, fields) for u in users]
    return jsonify({'data': filtered_users})
 
# --- リクエスト例と結果 ---
 
# 全フィールド:
# GET /api/users
# → {"data": [{"id": "usr_1", "full_name": "...", ...}]}
 
# 選択フィールド:
# GET /api/users?fields=id,full_name
# → {"data": [{"id": "usr_1", "full_name": "田中太郎"},
#              {"id": "usr_2", "full_name": "佐藤花子"}]}
 
# ネストフィールド:
# GET /api/users?fields=id,profile.avatar_url
# → {"data": [{"id": "usr_1", "profile": {"avatar_url": "..."}},
#              {"id": "usr_2", "profile": {"avatar_url": "..."}}]}

# コード例8: イベントスキーマのバージョニング
 
import json
from datetime import datetime
from typing import Any
 
class VersionedEvent:
    """バージョン付きイベントの基底クラス"""
 
    def __init__(self, event_type: str, version: int,
                 payload: dict):
        self.metadata = {
            'event_id': generate_uuid(),
            'event_type': event_type,
            'version': version,
            'timestamp': datetime.utcnow().isoformat(),
            'source': 'user-service'
        }
        self.payload = payload
 
    def to_dict(self) -> dict:
        return {
            'metadata': self.metadata,
            'payload': self.payload
        }
 
    def to_json(self) -> str:
        return json.dumps(self.to_dict(), ensure_ascii=False)
 
 
# --- イベント定義: ユーザー作成 ---
 
class UserCreatedEventV1(VersionedEvent):
    """v1: シンプルなユーザー作成イベント"""
 
    def __init__(self, user_id: int, name: str, email: str):
        super().__init__(
            event_type='user.created',
            version=1,
            payload={
                'user_id': user_id,
                'name': name,
                'email': email
            }
        )
 
 
class UserCreatedEventV2(VersionedEvent):
    """v2: プロフィール情報を含むユーザー作成イベント"""
 
    def __init__(self, user_id: str, full_name: str,
                 email: str, profile: dict):
        super().__init__(
            event_type='user.created',
            version=2,
            payload={
                'user_id': user_id,      # string型に変更
                'full_name': full_name,   # name → full_name
                'email': email,
                'profile': profile        # 新規追加
            }
        )
 
 
# --- イベントコンシューマー: バージョン対応 ---
 
class UserEventConsumer:
    """複数バージョンのイベントを処理するコンシューマー"""
 
    def handle(self, event_json: str) -> None:
        event = json.loads(event_json)
        version = event['metadata']['version']
        payload = event['payload']
 
        handler = getattr(self, f'_handle_v{version}', None)
        if handler is None:
            # 未知のバージョン: ログを記録して処理をスキップ
            log_warning(
                f"Unknown event version: {version}, "
                f"event_type: {event['metadata']['event_type']}"
            )
            return
 
        handler(payload)
 
    def _handle_v1(self, payload: dict) -> None:
        """v1イベントの処理"""
        user_id = payload['user_id']
        name = payload['name']
        email = payload['email']
        # v1の処理ロジック
        create_user_record(user_id, name, email)
 
    def _handle_v2(self, payload: dict) -> None:
        """v2イベントの処理"""
        user_id = payload['user_id']
        full_name = payload['full_name']
        email = payload['email']
        profile = payload.get('profile', {})
        # v2の処理ロジック
        create_user_record_v2(user_id, full_name, email, profile)
 
 
# --- Upcastingパターン ---
 
class EventUpcaster:
    """古いバージョンのイベントを最新バージョンに変換する"""
 
    @staticmethod
    def upcast(event: dict) -> dict:
        version = event['metadata']['version']
        payload = event['payload']
 
        # v1 → v2 への変換
        if version == 1:
            payload = {
                'user_id': str(payload['user_id']),
                'full_name': payload['name'],
                'email': payload['email'],
                'profile': {}  # デフォルト値で補完
            }
            event['metadata']['version'] = 2
            event['payload'] = payload
 
        return event

# コード例9: バージョン互換性テストの実装（pytest）
 
import pytest
import json
from app import create_app
 
@pytest.fixture
def client():
    app = create_app(testing=True)
    with app.test_client() as client:
        yield client
 
class TestUserEndpointV1:
    """v1 ユーザーエンドポイントのテスト"""
 
    def test_get_users_v1_response_structure(self, client):
        """v1のレスポンス構造が正しいことを検証"""
        response = client.get('/api/v1/users')
        data = json.loads(response.data)
 
        assert response.status_code == 200
        assert 'users' in data
        assert isinstance(data['users'], list)
 
        if data['users']:
            user = data['users'][0]
            # v1では 'name' フィールドが存在する（'full_name'ではない）
            assert 'name' in user
            assert 'full_name' not in user
            # v1では 'id' が integer
            assert isinstance(user['id'], int)
            # v1では 'profile' は存在しない
            assert 'profile' not in user
 
    def test_get_users_v1_deprecation_headers(self, client):
        """v1が非推奨の場合、適切なヘッダーが返ることを検証"""
        response = client.get('/api/v1/users')
 
        assert response.headers.get('Deprecation') == 'true'
        assert 'Sunset' in response.headers
        assert 'Link' in response.headers
 
class TestUserEndpointV2:
    """v2 ユーザーエンドポイントのテスト"""
 
    def test_get_users_v2_response_structure(self, client):
        """v2のレスポンス構造が正しいことを検証"""
        response = client.get('/api/v2/users')
        data = json.loads(response.data)
 
        assert response.status_code == 200
        assert 'data' in data
        assert 'pagination' in data
        assert isinstance(data['data'], list)
 
        if data['data']:
            user = data['data'][0]
            # v2では 'full_name' フィールドが存在する
            assert 'full_name' in user
            assert 'name' not in user
            # v2では 'id' が string
            assert isinstance(user['id'], str)
            # v2では 'profile' が存在する
            assert 'profile' in user
 
    def test_get_users_v2_pagination(self, client):
        """v2のページネーションが正しく動作することを検証"""
        response = client.get('/api/v2/users?page=1&per_page=10')
        data = json.loads(response.data)
 
        pagination = data['pagination']
        assert 'current_page' in pagination
        assert 'total_pages' in pagination
        assert 'total_items' in pagination
        assert pagination['current_page'] == 1
 
class TestVersionCompatibility:
    """バージョン間の互換性テスト"""
 
    def test_v1_and_v2_same_data(self, client):
        """v1とv2が同じデータソースから返すことを検証"""
        v1_response = client.get('/api/v1/users')
        v2_response = client.get('/api/v2/users')
 
        v1_data = json.loads(v1_response.data)
        v2_data = json.loads(v2_response.data)
 
        # ユーザー数が同じであること
        assert len(v1_data['users']) == len(v2_data['data'])
 
    def test_v1_name_maps_to_v2_full_name(self, client):
        """v1のnameがv2のfull_nameに対応することを検証"""
        v1_response = client.get('/api/v1/users/1')
        v2_response = client.get('/api/v2/users/1')
 
        v1_user = json.loads(v1_response.data)
        v2_user = json.loads(v2_response.data)
 
        assert v1_user['name'] == v2_user['data']['full_name']
 
class TestDateBasedVersioning:
    """日付ベースバージョニングのテスト"""
 
    def test_old_version_returns_old_structure(self, client):
        """古いバージョンを指定すると旧構造が返ることを検証"""
        response = client.get(
            '/api/users/123',
            headers={'API-Version': '2024-01-15'}
        )
        data = json.loads(response.data)
 
        # 旧構造: idがinteger, nameフィールド
        assert isinstance(data['id'], int)
        assert 'name' in data
        assert 'full_name' not in data
 
    def test_new_version_returns_new_structure(self, client):
        """新しいバージョンを指定すると新構造が返ることを検証"""
        response = client.get(
            '/api/users/123',
            headers={'API-Version': '2025-06-15'}
        )
        data = json.loads(response.data)
 
        # 新構造: idがstring, full_nameフィールド
        assert isinstance(data['id'], str)
        assert 'full_name' in data
        assert 'name' not in data
 
    def test_version_header_in_response(self, client):
        """レスポンスにバージョン情報が含まれることを検証"""
        response = client.get(
            '/api/users/123',
            headers={'API-Version': '2024-06-01'}
        )
 
        assert response.headers.get('API-Version') == '2024-06-01'

# 解答の骨格（発展させること）:
 
from abc import ABC, abstractmethod
from typing import Callable, Optional
from dataclasses import dataclass, field
from datetime import datetime
 
@dataclass
class VersionConfig:
    """バージョンの設定情報"""
    version: str                         # "v1", "v2", "2024-01-15" 等
    status: str                          # "active", "deprecated", "sunset"
    release_date: datetime               # リリース日
    sunset_date: Optional[datetime]      # 廃止予定日（Noneなら未定）
    successor: Optional[str]             # 後継バージョン（Noneなら最新）
    transformers: dict = field(          # エンドポイント別の変換関数
        default_factory=dict
    )
 
class VersioningMiddleware:
    """バージョニングミドルウェアの基底クラス"""
 
    def __init__(self):
        self.versions: dict[str, VersionConfig] = {}
        self.metrics: dict[str, int] = {}
 
    def register_version(self, config: VersionConfig) -> None:
        """バージョンを登録する"""
        self.versions[config.version] = config
 
    def resolve_version(self, request) -> str:
        """リクエストからバージョンを解決する"""
        # 1. URIパスをチェック
        version = self._extract_from_path(request.path)
        if version:
            return version
 
        # 2. ヘッダーをチェック
        version = self._extract_from_header(request.headers)
        if version:
            return version
 
        # 3. デフォルトバージョンを返す
        return self._get_default_version()
 
    def process_request(self, request):
        """リクエストを処理し、適切なバージョンにルーティング"""
        version = self.resolve_version(request)
 
        # メトリクス収集
        self._record_metrics(version)
 
        # バージョンの状態チェック
        config = self.versions.get(version)
        if config is None:
            return self._unsupported_version_response(version)
 
        if config.status == 'sunset':
            return self._gone_response(version, config)
 
        # リクエスト変換（必要な場合）
        transformed_request = self._transform_request(
            request, version
        )
 
        return transformed_request, config
 
    def process_response(self, response, version: str):
        """レスポンスにバージョン関連ヘッダーを付与"""
        config = self.versions[version]
 
        # レスポンス変換
        transformed = self._transform_response(
            response, version
        )
 
        # 非推奨ヘッダーの付与
        if config.status == 'deprecated':
            transformed.headers['Deprecation'] = 'true'
            if config.sunset_date:
                transformed.headers['Sunset'] = (
                    config.sunset_date.strftime(
                        '%a, %d %b %Y %H:%M:%S GMT'
                    )
                )
            if config.successor:
                transformed.headers['Link'] = (
                    f'</{config.successor}/docs>; '
                    f'rel="successor-version"'
                )
 
        # バージョン情報ヘッダー
        transformed.headers['X-API-Version'] = version
 
        return transformed
 
    # --- 以下、各種ヘルパーメソッドを実装 ---
    # _extract_from_path, _extract_from_header,
    # _get_default_version, _record_metrics,
    # _unsupported_version_response, _gone_response,
    # _transform_request, _transform_response