【要約】FastAPI でやりがちなレイヤードアーキテクチャ違反と修正パターン [Zenn_Python] | Summary by TechDistill
> Source: Zenn_Python
Execute Primary Source
// Problem
開発者がFastAPIでアプリケーションを構築する際、各レイヤーの責務が曖昧になり、コードの結合度が高まる問題に直面する。これにより、変更の影響範囲が予測不能になる。
- ・RouterがDBのトランザクション制御を行い、ビジネスロジックの変更がHTTP層に波及する。
- ・Repositoryがコミットを完結させ、複数操作を一つのトランザクションにまとめることが困難になる。
- ・Serviceが直接SQL操作を行い、ユニットテストの作成やクエリ最適化が困難になる。
- ・ServiceがHTTP固有の例外を投げ、CLI等の非HTTP環境での再利用性を損なう。
// Approach
各レイヤーが「何の都合を引き受けるか」という観点で責務を再定義し、依存関係を整理するアプローチを採用する。
- ・RouterはHTTPプロトコル固有の処理（ルーティング、ステータスコード選択）に専念させる。
- ・Serviceはドメインルールとトランザクション境界（commit/rollback）を管理する。
- ・RepositoryはDB操作（SQL、ORMマッピング）に特化し、
flushまでを担当する。 - ・Serviceはドメイン例外を投げ、HTTPへの変換はException Handlerに委ねる。
// Result
適切な責務分離により、開発チームは以下の成果を得られる。
- ・ビジネスロジックの変更が他層に影響しない、疎結合な設計が実現する。
- ・Service層のテストにおいて、DB操作のモック化が容易になり、テスト容易性が向上する。
- ・トランザクション管理がService層に集約され、データの整合性維持が容易になる。
- ・ロジックの再利用性が高まり、バッチ処理など非HTTP環境への転用が容易になる。
Senior Engineer Insight
> 本記事の指摘は、中規模以上のシステムにおいて極めて実践的である。特にトランザクション境界をServiceに集約し、Repositoryを
flushに留める設計は、データ整合性を守る上で不可欠だ。実装コストは増すが、長期的な保守コストとテストの容易性を考えれば、投資対効果は極めて高い。規律なき開発は技術負債に直結するため、チーム全体での設計指針の徹底が必要である。