Go의 context.Context를 올바르게 다루기: Cancellation, Timeouts, Values
Go의 컨텍스트는 저장소가 아닌 제어 흐름입니다.
Go의 context.Context는 잘못 사용할 만큼 충분히 간단합니다. 그리고 바로 그것이 문제입니다.
대부분의 Go 개발자들은 표면적인 규칙을 빠르게 배웁니다. 컨텍스트를 첫 번째 인자로 전달하고, ctx.Done()을 확인하며, context.WithTimeout을 사용하고, 절대 nil을 전달하지 않습니다.
func DoSomething(ctx context.Context) error {
// ...
}
이 규칙들은 유용하지만, 쉬운 부분만 다룹니다. 프로덕션 서비스에서 컨텍스트는 단순한 파라미터 관례가 아닙니다. 그것은 요청 수명(request lifetime)을 위한 제어 평면(control plane)입니다.
컨텍스트는 작업에 언제 멈출지, 얼마 남았는지, 어떤 취소 경로가 선택되었는지, 그리고 어떤 요청 범위(request-scoped) 값들이 API 경계를 넘어야 하는지를 알려줍니다. 잘 사용하면 고루틴 누출을 방지하고, 낭비되는 작업을 피하며, 마감 시간을 전파하고, 서비스의 graceful shutdown(우아한 종료)을 용이하게 합니다. 잘못 사용하면 숨겨진 의존성, 가짜 전역 변수, 잊혀진 타임아웃, 누출된 타이머, 그리고 혼란스러운 취소 동작의 바구니가 됩니다.
조금 더 주관이 뚜렷한 버전은 이렇습니다: 컨텍스트는 취소, 마감 시간, 요청 범위 메타데이터에 사용하고, 의존성 컨테이너로는 사용하지 마십시오.
컨텍스트는 무엇을 위한가
context 패키지는 세 가지 주요 역할이 있습니다. 취소, 마감 시간 및 타임아웃, 그리고 요청 범위 값들입니다. 이 세 가지 역할이 컨텍스트가 설계된 모든 용도를 포괄합니다.
컨텍스트는 다음과 같은 질문에 대답해야 합니다:
이 요청이 취소되었는가?
이 작업에 남은 시간은 얼마나 되는가?
로그에 연결할 요청 ID는 무엇인가?
이 요청과 관련된 인증된 사용자는 누구인가?
컨텍스트는 다음과 같은 질문에 대답해서는 안 됩니다:
내 데이터베이스 연결은 어디 있는가?
내 로거는 어디 있는가?
내 구성(config)은 어디 있는가?
어떤 서비스 구현을 사용해야 하는가?
이것들은 의존성(dependencies)입니다. 함수 파라미터를 통해 명시적으로 전달하십시오(Go에서의 의존성 주입에서 이를 깔끔하게 처리하는 패턴을 참조하십시오). 컨텍스트는 애플리케이션 와이어링(application wiring)을 위한 것이 아니라, 요청 수명과 요청 메타데이터를 위한 것입니다.
컨텍스트의 기본 형태
핵심 인터페이스는 작습니다:
type Context interface {
Deadline() (deadline time.Time, ok bool)
Done() <-chan struct{}
Err() error
Value(key any) any
}
중요한 부분은 다음과 같습니다:
Done()은 컨텍스트가 취소되거나 마감 시간이 만료될 때 닫힙니다.Err()는 컨텍스트가 종료된 이유를 설명합니다.Deadline()은 컨텍스트에 마감 시간이 있는지 알려줍니다.Value()는 요청 범위 데이터를 저장합니다.
대부분의 코드는 이 인터페이스를 구현하지 않습니다. 컨텍스트를 받아서 아래로 전달할 뿐입니다.
첫 번째 규칙: 컨텍스트를 명시적으로 전달하십시오
요청 범위나 취소 가능한 작업을 수행하는 함수의 경우, 컨텍스트를 첫 번째 파라미터로 전달하십시오. 이는 표준 Go 관례이며, 생태계의 모든 라이브러리와 도구가 기대하는 방식입니다:
func GetUser(ctx context.Context, id string) (*User, error) {
// ...
}
다음과 같은 작업을 수행할 수 있는 함수에 대해 이렇게 하십시오:
- 데이터베이스 호출
- 다른 서비스 호출
- 대기열 대기
- 백그라운드 작업 시작
- I/O 차단
- 타임아웃 사용
- 요청 범위 값 필요
- 취소 필요
컨텍스트가 필요하지 않은 작은 순수 함수에는 컨텍스트를 추가하지 마십시오.
이것은 괜찮습니다:
func NormalizeEmail(email string) string {
return strings.ToLower(strings.TrimSpace(email))
}
모든 함수가 컨텍스트를 필요로 하는 것은 아닙니다. 모든 곳에 컨텍스트를 추가하면 코드가 지저분해집니다.
구조체에 컨텍스트를 저장하지 마십시오
구조체에 컨텍스트를 저장하는 것은 Go 코드베이스에서 가장 흔한 실수 중 하나이며, 명시적으로 지적할 가치가 있습니다. 이렇게 하지 마십시오:
type UserService struct {
ctx context.Context
db *sql.DB
}
대신 이렇게 하십시오:
type UserService struct {
db *sql.DB
}
func (s *UserService) GetUser(ctx context.Context, id string) (*User, error) {
// ...
}
컨텍스트는 요청, 작업 또는 태스크에 속하는 반면, 서비스 구조체는 일반적으로 단일 요청보다 훨씬 더 오래 살아갑니다. 이러한 수명을 섞으면 취소를 명확히 하기 어렵고, 컨텍스트가 어떤 작업에 속하는지 추론하기 어려워집니다.
단일 작업 수명을 진정으로 나타내는 타입에 대한 드문 예외는 있지만, 그렇게 드물기 때문에 기본 규칙은 간단해야 합니다:
컨텍스트를 전달하십시오. 저장하지 마십시오.
nil 컨텍스트를 전달하지 마십시오
절대 nil을 컨텍스트로 전달하지 마십시오.
나쁜 예:
err := svc.DoWork(nil)
기존 컨텍스트가 없을 때 context.Background()를 사용하십시오:
err := svc.DoWork(context.Background())
테스트에서는 가능하면 테스트 컨텍스트를 사용하십시오:
func TestDoWork(t *testing.T) {
err := svc.DoWork(t.Context())
if err != nil {
t.Fatal(err)
}
}
nil 컨텍스트는 코드가 그 위에 메서드를 호출할 때 패닉을 일으킬 수 있습니다. 백그라운드 컨텍스트는 명시적이고 안전합니다.
Background, TODO 및 요청 컨텍스트
세 가지 일반적인 시작점이 있습니다.
context.Background
부모 컨텍스트가 없을 때 프로그램의 최상위 레벨에서 context.Background()를 사용하십시오. 이는 모든 하위 컨텍스트가 파생되는 루트 컨텍스트입니다:
func main() {
ctx := context.Background()
_ = run(ctx)
}
또는:
func TestSomething(t *testing.T) {
ctx := context.Background()
_ = ctx
}
context.TODO
컨텍스트가 사용되어야 한다는 것을 알지만, 아직 어떤 컨텍스트를 사용할지 결정하지 않았을 때 context.TODO()를 사용하십시오.
ctx := context.TODO()
이는 마이그레이션 동안 유용하지만, 실제 컨텍스트가 존재한다면 영구적으로 남지 않아야 합니다.
Request context
HTTP 서버에서는 요청 컨텍스트를 사용하십시오:
func handler(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
_ = ctx
}
요청 컨텍스트는 클라이언트 연결이 닫히거나, 요청이 취소되거나, 서버가 요청 처리를 완료할 때 취소됩니다.
웹 서비스의 경우, 이는 일반적으로 애플리케이션 코드로 전달해야 하는 컨텍스트입니다.
context.WithCancel을 사용한 취소
명시적으로 작업을 멈추고 싶을 때 context.WithCancel를 사용하십시오.
ctx, cancel := context.WithCancel(parent)
defer cancel()
반환된 cancel 함수는 하위 컨텍스트를 취소하고 관련 리소스를 해제합니다. 완료 시 항상 호출하십시오. 컨텍스트가 결국 타임아웃되더라도, cancel을 조기에 호출하면 리소스를 필요 이상으로 살아있게 두는 것을 피할 수 있습니다.
예시:
func RunWorker(parent context.Context) error {
ctx, cancel := context.WithCancel(parent)
defer cancel()
done := make(chan error, 1)
go func() {
done <- doBackgroundWork(ctx)
}()
select {
case <-ctx.Done():
return ctx.Err()
case err := <-done:
return err
}
}
패턴은 간단합니다:
- 하위 컨텍스트를 파생시킵니다.
- cancel을 defer로 호출합니다.
- 함께 멈춰야 할 작업에 하위 컨텍스트를 전달합니다.
ctx.Done()을 관찰합니다.
context.WithTimeout을 사용한 타임아웃
작업에 최대 지속 시간이 있을 때 context.WithTimeout를 사용하십시오.
ctx, cancel := context.WithTimeout(parent, 2*time.Second)
defer cancel()
HTTP 클라이언트 예시:
func FetchUser(ctx context.Context, client *http.Client, url string) (*http.Response, error) {
ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
defer cancel()
req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
if err != nil {
return nil, err
}
return client.Do(req)
}
이는 타임아웃을 숨겨진 전역 설정이 아닌 작업의 일부로 만듭니다.
cancel을 항상 호출하십시오
WithCancel, WithTimeout, 또는 WithDeadline을 호출할 때, 항상 반환된 cancel 함수를 호출하십시오. 이는 정확성(correctness)에 중요합니다.
좋은 예:
ctx, cancel := context.WithTimeout(parent, 5*time.Second)
defer cancel()
나쁜 예:
ctx, _ := context.WithTimeout(parent, 5*time.Second)
cancel을 호출하지 않으면 타이머와 하위 컨텍스트가 필요한 것보다 더 오래 살아남을 수 있습니다.
마감 시간(Deadlines) 대 타임아웃(Timeouts)
타임아웃은 상대적입니다:
ctx, cancel := context.WithTimeout(parent, 2*time.Second)
defer cancel()
마감 시간은 절대적입니다:
deadline := time.Now().Add(2 * time.Second)
ctx, cancel := context.WithDeadline(parent, deadline)
defer cancel()
대부분의 애플리케이션 코드는 타임아웃을 사용합니다. 마감 시간은 여러 작업에 걸쳐 공유되어야 하는 고정된 종료 시간이 있는 요청에 유용합니다. 예를 들어, 요청에 900밀리초가 남았을 때, 각 다운스트림 호출에 새로운 1초 타임아웃을 주지 마십시오. 대신 남은 예산을 전파하십시오.
서비스 계층을 통한 타임아웃 예산
흔한 실수는 타임아웃을 맹목적으로 쌓는 것입니다.
func Handler(w http.ResponseWriter, r *http.Request) {
ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
defer cancel()
_ = service.DoWork(ctx)
}
func (s *Service) DoWork(ctx context.Context) error {
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
return s.repo.Query(ctx)
}
이는 해롭지 않아 보이지만, 실제 예산을 숨깁니다. 서비스 계층은 타이머를 동일한 값으로 재설정하는 대신 호출자의 마감 시간을 존중해야 합니다.
더 나은 패턴은 다음과 같습니다:
func Handler(w http.ResponseWriter, r *http.Request) {
ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
defer cancel()
if err := service.DoWork(ctx); err != nil {
// handle error
return
}
}
그리고 서비스 내부에서:
func (s *Service) DoWork(ctx context.Context) error {
return s.repo.Query(ctx)
}
하위 작업이 더 작은 예산이 필요할 때만 하위 타임아웃을 추가하십시오:
func (s *Service) DoWork(ctx context.Context) error {
queryCtx, cancel := context.WithTimeout(ctx, 500*time.Millisecond)
defer cancel()
return s.repo.Query(queryCtx)
}
올바른 정신적 모델은 직관적입니다: 전체 요청에는 하나의 외부 예산이 있고, 특정 하위 작업은 그 예산에서 할당된 더 작은 예산을 가질 수 있으며, 어떤 계층도 호출자가 의도한 것 이상으로 요청을 조용히 확장해서는 안 됩니다.
ctx.Err()를 사용하여 취소와 타임아웃 구별
컨텍스트가 종료될 때, ctx.Err()는 이유를 반환합니다.
보통 다음과 같습니다:
context.Canceled
context.DeadlineExceeded
예시:
select {
case <-ctx.Done():
return ctx.Err()
case result := <-resultCh:
return handle(result)
}
이는 호출자에게 취소와 타임아웃을 구별할 수 있게 해주며, 이 구별은 실제 중요합니다. 취소된 요청은 종종 클라이언트가 연결을 끊었음을 의미하는 반면, 마감 시간 초과 오류는 일반적으로 서비스가 너무 느렸음을 의미합니다. 따라서 항상 동일한 방식으로 로깅, 재시도 또는 보고해서는 안 됩니다.
더 나은 취소 이유를 위해 context.Cause 사용
현대 Go는 원인 인지(cause-aware) 취소도 지원합니다.
유용한 함수에는 다음이 포함됩니다:
context.WithCancelCausecontext.WithTimeoutCausecontext.WithDeadlineCausecontext.Cause
단순한 ctx.Err()는 넓은 이유(취소 또는 마감 시간 초과)를 알려줍니다.
context.Cause(ctx)는 더 구체적인 원인을 알려줄 수 있습니다.
예시:
var ErrShutdown = errors.New("server shutting down")
func Run(ctx context.Context) error {
ctx, cancel := context.WithCancelCause(ctx)
defer cancel(nil)
go func() {
// Some shutdown signal arrived.
cancel(ErrShutdown)
}()
<-ctx.Done()
return context.Cause(ctx)
}
이유가 호출자, 로그 또는 정리 동작에 중요한 경우 원인 인지 취소를 사용하고, 단순한 ctx.Err()가 충분한 곳에서는 피하십시오. 추가적인 세부 사항은 진단이 진정으로 필요할 때만 가치가 있습니다.
HTTP 서버 예시
일반적인 HTTP 핸들러는 r.Context()로 시작해야 합니다. Go HTTP 서비스 구조화에 대한 전체적인 walkthrough는 Go에서 REST API 구축을 참조하십시오.
func GetUserHandler(svc *UserService) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
id := r.PathValue("id")
user, err := svc.GetUser(ctx, id)
if err != nil {
writeError(w, err)
return
}
writeJSON(w, http.StatusOK, user)
}
}
서비스는 컨텍스트를 받아서 전파해야 합니다:
type UserService struct {
repo *UserRepository
}
func (s *UserService) GetUser(ctx context.Context, id string) (*User, error) {
return s.repo.GetUser(ctx, id)
}
리포지토리(repository)는 컨텍스트 인식 데이터베이스 메서드를 사용해야 합니다:
type UserRepository struct {
db *sql.DB
}
func (r *UserRepository) GetUser(ctx context.Context, id string) (*User, error) {
const query = `
select id, email, name
from users
where id = $1
`
var user User
err := r.db.QueryRowContext(ctx, query, id).Scan(
&user.ID,
&user.Email,
&user.Name,
)
if err != nil {
return nil, err
}
return &user, nil
}
중요한 것은 체인입니다. 각 계층은 동일한 컨텍스트를 다음으로 전달합니다:
중간에 context.Background()를 생성하여 체인을 끊지 마십시오.
context.Background() 실수: 취소 체인 끊기
이는 흔한 버그입니다:
func (s *UserService) GetUser(ctx context.Context, id string) (*User, error) {
return s.repo.GetUser(context.Background(), id)
}
이는 호출자로부터 모든 취소 및 마감 시간 정보를 버립니다. 클라이언트가 연결을 끊으면 데이터베이스 쿼리가 계속 실행됩니다. 요청이 타임아웃되면 다운스트림 작업이 여전히 진행 중일 수 있습니다. 서버가 종료 중이면 이 코드는 이를 완전히 무시합니다. 비즈니스 로직 내부에서 수신된 컨텍스트를 context.Background()로 교체하는 것은 거의 항상 잘못되었습니다.
주어진 컨텍스트를 사용하십시오:
func (s *UserService) GetUser(ctx context.Context, id string) (*User, error) {
return s.repo.GetUser(ctx, id)
}
context.Background()는 부모 컨텍스트가 없는 가장자리(edge)에서만 사용하십시오.
HTTP 클라이언트 예시
아웃바운드 HTTP 요청의 경우, 컨텍스트를 요청에 연결하십시오.
func CallAPI(ctx context.Context, client *http.Client, endpoint string) (*http.Response, error) {
req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
if err != nil {
return nil, err
}
return client.Do(req)
}
이렇게 하지 마십시오:
req, err := http.NewRequest(http.MethodGet, endpoint, nil)
이는 작업 컨텍스트 없이 요청을 생성합니다.
또한 http.Client.Timeout에만 의존하지 마십시오. 이는 안전 제한으로 유용할 수 있지만, 요청 컨텍스트는 호출 체인 전반에 걸쳐 더 나은 전파를 제공합니다.
흔한 패턴은 다음과 같습니다:
func CallAPI(ctx context.Context, client *http.Client, endpoint string) (*http.Response, error) {
ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
defer cancel()
req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
if err != nil {
return nil, err
}
return client.Do(req)
}
이는 더 큰 요청 내에서 다운스트림 API 호출이 특정 예산을 필요로 할 때 사용하십시오.
데이터베이스 예시
대부분의 Go 데이터베이스 API는 컨텍스트 인식 메서드를 가지고 있습니다. GORM, Ent, Bun, sqlc를 포함하여 Go 데이터 액세스 라이브러리가 컨텍스트를 처리하는 방식에 대한 더 넓은 시야를 원하시면 PostgreSQL용 Go ORM 비교를 참조하십시오.
이들을 사용하십시오.
좋은 예:
rows, err := db.QueryContext(ctx, query, args...)
좋은 예:
err := db.QueryRowContext(ctx, query, id).Scan(&name)
좋은 예:
result, err := db.ExecContext(ctx, query, args...)
나쁜 예:
rows, err := db.Query(query, args...)
컨텍스트 인식 형태는 요청이 취소되거나 타임아웃될 때 데이터베이스 작업이 멈추도록 허용하며, 이는 느린 쿼리, 과부하된 데이터베이스, 그리고 지연 시간이 사용자 경험에 직접적인 영향을 미치는 사용자 중심 API에서 특히 중요합니다.
트랜잭션과 컨텍스트
트랜잭션은 신중한 컨텍스트 처리가 필요합니다.
트랜잭션은 일반적으로 작업 컨텍스트로 시작해야 합니다:
tx, err := db.BeginTx(ctx, nil)
if err != nil {
return err
}
defer tx.Rollback()
그런 다음 트랜잭션 작업에 동일한 컨텍스트를 사용하십시오:
if _, err := tx.ExecContext(ctx, query, args...); err != nil {
return err
}
if err := tx.Commit(); err != nil {
return err
}
트랜잭션 주변의 타임아웃에 주의하십시오. 컨텍스트가 Commit 전에 취소되면 트랜잭션이 롤백될 수 있습니다. 이것이 원하는 것일 수 있지만, 의도적이어야 합니다.
긴 트랜잭션의 경우, 더 나은 답변은 보통 더 긴 타임아웃이 아니라, 단위당 더 적은 작업을 수행하는 더 짧은 트랜잭션입니다.
백그라운드 워커와 컨텍스트
백그라운드 워커는 자신의 수명을 나타내는 컨텍스트를 받아야 합니다.
예시:
type Worker struct {
logger *slog.Logger
}
func (w *Worker) Run(ctx context.Context) error {
ticker := time.NewTicker(10 * time.Second)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return ctx.Err()
case <-ticker.C:
if err := w.doOnce(ctx); err != nil {
w.logger.Error("worker iteration failed", "err", err)
}
}
}
}
이 워커는 컨텍스트가 취소될 때 깔끔하게 멈추고, 그 타이커는 defer ticker.Stop()을 통해 적절히 정리됩니다. main에서는 OS 신호에 연결된 루트 컨텍스트를 생성할 것입니다:
func main() {
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
worker := &Worker{logger: slog.Default()}
if err := worker.Run(ctx); err != nil && !errors.Is(err, context.Canceled) {
slog.Error("worker stopped", "err", err)
}
}
이는 컨텍스트의 올바른 사용법입니다: 이는 프로세스 작업의 수명을 설명하고, OS가 신호를 보내면 이 컨텍스트를 공유하는 고루틴의 전체 트리가 함께 멈춥니다.
컨텍스트 취소를 통한 고루틴 누출 방지
고루틴 누출은 고루틴이 더 이상 유용하지 않은 후 영원히 차단된 상태로 남아있을 때 발생합니다.
컨텍스트는 이를 방지하는 데 도움이 됩니다.
나쁜 예:
func StartWorker() {
go func() {
for {
doWork()
time.Sleep(time.Second)
}
}()
}
이 고루틴에는 종료 경로가 없습니다.
더 나은 예:
func StartWorker(ctx context.Context) {
go func() {
ticker := time.NewTicker(time.Second)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return
case <-ticker.C:
doWork()
}
}
}()
}
루프를 실행하는 고루틴은 거의 항상 취소 경로가 있어야 합니다.
이는 모든 고루틴이 직접 컨텍스트를 받아야 한다는 것을 의미하지는 않지만, 시스템은 이를 멈추는 명확한 방법을 가져야 합니다.
context.AfterFunc
context.AfterFunc는 컨텍스트가 취소된 후 함수를 실행합니다.
이는 정리, 작업 차단 해제, 또는 컨텍스트를 본질적으로 지원하지 않는 API 브리징에 유용할 수 있습니다.
예시:
func waitWithContext(ctx context.Context, ch <-chan struct{}) error {
stop := context.AfterFunc(ctx, func() {
// Wake up or clean up if needed.
})
defer stop()
select {
case <-ctx.Done():
return ctx.Err()
case <-ch:
return nil
}
}
AfterFunc를 신중하게 사용하십시오. 이는 취소가 발생했을 때 로직을 시작하므로, 제어 흐름을 따라가기 더 어렵게 만들 수 있습니다. 대부분의 애플리케이션 코드에서는 ctx.Done()에 대한 일반적인 select가 더 명확하고 추론하기 쉽습니다. AfterFunc는 컨텍스트 취소를 아직 컨텍스트를 받지 않는 API에 적응시켜야 할 때 가장 가치가 있습니다.
context.WithoutCancel
context.WithoutCancel은 부모가 취소되었을 때 취소되지 않는 컨텍스트를 생성합니다.
이는 유용하지만, 오용하기也容易합니다.
예시 사용 사례:
func Handler(audit *AuditLog) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
// Handle request...
_ = ctx
auditCtx := context.WithoutCancel(ctx)
go func() {
ctx, cancel := context.WithTimeout(auditCtx, 2*time.Second)
defer cancel()
_ = audit.Write(ctx, "request completed")
}()
}
}
아이디어는 요청 컨텍스트가 취소된 후에도 감사(gudit) 쓰기가 잠시 계속되어야 할 수 있다는 것입니다. 이는 드물고 의도적이어야 합니다. WithoutCancel을 취소 문제를 회피하는 방법으로 사용하지 마십시오. 하위 작업이 진정으로 부모 취소보다 더 오래 살아야 할 때만 사용하고, 항상 새로운 타임아웃을 추가하십시오. 취소를 무시하지만 마감 시간이 없는 컨텍스트는 쉽게 백그라운드 고루틴 누출을 생성할 수 있습니다.
컨텍스트 값, 올바르게 처리하기
컨텍스트 값은 API 경계를 가로지르는 요청 범위 데이터를 위한 것입니다.
좋은 예시:
- 요청 ID
- 추적 ID
- 인증된 사용자 ID
- 테넌트 ID
- 로캘(locale)
- 보안 주체(security principal)
- 상관 메타데이터(correlation metadata)
나쁜 예시:
- 데이터베이스 연결
- 숨겨진 의존성으로서의 로거
- 일반 제어 흐름을 위한 기능 플래그
- 선택적 함수 파라미터
- 구성(configuration)
- 서비스 클라이언트
유용한 규칙: 값이 요청의 정체성 또는 관찰성 컨텍스트의 일부라면, 컨텍스트에 속할 수 있습니다. 코드가 작업을 수행하는 데 필요한 의존성이라면 명시적으로 전달하십시오.
컨텍스트 값에 타입화된 키 사용
일반 문자열을 컨텍스트 키로 사용하지 마십시오.
나쁜 예:
ctx = context.WithValue(ctx, "userID", "123")
이는 다른 패키지와 충돌할 수 있습니다.
내보내지 않는 사용자 정의 키 타입을 사용하십시오:
type userIDKey struct{}
func WithUserID(ctx context.Context, userID string) context.Context {
return context.WithValue(ctx, userIDKey{}, userID)
}
func UserIDFromContext(ctx context.Context) (string, bool) {
userID, ok := ctx.Value(userIDKey{}).(string)
return userID, ok
}
이 패턴은 패키지 경계에서 타입 안전성을 제공하고, 다른 패키지와 키 충돌을 피하며, 타입화된 접근자 함수로 컨텍스트 API 표면을 깔끔하게 유지합니다.
선택적 파라미터에 컨텍스트 값 사용하지 마십시오
이는 나쁩니다:
ctx = context.WithValue(ctx, "pageSize", 100)
users, err := repo.ListUsers(ctx)
이는 함수 계약을 숨깁니다.
명시적 파라미터를 선호하십시오:
users, err := repo.ListUsers(ctx, ListUsersOptions{
PageSize: 100,
})
컨텍스트 값은 함수 인수를 대체해서는 안 됩니다. 숨겨진 입력은 코드를 이해하고, 테스트하고, 검토하기 어렵게 만듭니다 — 그리고 함수 서명을 읽는 사람은 그 파라미터가 아예 존재한다는 사실조차 알 수 없습니다.
로깅과 컨텍스트
컨텍스트와 함께 로깅하는 두 가지 일반적인 접근 방식이 있습니다. 여기서의 예시는 Go의 log/slog 패키지를 사용합니다. 프로덕션 서비스에서 slog를 사용한 구조화된 로깅에 대한 더 깊은 분석은 slog를 사용한 Go 구조화된 로깅을 참조하십시오.
접근 방식 1: 값 추출 및 로그 첨부
func LogRequest(ctx context.Context, logger *slog.Logger, msg string) {
if requestID, ok := RequestIDFromContext(ctx); ok {
logger = logger.With("request_id", requestID)
}
logger.Info(msg)
}
이는 로거를 적절한 의존성으로 명시적으로 유지하고, 컨텍스트는 오직 legitimately API 경계를 가로지르는 요청 범위 값에만 사용합니다.
접근 방식 2: 컨텍스트에 로거 저장
일부 코드베이스는 컨텍스트에 로거를 저장합니다.
이는 편리할 수 있지만, 기본값으로 추천하지 않습니다. 이는 컨텍스트를 의존성 컨테이너로 만듭니다.
제 선호도:
- 로거 의존성을 명시적으로 전달하십시오.
- 추적 ID 및 요청 ID를 컨텍스트에 저장하십시오.
- 경계 또는 미들웨어에서 로그에 이러한 값을 추가하십시오.
이는 의존성을 가시적으로 유지합니다.
컨텍스트와 추적(Tracing)
추적은 컨텍스트 값의 가장 강력한 사용 사례 중 하나이며, 진정한 적합성(good fit)입니다. OpenTelemetry 및 유사한 시스템은 컨텍스트를 사용하여 함수 호출 및 프로세스 경계를 가로질러 추적 스팬(trace spans)을 전파합니다. 왜냐하면 추적 데이터는 컨텍스트가 전달하도록 설계된 바로 그 종류의 요청 범위 메타데이터이기 때문입니다.
일반적인 패턴은 다음과 같습니다:
func (s *Service) DoWork(ctx context.Context) error {
ctx, span := s.tracer.Start(ctx, "Service.DoWork")
defer span.End()
return s.repo.Query(ctx)
}
컨텍스트는 활성 추적 스팬을 운반하고, 리포지토리는 이를 기반으로 하위 스팬을 생성할 수 있습니다. 각 계층은 tracer 객체의 명시적인 전달 없이 자신의 스팬을 추가합니다. 컨텍스트가 호출 트리 전체에서 투명하게 그 작업을 수행합니다.
컨텍스트와 에러 처리
작업이 컨텍스트 취소로 인해 멈출 때, 그 정보를 보존하십시오. 여기서의 패턴은 Go 에러 처리 아키텍처에서 다루는 더 넓은 에러 설계 전략을 보완합니다.
예시:
err := svc.DoWork(ctx)
if err != nil {
if errors.Is(err, context.Canceled) {
// Client canceled or caller stopped the work.
return err
}
if errors.Is(err, context.DeadlineExceeded) {
// Timeout.
return err
}
return err
}
그들을 숨기는 방식으로 컨텍스트 에러를 맹목적으로 감싸지(wrap) 마십시오.
%w로 감싸는 것은 errors.Is를 보존하므로, 호출자는 여전히 취소나 타임아웃을 감지할 수 있습니다:
if err != nil {
return fmt.Errorf("query user: %w", err)
}
에러를 완전히 대체하는 것은 그 정보를 폐기하고, 특정 컨텍스트 에러 타입을 확인하는 호출자를 깨뜨립니다:
if err != nil {
return errors.New("query user failed")
}
컨텍스트 에러를 HTTP 응답으로 매핑
컨텍스트 에러는 종종 다른 HTTP 결과로 매핑됩니다.
예시:
func writeError(w http.ResponseWriter, err error) {
switch {
case errors.Is(err, context.Canceled):
// The client likely went away.
// Some systems log this as a client closed request.
return
case errors.Is(err, context.DeadlineExceeded):
http.Error(w, "request timed out", http.StatusGatewayTimeout)
return
default:
http.Error(w, "internal server error", http.StatusInternalServerError)
return
}
}
클라이언트 취소를 애플리케이션 실패로 취급하지 마십시오. 사용자가 브라우저 탭을 닫았다면, 이는 당신의 서비스가 잘못 행동한 것이 아니며, 이를 에러로 로깅하는 것은 신호 없이 소음만 추가합니다.
미들웨어에서의 컨텍스트
HTTP 미들웨어는 요청 범위 값을 추가하는 흔한 곳입니다.
예시 요청 ID 미들웨어:
type requestIDKey struct{}
func WithRequestID(ctx context.Context, requestID string) context.Context {
return context.WithValue(ctx, requestIDKey{}, requestID)
}
func RequestIDFromContext(ctx context.Context) (string, bool) {
requestID, ok := ctx.Value(requestIDKey{}).(string)
return requestID, ok
}
func RequestIDMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
requestID := r.Header.Get("X-Request-ID")
if requestID == "" {
requestID = newRequestID()
}
ctx := WithRequestID(r.Context(), requestID)
next.ServeHTTP(w, r.WithContext(ctx))
})
}
이는 컨텍스트의 좋은 사용법입니다. 요청 ID는 요청에 속하며, 전체 호출 체인을 통해 여행해야 하며, 각 계층에서 로그 및 추적에 첨부하는 것은 컨텍스트 값이 지원하도록 설계된 교차 관찰성(cross-cutting observability) 우려의 정확한 예입니다.
테스트에서의 컨텍스트
테스트에서는 맹목적으로 context.Background()를 사용하지 마십시오.
작업이 테스트 수명에 속할 때 t.Context()를 선호하십시오:
func TestService(t *testing.T) {
ctx := t.Context()
err := service.DoWork(ctx)
if err != nil {
t.Fatal(err)
}
}
타임아웃 동작의 경우, 타임아웃이 작고 의미 있는 경우에만 실제 타임아웃으로 테스트하십시오.
동시 및 시간 의존 코드의 경우, testing/synctest 사용을 고려하십시오. synctest를 사용한 Go 동시 코드 테스트는 이 도구를 심층적으로 다룹니다:
func TestTimeout(t *testing.T) {
synctest.Test(t, func(t *testing.T) {
ctx, cancel := context.WithTimeout(t.Context(), 30*time.Second)
defer cancel()
time.Sleep(30 * time.Second)
if !errors.Is(ctx.Err(), context.DeadlineExceeded) {
t.Fatalf("got %v, want deadline exceeded", ctx.Err())
}
})
}
이는 실제 시간을 기다리지 않고 실제 타임아웃 값을 테스트할 수 있게 해줍니다.
컨텍스트와 errgroup
함께 취소되어야 하는 고루틴 그룹의 경우, errgroup은 종종 좋은 선택입니다.
예시:
func FetchAll(ctx context.Context, ids []string, client *Client) error {
g, ctx := errgroup.WithContext(ctx)
for _, id := range ids {
id := id
g.Go(func() error {
_, err := client.Fetch(ctx, id)
return err
})
}
return g.Wait()
}
하나의 고루틴이 에러를 반환하면, 그룹 컨텍스트가 취소되고 ctx.Done()을 존중하는 다른 고루틴은 조기에 멈출 수 있습니다. 이는 여러 고루틴, 채널, 그리고 취소 경로를 수동으로 관리하는 것보다 훨씬 깔끔합니다. 여기서 핵심 구절은 “컨텍스트를 존중한다"입니다. errgroup은 ctx.Done()을 무시하는 작업을 멈출 수 없습니다.
Graceful Shutdown(우아한 종료)
컨텍스트는 graceful shutdown의 핵심입니다.
일반적인 서버 설정은 다음과 같습니다:
- OS 신호로 취소되는 루트 컨텍스트
- HTTP 서버
- 백그라운드 워커
- 종료 타임아웃
- 정리 로직
예시:
func main() {
root, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
server := &http.Server{
Addr: ":8080",
Handler: routes(),
}
go func() {
<-root.Done()
shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := server.Shutdown(shutdownCtx); err != nil {
slog.Error("server shutdown failed", "err", err)
}
}()
if err := server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
slog.Error("server failed", "err", err)
os.Exit(1)
}
}
종료 컨텍스트가 루트 컨텍스트와 동일하지 않다는 것에 주목하십시오. OS 신호가 도착할 때 루트는 이미 취소됩니다. 별도의 타임아웃 컨텍스트는 강제 종료 전에 인플라이트(in-flight) 요청을 배수(drain)할 수 있는 유한한 시간을 종료 프로세스에 제공합니다. 이는 미세하지만 중요한 구별이며, 이것이 바로 graceful shutdown이 실제로 작동하는 이유입니다.
흔한 반패턴(Anti-patterns)
반패턴 1: 컨텍스트를 의존성 컨테이너로 사용
나쁜 예:
ctx = context.WithValue(ctx, "db", db)
ctx = context.WithValue(ctx, "logger", logger)
ctx = context.WithValue(ctx, "config", cfg)
의존성을 명시적으로 전달하십시오.
반패턴 2: 비즈니스 로직 내부에서 context.Background 생성
나쁜 예:
func (s *Service) DoWork(ctx context.Context) error {
return s.repo.Save(context.Background())
}
이는 취소 전파를 끊습니다.
반패턴 3: cancel 잊기
나쁜 예:
ctx, _ := context.WithTimeout(parent, time.Second)
좋은 예:
ctx, cancel := context.WithTimeout(parent, time.Second)
defer cancel()
반패턴 4: 컨텍스트에 선택적 파라미터 넣기
나쁜 예:
ctx = context.WithValue(ctx, "includeDeleted", true)
명시적인 옵션 구조체를 사용하십시오.
반패턴 5: 순수 코드로 컨텍스트 너무 깊게 전달
나쁜 예:
func Add(ctx context.Context, a, b int) int {
return a + b
}
장시간 실행되거나 취소 가능하지 않는 한, 순수 계산에는 컨텍스트가 필요하지 않습니다.
반패턴 6: 루프에서 취소 무시
나쁜 예:
for item := range items {
process(item)
}
더 나은 예:
for item := range items {
select {
case <-ctx.Done():
return ctx.Err()
default:
}
if err := process(ctx, item); err != nil {
return err
}
}
반패턴 7: 컨텍스트 에러 삼키기
나쁜 예:
if err != nil {
return errors.New("operation failed")
}
좋은 예:
if err != nil {
return fmt.Errorf("operation failed: %w", err)
}
취소 및 마감 시간 에러를 보존하십시오.
실용적인 컨텍스트 체크리스트
Go 백엔드 코드에 이 체크리스트를 사용하십시오.
함수 서명
- 컨텍스트는 첫 번째 파라미터입니다.
- 컨텍스트는 장수하는(long-lived) 구조체에 저장되지 않습니다.
- 필요하지 않는 한 컨텍스트는 순수 헬퍼 함수에 전달되지 않습니다.
- nil 컨텍스트는 결코 사용되지 않습니다.
취소
- 장시간 실행되는 루프는
ctx.Done()을 확인합니다. - 고루틴에는 종료 경로가 있습니다.
- 워커 수명은 부모 컨텍스트에 연결됩니다.
- 컨텍스트 취소는 다운스트림 호출로 전파됩니다.
타임아웃
- 외부 요청 타임아웃은 경계에서 설정됩니다.
- 하위 작업 타임아웃은 외부 예산보다 작습니다.
- Cancel 함수는 항상 호출됩니다.
- 타임아웃은 각 계층에서 맹목적으로 쌓이지 않습니다.
값
- 컨텍스트 값은 요청 범위입니다.
- 키는 일반 문자열이 아닌 사용자 정의 타입을 사용합니다.
- 의존성은 컨텍스트에 저장되지 않습니다.
- 선택적 파라미터는 컨텍스트에 저장되지 않습니다.
에러
context.Canceled및context.DeadlineExceeded가 보존됩니다.- 컨텍스트 에러는 API 경계에서 올바르게 매핑됩니다.
- 원인 인지 취소는 이유가 중요한 경우에만 사용됩니다.
테스트
- 테스트는 적절한 곳에서
t.Context()를 사용합니다. - 타임아웃 테스트는 느린 실제 sleep을 피합니다.
- 동시 타임아웃 동작은 유용할 때
testing/synctest로 테스트됩니다. - 고루틴 누출은 종료 경로가 존재하는지 확인하여 검사됩니다.
Go 코드베이스에서 컨텍스트 사용 감사하기
다음 패턴을 검색하십시오:
grep -R "context.Background()" .
grep -R "context.TODO()" .
grep -R "WithTimeout" .
grep -R "WithCancel" .
grep -R "WithValue" .
grep -R "type .* struct" .
그리고 물어보십시오:
context.Background()가 최상위 경계에서만 사용되고 있는가?- Cancel 함수가 항상 호출되고 있는가?
- 타임아웃이 합리적인 경계에 배치되어 있는가?
- 컨텍스트 값이 진정으로 요청 범위인가?
- 의존성이 컨텍스트 값에 숨겨져 있는가?
- 고루틴이 멈출 수 있는가?
- 컨텍스트 에러가 보존되고 있는가?
이는 좋은 코드 리뷰 습관입니다. 왜냐하면 많은 컨텍스트 버그는 구문 버그가 아니라, 취소, 부하 또는 종료 조건에서만 나타나는 수명 버그이기 때문입니다.
제 주관이 뚜렷한 규칙들
이 규칙들은 지루하지만, 작동합니다.
규칙 1: 컨텍스트는 제어 흐름입니다
취소, 마감 시간, 요청 메타데이터 제어를 위해 컨텍스트를 사용하십시오.
의존성을 몰래 전달(smuggle)하는 데 사용하지 마십시오.
규칙 2: 호출자가 예산을 소유합니다
함수는 일반적으로 수신된 컨텍스트를 존중해야 합니다.
하위 작업이 특정 더 작은 예산이 필요할 때만 더 짧은 하위 타임아웃을 생성하십시오.
규칙 3: Background는 가장자리에 속합니다
main, 테스트, 최상위 설정에서 context.Background()를 사용하십시오.
취소를 탈출하기 위해 서비스 및 리포지토리 메서드 내부에서 사용하지 마십시오.
규칙 4: 값들은 지루해야 합니다
요청 ID, 추적 ID, 사용자 ID, 테넌트 ID는 컨텍스트에 속합니다. 데이터베이스 연결, 로거, 구성 구조체, 서비스 클라이언트는 그렇지 않습니다 — 그것들은 의존성이며 명시적으로 전달되어야 합니다.
규칙 5: 모든 고루틴은 수명이 필요합니다
고루틴이 시작되면, 어떻게 멈추는지 정확히 알아야 합니다. 컨텍스트가 종종 올바른 답변이지만, 컨텍스트가 아니라면 채널, 동기화 원시 자료(sync primitive), 또는 명시적인 신호와 같은 다른 명확한 메커니즘이 있어야 합니다.
최종 생각
context.Context는 API가 크기 때문에 복잡한 것이 아닙니다 — API는 작습니다. 그것이 수명(lifetime)을 나타내기 때문에 복잡합니다. 그리고 수명은 아키텍처입니다. 컨텍스트가 어디로 흐르고, 어디서 파생되고, 어디서 멈추는지에 대한 모든 결정은 당신의 서비스가 실패, 부하, 종료를 어떻게 처리하는지에 대한 결정입니다.
잘 사용되는 컨텍스트는 Go 서비스를 취소하기 쉽고, 종료하기 쉽고, 관찰하기 쉬우며, 고루틴을 누출할 가능성이 적게 만듭니다. 잘못 사용되는 컨텍스트는 의존성을 숨기고, 마감 시간을 폐기하며,压力下에서 코드를 추론하기 어렵게 만듭니다.
실용적인 결론은 간단합니다:
Pass context down.
Do not store it.
Do not replace explicit parameters with values.
Respect cancellation.
Use timeouts at boundaries.
Always call cancel.
이것이 바로 올바르게 처리된 Go 컨텍스트입니다.
이 기사는 프로덕션 시스템의 코드 구조, 데이터 액세스, 통합 패턴 및 테스트 아키텍처를 다루는 프로덕션에서의 애플리케이션 아키텍처 클러스터의 일부입니다.
