yd-go-expert

yd-go-expert

Go 코드가 대상이다. SQL·스키마는 yd-db-expert 와 엔진별 스킬(yd-pg-expert·yd-oracle-expert·yd-sqlite-expert), 프론트 산출물 내장의 빌드 순서는 yd-frontend-build 가 맡는다.

이 문서는 일반론을 적지 않는다. 판단이 갈리는 지점, 자주 틀리는 곳, 최근 버전에서 바뀐 것만 담는다.

1. 에러

• 감싸서 올린다. fmt.Errorf("%s 열기 실패: %w", path, err) — %w 여야 errors.Is/errors.As 가 통한다. %v 로 감싸면 사슬이 끊긴다.
• 호출부가 분기해야 하는 실패는 센티널로 노출한다. var ErrNotFound = errors.New(...). 문자열 비교로 분기하지 않는다.
• 메시지는 소문자로 시작하고 마침표를 붙이지 않는다. 한국어 메시지도 문장부호 없이 짧게.
• 로그와 반환을 동시에 하지 않는다. 둘 다 하면 같은 실패가 여러 번 기록된다. 최상위(핸들러·main)에서 한 번만 기록한다.
• panic 은 프로그래머 오류에만. 입력이 잘못된 것은 에러다.
• error 자리에 nil 포인터를 돌려주지 않는다(typed nil). var e *MyErr; return e 는 호출부에서 err != nil 이 참이다. 인터페이스 값에 타입 정보가 남기 때문이다. 실패가 없으면 리터럴 nil 을 반환한다.

if errors.Is(err, chatdb.ErrNotFound) { ... }   // 분기
var perr *fs.PathError
if errors.As(err, &perr) { ... }                 // 타입 정보가 필요할 때

Go 1.26+ 는 errors.AsType 으로 변수 선언 없이 꺼낸다. go.mod 의 go 버전이 1.26 미만이면 errors.As 를 쓴다.

go vet 는 go.mod 보다 새로운 표준 라이브러리 API 를 쓰면 requires go1.26 or later 로 잡는다. 완료 조건의 go vet 가 그 확인을 겸한다.

if perr, ok := errors.AsType[*fs.PathError](err); ok { ... }

2. 동시성 — 필요할 때만

goroutine 을 띄우기 전에 답한다: 누가 이걸 멈추는가? 결과는 누가 받는가? 답이 없으면 만들지 않는다.

• goroutine 의 수명은 호출부가 통제한다. context.Context 를 첫 인자로 받고, 종료 신호를 존중한다. 구조체 필드에 context 를 넣지 않는다.
• 채널로 소유권을 옮기거나, 뮤텍스로 공유를 보호하거나 — 둘을 섞지 않는다.
• sync.WaitGroup 은 Add 를 goroutine 밖에서 부른다. 안에서 부르면 경합이다. Go 1.25+ 는 wg.Go(func() { ... }) 가 Add·Done 을 대신해 이 실수가 생기지 않는다.
• 하나가 실패하면 나머지를 멈춰야 하면 golang.org/x/sync/errgroup 의 errgroup.WithContext 를 쓴다. WaitGroup 은 에러를 모으지도, 취소하지도 않는다.
• 루프 안의 defer 는 함수가 끝날 때까지 실행되지 않는다. 파일을 수백 개 여는 루프에서 쓰면 핸들이 쌓인다. 반복마다 닫아야 하면 본문을 함수로 빼고 그 안에서 defer 한다.
• 루프 변수 캡처는 Go 1.22부터 반복마다 새 변수라 안전하다. 그 이전 버전 코드를 손볼 때는 여전히 확인한다.
• 테스트는 -race 로 돌린다. 동시성 코드를 추가·수정했으면 필수다.

3. net/http — Go 1.22+ ServeMux

메서드와 경로 변수를 표준 mux 가 지원한다. 서드파티 라우터를 새로 들이기 전에 이걸로 충분한지 본다.