Community코딩 & 개발github.com

Go 서비스 작업

Go 백엔드 서비스에서 컨텍스트 전파, 에러 래핑, 트랜잭션 경계, 테넌시 범위, 테이블 기반 테스트를 다루며 핸들러, 서비스 또는 리포지토리를 구현, 확장 또는 디버깅합니다. Go 서버 코드를 작성하거나 변경할 때, 엔드포인트나 gRPC 메서드를 추가할 때, 리포지토리 쿼리를 건드릴 때, 또는 Go 서비스에서 패닉, 누수, 불안정한 테스트를 진단할 때 사용합니다.

Go 서비스 작업란 무엇인가요?

이 스킬은 Go로 작성된 백엔드 서비스에서 일관된 코딩 패턴과 모범 사례를 적용하여 동시성과 멀티 테넌시 환경에서도 코드의 정확성과 유지보수성을 보장합니다. **주요 내용**으로는 컨텍스트 전파(ctx를 첫 번째 파라미터로 전달하고, 구조체에 저장 금지), 에러 래핑(%w 사용, 함수명 대신 식별자 추가), 트랜잭션 경계(서비스 계층에서 트랜잭션 열기, defer tx.Rollback() 사용), 테넌시(코드 수준에서 테넌트 식별자 강제, 모든 리포지토리 쿼리에 조건 포함), 고루틴 수명 관리(errgroup 사용, 명시적 종료 조건), 그리고 테이블 기반 테스트(동작별 테스트 케이스, 타임아웃 전달, -race 플래그 사용)를 포함합니다. 이 스킬은 Go 1.21+ 환경에서 특히 유용하며, handler → service → repository 계층을 명확히 분리하고, 공유 패키지 내에서 일관된 패턴을 우선시합니다. 사용자는 코드 변경 전에 go.mod의 Go 버전을 확인하고, 가장 좁은 범위의 테스트를 먼저 실행한 후 golangci-lint를 통해 최종 점검을 권장합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-go-service

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Go 서비스 작업은(는) 무엇을 하나요?

동시성과 멀티 테넌시 환경에서 계층화된 Go 서비스를 올바르게 유지하는 규칙입니다. 먼저 주변 패키지를 읽으십시오 — 여기 있는 규칙보다 일관되게 적용된 로컬 패턴이 우선합니다.

코드 작성 전

도구 체인을 확인하세요. go.mod는 사용 가능한 표준 라이브러리와 언어 기능을 결정하며, 동일한 워크스페이스에 있는 서비스라도 다른 버전을 사용하는 경우가 많습니다. 루프 변수 캡처는 Go 1.22 미만에서는 실제 버그이고, 그 이상에서는 문제가 되지 않습니다. errors.Join, slices, maps는 Go 1.21이 필요합니다. 최신 버전을 가정하지 말고 버전을 확인하세요.

그런 다음 변경하려는 결정을 소유한 계층을 찾으십시오. 핸들러는 전송(transport)을 도메인(domain)으로 변환하며 그 외에는 아무것도 하지 않습니다. 서비스가 결정을 보유합니다. 리포지토리가 쿼리를 보유합니다. 핸들러에서 추가된 유효성 검사는 서비스의 다른 모든 호출자에게 보이지 않습니다.

컨텍스트

컨텍스트는 요청에 속하며 요청과 함께 사라집니다.

  • ctx를 첫 번째 파라미터로 전달하고, 데이터베이스 호출까지 계속 전달하세요. 컨텍스트를 받지 않는 함수는 취소될 수 없고 데드라인을 전달할 수 없습니다.
  • context.Context를 구조체 필드에 저장하지 마세요.
  • 요청 컨텍스트를 핸들러보다 오래 살아있는 고루틴에 전달하지 마세요. 분리된 백그라운드 작업에는 자체 타임아웃이 있는 자체 컨텍스트가 필요하며, 핸들러가 반환되기 전에 필요한 값을 명시적으로 복사해야 합니다.
  • 트랜잭션, 연결, 요청 범위의 데이터베이스 접근자 등 요청에서 파생된 모든 핸들에도 동일하게 적용됩니다. 핸들러가 반환된 후에 이를 사용하는 것은 좀 더 친절한 에러 메시지가 있는 use-after-free입니다.

에러

  • %w로 래핑하고 호출자가 이미 알 수 없는 것을 추가하세요: 식별자, 작업. fmt.Errorf("load order %d: %w", id, err). 함수 이름을 접두사로 붙이지 마세요; 그런 스택은 잡음으로 읽힙니다.
  • errors.Is와 errors.As로 비교하세요. 직접 ==를 사용하면 누군가 래핑했을 때 깨집니다.
  • 정확히 한 곳, 핸들러 경계에서 전송 상태로 변환하세요. HTTP 코드를 반환하는 리포지토리는 두 계층을 누출한 것입니다.
  • sql.ErrNoRows는 도메인 결과이지 실패가 아닙니다. 리포지토리 경계에서 도메인의 "찾을 수 없음"으로 매핑하여 서비스가 database/sql을 임포트하지 않도록 하세요.
  • 컴파일러를 만족시키기 위해 에러를 버리지 마세요. 진정으로 무시할 수 있는 경우라면 _에 할당하고 이유를 주석으로 남기세요.

트랜잭션

불변성을 소유한 계층(보통 서비스, 절대 리포지토리)에서 트랜잭션을 여세요. 자체 트랜잭션을 여는 리포지토리는 더 큰 트랜잭션에 포함될 수 없기 때문입니다. 트랜잭션 핸들을 아래로 전달하세요.

모든 경로(패닉 포함)에서 커밋과 롤백을 수행하세요. 성공적인 커밋 후의 롤백은 해가 없어야 합니다; 이것이 defer tx.Rollback()을 안전하게 만드는 이유입니다.

트랜잭션과 원자적으로 유지될 필요가 없는 I/O를 트랜잭션 내에서 수행하지 마세요. 열린 트랜잭션 내에서 결제 제공자에게 HTTP 호출을 하면 다른 사람의 장애 시간 동안 데이터베이스 잠금을 유지합니다.

테넌시

서비스가 멀티 테넌트인 경우, 테넌트 식별자는 데이터베이스가 아닌 코드에서 강제됩니다. 모든 리포지토리 쿼리(읽기 및 쓰기)는 테넌트 조건을 포함합니다. 기본 키로만 필터링하는 쿼리는 다른 테넌트의 행을 기꺼이 반환합니다. 코드베이스가 이미 사용하는 요청 컨텍스트 접근자에서 식별자를 파생시키고, 어떤 접근자가 올바른지 확인하세요: 하위 테넌트를 대신하여 작동하는 서비스는 일반적으로 두 개의 접근자를 가지며, 명백한 것이 종종 잘못된 것입니다.

고루틴

모든 고루틴에는 알려진 수명과 알려진 소유자가 필요합니다. go를 작성하기 전에 다음 질문에 답하세요: 누가 그것을 기다리는가, 어떻게 멈추는가, 그리고 에러는 어디로 가는가? 에러가 버려진 고루틴은 침묵의 실패입니다.

호출자가 기다리는 경우 errgroup을 사용하세요. 적합하지 않은 경우 명시적인 sync.WaitGroup과 수집된 에러 채널을 사용하세요. 요청 처리에서 맨 go f()는 거의 항상 결함입니다.

테스트

테이블 기반, 케이스당 하나의 t.Run, 입력이 아닌 동작으로 이름을 지정하세요. 각 케이스는 입력, 기대값, 그리고 그 외에는 아무것도 명시합니다. 모든 케이스가 공유하는 설정은 테이블 위에 속합니다.

실행 시 항상 타임아웃을 전달하세요:

go test -count=1 -timeout 60s ./...

-count=1은 결과 캐시를 비활성화합니다. 그렇지 않으면 방금 변경한 코드에 대해 통과를 보고합니다. 타임아웃은 보이는 것보다 중요합니다: 타임아웃이 없는 교착 상태 테스트는 머신이 멈출 때까지 메모리를 소비합니다.

패키지의 내보낸 동작을 테스트하세요. 내보내지 않은 내부를 건드리는 테스트는 구현을 고정시키고 모든 정직한 리팩터링에서 실패합니다.

테스트가 불안정할 때, 대부분의 경우 실제 경합을 보고하는 것입니다. 그렇지 않다고 결론 내리기 전에 -race 플래그로 실행하고, 절대 sleep을 추가하여 고치지 마세요.

완료 전에

변경 사항을 다루는 가장 좁은 테스트를 실행한 다음, 공유 계약이 이동했다면 범위를 넓히세요. 서비스에서 golangci-lint run을 실행하세요. 종료 코드를 삼킬 수 있는 make 타겟 대신 말입니다. 테스트를 약화시키는 대신 출력과 함께 실패를 보고하세요.

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-api

Design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-python

Write and debug Python with attention to the traps that produce silent wrong behaviour — mutable defaults, late-binding closures, shallow copies, swallowed exceptions — plus typing, environment and packaging with uv or venv, and pytest structure. Use when writing a Python script, service or library, setting up a Python project, or debugging behaviour that looks impossible.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

sk-system-design

Design or evaluate a distributed system from its constraints — service boundaries, synchronous versus event-driven communication, consistency, failure behaviour and capacity — and state the trade-off each choice buys. Use when splitting or merging services, choosing between a call and an event, deciding where data lives, reviewing an architecture proposal, or answering a system design question.

관련 스킬