
이전 글에서는 gRPC의 직렬화 포맷인 Protocol Buffers에 대해 살펴보았습니다. 이번 글에서는 gRPC가 무엇인지, REST와 어떻게 다른지를 알아보고, Go로 첫 번째 gRPC 서버와 클라이언트를 구현해봅니다.
gRPC는 Google이 만든 고성능 RPC(Remote Procedure Call) 프레임워크입니다.
RPC는 원격 서버의 함수를 마치 로컬 함수처럼 호출하는 것입니다. 개발자 입장에서는 함수 호출처럼 보이지만, 내부적으로는 네트워크를 통해 원격 서버에서 실행됩니다.
이 과정을 gRPC가 모두 처리해줍니다.
| REST | gRPC | |
|---|---|---|
| 프로토콜 | HTTP/1.1 (또는 2.0) | HTTP/2.0 필수 |
| 데이터 포맷 | JSON (텍스트) | Protobuf (바이너리) |
| 인터페이스 정의 | OpenAPI/Swagger (선택) | .proto 파일 (필수) |
| 코드 생성 | 선택 | 필수 |
| 스트리밍 | 제한적 (WebSocket 등 우회) | 네이티브 지원 |
| 브라우저 지원 | 직접 가능 | 제한적 (grpc-web 필요) |
| 설계 방식 | 리소스 중심 (GET /todos/1) |
함수 중심 (GetTodo) |
REST는 리소스를 URL로 표현하고 HTTP 메서드로 동작을 구분합니다. gRPC는 함수(메서드)를 직접 정의하고 호출합니다.
gRPC는 IDL(Interface Definition Language) 로 .proto 파일을 사용합니다.
service TodoService {
rpc GetTodo (GetTodoRequest) returns (GetTodoResponse);
rpc CreateTodo (CreateTodoRequest) returns (CreateTodoResponse);
}
이 .proto 파일 하나로 서버와 클라이언트의 코드가 자동 생성됩니다. 서버 개발자는 생성된 인터페이스를 구현하고, 클라이언트 개발자는 생성된 클라이언트를 호출합니다. 서버와 클라이언트가 다른 언어여도 됩니다.
gRPC는 HTTP/2.0의 스트리밍을 활용하여 4가지 통신 패턴을 지원합니다. stream 키워드의 위치로 결정됩니다.
rpc GetTodo (GetTodoRequest) returns (GetTodoResponse);
REST와 동일한 구조입니다. 가장 기본적인 패턴입니다.
rpc ListTodos (ListTodosRequest) returns (stream Todo);
서버가 여러 응답을 스트림으로 전송합니다. 검색 결과를 한 건씩 스트리밍하거나, 실시간 로그를 전송할 때 사용합니다.
rpc CreateTodos (stream CreateTodoRequest) returns (TodoList);
클라이언트가 여러 요청을 스트림으로 보내고, 서버가 최종 응답을 반환합니다. 파일 업로드나 센서 데이터 일괄 전송에 사용합니다.
rpc Chat (stream ChatMessage) returns (stream ChatMessage);
양쪽 모두 동시에 스트림으로 주고받습니다. 두 스트림은 독립적이라 순서와 타이밍이 자유롭습니다. 채팅이나 실시간 게임에 사용합니다.
| 요청 | 응답 | 패턴 |
|---|---|---|
| 일반 | 일반 | Unary |
| 일반 | stream |
Server Streaming |
stream |
일반 | Client Streaming |
stream |
stream |
Bidirectional Streaming |
# protoc (protobuf 컴파일러)
brew install protobuf
# Go 플러그인 — protoc가 내부적으로 호출하는 CLI 도구
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
go install로 설치하는 이유는, 이들이 코드에서 import하는 라이브러리가 아니라 protoc가 호출하는 독립된 실행 파일이기 때문입니다. ~/go/bin/에 설치되므로 PATH에 포함되어 있어야 합니다.
grpc-1/
├── go.mod
├── todo/v1/
│ └── todo.proto ← 직접 작성하는 서비스/메시지 정의
├── pb/
│ ├── todo.pb.go ← protoc이 자동 생성 (메시지)
│ └── todo_grpc.pb.go ← protoc이 자동 생성 (서비스)
├── server/
│ └── main.go ← gRPC 서버
└── client/
└── main.go ← gRPC 클라이언트
syntax = "proto3";
package todo.v1;
option go_package = "/pb";
message Todo {
int32 id = 1;
string title = 2;
bool done = 3;
}
message GetTodoRequest {
int32 id = 1;
}
message GetTodoResponse {
Todo todo = 1;
}
message CreateTodoRequest {
string title = 1;
}
message CreateTodoResponse {
Todo todo = 1;
}
service TodoService {
rpc GetTodo(GetTodoRequest) returns (GetTodoResponse);
rpc CreateTodo(CreateTodoRequest) returns (CreateTodoResponse);
}
message로 주고받을 데이터를, service로 호출할 메서드를 정의합니다.
protoc --go_out=. --go-grpc_out=. \
--go_opt=module=grpc-1 --go-grpc_opt=module=grpc-1 \
todo/v1/todo.proto
pb/ 디렉토리에 두 파일이 생성됩니다:
todo.pb.go: Todo, GetTodoRequest 등 Go 구조체와 직렬화 코드todo_grpc.pb.go: TodoServiceServer 인터페이스, NewTodoServiceClient(), RegisterTodoServiceServer() 등이후 gRPC 라이브러리 의존성을 추가합니다:
go get google.golang.org/grpc
go get google.golang.org/protobuf
생성된 todo_grpc.pb.go에는 TodoServiceServer 인터페이스가 있습니다. 이 인터페이스를 구현하면 gRPC 서버가 됩니다.
package main
import (
"context"
"errors"
"log/slog"
"net"
"os"
"os/signal"
"syscall"
"google.golang.org/grpc"
"grpc-1/pb"
)
type todoServer struct {
pb.UnimplementedTodoServiceServer
todos []*pb.Todo
nextID int32
}
pb.UnimplementedTodoServiceServer를 임베딩합니다. 이것은 gRPC가 요구하는 패턴으로, 나중에 .proto에 새 메서드가 추가되어도 기존 서버 코드가 깨지지 않도록 하는 안전장치입니다. 구현하지 않은 메서드는 임베딩된 기본 구현이 "미구현" 에러를 반환합니다.
func (ts *todoServer) GetTodo(ctx context.Context, req *pb.GetTodoRequest) (*pb.GetTodoResponse, error) {
id := req.GetId()
for _, todo := range ts.todos {
if todo.GetId() == id {
return &pb.GetTodoResponse{Todo: todo}, nil
}
}
return &pb.GetTodoResponse{}, errors.New("index out of range")
}
req.GetId()는 protobuf가 자동 생성한 getter 메서드입니다. 슬라이스를 순회하며 ID가 일치하는 Todo를 찾아 반환합니다. 에러 메시지는 "찾지 못했다"보다는 "그 인덱스에 해당하는 요소가 없다"는 의미로 붙인 것인데, 돌아보면 sql.ErrNoRows처럼 더 명확한 이름이 나았을 것 같습니다.
func (ts *todoServer) CreateTodo(ctx context.Context, req *pb.CreateTodoRequest) (*pb.CreateTodoResponse, error) {
newTodo := pb.Todo{Id: ts.nextID, Title: req.Title, Done: false}
ts.nextID++
ts.todos = append(ts.todos, &newTodo)
return &pb.CreateTodoResponse{Todo: &newTodo}, nil
}
func main() {
listener, err := net.Listen("tcp", ":50051")
if err != nil {
slog.Error("server listener registration failed")
return
}
grpcServer := grpc.NewServer()
pb.RegisterTodoServiceServer(grpcServer, &todoServer{nextID: 1})
slog.Info("server started...")
go func() {
ch := make(chan os.Signal, 1)
signal.Notify(ch, os.Interrupt, syscall.SIGTERM)
<-ch
slog.Warn("graceful stop")
grpcServer.GracefulStop()
}()
grpcServer.Serve(listener)
}
grpcServer.Serve(listener)는 블로킹 호출이므로, graceful shutdown을 위한 시그널 대기는 별도 고루틴에서 처리합니다. GracefulStop()은 진행 중인 RPC가 완료될 때까지 기다린 후 서버를 종료합니다.
package main
import (
"context"
"fmt"
"log/slog"
"time"
"google.golang.org/grpc"
"google.golang.org/grpc/credentials/insecure"
"grpc-1/pb"
)
const timeout = 5
type clientPort struct {
pb.TodoServiceClient
}
TodoServiceClient 인터페이스를 임베딩한 clientPort 구조체로 클라이언트를 감쌉니다. 각 메서드에서 context 생성과 타임아웃 설정을 처리하여, 호출하는 쪽은 request만 넘기면 되도록 추상화합니다.
func (cp *clientPort) GetTodo(req *pb.GetTodoRequest) (*pb.GetTodoResponse, error) {
ctx, cancel := context.WithTimeout(context.Background(), time.Duration(timeout*time.Second))
defer cancel()
resp, err := cp.TodoServiceClient.GetTodo(ctx, req)
if err != nil {
return &pb.GetTodoResponse{}, err
}
return resp, nil
}
func (cp *clientPort) CreateTodo(req *pb.CreateTodoRequest) (*pb.CreateTodoResponse, error) {
ctx, cancel := context.WithTimeout(context.Background(), time.Duration(timeout*time.Second))
defer cancel()
resp, err := cp.TodoServiceClient.CreateTodo(ctx, req)
if err != nil {
return &pb.CreateTodoResponse{}, err
}
return resp, nil
}
func main() {
clientConn, err := grpc.NewClient("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
slog.Error("client connection failed")
return
}
defer clientConn.Close()
cp := clientPort{pb.NewTodoServiceClient(clientConn)}
getReq := pb.GetTodoRequest{Id: 1}
getResp, err := cp.GetTodo(&getReq)
if err != nil {
slog.Error("error occurred", "err", err)
}
slog.Info(fmt.Sprintf("[+] resp: %v", getResp))
createReq := pb.CreateTodoRequest{Title: "Todo List 1"}
createResp, err := cp.CreateTodo(&createReq)
if err != nil {
slog.Error("error occurred", "err", err)
}
slog.Info(fmt.Sprintf("[+] resp: %v", createResp))
slog.Info("server terminating...")
}
insecure.NewCredentials()는 TLS 없이 테스트 환경에서 사용합니다. 프로덕션에서는 TLS 인증서를 설정해야 합니다. 마지막의 slog.Info("server terminating...")은 사실 클라이언트 쪽 로그인데 이름을 그렇게 붙였습니다 — 아래 실행 결과의 마지막 줄이 이 호출입니다.
# 터미널 1 — 서버 시작
$ go run server/main.go
14:56:18 INFO server started...
# 터미널 2 — 클라이언트 실행
$ go run client/main.go
14:56:25 ERROR error occurred err="rpc error: code = Unknown desc = index out of range"
14:56:25 INFO [+] resp:
14:56:25 INFO [+] resp: todo:{id:1 title:"Todo List 1"}
14:56:25 INFO server terminating...
# 터미널 1 — Ctrl+C로 서버 종료
^C
14:56:32 WARN graceful stop
첫 번째 GetTodo(id=1)는 서버에 아직 Todo가 없어 에러가 반환되고, CreateTodo 후에는 정상적으로 Todo가 생성됩니다. 서버는 Ctrl+C(SIGINT) 수신 시 graceful shutdown됩니다.
다음 글에서는 gRPC의 스트리밍 패턴을 다뤄보겠습니다.