RepoThread Logo
RepoThread
요금제

프로젝트 개요

관련 소스 파일

이 페이지의 내용은 다음 소스 파일을 기반으로 생성되었습니다:

gochat은 순수 Go 언어로 구현된 경량급 인스턴트 메시징(IM) 시스템으로, 개인 메시지와 채팅방 브로드캐스트 메시지를 모두 지원한다. 각 계층은 RPC를 통해 통신하며 수평 확장이 가능한 구조로 설계되어 있다. WebSocket과 TCP 프로토콜을 동시에 지원하고, 최신 버전에서는 두 프로토콜 간 메시지 상호 운용이 가능하다. etcd 기반 서비스 디스커버리를 통해 확장 배포 시 용이하며, Redis를 메시지 저장 및 전달 담체로 사용해 매우 경량화된 구조를 갖추고 있다 (readme.md:19-26, readme.en.md:20-27).

프로젝트 소개 및 특징

핵심 가치 제안

gochat 프로젝트는 분산형 IM 시스템의 학습과 프로토타이핑을 위한 명확한 아키텍처를 제공하는 것을 목표로 한다. 마이크로서비스 패턴, RPC 통신, 서비스 디스커버리, 메시지 큐잉 등 현대적인 백엔드 아키텍처의 핵심 개념을 단일 프로젝트에서 종합적으로 다룰 수 있도록 설계되었다.

주요 기능 특성

특성설명구현 방식
프로토콜 지원WebSocket, TCP 동시 지원connect 계층에서 프로토콜별 핸들러 분리
메시지 유형개인 메시지, 채팅방 브로드캐스트logic 계층에서 메시지 라우팅 처리
수평 확장모든 계층 독립적 확장 가능etcd 서비스 디스커버리 기반
메시지 큐비동기 메시지 처리Redis List 구조 활용
서비스 디스커버리동적 서비스 등록 및 발견etcd watch 메커니즘
크로스 플랫폼다양한 OS에서 실행 가능Go 교차 컴파일 특성 활용

기술적 이점

  • 모듈 간 독립성: 각 계층이 명확한 책임 경계를 가지며 독립적으로 배포 및 확장 가능
  • 유연한 메시지 저장소: Redis를 기본으로 사용하나 Kafka, RabbitMQ 등으로 교체 가능
  • 간편한 환경 구축: Docker를 통한 원클릭 환경 구성 지원 (readme.md:25)
  • 동적 설정 갱신: etcd watch를 통한 서비스 IP 동적 업데이트 (readme.md:34)

적용 시나리오

  • 실시간 채팅 서비스: 소규모~중간 규모의 실시간 메시징 서비스 프로토타입
  • 분산 시스템 학습: 마이크로서비스 아키텍처 패턴 학습용 교육 자료
  • IoT 메시징: TCP 프로토콜 지원을 통한 IoT 기기와의 통신 가능
  • 게임 채팅: 방 기반 브로드캐스트 메시지 기능 활용

시스템 아키텍처 및 모듈 구성

아키텍처 개요

gochat은 5개의 핵심 모듈과 2개의 지원 모듈로 구성된 마이크로서비스 아키텍처를 채택했다. 각 모듈은 단일 책임 원칙을 따르며 RPC를 통해 느슨하게 결합된다. 프로그램 진입점인 main.go에서는 명령줄 플래그를 통해 실행할 모듈을 선택적으로 기동할 수 있다 (main.go:21-44).

go
1switch module {
2case "logic":
3    logic.New().Run()
4case "connect_websocket":
5    connect.New().Run()
6case "connect_tcp":
7    connect.New().RunTcp()
8case "task":
9    task.New().Run()
10case "api":
11    api.New().Run()
12case "site":
13    site.New().Run()
14}

모듈 구조도

正在加载图表渲染器...

아키텍처 다이어그램 설명:

  1. 클라이언트 계층: WebSocket(브라우저)과 TCP(모바일/IoT) 두 가지 프로토콜을 통해 접속 가능
  2. 게이트웨이 계층: Site 모듈은 정적 페이지 제공, API 모듈은 RESTful 인터페이스 노출
  3. 코어 서비스 계층: Connect는 연결 유지, Logic은 비즈니스 규칙 처리 담당
  4. 워커 계층: Task 모듈이 Redis 큐에서 메시지를 소비하여 Connect 계층에 전달
  5. 인프라 계층: etcd, Redis, SQLite이 각각 서비스 디스커버리, 메시징, 영속성 제공

핵심 모듈 상세 분석

Connect 모듈 (connect)

책임 경계:

  • 수천~수만 개의 동시 연결을 유지 관리
  • WebSocket 및 TCP 프로토콜 핸들링
  • 실시간 메시지 푸시 수행
  • 비즈니스 로직 처리는 하지 않음 (Logic 모듈에 위임)

진입점 및 API:

  • connect.New().Run(): WebSocket 서버 시작 (main.go:30)
  • connect.New().RunTcp(): TCP 서버 시작 (main.go:32)

주요 데이터 구조:

  • Room 기반 세션 이중 연결 리스트: 동일 채팅방 사용자들의 연결 세션 관리
  • ServerId: 각 Connect 인스턴스의 고유 식별자

호출 관계:

  • Logic 모듈로 RPC 호출: 사용자 인증, 방 입장 등 비즈니스 요청
  • Task 모듈으로부터 RPC 수신: 메시지 브로드캐스트 요청

Logic 모듈 (logic)

책임 경계:

  • 비즈니스 로직 처리의 중심 허브
  • 메시지 큐 발행 (직접 전송하지 않음)
  • 사용자 세션 정보 관리
  • 데이터베이스 CRUD 작업

진입점 및 API:

  • logic.New().Run(): Logic 서비스 시작 (main.go:28)

주요 기능:

  • 사용자 로그인 시 Connect 계층의 ServerId 기록
  • 메시지 수신 시 Redis 큐로 Publish
  • 방 입장/퇴장 로직 처리

에러 처리:

  • RPC 호출 실패 시 재시도 메커니즘
  • 데이터베이스 연결 실패 시 graceful degradation

Task 모듈 (task)

책임 경계:

  • Redis 큐에서 메시지 소비
  • 메시지 라우팅 로직 수행
  • Connect 계층으로 메시지 전달 명령

진입점 및 API:

  • task.New().Run(): Task 워커 시작 (main.go:34)

메시지 처리 흐름:

  1. Redis List에서 메시지 POP
  2. 메시지 내용에서 userId, roomId, serverId 추출
  3. 해당 serverId를 가진 Connect 인스턴스로 RPC 호출
  4. Connect가 해당 방의 모든 세션에 메시지 전달

API 모듈 (api)

책임 경계:

  • RESTful API 인터페이스 제공
  • HTTP 요청 검증 및 변환
  • Logic 모듈로의 RPC 프록시 역할

진입점 및 API:

주요 엔드포인트:

  • 로그인 API: 사용자 인증 및 토큰 발급
  • 메시지 전송 API: HTTP를 통한 메시지 발송
  • 방 관리 API: 채팅방 생성/조회

디렉토리 구조

gochat/
├── api/                  # REST API 계층, 수평 확장 가능
├── architecture/         # 아키텍처 다이어그램 리소스
├── bin/                  # 컴파일된 바이너리 (git 추적 제외)
├── config/               # 환경별 설정 파일
├── connect/              # 연결 계층, 대량 연결 핸들링
├── db/                   # DB 연결 초기화 (SQLite3 기본)
├── docker/               # Docker 환경 구성
├── logic/                # 비즈니스 로직 계층
├── main.go               # 단일 진입점
├── proto/                # RPC 프로토콜 정의
├── site/                 # 정적 웹 페이지
├── task/                 # 메시지 소비 워커
├── tools/                # 유틸리티 함수
└── vendor/               # 의존성 패키지

(readme.md:127-148)

기술 스택 및 의존성

핵심 기술 스택

카테고리기술버전용도
프로그래밍 언어Go1.18+전체 시스템 구현
데이터베이스SQLite3-사용자 정보 저장 (교체 가능)
ORMGORM1.9.16데이터베이스 추상화
서비스 디스커버리etcd3.4.3서비스 등록 및 발견
RPC 프레임워크rpcx1.7.4모듈 간 통신
메시지 큐Redis5.0.9메시지 저장 및 전달
캐시Redis5.0.9세션, 카운터, 방 정보

(go.mod:1-22, readme.md:150-168)

주요 의존성 패키지

go
1require (
2    github.com/bwmarrin/snowflake v0.3.0    // 분산 ID 생성
3    github.com/gin-gonic/gin v1.7.7         // HTTP 프레임워크
4    github.com/go-redis/redis v6.15.9       // Redis 클라이언트
5    github.com/google/uuid v1.3.0           // UUID 생성
6    github.com/gorilla/websocket v1.5.0     // WebSocket 구현
7    github.com/jinzhu/gorm v1.9.16          // ORM
8    github.com/pkg/errors v0.9.1            // 에러 처리
9    github.com/sirupsen/logrus v1.8.1       // 로깅
10    github.com/spf13/viper v1.11.0          // 설정 관리
11    github.com/smallnest/rpcx v1.7.4        // RPC 프레임워크
12    github.com/rpcxio/rpcx-etcd v0.1.0      // etcd 플러그인
13)

(go.mod:5-22)

기술 선택 이유

etcd 서비스 디스커버리:

  • 각 계층이 etcd에 자신의 서비스 주소를 등록
  • 다른 계층은 etcd에서 필요한 서비스를 발견하여 호출
  • watch 메커니즘으로 서비스 추가/제거 시 동적으로 인식 (readme.md:22)

Redis 메시지 큐:

  • 경량화된 메시지 브로커 역할
  • 실제 운영 환경에서는 Kafka, RabbitMQ로 교체 가능 (readme.md:23)
  • List 자료구조를 활용한 간단한 큐 구현

SQLite 데이터베이스:

  • 데모 및 개발 환경에서의 편의성 제공
  • 실제 운영 환경에서 MySQL 등으로 교체 가능 (readme.md:154-156)

메시지 전달 흐름

메시지 전송 시퀀스

正在加载图表渲染器...

시퀀스 다이어그램 설명:

  1. 연결 설정 단계: 사용자가 API를 통해 로그인하고, Connect 모듈과 지속 연결을 설정
  2. 메시지 전송 단계: API → Logic → Redis 큐로 메시지가 비동기적으로 전달됨
  3. 메시지 수신 단계: Task 워커가 큐에서 메시지를 소비하고, 적절한 Connect 인스턴스로 RPC 호출

WebSocket과 TCP 메시지 상호 운용

최신 버전에서는 WebSocket과 TCP 프로토콜 간 메시지 상호 운용을 지원한다. 동일한 채팅방에 WebSocket으로 접속한 사용자와 TCP로 접속한 사용자가 모두 존재할 수 있으며, 메시지는 프로토콜에 관계없이 모든 방 참여자에게 전달된다 (readme.en.md:53-61).

TCP 메시지 처리 특이사항:

  • TCP는 스트림 기반 프로토콜이므로 패킷 분할/재조립 필요
  • pkg/stickpackage 모듈에서 Pack/Unpack 메서드 제공
  • 클라이언트는 동일한 프로토콜로 메시지 인코딩/디코딩 구현 필요

라이선스 및 배포 환경

오픈소스 라이선스

gochat은 MIT 라이선스 하에 배포된다. 이 라이선스는 상업적 사용, 수정, 배포, 서브라이선스 설정을 포함한 광범위한 자유를 허용한다 (LICENSE:1-21).

MIT 라이선스 주요 조건:

  • 저작권 고지 및 라이선스 사본을 모든 복제본에 포함
  • 소프트웨어는 "있는 그대로" 제공되며, 어떠한 보증도 하지 않음
  • 작성자는 계약, 불법 행위 또는 기타 방식으로 발생하는 손해에 대해 책임지지 않음

Docker 배포 환경

프로젝트는 Docker를 통한 간편한 환경 구축을 지원한다. Dockerfile은 Go 1.18 베이스 이미지를 사용하며, etcd, Redis, SQLite 등 필요한 모든 의존성을 포함한다 (docker/Dockerfile:1-29).

Dockerfile 구성 요소:

dockerfile
1FROM golang:1.18
2MAINTAINER Lock <lockexit@gmail.com>
3WORKDIR /go/src/gochat
4# etcd v3.4.3 설치
5# Redis 5.0.9 설치
6# Supervisor 설치
7ENV RUN_MODE dev

빌드 명령:

bash
1make build TAG=1.18
2# 또는
3make build TAG=latest

(Makefile:1-4)

런타임 환경 변수

변수명기본값설명
RUN_MODEdev실행 모드 (dev/prod), 설정 파일 선택에 사용

(docker/Dockerfile:27)

프로젝트 정량 지표

지표수치비고
지원 프로토콜2개WebSocket, TCP
코어 모듈 수5개logic, connect, task, api, site
지원 메시지 유형2개개인 메시지, 방 브로드캐스트
데이터베이스1개 (교체 가능)SQLite3 (MySQL 등으로 교체 가능)
외부 의존성3개etcd, Redis, SQLite
Go 버전 요구사항1.18+제네릭 등 최신 기능 활용
프로젝트 크기~66MBvendor 포함

보고서 탐색 가이드

正在加载图表渲染器...

탐색 가이드 설명:

  1. 프로젝트 개요 (현재 문서): 전체 시스템의 목적, 구조, 기술 스택을 파악
  2. 아키텍처 심층 분석: 각 모듈의 내부 구현, RPC 통신 패턴, 확장 전략 심층 분석
  3. 데이터 모델 및 흐름: 메시지 큐 구조, 데이터베이스 스키마, 캐시 전략 상세 설명
  4. API 설계: RESTful 엔드포인트, RPC 인터페이스, 프로토콜 버퍼 정의 분석
  5. 배포 및 운영: Docker 구성, 모니터링, 로깅, 장애 대응 전략

추천 학습 경로:

  • 초급: 개요 → API 설계 → 배포 및 운영
  • 중급: 개요 → 아키텍처 심층 분석 → 데이터 모델 및 흐름
  • 고급: 전체 문서 순차적 학습 후 소스 코드 정독