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

{nene2_python-1.8.32 → nene2_python-1.8.34}/CHANGELOG.md

@@ -5,6 +5,37 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.34] — 2026-05-20
+
+テストの ResourceWarning 解消と `SqlAlchemyQueryExecutor` / `SqlAlchemyTransactionManager` の `engine` プロパティ追加。
+
+### Added
+- `SqlAlchemyQueryExecutor.engine` プロパティ — 下層の SQLAlchemy エンジンを公開（テストのティアダウンで `executor.engine.dispose()` に使用）(#428)
+- `SqlAlchemyTransactionManager.engine` プロパティ — 同上 (#428)
+
+### Fixed
+- テスト実行時に Python 3.14 で 80+ 件出ていた `ResourceWarning: unclosed database` を解消 (#428)
+  - `create_app()` で `app.state.db_executor` を保存してテストからエンジンを dispose できるように変更
+  - `export_openapi.py` でエンジンを dispose するように修正
+  - テストフィクスチャを `yield` + `engine.dispose()` パターンに統一
+  - `tests/conftest.py` を新規作成し module-level app エンジンをセッション終了時に dispose
+  - `StaticPool` の最後の 1 件は `pyproject.toml` の `filterwarnings` で抑制
+
+---
+
+## [1.8.33] — 2026-05-20
+
+FT100 フィールドトライアル — In-memory TTL レスポンスキャッシュパターン検証と nene2.cache モジュール追加。
+
+### Added
+- `nene2.cache` モジュールを新設 (#409) (FT100)
+  - `TtlCache[V]` — TTL 付きインメモリキャッシュ（ジェネリック型）
+  - `time.monotonic()` ベースの TTL で NTP 調整の影響を受けない
+  - `get()`, `set()`, `delete()`, `clear()`, `size()` API
+- Field trial report: `docs/field-trials/2026-05-field-trial-100.md` (FT100)
+
+---
+
 ## [1.8.32] — 2026-05-20
 
 FT99 フィールドトライアル — Webhook HMAC-SHA256 署名検証パターン検証と nene2.security モジュール追加。

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.32
+Version: 1.8.34
 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.34/docs/field-trials/2026-05-field-trial-100.md

@@ -0,0 +1,62 @@
+# Field Trial 100: In-memory TTL レスポンスキャッシュ
+
+## テーマ
+
+重い処理の結果を TTL 付きインメモリキャッシュに格納し、重複リクエストにキャッシュから応答するパターンを nene2 上で実装する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft100-response-cache/` に以下を実装:
+
+- `TtlCache` データクラス（TTL 付き辞書）
+- FastAPI lifespan でキャッシュを初期化・破棄
+- `Depends(get_cache)` でハンドラーに注入
+- キャッシュヒット/ミス判定、TTL 失効テスト
+
+## テスト結果
+
+全 7 テスト通過。
+
+## Friction Points
+
+### FP1: nene2 に TTL キャッシュユーティリティがない
+
+**状況**: キャッシュは Web API の基本パターンだが、nene2 に `TtlCache` のようなユーティリティが存在しない。`TtlCache` を毎回自前実装する必要がある。
+
+**影響**: 開発者がスレッドセーフでないキャッシュを実装してしまうリスク。また asyncio 環境での並行アクセスの考慮が漏れやすい（Python GIL により dict 操作自体はアトミックだが、get-then-set パターンは競合する）。
+
+**期待する API**:
+```python
+from nene2.cache import TtlCache
+
+cache = TtlCache(ttl_seconds=60.0)
+cache.set("key", value)
+value = cache.get("key")  # None if expired
+```
+
+### FP2: lifespan + グローバル変数パターンに型エラーが出る
+
+**状況**: キャッシュを lifespan で初期化してグローバル変数に格納するパターンで、`async def lifespan(app: FastAPI)` の型注釈に `type: ignore[type-arg]` が必要。
+
+```python
+_cache: TtlCache | None = None
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):  # type: ignore[type-arg] が必要
+    global _cache
+    _cache = TtlCache(ttl_seconds=60.0)
+    yield
+```
+
+`app.state` を使うパターンの方がよりクリーンだが、`app.state` の型付けも `app.state.cache` のアクセスで `Any` になる。
+
+### FP3: `app.state` でのキャッシュ管理がドキュメント化されていない
+
+**状況**: `lifespan-and-app-state.md` では `app.state.db` の例はあるが、キャッシュを `app.state` に格納するパターン（`request.app.state.cache`）の説明がない。
+
+**影響**: グローバル変数を使う開発者が多く、テスト時のリセットが困難になる。
+
+## まとめ
+
+キャッシュユーティリティ追加は中程度の価値あり（FP1）。FP2・FP3 はドキュメント摩擦。
+今回は FP1 を `nene2.cache` モジュールとして実装し、Issue を起票する。

nene2_python-1.8.34/docs/field-trials/2026-05-field-trial-101.md

@@ -0,0 +1,59 @@
+# Field Trial 101: Query Parameter Filter/Sort パターン
+
+## テーマ
+
+`?status=published&sort=views&order=desc&tag=fastapi` のような複数フィルター + ソートのクエリパラメーターを型安全に扱うパターンを nene2 上で実装する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft101-query-filter/` に以下を実装:
+
+- `ArticleFilter` dataclass に `StrEnum` で列挙型フィルター
+- `get_article_filter()` ファクトリ関数で `Depends()` に接続
+- `PaginationQueryParser` と組み合わせてページネーション
+- 11 テスト通過
+
+## テスト結果
+
+全 11 テスト通過（修正後）。
+
+## Friction Points
+
+### FP1: `PaginationQueryParser.as_depends()` が存在しない（ドキュメントとの乖離）
+
+**状況**: 他のパーサー系クラスで `as_depends()` ファクトリパターンを使うケースがあり（FT83 など）、`PaginationQueryParser.as_depends()` を試みたが `AttributeError`。
+
+正しい使い方は:
+```python
+# ✅ Annotated スタイル
+pagination: Annotated[PaginationQueryParser, Depends()]
+
+# ❌ as_depends() は存在しない
+pagination: PaginationQueryParser = Depends(PaginationQueryParser.as_depends())
+```
+
+**影響**: `Depends()` の使い方が複数あるため混乱しやすい。how-to ガイドに明記が必要。
+
+### FP2: `Depends()` スタイルとデフォルト値の混在でシンタックスエラー
+
+**状況**: 複数の `Depends()` パラメーターを持つハンドラーで、`= Depends(...)` スタイルと `Annotated[T, Depends()]` スタイルを混在させると `SyntaxError: parameter without a default follows parameter with a default` が出る。
+
+```python
+# ❌ SyntaxError
+def list_articles(
+    filter_: ArticleFilter = Depends(get_article_filter),  # デフォルト値あり
+    pagination: Annotated[PaginationQueryParser, Depends()],  # デフォルト値なし
+) -> JSONResponse: ...
+
+# ✅ Annotated スタイルに統一
+def list_articles(
+    filter_: Annotated[ArticleFilter, Depends(get_article_filter)],
+    pagination: Annotated[PaginationQueryParser, Depends()],
+) -> JSONResponse: ...
+```
+
+**影響**: エラーメッセージが直感的でなく、原因がわかりにくい。
+
+## まとめ
+
+摩擦の原因はドキュメント不足。FP1・FP2 を how-to ガイドに追記する Issue を起票する。コード修正は不要。

nene2_python-1.8.34/docs/field-trials/2026-05-field-trial-102.md

@@ -0,0 +1,34 @@
+# Field Trial 102: response_model と PaginationResponse の型整合性
+
+## テーマ
+
+`response_model` と `PaginationResponse` / `JSONResponse` の組み合わせパターンを実際に動かして、OpenAPI スキーマへの影響と型整合性を検証する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft102-response-model/` に 4 パターンを実装:
+
+1. **v1**: `response_model` なし + `JSONResponse` + `PaginationResponse`
+2. **v2**: `response_model=ProductListResponse` + Pydantic モデル直返し
+3. **v3**: `response_model=ProductListResponse` + `dict` 返却（FastAPI が変換）
+4. **v4**: `response_model=ProductListResponse` + `JSONResponse`（検証はされない）
+
+## テスト結果
+
+全 9 テスト通過。
+
+## Friction Points
+
+摩擦なし。
+
+`response-patterns.md` How-to（PR #403 で追加済み）がこのパターンを説明しており、スムーズに実装できた。
+
+- パターン1（JSONResponse + PaginationResponse）は OpenAPI スキーマなしで OK
+- パターン2（Pydantic 直返し + response_model）は OpenAPI スキーマあり
+- パターン4（JSONResponse + response_model）は response_model があってもバリデーション非実施
+
+前回の摩擦（`problem_details_response()` と Pydantic 直返しの非一貫性）は PR #403 で文書化済み。
+
+## まとめ
+
+ドキュメント整備が功を奏し、摩擦ゼロで実装完了。

nene2_python-1.8.34/docs/field-trials/2026-05-field-trial-103.md

@@ -0,0 +1,47 @@
+# Field Trial 103: カスタムミドルウェアで認証情報をリクエストスコープに格納
+
+## テーマ
+
+JWT ミドルウェアで検証後の認証情報（`AuthUser`）を `request.state` に格納し、ハンドラーで `Depends()` を通じて取得するパターンを検証する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft103-request-state-auth/` に以下を実装:
+
+- `JwtAuthMiddleware` — JWT を検証して `request.state.user` に `AuthUser` を格納
+- `get_current_user()` — `request.state.user` から `AuthUser` を取得する Depends ファクトリ
+- `require_admin()` — `admin` ロールチェック依存
+- `EXCLUDE_PATHS` で `/health` をスキップ
+
+## テスト結果
+
+全 7 テスト通過。`InsecureKeyLengthWarning` はテスト用の短いシークレットによるもの（想定内）。
+
+## Friction Points
+
+### FP1: `request.state.user` アクセスに `type: ignore[attr-defined]` が必要
+
+**状況**: `request.state` は `starlette.datastructures.State` で動的属性を持つ。ミドルウェアで `request.state.user = AuthUser(...)` と設定しても、Depends ファクトリで `request.state.user` を参照する際に mypy が `attr-defined` エラーを出す。
+
+```python
+def get_current_user(request: Request) -> AuthUser:
+    user: AuthUser = request.state.user  # type: ignore[attr-defined]  # reason: middleware で確実に設定済み
+    return user
+```
+
+これは `app.state` でも同様（FT100 で確認済み）。
+
+**影響**: 低。`type: ignore` + `reason` コメントで対処可能。
+
+### FP2: `BearerTokenMiddleware` のトークン文字列が `request.state` に格納されない
+
+**状況**: nene2 の `BearerTokenMiddleware` は JWT/API キーの検証後にトークン文字列を返す（`make_require_auth()` Depends 経由）が、検証済みのペイロードやユーザー情報を `request.state` に自動格納する機能がない。
+
+カスタム JWT ミドルウェアで対応したが、`BearerTokenMiddleware` + `request.state` の統合パターンがない。
+
+**影響**: 中。`BearerTokenMiddleware` を使いたいが `request.state` にユーザー情報を格納したい場合、自前ミドルウェアを書き直す必要がある。
+
+## まとめ
+
+FP1 は既知の Starlette 制約（low）。FP2 は nene2 の認証統合に関する中程度の摩擦。
+docs として「request.state を使った認証情報伝播パターン」を how-to に追加する。

nene2_python-1.8.34/docs/field-trials/2026-05-field-trial-104.md

@@ -0,0 +1,48 @@
+# Field Trial 104: AsyncIterator を返す UseCase + StreamingResponse
+
+## テーマ
+
+UseCase が `AsyncIterator` を返し、FastAPI の `StreamingResponse` でストリーミングする本格的なパターンを検証する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft104-streaming-usecase/` に以下を実装:
+
+- `StreamLogsUseCase` — `AsyncIterator[LogEntry]` を返す UseCase
+- `ExportCsvUseCase` — CSV 行を `AsyncIterator[str]` で返す UseCase
+- NDJSON / SSE / CSV の 3 形式にストリーミング変換
+- 6 テスト通過
+
+## テスト結果
+
+全 6 テスト通過（修正後）。
+
+## Friction Points
+
+### FP1: `TestClient.stream()` 内で `r.text` が使えない
+
+**状況**: `with client.stream("GET", "/export/users.csv") as r:` コンテキスト内で `r.text` にアクセスすると `httpx.ResponseNotRead` が発生する。
+
+```python
+# ❌ ResponseNotRead
+with client.stream("GET", "/export/csv") as r:
+    content = r.text  # エラー!
+
+# ✅ iter_text() でチャンク収集
+with client.stream("GET", "/export/csv") as r:
+    content = "".join(r.iter_text())
+```
+
+**影響**: ストリーミングレスポンスのテストで直感に反するエラーが出る。`streaming.md` How-to に `iter_text()` パターンを追記する必要がある。
+
+### FP2: `AsyncUseCaseProtocol` は `AsyncIterator` を返す UseCase に対応していない
+
+**状況**: `AsyncUseCaseProtocol` は `async def execute(self, input_: I) -> O` を定義しており、`O = AsyncIterator[T]` として使うことは技術的には可能だが、`O` 型が `AsyncIterator` であることを表現するのが難しい。
+
+現在の実装では `AsyncUseCaseProtocol` を使わず、独立した UseCase クラスとして実装した。
+
+**影響**: 低。ストリーミング UseCase は専用の Protocol を定義するか、型注釈なしで書くのが現実的。
+
+## まとめ
+
+FP1 をドキュメント修正で対応。FP2 は将来の検討事項として記録。

nene2_python-1.8.34/docs/field-trials/2026-05-field-trial-105.md

@@ -0,0 +1,43 @@
+# Field Trial 105: マルチテナント DB 接続
+
+## テーマ
+
+`X-Tenant-Id` ヘッダーでテナントを切り替え、リクエストごとに異なる SQLite DB に接続するマルチテナントパターンを検証する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft105-multitenant/` に以下を実装:
+
+- `TENANT_DB_URLS` マップでテナント DB URL を管理
+- `get_tenant_session()` Depends でテナント特定・セッション生成
+- テナント分離テスト（A と B は独立した DB）
+
+## テスト結果
+
+全 6 テスト通過。
+
+## Friction Points
+
+### FP1: `create_engine()` をリクエストごとに呼ぶのはパフォーマンス上の問題
+
+**状況**: `get_tenant_session()` がリクエストごとに `create_engine()` を呼ぶ。SQLAlchemy では `create_engine()` はアプリ起動時に一度だけ呼ぶべきで、コネクションプールを使い回す設計が推奨される。
+
+nene2 にテナントごとのエンジンキャッシュパターンがない。`TtlCache[Session]` で代替できるが、セッションはリクエストスコープで閉じる必要があるため、エンジンをキャッシュすべき。
+
+```python
+# 推奨パターン
+_engine_cache: dict[str, Engine] = {}
+
+def get_engine(tenant_id: str) -> Engine:
+    if tenant_id not in _engine_cache:
+        _engine_cache[tenant_id] = create_engine(TENANT_DB_URLS[tenant_id], ...)
+    return _engine_cache[tenant_id]
+```
+
+### FP2: `SqlAlchemyQueryExecutor` はシングルエンジン想定
+
+**状況**: `nene2.database.SqlAlchemyQueryExecutor` はアプリ起動時に単一エンジンで初期化することを前提としている。マルチテナントでリクエストごとに異なるエンジンを使う場合、`SqlAlchemyQueryExecutor` を使わず直接 `Session` を操作する必要がある。
+
+## まとめ
+
+FP1 は `TtlCache` を使ったエンジンキャッシュパターンとして docs に追記する。FP2 はアーキテクチャ設計上の制約として記録。コード修正は不要。

nene2_python-1.8.34/docs/field-trials/2026-05-field-trial-106.md

@@ -0,0 +1,39 @@
+# Field Trial 106: Idempotency Key パターン
+
+## テーマ
+
+`Idempotency-Key` ヘッダーを使って POST リクエストを冪等にするパターンを検証する。
+`nene2.cache.TtlCache` の実用例として組み込む。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft106-idempotency/` に以下を実装:
+
+- `TtlCache[dict[str, Any]]` を `app.state.idempotency_cache` として lifespan で初期化
+- `POST /orders` で `Idempotency-Key` ヘッダーをチェック
+- 既存キャッシュがあれば `X-Idempotency-Replayed: true` ヘッダーと共にキャッシュから返す
+- キャッシュなければ UseCase を実行してキャッシュに保存
+- 7 テスト通過
+
+## テスト結果
+
+全 7 テスト通過。
+
+## Friction Points
+
+### FP1: Idempotency Key 同一キー + 異なるボディの扱いが未定義
+
+**状況**: Stripe などの実装では、同じ `Idempotency-Key` で異なるリクエストボディを送ると `422 Unprocessable Entity` を返す。現在の実装ではキャッシュされた最初のレスポンスを無条件に返すため、ボディが変わっても同じレスポンスが返る。
+
+**影響**: 中。金融系 API では重要だが、一般的な API では省略可。
+
+### FP2: Idempotency Key ユーティリティがない
+
+**状況**: `TtlCache` を使って実装できたが、`get_idempotency_cache()` Depends パターンや `X-Idempotency-Replayed` ヘッダーの付与は完全に自前実装。Stripe / Square などで標準化されたパターンであるため、nene2 に軽量ユーティリティがあると便利。
+
+**影響**: 低。`TtlCache` + ハンドラーコードで完結可能。
+
+## まとめ
+
+`TtlCache` の実用例として Idempotency Key パターンはスムーズに実装できた。摩擦は小さい。
+docs として how-to を追加する。

nene2_python-1.8.34/docs/field-trials/2026-05-field-trial-107.md

@@ -0,0 +1,46 @@
+# Field Trial 107: Bulk Operations（一括作成・削除）
+
+## テーマ
+
+`POST /items/bulk` と `DELETE /items/bulk` による一括操作パターンを検証する。
+部分成功（一部成功・一部失敗）を 207 Multi-Status で返す方法も確認する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft107-bulk-ops/` に以下を実装:
+
+- `POST /items/bulk` — 一括作成（価格制限でビジネスバリデーション、部分失敗対応）
+- `DELETE /items/bulk` — 一括削除（存在しない ID は failed に入れる）
+- 207 Multi-Status レスポンスに `succeeded` / `failed` を含める
+- 8 テスト通過（修正後）
+
+## テスト結果
+
+全 8 テスト通過（修正後）。
+
+## Friction Points
+
+### FP1: `TestClient.delete()` が `json` パラメーターを受け付けない
+
+**状況**: `DELETE` リクエストにリクエストボディを付ける場合、`client.delete(url, json=body)` は `TypeError` になる。
+
+```python
+# ❌ TypeError: unexpected keyword argument 'json'
+r = client.delete("/items/bulk", json={"ids": [1, 2]})
+
+# ✅ request() を使う
+r = client.request("DELETE", "/items/bulk", json={"ids": [1, 2]})
+```
+
+**影響**: 中。DELETE + ボディはやや非標準だが、一括削除では一般的なパターン。テストコードが `request()` を直接使う必要があるため直感的でない。
+
+**代替案**: ボディを持つ DELETE の代わりに `POST /items/bulk-delete` にする方が REST 的にクリーン（ボディを持つ DELETE は RFC 9110 で「意味がないわけではないが、推奨されない」）。
+
+### FP2: 207 Multi-Status のレスポンス型が OpenAPI スキーマに表現しにくい
+
+**状況**: `response_model` で 207 のスキーマを定義しようとすると、succeeded/failed の型が複雑になる。実用的には `response_model` なしで `JSONResponse` を直接返すのが現実的。
+
+## まとめ
+
+FP1 は how-to に追記（`TestClient` の HTTP メソッドと `json` パラメーターの注意点）。
+FP2 はドキュメント摩擦（bulk 操作は `response_model` を省略して OK）。

nene2_python-1.8.34/docs/field-trials/2026-05-field-trial-108.md

@@ -0,0 +1,46 @@
+# Field Trial 108: Pydantic computed_field と property パターン
+
+## テーマ
+
+Pydantic v2 の `@computed_field` + `@property` を使って、ストアドフィールドから計算されるプロパティを
+OpenAPI スキーマに自動的に含めるパターンを検証する。
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft108-computed-field/` に以下を実装:
+
+- `ProductResponse` — `price_dollars`, `is_in_stock`, `display_name` の computed fields
+- `OrderLineResponse` — ネストした computed fields (`line_total_cents`, `line_total_dollars`)
+- `/order-preview` エンドポイントで `JSONResponse(line.model_dump(mode="json"))` パターン確認
+- 6 テスト通過
+
+## テスト結果
+
+全 6 テスト通過。
+
+## Friction Points
+
+### FP1: `model_dump()` が datetime を Python オブジェクトのまま返す → `JSONResponse` で 500 エラー
+
+**状況**: `OrderLineResponse` のネストモデルには `created_at: datetime` フィールドがある。
+`JSONResponse(line.model_dump())` を使うと、`json.dumps` が `datetime` を直列化できずに
+`TypeError: Object of type datetime is not JSON serializable` で 500 エラーになる。
+
+```python
+# ❌ model_dump() は datetime をそのまま返す → JSONResponse でエラー
+return JSONResponse(line.model_dump())
+
+# ✅ mode="json" を指定すると datetime を ISO 8601 文字列に変換する
+return JSONResponse(line.model_dump(mode="json"))
+```
+
+**影響**: 大。`response_model=` を使う通常のルートは FastAPI が自動変換するため問題ないが、
+`JSONResponse` を直接返すルート（207 Multi-Status, /order-preview など）でこのパターンを
+使い忘れると本番で 500 エラーになる。
+
+**代替案**: `jsonable_encoder(line.model_dump())` でも変換できるが、`mode="json"` の方が Pydantic 標準。
+
+## まとめ
+
+`@computed_field` + `@property` は摩擦ゼロで OpenAPI スキーマに含められる優れたパターン。
+FP1 は `JSONResponse` を直接使う場合の注意点として how-to に追記する。

nene2_python-1.8.34/docs/field-trials/2026-05-field-trial-109.md

@@ -0,0 +1,53 @@
+# Field Trial 109: API バージョニング（v1/v2 ルーティング）
+
+## テーマ
+
+FastAPI の `APIRouter` を使って `/v1` と `/v2` でエンドポイントを分離するパターンを検証する。
+- フィールド名の変更（`email` → `contact_email`）
+- フィールドの追加（`age` を v2 で追加）
+- `full_name` から `first_name`/`last_name` への分割
+- OpenAPI スキーマが両バージョンを正確に反映するか
+
+## 実施内容
+
+`/home/xi/docker/nene2-python-FT/ft109-api-versioning/` に以下を実装:
+
+- ドメイン `User` dataclass（バージョン非依存）
+- `UserResponseV1` — `full_name`, `email`
+- `UserResponseV2` — `first_name`, `last_name`, `contact_email`, `age`
+- `v1_router = APIRouter(prefix="/v1", tags=["v1"])`
+- `v2_router = APIRouter(prefix="/v2", tags=["v2"])`
+- 9 テスト通過
+
+## テスト結果
+
+全 9 テスト一発通過。摩擦ゼロ。
+
+## Friction Points
+
+なし。`APIRouter(prefix="/v1")` でルーターを分離し `app.include_router()` で登録するだけで
+バージョン分離が完成する。OpenAPI スキーマも `UserResponseV1` / `UserResponseV2` を
+個別に定義することで両バージョンのスキーマが正確に生成される。
+
+## 観察
+
+### O1: バージョン間の共有ロジックはドメイン層に置く
+
+`find_user()` などのクエリ関数はバージョン非依存のドメイン層に置き、
+各バージョンのハンドラーから呼ぶ設計が自然に機能した。
+`from_domain()` クラスメソッドで変換することでドメインと HTTP を分離できた。
+
+### O2: OpenAPI タグでバージョンを整理できる
+
+`tags=["v1"]` / `tags=["v2"]` を `APIRouter` に指定すると、
+Swagger UI でバージョンごとにグループ化されて見やすくなる。
+
+### O3: `APIRouter` prefix は重複しない
+
+`app.include_router(v1_router)` で登録すると `/v1/users` になる。
+ルーター内のパスに `/v1` を書く必要はない（二重にならない）。
+
+## まとめ
+
+FT109 は摩擦ゼロ確認。APIバージョニングは FastAPI の `APIRouter` + `prefix` で
+自然に実現できる。how-to ドキュメントに記録のみ。

nene2_python-1.8.34/docs/how-to/api-versioning.md

@@ -0,0 +1,92 @@
+# How-to: API バージョニング
+
+FastAPI の `APIRouter` + `prefix` でエンドポイントを `/v1`, `/v2` に分離するパターン。
+
+---
+
+## 基本構成
+
+```python
+from fastapi import APIRouter, FastAPI
+
+app = FastAPI()
+
+v1_router = APIRouter(prefix="/v1", tags=["v1"])
+v2_router = APIRouter(prefix="/v2", tags=["v2"])
+
+@v1_router.get("/users")
+def list_users_v1() -> list[UserResponseV1]:
+    ...
+
+@v2_router.get("/users")
+def list_users_v2() -> list[UserResponseV2]:
+    ...
+
+app.include_router(v1_router)
+app.include_router(v2_router)
+```
+
+`APIRouter` の `prefix` はルーター内のパスに **自動的に付加**される。
+ルーター内のパスに `/v1` を書く必要はない（二重にならない）。
+
+---
+
+## ドメイン層は共有、HTTP 層でバージョン差分を吸収
+
+バージョン間の共有ロジックはドメイン層に置き、各バージョンの Pydantic モデルで差分を表現する。
+
+```python
+# ドメイン層（バージョン非依存）
+@dataclass(frozen=True, slots=True)
+class User:
+    user_id: int
+    first_name: str
+    last_name: str
+    email: str
+    age: int
+
+# v1: full_name に結合
+class UserResponseV1(BaseModel):
+    user_id: int
+    full_name: str
+    email: str
+
+    @classmethod
+    def from_domain(cls, user: User) -> "UserResponseV1":
+        return cls(
+            user_id=user.user_id,
+            full_name=f"{user.first_name} {user.last_name}",
+            email=user.email,
+        )
+
+# v2: first_name/last_name を分離 + age を追加 + email → contact_email
+class UserResponseV2(BaseModel):
+    user_id: int
+    first_name: str
+    last_name: str
+    contact_email: str
+    age: int
+
+    @classmethod
+    def from_domain(cls, user: User) -> "UserResponseV2":
+        return cls(
+            user_id=user.user_id,
+            first_name=user.first_name,
+            last_name=user.last_name,
+            contact_email=user.email,
+            age=user.age,
+        )
+```
+
+---
+
+## OpenAPI スキーマ
+
+`tags=["v1"]` / `tags=["v2"]` を `APIRouter` に指定すると Swagger UI でバージョンごとに
+グループ化される。スキーマには `UserResponseV1` / `UserResponseV2` が個別に定義される。
+
+---
+
+## 参照
+
+- FT109: `docs/field-trials/2026-05-field-trial-109.md`