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

Gin과 Validator v10으로 견고한 요청 유효성 검사하기

Sep 16, 2025
# Misc

James Reed

Infrastructure Engineer · Leapcell

This post is also available in English, 日本語, and Deutsch
Cover of "Gin과 Validator v10으로 견고한 요청 유효성 검사하기"

소개: 안정적인 API의 보이지 않는 수호자

현대 웹 개발 분야에서 API는 애플리케이션이 상호 작용하고 데이터를 교환하는 중요한 관문 역할을 합니다. API의 건강성과 신뢰성은 단순히 속도나 기능만으로 판단되는 것이 아니라, 기본적으로 처리하는 데이터의 무결성에 의해 좌우됩니다. 일치하지 않거나 잘못된 형식의 입력 데이터는 잘못된 데이터베이스 항목, 예상치 못한 애플리케이션 동작, 보안 취약성에 이르기까지 광범위한 오류의 연쇄 반응을 초래할 수 있습니다. 따라서 견고한 요청 데이터 유효성 검사는 단순한 모범 사례가 아니라, 탄력적이고 신뢰할 수 있는 백엔드 서비스를 구축하는 데 필수적인 구성 요소입니다.

Gin과 같은 프레임워크는 라우팅 및 HTTP 요청 처리에 탁월한 도구를 제공하지만, 일반적으로 즉시 사용할 수 있는 포괄적인 데이터 유효성 검사 기능을 제공하지는 않습니다. 바로 이 지점에서 전용 유효성 검사 라이브러리가 빛을 발하며, 비즈니스 로직에 도달하기 전에 수신 데이터가 미리 정의된 규칙을 준수하도록 보장하기 위해 원활하게 통합됩니다. 이 글에서는 Gin과 널리 사용되는 go‐playground/validator v10 라이브러리를 Go 언어에서 조합하여 정교하고 유연한 요청 데이터 유효성 검사 로직을 구축하는 방법을 자세히 살펴보고, 이를 통해 애플리케이션을 보호하고 API 품질을 향상시킬 것입니다.

핵심 개념 및 구현 세부 정보

실질적인 구현에 들어가기 전에 논의의 중심이 되는 몇 가지 핵심 개념을 간략하게 명확히 해 봅시다.

  • Gin: Go 언어로 작성된 고성능 HTTP 웹 프레임워크입니다. 속도와 미니멀한 디자인으로 알려져 있으며 웹 애플리케이션 및 API 구축에 필수적인 기능을 제공합니다.
  • Struct Tag: Go의 구조체 필드에 첨부되는 메타데이터로, 일반적으로 리플렉션에 사용됩니다. validator의 맥락에서 구조체 태그는 각 필드에 대한 유효성 검사 규칙을 정의합니다.
  • go-playground/validator (v10): 필드 간 유효성 검사, 사용자 정의 유효성 검사기, 국제화와 같은 기능을 지원하는 Go 구조체 및 필드 유효성 검사 라이브러리입니다. 매우 구성 가능하고 효율적입니다.
  • Custom Validation (사용자 정의 유효성 검사): validator 라이브러리가 제공하는 기본 규칙을 넘어서는 자체 유효성 검사 규칙을 정의하고 등록하는 기능입니다. 이는 도메인별 비즈니스 로직에 중요합니다.
  • Cross-Field Validation (필드 간 유효성 검사): 동일한 구조 내의 여러 필드 값에 따라 달라지는 유효성 검사 규칙입니다. 예를 들어, confirm_password 필드가 password 필드와 일치하는지 확인하는 것입니다.

환경 설정

먼저 Gin과 Validator v10이 설치되었는지 확인하세요:

go get github.com/gin-gonic/gin
go get github.com/go-playground/validator/v10

기본 요청 유효성 검사

간단한 사용자 등록 데이터 유효성 검사 예시부터 시작하겠습니다.

package main

import (
	"log"
	"net/http"

	"github.com/gin-gonic/gin"
	"github.com/go-playground/validator/v10"
)

// UserRegisterRequest는 사용자 등록 데이터의 구조를 정의합니다
type UserRegisterRequest struct {
	Username string `json:"username" binding:"required,min=3,max=30"`
	Email    string `json:"email" binding:"required,email"`
	Password string `json:"password" binding:"required,min=6"`
}

func main() {
	r := gin.Default()

	// 사용자 등록을 위한 핸들러 등록
	r.POST("/register", func(c *gin.Context) {
		var req UserRegisterRequest
		if err := c.ShouldBindJSON(&req); err != nil {
			// 유효성 검사 오류 처리
			var validationErrors validator.ValidationErrors
			if ok := c.Error.IsType(&validationErrors); ok {
				errorResponse := make(map[string]string)
				for _, fieldErr := range validationErrors {
					errorResponse[fieldErr.Field()] = fieldErr.Tag()
				}
				c.JSON(http.StatusBadRequest, gin.H{"error": "Validation failed", "details": errorResponse})
			} else {
				// 다른 바인딩 오류 처리 (예: 잘못된 JSON 형식)
				c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			}
			return
		}

		// 유효성 검사가 통과되면 요청을 처리합니다
		c.JSON(http.StatusOK, gin.H{"message": "User registered successfully", "user": req.Username})
	})

	log.Fatal(r.Run(":8080")) // 8080 포트에서 수신 및 서비스
}

이 예시에서:

  • JSON 언마샬링을 위한 json 태그와 유효성 검사를 위한 binding 태그가 있는 UserRegisterRequest 구조체를 정의했습니다.
  • binding:"required,min=3,max=30"는 Username 필드가 필수이며, 최소 3자, 최대 30자여야 함을 의미합니다.
  • binding:"required,email"는 Email이 필수이고 유효한 이메일 형식을 갖도록 보장합니다.
  • c.ShouldBindJSON(&req)는 요청 본문을 구조체에 바인딩하고 binding 태그에 정의된 유효성 검사를 자동으로 실행합니다.
  • 오류 처리는 유효성 검사 오류 (validator.ValidationErrors)와 다른 바인딩 오류를 구분합니다.

사용자 정의 유효성 검사 규칙 통합

때로는 기본 유효성 검사기만으로는 충분하지 않을 수 있습니다. 예를 들어, 사용자 이름이 "admin" 또는 "root"일 수 없다는 요구 사항이 있다고 가정해 보겠습니다. 사용자 정의 유효성 검사로 이를 달성할 수 있습니다.

package main

import (
	"log"
	"net/http"
	"reflect"

	"github.com/gin-gonic/gin"
	"github.com/go-playground/validator/v10"
)

// 전역 유효성 검사기 인스턴스 생성
var validate *validator.Validate

// isNotReserved는 문자열이 예약된 사용자 이름이 아닌지 확인합니다
func isNotReserved(fl validator.FieldLevel) bool {
	reservedUsernames := map[string]bool{
		"admin": true,
		"root":  true,
	}
	return !reservedUsernames[fl.Field().String()]
}

// 사용자 정의 유효성 검사가 포함된 UserRegisterRequest
type UserRegisterRequest struct {
	Username string `json:"username" binding:"required,min=3,max=30,notreserved"` // 'notreserved' 추가됨
	Email    string `json:"email" binding:"required,email"`
	Password string `json:"password" binding:"required,min=6"`
}

func main() {
	r := gin.Default()

	// 유효성 검사기 초기화 및 사용자 정의 유효성 검사 등록
	validate = validator.New()
	validate.RegisterValidation(`notreserved`, isNotReserved)

	// 사용자가 우리의 전역 유효성 검사기 인스턴스를 사용하도록 사용자 정의 타입 변환기
	if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
		v.RegisterValidation("notreserved", isNotReserved)
	}


	r.POST("/register", func(c *gin.Context) {
		var req UserRegisterRequest
		if err := c.ShouldBindJSON(&req); err != nil {
			var validationErrors validator.ValidationErrors
			if ok := c.Error.IsType(&validationErrors); ok {
				errorResponse := make(map[string]string)
				for _, fieldErr := range validationErrors {
					errorResponse[fieldErr.Field()] = fieldErr.Tag()
				}
				c.JSON(http.StatusBadRequest, gin.H{"error": "Validation failed", "details": errorResponse})
			} else {
				c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			}
			return
		}

		c.JSON(http.StatusOK, gin.H{"message": "User registered successfully", "user": req.Username})
	})

	log.Fatal(r.Run(":8080")) 
}

여기서는 notreserved를 사용자 정의 유효성 검사 규칙으로 도입했습니다.

  • isNotReserved는 validator.FieldLevel을 받아 필드 값이 유효하면 true, 그렇지 않으면 false를 반환하는 함수입니다.
  • validate.RegisterValidation("notreserved", isNotReserved)는 이 함수를 유효성 검사기 인스턴스에 등록합니다.
  • binding 엔진이 사용자 정의 유효성 검사기를 사용하도록 보장하기 위해 유형을 확인하고 사용자 정의 규칙을 등록합니다. 사용자 정의 유효성 검사기를 Gin과 깔끔하게 통합하는 더 강력한 방법은 Gin의 기본 유효성 검사기를 교체하는 것입니다.

Gin의 기본 유효성 검사기를 사용자 정의 유효성 검사기로 교체하기

더 많은 제어, 특히 사용자 정의 태그의 경우 Gin의 기본 유효성 검사기를 교체하는 것이 가장 좋습니다.

package main

import (
	"log"
	"net/http"
	"reflect"
	"strings"

	"github.com/gin-gonic/gin"
	"github.com/gin-gonic/gin/binding"
	"github.com/go-playground/validator/v10"
)

// CustomValidator는 gin.Binding.Validator 인터페이스를 구현합니다
type CustomValidator struct {
	validator *validator.Validate
}

func (cv *CustomValidator) ValidateStruct(obj interface{}) error {
	if kind := reflect.TypeOf(obj).Kind(); kind == reflect.Ptr {
		obj = reflect.ValueOf(obj).Elem().Interface()
	}
	return cv.validator.Struct(obj)
}

func (cv *CustomValidator) Engine() interface{} {
	return cv.validator
}

// isNotReserved는 그대로 유지됩니다
func isNotReserved(fl validator.FieldLevel) bool {
	reservedUsernames := map[string]bool{
		"admin": true,
		"root":  true,
	}
	return !reservedUsernames[fl.Field().String()]
}

// PasswordMatch는 비밀번호가 일치하는지 확인합니다
func PasswordMatch(fl validator.FieldLevel) bool {
    // 전체 구조체 가져오기
	req := fl.Top().Interface().(UserRegisterRequest) 
	return req.Password == req.ConfirmPassword
}

// 사용자 정의 및 필드 간 유효성 검사가 포함된 UserRegisterRequest
type UserRegisterRequest struct {
	Username        string `json:"username" binding:"required,min=3,max=30,notreserved"`
	Email           string `json:"email" binding:"required,email"`
	Password        string `json:"password" binding:"required,min=6"`
	ConfirmPassword string `json:"confirm_password" binding:"required,eqfield=Password"` // 필드 간 유효성 검사
}


func main() {
	r := gin.Default()

	// 사용자 정의 유효성 검사기 초기화 및 규칙 등록
	validate := validator.New()
	validate.RegisterValidation("notreserved", isNotReserved)
	// 옵션: `eqfield`가 충분히 표현적이지 않은 경우 필드 간 유효성 검사를 위한 사용자 정의 태그 등록
	// validate.RegisterValidation("passwordmatch", PasswordMatch) // 이것은 `eqfield`에 대한 대안이 될 수 있습니다

	// 필드 이름 태그 함수 등록하여 오류 필드 이름으로 json 태그 사용
	validate.RegisterTagNameFunc(func(fld reflect.StructField) string {
		name := strings.SplitN(fld.Tag.Get("json"), ",", 2)[0]
		if name == "-" {
			return ""
		}
		return name
	})

	// Gin의 기본 유효성 검사기 교체
	binding.Validator = &CustomValidator{validator: validate}

	r.POST("/register", func(c *gin.Context) {
		var req UserRegisterRequest
		if err := c.ShouldBindJSON(&req); err != nil {
			if validationErrors, ok := err.(validator.ValidationErrors); ok {
				errorResponse := make(map[string]string)
				for _, fieldErr := range validationErrors {
					// json 태그에서 사용자 정의 필드 이름 사용
					errorResponse[fieldErr.Field()] = fieldErr.Tag() 
				}
				c.JSON(http.StatusBadRequest, gin.H{"error": "Validation failed", "details": errorResponse})
			} else {
				c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			}
			return
		}

		c.JSON(http.StatusOK, gin.H{"message": "User registered successfully", "user": req.Username})
	})

	log.Fatal(r.Run(":8080"))
}

이 버전의 주요 변경 사항 및 고급 기능:

  • CustomValidator 구조체: gin.Binding.Validator 인터페이스를 구현하여 validator 인스턴스로 유효성 검사 프로세스를 완전히 제어할 수 있습니다.
  • binding.Validator = &CustomValidator{validator: validate}: 이 줄은 Gin의 기본 유효성 검사기를 사용자 정의 유효성 검사기로 교체합니다.
  • eqfield=Password: 이는 validator v10의 기본 필드 간 유효성 검사 규칙입니다. ConfirmPassword가 Password 필드와 같음을 보장합니다.
  • validate.RegisterTagNameFunc: 이는 유효성 검사 오류의 필드 이름을 매핑할 수 있는 강력한 기능입니다. 기본적으로 validator는 구조체 필드 이름(예: Username)을 사용합니다. JSON API를 다룰 때 일반적으로 더 사용자 친화적인 오류 메시드를 생성하기 위해 json 태그 이름(예: username)을 대신 사용하도록 지시하고 있습니다.

애플리케이션 시나리오

Gin과 validator v10의 조합은 다양한 시나리오에 이상적입니다.

  • 사용자 인증 및 권한 부여: 이메일 형식, 비밀번호 강도, 사용자 이름 고유성 확인.
  • 전자 상거래 플랫폼: 제품 수량, 유효한 주소, 결제 정보 형식 확인.
  • IoT 장치용 API: 장치 데이터가 특정 프로토콜 및 형식과 일치하는지 확인.
  • 구성 API: 적용하기 전에 복잡한 구성 구조 유효성 검사.
  • 양식 제출: 구조화되고 유효성이 검증된 입력이 필요한 모든 웹 양식.

사용자 정의 유효성 검사기를 생성하는 기능은 개발자가 복잡한 비즈니스 로직 유효성 검사를 DTO(Data Transfer Object) 구조체 내에 직접 캡슐화할 수 있게 하여 코드를 더 깔끔하고 유지 보수하기 쉬우며 이해하기 쉽게 만듭니다.

결론: 지능적인 유효성 검사로 API 강화하기

Gin 웹 프레임워크와 go-playground/validator v10을 깊이 통합함으로써 개발자는 정교하고 고도로 사용자 정의 가능한 요청 데이터 유효성 검사 로직을 구축할 수 있습니다. 이는 잘못되거나 유효하지 않은 입력 문제를 사전에 방지하여 연쇄 오류를 방지하고 데이터 무결성을 보장할 뿐만 아니라 API의 견고성, 보안 및 전반적인 신뢰성을 크게 향상시킵니다. 지능적인 유효성 검사는 안정적인 애플리케이션의 보이지 않는 수호자로서 잠재적인 혼돈을 예측 가능한 질서로 바꿉니다.

Share this article

HackerNews

More Posts from Leapcell

Popular Posts