Gin를 실무 흐름으로 이해하기
Go 생태계에서 가장 인기 있는 HTTP 웹 프레임워크. 라우팅, 미들웨어, JSON 바인딩, GORM, JWT 인증, Docker 배포까지 실무 중심으로 정리했습니다. 이 가이드는 개념을 나열하기보다, 실제 프로젝트에서 판단해야 하는 순서대로 내용을 따라갈 수 있게 구성했습니다.
Go 웹 프레임워크 가이드
Gin 완전 가이드
Go 생태계에서 가장 인기 있는 HTTP 웹 프레임워크. 라우팅, 미들웨어, JSON 바인딩, GORM, JWT 인증, Docker 배포까지 실무 중심으로 정리했습니다.
가이드 사용법
백엔드 / 시스템 개발
문법보다 요청이 들어와 검증, 처리, 저장, 응답으로 이어지는 경계를 먼저 잡습니다.
구조 다이어그램
글로 읽은 내용을 머릿속에 오래 남기려면 먼저 흐름을 그림으로 잡는 편이 좋습니다. 아래 두 그림은 Gin를 학습할 때 계속 되돌아볼 수 있는 기준 지도입니다.
학습 흐름
다이어그램 렌더링 중…
아키텍처 관점
다이어그램 렌더링 중…
Gin이란?
Gin를 처음 펼칠 때는 세부 명령보다 큰 그림이 먼저입니다. 이 섹션에서는 앞으로 배울 개념들이 어떤 문제를 풀기 위해 등장했는지부터 잡아봅니다.
Gin은 Go로 작성된 고성능 HTTP 웹 프레임워크입니다. HttpRouter 기반으로 초당 수십만 요청을 처리할 수 있습니다.
라우팅
여기서는 라우팅을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.
gin.Default()는 로깅과 panic 복구 미들웨어가 이미 적용된 라우터를 반환해 별도 설정 없이 바로 실무에 쓸 수 있습니다. Group으로 공통 prefix(/api/v1/users)를 묶으면 경로마다 반복해서 적지 않아도 되고, 버전이나 리소스 단위로 라우트를 조직화하기 쉬워집니다.
GO
r := gin.Default() // Logger + Recovery 미들웨어
// 라우터 그룹
api := r.Group("/api/v1")
{
users := api.Group("/users")
users.GET("", listUsers)
users.GET("/:id", getUser)
users.POST("", createUser)
users.PUT("/:id", updateUser)
users.DELETE("/:id", deleteUser)
}
r.Run(":8080")요청 바인딩 & 검증
여기서는 요청 바인딩 & 검증을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.
struct 태그에 binding 규칙을 선언해두면 ShouldBindJSON 한 번으로 JSON 파싱과 필수값·형식 검증이 동시에 끝납니다. required, email, min=8 같은 규칙을 만족하지 못하면 err에 검증 실패 사유가 담기므로, 검증 로직을 핸들러마다 직접 if문으로 작성할 필요가 없습니다.
GO
type CreateUserRequest struct {
Name string `json:"name" binding:"required,min=2"`
Email string `json:"email" binding:"required,email"`
Password string `json:"password" binding:"required,min=8"`
}
func createUser(c *gin.Context) {
var req CreateUserRequest
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
return
}
// 처리 로직
c.JSON(http.StatusCreated, user)
}미들웨어
여기서는 미들웨어을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.
미들웨어는 요청이 실제 핸들러에 도달하기 전후에 공통 로직(로깅, 인증, panic 복구, CORS)을 끼워 넣는 함수입니다. `c.Next()`를 호출하면 체인의 다음 미들웨어(또는 핸들러)로 넘어가고, 그 앞뒤에 코드를 두면 요청 전/응답 후 처리를 모두 구현할 수 있습니다.
middleware.goGO
func RequestLogger() gin.HandlerFunc {
return func(c *gin.Context) {
start := time.Now()
c.Next() // 다음 미들웨어/핸들러 실행 — 여기서 응답이 만들어짐
log.Printf("%s %s %d %v", c.Request.Method, c.Request.URL.Path, c.Writer.Status(), time.Since(start))
}
}
func AuthRequired() gin.HandlerFunc {
return func(c *gin.Context) {
token := c.GetHeader("Authorization")
if token == "" {
c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "missing token"})
return // Abort 이후 c.Next()를 호출하지 않으면 이후 핸들러는 실행되지 않음
}
c.Next()
}
}
r := gin.New()
r.Use(gin.Recovery(), RequestLogger()) // 전역 미들웨어
protected := r.Group("/api/v1/admin")
protected.Use(AuthRequired()) // 그룹 단위로만 적용GORM + 데이터베이스
여기서는 GORM + 데이터베이스을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.
GORM은 Go 생태계에서 가장 널리 쓰이는 ORM으로, 구조체 태그로 테이블 스키마를 정의하고 `AutoMigrate`로 실제 테이블을 동기화합니다. Gin 핸들러 안에서는 GORM이 반환하는 `*gorm.DB`를 그대로 쿼리 빌더처럼 사용합니다.
model.goGO
type User struct {
ID uint `gorm:"primaryKey"`
Name string `gorm:"not null"`
Email string `gorm:"uniqueIndex;not null"`
CreatedAt time.Time
}
db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})
if err != nil {
log.Fatal(err)
}
db.AutoMigrate(&User{}) // 구조체 기준으로 테이블 생성/컬럼 동기화
func getUser(c *gin.Context) {
var user User
if err := db.First(&user, c.Param("id")).Error; err != nil {
c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})
return
}
c.JSON(http.StatusOK, user)
}
func createUser(c *gin.Context) {
var user User
c.ShouldBindJSON(&user)
db.Create(&user)
c.JSON(http.StatusCreated, user)
}JWT 인증
여기서는 JWT 인증을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.
golang-jwt 라이브러리로 로그인 성공 시 서명된 토큰을 발급하고, 이후 요청은 미들웨어에서 그 토큰을 검증해 사용자를 식별합니다. 검증에 성공한 사용자 정보는 `c.Set`으로 컨텍스트에 담아 이후 핸들러에서 꺼내 씁니다.
jwt_auth.goGO
var secretKey = []byte(os.Getenv("JWT_SECRET"))
func GenerateToken(userID uint) (string, error) {
claims := jwt.MapClaims{
"user_id": userID,
"exp": time.Now().Add(24 * time.Hour).Unix(),
}
token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
return token.SignedString(secretKey)
}
func JWTAuthMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
tokenString := strings.TrimPrefix(c.GetHeader("Authorization"), "Bearer ")
token, err := jwt.Parse(tokenString, func(t *jwt.Token) (interface{}, error) {
return secretKey, nil
})
if err != nil || !token.Valid {
c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "invalid token"})
return
}
claims := token.Claims.(jwt.MapClaims)
c.Set("userID", claims["user_id"]) // 이후 핸들러에서 c.GetUint("userID")로 사용
c.Next()
}
}Docker 배포
여기서는 Docker 배포을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.
Go는 정적 바이너리로 컴파일되므로 실행 단계 이미지에 OS나 런타임을 통째로 담을 필요가 없습니다. CGO_ENABLED=0으로 순수 정적 바이너리를 만들면 scratch(빈 이미지) 위에 바이너리 하나만 올려도 실행되어, 최종 이미지 크기를 수 MB 수준까지 줄일 수 있습니다.
DOCKERFILE
FROM golang:1.22-alpine AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-w -s" -o /app ./cmd/server
FROM scratch
COPY --from=builder /app /app
COPY --from=builder /etc/ssl/certs /etc/ssl/certs
EXPOSE 8080
ENTRYPOINT ["/app"]Gin 실무 설계
Gin 실무 설계은 선택지가 갈리는 지점입니다. 표를 기준으로 각 방법의 쓰임새와 운영상의 차이를 비교해두면 이후 판단이 훨씬 쉬워집니다.
Gin은 middleware 순서와 request binding/validation 책임을 명확히 해야 합니다. business logic을 handler에 넣지 않는 것이 중요합니다.
| 결정 지점 | 확인 질문 | 실무 기준 |
|---|---|---|
| 경계 | Gin 코드에서 바뀌기 쉬운 부분은 어디인가? | 입출력, 설정, 외부 연동, 핵심 규칙을 분리합니다. |
| 상태 | 상태가 어디서 생성되고 어디서 사라지는가? | 상태 소유자와 수명 주기를 코드로 드러냅니다. |
| 장애 | 실패했을 때 호출자는 무엇을 받는가? | timeout, fallback, error contract를 먼저 정합니다. |
Gin 운영 기준
이 섹션은 Gin 운영 기준을 실무 관점에서 정리합니다. 개념을 외우기보다, 어떤 상황에서 이 기준을 꺼내 쓸지에 초점을 맞춰보세요.
운영에서는 panic recovery, structured logging, request id, timeout middleware, payload size limit이 필요합니다.
Gin 검증 전략
Gin 검증 전략은 선택지가 갈리는 지점입니다. 표를 기준으로 각 방법의 쓰임새와 운영상의 차이를 비교해두면 이후 판단이 훨씬 쉬워집니다.
httptest로 route, middleware, validation error, auth failure를 검증해야 합니다.
| 품질 축 | 검증 방법 | 완료 기준 |
|---|---|---|
| 정확성 | 정상/실패 케이스를 자동화합니다. | 핵심 시나리오가 재현 가능하게 통과합니다. |
| 회귀 방지 | 버그 수정 시 동일 케이스를 테스트로 남깁니다. | 같은 장애가 다시 배포되지 않습니다. |
| 운영성 | 로그, 메트릭, 알림을 확인합니다. | 문제가 생겼을 때 원인 추적 경로가 있습니다. |