DocsPricingBlog
Contact Us
Log inSign up for FREE
Back to Tech Articles

Go 애플리케이션에서의 Gorilla WebSocket을 이용한 실시간 통신

Sep 18, 2025
# Misc

Ethan Miller

Product Engineer · Leapcell

This post is also available in English, 日本語, and Deutsch
Cover of "Go 애플리케이션에서의 Gorilla WebSocket을 이용한 실시간 통신"

소개: Go 애플리케이션에 실시간 상호작용 기능 강화

오늘날 빠르게 변화하는 디지털 세상에서 정적인 웹 페이지와 전통적인 요청-응답 아키텍처는 종종 사용자 기대를 충족시키지 못합니다. 채팅 플랫폼, 협업 편집 도구, 라이브 대시보드 또는 온라인 게임과 같은 현대적인 애플리케이션은 즉각적인 업데이트와 원활한 상호작용을 통해 번창합니다. 이러한 실시간 통신에 대한 요구는 WebSocket과 같은 기술을 필수적으로 만들었습니다. Go는 뛰어난 동시성 기본 요소와 강력한 표준 라이브러리를 갖추고 있어 고성능 네트워크 서비스를 구축하는 데 이상적인 언어입니다. Go에서 실시간 통신과 관련하여 gorilla/websocket 라이브러리는 사실상의 표준으로 두드러집니다. 이 라이브러리는 WebSocket 서버 및 클라이언트 구현을 위한 간단하면서도 강력한 API를 제공하여 개발자가 Go 애플리케이션에 동적인 양방향 통신 기능을 손쉽게 추가할 수 있도록 합니다. 이 글에서는 gorilla/websocket을 통합하여 서비스의 상호작용 수준을 한 단계 높이는 과정을 안내합니다.

실시간 통신 및 WebSocket 이해

코드로 들어가기 전에 관련된 핵심 개념에 대한 명확한 이해를 확립해 봅시다.

실시간 통신 (RTC): 이는 전송 지연 없이 사용자가 정보를 즉시 교환할 수 있도록 하는 모든 통신 매체를 의미합니다. 웹 컨텍스트에서 이는 서버가 주기적으로 서버를 폴링할 필요 없이 사용 가능한 즉시 서버가 클라이언트에 데이터를 푸시할 수 있음을 의미합니다.

WebSocket: WebSocket은 단일의 오래 지속되는 TCP 연결을 통해 전이중 통신 채널을 제공합니다. 각 요청이 새 연결을 시작하는 전통적인 HTTP와 달리 WebSocket은 초기 HTTP 핸드셰이크 후에 영구적인 연결을 설정합니다. 이를 통해 클라이언트와 서버 모두 언제든지 서로에게 메시지를 보낼 수 있어 폴링 또는 장기 폴링 기술에 비해 오버헤드와 지연 시간을 크게 줄입니다.

gorilla/websocket: 이것은 WebSocket 서버 및 클라이언트 구현을 위한 깔끔하고 관용적인 API를 제공하는 인기 있고 잘 관리되는 Go 라이브러리입니다. 핸드셰이크, 프레이밍 및 제어 프레임을 포함한 WebSocket 프로토콜의 복잡성을 처리하여 개발자가 애플리케이션 로직에 집중할 수 있도록 합니다.

간단한 WebSocket 서버 구축

수신되는 메시지를 다시 에코하는 기본 WebSocket 서버를 만드는 것부터 시작하겠습니다. 이는 기본적인 gorilla/websocket 서버 측 API를 시연할 것입니다.

package main

import (
	"log"
	"net/http"

	"github.com/gorilla/websocket"
)

// Configure the upgrader to handle WebSocket handshakes.
// CheckOrigin is important for security in production environments.
// For demonstration, we'll allow all origins.
var upgrader = websocket.Upgrader{
	ReadBufferSize:  1024,
	WriteBufferSize: 1024,
	CheckOrigin: func(r *http.Request) bool {
		return true // Allow all origins for simplicity. In production, restrict this.
	},
}

// wsHandler handles WebSocket connections.
func wsHandler(w http.ResponseWriter, r *http.Request) {
	// Upgrade the HTTP connection to a WebSocket connection.
	conn, err := upgrader.Upgrade(w, r, nil)
	if err != nil {
		log.Printf("Failed to upgrade connection: %v", err)
		return
	}
	defer conn.Close() // Ensure the connection is closed when the handler exits.

	log.Println("Client connected:", r.RemoteAddr)

	for {
		// Read message from the client.
		messageType, p, err := conn.ReadMessage()
		if err != nil {
			log.Printf("Error reading message from %s: %v", r.RemoteAddr, err)
			break // Exit the loop on error (e.g., client disconnected).
		}

		log.Printf("Received message from %s: %s", r.RemoteAddr, p)

		// Write the same message back to the client.
		if err := conn.WriteMessage(messageType, p); err != nil {
			log.Printf("Error writing message to %s: %v", r.RemoteAddr, err)
			break // Exit the loop on error.
		}
	}

	log.Println("Client disconnected:", r.RemoteAddr)
}

func main() {
	http.HandleFunc("/ws", wsHandler) // Register our WebSocket handler.

	log.Println("WebSocket server starting on :8080")
	err := http.ListenAndServe(":8080", nil) // Start the HTTP server.
	if err != nil {
		log.Fatalf("Server failed to start: %v", err)
	}
}

설명:

  1. upgrader: 이 전역 변수는 HTTP 연결을 WebSocket으로 업그레이드하는 방법을 구성합니다. ReadBufferSize와 WriteBufferSize는 버퍼 크기를 결정합니다. CheckOrigin은 프로덕션 환경에서 보안에 중요합니다. 이 시연에서는 모든 origin을 허용합니다.
  2. wsHandler:
    • upgrader.Upgrade(w, r, nil): 이는 WebSocket 핸드셰이크를 수행하는 핵심 호출입니다. 성공하면 수립된 WebSocket 연결을 나타내는 websocket.Conn 객체를 반환합니다.
    • defer conn.Close(): 함수가 종료될 때 연결이 올바르게 닫히도록 보장하여 리소스를 해제합니다.
    • for {} 루프는 메시지를 지속적으로 읽고 씁니다.
    • conn.ReadMessage(): 수신된 메시지를 읽습니다. 메시지 유형(예: websocket.TextMessage, websocket.BinaryMessage), 메시지 페이로드 ([]byte) 및 오류를 반환합니다.
    • conn.WriteMessage(messageType, p): 클라이언트에 메시지를 다시 씁니다. 여기서는 단순히 수신된 메시지를 에코합니다.
    • ReadMessage 및 WriteMessage에 대한 오류 처리는 클라이언트 연결 끊김 또는 네트워크 문제를 감지하는 데 중요합니다.

간단한 WebSocket 클라이언트 구축 (Go에서)

일반적으로 브라우저의 JavaScript API(예: new WebSocket('ws://localhost:8080/ws'))를 사용하여 WebSocket 서버에 연결하지만, gorilla/websocket은 클라이언트 측 기능도 제공합니다. 서버를 테스트하기 위한 Go 클라이언트를 만들어 보겠습니다.

package main

import (
	"fmt"
	"log"
	"net/url"
	"os"
	"os/signal"
	time "time"

	"github.com/gorilla/websocket"
)

func main() {
	interrupt := make(chan os.Signal, 1)
	signal.Notify(interrupt, os.Interrupt)

	u := url.URL{Scheme: "ws", Host: "localhost:8080", Path: "/ws"}
	log.Printf("Connecting to %s", u.String())

	conn, _, err := websocket.DefaultDialer.Dial(u.String(), nil)
	if err != nil {
		log.Fatal("Dial:", err)
	}
	defer conn.Close()

	done := make(chan struct{})

	// Goroutine to read messages from the server
	go func() {
		defer close(done)
		 for {
			_, message, err := conn.ReadMessage()
			if err != nil {
				log.Println("Read error:", err)
				return
			}
			log.Printf("Received from server: %s", message)
		}
	}()

	// Goroutine to send messages to the server
	ticker := time.NewTicker(time.Second)
	defer ticker.Stop()

	for {
		select {
		case <-done: // Server connection closed
			return
		case t := <-ticker.C: // Send a message every second
			message := fmt.Sprintf("Hello from client at %s", t.Format(time.RFC3339))
			err := conn.WriteMessage(websocket.TextMessage, []byte(message))
			if err != nil {
				log.Println("Write error:", err)
				return
			}
		case <-interrupt: // OS interrupt (Ctrl+C)
			log.Println("Interrupt signal received. Closing connection...")
			err := conn.WriteMessage(websocket.CloseMessage, websocket.FormatCloseMessage(websocket.CloseNormalClosure, ""))
			if err != nil {
				log.Println("Write close error:", err)
				return
			}
			select {
			case <-done:
			case <-time.After(time.Second): // Wait for server to close, or timeout
			}
			return
		}
	}
}

설명:

  1. websocket.DefaultDialer.Dial: 이 함수는 지정된 URL에 대한 클라이언트 측 WebSocket 연결을 설정합니다.
  2. done 채널: 읽기 루틴이 중지되었을 때(일반적으로 서버에서 연결을 닫거나 오류가 발생했을 때) 신호를 보내는 데 사용됩니다.
  3. 읽기 Goroutine: 서버에서 지속적으로 메시지를 읽고 출력합니다.
  4. 쓰기 Goroutine (또는 ticker가 있는 메인 루프): conn.WriteMessage를 사용하여 1초마다 서버에 메시지를 보냅니다.
  5. interrupt 채널: Ctrl+C를 사용하여 WebSocket 연결을 닫음 메시지와 함께 정상적으로 처리하여 서버에 신호를 보냅니다.

고급 개념 및 응용 시나리오

여러 연결 관리 (채팅 애플리케이션 예제)

실제 WebSocket 애플리케이션은 여러 연결된 클라이언트를 관리해야 합니다. 일반적인 패턴은 허브 또는 관리자를 두어 모든 활성 연결을 추적하고 메시지를 브로드캐스트하는 것입니다.

채팅 애플리케이션을 지원하기 위해 서버를 리팩토링하여 한 클라이언트의 메시지를 다른 모든 연결된 클라이언트에 브로드캐스트합니다.

package main

import (
	"log"
	"net/http"
	"sync"
	time "time"

	"github.com/gorilla/websocket"
)

// Client represents a single WebSocket client connection.
type Client struct {
	conn *websocket.Conn
	mu   sync.Mutex // Mutex to protect writes to the connection
}

// Hub manages the WebSocket connections.
type Hub struct {
	clients    map[*Client]bool // Registered clients
	register   chan *Client     // Register requests from the clients
	unregister chan *Client     // Unregister requests from clients
	broadcast  chan []byte      // Inbound messages from clients to broadcast
}

// NewHub creates a new Hub instance.
func NewHub() *Hub {
	return &Hub{
		broadcast:  make(chan []byte),
		register:   make(chan *Client),
		unregister: make(chan *Client),
		clients:    make(map[*Client]bool),
	}
}

// Run starts the hub's operation.
func (h *Hub) Run() {
	for {
		select {
		case client := <-h.register:
			h.clients[client] = true
			log.Printf("Client registered: %s (total: %d)", client.conn.RemoteAddr(), len(h.clients))
		case client := <-h.unregister:
			if _, ok := h.clients[client]; ok {
				delete(h.clients, client)
				client.conn.Close()
				log.Printf("Client unregistered: %s (total: %d)", client.conn.RemoteAddr(), len(h.clients))
			}
		case message := <-h.broadcast:
			for client := range h.clients {
				client.mu.Lock() // Ensure only one write operation at a time for this client
				err := client.conn.WriteMessage(websocket.TextMessage, message)
				client.mu.Unlock()
				if err != nil {
					log.Printf("Error sending message to client %s: %v", client.conn.RemoteAddr(), err)
					client.conn.Close()
					delete(h.clients, client) // Remove client if sending fails
				}
			}
		}
	}
}

var upgrader = websocket.Upgrader{
	ReadBufferSize:  1024,
	WriteBufferSize: 1024,
	CheckOrigin: func(r *http.Request) bool { return true },
}

// ServeWs handles WebSocket requests from the peer.
func ServeWs(hub *Hub, w http.ResponseWriter, r *http.Request) {
	conn, err := upgrader.Upgrade(w, r, nil)
	if err != nil {
		log.Printf("Failed to upgrade connection: %v", err)
		return
	}

	client := &Client{conn: conn}
	hub.register <- client // Register the new client

	// Allow collection of old messages and prevent too many messages
	// from filling the Websocket send buffer.
	go client.writePump(hub)
	go client.readPump(hub)
}

// readPump pumps messages from the websocket connection to the hub.
func (c *Client) readPump(hub *Hub) {
	defer func() {
		hub.unregister <- c // Unregister on exit
		c.conn.Close()
	}()
	c.conn.SetReadLimit(512) // Max message size
	c.conn.SetReadDeadline(time.Now().Add(60 * time.Second)) // Set a deadline for pong messages
	c.conn.SetPongHandler(func(string) error {
		c.conn.SetReadDeadline(time.Now().Add(60 * time.Second)) // Reset deadline on pong
		return nil
	})

	for {
		_, message, err := c.conn.ReadMessage()
		if err != nil {
			if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseAbnormalClosure) {
				log.Printf("Error reading from client %s: %v", c.conn.RemoteAddr(), err)
			}
			break
		}
		hub.broadcast <- message // Send message to the hub for broadcasting
	}
}

// writePump pumps messages from the hub to the websocket connection.
func (c *Client) writePump(hub *Hub) {
	ticker := time.NewTicker(50 * time.Second) // Send pings periodically
	defer func() {
		ticker.Stop()
		c.conn.Close()
	}()
	for {
		select {
		case message, ok := <-hub.broadcast: // This is simplistic; real chat would send messages specifically for this client
			if !ok {
				// The hub closed the broadcast channel.
				c.mu.Lock()
				c.conn.WriteMessage(websocket.CloseMessage, []byte{})
				c.mu.Unlock()
				return
			}
			c.mu.Lock()
			err := c.conn.WriteMessage(websocket.TextMessage, message)
			c.mu.Unlock()
			if err != nil {
				log.Printf("Error writing message to client %s: %v", c.conn.RemoteAddr(), err)
				return // Exit writePump
			}
		case <-ticker.C:
			// Send a ping message to keep the connection alive.
			c.mu.Lock()
			err := c.conn.WriteMessage(websocket.PingMessage, nil)
			c.mu.Unlock()
			if err != nil {
				log.Printf("Ping error to client %s: %v", c.conn.RemoteAddr(), err)
				return // Exit writePump
			}
		}
	}
}

func main() {
	hub := NewHub()
	go hub.Run() // Start the hub in a goroutine

	http.HandleFunc("/ws", func(w http.ResponseWriter, r *http.Request) {
		ServeWs(hub, w, r)
	})

	log.Println("Chat server starting on :8080")
	err := http.ListenAndServe(":8080", nil)
	if err != nil {
		log.Fatalf("Server failed to start: %v", err)
	}
}

채팅 예제에서 추가된 주요 사항:

  1. Client 구조체: websocket.Conn과 단일 연결에 대한 스레드 안전 쓰기를 보장하기 위한 sync.Mutex를 캡슐화합니다.
  2. Hub 구조체:
    • clients: 모든 활성 Client 인스턴스를 저장하는 맵입니다.
    • register, unregister, broadcast: 클라이언트와 허브 간의 비동기 통신에 사용되는 채널입니다. 이를 통해 허브 작업(클라이언트 추가/제거, 브로드캐스트)이 동기화되고 스레드 안전하게 수행됩니다.
  3. Hub.Run(): 자체 goroutine에서 실행되며 register, unregister, broadcast 채널을 지속적으로 모니터링하여 들어오는 요청을 처리합니다.
  4. readPump 및 writePump:
    • 각 클라이언트에는 전용 readPump 및 writePump goroutine이 제공됩니다.
    • readPump: 클라이언트에서 메시지를 읽어 hub.broadcast 채널로 보냅니다. 또한 읽기 시간 초과 및 pong 메시지를 설정하여 연결을 유지합니다.
    • writePump: hub.broadcast 채널에서 클라이언트로 메시지를 보냅니다. 또한 주기적으로 클라이언트에게 ping 메시지를 보내 응답 없는 피어를 감지합니다.
  5. 동시성 및 동기화: 채널과 Client 연결의 sync.Mutex 사용은 경쟁 조건 없이 여러 클라이언트를 동시에 처리하는 데 중요합니다.

오류 처리 및 정상 종료

예제에서는 기본 오류 처리(오류 로깅, 연결 문제 시 루프 종료)를 보여줍니다. 프로덕션에서는 더 강력한 오류 복구, 잠재적인 재시도 및 포괄적인 로깅이 필요합니다. 클라이언트의 os.Interrupt에서와 같이 정상 종료는 리소스를 깨끗하게 해제하는 데 중요합니다.

유지보수를 위한 Ping/Pong

WebSocket에는 연결을 유지하고 응답하지 않는 피어를 감지하기 위한 ping/pong 프레임이 내장되어 있습니다. 채팅 서버 예제에는 readPump에서 SetReadDeadline 및 SetPongHandler를 포함하여 특정 시간 내에 pong을 기대하며, writePump에서는 PingMessage를 보내는 ticker를 포함하여 이를 구현합니다.

보안 고려 사항

  • CheckOrigin: 프로덕션에서는 Origin 헤더를 철저히 검증하여 사이트 간 WebSocket 하이재킹을 방지해야 합니다.
  • 인증/권한 부여: 기존 인증 시스템(예: 초기 HTTP 핸드셰이크의 JWT)과 통합하여 승인된 사용자만 WebSocket 연결을 설정하도록 합니다.
  • 입력 유효성 검사: 클라이언트로부터 받은 모든 메시지를 위생 및 유효성 검사하여 인젝션 공격 또는 잘못된 형식의 데이터를 방지합니다.
  • 속도 제한: 개별 클라이언트의 메시지 속도를 제한하여 서비스 거부 공격으로부터 보호합니다.

배포

역방향 프록시(Nginx 또는 Caddy와 같은) 뒤에 Go WebSocket 서버를 배포할 때 프록시가 WebSocket 업그레이드 및 영구 연결을 올바르게 처리하도록 구성해야 합니다. 이는 일반적으로 특정 헤더( Upgrade: websocket, Connection: upgrade) 구성을 포함합니다.

결론: 상호작용적인 Go 애플리케이션 강화

gorilla/websocket 라이브러리를 사용하면 Go 애플리케이션에 실시간 통신을 추가하는 것이 간단하고 효율적입니다. WebSocket의 핵심 개념을 이해하고 Goroutines와 채널을 활용하여 동시 클라이언트 관리를 통해 사용자 경험을 향상시키는 강력하고 상호작용적인 서비스를 구축할 수 있습니다. 간단한 에코 서버부터 복잡한 채팅 애플리케이션 및 그 이상까지, gorilla/websocket은 즉각적인 양방향 데이터 교환으로 Go 애플리케이션에 생기를 불어넣는 강력한 기반을 제공합니다. 이 라이브러리를 사용하여 정적인 상호작용을 동적이고 실시간 경험으로 변환하십시오.

Share this article

HackerNews

More Posts from Leapcell

Popular Posts