nene2-python 1.8.19__tar.gz → 1.8.21__tar.gz

{nene2_python-1.8.19 → nene2_python-1.8.21}/CHANGELOG.md

@@ -5,6 +5,32 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.21] — 2026-05-20
+
+FT75 フィールドトライアル — ミドルウェアスタック順序問題の発見と根本解決。
+
+### Added
+- `setup_middlewares(app, ...)` ユーティリティ関数を追加 (#320 #321) (FT75)
+  — 全ミドルウェアを正しい順序（RequestId 最外側・ErrorHandler 最内側）で一括登録し、
+  エラーレスポンスにも X-Request-Id とセキュリティヘッダーが確実に付与される
+- `docs/how-to/middleware-stack.md` — ミドルウェア順序の解説ガイドを追加
+- CLAUDE.md セクション 8 に推奨 `add_middleware` 順序を追記
+- Field trial report: `docs/field-trials/2026-05-field-trial-75.md` (FT75)
+
+---
+
+## [1.8.20] — 2026-05-20
+
+FT72 フィールドトライアル — DatabaseIntegrityException + ErrorHandlerMiddleware.install() 改善。
+
+### Added
+- `ErrorHandlerMiddleware.install(app)` クラスメソッドを追加 (#315) (FT72)
+  — `add_middleware` と `add_exception_handler(RequestValidationError)` を一度に設定し、
+  Pydantic の 422 バリデーションエラーも nene2 Problem Details 形式に自動統一する
+- Field trial reports: `docs/field-trials/2026-05-field-trial-70.md` 〜 `2026-05-field-trial-72.md` (FT70〜FT72)
+
+---
+
 ## [1.8.19] — 2026-05-20
 
 FT68 フィールドトライアル — SimpleDomainHandler + extra_factory 実運用検証。

{nene2_python-1.8.19 → nene2_python-1.8.21}/CLAUDE.md

@@ -233,6 +233,35 @@ AI エージェント（Claude 等）がこのコードベースを正確に理
 - `nene2.http.problem_details_response()` で RFC 9457 エラー応答
 - `nene2.http.PaginationQueryParser` でページネーション
 
+### ミドルウェアスタック順序（重要）
+
+`app.add_middleware()` は **LIFO**（後から追加したものが外側になる）。
+直感と逆なので注意 — 「外側に置きたいものを後から追加する」。
+
+**推奨 `add_middleware` 呼び出し順**（最初が最内側・最後が最外側）:
+
+```python
+# ✅ 正しい順序
+app.add_middleware(ErrorHandlerMiddleware)           # 最内側: ハンドラー例外を捕捉
+app.add_middleware(RequestLoggingMiddleware)         # ↑
+app.add_middleware(ThrottleMiddleware, ...)          # |
+app.add_middleware(RequestSizeLimitMiddleware, ...)  # |
+app.add_middleware(SecurityHeadersMiddleware)        # ↓  全レスポンスにヘッダー付与
+app.add_middleware(RequestIdMiddleware)              # 最外側: 全レスポンスに X-Request-Id 付与
+```
+
+```python
+# ❌ よくある間違い — ErrorHandler を最後（最外側）に追加
+app.add_middleware(RequestIdMiddleware)
+app.add_middleware(ErrorHandlerMiddleware)   # 最外側にすると...
+# → 500 エラーに X-Request-Id が付かない（内側のミドルウェアをバイパスするため）
+# → 500 エラーにセキュリティヘッダーが付かない
+```
+
+`ErrorHandlerMiddleware` が例外を捕捉して新しい Response を返すとき、
+それより内側のミドルウェアはバイパスされる（Starlette の `BaseHTTPMiddleware` の仕様）。
+`RequestIdMiddleware` と `SecurityHeadersMiddleware` は必ず **ErrorHandler より外側** に置くこと。
+
 ### REST 規約
 - リソース名は複数形: `/notes`, `/tags`
 - ID はパスパラメータ: `/notes/{note_id}`

{nene2_python-1.8.19 → nene2_python-1.8.21}/PKG-INFO

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

@@ -0,0 +1,58 @@
+# FT69: PaginationQueryParser + PaginationResponse 実運用検証
+
+**日付**: 2026-05-20  
+**テーマ**: ページネーション機能 (`PaginationQueryParser` + `PaginationResponse`) の実運用確認  
+**バージョン**: v1.8.19  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft69-pagination/`
+
+---
+
+## 概要
+
+`nene2.http.PaginationQueryParser` を FastAPI の `Depends()` で使い、
+`PaginationResponse` でレスポンスを組み立てるパターンを検証した。
+dataclass アイテムの自動シリアライズも確認。
+
+---
+
+## 実装内容
+
+- `PaginationQueryParser` を `Annotated[..., Depends()]` で受け取り
+- `pagination.limit` / `pagination.offset` でスライス
+- `PaginationResponse(items, limit, offset, total)` で標準レスポンス
+- `total=None` 時に `total` フィールドが省略されることを確認
+
+---
+
+## テスト結果
+
+**8/8 passed**
+
+| テスト | 結果 |
+|---|---|
+| `test_default_pagination_returns_first_20` | PASSED |
+| `test_custom_limit_and_offset` | PASSED |
+| `test_limit_too_large_returns_422` | PASSED |
+| `test_limit_zero_returns_422` | PASSED |
+| `test_negative_offset_returns_422` | PASSED |
+| `test_no_total_omits_total_field` | PASSED |
+| `test_last_page_returns_remaining_items` | PASSED |
+| `test_dataclass_items_serialized_to_dict` | PASSED |
+
+---
+
+## Friction Points
+
+なし。`PaginationQueryParser` + `PaginationResponse` はすべて直感的に動作した。
+
+**特筆点**:
+- `limit=0` や `limit>100` は FastAPI の Query バリデーションが自動で 422 を返す
+- `PaginationResponse.to_dict()` が dataclass インスタンスを自動でシリアライズするのが便利
+- `total=None` 時に `total` フィールドが省略されるため、カーソルページネーションにも対応可能
+
+---
+
+## 結論
+
+`PaginationQueryParser` + `PaginationResponse` は実運用で問題なく使用できる。
+FastAPI の Depends と自然に連携し、デフォルト値 (limit=20, max=100) も適切。

nene2_python-1.8.21/docs/field-trials/2026-05-field-trial-70.md

@@ -0,0 +1,67 @@
+# FT70: 複数ドメイン連携 実運用検証
+
+**日付**: 2026-05-20  
+**テーマ**: 複数ドメイン連携（Post + Comment ネストリソース API）の実運用確認  
+**バージョン**: v1.8.19  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft70-multi-domain/`
+
+---
+
+## 概要
+
+Post ドメインと Comment ドメインを組み合わせたネストリソース API を実装し、
+複数のフレームワーク機能を同時に使用した際の統合動作を検証した。
+
+---
+
+## 実装内容
+
+- `GET /posts` — `PaginationQueryParser` + `PaginationResponse` でページネーション
+- `POST /posts` — `SqlAlchemyTransactionManager.transactional()` でインサート
+- `GET /posts/{post_id}` — 存在しない場合 404 (Problem Details)
+- `GET /posts/{post_id}/comments` — 親リソース存在チェック付きページネーション
+- `POST /posts/{post_id}/comments` — 親リソース存在チェック付きインサート
+- `RequestIdMiddleware` + `ErrorHandlerMiddleware` をスタック
+- `StaticPool` を使ったインメモリ SQLite（接続共有）
+- `dataclass(frozen=True, slots=True)` を Post / Comment の値オブジェクトに使用
+
+---
+
+## テスト結果
+
+**10/10 passed**
+
+| テスト | 結果 |
+|---|---|
+| `test_list_posts_returns_paginated` | PASSED |
+| `test_get_post_returns_200` | PASSED |
+| `test_get_nonexistent_post_returns_404` | PASSED |
+| `test_create_post_returns_201` | PASSED |
+| `test_list_comments_for_post` | PASSED |
+| `test_list_comments_for_nonexistent_post_returns_404` | PASSED |
+| `test_create_comment_returns_201` | PASSED |
+| `test_create_comment_for_nonexistent_post_returns_404` | PASSED |
+| `test_request_id_header_present` | PASSED |
+| `test_comment_count_increases_after_create` | PASSED |
+
+---
+
+## Friction Points
+
+なし。複数ドメインを組み合わせた際もすべてのフレームワーク機能が正常に動作した。
+
+**特筆点**:
+- `StaticPool` は FT67 で習得済みのため、インメモリ SQLite の設定は迷わず実施できた
+- `PaginationQueryParser` + `PaginationResponse` のネストリソース（`/posts/{id}/comments`）への適用も自然
+- `SqlAlchemyTransactionManager.transactional()` で Post と Comment の両インサートが問題なく動作
+- `RequestIdMiddleware` は `ErrorHandlerMiddleware` と共存可能（ミドルウェアスタック順序の制約なし）
+- `problem_details_response()` の 404 応答は親リソース (`post-not-found`) に統一可能
+
+---
+
+## 結論
+
+nene2-python の主要機能（Pagination, Transaction, RequestId, ErrorHandler, Problem Details）を
+複数ドメイン連携シナリオで組み合わせても一切の摩擦がなかった。
+FT57〜FT69 で修正・ドキュメント化された機能がすべて期待通り動作し、
+フレームワークの統合品質が高いことを確認できた。

nene2_python-1.8.21/docs/field-trials/2026-05-field-trial-71.md

@@ -0,0 +1,83 @@
+# FT71: 完全レイヤードアーキテクチャ実運用検証
+
+**日付**: 2026-05-20  
+**テーマ**: UseCaseProtocol + Repository パターンによる完全レイヤードアーキテクチャ検証  
+**バージョン**: v1.8.19  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft71-layered-arch/`
+
+---
+
+## 概要
+
+NENE2 の核心設計パターン（HTTP Handler → UseCase → Repository の完全分離）を
+Todo ドメインで実装し、`UseCaseProtocol`・`ValidationException`・`InMemoryRepository` 注入が
+実運用で問題なく動作することを確認した。
+
+---
+
+## 実装内容
+
+### ドメイン層（HTTP・DB 非依存）
+- `Todo(id, title, done)` — `dataclass(frozen=True, slots=True)` 値オブジェクト
+- Input/Output DTO 群 — `CreateTodoInput/Output`, `GetTodoInput/Output`, `ListTodosInput/Output`, `CompleteTodoInput/Output`
+- `TodoRepositoryInterface` — `abc.ABC` 抽象インターフェース
+- UseCase 群: `CreateTodoUseCase`, `GetTodoUseCase`, `ListTodosUseCase`, `CompleteTodoUseCase`
+
+### インフラ層
+- `InMemoryTodoRepository` — テスト用インメモリ実装
+- `SqlAlchemyTodoRepository` — 本番用 SQLAlchemy 実装
+
+### HTTP 層（thin handler）
+- `create_app(repository=None)` — `repository` が None の場合 SQLAlchemy を使用、注入された場合はそのまま使用
+- Handler は parse → use-case → response の 3 ステップのみ
+
+---
+
+## テスト結果
+
+**15/15 passed**
+
+| テスト | 結果 | 種別 |
+|---|---|---|
+| `test_create_todo_use_case_returns_new_todo` | PASSED | UseCase 単体 |
+| `test_create_todo_use_case_raises_validation_error_on_blank_title` | PASSED | UseCase 単体 |
+| `test_get_todo_use_case_returns_existing_todo` | PASSED | UseCase 単体 |
+| `test_list_todos_use_case_returns_all_items` | PASSED | UseCase 単体 |
+| `test_complete_todo_use_case_marks_done` | PASSED | UseCase 単体 |
+| `test_list_todos_returns_paginated` | PASSED | HTTP 統合 |
+| `test_get_todo_returns_200` | PASSED | HTTP 統合 |
+| `test_get_nonexistent_todo_returns_404` | PASSED | HTTP 統合 |
+| `test_create_todo_returns_201` | PASSED | HTTP 統合 |
+| `test_create_todo_with_blank_title_returns_422` | PASSED | HTTP 統合 |
+| `test_complete_todo_marks_done` | PASSED | HTTP 統合 |
+| `test_complete_nonexistent_todo_returns_404` | PASSED | HTTP 統合 |
+| `test_list_todos_pagination_offset` | PASSED | HTTP 統合 |
+| `test_request_id_header_present` | PASSED | HTTP 統合 |
+| `test_in_memory_repo_used_for_unit_tests_without_db` | PASSED | DI 注入 |
+
+---
+
+## Friction Points
+
+なし。
+
+**特筆点**:
+- `ValidationException` を UseCase 内（ドメイン層）で raise しても、
+  `ErrorHandlerMiddleware` が自動で 422 Problem Details に変換する。
+  ドメイン層が HTTP を知らなくてよい。
+- `create_app(repository=InMemoryTodoRepository(...))` の DI 注入パターンで
+  HTTP テストも DB なしで実行できる。5 つの UseCase 単体テストは完全に DB 非依存。
+- `UseCaseProtocol[I, O]` の静的型チェックは `isinstance()` ではなく型注釈で行う。
+  `def _assert_protocols() -> None: _: UseCaseProtocol[...] = SomeUseCase(...)` のパターンで
+  mypy が protocol 適合を静的に保証する。
+- `InMemoryTodoRepository` の `mark_done()` 実装で `done=True` に更新するため
+  リスト全体を再構築するパターン（frozen dataclass なので in-place 変更不可）が自然に強制される。
+
+---
+
+## 結論
+
+`UseCaseProtocol` + `Repository Interface` + `InMemoryRepository` の三点セットで
+NENE2 の完全レイヤードアーキテクチャが機能する。
+UseCase 単体テスト（DB なし）と HTTP 統合テスト（SQLAlchemy 経由）を
+同一 `create_app()` ファクトリで切り替えられる DI パターンが特に有用。

nene2_python-1.8.21/docs/field-trials/2026-05-field-trial-72.md

@@ -0,0 +1,72 @@
+# FT72: DatabaseIntegrityException + write() 戻り値パターン実運用検証
+
+**日付**: 2026-05-20  
+**テーマ**: ユニーク制約違反 (409) と UPDATE/DELETE の rowcount=0 (404) パターン検証  
+**バージョン**: v1.8.19  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft72-db-integrity/`
+
+---
+
+## 概要
+
+ユーザー登録 API でユニーク制約違反 → `DatabaseIntegrityException` → 409 のマッピングと、
+`write()` 戻り値 0 を使った UPDATE/DELETE の「対象なし → 404」パターンを実運用で検証した。
+あわせて `request_validation_error_handler` による Pydantic 422 → nene2 形式変換も確認した。
+
+---
+
+## 実装内容
+
+- `users` テーブル（`username UNIQUE`, `email UNIQUE`）
+- `POST /users` — INSERT、重複時 `DatabaseIntegrityException` → 409
+- `GET /users/{id}` — 存在しない場合 404
+- `PUT /users/{id}/email` — UPDATE、`write()` 戻り値 0 → 404
+- `DELETE /users/{id}` — DELETE、`write()` 戻り値 0 → 404、成功時 204
+- `SimpleDomainHandler(DatabaseIntegrityException, "user-conflict", "Conflict", 409)` で自動変換
+- `app.add_exception_handler(RequestValidationError, request_validation_error_handler)` で Pydantic 422 形式統一
+
+---
+
+## テスト結果
+
+**11/11 passed**
+
+| テスト | 結果 |
+|---|---|
+| `test_register_user_returns_201` | PASSED |
+| `test_register_duplicate_username_returns_409` | PASSED |
+| `test_register_duplicate_email_returns_409` | PASSED |
+| `test_get_user_returns_200` | PASSED |
+| `test_get_nonexistent_user_returns_404` | PASSED |
+| `test_update_email_returns_200` | PASSED |
+| `test_update_email_for_nonexistent_user_returns_404` | PASSED |
+| `test_update_to_duplicate_email_returns_409` | PASSED |
+| `test_delete_user_returns_204` | PASSED |
+| `test_delete_nonexistent_user_returns_404` | PASSED |
+| `test_register_invalid_body_returns_422_nene2_format` | PASSED |
+
+---
+
+## Friction Points
+
+なし。
+
+**特筆点**:
+- `SimpleDomainHandler(DatabaseIntegrityException, ...)` で SQLAlchemy の IntegrityError を
+  透過的に 409 に変換できる。ハンドラー側のコードに `try/except` が不要。
+- `write()` の戻り値セマンティクス（UPDATE/DELETE は rowcount、INSERT は lastrowid）により、
+  `if affected == 0: return 404` パターンが自然に書ける。
+- `JSONResponse(None, status_code=204)` が 204 No Content として正しく動作する。
+- `request_validation_error_handler` を `add_exception_handler(RequestValidationError, ...)` で
+  登録することで、Pydantic の 422 バリデーションエラーも nene2 の `validation-failed`
+  Problem Details 形式に統一できる。`ErrorHandlerMiddleware` だけではこのケースをカバーできないため、
+  完全な 422 形式統一には両方の登録が必要。
+
+---
+
+## 結論
+
+`DatabaseIntegrityException` は `SimpleDomainHandler` で宣言的に 409 にマッピングでき、
+`write()` の 0 戻り値で UPDATE/DELETE の「対象なし → 404」も慣用的に書ける。
+Pydantic バリデーション 422 の形式統一には `request_validation_error_handler` の追加登録が必要な点は
+覚えておく価値がある。

nene2_python-1.8.21/docs/field-trials/2026-05-field-trial-73.md

@@ -0,0 +1,69 @@
+# FT73: PaginationQueryParser.parse() 静的メソッド実運用検証
+
+**日付**: 2026-05-20  
+**テーマ**: `PaginationQueryParser.parse(Request)` レガシーパターンと `ErrorHandlerMiddleware.install()` の連携確認  
+**バージョン**: v1.8.20  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft73-pagination-parse/`
+
+---
+
+## 概要
+
+`PaginationQueryParser.parse(request)` 静的メソッド（`Depends()` を使わないパターン）を検証した。
+カスタム `default_limit` / `max_limit` の動作と、
+v1.8.20 で追加した `ErrorHandlerMiddleware.install()` との連携も確認した。
+
+---
+
+## 実装内容
+
+- `GET /items` — `PaginationQueryParser.parse(request)` でデフォルト (limit=20, max=100)
+- `GET /items/custom` — `parse(request, default_limit=5, max_limit=10)` でカスタム値
+- `ErrorHandlerMiddleware.install(app)` を使用（v1.8.20 の新機能）
+- `ValidationException` による 422 を nene2 Problem Details 形式で返す
+
+---
+
+## テスト結果
+
+**11/11 passed**
+
+| テスト | 結果 |
+|---|---|
+| `test_default_pagination_returns_20_items` | PASSED |
+| `test_custom_limit_and_offset` | PASSED |
+| `test_limit_too_large_returns_422` | PASSED |
+| `test_limit_zero_returns_422` | PASSED |
+| `test_negative_offset_returns_422` | PASSED |
+| `test_non_integer_limit_returns_422` | PASSED |
+| `test_non_integer_offset_returns_422` | PASSED |
+| `test_custom_default_limit_applied` | PASSED |
+| `test_custom_max_limit_enforced` | PASSED |
+| `test_custom_max_limit_at_boundary` | PASSED |
+| `test_last_page_returns_remaining_items` | PASSED |
+
+---
+
+## Friction Points
+
+なし。
+
+**特筆点**:
+- `PaginationQueryParser.parse()` は `ValidationException` を raise するため、
+  `ErrorHandlerMiddleware.install(app)` と組み合わせると
+  非整数値・範囲外の入力が自動的に 422 nene2 Problem Details で返る。
+- `parse()` が返す `PaginationQuery` (named dataclass) は `limit` / `offset` を保持し、
+  `Depends()` パターンの `PaginationQueryParser` インスタンスと同じインターフェースで使える。
+- `default_limit` / `max_limit` のカスタマイズが `parse()` の引数で完結するため、
+  ルートごとに異なるページネーション制限を設定しやすい。
+- `ErrorHandlerMiddleware.install(app)` が v1.8.20 で正式追加され、
+  `ValidationException` の 422 フォーマット統一が一行で完了するようになった。
+
+---
+
+## 結論
+
+`PaginationQueryParser.parse()` は `Depends()` パターンが使えないシナリオ
+（例: ミドルウェアや `WebSocket` ハンドラー内）で有効な代替手段。
+`default_limit` / `max_limit` のカスタマイズと `ValidationException` の自動 422 変換が
+`ErrorHandlerMiddleware.install()` との組み合わせで自然に機能する。

nene2_python-1.8.21/docs/field-trials/2026-05-field-trial-74.md

@@ -0,0 +1,76 @@
+# FT74: カスタム HealthCheckProtocol 実装の実運用検証
+
+**日付**: 2026-05-20  
+**テーマ**: ユーザー定義 `HealthCheckProtocol` / `AsyncHealthCheckProtocol` 実装と `CompositeHealthCheck` の連携  
+**バージョン**: v1.8.20  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft74-custom-health/`
+
+---
+
+## 概要
+
+ユーザーが `HealthCheckProtocol` を実装する実際のシナリオ（メモリ・DB・外部サービス）を
+`CompositeHealthCheck` / `AsyncCompositeHealthCheck` に組み合わせて動作を検証した。
+
+---
+
+## 実装内容
+
+### カスタム同期ヘルスチェック
+- `AlwaysOkCheck` — 常に ok を返すベースライン
+- `ToggleableCheck` — テストで on/off できるトグル可能なチェック
+- `MemoryCheck` — 閾値ベースのメモリ使用量チェック（psutil なしでシミュレート）
+
+### カスタム非同期ヘルスチェック
+- `AsyncAlwaysOkCheck` — 常に ok を返す非同期版
+- `AsyncToggleableCheck` — 非同期版トグルチェック
+
+### エンドポイント
+- `GET /health` — `CompositeHealthCheck` (同期)
+- `GET /health/async` — `AsyncCompositeHealthCheck` (非同期)
+- `create_app(db_healthy, cache_healthy, memory_usage_pct)` でテストシナリオを切り替え
+
+---
+
+## テスト結果
+
+**13/13 passed**
+
+| テスト | 結果 | 種別 |
+|---|---|---|
+| `test_always_ok_check_returns_ok` | PASSED | 単体 |
+| `test_toggleable_check_returns_error_when_unhealthy` | PASSED | 単体 |
+| `test_memory_check_ok_under_threshold` | PASSED | 単体 |
+| `test_memory_check_error_over_threshold` | PASSED | 単体 |
+| `test_composite_ok_when_all_checks_pass` | PASSED | 単体 |
+| `test_composite_error_when_any_check_fails` | PASSED | 単体 |
+| `test_health_status_http_code_200_when_ok` | PASSED | 単体 |
+| `test_health_status_http_code_503_when_error` | PASSED | 単体 |
+| `test_sync_health_endpoint_returns_200_when_all_ok` | PASSED | HTTP 統合 |
+| `test_sync_health_endpoint_returns_503_when_db_down` | PASSED | HTTP 統合 |
+| `test_sync_health_endpoint_returns_503_when_memory_high` | PASSED | HTTP 統合 |
+| `test_async_health_endpoint_returns_200_when_all_ok` | PASSED | HTTP 統合 |
+| `test_async_health_endpoint_returns_503_when_cache_down` | PASSED | HTTP 統合 |
+
+---
+
+## Friction Points
+
+なし。
+
+**特筆点**:
+- `HealthCheckProtocol` / `AsyncHealthCheckProtocol` はどちらも `@runtime_checkable Protocol` なので、
+  特定の基底クラスを継承せずとも `check()` メソッドを実装するだけで準拠できる。
+- `CompositeHealthCheck` は各チェックの `checks` dict をフラットマージするため、
+  複数チェックが同一キーを持つと後のチェックが上書きする。キーの命名が重要。
+- `HealthStatus.http_status_code` は 200 / 503 を自動で返すため、
+  HTTP ハンドラーで `status_code=status.http_status_code` とするだけで正しいステータスコードになる。
+- `create_app(db_healthy=False)` の DI パターンで HTTP テストにおける「障害シミュレーション」が簡潔に書ける。
+
+---
+
+## 結論
+
+`HealthCheckProtocol` の実装は `check() -> HealthStatus` を持つだけで完了する。
+`CompositeHealthCheck` がフラットマージすることを把握した上で、
+各チェックのキー命名を一意にすれば、複数チェックの組み合わせは完全に直感的に動作する。

nene2_python-1.8.21/docs/field-trials/2026-05-field-trial-75.md

@@ -0,0 +1,128 @@
+# FT75: ミドルウェアスタック順序依存性の実運用検証
+
+**日付**: 2026-05-20  
+**テーマ**: Starlette LIFO ミドルウェア順序の落とし穴 — エラーレスポンスにヘッダーが付かない問題  
+**バージョン**: v1.8.20  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft75-middleware-order/`
+
+---
+
+## 概要
+
+nene2 が提供する 6 つのミドルウェアを組み合わせた際の順序依存バグを検証した。
+「ErrorHandler を最外側に」という直感が **間違い** であることを実際のテストで実証し、
+全レスポンスに X-Request-Id とセキュリティヘッダーを付与するための正しい順序を確認した。
+
+---
+
+## 発見した問題
+
+### Starlette BaseHTTPMiddleware の動作原理
+
+`app.add_middleware(X)` は **LIFO**（後から追加したものが外側になる）で積まれる。
+
+```python
+app.add_middleware(A)  # 内側
+app.add_middleware(B)  # 外側
+# スタック: B(A(Router))
+# リクエスト: B → A → Router
+# レスポンス: Router → A → B
+```
+
+### 落とし穴: ErrorHandler を最外側にすると何が起きるか
+
+```python
+# 「直感」による書き方
+app.add_middleware(RequestIdMiddleware)       # 内側
+app.add_middleware(SecurityHeadersMiddleware) # 内側
+app.add_middleware(ErrorHandlerMiddleware)    # 最外側（最後に追加）
+
+# スタック: ErrorHandler(SecurityHeaders(RequestId(Router)))
+```
+
+ハンドラーが例外を raise すると:
+1. `ErrorHandlerMiddleware.dispatch` が例外を捕捉
+2. `problem_details_response(...)` で **新しい Response を直接 return**
+3. この Response は内側の `SecurityHeaders` も `RequestId` も **通過しない**
+4. 結果: **500 エラーに X-Request-Id もセキュリティヘッダーも付かない**
+
+### 正しい順序
+
+ErrorHandler を **最内側** に置き、RequestId と SecurityHeaders を **外側** に置く。
+
+```python
+# 正しい書き方（最初に add するものが最内側）
+app.add_middleware(ErrorHandlerMiddleware)           # 最内側
+app.add_middleware(RequestLoggingMiddleware)
+app.add_middleware(ThrottleMiddleware, ...)
+app.add_middleware(RequestSizeLimitMiddleware, ...)
+app.add_middleware(SecurityHeadersMiddleware)
+app.add_middleware(RequestIdMiddleware)              # 最外側
+
+# スタック: RequestId(SecurityHeaders(SizeLimit(Throttle(RequestLogging(ErrorHandler(Router))))))
+# 全レスポンス（エラー含む）が SecurityHeaders と RequestId を通過する ✓
+```
+
+---
+
+## テスト結果
+
+**10/10 passed**
+
+| テスト | 結果 | 観察内容 |
+|---|---|---|
+| `test_correct_order_500_is_problem_details` | PASSED | ErrorHandler は内側でも 500 を捕捉できる |
+| `test_correct_order_500_has_request_id` | PASSED | RequestId が外側 → 500 にも付く |
+| `test_correct_order_500_has_security_headers` | PASSED | SecurityHeaders が外側 → 500 にも付く |
+| `test_correct_order_413_is_problem_details` | PASSED | SizeLimitMiddleware は内部で直接 problem_details_response を返す |
+| `test_correct_order_413_has_request_id` | PASSED | 413 にも X-Request-Id が付く |
+| `test_correct_order_413_has_security_headers` | PASSED | 413 にもセキュリティヘッダーが付く |
+| `test_naive_order_500_missing_request_id` | PASSED | 直感的順序だと 500 に X-Request-Id が**付かない**ことを実証 |
+| `test_naive_order_500_missing_security_headers` | PASSED | 直感的順序だと 500 にセキュリティヘッダーが**付かない**ことを実証 |
+
+---
+
+## Friction Points
+
+### 🔴 重大: ミドルウェア推奨順序がドキュメント化されていない
+
+`add_middleware` の呼び出し順序について nene2 のドキュメントに推奨順序が存在しない。
+Starlette の LIFO 動作は非直感的であり、「ErrorHandler が最外側にあるべき」という誤解を招きやすい。
+
+実際の影響:
+- **ErrorHandler を最外側に置く（最後に add する）と** 500 エラーに X-Request-Id が付かない
+- **Security audit で「エラーレスポンスにセキュリティヘッダーがない」と指摘される**
+- 本番環境で気づかずに運用してしまう可能性が高い
+
+**推奨順序（コメント付き）をドキュメントに追加すべき。**
+
+---
+
+## 使用感（主観評価）
+
+**直感性: ★★☆☆☆**  
+LIFO の仕組みを知っていても、「外側に置きたいものを後から add する」という逆転発想は
+毎回確認しないと間違える。Express.js でも同じ罠があり、FastAPI/Starlette ユーザーが
+最も頻繁にハマる問題のひとつ。
+
+**実害の深刻さ: ★★★★★**  
+単に動かない（すぐ気づく）ではなく、**動くが一部の非機能要件が欠落する**パターン。
+Security headers がエラーページだけ欠落していても CI は通るし、
+X-Request-Id がエラーレスポンスにないことはログ追跡するまで気づかない。
+
+**修正のしやすさ: ★★★★★**  
+順序を正しくするだけなので、原因がわかれば修正は 1 分。
+問題は「原因に気づく」のが遅いこと。
+
+**フレームワーク側で改善できること**:  
+CLAUDE.md や how-to ガイドに推奨スタック順序を明記するだけで解決できる。
+ミドルウェアを `ErrorHandlerMiddleware.install()` のように一括登録する
+`setup_middlewares(app)` ユーティリティがあると事故を防げる。
+
+---
+
+## 結論
+
+ミドルウェア順序のバグは **動作するが静かに壊れている** 類の問題で、
+実際の本番事故に直結しやすい。正しい順序（ErrorHandler 最内側・RequestId 最外側）を
+nene2 の公式ドキュメントと CLAUDE.md に追記することを強く推奨する。