refactor(topics): 멀티 에이전트용 지식 재편 — _Common(공통 기본기) + Domain_* 구조
에이전트 8종(대화형/프로그래머 C·S/디자이너/설계자/기획자/QA/PD/PM)에게 [공통 기본 능력 + 롤별 Specialty] 2층으로 지식을 주입하기 위한 재분류. 문서 내용·포맷은 무수정, 폴더 이동만 (6,372개 문서 수 보존 확인). - Topic_Programming → Domain_Programming (내부 구조 보존) - Topic_Graphic → Domain_Design - Topic_Business → Domain_Product - Topic_General → Domain_General - _Common 신설: Math(구 Topic_Math_Specialty), Reasoning(구 General/From_Thinking & Reasoning), Reasoning_Creativity(구 General/From_창의성), Communication(Poetic_Blog_Writing + From_writing) - 타 도메인의 From_* 폴더는 유지 (출처 표기일 뿐, 이미 도메인에 맞게 분류된 문서) - 빈 폴더 정리 (memory/procedures) - 에이전트→폴더 매핑은 workspace의 .astra/agent-knowledge-map.json (9개 에이전트) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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