BACKEND

Go REST API 서버 구축 — net/http와 Gin, Go 1.27 기준

junetapa 2026. 10. 29 업데이트 14 min read

Go로 REST API 서버를 만들 때 첫 갈림길은 «표준 라이브러리로 시작할지, Gin 같은 프레임워크로 시작할지»다. Go 1.22에서 표준 net/http 라우터가 메서드와 경로 변수를 알아듣게 되면서 이 질문의 답이 바뀌었다. 이 글은 표준 net/http로 CRUD 서버를 세우는 순서, JSON 요청과 오류 응답 다루기, 미들웨어, Gin으로 옮길 시점, 운영에 필요한 타임아웃·종료·테스트까지 차례로 정리한다. 판 번호와 API 동작은 2026년 10월 29일 go.dev·pkg.go.dev·Gin 공식 문서로 다시 확인했다.

2026년 10월 다시 씀

예전 판에 있던 «Node.js에서 Go로 옮겨 초당 처리량 3~5배», «Go 웹 프레임워크 채택률 Gin 48%» 같은 수치는 출처를 다시 확인할 수 없어 뺐다. 기준 판은 Go 1.26에서 Go 1.27로 올렸고, «Go 1.26에서 컨테이너 CPU 제한에 맞춰 GOMAXPROCS 자동 조정»이라고 적었던 문장은 공식 릴리스 노트대로 Go 1.25의 변경으로 바로잡았다.

시작 전 — 판 확인과 프로젝트 구조

2026년 10월 29일 go.dev 릴리스 기록 기준으로 최신 판은 Go 1.27이다. 판마다 서버 코드에 닿는 변경이 있어서, 팀에서 쓰는 판을 먼저 정해 두는 편이 좋다.

판첫 출시최신 패치(10/29 기준)서버 코드에 닿는 변경
Go 1.252025-08-12go1.25.14컨테이너 CPU 제한을 보고 GOMAXPROCS 기본값을 정함 · http.CrossOriginProtection(CSRF 막기) 추가
Go 1.262026-02-10go1.26.10Green Tea 가비지 컬렉터 기본 켜짐 · ServeMux 끝 슬래시 넘김이 301에서 307로
Go 1.272026-08-19go1.27.3(2026-10-19)encoding/json/v2·jsontext 추가, 기존 encoding/json도 v2 구현 위에서 동작 · HTTP/2 서버가 클라이언트 우선순위 신호를 따름 · Server.MaxHeaderValueCount

Go 1.27에서 기존 encoding/json은 코드 변경 없이 그대로 쓰지만, 안쪽 구현이 v2로 바뀌면서 오류 메시지 문구가 달라질 수 있다고 릴리스 노트가 적고 있다. 오류 메시지 문자열을 그대로 비교하는 테스트가 있다면 판을 올릴 때 같이 확인한다.

폴더 구조 — go.dev 공식 안내

go.dev의 «Organizing a Go module» 문서는 서버 프로젝트에 대해 «서버는 보통 밖으로 내보낼 패키지가 없으므로 서버 로직은 internal에 두고, 실행 명령은 cmd에 모으라»고 권한다. internal 아래 패키지는 다른 모듈이 가져다 쓸 수 없어서 마음껏 구조를 바꿀 수 있다는 것이 이유다.

폴더 예
myapi/
  go.mod
  cmd/
    api-server/
      main.go          # 서버 시작·설정 읽기·종료 처리
  internal/
    user/
      handler.go       # HTTP 요청 ↔ 서비스 호출
      service.go       # 규칙과 검증
      store.go         # DB 접근
    httpx/
      respond.go       # JSON 응답·오류 응답 도우미

핸들러·서비스·저장소를 나누는 것은 공식 문서가 정한 규칙이 아니라 흔히 쓰는 나눔이다. 처음에는 기능 단위(user, order) 폴더 안에서 파일만 나누고, 커지면 패키지를 쪼개는 편이 Go 쪽 안내와도 잘 맞는다.

핸들러와 서비스, 저장소로 나뉘는 고 레스트 서버의 계층 구조를 나타낸 도해
핸들러는 얇게, 로직은 가운데, DB 는 맨 아래 — 이 순서를 지키면 테스트가 쉬워진다.

표준 net/http로 라우팅하기

Go 1.22부터 http.ServeMux의 패턴에 HTTP 메서드와 경로 변수를 적을 수 있다. go.dev 블로그 «Routing Enhancements for Go 1.22»가 설명하는 규칙은 다음과 같다.

  • 메서드 — GET /posts/{id}처럼 앞에 메서드를 쓴다. GET 패턴은 HEAD도 받고, 나머지 메서드는 정확히 같아야 한다. 맞는 경로는 있는데 메서드가 다르면 서버가 405와 허용 메서드 목록을 돌려준다.
  • 경로 변수 — {name}은 경로 한 칸, 끝의 {name...}는 남은 경로 전부와 맞는다. 핸들러에서는 r.PathValue("name")으로 꺼낸다.
  • 끝 슬래시만 — /posts/{$}는 «/posts/»에만 맞고 «/posts»나 «/posts/234»에는 맞지 않는다.
  • 우선순위 — 등록 순서와 상관없이 «더 구체적인 패턴이 이긴다». /posts/latest가 /posts/{id}보다 먼저 잡힌다. 어느 쪽도 더 구체적이지 않게 겹치는 두 패턴을 등록하면 panic이 나므로 서버를 켜는 순간 충돌을 알 수 있다.
cmd/api-server/main.go — 라우트 등록
mux := http.NewServeMux()

mux.HandleFunc("GET /api/v1/users", h.List)
mux.HandleFunc("POST /api/v1/users", h.Create)
mux.HandleFunc("GET /api/v1/users/{id}", h.Get)
mux.HandleFunc("PUT /api/v1/users/{id}", h.Update)
mux.HandleFunc("DELETE /api/v1/users/{id}", h.Delete)
mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusNoContent)
})
internal/user/handler.go — 경로 변수 꺼내기
func (h *Handler) Get(w http.ResponseWriter, r *http.Request) {
    id, err := strconv.ParseInt(r.PathValue("id"), 10, 64)
    if err != nil {
        httpx.Problem(w, http.StatusBadRequest, "잘못된 사용자 번호", err.Error())
        return
    }
    u, err := h.svc.Find(r.Context(), id)
    if errors.Is(err, ErrNotFound) {
        httpx.Problem(w, http.StatusNotFound, "사용자 없음", "")
        return
    }
    if err != nil {
        httpx.Problem(w, http.StatusInternalServerError, "서버 오류", "")
        return
    }
    httpx.JSON(w, http.StatusOK, u)
}

한 가지 주의할 점은 1.22 이전 코드와의 호환이다. 이제 중괄호가 경로 변수로 읽히므로, 예전 패턴에 중괄호가 글자 그대로 들어 있었다면 뜻이 바뀐다. 공식 블로그는 이전 동작이 필요하면 httpmuxgo121 GODEBUG 설정으로 되돌릴 수 있다고 안내한다.

REST로 할지 GraphQL로 할지부터 고민 중이라면 GraphQL vs REST API 선택 가이드에서 두 방식을 먼저 비교해 보는 편이 순서상 맞다.

JSON 요청과 응답 다루기

요청 본문을 읽을 때 지켜야 할 것은 세 가지다. 크기를 제한하고, 모르는 필드를 어떻게 다룰지 정하고, 값 검증은 디코딩 뒤에 따로 한다. 크기 제한은 http.MaxBytesReader가 맡는다. pkg.go.dev 문서는 이 함수를 «들어오는 요청 본문 크기를 제한하기 위한 것»으로 설명하고, 한도를 넘으면 *http.MaxBytesError를 돌려준다.

internal/httpx/respond.go — 읽기·쓰기 도우미
const maxBody = 1 << 20 // 1MiB

func Decode(w http.ResponseWriter, r *http.Request, dst any) error {
    r.Body = http.MaxBytesReader(w, r.Body, maxBody)
    dec := json.NewDecoder(r.Body)
    dec.DisallowUnknownFields() // 오타 난 필드 이름을 오류로
    if err := dec.Decode(dst); err != nil {
        return err
    }
    if dec.More() {
        return errors.New("본문에 JSON 값이 두 개 이상")
    }
    return nil
}

func JSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(v)
}

디코딩이 성공했다고 값이 맞는 것은 아니다. 이름이 비었는지, 이메일 모양인지 같은 규칙은 서비스 쪽에서 따로 검사하고, 어느 필드가 왜 틀렸는지를 오류 응답에 담는다. 이 부분이 길어지기 시작하는 것이 프레임워크를 고민할 첫 신호다(아래 Gin 절).

Go 1.27의 JSON v2

Go 1.27에 새로 들어온 encoding/json/v2는 기본값이 더 엄격해서, 문자열 안의 잘못된 UTF-8과 객체 안 중복된 이름을 거부한다. 새 코드에서 v2를 직접 쓰면 중복 키로 검증을 피해 가는 요청을 막는 데 도움이 된다. 기존 encoding/json 코드는 그대로 동작하며, 이전 구현이 꼭 필요하면 빌드 때 GOEXPERIMENT=nojsonv2로 끌 수 있지만 릴리스 노트는 이 선택지가 앞으로 빠질 예정이라고 적었다.

오류 응답 형식 정하기

오류 응답의 모양은 서버 전체에서 하나로 맞추는 편이 클라이언트 쪽 코드를 단순하게 만든다. 따로 정한 형식이 없다면 IETF 표준인 RFC 9457 «Problem Details for HTTP APIs»(2023년 7월, RFC 7807 대체)를 쓰면 된다. 미디어 타입은 application/problem+json이고, 기본 필드는 다섯 개다.

필드뜻
type문제 종류를 가리키는 URI 참조. 없으면 about:blank로 본다
title문제 종류의 짧은 설명. 같은 종류면 매번 같게(번역 제외)
statusHTTP 상태 코드. 실제 응답 상태 코드와 같아야 한다
detail이번 일에 대한 설명. 디버깅 정보가 아니라 클라이언트가 고칠 수 있게 돕는 내용
instance이번 일을 가리키는 URI 참조
internal/httpx/respond.go — RFC 9457 오류 응답
type problem struct {
    Type   string `json:"type"`
    Title  string `json:"title"`
    Status int    `json:"status"`
    Detail string `json:"detail,omitempty"`
}

func Problem(w http.ResponseWriter, status int, title, detail string) {
    w.Header().Set("Content-Type", "application/problem+json")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(problem{"about:blank", title, status, detail})
}

500 응답의 detail에는 내부 오류 문자열을 넣지 않는다. DB 주소나 쿼리 조각이 밖으로 새기 쉽기 때문이다. 내부 오류는 로그에만 남기고, 응답에는 요청을 구분할 수 있는 번호 정도만 준다.

미들웨어 — 로깅·복구·CSRF

표준 라이브러리에서 미들웨어는 http.Handler를 받아 http.Handler를 돌려주는 함수일 뿐이다. 따로 등록 장치가 없으니 감싸는 순서가 곧 실행 순서다.

internal/httpx/middleware.go
func Logging(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        next.ServeHTTP(w, r)
        slog.Info("req", "method", r.Method, "path", r.URL.Path, "took", time.Since(start))
    })
}

func Recover(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if v := recover(); v != nil {
                slog.Error("panic", "value", v)
                Problem(w, http.StatusInternalServerError, "서버 오류", "")
            }
        }()
        next.ServeHTTP(w, r)
    })
}

// main.go: 바깥쪽이 먼저 실행
handler := httpx.Logging(httpx.Recover(mux))

브라우저에서 쿠키로 로그인하는 API라면 CSRF도 챙겨야 한다. Go 1.25에 들어온 http.CrossOriginProtection은 브라우저의 Fetch 메타데이터(Sec-Fetch-Site)나 Origin과 Host 비교로 교차 출처 요청을 가려 «안전하지 않은» 요청을 거부한다. 토큰이나 쿠키가 필요 없고, GET·HEAD·OPTIONS는 항상 통과시킨다. 토큰 인증(Authorization 헤더)만 쓰는 API라면 해당이 덜하지만, 관리 화면처럼 쿠키 세션을 쓰는 곳이 섞여 있다면 붙여 두는 편이 낫다.

Gin으로 옮길 시점과 바뀌는 코드

표준 라이브러리만으로도 위 구성이 다 된다. 그래도 프레임워크를 얹는 이유는 반복 코드다. 라우트 묶음마다 다른 미들웨어, 쿼리·폼·JSON을 구조체로 한 번에 읽기, 필드 태그로 하는 검증이 많아질수록 직접 짠 도우미가 길어진다. 아래 표는 같은 일을 두 방식으로 할 때의 차이다.

할 일표준 net/httpGin
메서드·경로 변수"GET /users/{id}" · r.PathValue("id")r.GET("/users/:id", …) · c.Param("id")
라우트 묶음하위 mux를 만들어 StripPrefix로 붙이거나 접두사를 직접 적음r.Group("/api/v1")에 미들웨어까지 묶음
JSON 읽기와 검증디코딩 + 직접 짠 검사c.ShouldBindJSON(&in) + binding:"required,email" 태그(go-playground/validator)
기본 미들웨어직접 감쌈gin.Default()에 로거·복구 포함
외부 의존성없음Gin과 그 의존 모듈
Gin으로 같은 생성 API
type createUser struct {
    Name  string `json:"name"  binding:"required,min=2,max=50"`
    Email string `json:"email" binding:"required,email"`
}

r := gin.Default() // 로거·복구 미들웨어 포함
v1 := r.Group("/api/v1")
v1.POST("/users", func(c *gin.Context) {
    var in createUser
    if err := c.ShouldBindJSON(&in); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"title": "입력 오류", "detail": err.Error()})
        return
    }
    // 서비스 호출 …
    c.JSON(http.StatusCreated, in)
})

2026년 10월 29일 확인한 Gin 공식 문서는 Go 1.25 이상을 요구하고, 안내된 최신 판은 Gin 1.12.0이다. Gin의 FAQ는 검증에 go-playground/validator를 쓴다고 적고, ShouldBindJSON이 실패하면 400으로 답하는 예를 보여 준다. 위 예처럼 서비스·저장소 계층을 표준 라이브러리 시절 그대로 두고 핸들러 층만 바꾸면, 나중에 다른 프레임워크로 옮기거나 표준으로 돌아오는 비용도 작다.

진과 에코, 파이버, 카이 등 고 프레임워크의 성격을 정리한 도해
Go 는 표준 라이브러리만으로도 서버가 되므로 «얼마나 얹을지»의 문제다.

Echo·Chi·Fiber 같은 다른 선택지도 있다. 고를 때는 속도 순위보다 표준 http.Handler 미들웨어를 그대로 쓸 수 있는지, 팀이 이미 아는 방식인지를 먼저 보는 편이 실무에 가깝다. 다른 언어의 백엔드 프레임워크와 견줘 보고 싶다면 FastAPI vs Django vs Flask 선택 가이드를 함께 보면 된다.

서버 설정 — 타임아웃과 안전한 종료

http.ListenAndServe(":8080", mux) 한 줄은 예제로는 편하지만 타임아웃이 하나도 없다. pkg.go.dev 문서에 적힌 http.Server의 네 타임아웃은 이렇게 나뉜다.

필드재는 구간비었을 때
ReadHeaderTimeout요청 헤더를 읽는 시간ReadTimeout 값을 씀
ReadTimeout본문까지 포함한 요청 전체를 읽는 시간0이면 제한 없음
WriteTimeout응답을 쓰는 시간(새 요청 헤더를 읽을 때마다 다시 잼)0이면 제한 없음
IdleTimeoutkeep-alive 연결에서 다음 요청을 기다리는 시간ReadTimeout 값을 씀

내릴 때는 Server.Shutdown을 쓴다. 문서에 따르면 Shutdown은 먼저 열린 리스너를 모두 닫고, 쉬고 있는 연결을 닫은 뒤, 처리 중인 연결이 끝날 때까지 기다린다. 이때 ListenAndServe는 곧바로 http.ErrServerClosed를 돌려주므로, 프로그램이 Shutdown이 끝나기 전에 빠져나가지 않게 짜야 한다. 넘겨준 context가 먼저 끝나면 Shutdown은 그 오류를 돌려준다. WebSocket처럼 가로챈(hijacked) 연결은 닫지도 기다리지도 않으니 따로 알려야 한다.

cmd/api-server/main.go — 시작과 종료
srv := &http.Server{
    Addr:              ":8080",
    Handler:           handler,
    ReadHeaderTimeout: 5 * time.Second,
    ReadTimeout:       15 * time.Second,
    WriteTimeout:      30 * time.Second,
    IdleTimeout:       60 * time.Second,
}

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()

go func() {
    if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
        log.Fatal(err)
    }
}()

<-ctx.Done() // 종료 신호를 기다림
shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := srv.Shutdown(shutdownCtx); err != nil {
    log.Printf("shutdown: %v", err)
}

위 타임아웃 숫자는 예시일 뿐이다. 파일 업로드처럼 본문이 큰 경로가 있으면 전체 ReadTimeout을 짧게 두기 어렵기 때문에, 헤더 타임아웃만 짧게 두고 그 경로에서 따로 제한하는 식으로 나눈다. 컨테이너로 배포한다면 Go 1.25부터 런타임이 cgroup CPU 제한을 보고 GOMAXPROCS 기본값을 정한다(쿠버네티스의 «CPU limit»과 대응, «CPU request»는 보지 않음). 이미지 빌드와 배포 파이프라인은 Docker + GitHub Actions CI/CD 완전 가이드에 정리했다.

httptest로 핸들러 테스트

표준 net/http/httptest의 NewRecorder를 쓰면 실제 포트를 열지 않고 핸들러를 바로 호출해 응답을 확인할 수 있다. 라우터(mux)째로 호출하면 메서드·경로 패턴까지 함께 검증된다.

internal/user/handler_test.go
func TestGetUser_NotFound(t *testing.T) {
    mux := newTestMux(t) // 가짜 저장소를 넣은 라우터
    req := httptest.NewRequest(http.MethodGet, "/api/v1/users/999", nil)
    rec := httptest.NewRecorder()

    mux.ServeHTTP(rec, req)

    if rec.Code != http.StatusNotFound {
        t.Fatalf("status = %d, want 404", rec.Code)
    }
    if ct := rec.Header().Get("Content-Type"); ct != "application/problem+json" {
        t.Fatalf("content-type = %q", ct)
    }
}

func TestUsers_MethodNotAllowed(t *testing.T) {
    mux := newTestMux(t)
    req := httptest.NewRequest(http.MethodPatch, "/api/v1/users", nil)
    rec := httptest.NewRecorder()
    mux.ServeHTTP(rec, req)
    if rec.Code != http.StatusMethodNotAllowed {
        t.Fatalf("status = %d, want 405", rec.Code)
    }
}

Go 1.27에는 메모리 안의 가짜 네트워크를 쓰는 httptest.NewTestServer가 더해져 testing/synctest와 함께 쓸 수 있게 됐다. 타임아웃처럼 시간이 걸리는 동작을 시험할 때 쓸모가 있다. 다만 1.27 전용 API이므로 지원하는 판이 섞인 팀이라면 go.mod의 go 줄을 먼저 맞춘다.

자주 묻는 것

Go로 REST API를 만들 때 프레임워크가 꼭 필요한가요?

꼭 필요하지는 않습니다. Go 1.22부터 표준 net/http의 ServeMux가 GET /users/{id} 같은 메서드·경로 변수 패턴을 지원하고, 맞지 않는 메서드에는 405와 허용 메서드 목록을 돌려줍니다. 라우트 묶음, 요청 바인딩과 검증을 많이 쓰게 될 때 Gin 같은 프레임워크를 얹으면 됩니다.

지금 Go 최신 판은 무엇인가요?

2026년 10월 29일 go.dev 릴리스 기록 기준으로 최신 판은 Go 1.27(1.27.0은 2026년 8월 19일)이고 최신 패치는 2026년 10월 19일의 go1.27.3입니다. 같은 날 1.26 계열도 go1.26.10 패치가 나왔습니다.

Gin을 쓰려면 Go 몇 버전이 필요한가요?

2026년 10월 29일 확인한 Gin 공식 문서는 Go 1.25 이상을 요구한다고 적고 있습니다. 문서에 안내된 최신 Gin 판은 1.12.0입니다.

서버를 내릴 때 처리 중인 요청을 잃지 않으려면 어떻게 하나요?

http.Server의 Shutdown을 씁니다. Shutdown은 먼저 리스너와 쉬고 있는 연결을 닫고, 처리 중인 연결이 끝날 때까지 기다립니다. 넘겨준 context가 먼저 끝나면 그 오류를 돌려주므로 보통 몇 초짜리 타임아웃 context를 함께 줍니다.

정리

Go REST API 서버는 표준 net/http로 시작해도 충분하다. Go 1.22 이후의 패턴 라우팅으로 메서드·경로 변수를 처리하고, 본문 크기 제한과 RFC 9457 오류 응답을 도우미 함수 두 개로 묶고, 로깅·복구 미들웨어로 감싼다. 바인딩·검증 코드가 길어지고 라우트 묶음이 늘면 그때 Gin을 핸들러 층에만 얹는다. 어느 쪽이든 운영에 나가기 전에는 http.Server 타임아웃, Shutdown을 쓴 종료, httptest 테스트 세 가지를 갖춰 둔다.

Go REST API 서버 구축 대표 그림 — 왼쪽에 «Go REST API 서버 구축» 제목과 «Go 1.27 · RFC 9457» 배지가 있고, 오른쪽에 전원 버튼과 방패가 달린 서버 상자에서 네 갈래 색 화살표가 각 상자로 뻗고 위에 중괄호 모양 JSON 카드가 떠 있는 장면
Go REST API 서버 구축 — net/http와 Gin, Go 1.27 기준.

참고 자료

  1. go.dev. Release History — go1.25.0 2025-08-12, go1.26.0 2026-02-10, go1.27.0 2026-08-19, go1.27.3·go1.26.10 2026-10-19(2026-10-29 확인). go.dev
  2. go.dev. Go 1.27 Release Notes — encoding/json/v2·jsontext, nojsonv2, HTTP/2 우선순위, Server.MaxHeaderValueCount, httptest.NewTestServer(2026-10-29 확인). go.dev
  3. go.dev. Go 1.26 Release Notes — Green Tea GC 기본, ServeMux 끝 슬래시 넘김 307(2026-10-29 확인). go.dev
  4. go.dev. Go 1.25 Release Notes — 컨테이너 인식 GOMAXPROCS, CrossOriginProtection(2026-10-29 확인). go.dev
  5. go.dev blog. Routing Enhancements for Go 1.22 — 메서드·와일드카드·{$}·우선순위·405·httpmuxgo121(2026-10-29 확인). go.dev
  6. go.dev. Organizing a Go module — internal·cmd, 서버 프로젝트 배치(2026-10-29 확인). go.dev
  7. pkg.go.dev. net/http — Server 타임아웃 네 필드, Server.Shutdown, ErrServerClosed, MaxBytesReader, CrossOriginProtection(2026-10-29 확인). pkg.go.dev
  8. RFC Editor. RFC 9457 Problem Details for HTTP APIs — 2023년 7월, RFC 7807 대체, application/problem+json, 필드 다섯(2026-10-29 확인). rfc-editor.org
  9. Gin Web Framework. Documentation — Go 1.25 이상, Gin 1.12.0, gin.Default 로거·복구(2026-10-29 확인). gin-gonic.com
  10. Gin Web Framework. FAQ — go-playground/validator 검증, binding 태그, ShouldBindJSON 예(2026-10-29 확인). gin-gonic.com
Go Golang REST API net/http ServeMux Gin Go 1.27 백엔드
junetapa(박준철)
개발자가 아니라 쓰는 사람. IT 현장 27년의 기준으로 AI 도구를 고르고 기록한다.
Twitter Facebook URL 복사