Enterprise Go는 Go 서비스를 팀 단위로 오래 운영하기 위한 실무 규칙 모음이다. 프레임워크나 라이브러리 선택보다 책임 분리, 경계 통제, 팀 표준을 먼저 정한다는 관점으로 프로젝트 구조부터 빌드 자동화까지 다룬다.

핵심

  • 구조의 핵심은 폴더 트리가 아니라 책임 분리다. main은 얇게 두고, 조립은 internal/app에 모으고, 공개 API가 아니면 internal에 둔다. main은 app.Run()만 부르고, internal/app이 설정 로딩, 의존성 조립, 프로세스 시작과 종료를 맡는다. main에서 조립까지 다 하면 테스트할 수 있는 진입점이 사라진다. pkg는 외부 공개가 필요할 때만 연다. 너무 일찍 열면 API 호환성 부담이 생긴다. 처음에는 main.go 하나로 시작해 코드가 커지면 cmd와 internal로, 바이너리가 늘면 cmd/{api,worker,admin}으로 나눈다.
  • HTTP 서버는 운영 규칙으로 견고해진다. 미들웨어는 Recover → RequestID → Logger → CORS → Auth → Handler 순서로 두고, 도메인 에러를 HTTP 상태 코드로 매핑하고, 종료할 때는 새 요청을 막은 뒤 진행 중인 요청에 제한 시간을 준다. 순서가 깨지면 추적할 수 없는 로그, 놓친 패닉, 기록되지 않은 인증 실패가 생긴다. 종료 신호는 signal.NotifyContext로 받고, 컴포넌트가 여럿이면 run.Group 패턴으로 종료 순서를 한곳에서 관리한다. readiness와 liveness를 나누고, 요청 타임아웃 기본값을 명시하며, 패닉에도 표준 에러 응답을 내고, access log에는 request id를 꼭 남긴다.
  • context.Context는 함수 첫 인자로 받고 구조체 필드에 저장하지 않는다. context.Background()는 진입점에서만 쓰고, 상위 타임아웃이 하위 타임아웃을 감싸게 설계한다. 모든 저장소와 외부 호출은 받은 ctx를 그대로 넘겨 취소를 전파한다. Context가 나르는 것은 요청 범위 값, 타임아웃과 데드라인, 취소 신호다. 타임아웃은 예를 들어 HTTP 전체 30초, 유스케이스 10초, DB 3초, 외부 API 5초처럼 겹쳐 둔다. WithValue에는 request id, trace id, 인증 주체만 담고 DB 핸들이나 큰 객체, 옵션 묶음은 넣지 않는다. 새 고루틴에서 parent context를 빠뜨리거나 라이브러리 안에서 임의로 Background()를 만드는 실수가 흔하다.
  • 동시성은 Java 개념에 대응시켜 고른다. 스레드 풀은 Worker Pool과 Channel, CompletableFuture는 errgroup, synchronized는 sync.Mutex, BlockingQueue는 Channel이고, 경쟁 상태는 -race 플래그로 잡는다. Enterprise Go 시리즈 #4: Goroutine과 Channel 실전 활용
  • DB 연동의 핵심은 ORM 선택이 아니라 트랜잭션 경계 통제다. WithTx 래퍼 한곳에서 성공 시 커밋, 에러 시 롤백을 보장한다. Spring의 @Transactional과 달리 Go에서는 경계를 코드에 드러내야 한다. Repository는 트랜잭션을 만들지 않고 호출자가 준 ctx에서 핸들을 얻어 실행하며, 긴 트랜잭션에 외부 API 호출을 넣지 않는다. 커넥션 풀은 MaxOpenConns를 DB 여유와 동시성에 맞춰 제한하고, MaxIdleConns는 그 30~50%, ConnMaxLifetime은 LB나 방화벽 타임아웃보다 짧게 두고 시작해 지표를 보며 맞춘다.
  • 외부 호출에는 Rate Limit → Circuit Breaker → Retry → Timeout 순서로 패턴을 감싼다. Timeout은 모든 외부 호출에 필수이고, Retry는 5xx와 네트워크 오류에만 건다. Enterprise Go 시리즈 #6: Resilient한 외부 통신
  • 테스트는 도구보다 계층 분리가 먼저다. 유닛 테스트는 빠르고 결정적으로, 통합 테스트는 실제 인프라를 붙여 계약을 검증하고, 라벨로 따로 실행한다. mock은 gomock이나 손으로 짠 fake, 통합은 testcontainers-go, BDD가 필요하면 ginkgo와 gomega를 쓴다. PR에는 유닛과 핵심 통합만, main이나 nightly에는 전체 통합을 돌리고(ginkgo -r --label-filter='integration'), PR 단계 테스트는 10분 안에 끝나게 유지한다. 신규 기능에는 유닛과 통합 테스트를 하나씩은 두고, mock을 과하게 써서 구현에 묶이지 않게 한다.
  • 관측성은 Logs(zap → Loki), Metrics(Prometheus → Grafana), Traces(OpenTelemetry → Tempo), Profile(pprof)로 나눠 각각 디버깅, 알림, 병목 분석, 성능 최적화에 쓴다. Enterprise Go 시리즈 #8: Observability와 Debugging
  • Makefile의 본질은 자동화가 아니라 표준화다. build, test, lint, generate, clean을 두고 개발자와 CI가 같은 명령을 쓰게 한다. test 타깃은 예를 들어 go test -race -cover ./...이다. 모노레포에서는 build-api, build-worker처럼 서비스별 타깃과 변경된 서비스만 빌드하는 타깃을 두고, help 타깃으로 문서를 대신한다. 환경별 분기를 과하게 넣거나 로컬에서만 되는 명령을 넣지 않고, 타깃은 .PHONY로 선언한다.

코드와 함께 더 깊이 다룬 원문:

관련