DocsPricingBlog
Contact Us
Log inSign up for FREE
Back to Tech Articles

Gin 및 Chi 라우터용 모듈식 재사용 가능한 미들웨어 구축

Oct 09, 2025
# Misc

Grace Collins

Solutions Engineer · Leapcell

This post is also available in English, 日本語, and Deutsch
Cover of "Gin 및 Chi 라우터용 모듈식 재사용 가능한 미들웨어 구축"

소개

Go로 강력하고 확장 가능한 웹 애플리케이션을 구축하는 세계에서 미들웨어는 횡단 관심사를 처리하는 데 중요한 역할을 합니다. 사용자 인증, 요청 로깅, 입력 유효성 검사 또는 콘텐츠 유형 협상과 같은 시나리오를 상상해 보세요. 이러한 기능을 모든 핸들러 함수 내에 직접 구현하면 상당한 코드 중복, 복잡한 논리 및 유지 관리의 어려움으로 이어질 수 있습니다. 바로 여기서 미들웨어의 힘이 빛을 발합니다. 이러한 공통 기능을 별도의 교체 가능한 구성 요소로 추상화함으로써 더 깨끗하고 모듈화되며 유지 관리가 용이한 코드베이스를 달성할 수 있습니다. 이 기사에서는 Go에서 가장 인기 있는 두 웹 프레임워크인 Gin 및 Chi에 대한 조합 가능하고 재사용 가능한 미들웨어를 효과적으로 작성하여 개발자가 우아하고 효율적인 API를 구축할 수 있도록 하는 방법에 중점을 둡니다.

미들웨어 이해: 웹 애플리케이션의 빌딩 블록

Gin 및 Chi의 세부 사항에 들어가기 전에 미들웨어가 무엇인지, 그리고 관련된 핵심 개념에 대한 기본적인 이해를 확립해 봅시다.

미들웨어란 무엇입니까?

본질적으로 미들웨어는 메인 핸들러 함수를 실행하기 전이나 후에 HTTP 요청 및 응답을 처리하는 함수 또는 함수 집합입니다. HTTP 요청이 통과하는 "파이프라인"을 형성하여 각 미들웨어가 특정 작업을 수행하고, 요청 또는 응답을 수정하고, 파이프라인의 다음 요소로 제어를 전달하여 최종 핸들러에 도달할 수 있습니다.

핵심 개념

  • 요청/응답 가로채기: 미들웨어는 HTTP 요청의 흐름을 가로채어 사전 처리(예: 인증) 또는 사후 처리(예: 응답 상태 로깅)를 가능하게 합니다.
  • 체인/파이프라인: 여러 미들웨어 함수를 연결하여 시퀀스를 형성할 수 있습니다. 각 미들웨어는 요청을 다음 미들웨어로 전달할지 또는 조기에 요청을 종료할지(예: 인증 실패 시) 결정할 수 있습니다.
  • 컨텍스트: 미들웨어는 종종 HTTP 컨텍스트를 활용하여 미들웨어 체인 및 최종 핸들러와 공유할 수 있는 데이터를 저장하고 검색합니다. 이를 통해 전역 변수를 피하고 스레드 안전한 데이터 공유를 촉진할 수 있습니다.
  • 재사용성: 잘 설계된 미들웨어는 수정 없이 다른 라우트 또는 다른 애플리케이션에 적용할 수 있을 만큼 일반적이어야 합니다.
  • 조합성: 여러 개의 작고 단일 목적의 미들웨어를 더 복잡한 기능으로 결합하는 능력.

Gin 및 Chi 미들웨어 서명

Gin과 Chi는 자체 내부 API를 가지고 있지만 미들웨어를 정의하는 데 매우 유사한 패턴을 제공합니다.

Gin 미들웨어 서명:

Gin에서 미들웨어 함수는 일반적으로 func(*gin.Context) 서명을 갖습니다. gin.Context 객체에는 http.ResponseWriter 및 *http.Request와 Next(), Abort(), Set()과 같은 요청 수명 주기 관리를 위한 메서드가 포함되어 있습니다.

// 예제 Gin 미들웨어: 로거
func LoggerMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        start := time.Now()
        c.Next() // 다음 미들웨어/핸들러 처리
        duration := time.Since(start)
        log.Printf("Request - Method: %s, Path: %s, Status: %d, Duration: %v",
            c.Request.Method, c.Request.URL.Path, c.Writer.Status(), duration)
    }
}

Chi 미들웨어 서명:

Chi 미들웨어는 표준 net/http 인터페이스에 더 가깝게 따릅니다. Chi의 미들웨어 함수는 일반적으로 func(http.Handler) http.Handler 서명을 갖습니다. 이 "데코레이터" 패턴은 매우 강력하여 미들웨어가 http.Handler를 래핑하고 새 핸들러를 반환할 수 있습니다.

// 예제 Chi 미들웨어: RequestID
func RequestIDMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        reqID := r.Header.Get("X-Request-ID")
        if reqID == "" {
            reqID = uuid.New().String()
        }
        ctx := context.WithValue(r.Context(), RequestIDKey, reqID)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// 컨텍스트를 위한 키 정의
type ContextKey string
const RequestIDKey ContextKey = "requestID"

여기서 차이점에 주목하십시오. Gin의 Next()는 명시적으로 다음 핸들러로 이동하고, Chi의 next.ServeHTTP()는 래핑된 핸들러를 호출합니다. 둘 다 요청 처리를 계속하는 동일한 목표를 달성합니다.

재사용 가능한 미들웨어 작성

재사용성의 핵심은 미들웨어를 가능한 한 일반적이고 구성 가능하게 만드는 것입니다.

매개변수화된 미들웨어

값을 하드코딩하는 대신 초기화 시 미들웨어를 구성할 수 있도록 합니다.

// Gin: 속도 제한 미들웨어
func RateLimitMiddleware(maxRequests int, window time.Duration) gin.HandlerFunc {
    // 실제 시나리오에서는 토큰 버킷 또는 누수 버킷과 같은 더 정교한 속도 제한 알고리즘을 사용하고
    // 잠재적으로 분산 저장소를 사용합니다.
    // 단순화를 위해 IP별로 기본 인메모리 카운터를 사용합니다.
    ipCounters := make(map[string]int)
    lastResets := make(map[string]time.Time)
    mu := sync.Mutex{}

    return func(c *gin.Context) {
        ip := c.ClientIP()

        mu.Lock()
        defer mu.Unlock()

        if _, ok := lastResets[ip]; !ok || time.Since(lastResets[ip]) > window {
            ipCounters[ip] = 0
            lastResets[ip] = time.Now()
        }

        if ipCounters[ip] >= maxRequests {
            c.AbortWithStatusJSON(http.StatusTooManyRequests, gin.H{"error": "Too many requests"})
            return
        }

        ipCounters[ip]++
        c.Next()
    }
}

// Chi: 인증 미들웨어
func AuthMiddleware(secretKey string) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            token := r.Header.Get("Authorization")
            if token == "" || !isValidToken(token, secretKey) { // isValidToken은 실제 유효성 검사 함수여야 합니다.
                http.Error(w, "Unauthorized", http.StatusUnauthorized)
                return
            }
            // 토큰이 유효한 경우 컨텍스트에 사용자 정보를 저장할 수 있습니다.
            ctx := context.WithValue(r.Context(), UserIDKey, "some_user_id") // UserIDKey가 정의되었다고 가정
            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}

// 시연을 위한 더미 isValidToken
func isValidToken(token, secretKey string) bool {
    // 실제 앱에서는 JWT, API 키 등을 유효성 검사합니다.
    return token == "Bearer mysecrettoken" && secretKey == "supersecret"
}

옵션 패턴이 있는 미들웨어

여러 개의 선택적 매개변수를 허용하는 미들웨어의 경우 "옵션 패턴"(함수형 옵션)은 구성을 제공하는 깔끔한 방법입니다.

// Gin: 옵션이 있는 LogLevel 미들웨어
type LogLevel int

const (
    LogInfo LogLevel = iota
    LogError
)

type LoggerOptions struct {
    LogLevel LogLevel
    IncludeHeaders bool
}

type LoggerOption func(*LoggerOptions)

func WithLogLevel(level LogLevel) LoggerOption {
    return func(o *LoggerOptions) {
        o.LogLevel = level
    }
}

func WithHeaders() LoggerOption {
    return func(o *LoggerOptions) {
        o.IncludeHeaders = true
    }
}

func ConfigurableLoggerMiddleware(opts ...LoggerOption) gin.HandlerFunc {
    options := LoggerOptions{
        LogLevel: LogInfo,
        IncludeHeaders: false,
    }
    for _, opt := range opts {
        opt(&options)
    }

    return func(c *gin.Context) {
        start := time.Now()
        c.Next()
        duration := time.Since(start)

        if options.LogLevel == LogInfo {
            log.Printf("Request Info - Method: %s, Path: %s, Status: %d, Duration: %v",
                c.Request.Method, c.Request.URL.Path, c.Writer.Status(), duration)
            if options.IncludeHeaders {
                log.Println("Headers:", c.Request.Header)
            }
        } else if options.LogLevel == LogError && c.Writer.Status() >= 400 {
            log.Printf("Request Error - Method: %s, Path: %s, Status: %d, Message: %s",
                c.Request.Method, c.Request.URL.Path, c.Writer.Status(), c.Errors.ByType(gin.ErrorTypePrivate).String())
        }
    }
}

// 사용법:
// r.Use(ConfigurableLoggerMiddleware(WithLogLevel(LogError)))
// r.Use(ConfigurableLoggerMiddleware(WithLogLevel(LogInfo), WithHeaders()))

조합 가능한 미들웨어 구축

조합성은 종종 미들웨어 함수가 구조화되는 방식과 자연스럽게 함께 제공됩니다. 각 미들웨어를 단일 책임에 집중시킴으로써 더 복잡한 처리 파이프라인을 만들기 위해 쉽게 결합할 수 있습니다.

// Gin 예제: 여러 미들웨어 결합
func setupGinRouter() *gin.Engine {
    r := gin.New()

    // 모든 라우트에 적용되는 전역 미들웨어
    r.Use(gin.Logger()) // 내장 Gin 로거
    r.Use(gin.Recovery()) // 내장 Gin 복구
    r.Use(RateLimitMiddleware(10, time.Minute)) // 사용자 정의 속도 제한

    // 라우트 그룹에 특정 미들웨어 적용
    adminGroup := r.Group("/admin")
    adminGroup.Use(AuthMiddleware("supersecret")) // 사용자 정의 인증
    {
        adminGroup.GET("/dashboard", func(c *gin.Context) {
            c.JSON(http.StatusOK, gin.H{"message": "Welcome Admin!"})
        })
    }

    r.GET("/public", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{"message": "Public access"})
    })

    return r
}

// Chi 예제: 여러 미들웨어 결합
func setupChiRouter() http.Handler {
    r := chi.NewRouter()

    // 모든 라우트에 적용되는 전역 미들웨어
    r.Use(middleware.Logger) // Chi 내장 로거
    r.Use(middleware.Recoverer) // Chi 내장 복구
    r.Use(RequestIDMiddleware) // 사용자 정의 요청 ID

    // 라우트 그룹에 특정 미들웨어 적용
    r.Group(func(adminRouter chi.Router) {
        adminRouter.Use(AuthMiddleware("supersecret")) // 사용자 정의 인증
        adminRouter.Get("/admin/dashboard", func(w http.ResponseWriter, r *http.Request) {
            w.Write([]byte("Welcome Admin!"))
        })
    })

    r.Get("/public", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Public access"))
    })

    return r
}

두 예제 모두 Use() 메서드(Gin) 또는 r.Use() 및 r.Group()(Chi)가 쉬운 조합을 가능하게 한다는 점에 주목하십시오. 원하는 순서대로 미들웨어 함수를 나열하기만 하면 됩니다. 순서는 매우 중요하며, 각 미들웨어는 요청을 순차적으로 처리하므로 중요합니다.

실제 적용: JWT 인증 미들웨어

두 프레임워크 모두에 대해 더 완전하고 재사용 가능한 JWTAuthMiddleware를 보여드리겠습니다.

Gin JWT 미들웨어:

package middleware

import (
    "net/http"
    "strings"
    "time"

    "github.com/dgrijalva/jwt-go"
    "github.com/gin-gonic/gin"
)

// claims는 JWT 클레임 구조를 나타냅니다.
type Claims struct {
    UserID string `json:"user_id"`
    jwt.StandardClaims
}

// JWTAuthMiddleware는 JWT 인증을 위한 Gin 미들웨어를 생성합니다.
func JWTAuthMiddleware(secretKey string) gin.HandlerFunc {
    return func(c *gin.Context) {
        // Authorization 헤더에서 토큰 추출
        authHeader := c.GetHeader("Authorization")
        if authHeader == "" {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Authorization header required"})
            return
        }

        tokenParts := strings.Split(authHeader, " ")
        if len(tokenParts) != 2 || tokenParts[0] != "Bearer" {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Invalid Authorization header format"})
            return
        }

        tokenString := tokenParts[1]

        // 토큰 구문 분석 및 유효성 검사
        token, err := jwt.ParseWithClaims(tokenString, &Claims{}, func(token *jwt.Token) (interface{}, error) {
            return []byte(secretKey), nil
        })

        if err != nil {
            if err == jwt.ErrSignatureInvalid {
                c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Invalid token signature"})
                return
            }
            if ve, ok := err.(*jwt.ValidationError); ok {
                if ve.Errors&jwt.ValidationErrorExpired != 0 {
                    c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Token expired"})
                    return
                }
            }
            c.AbortWithStatusJSON(http.StatusForbidden, gin.H{"error": "Could not parse token"})
            return
        }

        if !token.Valid {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Invalid token"})
            return
        }

        claims, ok := token.Claims.(*Claims)
        if !ok {
            c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": "Failed to get token claims"})
            return
        }

        // 후속 핸들러를 위해 사용자 ID를 컨텍스트에 저장
        c.Set("userID", claims.UserID)
        c.Next()
    }
}

Chi JWT 미들웨어:

package middleware

import (
    "context"
    "net/http"
    "strings"
    "time"

    "github.com/dgrijalva/jwt-go"
)

// claims는 JWT 클레임 구조를 나타냅니다.
type Claims struct {
    UserID string `json:"user_id"`
    jwt.StandardClaims
}

// UserID를 저장하기 위한 ContextKey 정의
type ContextKey string
const UserIDKey ContextKey = "userID"

// JWTAuthMiddleware는 JWT 인증을 위한 Chi 미들웨어를 생성합니다.
func JWTAuthMiddleware(secretKey string) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            authHeader := r.Header.Get("Authorization")
            if authHeader == "" {
                http.Error(w, "Authorization header required", http.StatusUnauthorized)
                return
            }

            tokenParts := strings.Split(authHeader, " ")
            if len(tokenParts) != 2 || tokenParts[0] != "Bearer" {
                http.Error(w, "Invalid Authorization header format", http.StatusUnauthorized)
                return
            }

            tokenString := tokenParts[1]

            token, err := jwt.ParseWithClaims(tokenString, &Claims{}, func(token *jwt.Token) (interface{}, error) {
                return []byte(secretKey), nil
            })

            if err != nil {
                if err == jwt.ErrSignatureInvalid {
                    http.Error(w, "Invalid token signature", http.StatusUnauthorized)
                    return
                }
                if ve, ok := err.(*jwt.ValidationError); ok {
                    if ve.Errors&jwt.ValidationErrorExpired != 0 {
                        http.Error(w, "Token expired", http.StatusUnauthorized)
                        return
                    }
                }
                http.Error(w, "Could not parse token", http.StatusForbidden)
                return
            }

            if !token.Valid {
                http.Error(w, "Invalid token", http.StatusUnauthorized)
                return
            }

            claims, ok := token.Claims.(*Claims)
            if !ok {
                http.Error(w, "Failed to get token claims", http.StatusInternalServerError)
                return
            }

            // 후속 핸들러를 위해 사용자 ID를 컨텍스트에 저장
            ctx := context.WithValue(r.Context(), UserIDKey, claims.UserID)
            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}

이 예제들은 논리가 얼마나 유사한지, 하지만 프레임워크의 컨텍스트와의 상호 작용과 다음 핸들러로 제어를 전달하는 방식이 어떻게 다른지 보여줍니다. 둘 다 조합 가능하고 재사용 가능한 인증을 달성하는 데 동등하게 강력합니다.

결론

효과적인 미들웨어를 작성하는 것은 확장 가능하고 유지 관리 가능한 Go 웹 애플리케이션을 구축하는 데 기본입니다. 핵심 개념을 이해하고 Gin 및 Chi와 같은 프레임워크에서 제공하는 패턴을 활용함으로써 개발자는 횡단 관심사를 우아하게 해결하는 모듈식, 재사용 가능하고 조합 가능한 미들웨어를 만들 수 있으며, 이는 더 깨끗한 코드와 더 효율적인 개발 워크플로우로 이어집니다. 미들웨어를 활용하여 API 개발을 간소화하고 강력한 서비스를 구축하십시오.

Share this article

HackerNews

More Posts from Leapcell

Popular Posts