docs(10_Wiki): 위키 전체 재구성 — Topic_* 폴더를 4개 카테고리로 통합 + 대규모 중복 제거
Topic_Agent/Topic_Blog/Topics/Topics_Biz/Topics_Meeting/Topics_Rag의 마크다운 지식 문서를 Topic_General/Topic_Programming/Topic_Graphic/Topic_Business 4개 카테고리로 재분류. - 중복 제거: frontmatter의 status:duplicate/merged + duplicate_of/redirect_to 필드로 자기 자신을 중복으로 선언한 리다이렉트 stub 1032개 제거, 완전 동일 내용 파일 472개 제거, 동일 파일명·다른 내용 충돌 시 더 큰(완전한) 버전만 유지(162개 제거) — 총 1639개 중복 제거. - 분류: 폴더 단위로 명확한 항목(AI_and_ML/Coding/Architecture 등 → Programming, Comfyui/Visual_Effects → Graphic, Topics_Biz/Topics_Meeting/사업 등 → Business, Poetic_Blog_Writing/창의성/Game_Design 등 → General)은 폴더 우선순위로, 나머지 혼재 폴더(Topic_Agent/Topic_Blog/Topics 루트/Thinking & Reasoning/Other/UI_UX_Assets)는 title/tags 키워드 스코어링으로 파일 단위 분류(불명확한 경우 General로 폴백). 원본 폴더명은 "From_*" 서브폴더로 보존해 추적 가능성 유지. - 최종 배치: Programming 2784 / General 1608 / Graphic 285 / Business 249 = 4926개 문서. - 에이전트 운영 상태(.astra/.agent/.obsidian/sessions/memory/_company/docs/lessons/_shared/src)는 지식 콘텐츠가 아니므로 재분류 대상에서 제외하고 원위치 유지. - Topics/Topic_email(상위 보호 폴더 Topic_email과 파일명 100% 중복) 삭제 — 보호 폴더 자체는 미변경. - 완전히 비게 된 Topic_Agent/Topic_Blog/Topics_Biz/Topics_Rag 폴더 제거.
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,146 @@
|
||||
---
|
||||
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 항상.
|
||||
|
||||
## 🔗 관련 문서
|
||||
Reference in New Issue
Block a user