[Gin Gonic] API Routing 설정하기

- 목차

 

들어가며.

Go 언어의 대표적인 웹 프레임워크인 Gin Gonic 은 가볍고 빠른 성능으로 유명합니다.

Gin 의 라우팅(Routing) 시스템은 간단하면서도 강력한 기능을 제공하여 다양한 API 경로를 쉽게 설정할 수 있게 해줍니다.

이번 글에서는 Gin의 라우팅 설정과 활용 방법을 자세히 알아보겠습니다.

 

Routing 이란 ?

Routing(라우팅) 은 클라이언트 요청(URL)과 서버의 특정 동작(Handler) 을 연결하는 작업입니다.

예를 들어, 클라이언트가 GET /users로 요청을 보내면 서버가 사용자 목록을 반환하도록 처리하는 것이 라우팅의 역할입니다.

Gin에서는 라우팅 설정이 간단하며, 다음과 같은 HTTP 메서드를 지원합니다:

• GET: 데이터 조회
• POST: 데이터 생성
• PUT: 데이터 수정
• DELETE: 데이터 삭제
• PATCH: 데이터 일부 수정
• OPTIONS: 허용된 HTTP 메서드 확인
• HEAD: 헤더 정보 확인

 

Gin 의 기본 Routing 설정.

Gin 의 라우팅은 아래와 같이 간단한 코드로 실행할 수 있습니다.

아래 예시는 간단한 GET, POST Method 를 구현합니다.

 

package main

import (
	"net/http"
	"github.com/gin-gonic/gin"
)

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

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

	r.POST("/submit", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{"status": "submitted"})
	})

	r.Run(":8080")
}

 

/ping GET Method 의 클라이언트 호출 예시는 아래와 같습니다.

 

curl -X GET http://localhost:8080/ping

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100    18  100    18    0     0  13167      0 --:--:-- --:--:-- --:--:-- 18000
{
  "message": "pong"
}

 

 

그리고 /submit POST Method 의 클라이언트 호출은 아래와 같습니다.

 

curl -X POST http://localhost:8080/submit

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100    22  100    22    0     0  29372      0 --:--:-- --:--:-- --:--:-- 22000
{
  "status": "submitted"
}

 

 

동적 라우팅 설정.

클라이언트 요청 URL에 지정된 동적인 파라미터를 추출할 수 있습니다.

아래의 예시는 요청 URL 의 Path 에 등록된 :id 라는 동적 변수를 추출하는 예시입니다.

아래의 예시와 같이 Gin Gonic 에서는 URL 경로에서 동적 변수를 손쉽게 추출할 수 있도록 Context.Param 메서드를 제공합니다. 

 

package main

import (
	"github.com/gin-gonic/gin"
	"net/http"
)

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

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

	r.GET("/users/:id", func(c *gin.Context) {
		id := c.Param("id")
		c.JSON(http.StatusOK, gin.H{"user_id": id})
	})

	r.POST("/submit", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{"status": "submitted"})
	})

	r.Run(":8080")
}

 

curl -X GET http://localhost:8080/users/123

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100    17  100    17    0     0  17119      0 --:--:-- --:--:-- --:--:-- 17000
{
  "user_id": "123"
}

 

 

쿼리 파라미터 처리.

쿼리 스트링(Query String) 을 통해 전달된 파라미터를 읽을 수도 있습니다.

아래의 예시는 /search API 요청을 통해서 전달되는 Query String 을 Context.Query 메소드를 통해서 파싱하는 과정입니다.

 

package main

import (
	"github.com/gin-gonic/gin"
	"net/http"
)

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

	r.GET("/search", func(c *gin.Context) {
		query := c.Query("q")
		c.JSON(http.StatusOK, gin.H{"query": query})
	})

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

	r.GET("/users/:id", func(c *gin.Context) {
		id := c.Param("id")
		c.JSON(http.StatusOK, gin.H{"user_id": id})
	})

	r.POST("/submit", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{"status": "submitted"})
	})

	r.Run(":8080")
}

 

curl -X GET http://localhost:8080/search?q=gin

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100    15  100    15    0     0  14749      0 --:--:-- --:--:-- --:--:-- 15000
{
  "query": "gin"
}

 

 

Gin Gonic 의 RouterGroup 이란 ?

Gin Gonic 에서는 RouterGroup 이라는 기능이 제공됩니다.

RouterGroup 은 공통 경로(prefix) 에 미들웨어를 등록하기 위해서 사용됩니다.

 

아래의 예시와 같이 "/api" Base Path 를 만들고 RouterGroup 객체를 생성합니다.

그리고 이 그룹에 속한 모든 라우트는 /api 로 시작하는 경로를 가집니다.

아래의 실행 결과는 "GET /api/users", "POST /api/users" 와 같은 Method 와 API Path 를 가집니다.

 

api := r.Group("/api")
{
    api.GET("/users", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{"message": "List of users"})
    })
    
    api.POST("/users", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{"message": "User created"})
    })
}

 

 

RouterGroup 에 Middleware 적용하기.

RouterGroup 은 공통의 Middleware 를 가질 수 있습니다.

아래의 예시는 "/api" RouterGroup 에 Auth Check 를 수행하는 Middleware 를 적용하는 예시입니다.

클라이언트의 모든 "/api/**" 요청은 반드시 Auth Check Middleware 를 거치게 됩니다.

 

아래와 같이 Request Header 를 추출해야할 때에는 Context.GetHeader 메소드를 사용합니다.

 

package main

import (
	"github.com/gin-gonic/gin"
	"net/http"
)

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

	api := r.Group("/api", func(c *gin.Context) {
		token := c.GetHeader("Authorization")
		if token != "valid_token" {
			c.JSON(http.StatusUnauthorized, gin.H{"error": "Unauthorized"})
			c.Abort()
			return
		}
		c.Next()
	})

	users := api.Group("/users")
	{
		users.GET("/", func(c *gin.Context) {
			c.JSON(http.StatusOK, gin.H{"message": "List of users"})
		})
		users.POST("/", func(c *gin.Context) {
			c.JSON(http.StatusOK, gin.H{"message": "User created"})
		})
	}

	r.Run(":8080")
}

 

Authorization 실패하는 경우.

curl -X GET http://localhost:8080/api/users/

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100    24  100    24    0     0  22598      0 --:--:-- --:--:-- --:--:-- 24000
{
  "error": "Unauthorized"
}

 

Authorization 성공.

curl -X GET 'http://localhost:8080/api/users/' \
-H 'Authorization:valid_token'

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100    27  100    27    0     0  36388      0 --:--:-- --:--:-- --:--:-- 27000
{
  "message": "List of users"
}