🔌

gRPC 시작하기 - Client Streaming RPC

최민석·2026-04-15

gRPC 시작하기 - Client Streaming RPC

gRPC

🔌 gRPC with Go 시리즈

이전 글에서는 Server Streaming RPC를 다뤘습니다. 이번 글에서는 그 반대 방향인 Client Streaming RPC를 구현해봅니다. 클라이언트가 여러 요청을 스트림으로 보내고, 서버가 최종 응답 하나를 반환하는 패턴입니다.


Client Streaming이란

Server Streaming이 "요청 하나, 응답 여러 개"였다면, Client Streaming은 "요청 여러 개, 응답 하나" 입니다.

sequenceDiagram participant C as 클라이언트 participant S as 서버 C->>S: SumRequest (0) C->>S: SumRequest (1) C->>S: SumRequest (2) Note over C: ... C->>S: SumRequest (9) Note over C,S: 클라이언트가 스트림 종료 S-->>C: SumResponse (total: 45)

파일 업로드(청크 단위 전송), 센서 데이터 일괄 전송 등에 사용됩니다.


proto 파일 정의

syntax = "proto3";

package sum.v1;

option go_package = "/pb";

message SumRequest {
  int32 number = 1;
}

message SumResponse {
  int32 total = 1;
}

service SumService {
  rpc Sum(stream SumRequest) returns (SumResponse);
}

Server Streaming에서는 returns 쪽에 stream이 붙었지만, Client Streaming에서는 요청 쪽에 stream이 붙습니다.


세 가지 스트리밍 패턴의 시그니처 비교

protoc이 생성하는 서버 메서드 시그니처를 비교하면 패턴별 차이가 명확해집니다.

패턴 서버 메서드 시그니처
Unary Method(context.Context, *Request) (*Response, error)
Server Streaming Method(*Request, grpc.ServerStreamingServer[Response]) error
Client Streaming Method(grpc.ClientStreamingServer[Request, Response]) error

Client Streaming에서는 인자가 stream 객체 하나뿐입니다. 요청도 스트림에서 Recv()로 받고, 응답도 스트림의 SendAndClose()로 보냅니다.


서버 구현

type SumServer struct {
    pb.UnimplementedSumServiceServer
}

func (ss *SumServer) Sum(s grpc.ClientStreamingServer[pb.SumRequest, pb.SumResponse]) error {
    var total int = 0
    for {
        req, err := s.Recv()
        if err != nil {
            if errors.Is(err, io.EOF) {
                s.SendAndClose(&pb.SumResponse{Total: int32(total)})
                return nil
            } else {
                return status.Error(codes.DataLoss, "receive failed")
            }
        }
        total += int(req.GetNumber())
    }
}

Server Streaming에서는 서버가 Send를 루프로 여러 번 호출했습니다. Client Streaming에서는 반대로 서버가 Recv를 루프로 여러 번 호출합니다.

  • s.Recv(): 클라이언트가 보낸 값을 하나씩 수신. 블로킹
  • io.EOF: 클라이언트가 스트림을 종료했다는 신호
  • s.SendAndClose(): 최종 응답을 보내고 스트림을 닫음

total을 함수 내 지역 변수로 선언한 것에 주목하세요. 구조체 필드로 두면 여러 클라이언트가 동시에 호출할 때 값이 섞입니다.


클라이언트 구현

client := pb.NewSumServiceClient(conn)
stream, err := client.Sum(context.Background())
if err != nil {
    // 에러 처리
}

for i := range int32(10) {
    time.Sleep(2 * time.Second)
    slog.Info(color.GreenString(fmt.Sprintf("[+] sending %v ...", i)))
    stream.Send(&pb.SumRequest{Number: i})
}

resp, err := stream.CloseAndRecv()
if err != nil {
    // 에러 처리
}
slog.Info(color.CyanString(fmt.Sprintf("[$] result: %v", resp.Total)))
  • client.Sum(): 스트림 객체를 얻음
  • stream.Send(): 요청을 여러 번 전송
  • stream.CloseAndRecv(): 스트림을 닫고 서버의 최종 응답을 수신

Server Streaming에서 클라이언트가 Recv 루프를 돌았던 것과 대칭입니다. Client Streaming에서는 클라이언트가 Send 루프를 돌고 CloseAndRecv로 마무리합니다.


Send/Recv 패턴 정리

지금까지 다룬 세 가지 패턴에서 서버와 클라이언트가 각각 어떤 메서드를 사용하는지 정리해봅니다.

패턴 서버 클라이언트
Unary 인자로 받고 반환 호출하고 반환값 받음
Server Streaming Send 루프 → return nil Recv 루프 → io.EOF로 종료
Client Streaming Recv 루프 → SendAndClose Send 루프 → CloseAndRecv

실행 결과

# 터미널 1 — 서버 시작
$ go run server/main.go
09:31:14 INFO [*] server starting...

# 터미널 2 — 클라이언트 실행
$ go run client/main.go
09:31:22 INFO [+] sending 0 ...
09:31:24 INFO [+] sending 1 ...
09:31:26 INFO [+] sending 2 ...
09:31:28 INFO [+] sending 3 ...
09:31:30 INFO [+] sending 4 ...
09:31:32 INFO [+] sending 5 ...
09:31:34 INFO [+] sending 6 ...
09:31:36 INFO [+] sending 7 ...
09:31:38 INFO [+] sending 8 ...
09:31:40 INFO [+] sending 9 ...
09:31:40 INFO [$] result: 45

2초 간격으로 0~9를 스트림으로 전송한 뒤, 서버가 합계 45를 계산하여 최종 응답으로 반환했습니다.

다음 글에서는 gRPC의 마지막 통신 패턴인 Bidirectional Streaming RPC를 다뤄보겠습니다.

관련 포스트