문서가격블로그
문의하기
로그인무료로 가입하기
Back to Tech Articles

GinとFastAPIにおけるミドルウェア実行の解明

7월 25, 2025
# Misc

Daniel Hayes

Full-Stack Engineer · Leapcell

이 게시물은 English, 한국어 및 Deutsch에서도 볼 수 있습니다.
Cover of "GinとFastAPIにおけるミドルウェア実行の解明"

はじめに

バックエンド開発の複雑な世界では、堅牢でスケーラブルなWebサービスを構築することは、ミドルウェアの戦略的な使用に大きく依存します。これらの強力なコンポーネントは、リクエストの前処理、レスポンスの後処理、認証、ロギング、エラー管理などを柔軟に行う方法を提供し、コアビジネスロジックを煩雑にすることなく実現します。しかし、これらのミドルウェアが実行される正確な順序と、それらが基本的なリクエスト-レスポンスサイクルとどのように相互作用するかを把握することは、開発者にとって大きなハードルとなり、微妙なバグや非効率的なアーキテクチャにつながる可能性があります。このパイプラインを理解することは、単なる学術的な演習ではありません。デバッグ、パフォーマンスの最適化、アプリケーションのセキュリティと信頼性の確保にとって極めて重要です。この記事では、2つの人気のあるWebフレームワーク、GoのGinとPythonのFastAPIにおけるミドルウェア実行のメカニズムを深く掘り下げ、それらの操作シーケンスと、それぞれのスタックを通じたリクエストとレスポンスの旅を明らかにします。

ミドルウェアとリクエスト/レスポンスフローの詳細

GinとFastAPIの具体例を分析する前に、ミドルウェアとHTTPリクエスト-レスポンスサイクルの基盤となるコアコンセプトについて共通の理解を確立しましょう。

主要な用語

  • ミドルウェア: Webサーバーとアプリケーションの間に位置し、受信リクエストと送信レスポンスを処理するソフトウェアコンポーネント。各ミドルウェアは通常、特定のタスクを実行し、次にチェーン内の次のミドルウェアまたは最終的なルートハンドラに制御を渡します。
  • リクエスト: クライアント（例：Webブラウザ、モバイルアプリ）がサーバーに送信するHTTPメッセージで、リソースを要求したりアクションの実行を求めたりします。メソッド（GET、POSTなど）、URL、ヘッダー、および可能性のあるボディを含みます。
  • レスポンス: サーバーがリクエストに応答してクライアントに送信するHTTPメッセージです。ステータスコード、ヘッダー、およびボディ（例：HTML、JSON）を含みます。
  • コンテキスト: 単一のHTTPリクエスト-レスポンスサイクルのすべての情報を含むオブジェクト。これには通常、リクエスト自体、レスポンスを書き込むためのメソッド、およびミドルウェア間でデータを保存および取得するメカニズムが含まれます。
  • ルートハンドラ（またはエンドポイント関数）: リクエストが定義されたルートに一致したときに実行される特定の関数またはメソッド。通常、コアビジネスロジックはここに配置されます。
  • 責任の連鎖パターン: ミドルウェアはしばしばこのデザインパターンを実装し、リクエストはハンドラのチェーンに沿って順次渡され、各ハンドラは特定のロジックを実行します。

Ginミドルウェアの実行とリクエスト/レスポンスフロー

Ginは、Goで書かれた高性能HTTP Webフレームワークであり、強力で直感的なミドルウェアシステムを活用しています。

Ginミドルウェアの原則

Ginでは、ミドルウェア関数はgin.Contextオブジェクトを受け取るhttp.HandlerFunc互換の関数です。通常は次のようになります。

func MyMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        // リクエストが進む前の前処理ロジック
        log.Println("Before request:", c.Request.URL.Path)

        // チェーン内の次のミドルウェア/ハンドラに制御を渡す
        c.Next()

        // ハンドラからリクエストが戻った後の後処理ロジック
        log.Println("After request:", c.Request.URL.Path, "Status:", c.Writer.Status())
    }
}

c.Next()の呼び出しは非常に重要です。これにより、現在のミドルウェアはチェーン内の次のハンドラに制御を譲ることができます。c.Next()が呼び出されない場合、リクエストは現在のミドルウェアで停止し、後続のミドルウェアやルートハンドラは実行されません。

実行順序の例

次のGinアプリケーションを考えてみましょう。

package main

import (
	"log"
	"net/http"
	"time"

	"github.com/gin-gonic/gin"
)

// LoggerMiddleware はリクエストの開始と終了時刻をログに記録します
func LoggerMiddleware() gin.HandlerFunc {
	return func(c *gin.Context) {
		startTime := time.Now()
		log.Printf("LoggerMiddleware: Starting request for %s %s", c.Request.Method, c.Request.URL.Path)

		c.Next() // チェーン内の次のハンドラに制御を渡す

		duration := time.Since(startTime)
		log.Printf("LoggerMiddleware: Finished request for %s %s in %v. Status: %d",
			c.Request.Method, c.Request.URL.Path, duration, c.Writer.Status())
	}
}

// AuthenticationMiddleware は有効なヘッダーをチェックします
func AuthenticationMiddleware() gin.HandlerFunc {
	return func(c *gin.Context) {
		log.Printf("AuthenticationMiddleware: Checking authentication for %s", c.Request.URL.Path)
		token := c.GetHeader("Authorization")
		if token == "" {
			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"message": "Unauthorized"})
			log.Printf("AuthenticationMiddleware: Unauthorized access to %s", c.Request.URL.Path)
			return // 重要: 権限のないリクエストはここで処理を停止します
		}
		// 実際のアプリでは、トークンを検証します
		c.Set("user_id", "some_user_id_from_token") // コンテキストにデータを保存
		log.Printf("AuthenticationMiddleware: Authorized access to %s", c.Request.URL.Path)
		c.Next()
	}
}

func main() {

outer := gin.Default()

	// グローバルミドルウェアをすべてのルートに適用
	router.Use(LoggerMiddleware())

	// 特定のミドルウェアを持つルートグループ
	authorized := router.Group("/admin")
	authorized.Use(AuthenticationMiddleware()) // /admin グループに固有のミドルウェア
	{
		authorized.GET("/dashboard", func(c *gin.Context) {
			userID := c.MustGet("user_id").(string) // コンテキストからデータを取得
			log.Printf("DashboardHandler: User %s accessing dashboard", userID)
			c.JSON(http.StatusOK, gin.H{"message": "Welcome to the admin dashboard", "user": userID})
		})
	}


outer.GET("/public", func(c *gin.Context) {
		log.Printf("PublicHandler: Accessing public endpoint")
		c.JSON(http.StatusOK, gin.H{"message": "This is a public endpoint"})
	})

	log.Println("Starting Gin server on :8080")
	if err := router.Run(":8080"); err != nil {
		log.Fatalf("Gin server failed to start: %v", err)
	}
}

/admin/dashboardの実行フロー:

  1. リクエストが到着します。
  2. LoggerMiddleware: log.Printf("LoggerMiddleware: Starting request...")が実行されます。
  3. LoggerMiddlewareでc.Next()が呼び出されます。 制御は次のグローバルまたはグループ固有のミドルウェアに渡されます。
  4. AuthenticationMiddleware: log.Printf("AuthenticationMiddleware: Checking authentication...")が実行されます。
  5. 認証されている場合: log.Printf("AuthenticationMiddleware: Authorized...")が実行されます。c.Next()が呼び出されます。制御はルートハンドラに渡されます。
  6. authorized.GET("/dashboard", ...) (ルートハンドラ): log.Printf("DashboardHandler: User %s accessing dashboard")が実行されます。c.JSONがレスポンスを書き込みます。
  7. ルートハンドラが戻ります。 制御はc.Next()呼び出しのスタックを上に流れます。
  8. AuthenticationMiddleware (後処理): この例ではc.Next()の後にロジックが置かれていないため、明示的な後処理はありませんが、ここで発生します。
  9. AuthenticationMiddlewareが戻ります。
  10. LoggerMiddleware (後処理): log.Printf("LoggerMiddleware: Finished request...")が実行され、/admin/dashboardの最終ステータスを監視します。
  11. レスポンスがクライアントに送信されます。

/publicの実行フロー:

  1. リクエストが到着します。
  2. LoggerMiddleware: log.Printf("LoggerMiddleware: Starting request...")が実行されます。
  3. LoggerMiddlewareでc.Next()が呼び出されます。(/publicのルートハンドラへの制御が渡されます。グループ固有のミドルウェアはありません。)
  4. router.GET("/public", ...) (ルートハンドラ): log.Printf("PublicHandler: Accessing public endpoint")が実行されます。c.JSONがレスポンスを書き込みます。
  5. ルートハンドラが戻ります。 制御は上に流れます。
  6. LoggerMiddleware (後処理): log.Printf("LoggerMiddleware: Finished request...")が実行されます。
  7. レスポンスがクライアントに送信されます。

Ginの重要なポイント: ミドルウェアは互いにラップします。c.Next()が呼び出されると、実行フローは一時停止し、スタックの奥に進み、後続のミドルウェア/ハンドラを実行し、次に現在のミドルウェアの後処理ロジックを完了するために戻ります。c.AbortWithStatusJSONは、チェーンをショートサーキットし、ハンドラのさらなる実行を防ぐために不可欠です。

FastAPIミドルウェアの実行とリクエスト/レスポンスフロー

FastAPIは、Python 3.7+に基づいたAPI構築のためのモダンで高速なWebフレームワークであり、標準的なPython型ヒントを使用しており、堅牢なミドルウェアシステムも備えています。

FastAPIミドルウェアの原則

FastAPIミドルウェア関数は非同期であり、通常@app.middleware("http")デコレータを使用して定義されます。これらは、requestオブジェクトとcall_next関数を受け取ります。

from fastapi import Request, Response
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.types import ASGIApp

class MyMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        # リクエストが進む前の前処理ロジック
        print(f"MyMiddleware: Before request for {request.url.path}")

        response = await call_next(request) # 次のミドルウェア/ハンドラに制御を渡す

        # ハンドラからリクエストが戻った後の後処理ロジック
        print(f"MyMiddleware: After request for {request.url.path}, Status: {response.status_code}")
        return response

await call_next(request)は、Ginのc.Next()に相当するFastAPIの機能です。これは非同期に次のミドルウェアまたはルートハンドラを呼び出します。次に、下流のコンポーネントからのレスポンスが返され、現在のミドルウェアが独自のレスポンスを返す前に後処理を実行できるようになります。

実行順序の例

FastAPIアプリケーションで例示してみましょう。

from fastapi import FastAPI, Request, Response, status
from starlette.middleware.base import BaseHTTPMiddleware
import time
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

app = FastAPI()

# @app.middleware を使用したグローバルミドルウェア
@app.middleware("http")
async def logger_middleware(request: Request, call_next):
    start_time = time.time()
    logger.info(f"LoggerMiddleware: Request started for {request.method} {request.url.path}")

    response = await call_next(request) # 制御を委譲

    process_time = time.time() - start_time
    response.headers["X-Process-Time"] = str(process_time)
    logger.info(f"LoggerMiddleware: Request finished for {request.method} {request.url.path} in {process_time:.4f}s. Status: {response.status_code}")
    return response

# 認証用のカスタムミドルウェアクラス
class AuthenticationMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        logger.info(f"AuthenticationMiddleware: Checking authentication for {request.url.path}")
        if request.url.path.startswith("/admin"):
            auth_header = request.headers.get("Authorization")
            if not auth_header or auth_header != "Bearer mysecrettoken":
                logger.warning(f"AuthenticationMiddleware: Unauthorized access to {request.url.path}")
                return Response("Unauthorized", status_code=status.HTTP_401_UNAUTHORIZED)
            request.state.user_id = "admin_user_from_token" # stateにデータを保存
            logger.info(f"AuthenticationMiddleware: Authorized access to {request.url.path}")
        
        response = await call_next(request) # 制御を委譲
        return response

app.add_middleware(AuthenticationMiddleware) # ミドルウェアを明示的に追加

@app.get("/public")
async def read_public():
    logger.info("PublicEndpoint: Accessing public endpoint")
    return {"message": "This is a public endpoint"}

@app.get("/admin/dashboard")
async def read_admin_dashboard(request: Request):
    user_id = getattr(request.state, "user_id", "anonymous")
    logger.info(f"AdminDashboardEndpoint: User {user_id} accessing dashboard")
    return {"message": "Welcome to the admin dashboard", "user": user_id}

# 実行するには： uvicorn main:app --reload

/admin/dashboardの実行フロー:

  1. リクエストが到着します。
  2. logger_middleware: logger.info("LoggerMiddleware: Request started...")が実行されます。
  3. logger_middlewareでawait call_next(request)が呼び出されます。 制御は次のミドルウェアに渡されます。
  4. AuthenticationMiddleware.dispatch: logger.info("AuthenticationMiddleware: Checking authentication...")が実行されます。
  5. 認証されている場合: logger.info("AuthenticationMiddleware: Authorized...")が実行されます。await call_next(request)が呼び出されます。制御はルートハンドラに渡されます。
  6. read_admin_dashboard (ルートハンドラ): logger.info("AdminDashboardEndpoint: User ... accessing dashboard")が実行されます。FastAPIがJSONResponseに変換する辞書が返されます。
  7. ルートハンドラが戻ります。 制御はスタックを上に流れます。
  8. AuthenticationMiddleware.dispatch (後処理): この例ではawait call_next(request)の後に明示的な後処理はありません。その後、return responseがレスポンスをさらに上に送信します。
  9. AuthenticationMiddleware.dispatchが戻ります。
  10. logger_middleware (後処理): logger.info("LoggerMiddleware: Request finished...")が実行され、X-Process-Timeヘッダーがレスポンスに追加されます。return responseがレスポンスをクライアントに送信します。
  11. レスポンスがクライアントに送信されます。

/admin/dashboardの実行フロー (認証なし):

  1. ステップ1-4は同じです。
  2. AuthenticationMiddleware.dispatch: Authorizationヘッダーがないことを検出します。logger.warning("AuthenticationMiddleware: Unauthorized access...")が実行されます。
  3. return Response(...): 認証されていないレスポンスが即座に返されます。await call_next(request)は呼び出されません。ルートハンドラおよび後続のミドルウェアはスキップされます。
  4. 制御は即座にlogger_middlewareに戻ります。
  5. logger_middleware (後処理): logger.info("LoggerMiddleware: Request finished...")が実行され、認証ミドルウェアからの401レスポンスを処理します。
  6. レスポンスがクライアントに送信されます。

FastAPIの重要なポイント: Ginと同様に、ミドルウェアは互いにラップします。await call_next(request)は現在のミドルウェアを一時停止し、下流のコンポーネントを実行し、次に返されたresponseオブジェクトで実行を再開します。早期にResponseオブジェクトを返すこと（例：権限のないリクエストの場合）は、チェーンを効果的にショートサーキットします。FastAPIでは、request.stateを使用してミドルウェアとルートハンドラ間でデータを渡すこともできます。

結論

GinやFastAPIのようなフレームワークにおけるミドルウェアの正確な実行順序を理解することは、予測可能で管理可能で安全なWebアプリケーションを構築するための基本です。両方のフレームワークは「ラッパー」または「オニオン」モデルを採用しており、ミドルウェアはリクエストを前処理し、制御をルートハンドラに深く渡し、次に制御が戻るにつれてレスポンスを後処理します。制御の委譲（Ginのc.Next()、FastAPIのawait call_next(request)）とチェーンのショートサーキット（Ginのc.AbortWithStatusJSON()、FastAPIの早期return Response()）の概念は、このフローをマスターするために不可欠です。これらのメカニズムを内部化することにより、開発者はロギング、認証、エラー処理のようなクロスサービングコンサーンを効率的に実装し、堅牢でスケーラブルなバックエンドアーキテクチャを確保できます。ミドルウェアは、すべてのリクエストとレスポンスの旅をオーケストレーションし、APIインタラクションの性質そのものを形作ります。

Share this article

HackerNews

More Posts from Leapcell

Popular Posts