nene2-python 1.8.4__tar.gz → 1.8.6__tar.gz

{nene2_python-1.8.4 → nene2_python-1.8.6}/CHANGELOG.md

@@ -5,6 +5,29 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.6] — 2026-05-20
+
+FT41〜FT42 フィールドトライアル — structlog テスト統合ドキュメント・configure_problem_details リセット関数。
+
+### Added
+- `nene2.http.reset_problem_details()` — `configure_problem_details()` で設定したグローバル状態をテスト間でリセットするヘルパー関数 (FT42)
+- Field trial reports: `docs/field-trials/2026-05-field-trial-41.md`、`docs/field-trials/2026-05-field-trial-42.md`
+
+### Changed
+- `docs/how-to/run-tests.md` — `configure_for_testing()` + `caplog` による structlog ログキャプチャパターンを追記 (FT41)
+
+---
+
+## [1.8.5] — 2026-05-20
+
+FT37〜FT40 フィールドトライアル — RequestSizeLimitMiddleware パスごとサイズ制限とドキュメント改善。
+
+### Added
+- `RequestSizeLimitMiddleware` に `path_limits: dict[str, int] | None = None` パラメータを追加 — パスごとに異なるリクエストボディサイズ制限を設定可能に (FT39)
+- Field trial reports: `docs/field-trials/2026-05-field-trial-37.md` 〜 `docs/field-trials/2026-05-field-trial-40.md`
+
+---
+
 ## [1.8.4] — 2026-05-20
 
 FT33〜FT36 フィールドトライアル — バリデーション・DB整合性・混合認証・非同期ヘルスチェック改善。

{nene2_python-1.8.4 → nene2_python-1.8.6}/PKG-INFO

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

@@ -0,0 +1,77 @@
+# Field Trial 37: PaginationResponse + PaginationQueryParser 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.4 時点
+**テーマ**: `PaginationQueryParser` の `Depends()` パターンと `PaginationResponse.to_dict()` を使ったページネーションパイプラインの実運用確認
+
+---
+
+## 概要
+
+50 件の `Product` データを `PaginationQueryParser` で limit/offset 制御し、
+`PaginationResponse.to_dict()` で slotted dataclass を自動シリアライズして `JSONResponse` に変換するパイプラインを検証した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft37-pagination/` に以下を作成:
+
+- **`app.py`** — `Annotated[PaginationQueryParser, Depends()]` パターンの `/api/products` エンドポイント
+- **`test_app.py`** — デフォルト・カスタム・最終ページ・無効値・Depends 動作確認 (9 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+**テスト結果**: 13 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP37-1: `Annotated[PaginationQueryParser, Depends()]` と書く必要がある
+
+**分類**: 軽微な摩擦（FastAPI 標準パターン）
+
+`def list(pagination: PaginationQueryParser = Depends())` ではなく
+`def list(pagination: Annotated[PaginationQueryParser, Depends()])` が推奨パターン。
+FastAPI の仕様に従っているが、初見では迷いやすい。
+
+**判断**: `docs/how-to/validation.md` および新規作成する how-to への記載で対応。
+
+---
+
+### FP37-2: `to_dict()` は dataclass のみ自動シリアライズ
+
+**分類**: 既知の制約（軽微）
+
+`PaginationResponse.to_dict()` は `dataclasses.is_dataclass()` で判定する。
+Pydantic モデルの items は `.model_dump()` を個別に呼ぶ必要がある。
+通常の dict はそのまま通過する。
+
+**判断**: dataclass 向け最適化という設計意図通り。
+Pydantic モデルとの混在ユースケースは how-to ドキュメントに記載する。
+
+---
+
+### FP37-3: `total` 省略時に `"total"` キーが消える（設計通り）
+
+**分類**: 設計通り（摩擦なし）
+
+`PaginationResponse(items=[], limit=10, offset=0)` のように `total` を渡さないと
+`to_dict()` の結果に `"total"` キーが含まれない。
+`total=None` を明示しても同じ結果。
+
+**判断**: 全件数を取得しない効率的なページネーションをサポートする意図通り。
+
+---
+
+## フレームワーク変更
+
+なし（全て設計通りの挙動）
+
+---
+
+## 関連
+
+- `nene2.http.PaginationQueryParser`
+- `nene2.http.PaginationResponse`
+- FT10 (PaginationResponse.to_dict() スロット対応, v1.3.0)

nene2_python-1.8.6/docs/field-trials/2026-05-field-trial-38.md

@@ -0,0 +1,85 @@
+# Field Trial 38: SqlAlchemyTransactionManager.transactional() 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.4 時点
+**テーマ**: 注文作成（在庫更新 + 注文レコード作成）をトランザクションで包み、途中での例外発生時のロールバック動作を確認する
+
+---
+
+## 概要
+
+`SqlAlchemyTransactionManager.transactional(callback)` を使って複数の DB 書き込みを一つのトランザクションに包み、途中で例外が発生した場合のロールバック動作を検証した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft38-transactions/` に以下を作成:
+
+- **`app.py`** — 在庫チェック + 在庫減少 + 注文作成を `transactional()` で包んだ注文 API
+- **`test_app.py`** — 正常注文・在庫不足・ロールバック確認・連続注文 (6 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (3 件)
+
+**テスト結果**: 9 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP38-1: コールバック内で型アノテーションに `DatabaseQueryExecutorInterface` が必要
+
+**分類**: 軽微な摩擦（mypy --strict 使用時）
+
+```python
+def _do_create(db: object) -> int:
+    ...
+```
+
+`db` を `object` 型にするとメソッド呼び出しに mypy エラーが出る。
+`DatabaseQueryExecutorInterface` をインポートして型アノテーションする必要がある。
+
+**判断**: mypy --strict の設計上当然の制約。インポートはやや冗長だが許容範囲。
+`db: DatabaseQueryExecutorInterface` が推奨パターンとしてドキュメントに記載されている。
+
+---
+
+### FP38-2: savepoint（ネストトランザクション）はサポートしない
+
+**分類**: 既知の制約（設計通り）
+
+`DatabaseQueryExecutorInterface` が持つのは `fetch_all` / `fetch_one` / `write` のみ。
+SQLAlchemy の savepoint 機能（`SAVEPOINT` / `ROLLBACK TO SAVEPOINT`）は使えない。
+
+**判断**: フレームワークの抽象化レイヤーが Pure SQL テキストベースの設計を採用しているため、
+ORM/Connection 固有の高度な機能は意図的に除外されている。
+savepoint が必要な場合は SQLAlchemy を直接使う Repository を実装するのが正しいパターン。
+
+---
+
+### FP38-3: トランザクション途中の例外はすべてロールバックされる（設計通り）
+
+**分類**: 設計通り（摩擦なし）
+
+```python
+def _callback(db: DatabaseQueryExecutorInterface) -> None:
+    db.write("INSERT ...")  # ← この変更も
+    raise ValueError("oops")  # ← ここで例外 → 全部ロールバック
+```
+
+例外の種類に関わらず（`DatabaseIntegrityException` 以外でも）全変更がロールバックされる。
+これは `SqlAlchemyTransactionManager.transactional()` の期待される動作。
+
+---
+
+## フレームワーク変更
+
+なし（全て設計通りの挙動）
+
+---
+
+## 関連
+
+- `nene2.database.SqlAlchemyTransactionManager`
+- `nene2.database.DatabaseQueryExecutorInterface`
+- FT16 (DatabaseIntegrityException, v1.7.0)
+- FT34 (DatabaseIntegrityException 実運用, v1.8.3)

nene2_python-1.8.6/docs/field-trials/2026-05-field-trial-39.md

@@ -0,0 +1,95 @@
+# Field Trial 39: RequestSizeLimitMiddleware 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.4 時点
+**テーマ**: `RequestSizeLimitMiddleware` で JSON ボディとバイナリアップロードのサイズを制限するパターンと、パスごとに異なる制限を設定したいユースケースの確認
+
+---
+
+## 概要
+
+小さな `max_bytes` 制限（200 bytes）を設定したアプリで、正常なリクエスト・超過リクエスト・除外パス・境界値を検証した。
+主な発見: パスごとに異なる制限（例: 通常 API は 1 MiB、アップロードエンドポイントは 10 MiB）が設定できない摩擦を発見。`path_limits` パラメータを追加して対応。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft39-request-size/` に以下を作成:
+
+- **`app.py`** — `RequestSizeLimitMiddleware(max_bytes=200, exclude_paths=[...])` の動作確認アプリ
+- **`test_app.py`** — 正常・超過・除外パス・境界値の動作確認 (8 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (3 件)
+
+**テスト結果**: 11 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP39-1: パスごとに異なる max_bytes を設定できない
+
+**分類**: 摩擦あり → **実装で対応**
+
+`RequestSizeLimitMiddleware` は全体で一つの `max_bytes` のみ設定できる。
+アップロードエンドポイント（例: 10 MiB）と通常 API（例: 1 MiB）で異なる制限を設定したい場合、
+`exclude_paths` でアップロードを除外してハンドラー内で手動チェックするしかなかった。
+
+**対応**: `ThrottleMiddleware.path_limits` と同様のパターンで `path_limits: dict[str, int] | None` を追加 (#259)。
+
+```python
+app.add_middleware(
+    RequestSizeLimitMiddleware,
+    max_bytes=1_048_576,                  # デフォルト: 1 MiB
+    path_limits={
+        "/upload/file": 10_485_760,       # /upload/file: 10 MiB
+        "/api/import": 5_242_880,         # /api/import: 5 MiB
+    },
+)
+```
+
+413 レスポンスの `max_bytes` フィールドはパス固有の制限値を返す。
+
+---
+
+### FP39-2: max_bytes 構造化フィールドが 413 レスポンスに含まれる（FT23 改善の確認）
+
+**分類**: 良い設計の確認
+
+```json
+{
+  "status": 413,
+  "type": ".../payload-too-large",
+  "title": "Payload Too Large",
+  "max_bytes": 200
+}
+```
+
+`max_bytes` フィールドがあることでクライアントがプログラムで制限値を知れる。
+FT23 で追加された改善が実際に役立つことを確認。
+
+---
+
+### FP39-3: Content-Length ヘッダーによる早期拒否が機能する
+
+**分類**: 設計通り（摩擦なし）
+
+Content-Length ヘッダーが `max_bytes` を超える場合、ボディを読む前に 413 を返す。
+メモリ効率が良い設計。
+
+---
+
+## フレームワーク変更
+
+- `RequestSizeLimitMiddleware` に `path_limits: dict[str, int] | None = None` を追加 (FP39-1)
+- テスト 2 件追加
+
+---
+
+## 関連
+
+- `nene2.middleware.RequestSizeLimitMiddleware`
+- FT12 (RequestSizeLimitMiddleware exclude_paths, v1.5.0)
+- FT23 (413 レスポンスに max_bytes 追加, v1.8.0)
+- FT28 (ThrottleMiddleware path_limits, v1.8.1)
+- Issue #259

nene2_python-1.8.6/docs/field-trials/2026-05-field-trial-40.md

@@ -0,0 +1,87 @@
+# Field Trial 40: 多ドメイン連携（Article + Tag 紐付け）実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.4 時点
+**テーマ**: 1 つの UseCase が 2 つのリポジトリ（Article + Tag）を横断するパターンの実運用確認
+
+---
+
+## 概要
+
+`TagArticleUseCase` が `InMemoryArticleRepository` と `InMemoryTagRepository` を
+コンストラクタインジェクションで受け取り、記事へのタグ付けを管理するパターンを実装した。
+複数の無効 TagId がある場合に `ValidationException` で全エラーを一度に収集するパターンも確認。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft40-multi-domain/` に以下を作成:
+
+- **`app.py`** — Article + Tag の 2 ドメインを跨ぐ `TagArticleUseCase` と FastAPI エンドポイント
+- **`test_app.py`** — 正常タグ付け・不正タグ・404・複数バリデーションエラー (7 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+**テスト結果**: 11 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP40-1: 複数リポジトリを受け取る UseCase は自然に書ける（良い設計）
+
+**分類**: 摩擦なし（設計の確認）
+
+フレームワークは UseCase 構造に制約を課さないため、
+複数のリポジトリを `__init__` で受け取るパターンが素直に実装できる。
+CLAUDE.md の「UseCase は他の UseCase を呼ばない」ルールに従い、
+各リポジトリを直接呼ぶことで依存関係がシンプルに保たれる。
+
+---
+
+### FP40-2: カスタムドメイン例外は SimpleDomainHandler 登録が必要
+
+**分類**: 軽微な摩擦（設計通り・注意喚起）
+
+`ValidationException` は `ErrorHandlerMiddleware` が自動で 422 に変換するが、
+`ArticleNotFoundException` のようなカスタムドメイン例外は
+`SimpleDomainHandler` を明示的に登録しないと 500 になる。
+登録を忘れると意図しない 500 レスポンスになるため注意が必要。
+
+```python
+# 忘れると 500 になる
+handlers = [
+    SimpleDomainHandler(ArticleNotFoundException, "article-not-found", "Not Found", 404),
+]
+app.add_middleware(ErrorHandlerMiddleware, domain_handlers=handlers)
+```
+
+**判断**: ドメイン例外の HTTP マッピングを明示的にする設計は正しい。
+`configure-auth.md` と同様に how-to ドキュメントでパターンを示す価値がある。
+
+---
+
+### FP40-3: 複数ドメイン横断バリデーションエラーを一括収集できる
+
+**分類**: 良い設計の確認
+
+`ValidationException` リストにエラーを積み上げてから raise するパターンで、
+複数の無効 TagId を一度のリクエストでまとめてクライアントに通知できる。
+FT33 で確認した `ValidationCode(StrEnum)` パターンと組み合わせると更に型安全になる。
+
+---
+
+## フレームワーク変更
+
+なし（全て設計通りの挙動）
+
+---
+
+## 関連
+
+- `nene2.use_case.UseCaseProtocol`
+- `nene2.validation.ValidationException`
+- `nene2.middleware.SimpleDomainHandler`
+- FT13 (ValidationException 実運用, v1.6.0)
+- FT21 (SimpleDomainHandler 実装, v1.8.0)
+- FT33 (ValidationCode StrEnum パターン, v1.8.3)

nene2_python-1.8.6/docs/field-trials/2026-05-field-trial-41.md

@@ -0,0 +1,126 @@
+# Field Trial 41: structlog テスト統合 — configure_for_testing() + caplog ログ相関
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.5 時点
+**テーマ**: `configure_for_testing()` + pytest `caplog` でリクエスト ID をログで追跡するパターンの実運用確認
+
+---
+
+## 概要
+
+`nene2.log.configure_for_testing()` を `conftest.py` のモジュールレベルで呼び出し、
+`RequestIdMiddleware` + `RequestLoggingMiddleware` を組み合わせたアプリのログを
+pytest の `caplog` でキャプチャ・検証するパターンを実装した。
+structlog と stdlib logging の橋渡し構造における制約も確認した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft41-log-testing/` に以下を作成:
+
+- **`conftest.py`** — モジュールレベルで `configure_for_testing()` を呼び出し
+- **`app.py`** — `RequestIdMiddleware` / `RequestLoggingMiddleware` / `ErrorHandlerMiddleware` を積んだ FastAPI アプリ。`extra_context` パラメータで静的フィールドを全ログに付加
+- **`test_app.py`** — 正常系・ヘッダー確認・caplog キャプチャ・ミドルウェアログ確認 (5 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+**テスト結果**: 9 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP41-1: configure_for_testing() は conftest.py のモジュールレベルで呼ぶ必要がある
+
+**分類**: 軽微な摩擦（設計通り・注意喚起）
+
+`configure_for_testing()` は structlog のグローバル設定を変更するため、
+テスト関数内で呼んでも機能するが、全テストに適用するには
+`conftest.py` のモジュールレベルで呼ぶことが重要。
+テスト関数内で呼ぶと、その関数のみに限定されず他のテストに副作用を与える可能性がある。
+
+```python
+# conftest.py — 正しいパターン
+from nene2.log import configure_for_testing
+configure_for_testing()
+```
+
+**判断**: ドキュメントに記載されたパターン通り。現行の `docs/how-to/run-tests.md` に
+明示的に記載することで摩擦を減らせる。
+
+---
+
+### FP41-2: caplog.records の LogRecord に request_id フィールドが直接ない
+
+**分類**: 設計上の制約（許容範囲）
+
+`RequestIdMiddleware` が `structlog.contextvars.bind_contextvars(request_id=...)` で
+バインドした値は、pytest の `caplog` が返す stdlib `LogRecord` に直接属性として
+アクセスできない（`record.request_id` が存在しない）。
+
+`ProcessorFormatter` を通すとメッセージ文字列に request_id が含まれるが、
+構造化フィールドとして直接取り出すことはできない。
+
+```python
+# NG — LogRecord に直接属性はない
+for record in caplog.records:
+    print(record.request_id)  # AttributeError
+
+# OK — メッセージ文字列に含まれる
+assert "request-id-test" not in " ".join(r.message for r in caplog.records)
+# (request_id の値は UUID であり、テスト側から事前に知ることはできない)
+```
+
+**判断**: structlog と stdlib logging の橋渡し構造による設計上の制約。
+`caplog` でのログ検証はメッセージ文字列ベースで行うのが現実的なアプローチ。
+`ProcessorFormatter` に対するテストを書きたい場合は structlog の `capture_logs()` を使う方法もある。
+
+---
+
+### FP41-3: caplog のキャプチャには configure_for_testing() が必須
+
+**分類**: 注意喚起（ドキュメントで対応済み）
+
+`configure_for_testing()` を呼ばない状態では、structlog のログは
+pytest の `caplog` にキャプチャされない。
+JSON レンダラーのまま stdout に出力されるため、
+テストで structlog ログを検証するには必ず `configure_for_testing()` を呼ぶ必要がある。
+
+**判断**: FT18 で実装した機能の使い方確認。`run-tests.md` に caplog との統合手順を追記する価値がある。
+
+---
+
+### FP41-4: structlog.contextvars でバインドした値はメッセージ文字列に含まれる
+
+**分類**: 摩擦なし（設計の確認）
+
+`structlog.contextvars.bind_contextvars(key="value")` でバインドした値は、
+`configure_for_testing()` の設定下では `record.message` にキー＝値形式で含まれる。
+テストで構造化フィールドを検証する場合はメッセージ文字列の部分一致で確認できる。
+
+```python
+structlog.contextvars.bind_contextvars(request_id="test-123")
+log.info("hello")
+# caplog.records[0].message → "hello request_id=test-123" (または類似形式)
+```
+
+**判断**: structlog + caplog の統合パターンとして文字列検索が現実的。
+
+---
+
+## フレームワーク変更
+
+なし（全て設計通りの挙動）
+
+ドキュメント追記のみ検討:
+- `docs/how-to/run-tests.md` に `configure_for_testing()` + caplog パターンを追記
+
+---
+
+## 関連
+
+- `nene2.log.configure_for_testing` (FT18, v1.8.0)
+- `nene2.middleware.RequestIdMiddleware`
+- `nene2.middleware.RequestLoggingMiddleware`
+- FT18 (configure_for_testing 実装, v1.8.0)
+- FT30 (RequestLoggingMiddleware extra_context, v1.8.2)

nene2_python-1.8.6/docs/field-trials/2026-05-field-trial-42.md

@@ -0,0 +1,137 @@
+# Field Trial 42: get_request_id() Depends + configure_problem_details() 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.5 時点
+**テーマ**: `get_request_id()` を FastAPI `Depends` で注入しレスポンスに含めるパターン、および `configure_problem_details()` のプロジェクト全体設定
+
+---
+
+## 概要
+
+`nene2.middleware.get_request_id()` を `Annotated[str, Depends(get_request_id)]` 構文で
+ハンドラーに注入し、レスポンスボディに `request_id` を含めるパターンを実装した。
+`configure_problem_details()` でプロジェクト全体の Problem Details base_url を設定し、
+カスタム例外を `SimpleDomainHandler` でマッピングする構成も確認した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft42-request-id-depends/` に以下を作成:
+
+- **`app.py`** — `get_request_id()` Depends 注入・`configure_problem_details()` 設定・`SimpleDomainHandler` でカスタム例外マッピング
+- **`test_app.py`** — 正常系・404・Problem Details base_url・request_id 相関 (9 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+**テスト結果**: 13 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP42-1: RequestIdMiddleware なしで get_request_id() を呼ぶと空文字が返る
+
+**分類**: 注意喚起（ドキュメントに記載済み）
+
+`get_request_id()` は `contextvars` を参照する。
+テスト関数から直接呼ぶ場合や `RequestIdMiddleware` を経由しない場合は `""` を返す。
+`TestClient` 経由でリクエストを送れば正しく UUID が返る。
+
+```python
+# RequestIdMiddleware なしで直接呼ぶ → ""
+from nene2.middleware import get_request_id
+assert get_request_id() == ""
+
+# TestClient 経由で呼ぶ → UUID v4
+r = client.get("/debug/request-id")
+assert len(r.json()["request_id"]) == 36
+```
+
+**判断**: ドキュメントに記載済みの動作。TestClient 経由で使うことを徹底すれば問題ない。
+
+---
+
+### FP42-2: configure_problem_details() のグローバル状態がテスト間で共有される
+
+**分類**: 軽微な摩擦（設計上の制約・テスト時の注意点）
+
+`configure_problem_details()` はモジュールレベルのグローバル変数 `_configured_base_url` を変更する。
+異なる `base_url` で複数の `create_app()` を呼ぶと最後の設定が残り、
+テスト間で state が漏れる。
+
+```python
+create_app(base_url="https://first.example.com/problems/")
+# _configured_base_url == "https://first.example.com/problems/"
+
+create_app(base_url="https://second.example.com/problems/")
+# _configured_base_url == "https://second.example.com/problems/"
+# ← first の設定は上書きされている
+```
+
+**対処**: テスト間で隔離が必要な場合、`nene2.http.problem_details._configured_base_url = None`
+で手動リセットするか、全テストで同一の base_url を使う。
+運用環境では起動時に一度だけ呼ぶ設計なので実害はない。
+
+**判断**: アプリ起動時一度だけ呼ぶ設計であり仕様通り。テスト向けに `reset_problem_details()` 関数を追加する価値があるかもしれない。
+
+---
+
+### FP42-3: SimpleDomainHandler のエラーレスポンスに request_id が自動付与されない
+
+**分類**: 設計上の制約（許容範囲・パターン提示）
+
+`ErrorHandlerMiddleware` + `SimpleDomainHandler` が生成する 404 レスポンスには
+`request_id` フィールドが自動追加されない。
+`X-Request-Id` ヘッダーは `RequestIdMiddleware` が付与するが、
+レスポンスボディへの `request_id` 付与はアプリ側で明示的に行う必要がある。
+
+エラーレスポンスに `request_id` を含めたい場合は、`problem_details_response()` を
+直接呼ぶ exception handler を登録するか、`SimpleDomainHandler` を継承して
+`request_id` を `extra` に追加するカスタム実装が必要。
+
+**判断**: `ErrorHandlerMiddleware` はドメインレイヤーに依存しない設計のため、
+`request_id` のような HTTP 横断概念を自動付与しないのは正しい。
+クライアントが `X-Request-Id` ヘッダーを参照すれば相関できる。
+
+---
+
+### FP42-4: Annotated[str, Depends(get_request_id)] 構文は問題なく動作する
+
+**分類**: 摩擦なし（良い設計の確認）
+
+Python 3.12+ 推奨の `Annotated` 構文で `get_request_id()` を注入できる。
+FastAPI の型推論も正しく動作し、`str` 型として扱われる。
+
+```python
+from typing import Annotated
+from fastapi import Depends
+from nene2.middleware import get_request_id
+
+async def handler(
+    request_id: Annotated[str, Depends(get_request_id)],
+) -> JSONResponse:
+    return JSONResponse({"request_id": request_id})
+```
+
+**判断**: FT25 で実装した `get_request_id()` は `Annotated` + `Depends` パターンと完全に互換。
+
+---
+
+## フレームワーク変更
+
+なし（全て設計通りの挙動）
+
+以下のドキュメント追記を検討:
+- `docs/how-to/` に `get_request_id()` Depends パターンの how-to ガイドを追加
+
+---
+
+## 関連
+
+- `nene2.middleware.get_request_id` (FT25, v1.8.1)
+- `nene2.middleware.RequestIdMiddleware`
+- `nene2.http.configure_problem_details` (FT19, v1.8.0)
+- `nene2.middleware.SimpleDomainHandler` (FT21, v1.8.0)
+- FT19 (configure_problem_details 実装, v1.8.0)
+- FT21 (SimpleDomainHandler 実装, v1.8.0)
+- FT25 (get_request_id 実装, v1.8.1)

{nene2_python-1.8.4 → nene2_python-1.8.6}/docs/how-to/run-tests.md

@@ -103,6 +103,27 @@ engine = create_engine(
 
 `StaticPool` guarantees all logical connections share the same underlying SQLite connection, so tables created in one operation are visible to the next.
 
+## Capturing structlog output with caplog
+
+Call `configure_for_testing()` at module level in `conftest.py` to route structlog through stdlib logging so pytest's `caplog` fixture can capture it.
+
+```python
+# conftest.py
+from nene2.log import configure_for_testing
+configure_for_testing()
+```
+
+Then assert on message strings in tests:
+
+```python
+def test_handler_logs(caplog: pytest.LogCaptureFixture) -> None:
+    client = TestClient(create_app())
+    client.post("/api/echo", json={"message": "hello"})
+    assert any("processing echo" in r.message for r in caplog.records)
+```
+
+**Note**: `caplog.records` returns stdlib `LogRecord` objects. Fields bound with `structlog.contextvars.bind_contextvars()` (such as `request_id`) are not directly accessible as `record.request_id` — they appear as part of the formatted message string instead.
+
 ## Coverage requirements
 
 | Scope | Target |

{nene2_python-1.8.4 → nene2_python-1.8.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nene2-python"
-version = "1.8.4"
+version = "1.8.6"
 description = "NENE2 Python — minimal API framework following NENE2's design philosophy"
 readme = "README.md"
 license = {text = "MIT"}