[G1-Sync] Manual knowledge update

10_Wiki/Topics/Coding/Backend_gRPC_Patterns.md

@@ -0,0 +1,149 @@
+---
+id: backend-grpc-patterns
+title: gRPC — Proto / Streaming / 인터셉터
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [backend, grpc, protobuf, streaming, vibe-coding]
+tech_stack: { language: "TS / Go / Java", applicable_to: ["Backend"] }
+applied_in: []
+aliases: [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 정의
+```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)
+```ts
+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
+```ts
+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)
+```ts
+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)
+```ts
+// 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)
+```ts
+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
+```proto
+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]]