ADR-0002: Discord Library: disgo¶

Umbra 의 Discord Bot 라이브러리로 disgo (disgoorg/disgo) v0.19+ 를 채택한다.

Status¶

Accepted

Decided at — 2026-04-13
Decided by — Pablo

Context¶

Go 언어 채택 후(ADR-0001) Discord 와 통신할 라이브러리를 선택해야 한다. Umbra 의 Bot 프로세스는 다음을 수행해야 한다.

Discord Gateway 에 상시 WebSocket 연결 유지
슬래시 커맨드와 인터랙션 처리
Components V2 (Container, Section, Text Display, Media Gallery, Separator) 활용
길드 이벤트 수신 및 도메인 라우팅
REST API 로 Discord 리소스 조작 (역할 생성, 채널 복구 등)

Go 진영의 주요 Discord 라이브러리 후보: discordgo, disgo, arikawa.

특히 Components V2 지원 은 Umbra 의 차별화 요소 중 하나이다. 결제 플로우, 스냅샷 카드, 복구 진행 UI 를 풍부한 레이아웃으로 구성해야 한다.

Decision¶

disgo (disgoorg/disgo) v0.19+ 를 Discord 라이브러리로 채택한다.

선택 근거:

Components V2 정식 지원 — 2025년 4월 v0.19 에 정식 머지 (PR #426). Container/Section/Text Display/Media Gallery/Separator 빌더 제공.
모던 API 설계 — 슬래시 커맨드, 인터랙션, 모달이 1급 시민. 보일러플레이트 적음.
모듈러 구조 — gateway, rest, cache, sharding 이 분리되어 Hexagonal 어댑터 설계와 결이 맞음.
활발한 유지보수 — 2025–2026 동안 Discord API 신기능 빠르게 반영.
인터랙션 라우터 내장 — 핸들러 디스패치 추상화가 깔끔.

Consequences¶

Positive¶

Components V2 를 즉시 활용 가능 — 결제 카드, 스냅샷 UI, 복구 진행 시각화
슬래시 커맨드 DX 가 좋아 Bot 핸들러 코드 간결화
모듈 분리로 어댑터 레이어에 자연스럽게 통합
Discord API 신기능 반영이 빠름

Negative¶

discordgo 대비 레퍼런스가 적음 (Stack Overflow, 블로그 글)
메이저 버전 업데이트가 잦음 (breaking change 가능성)
한국어 자료 거의 없음

Neutral¶

Luxtra 팀 컨벤션상 disgo 를 engine/recovery/subdomain/*/adapter/discord/ 와 apps/bot/internal/ 에서만 사용
도메인 코어는 disgo 타입을 모름 (Anti-Corruption Layer 유지)

Alternatives considered¶

Alternative 1: discordgo (bwmarrin/discordgo)¶

Pros

Go 진영 가장 유명한 Discord 라이브러리
레퍼런스 풍부 (Stack Overflow, GitHub 예제 다수)
진입 장벽 낮음

Cons

API 디자인이 올드함 — 슬래시 커맨드와 Components 가 후발 추가라 일관성 부족
Components V2 지원이 미흡, 유지보수 활동 정체
인터랙션 처리 시 보일러플레이트 많음
캐시/상태 관리가 monolithic 하여 Hexagonal 어댑터 분리가 어려움

Why rejected — Components V2 지원 부재와 유지보수 정체가 결정적. 결제 SaaS 장기 운영에 리스크.

Alternative 2: arikawa (diamondburned/arikawa)¶