🌘당신도 Go의 context를 잘못 쓰고 있을 수 있습니다

Many Developers Don’t Understand the Use of Context in Golang. Here’s What You Need to Know.

정말로 Go에서의 context를 제대로 이해하고 계신가요?

이 글에서는 context의 핵심 개념을 실전 예제와 함께 명확히 정리합니다.

특히 요청 ID 미들웨어(Request ID Middleware)를 활용한 트레이싱 예제를 통해, context가 실제 서비스에서 어떻게 활용될 수 있는지를 구체적으로 보여드립니다.

Go의 context 패키지는 API와 고루틴 전반에 걸쳐 취소, 데드라인, 요청 단위의 데이터 전달을 관리할 수 있는 강력한 도구입니다.

하지만 많은 개발자들이 그 정확한 사용법이나, 특히 요청 트레이싱과 결합했을 때의 진정한 장점을 잘 이해하지 못하는 경우가 많습니다.

이 글에서는 다음 내용을 중심으로 context.Context의 본질을 파헤쳐봅니다:

• context의 핵심 기능과 실전 활용법
• 요청 ID(Request ID) 미들웨어를 적용한 실제 API 예제 2가지
• 분산 시스템에서 Request ID가 왜 중요한지, 그리고 이를 통해 트레이싱이 어떻게 개선되는지

📌context.Context 란 무엇이며 왜 중요할까요?

Go에서 context.Context는 요청이나 작업의 생애주기 전반에 걸쳐 데드라인, 취소 신호, 메타데이터(키-값 쌍)를 전달하기 위한 구조체입니다.

이 구조를 통해 다음과 같은 작업이 가능해집니다:

• 클라이언트가 연결을 끊거나 데드라인이 초과되었을 때, 작업을 조기에 취소할 수 있음
• 인증 토큰, 트레이싱 ID 등과 같은 메타데이터를 API 계층 전반에 전파할 수 있음
• 고루틴이 불필요하게 살아있는 상황을 막고, 리소스 누수를 방지할 수 있음

context 없이 이와 같은 기능을 직접 구현하려면

취소 로직이 중복되고 코드가 복잡해지며, 리소스 낭비도 쉽게 발생하게 됩니다.

context는 이를 깔끔하고 안전하게 처리할 수 있도록 돕는 Go의 핵심 메커니즘입니다.

---

🧩 트레이싱을 위한 Request ID 미들웨어 구성

Request ID는 각 요청에 고유하게 부여되는 식별자입니다. 이는 분산 트레이싱(distributed tracing)의 핵심 요소로, 다음과 같은 역할을 수행합니다:

• 하나의 요청과 관련된 로그와 메트릭을 연결하여 추적 가능하게 함
• 다수의 서비스에 걸친 복잡한 흐름을 디버깅할 때 핵심 단서 제공
• 전체 시스템에서 요청 지연 시간(latency)과 에러율을 모니터링하는 데 활용됨

가장 좋은 방법은, Request ID를 미들웨어에서 생성하거나 상속받아 context에 저장하는 것입니다. 이렇게 하면 해당 요청을 처리하는 전 영역에서 Request ID를 손쉽게 사용할 수 있게 됩니다.

---

🔧 예제 API: Gorilla Mux, Context, UUID 기반 Request ID 미들웨어

✅ 시나리오

다음은 Request ID 미들웨어가 적용된 실제 API 예제입니다:

• 포트 8081에서 동작하는 메인 서비스
• 모든 요청에 대해 UUID 기반 Request ID 부여
• 외부 API 호출 시 context.WithTimeout을 활용하여 타임아웃 처리

---

🧱 주요 구조

// Request ID를 context에 저장하기 위한 키 정의
type key string
const requestIDKey key = "requestID"

• context.Context에 값을 저장할 때는 고유한 타입의 키를 사용해야 충돌을 방지할 수 있습니다.
• 문자열 대신 별도의 타입 key를 선언하여 사용합니다.

---

🧩 Request ID 미들웨어 구현

func CustomMiddleware() mux.MiddlewareFunc {
    return func(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)
            w.Header().Set("X-Request-ID", reqID) // 응답에도 헤더 세팅
            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}

💡 Request ID는
직접 생성하거나 상위 요청에서 받은 값을 그대로 사용

추적을 위해 클라이언트 → 서버 → 하위 서비스까지 이어져야 효과적입니다.

---

🚀 메인 함수: Router 구성 및 서버 실행

func main() {
    r := mux.NewRouter()
    r.Use(CustomMiddleware())
    r.HandleFunc("/request", handlerRequest).Methods("GET")
    log.Println("Server running at http://localhost:8081")
    log.Fatal(http.ListenAndServe(":8081", r))
}

• mux.Router를 사용해 미들웨어와 라우터를 설정
• /request 경로로 들어오는 요청에 대해 handlerRequest 실행

---

🔍 핵심 핸들러 함수 (/request)

func handlerRequest(w http.ResponseWriter, r *http.Request) {
    reqID, ok := r.Context().Value(requestIDKey).(string)
    if !ok {
        http.Error(w, "Request ID not found in context", http.StatusInternalServerError)
        return
    }

    err := externalAPIHandler(r.Context())
    if err != nil {
        log.Printf("request id: %v error message: %v", reqID, err.Error())
        w.WriteHeader(http.StatusInternalServerError)
        json.NewEncoder(w).Encode(requestIDResponse{Message: "internal server error"})
        return
    }

    json.NewEncoder(w).Encode(requestIDResponse{Message: "success"})
}

🔧 context에서 Request ID를 꺼내 로깅에 활용하고, 외부 API 호출에 같은 context를 넘깁니다.

---

🌐 외부 API 호출 처리 (externalAPIHandler)

func externalAPIHandler(ctx context.Context) error {
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()

    req, err := http.NewRequestWithContext(ctx, http.MethodGet, "http://localhost:8082/external/user", nil)
    if err != nil {
        return err
    }

    client := http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    _, err = io.ReadAll(resp.Body)
    return err
}

• context.WithTimeout을 활용해 5초 이상 지연되면 요청을 자동 취소하도록 설계
• 외부 호출에도 같은 context를 넘겨서 상위 요청 취소 시 하위 작업도 함께 중단됩니다

---

🧠 핵심 포인트 요약

항목	설명
✅ Request ID 생성	UUID 기반 생성 or 클라이언트로부터 전달
✅ Context 저장	context.WithValue로 Request ID를 전파
✅ Context 활용	외부 API 호출 시 타임아웃 및 취소 신호 전달
✅ 추적 편의성	로그마다 Request ID를 남겨 디버깅 용이

---

🛰️ API 2: 외부 서비스 시뮬레이션 (지연 응답)

이 서비스는 포트 8082에서 동작하며, /external/user 경로로 들어오는 요청에 대해 30초간 처리 지연을 시뮬레이션합니다.

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "time"
    "github.com/gorilla/mux"
)

type jsonResponse struct {
    Message string `json:"message"`
}

func handlerUser(w http.ResponseWriter, r *http.Request) {
    time.Sleep(30 * time.Second) // 30초간 작업 지연 시뮬레이션
    w.WriteHeader(http.StatusOK)
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(jsonResponse{
        Message: "Process completed successfully",
    })
}

func main() {
    r := mux.NewRouter()
    r.HandleFunc("/external/user", handlerUser)
    fmt.Println("Server running on http://localhost:8082")
    http.ListenAndServe(":8082", r)
}

---

🎯 이 API의 목적

• 장시간 처리되는 외부 작업 시나리오를 테스트하기 위한 용도
• 실제 서비스에서는 ML 연산, 외부 서비스 호출, DB 정합성 검사 등과 유사한 형태로 발생
• API 1(Main Service)에서 이 API를 호출하고 context.WithTimeout()을 통해 5초 내 응답이 없으면 자동 취소하도록 설정함

---

🔄 전체 흐름 요약 (Mermaid 다이어그램)

📌 30초 대기하는 외부 API와 5초 타임아웃 설정의 조합

context.WithTimeout()이 리소스 낭비를 막고, 사용자 경험을 개선

---

🧪 실전에서 이런 상황이 발생하면?

• 외부 API가 느릴 경우 전체 요청 처리가 지연되고, 클라이언트가 중단해도 서버는 계속 대기할 수 있음
• 이런 상황에서 context의 취소 시그널이 없다면, 고루틴과 연결이 살아남아 리소스 누수 발생

---

🧪 실험: 실제로 이 서비스를 실행하면 어떤 일이 벌어질까?

🎯 케이스 1: 클라이언트가 요청을 보낸 뒤 기다리는 경우

curl -ik http://localhost:8081/request

• 미들웨어가 UUID 기반의 Request ID를 생성하고, 이를 context 및 응답 헤더에 추가합니다.
• 메인 핸들러는 /external/user API를 호출하며, context.WithTimeout()으로 5초 제한을 둡니다.
• 하지만 외부 API는 30초 동안 응답을 지연하므로, 5초가 지나면 context 타임아웃이 발생하고 요청은 실패 처리됩니다.
• 서버는 다음과 같은 JSON 에러 응답을 반환합니다:

HTTP/1.1 500 Internal Server Error
X-Request-ID: 6a1b1a54-6e7c-4ae0-8a2c-a7e376a73f28
Content-Type: application/json

{
  "message": "internal server error"
}

📄 로그 출력 예시:

request id: 6a1b1a54-6e7c-4ae0-8a2c-a7e376a73f28 error message: context deadline exceeded

✅ 이처럼 Request ID가 있다면,

분산된 여러 서비스의 로그를 하나의 흐름으로 추적할 수 있습니다.

---

⛔ 케이스 2: 클라이언트가 요청 중간에 직접 취소하는 경우

curl -ik http://localhost:8081/request
# 요청 후 5초가 되기 전에 Ctrl + C로 중단

• 클라이언트가 직접 요청을 취소(Ctrl + C)하면, Go 서버는 context를 통해 취소 신호를 전파받습니다.
• 이 신호는 외부 API 호출에도 전달되어, API 요청 자체가 중단되고 리소스를 낭비하지 않게 됩니다.
• 클라이언트는 아무런 응답을 받지 않지만, 서버에서는 요청을 깔끔히 종료합니다.

📄 로그 출력 예시:

request id: d3c9e401-b1aa-4410-8b65-b2eabffccf1e error message: context canceled

⚠️ context deadline exceeded 와 context canceled은 의미가 다릅니다. 전자는 시스템이 타임아웃된 경우, 후자는 클라이언트가 취소한 경우 따라서 서비스에서는 이 차이를 명확히 구분하고 처리하는 로직이 필요합니다.

---

🔍 왜 Request ID가 트레이싱에 중요한가?

현대의 마이크로서비스 시스템에서는 하나의 요청이 여러 계층과 서비스로 전파됩니다.

이런 분산 환경에서 Request ID가 없다면 다음과 같은 문제가 발생합니다:

• 로그와 메트릭이 서로 연결되지 않아 흐름 추적이 어려움
• 복잡한 장애 원인 분석이나 지연 분석이 사실상 불가능
• 사용자 요청에 대한 전체 흐름을 신뢰성 있게 관찰(Observability) 할 수 없음

💡 미들웨어에서 Request ID를 생성/전파하고 이를 context.Context에 저장함으로써, 서비스 전반에 걸쳐 일관된 트레이싱 기반을 마련할 수 있습니다.

---

✅ 정리하며: 실전에서 쓸 수 있는 패턴들

이 글에서 다룬 예제를 통해 다음 내용을 배울 수 있었습니다:

• context.WithTimeout()을 활용해 외부 API 호출을 안전하게 종료하는 법
• UUID 기반 Request ID를 미들웨어에서 생성하고 전파하는 구조
• 클라이언트의 취소(Ctrl + C)를 서버까지 전달하고 리소스를 아끼는 처리 방식

이러한 패턴을 익히면 다음과 같은 이점을 얻게 됩니다:

• 📦 코드 유지보수성 향상
• 🔍 서비스 가시성(Observability) 확보
• 🧩 에러 디버깅 및 트레이싱의 일관성

---

💬 마무리

실제 서비스 환경에서 context와 Request ID를 제대로 활용하는 것은

프로덕션급 Go 애플리케이션을 만드는 핵심 역량 중 하나입니다.

---

🔎 추가 인사이트

✅ 1. 컨텍스트 취소 감지 및 정리 코드 구현

왜 중요한가?

context는 단순히 타임아웃/취소 시그널만 전달하는 도구가 아닙니다.

진짜 중요한 건, 고루틴 또는 리소스를 적극적으로 정리(cleanup) 하는 로직을 추가하는 것입니다.

select {
case <-ctx.Done():
    log.Println("context canceled:", ctx.Err())
    // 예: 연결 종료, 채널 닫기, 캐시 롤백 등 리소스 정리
    return ctx.Err()
case result := <-someProcess:
    return result
}

🎯 정리 로직이 없다면 context는 무의미합니다.

---

✅ 2. Request ID를 로그에 자동 포함하는 Logger Wrapping

왜 중요한가?

핸들러 내부에서 매번 ctx.Value()로 Request ID를 꺼내는 건 번거롭고 실수하기 쉽습니다.

따라서 로그 라이브러리를 감싸서 context에서 자동으로 Request ID를 꺼내 로깅에 포함

func LogWithContext(ctx context.Context, msg string) {
    reqID, _ := ctx.Value(requestIDKey).(string)
    log.Printf("[reqID:%s] %s", reqID, msg)
}

🧩 팀에서 공통 Logger 유틸로 만들어 두면 매우 편리합니다.

---

✅ 3.Request ID를 외부 API 호출 시 전파

왜 중요한가?

단일 서비스 내에서만 Request ID를 쓰는 건 반쪽짜리입니다.

외부 API 호출 시에도 반드시 X-Request-ID를 헤더로 추가해 주는 것이 분산 트레이싱의 핵심입니다.

req.Header.Set("X-Request-ID", reqID)

그리고 호출받는 외부 서비스도 그 값을 context에 저장해서 다시 DB, 로그, 다른 API에 전파해야 트레이싱의 연속성이 유지됩니다.

---