nene2-python 1.8.34__tar.gz → 1.8.35__tar.gz

{nene2_python-1.8.34 → nene2_python-1.8.35}/CLAUDE.md

@@ -355,7 +355,75 @@ docs/
 
 ---
 
-## 12. PHP版 NENE2 との対応表
+## 12. フィールドトライアル（FT）方法論
+
+### 目的
+
+Python 標準ライブラリ・サードパーティライブラリを nene2-python 上で実装し、
+フレームワーク API の安定性を実装者目線で検証する。
+「実際に詰まったポイント」だけを観察ベースで Issue 化し、
+ドキュメントと設計を同時に成長させるサイクルを回す。
+
+### フロー（1 FT あたり）
+
+```
+1. テーマ選定（docs/todo/current.md から未検証パターンを選ぶ）
+2. 独立サンドボックスを作成
+   場所: /home/xi/docker/nene2-python-FT/ftNNN-テーマ名/
+   ゼロから uv init → nene2-python を依存として追加
+3. 実装 + 全チェック通過
+   uv run pytest && uv run mypy src/ && uv run ruff check src/ tests/
+4. 摩擦点を記録（F-1, F-2, ...）
+5. FT レポート作成 → docs/field-trials/2026-05-field-trial-NNN.md
+   テンプレート: docs/templates/field-trial-report.md
+6. DX Review（6ペルソナ）を実施（後述）
+7. FT番号が3の倍数なら セキュリティ診断 を実施（後述）
+8. Follow-up Issues を GitHub Issue に変換
+9. まとめて main merge → パッチバージョン（v1.8.N）でリリース
+```
+
+### DX Review — 6ペルソナ
+
+各 FT レポートの末尾に、以下 6 ペルソナ目線での評価を必ず記載する。
+「コードが動く」だけでなく「初心者から経験者まで安全に使えるか」を客観的に検証する。
+
+| ペルソナ | 属性 | 主な評価観点 |
+|---|---|---|
+| **1. 初心者** | Python 歴1年・独学中・女性・バックエンド志望 | ドキュメント理解・事故リスク・規約の使いやすさ |
+| **2. ロースキル経験者** | Python 歴3-4年・スクリプト系・男性・SES | コピペ可能性・拡張時の罠・セキュリティ的な事故リスク |
+| **3. フロントエンド寄り** | React/TS 歴4年・バックエンド転向中・ノンバイナリ | エラーレスポンスの質・Python 固有概念の学習コスト |
+| **4. バックエンド経験者** | Django/FastAPI 歴5-6年・男性・リードエンジニア | 他フレームワークとの差異・nene2 の薄さへの評価 |
+| **5. シニアエンジニア** | 設計・コードレビュー担当・女性・10-12年 | コードレビューチェックポイント・チームでの安全なパターン |
+| **6. 設計者** | nene2-python 設計ポリシー目線 | CLAUDE.md ポリシー整合性・初心者でも安全な API 達成度 |
+
+各ペルソナの記述フォーマット:
+- 状況説明 1 文（ペルソナが置かれているコンテキスト）
+- 太字サブヘッディング 2〜4個（ドキュメント理解 / 事故リスク / 規約の使いやすさ など）
+- 事故リスクは「高 / 中 / 低」で定性評価
+
+### セキュリティ診断（3の倍数 FT）
+
+**FT番号 % 3 == 0 のとき**（FT165, FT168, ...）、通常のFT完了後に追加で実施する。
+
+**診断レベル**: Django・FastAPI・SQLAlchemy 本体でも CVE が報告されてきた攻撃ベクターを対象とする。
+
+対象カテゴリ（詳細は `docs/templates/field-trial-report.md` のセキュリティ診断セクション参照）:
+
+1. **OWASP API Security Top 10 (2023)** — BOLA/IDOR・認証破損・Mass Assignment・リソース消費・SSRF・設定ミス
+2. **インジェクション攻撃** — SQL・コマンド・パストラバーサル・SSTI・HTTP ヘッダーインジェクション
+3. **認証・認可** — パスワードハッシュ・タイミング攻撃・JWT alg:none・セッション固定
+4. **入力バリデーション** — 上限なし文字列・数値オーバーフロー・Null バイト・Unicode RTL
+5. **情報漏洩** — スタックトレース公開・ログへの機密データ出力・pip-audit CVE スキャン
+6. **Python/FastAPI 固有** — ReDoS・pickle/yaml インジェクション・非同期レースコンディション・Pydantic 型強制・SQLAlchemy raw query バイパス
+
+**合否判定**:
+- **合格**: 全カテゴリ問題なし
+- **条件付き合格**: MEDIUM 以下の指摘のみ、次 FT までに修正
+- **不合格**: HIGH/CRITICAL の指摘あり → main merge 前に必須修正
+
+---
+
+## 13. PHP版 NENE2 との対応表
 
 | PHP | Python |
 |---|---|

{nene2_python-1.8.34 → nene2_python-1.8.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.34
+Version: 1.8.35
 Summary: NENE2 Python — minimal API framework following NENE2's design philosophy
 Project-URL: Homepage, https://github.com/hideyukiMORI/nene2-python
 Project-URL: Repository, https://github.com/hideyukiMORI/nene2-python

nene2_python-1.8.35/docs/field-trials/2026-05-field-trial-110.md

@@ -0,0 +1,66 @@
+# Field Trial 110: ソフトデリートパターン（論理削除）
+
+## テーマ
+
+`deleted_at: datetime | None` フィールドを使った論理削除パターンを検証する。
+- `DELETE /resources/{id}` が物理削除ではなく `deleted_at` をセットする
+- `GET /resources` / `GET /resources/{id}` が削除済みアイテムを除外する
+- DELETE は冪等（既に削除済みでも 204）
+- `deleted_at` を公開レスポンスに含めない（管理エンドポイントのみ）
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft110-soft-delete/` に以下を実装:
+
+- `Article` dataclass — `deleted_at: datetime | None = None`、`is_deleted` プロパティ
+- `dataclasses.replace()` で frozen dataclass を更新（`deleted_at` をセット）
+- `ArticleResponse` に `deleted_at` フィールドを含めない設計
+- 管理用 `/articles/{id}/deleted` エンドポイントで `deleted_at` を確認
+- 9 テスト通過
+
+## テスト結果
+
+全 9 テスト一発通過。摩擦ゼロ。
+
+## Friction Points
+
+なし。
+
+## 観察
+
+### O1: frozen dataclass の更新は dataclasses.replace() で簡潔に書ける
+
+```python
+from dataclasses import replace
+
+_articles[article_id] = replace(article, deleted_at=datetime.now(UTC))
+```
+
+`frozen=True` な dataclass でも `replace()` で新しいインスタンスを作成できる。
+イミュータブル設計を壊さずに更新できる。
+
+### O2: is_deleted プロパティでビジネスロジックをドメインに閉じ込める
+
+```python
+@property
+def is_deleted(self) -> bool:
+    return self.deleted_at is not None
+```
+
+クエリフィルタ（`a.is_deleted`）でリポジトリ層が `deleted_at is not None` を意識しなくてよい。
+
+### O3: DELETE は 204 + 冪等が REST ベストプラクティス
+
+既に削除済みのリソースへの DELETE も 204 を返すことで冪等性を保つ。
+存在しないリソースへの DELETE も同様。
+
+### O4: deleted_at をレスポンスモデルから除外するのは Pydantic の通常設計で簡単
+
+`ArticleResponse` に `deleted_at` フィールドを定義しなければ、自動的に除外される。
+`exclude=` や `model_config` の設定は不要。
+
+## まとめ
+
+FT110 は摩擦ゼロ。ソフトデリートは nene2 + Python dataclass で自然に実装できる。
+`dataclasses.replace()` / `is_deleted` プロパティ / Pydantic レスポンスフィルタリングの
+各パターンを how-to に記録する。

nene2_python-1.8.35/docs/field-trials/2026-05-field-trial-111.md

@@ -0,0 +1,53 @@
+# Field Trial 111: カーソルベースページネーション
+
+## テーマ
+
+ID ベースのカーソル（Base64 エンコード）で大規模データを安定的にページングするパターンを検証する。
+既存の `PaginationQueryParser`（オフセット型）との比較として実装する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft111-cursor-pagination/` に以下を実装:
+
+- `after` クエリパラメータ + `limit` でカーソルページネーション
+- `next_cursor` / `has_next` を含む `CursorPage` レスポンスモデル
+- Base64 URL-safe エンコードでカーソルを不透明にする
+- 100件のサンプルデータで重複なし検証
+- 7 テスト通過（修正後）
+
+## テスト結果
+
+全 7 テスト通過（1件修正後）。
+
+## Friction Points
+
+### FP1: 無効なカーソルで `binascii.Error` が捕捉されず 500 になる
+
+**状況**: `?after=invalidcursor!` のような無効な Base64 文字列を渡すと、
+`base64.urlsafe_b64decode()` が `binascii.Error` を raise する。
+これを捕捉しないと `ErrorHandlerMiddleware` が 500 として返す。
+
+```python
+# ❌ binascii.Error が uncaught → 500
+after_id = _decode_cursor(after)
+
+# ✅ try-except でカーソルデコードを保護する
+try:
+    after_id = _decode_cursor(after)
+except Exception:
+    return JSONResponse({"detail": "Invalid cursor"}, status_code=400)
+```
+
+**影響**: 中。入力バリデーションとして当然捕捉すべきだが、
+Pydantic の `Query()` では Base64 形式の検証はできない（文字列型のみ）。
+カーソルデコードは必ず try-except で保護する必要がある。
+
+**代替案**: `ValidationException` を raise して 422 にするパターンもあるが、
+不正なカーソルは「バリデーションエラー」ではなく「不正リクエスト」なので 400 が適切。
+
+## まとめ
+
+FP1 を how-to に追記。カーソルのデコードは必ず try-except で保護し 400 を返す。
+オフセットページネーションとの使い分け:
+- オフセット型: 件数が少ない、管理画面など「ページ番号」で飛びたい場合
+- カーソル型: 件数が多い、リアルタイムデータ、無限スクロールなど

nene2_python-1.8.35/docs/field-trials/2026-05-field-trial-112.md

@@ -0,0 +1,65 @@
+# Field Trial 112: バルクアップデートパターン（PATCH /items/bulk）
+
+## テーマ
+
+FT107（バルク作成・削除）の応用として、PATCH による一括更新操作を検証する。
+- 部分更新（name のみ、price のみ、両方）
+- 207 Multi-Status で部分成功/失敗
+- `dataclasses.replace()` でイミュータブルエンティティを更新
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft112-bulk-update/` に以下を実装:
+
+- `PATCH /items/bulk` — 一括更新（部分成功対応）
+- `ItemUpdateRequest` — `name: str | None`, `price: int | None`（両方省略可能、一方だけ指定可能）
+- `@field_validator` でカスタムバリデーション（空白名チェック）
+- `dataclasses.replace()` でフィールドを選択的に更新
+- 8 テスト通過
+
+## テスト結果
+
+全 8 テスト一発通過。摩擦ゼロ。
+
+## Friction Points
+
+なし。
+
+## 観察
+
+### O1: PATCH の部分更新は `name: str | None = None` + `dataclasses.replace()` で実現
+
+```python
+class ItemUpdateRequest(BaseModel):
+    item_id: int
+    name: str | None = None  # 省略可
+    price: int | None = None  # 省略可
+
+new_name = update.name if update.name is not None else item.name
+new_price = update.price if update.price is not None else item.price
+updated = replace(item, name=new_name, price=new_price)
+```
+
+`None` をデフォルトにすることで「指定されたフィールドのみ更新」を表現できる。
+
+### O2: `@field_validator` でフィールドレベルのカスタムバリデーションが簡単
+
+```python
+@field_validator("name")
+@classmethod
+def name_must_not_be_empty(cls, v: str | None) -> str | None:
+    if v is not None and v.strip() == "":
+        raise ValueError("name must not be empty")
+    return v
+```
+
+`None` の場合はスキップし、空白文字のみの文字列を拒否する設計が自然に書ける。
+
+### O3: バルク更新とバルク作成・削除のパターンは統一できる
+
+FT107（バルク作成・削除）と同じ 207 Multi-Status パターンで一括更新を実装できた。
+`succeeded` / `failed` / `total` の構造を一貫させることでクライアント側の処理が統一できる。
+
+## まとめ
+
+FT112 は摩擦ゼロ確認。PATCH バルク更新は既存の 207 パターン + `dataclasses.replace()` で実現できる。

nene2_python-1.8.35/docs/field-trials/2026-05-field-trial-113.md

@@ -0,0 +1,79 @@
+# Field Trial 113: Pydantic 識別共用体（Discriminated Union）
+
+## テーマ
+
+`Literal` 型 + `Field(discriminator="type")` による Pydantic v2 の識別共用体パターンを検証する。
+異なる形状を持つペイロードを 1 つの Union 型で受け取り、OpenAPI スキーマに oneOf として反映させる。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft113-discriminated-union/` に以下を実装:
+
+- `TextEvent`, `ImageEvent`, `VideoEvent` — それぞれ `type: Literal["text" | "image" | "video"]` を持つ Pydantic モデル
+- `Event = Annotated[Union[TextEvent, ImageEvent, VideoEvent], Field(discriminator="type")]`
+- `POST /events` — 識別共用体でリクエストを受け取り、型を自動判別
+- `GET /events` — クエリパラメータ `event_type` でフィルタリング
+- 10 テスト通過
+
+## テスト結果
+
+全 10 テスト一発通過。摩擦ゼロ。
+
+## Friction Points
+
+なし。
+
+## 観察
+
+### O1: `Field(discriminator="type")` で識別共用体を定義できる
+
+```python
+from typing import Annotated, Literal, Union
+from pydantic import BaseModel, Field
+
+class TextEvent(BaseModel):
+    type: Literal["text"]
+    content: str
+
+class ImageEvent(BaseModel):
+    type: Literal["image"]
+    url: str
+
+Event = Annotated[
+    Union[TextEvent, ImageEvent],
+    Field(discriminator="type"),
+]
+
+class EventRequest(BaseModel):
+    event: Event
+```
+
+`{"type": "text", "content": "Hello"}` → `TextEvent` に自動マッピングされる。
+未知の `type` 値（`"audio"` など）は 422 になる。
+
+### O2: OpenAPI スキーマに `oneOf` + `discriminator` が反映される
+
+FastAPI の `/docs` で確認すると、リクエストボディのスキーマが以下のように生成される:
+
+```json
+{
+  "oneOf": [
+    { "$ref": "#/components/schemas/TextEvent" },
+    { "$ref": "#/components/schemas/ImageEvent" },
+    { "$ref": "#/components/schemas/VideoEvent" }
+  ],
+  "discriminator": { "propertyName": "type" }
+}
+```
+
+各サブモデルのスキーマも個別に定義され、OpenAPI クライアントが型を正確に認識できる。
+
+### O3: 必須フィールドの欠如・型ミスマッチは 422 になる
+
+識別子 `type` が合致してもサブモデルのバリデーションは完全に行われる。
+`{"type": "text"}` （`content` 欠如）や `{"type": "video", "duration_seconds": -1}` は 422 になる。
+
+## まとめ
+
+FT113 は摩擦ゼロ確認。Pydantic v2 の識別共用体は `Field(discriminator="type")` + `Literal` で
+簡潔に実装でき、OpenAPI スキーマにも正確に反映される。

nene2_python-1.8.35/docs/field-trials/2026-05-field-trial-114.md

@@ -0,0 +1,69 @@
+# Field Trial 114: プラグインレジストリパターン
+
+## テーマ
+
+`@runtime_checkable Protocol` + 辞書ベースのレジストリで、型安全なプラグイン登録・ディスパッチを実現するパターンを検証する。
+通知ハンドラー（email / slack / webhook）を例に、実行時の `isinstance` チェックと OpenAPI ルーティングを組み合わせる。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft114-plugin-registry/` に以下を実装:
+
+- `NotificationHandlerProtocol` — `@runtime_checkable Protocol`（`name: str` + `handle()` メソッド）
+- `_registry: dict[str, NotificationHandlerProtocol]` — モジュールレベルのレジストリ
+- `register_handler()` / `get_handler()` / `list_handlers()` — レジストリ操作関数
+- `EmailHandler`, `SlackHandler`, `WebhookHandler` — 組み込みハンドラー（Protocol を満たすが継承しない）
+- `POST /notify` — ハンドラー名でディスパッチ
+- `GET /handlers` — 登録済みハンドラー一覧
+- 9 テスト通過
+
+## テスト結果
+
+全 9 テスト一発通過。摩擦ゼロ。
+
+## Friction Points
+
+なし。
+
+## 観察
+
+### O1: `@runtime_checkable Protocol` で isinstance チェックが使える
+
+```python
+from typing import Protocol, runtime_checkable
+
+@runtime_checkable
+class NotificationHandlerProtocol(Protocol):
+    name: str
+    def handle(self, payload: dict[str, object]) -> dict[str, object]: ...
+
+assert isinstance(EmailHandler(), NotificationHandlerProtocol)  # True
+```
+
+継承なしに Protocol を満たす任意のクラスを `isinstance` で検証できる。
+レジストリに登録する前の型チェックに使えるが、属性の実行時チェックはメソッド定義の存在のみ確認する（引数型は確認されない）。
+
+### O2: モジュールレベル辞書レジストリは test fixture でリセット可能
+
+```python
+_registry: dict[str, NotificationHandlerProtocol] = {}
+
+@pytest.fixture(autouse=True)
+def _reset_registry() -> None:
+    _registry.clear()
+    register_handler(EmailHandler())
+    ...
+```
+
+モジュールグローバルの辞書を直接 `clear()` → 再登録することでテスト間の独立性を確保できる。
+`importlib.reload()` は不要。
+
+### O3: 構造的サブタイピングでサードパーティハンドラーが差し込める
+
+Protocol を使うため、外部パッケージのクラスでも `name` と `handle()` があれば登録できる。
+ABC 継承を強制しないため、既存コードへの侵食がない。
+
+## まとめ
+
+FT114 は摩擦ゼロ確認。`@runtime_checkable Protocol` + 辞書レジストリは、
+拡張性の高いプラグインシステムを最小コードで実現できる。

nene2_python-1.8.35/docs/field-trials/2026-05-field-trial-115.md

@@ -0,0 +1,91 @@
+# Field Trial 115: structlog 構造化ログ + リクエストコンテキスト伝播
+
+## テーマ
+
+`RequestLoggingMiddleware` + `RequestIdMiddleware` が structlog contextvars に自動バインドする `request_id` を、
+エンドポイント内のログ呼び出しに透過的に伝播させるパターンを検証する。
+また pytest の `caplog` フィクスチャで structlog 出力をキャプチャできるかを確認する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft115-structured-logging/` に以下を実装:
+
+- `RequestLoggingMiddleware` + `RequestIdMiddleware` を組み合わせたアプリ
+- `structlog.get_logger(__name__)` でエンドポイント内からログを発行
+- `get_request_id()` でリクエスト ID をレスポンスボディに含める
+- `configure_for_testing()` を呼んで pytest caplog と統合
+- 11 テスト通過（修正後）
+
+## テスト結果
+
+2 件修正後、全 11 テスト通過。
+
+## Friction Points
+
+### FP1: `X-Request-Id` は UUID v4 形式のみ転送される — 非 UUID 値は黙って置換される
+
+**状況**: テストで `X-Request-Id: test-req-001` を送信したところ、レスポンスに別の UUID が返ってきた。
+`RequestIdMiddleware` は UUID v4 形式のみ受け付け、それ以外は新規 UUID を生成する設計になっている。
+
+```python
+# ❌ 非 UUID 形式は無効化される
+client.post("/orders", headers={"X-Request-Id": "test-req-001"})
+# → レスポンスの X-Request-Id は新規生成 UUID になる
+
+# ✅ UUID v4 形式なら転送される
+valid_uuid = "550e8400-e29b-41d4-a716-446655440000"
+client.post("/orders", headers={"X-Request-Id": valid_uuid})
+# → レスポンスの X-Request-Id は "550e8400-e29b-41d4-a716-446655440000"
+```
+
+**影響**: 小。設計として正しい動作（ログインジェクション対策）だが、
+テストで任意文字列を X-Request-Id に指定しようとすると予期せず失敗する。
+
+**代替案**: UUID v4 形式のリクエスト ID を使うか、`uuid.uuid4()` で生成してからテスト内で指定する。
+
+## 観察
+
+### O1: `RequestLoggingMiddleware` が structlog contextvars に request_id を自動バインド
+
+```python
+structlog.contextvars.bind_contextvars(
+    request_id=request_id_var.get(),
+    method=request.method,
+    path=request.url.path,
+)
+```
+
+エンドポイント内で `logger.info("order.creating", item_id=body.item_id)` を呼ぶと、
+`request_id`, `method`, `path` が自動付与される。明示的な引数渡しは不要。
+
+### O2: `configure_for_testing()` で structlog を pytest caplog に接続できる
+
+```python
+# conftest.py または test ファイルの先頭
+from nene2.log import configure_for_testing
+configure_for_testing()
+
+def test_logs(caplog: pytest.LogCaptureFixture) -> None:
+    with caplog.at_level(logging.INFO):
+        client.post("/orders", json={"item_id": 2, "quantity": 5})
+    assert any("order.creating" in record.message for record in caplog.records)
+```
+
+`configure_for_testing()` は structlog を stdlib logging ブリッジ経由で出力するように設定し直す。
+これにより pytest の caplog フィクスチャが structlog の出力を記録できる。
+
+### O3: `WARNING` レベルのログも caplog で確認できる
+
+```python
+with caplog.at_level(logging.WARNING):
+    client.get("/orders/404")
+assert any("order.not_found" in record.message for record in caplog.records)
+```
+
+`logger.warning(...)` は caplog の `WARNING` レベルフィルターで確認できる。
+
+## まとめ
+
+FP1（UUID v4 バリデーション）を how-to に追記予定。
+structlog + contextvars の伝播はフレームワークが完全に自動化しており、
+エンドポイント側の実装は `structlog.get_logger(__name__)` の呼び出しのみで完結する。

nene2_python-1.8.35/docs/field-trials/2026-05-field-trial-116.md

@@ -0,0 +1,99 @@
+# Field Trial 116: @contextmanager リソース管理 + FastAPI lifespan
+
+## テーマ
+
+`@contextmanager` の `try/finally` でリソースのクリーンアップを保証しながら、
+FastAPI の `lifespan` コンテキストマネージャと統合するパターンを検証する。
+`FakeConnectionPool` を例に、接続の取得・返却・クローズが確実に行われることを確認する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft116-context-manager/` に以下を実装:
+
+- `FakeConnectionPool` — 接続取得・返却・クローズをシミュレートする dataclass
+- `managed_connection()` — `@contextmanager` + `try/finally` で接続のリークを防ぐ
+- `lifespan()` — `@asynccontextmanager` で起動時にプール初期化、終了時にクローズ
+- 8 テスト通過（修正後）
+
+## テスト結果
+
+3 件修正後、全 8 テスト通過。
+
+## Friction Points
+
+### FP1: `TestClient(app)` をコンテキストマネージャとして使わないと lifespan が起動しない
+
+**状況**: `TestClient(app)` を直接インスタンス化してフィクスチャに渡すと、
+lifespan の `startup` フェーズが実行されない。
+`_pool` がグローバルで `None` のままなので 503 が返り続けた。
+
+```python
+# ❌ lifespan が実行されない
+@pytest.fixture
+def client() -> TestClient:
+    return TestClient(app)  # startup イベントが起きない → _pool = None のまま
+
+# ✅ コンテキストマネージャとして使う
+@pytest.fixture
+def client() -> Generator[TestClient, None, None]:
+    with TestClient(app) as c:
+        yield c  # with ブロック開始で startup、終了で shutdown が実行される
+```
+
+**影響**: 中。lifespan を使うアプリでは必ず `with TestClient(app) as c:` パターンを使う必要がある。
+FastAPI の公式ドキュメントに記載されているが、pytest フィクスチャでは見落としやすい。
+
+## 観察
+
+### O1: `@contextmanager` + `try/finally` で例外時も必ずリソースが返却される
+
+```python
+@contextmanager
+def managed_connection(pool: FakeConnectionPool) -> Generator[str, None, None]:
+    conn = pool.acquire()
+    try:
+        yield conn
+    finally:
+        pool.release(conn)  # 例外が発生しても必ず実行される
+```
+
+`try/finally` の `finally` ブロックは `yield` が例外で終了した場合も実行される。
+接続リークを防ぐ確実な方法。
+
+### O2: `@asynccontextmanager` で FastAPI lifespan を実装できる
+
+```python
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def lifespan(application: FastAPI) -> AsyncGenerator[None, None]:
+    pool = FakeConnectionPool(name="main-pool")
+    try:
+        yield
+    finally:
+        pool.close()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+`yield` 前が startup、`yield` 後（finally）が shutdown に対応する。
+`app.on_event("startup")` の非推奨化に伴い、現在はこのパターンが標準。
+
+### O3: ネストした `managed_connection` は独立して動作する
+
+```python
+with managed_connection(pool) as conn1:
+    with managed_connection(pool) as conn2:
+        assert pool.active_connections == 2
+    assert pool.active_connections == 1
+assert pool.active_connections == 0
+```
+
+内側の `with` ブロックが終了すると `conn2` が返却され、
+外側が終了すると `conn1` が返却される。LIFO 順で確実に動作する。
+
+## まとめ
+
+FP1（TestClient をコンテキストマネージャとして使う）を how-to/lifespan-and-app-state.md に追記予定。
+`@contextmanager` + lifespan の組み合わせは nene2 のデータベース接続管理パターンと一致しており、
+一般的なリソース管理の基本として重要な確認が取れた。