ホーム

ルーティング

from fastapi import APIRouter,HTTPException,from starlette import statusの使い方

目的

本ノウハウ集の目的は、FastAPI を用いた Web API 開発におけるルーティング設計の実践的な知識とノウハウを体系的に解説することです。特に、APIRouter によるルーティングの分割・整理、HTTPException を用いたエラーハンドリング、status による明示的なステータスコード管理など、実際の開発現場で役立つテクニックや設計上のポイントを丁寧に紹介します。 対象読者は、Python の基本的な構文やコンピュータサイエンスの基礎知識を持つ若手エンジニアや学生です。Web アプリケーション開発の初学者から、より実践的な API 設計・運用を目指す方まで、幅広く活用できる内容を目指します。

FastAPI ルーティングの全体像

FastAPI のルーティングは、HTTP リクエスト（GET、POST、PUT、DELETE など）を受け取り、適切な処理関数（エンドポイント）に振り分ける仕組みです。ルーティングを適切に設計することで、API の可読性・保守性・拡張性が大きく向上します。 FastAPI では、@app.get()や@app.post()などのデコレータを使ってエンドポイントを定義します。さらに、APIRouter を活用することで、ルート定義を機能ごとに分割し、プロジェクト構成を整理できます。これにより、大規模なアプリケーションでもルーティングの管理が容易になり、チーム開発にも適した構造が実現できます。 また、ルーティング設計では、エラー発生時の適切なレスポンスや、HTTP ステータスコードの明示的な管理も重要です。FastAPI は HTTPException や status モジュールを使うことで、これらを直感的かつ安全に実装できます。 本ノウハウ集では、これらの基本から応用まで、FastAPI のルーティング設計に必要な実践的知識を体系的に解説していきます。

APIRouter の基礎

APIRouter とは何か、導入の意義

APIRouter は、FastAPI のルーティングを組織化・管理するための強力なツールです。FastAPI の公式ドキュメントでは「パス操作をグループ化するために使用されるクラス」と定義されています。 APIRouter の主な導入意義は以下です。 コードの整理性向上: ルーティング定義をファイルやモジュール単位で分割できます 責務の明確な分離: 機能ごとに役割を明確に分けられるため、マイクロサービス的な設計が可能です モジュール性の向上: ルーターをインポートするだけで、まとめて複数のルーティングを適用できます DRY 原則の実現: 共通の prefix（接頭辞）や tags を一括で設定できるため、コードの重複を避けられます 拡張性の確保: アプリケーションの成長に合わせて、ルーターの追加・変更が容易になります 大規模なアプリケーションを開発する場合、すべてのエンドポイント（パス操作）を 1 つのファイルに記述すると、コードが長大になり可読性や保守性が低下します。APIRouter を活用することで、これらの問題を解決し、より持続可能なコード構造を実現できます。

基本的な使い方と構文

まず、次のようなディレクトリ構造を作ります。

myapp/
├── main.py
└── routers/
    ├── __init__.py
    ├── users.py
    ├── items.py
    └── products.py

次に main.py に次を書き込みます。

from fastapi import FastAPI

app = FastAPI()

# メインアプリのルートを定義
@app.get("/")
async def root():
    return {"message": "Hello "}

コンソールに下記を打ち込み、指定されたアドレスを開いてください。 デフォルトはhttp://127.0.0.1:8000/

 uvicorn main:app --reload

@app.get(“/aaa/aaa_bbb/”)や@app.get(“/bbb/bbb_bbb/”)などでブラウザからアクセスできるエンドポイントアドレスを増やせますが、一つのファイルにまとめきれなくなります。 そこで、エンドボイントを記載するコードをファイル分割できるようにします。

# users.py
from fastapi import APIRouter

router = APIRouter(prefix="/user", tags=["user"])

@router.get("/")
async def get_users():
    return {"users": "all"}



# item.py
from fastapi import APIRouter

router = APIRouter(prefix="/item", tags=["item"])


@router.get("/")
async def get_item():
    return {"items": "all"}

main.py で include_router を使ってそれぞれの APIRouter インスタンスを取り込めます。

# main.py
from fastapi import FastAPI
from routers import items,users
app = FastAPI()

app.include_router(items.router)
app.include_router(users.router)
# メインアプリのルートを定義
@app.get("/")
async def root():
    return {"message": "Hello "}

http://127.0.0.1:8000/docs にアクセスして確認してみてください。

目次