2nd/10_Wiki/Topics/Coding/Backend_gRPC_Patterns.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
backend-grpc-patterns	gRPC — Proto / Streaming / 인터셉터	Coding	draft	B	conceptual	2026-05-09	2026-05-09	backend grpc protobuf streaming vibe-coding	language applicable_to TS / Go / Java Backend		protobuf gRPC stream unary server streaming bidi ConnectRPC

gRPC

Service-to-service RPC 표준. Proto schema → 타입 안전 코드 generate. HTTP/2 = 한 connection 다중 stream. JSON/REST 보다 빠르고 타입 안전. 브라우저 사용은 gRPC-Web 또는 ConnectRPC.

📖 핵심 개념

• 4 RPC 종류: unary / server stream / client stream / bidi stream.
• Proto3 syntax: enum / oneof / map / repeated.
• Interceptor: middleware (auth, logging, retry).
• Deadline: 모든 호출 timeout 명시.

💻 코드 패턴

Proto 정의

syntax = "proto3";
package user.v1;

service UserService {
  rpc GetUser(GetUserRequest) returns (User);
  rpc StreamUsers(ListUsersRequest) returns (stream User);
  rpc CreateUsers(stream CreateUserRequest) returns (BulkResult);
  rpc Chat(stream ChatMessage) returns (stream ChatMessage);
}

message User {
  string id = 1;
  string email = 2;
  google.protobuf.Timestamp created_at = 3;
  optional string name = 4;
}

message GetUserRequest { string id = 1; }

Server (Node + ts-proto + @grpc/grpc-js)

import * as grpc from '@grpc/grpc-js';

const server = new grpc.Server();
server.addService(UserServiceService, {
  getUser: async (call, cb) => {
    const u = await db.user.findUnique({ where: { id: call.request.id } });
    if (!u) return cb({ code: grpc.status.NOT_FOUND, message: 'user' });
    cb(null, u);
  },
  streamUsers: async (call) => {
    const it = db.user.streamAll();
    for await (const u of it) call.write(u);
    call.end();
  },
});

server.bindAsync('0.0.0.0:50051', grpc.ServerCredentials.createInsecure(), () => {
  server.start();
});

Client + deadline + retry

const client = new UserServiceClient('localhost:50051', grpc.credentials.createInsecure());

client.getUser({ id: 'u1' }, { deadline: Date.now() + 5000 }, (err, res) => {
  if (err?.code === grpc.status.NOT_FOUND) ...
});

Interceptor (auth)

const authInterceptor: grpc.Interceptor = (opts, nextCall) => {
    return new grpc.InterceptingCall(nextCall(opts), {
        start(metadata, listener, next) {
            metadata.add('authorization', `Bearer ${token}`);
            next(metadata, listener);
        },
    });
};

const client = new UserServiceClient(addr, creds, { interceptors: [authInterceptor] });

ConnectRPC (browser-friendly)

// HTTP/1+JSON, HTTP/2+protobuf 다 지원. CORS 친화.
import { createPromiseClient } from '@connectrpc/connect';
import { createConnectTransport } from '@connectrpc/connect-web';

const t = createConnectTransport({ baseUrl: 'https://api.example.com' });
const client = createPromiseClient(UserService, t);
const u = await client.getUser({ id: 'u1' });

Streaming (server-side)

const stream = client.streamUsers({});
stream.on('data', (u) => console.log(u));
stream.on('end', () => console.log('done'));
stream.on('error', (e) => console.error(e));

Versioning

package user.v1;
// 새 필드는 새 number 부여. 기존 number / type 절대 변경 금지.
// breaking 시 user.v2 새 패키지.

🤔 의사결정 기준

상황	추천
내부 service-to-service	gRPC
브라우저 호출	ConnectRPC / gRPC-Web
public REST API	REST or GraphQL
실시간 양방향	bidi stream / WebSocket
부분 업데이트	google.protobuf.FieldMask
Batching	repeated field 또는 client stream

❌ 안티패턴

• Deadline 없음: 영원히 hang.
• Stream cancel 안 함: 서버 자원 소진.
• Proto field number 재사용: prod 데이터 깨짐.
• enum 0 안 만들고 시작: default unknown 부재.
• Optional 안 쓰고 string 빈 문자열 = null: 모호.
• Server reflection prod 켬: schema 노출.
• TLS 없는 prod: token 노출.

🤖 LLM 활용 힌트

• Proto3 + ts-proto / buf 권장.
• ConnectRPC 가 modern + browser 친화.
• Deadline + Interceptor 항상.

🔗 관련 문서

• REST_API_Versioning_Strategies
• GraphQL_Server_Patterns
• Backend_API_Auth_Strategies