@wooojin/forgen 0.4.7 → 0.4.9

package/assets/dev-guide/be/principles/go.md

@@ -0,0 +1,469 @@
+---
+title: Go 원칙
+version: 2026-05-18
+sources:
+  - sources/go-runtime/
+---
+
+# Go 원칙
+
+> [공통 원칙](./common.md)을 먼저 따르고, 아래는 Go 특화.
+
+## G0. 의사결정 우선순위
+
+1. **에러는 값** — panic은 진짜 예외(복구 불가)에만
+2. **context.Context 전파** — cancellation/deadline은 모든 I/O에 전달
+3. **goroutine 생명주기 명확화** — 시작한 곳이 종료 책임 보유
+4. **interface는 작게** — consumer 측 정의, 1~3 메서드
+5. **lint 자동화** — golangci-lint + go vet + staticcheck CI 필수
+
+---
+
+## G1. 에러는 값으로 반환
+
+근거: `sources/go-runtime/` (Effective Go, Rob Pike "Errors are values")
+
+**panic은 "진짜 프로그래밍 오류" 또는 "복구 불가 상황"에만. 일반 에러는 반환값.**
+
+### G1.1 에러 반환 패턴
+
+```go
+// 에러를 항상 마지막 반환값으로
+func fetchUser(ctx context.Context, id string) (*User, error) {
+    row := db.QueryRowContext(ctx, "SELECT * FROM users WHERE id = $1", id)
+    var user User
+    if err := row.Scan(&user.ID, &user.Name, &user.Email); err != nil {
+        if errors.Is(err, sql.ErrNoRows) {
+            return nil, ErrUserNotFound  // sentinel error
+        }
+        return nil, fmt.Errorf("fetchUser %s: %w", id, err)  // 래핑
+    }
+    return &user, nil
+}
+```
+
+### G1.2 에러 래핑과 검사
+
+```go
+// 에러 래핑: %w 사용 (Go 1.13+)
+return fmt.Errorf("processPayment: %w", ErrInsufficientFunds)
+
+// 에러 검사: errors.Is (sentinel), errors.As (타입)
+if errors.Is(err, ErrUserNotFound) {
+    return http.StatusNotFound, nil
+}
+var validationErr *ValidationError
+if errors.As(err, &validationErr) {
+    return http.StatusBadRequest, validationErr.Fields
+}
+```
+
+### G1.3 Sentinel Error 정의
+
+```go
+// 패키지 레벨 sentinel errors
+var (
+    ErrUserNotFound      = errors.New("user not found")
+    ErrInsufficientFunds = errors.New("insufficient funds")
+    ErrDuplicateEmail    = errors.New("duplicate email")
+)
+
+// 필드 정보가 필요한 구조체 에러
+type ValidationError struct {
+    Fields map[string]string
+}
+func (e *ValidationError) Error() string {
+    return fmt.Sprintf("validation failed: %v", e.Fields)
+}
+```
+
+### G1.4 panic 허용 기준
+
+```go
+// OK: 프로그래밍 오류 — nil 포인터, 인덱스 초과 등 (런타임 패닉)
+// OK: 초기화 실패 — 앱이 시작될 수 없는 상태
+func mustParseTemplate(s string) *template.Template {
+    t, err := template.New("").Parse(s)
+    if err != nil {
+        panic(fmt.Sprintf("failed to parse template: %v", err))  // 컴파일 타임 알아야 할 오류
+    }
+    return t
+}
+
+// NOT OK: 일반 런타임 에러 (DB 오류, 네트워크 오류, 검증 실패)
+```
+
+---
+
+## G2. context.Context 전파
+
+**모든 I/O 함수의 첫 번째 인자는 context.Context. cancellation/deadline이 반드시 전파되어야 한다.**
+
+### G2.1 함수 시그니처 규칙
+
+```go
+// WRONG: context 없는 DB 호출
+func (r *UserRepo) FindByID(id string) (*User, error) {
+    return r.db.QueryRow("SELECT ...", id).Scan(...)
+}
+
+// RIGHT: context 전파
+func (r *UserRepo) FindByID(ctx context.Context, id string) (*User, error) {
+    return r.db.QueryRowContext(ctx, "SELECT ...", id).Scan(...)
+}
+```
+
+### G2.2 context 값 사용 기준
+
+```go
+// context.Value: 요청 범위 메타데이터만 (request ID, auth user, traceID)
+// 비즈니스 로직 파라미터를 context에 넣지 마라
+
+// WRONG
+ctx = context.WithValue(ctx, "userID", userID)
+
+// RIGHT: 명시적 파라미터
+func processOrder(ctx context.Context, userID string, items []Item) error
+```
+
+### G2.3 context 취소 처리
+
+```go
+func longOperation(ctx context.Context) error {
+    for {
+        select {
+        case <-ctx.Done():
+            return ctx.Err()  // context.Canceled 또는 context.DeadlineExceeded
+        default:
+            // 작업 계속
+        }
+        // 또는 I/O 함수에 ctx 전달 시 자동 처리
+    }
+}
+```
+
+### G2.4 Timeout 설정
+
+```go
+// HTTP 핸들러: 요청 timeout
+ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
+defer cancel()  // 반드시 defer cancel() — goroutine/timer 누수 방지
+
+result, err := svc.Process(ctx, input)
+```
+
+---
+
+## G3. Goroutine 생명주기
+
+**goroutine을 시작한 쪽이 종료 책임을 진다. goroutine leak은 메모리 누수와 동일하다.**
+
+### G3.1 goroutine leak 패턴과 픽스
+
+```go
+// WRONG: 종료 조건 없는 goroutine
+func start() {
+    go func() {
+        for {
+            processMessage()  // 영원히 실행
+        }
+    }()
+}
+
+// RIGHT: context 기반 종료
+func start(ctx context.Context) {
+    go func() {
+        for {
+            select {
+            case <-ctx.Done():
+                return
+            default:
+                processMessage(ctx)
+            }
+        }
+    }()
+}
+```
+
+### G3.2 WaitGroup으로 완료 대기
+
+```go
+func processAll(ctx context.Context, items []Item) error {
+    var wg sync.WaitGroup
+    errCh := make(chan error, len(items))  // 버퍼드 채널 (모든 에러 수집)
+
+    for _, item := range items {
+        wg.Add(1)
+        go func(item Item) {
+            defer wg.Done()
+            if err := process(ctx, item); err != nil {
+                errCh <- err
+            }
+        }(item)  // 루프 변수 캡처 — Go 1.22부터 자동이지만 명시적 인자가 명확
+    }
+
+    wg.Wait()
+    close(errCh)
+
+    for err := range errCh {
+        return err  // 첫 번째 에러 반환 (또는 multierr.Combine)
+    }
+    return nil
+}
+```
+
+### G3.3 errgroup 패턴
+
+```go
+import "golang.org/x/sync/errgroup"
+
+func fanOut(ctx context.Context) error {
+    g, ctx := errgroup.WithContext(ctx)  // 한 goroutine 실패 시 나머지 ctx 취소
+
+    g.Go(func() error { return fetchUsers(ctx) })
+    g.Go(func() error { return fetchOrders(ctx) })
+    g.Go(func() error { return fetchInventory(ctx) })
+
+    return g.Wait()  // 모든 goroutine 완료 대기, 첫 번째 non-nil 에러 반환
+}
+```
+
+---
+
+## G4. Channel 단일 책임
+
+**channel은 한 가지 목적으로만. close는 항상 sender가.**
+
+### G4.1 channel 패턴
+
+```go
+// 생산자-소비자: sender가 close
+func producer(ctx context.Context) <-chan Item {
+    ch := make(chan Item)
+    go func() {
+        defer close(ch)  // sender가 close
+        for _, item := range items {
+            select {
+            case ch <- item:
+            case <-ctx.Done():
+                return
+            }
+        }
+    }()
+    return ch
+}
+
+func consumer(ctx context.Context, ch <-chan Item) {
+    for item := range ch {  // close 시 자동 종료
+        process(ctx, item)
+    }
+}
+```
+
+### G4.2 channel vs sync.Mutex 선택 기준
+
+```
+goroutine 간 데이터 전달 → channel
+공유 상태 보호 (캐시, 카운터) → sync.Mutex / sync.RWMutex
+단발성 신호 (완료 알림) → chan struct{} (또는 context)
+```
+
+---
+
+## G5. Interface는 작게
+
+**interface는 큰 것을 정의하지 마라. consumer 측에서, 1~3 메서드로.**
+
+### G5.1 인터페이스 크기 원칙
+
+```go
+// WRONG: 모든 것을 포함한 큰 인터페이스
+type UserRepository interface {
+    Create(ctx context.Context, user *User) error
+    Update(ctx context.Context, user *User) error
+    Delete(ctx context.Context, id string) error
+    FindByID(ctx context.Context, id string) (*User, error)
+    FindByEmail(ctx context.Context, email string) (*User, error)
+    List(ctx context.Context, filter UserFilter) ([]*User, error)
+    Count(ctx context.Context, filter UserFilter) (int, error)
+}
+
+// RIGHT: 사용 측이 필요한 것만
+type UserFinder interface {
+    FindByID(ctx context.Context, id string) (*User, error)
+}
+
+type UserCreator interface {
+    Create(ctx context.Context, user *User) error
+}
+
+// UserService는 필요한 인터페이스만 조합
+type UserService struct {
+    finder  UserFinder
+    creator UserCreator
+}
+```
+
+### G5.2 Consumer 측 정의
+
+```go
+// WRONG: 구현 패키지에서 인터페이스 정의 (Go 안티패턴)
+// user/repository.go
+type Repository interface { ... }  // 구현 패키지가 자기 인터페이스를 선언
+
+// RIGHT: consumer 패키지에서 필요한 것만 정의
+// order/service.go — order 서비스가 필요한 user 기능만 정의
+type userProvider interface {
+    FindByID(ctx context.Context, id string) (*User, error)
+}
+```
+
+### G5.3 표준 라이브러리 인터페이스 우선 활용
+
+```go
+io.Reader, io.Writer, io.Closer — 스트림
+fmt.Stringer — 문자열 표현
+error — 에러
+http.Handler — HTTP 처리
+```
+
+---
+
+## G6. 메모리 재사용 — sync.Pool
+
+**sync.Pool은 신중하게. 올바르게 쓰지 않으면 미묘한 버그 원인.**
+
+### G6.1 sync.Pool 적절한 사용
+
+```go
+// 적합: 버퍼, bytes.Buffer, 인코더 같은 임시 객체
+var bufPool = sync.Pool{
+    New: func() interface{} {
+        return new(bytes.Buffer)
+    },
+}
+
+func encode(v interface{}) ([]byte, error) {
+    buf := bufPool.Get().(*bytes.Buffer)
+    defer func() {
+        buf.Reset()        // 상태 초기화 필수
+        bufPool.Put(buf)   // 반환
+    }()
+    if err := json.NewEncoder(buf).Encode(v); err != nil {
+        return nil, err
+    }
+    return append([]byte{}, buf.Bytes()...), nil  // copy — buf는 pool에 반환되므로
+}
+```
+
+### G6.2 sync.Pool 주의사항
+
+- Pool에서 꺼낸 객체의 **이전 상태가 남아있을 수 있다** → `Reset()` / `Zero` 필수.
+- GC가 Pool을 비울 수 있다 — 영구 캐시 용도로 사용 금지.
+- escape analysis 확인: `go build -gcflags='-m'` 으로 heap 할당 여부 확인.
+
+---
+
+## G7. 정적 분석 필수
+
+**린터 없이 코드 리뷰는 없다. CI에서 통과 못하면 merge 불가.**
+
+### G7.1 golangci-lint 설정
+
+```yaml
+# .golangci.yml
+linters:
+  enable:
+    - govet          # go vet (공식)
+    - staticcheck    # SA/S 룰 (버그 탐지)
+    - errcheck       # 에러 무시 탐지
+    - gosimple       # 코드 단순화
+    - ineffassign    # 불필요한 할당
+    - unused         # 미사용 코드
+    - gosec          # 보안 룰 (G-시리즈)
+    - noctx          # context 없는 HTTP 요청 탐지
+    - bodyclose      # http.Response.Body.Close() 확인
+    - nilerr         # nil 에러 반환 패턴 탐지
+    - wrapcheck      # 외부 패키지 에러 wrap 강제
+    - cyclop         # 순환 복잡도 제한
+
+linters-settings:
+  cyclop:
+    max-complexity: 10
+  gosec:
+    excludes: ["G304"]  # 파일 경로는 의도적으로 제외 가능
+
+issues:
+  exclude-rules:
+    - path: "_test.go"
+      linters: [wrapcheck, gosec]
+```
+
+### G7.2 CI 파이프라인
+
+```yaml
+# .github/workflows/go.yml
+- name: golangci-lint
+  uses: golangci/golangci-lint-action@v4
+  with:
+    version: latest
+
+- name: go test
+  run: go test -race -coverprofile=coverage.out ./...
+
+- name: go vet
+  run: go vet ./...
+```
+
+- `-race` 플래그 필수 (data race 탐지).
+- 커버리지: `go tool cover -func=coverage.out` 으로 함수별 커버리지.
+
+---
+
+## G8. 구조화 로그 (slog)
+
+```go
+import "log/slog"  // Go 1.21+
+
+// 기본 설정
+logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
+    Level: slog.LevelInfo,
+    ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
+        // 민감 정보 리댁션
+        if a.Key == "password" || a.Key == "token" {
+            return slog.String(a.Key, "[REDACTED]")
+        }
+        return a
+    },
+}))
+slog.SetDefault(logger)
+
+// 사용
+slog.InfoContext(ctx, "order created",
+    slog.String("orderId", order.ID),
+    slog.String("userId", order.UserID),
+    slog.Float64("amount", order.Amount),
+    slog.Duration("duration", time.Since(start)),
+)
+```
+
+---
+
+## G9. Go 안티패턴 카탈로그
+
+| 안티패턴 | 픽스 |
+|----------|------|
+| 에러 무시 (`_ = err`) | 에러 처리 또는 이유 주석 |
+| `panic` in 일반 에러 경로 | `error` 반환값 사용 |
+| context 없는 DB/HTTP 호출 | `xxxContext(ctx, ...)` 버전 사용 |
+| goroutine 종료 조건 없음 | context 취소 또는 done 채널 |
+| `defer cancel()` 누락 | `ctx, cancel := context.WithTimeout(...)` → `defer cancel()` |
+| receiver에서 직접 인터페이스 정의 | consumer 측에서 필요한 것만 |
+| 큰 인터페이스 (5+ 메서드) | 목적별 소형 인터페이스 분리 |
+| `sync.Mutex` Lock 후 defer Unlock 누락 | `defer mu.Unlock()` 패턴 |
+| goroutine 내 루프 변수 캡처 (Go 1.22 미만) | `item := item` 또는 인자로 전달 |
+| `http.Get` (context 없음) | `http.NewRequestWithContext(ctx, ...)` |
+| `json.Unmarshal` 에러 무시 | 에러 처리 |
+| 채널 receiver가 close | sender가 close |
+| `fmt.Println` in 프로덕션 코드 | `slog` 구조화 로그 |
+| `golangci-lint` CI 미설정 | `.golangci.yml` + CI 단계 추가 |