@wooojin/forgen 0.4.8 → 0.4.9

package/assets/dev-guide/be/skills/go/be-perf/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: be-perf-go
+description: Go 서비스의 p95/p99 성능 문제를 진단하고 수정. DB N+1, GC pause, goroutine leak, lock contention, allocation 최적화, network roundtrip 카테고리별 절차로 접근한다.
+---
+
+# be-perf (Go)
+
+> **호출 시점**: "p99가 800ms야 잡아줘", "GC pause가 심해", "goroutine 수가 계속 올라가", "메모리 사용량이 이상해".
+> **선행 로딩**: `principles/common.md` + `principles/go.md` 필수.
+
+## 0. 절대 금지
+
+1. 측정 없이 최적화 추측 금지 — pprof 데이터 없이 "아마 GC겠지"는 근거 없음.
+2. p50만 보고 OK 선언 금지 — p95/p99 반드시 확인.
+3. unsafe 패키지 성능 최적화 목적 사용 금지 — 이득이 미미하고 버그 위험 높음.
+
+## 1. 진단 절차
+
+### Step 1 — 현재 지표 수집
+
+```bash
+# pprof 활성화 (프로덕션에서는 조건부로만)
+import _ "net/http/pprof"
+go func() { http.ListenAndServe(":6060", nil) }()
+
+# 30초 CPU 프로파일 수집
+go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30
+
+# 메모리 프로파일
+go tool pprof http://localhost:6060/debug/pprof/heap
+
+# goroutine 덤프
+curl http://localhost:6060/debug/pprof/goroutine?debug=2
+
+# 벤치마크 기준선
+go test -bench=. -benchmem -count=5 ./...
+```
+
+### Step 2 — 병목 카테고리 분류
+
+| 증상 | 카테고리 |
+|------|----------|
+| pprof CPU에서 GC 관련 함수 상위 | GC pause / allocation 과다 |
+| goroutine 수 지속 증가 | goroutine leak |
+| 특정 goroutine이 mutex 대기 | lock contention |
+| DB slow query | N+1 / 인덱스 누락 |
+| 외부 API 대기 | network roundtrip |
+
+## 2. 카테고리별 진단 및 픽스
+
+### 2.1 DB N+1
+
+```go
+// WRONG: N+1
+orders, _ := repo.FindOrders(ctx)
+for _, o := range orders {
+    o.User, _ = repo.FindUser(ctx, o.UserID)  // N번 쿼리
+}
+
+// RIGHT: JOIN 또는 IN 쿼리
+orders, _ := repo.FindOrdersWithUsers(ctx)
+// SELECT o.*, u.name FROM orders o JOIN users u ON o.user_id = u.id
+
+// 또는 IN 쿼리
+userIDs := make([]string, len(orders))
+for i, o := range orders { userIDs[i] = o.UserID }
+users, _ := repo.FindUsersByIDs(ctx, userIDs)
+// SELECT * FROM users WHERE id = ANY($1)
+userMap := make(map[string]*User, len(users))
+for _, u := range users { userMap[u.ID] = u }
+```
+
+### 2.2 GC Pause / 과도한 Allocation
+
+**탐지**: pprof heap 에서 alloc_objects 상위 함수 확인.
+
+```bash
+go tool pprof -alloc_objects http://localhost:6060/debug/pprof/heap
+# top 10 으로 allocation 많은 함수 확인
+```
+
+**픽스**:
+```go
+// sync.Pool로 자주 할당하는 버퍼 재사용
+var bufPool = sync.Pool{New: func() interface{} { return new(bytes.Buffer) }}
+
+func encodeJSON(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(nil), buf.Bytes()...), nil
+}
+
+// 슬라이스 용량 사전 할당
+func buildResult(items []Item) []Result {
+    results := make([]Result, 0, len(items))  // capacity 미리 지정
+    for _, item := range items {
+        results = append(results, transform(item))
+    }
+    return results
+}
+
+// 문자열 빌더 (+ concat 대신)
+var sb strings.Builder
+sb.Grow(len(parts) * 20)  // 예상 크기 미리 할당
+for _, p := range parts {
+    sb.WriteString(p)
+}
+result := sb.String()
+```
+
+### 2.3 Goroutine Leak
+
+**탐지**:
+```bash
+# goroutine 덤프 - 비정상적으로 많으면 leak
+curl -s http://localhost:6060/debug/pprof/goroutine?debug=2 | head -50
+# 또는 goleak 라이브러리 (테스트에서)
+```
+
+```go
+// 테스트에서 leak 탐지
+import "go.uber.org/goleak"
+
+func TestCreateOrder(t *testing.T) {
+    defer goleak.VerifyNone(t)
+    // ...
+}
+```
+
+**픽스**:
+```go
+// WRONG: 종료 조건 없는 goroutine
+func startWorker() {
+    go func() {
+        for {
+            processJob()  // context 없음 — 영원히 실행
+        }
+    }()
+}
+
+// RIGHT: context 기반 종료
+func startWorker(ctx context.Context) {
+    go func() {
+        for {
+            select {
+            case <-ctx.Done():
+                return
+            default:
+                processJob(ctx)
+            }
+        }
+    }()
+}
+
+// 고정 크기 worker pool
+func NewWorkerPool(ctx context.Context, n int, jobs <-chan Job) {
+    var wg sync.WaitGroup
+    for i := 0; i < n; i++ {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            for {
+                select {
+                case job, ok := <-jobs:
+                    if !ok { return }
+                    job.Execute(ctx)
+                case <-ctx.Done():
+                    return
+                }
+            }
+        }()
+    }
+    wg.Wait()
+}
+```
+
+### 2.4 Lock Contention
+
+**탐지**: pprof mutex 프로파일.
+```bash
+go tool pprof http://localhost:6060/debug/pprof/mutex
+```
+
+**픽스**:
+```go
+// sync.RWMutex: 읽기 많고 쓰기 적을 때
+type Cache struct {
+    mu    sync.RWMutex
+    items map[string]Item
+}
+
+func (c *Cache) Get(key string) (Item, bool) {
+    c.mu.RLock()           // 읽기 lock (다중 동시 읽기 허용)
+    defer c.mu.RUnlock()
+    item, ok := c.items[key]
+    return item, ok
+}
+
+func (c *Cache) Set(key string, item Item) {
+    c.mu.Lock()            // 쓰기 lock (단독)
+    defer c.mu.Unlock()
+    c.items[key] = item
+}
+
+// atomic 연산 (카운터)
+import "sync/atomic"
+var requestCount int64
+atomic.AddInt64(&requestCount, 1)  // mutex 불필요
+```
+
+### 2.5 Network Roundtrip
+
+```go
+// HTTP 클라이언트 연결 풀 설정
+transport := &http.Transport{
+    MaxIdleConns:        100,
+    MaxIdleConnsPerHost: 10,
+    IdleConnTimeout:     90 * time.Second,
+    // Keep-Alive 기본 활성화
+}
+client := &http.Client{
+    Transport: transport,
+    Timeout:   5 * time.Second,
+}
+
+// 독립적인 외부 호출 병렬화
+g, ctx := errgroup.WithContext(ctx)
+var user *User
+var inventory *Inventory
+
+g.Go(func() error {
+    var err error
+    user, err = userClient.GetUser(ctx, userID)
+    return err
+})
+g.Go(func() error {
+    var err error
+    inventory, err = inventoryClient.GetStock(ctx, productID)
+    return err
+})
+if err := g.Wait(); err != nil { ... }
+
+// gRPC: 스트리밍 활용 (대용량 응답)
+// 단건 요청 반복 → 배치 RPC
+```
+
+### 2.6 DB 연결 풀 / 쿼리 최적화
+
+```go
+db.SetMaxOpenConns(25)
+db.SetMaxIdleConns(10)
+db.SetConnMaxLifetime(5 * time.Minute)
+db.SetConnMaxIdleTime(5 * time.Minute)
+
+// 슬로우 쿼리 로깅
+// PostgreSQL: log_min_duration_statement = 100
+// 또는 ORM 레벨 후킹
+```
+
+## 3. 벤치마크 패턴
+
+```go
+func BenchmarkCreateOrder(b *testing.B) {
+    svc := setupService(b)
+    req := validRequest()
+
+    b.ResetTimer()
+    b.RunParallel(func(pb *testing.PB) {
+        for pb.Next() {
+            _, err := svc.CreateOrder(context.Background(), req)
+            if err != nil {
+                b.Fatal(err)
+            }
+        }
+    })
+    // 메모리 할당도 확인: go test -bench=. -benchmem
+}
+```
+
+## 4. 출력 형식
+
+```
+## 성능 진단 결과
+
+### 측정 기준선
+- p50: Xms / p95: Xms / p99: Xms
+- goroutine 수: N
+- heap: XMB
+
+### 발견된 병목
+1. [DB N+1] internal/service/order.go:55 — 주문 목록 조회 시 N번 user 쿼리
+2. [GC] internal/handler/serialize.go:30 — 요청마다 bytes.Buffer 새로 할당
+
+### 적용한 픽스
+- 변경 파일: <목록>
+- 재측정: p95 Xms → Xms, heap XMB → XMB
+
+### 추가 권고
+- ...
+```
+
+## 5. 관련 문서
+
+- 원칙: [`principles/common.md`](../../../principles/common.md) F섹션, [`principles/go.md`](../../../principles/go.md) G6
+- 코퍼스: `sources/go-runtime/`, `sources/postgres/`

package/assets/dev-guide/be/skills/go/be-review/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: be-review-go
+description: Go PR을 사내 BE 원칙 기준으로 리뷰. [SEVERITY] file:line — 이슈 형식으로 출력하고, 머지 차단/비차단을 명확히 구분한다.
+---
+
+# be-review (Go)
+
+> **호출 시점**: "이 PR 리뷰해줘", "이 Go 코드 리뷰해줘", "OWASP 관점에서 검토해줘".
+> **선행 로딩**: `principles/common.md` + `principles/go.md` 필수.
+
+## 0. 절대 금지
+
+1. golangci-lint가 잡는 이슈를 수동 리뷰에 중복 포함하지 마라 (자동 도구 역할 존중).
+2. 주관적 스타일 의견을 [HIGH]로 분류 금지.
+3. Go idiom이 아닌 이유로 [HIGH] 처리 금지 — 보안/안전성 기준으로만.
+
+## 1. 리뷰 출력 형식
+
+```
+## 리뷰 요약
+- 변경: N files +X -Y
+- HIGH N, MED N, LOW N / 머지 [차단|비차단]
+
+[HIGH] internal/handler/order.go:42 — context 없는 DB 쿼리 (N9 antipa.)
+[HIGH] internal/handler/order.go:88 — 에러 무시 (_ = err), 결제 실패 묵살
+[MED]  internal/service/order.go:120 — goroutine 종료 조건 없음 (leak 위험)
+[LOW]  internal/repository/order.go:55 — 인터페이스 구현 패키지에서 정의
+```
+
+### SEVERITY 기준
+
+| SEVERITY | 정의 | 머지 |
+|----------|------|------|
+| **HIGH** | 에러 묵살, goroutine leak, context 미전파, OWASP 취약점, panic 남용, race condition | 차단 |
+| **MED** | 큰 인터페이스, goroutine 종료 조건 불명확, 에러 래핑 누락, defer cancel 누락 | 권고 |
+| **LOW** | 네이밍, 패키지 구조, 코멘트 스타일 | 비차단 |
+
+## 2. 체크리스트
+
+### 2.1 에러 처리 (HIGH)
+
+```
+[ ] 에러 무시 없음 — _ = err 패턴
+[ ] 빈 에러 처리 없음 — if err != nil { return } (로그 없는 경우)
+[ ] 에러 래핑 — fmt.Errorf("funcName: %w", err)
+[ ] panic 사용이 정당한가 — 초기화 실패 / 프로그래밍 오류에만
+[ ] sentinel error 정의 — errors.New로 변수화
+[ ] errors.Is / errors.As 올바른 사용
+```
+
+### 2.2 context 전파 (HIGH/MED)
+
+```
+[ ] I/O 함수 첫 인자가 context.Context
+[ ] DB 쿼리: QueryContext, ExecContext, QueryRowContext 사용
+[ ] HTTP 요청: http.NewRequestWithContext 사용
+[ ] context.WithTimeout 후 defer cancel() 존재
+[ ] context.Value — 비즈니스 파라미터 전달에 미사용
+```
+
+### 2.3 goroutine 안전성 (HIGH/MED)
+
+```
+[ ] goroutine 종료 조건 존재 (ctx.Done() 또는 done channel)
+[ ] WaitGroup / errgroup으로 완료 대기
+[ ] 채널 close — sender가 담당
+[ ] 버퍼드 채널 크기 의도적으로 선택
+[ ] sync.Mutex Lock 후 defer Unlock
+[ ] go test -race 통과 (PR CI에 포함)
+```
+
+### 2.4 보안 (HIGH)
+
+```
+[ ] SQL 파라미터화 — 문자열 concat 없음
+[ ] 소유권 검증 — URL params로 타인 리소스 접근 불가
+[ ] 입력 검증 — 외부 데이터 go-validator 또는 수동 검증
+[ ] 응답에 내부 필드 노출 없음
+[ ] 시크릿 코드 내 하드코딩 없음
+```
+
+### 2.5 인터페이스 설계 (MED/LOW)
+
+```
+[ ] 인터페이스 크기 — 1~3 메서드 (5+ 메서드 경고)
+[ ] 인터페이스 정의 위치 — consumer 패키지 (구현 패키지 X)
+[ ] 표준 라이브러리 인터페이스 재활용 (io.Reader 등)
+```
+
+### 2.6 코드 품질 (LOW)
+
+```
+[ ] 함수 50줄 이하
+[ ] 중첩 깊이 4 이하 (early return 활용)
+[ ] 네이밍 — Go 관습 (CamelCase, receiver 단문자)
+[ ] 패키지 이름 — 단수 소문자 (orders X → order O)
+[ ] golangci-lint 이슈 없음
+```
+
+## 3. 이슈 카탈로그 (즉시 참조)
+
+| 패턴 | SEVERITY | 설명 |
+|------|----------|------|
+| `_ = err` | HIGH | 에러 묵살 |
+| `db.Query(ctx, "... WHERE id = " + id)` | HIGH | SQL injection |
+| `go func() { for { process() } }()` | HIGH | goroutine leak |
+| `ctx, cancel := ...; cancel()` (defer 없음) | MED | context 누수 |
+| `resp, _ := http.Get(url)` | HIGH | context 없음 + 에러 무시 |
+| `resp.Body.Close()` 누락 | MED | resource leak |
+| `interface` 5+ 메서드 | MED | 분리 필요 |
+| `type Repo interface { ... }` in repo pkg | LOW | consumer 측 정의 권장 |
+| `panic(err)` in handler | HIGH | 서버 크래시 |
+| `fmt.Println(...)` in prod | LOW | slog 구조화 로그 |
+| `json.Unmarshal(data, &v)` 에러 무시 | HIGH | 에러 처리 |
+
+## 4. 관련 문서
+
+- 원칙: [`principles/common.md`](../../../principles/common.md), [`principles/go.md`](../../../principles/go.md)
+- 보안: [`skills/go/be-security/SKILL.md`](../be-security/SKILL.md)