From 50edea02251168ba59291f9d4aadeb93d7eb757e Mon Sep 17 00:00:00 2001 From: Godopu Date: Fri, 17 Jul 2026 15:44:22 +0900 Subject: [PATCH] docs: add Random Service project introduction in GRPC.md and re-index sections --- docs/GRPC.md | 45 ++++++++++++++++++++++++++++++++------------- 1 file changed, 32 insertions(+), 13 deletions(-) diff --git a/docs/GRPC.md b/docs/GRPC.md index e08f69d..543556b 100644 --- a/docs/GRPC.md +++ b/docs/GRPC.md @@ -28,9 +28,28 @@ gRPC는 HTTP/2를 기반으로 구축된 구글의 고성능 오픈소스 원격 --- -## 2. 인터페이스 명세서 (`protoapi.proto`) +## 2. 실습 프로젝트 소개: Random 데이터 서비스 -저장소 루트의 [protoapi.proto](../protoapi.proto) 파일은 의사 난수, 비밀번호, 날짜 데이터를 교환하는 `Random` 서비스를 제공하기 위해 아래와 같이 사양을 선언해 둡니다. +본 튜토리얼에서는 gRPC 분산 통신 기법을 실증적으로 학습하기 위해 가상의 **Random 데이터 API 서비스** 프로젝트를 직접 설계하고 구현해 나갑니다. + +### 2.1 프로젝트 시나리오 +사물인터넷(IoT) 센서 노드나 지능형 멀티 에이전트 분산 환경에서는 기기들이 중앙 서버에 접속해 상태 정보(날짜/시간)를 동기화하거나, 보안 패킷 전송을 위해 임시 원격 패스워드를 발급받고, 연산용 고유 난수를 안전하게 질의해야 하는 현실적인 통신 요건이 존재합니다. +우리가 개발할 `Random` 서비스는 이에 대응하는 다음 3가지 원격 프로시저(RPC)를 구현합니다: +1. **서버 시간 및 날짜 조회 (`GetDate`)**: 클라이언트가 요청 시 서버는 내부 시스템의 포맷팅된 시간 문자열을 가공하여 반환합니다. +2. **일회성 보안 패스워드 발급 (`GetRandomPass`)**: 클라이언트가 난수 시드와 바이트 길이를 명시하여 요청하면, 서버는 안전한 ASCII 비밀번호 문자열을 조립해 응답합니다. +3. **의사 난수 정수 생성 (`GetRandom`)**: 재현성을 위해 시드값과 시퀀스 위치를 인자로 전달받아 계산에 부합하는 정수 난수값을 연산해 반환합니다. + +### 2.2 학습 목표 및 진행 방법 +이 간단하면서도 긴밀한 데이터 파이프라인을 구축하는 실습을 통해 학습자는 다음 gRPC 지식 체계를 단계별로 마스터하게 됩니다: +* **스키마 설계**: `.proto` IDL 문법을 활용해 데이터 형식(Message)과 원격 함수(Service RPC) 계약을 강제하는 법을 습득합니다. +* **Stub 컴파일**: `protoc` 도구 체인을 가동하여 Go 프로그래밍 언어 소스코드를 안전하게 생성하고 프로젝트 빌드에 바인딩하는 기법을 배웁니다. +* **네트워크 구현**: 실제로 TCP 소켓을 확보하여 gRPC 서버를 실행하고, 클라이언트가 평문 커넥션을 수립하여 실시간 동기식 원격 프로시저를 직접 기동하는 엔드투엔드 구동 구조를 체득합니다. + +--- + +## 3. 인터페이스 명세서 (`protoapi.proto`) + +저장소 루트의 [protoapi.proto](../protoapi.proto) 파일은 앞서 설계한 `Random` 서비스를 구축하기 위해 아래와 같이 사양을 선언해 둡니다. ```proto syntax = "proto3"; @@ -72,11 +91,11 @@ message RandomPass { --- -## 3. Go Stub 컴파일 및 도구 체인 +## 4. Go Stub 컴파일 및 도구 체인 `.proto` 파일을 Go 파일로 출력하기 위해 프로토콜 버퍼 컴파일러(`protoc`)와 플러그인이 로컬에 갖추어져야 합니다. -### 3.1 OS별 설치 가이드 +### 4.1 OS별 설치 가이드 * **macOS**: ```bash brew install protobuf @@ -90,7 +109,7 @@ message RandomPass { go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest ``` -### 3.2 컴파일 실행 명령어 +### 4.2 컴파일 실행 명령어 ```bash protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. \ --go-grpc_opt=paths=source_relative protoapi.proto @@ -99,9 +118,9 @@ protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. \ --- -## 4. 실습 코드 구현 상세 분석 +## 5. 실습 코드 구현 상세 분석 -### 4.1 gRPC 서버 구현 ([server.go](../examples/grpcentity/server.go)) +### 5.1 gRPC 서버 구현 ([server.go](../examples/grpcentity/server.go)) * **구조체 정의**: ```go @@ -120,7 +139,7 @@ protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. \ server.Serve(listen) ``` -### 4.2 gRPC 클라이언트 구현 ([client.go](../examples/grpcentity/client.go)) +### 5.2 gRPC 클라이언트 구현 ([client.go](../examples/grpcentity/client.go)) * **연결 수립**: ```go @@ -132,7 +151,7 @@ protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. \ * **원격 호출**: `client.GetDate()`, `client.GetRandom()`, `client.GetRandomPass()`를 차례로 호출하여 매개변수와 결과를 콘솔로 확인합니다. -### 4.3 gRPC 실습 예제 동작 흐름 +### 5.3 gRPC 실습 예제 동작 흐름 예제가 구동되면 서버와 클라이언트 간에 다음과 같은 호출 시퀀스가 순차적으로 실행됩니다: 1. **날짜 조회 (`GetDate`)**: 클라이언트가 서버에 날짜 조회를 요청하고, 서버는 자체의 현재 날짜와 시간 문자열을 포맷하여 반환합니다. 2. **비밀번호 생성 (`GetRandomPass`)**: 클라이언트가 생성할 무작위 비밀번호의 길이(기본 8자)와 난수 생성 시드값을 전달하면, 서버는 지정된 사양의 임의 문자열을 작성해 반환합니다. @@ -140,11 +159,11 @@ protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. \ --- -## 5. 트러블슈팅 (Troubleshooting) +## 6. 트러블슈팅 (Troubleshooting) gRPC 서버 및 클라이언트 실습 과정에서 직면할 수 있는 대표적인 문제와 해결 방안입니다. -### 5.1 `listen tcp :8080: bind: address already in use` +### 6.1 `listen tcp :8080: bind: address already in use` * **원인**: 포트 `8080`이 이미 다른 백그라운드 프로세스나 기존 기동된 서버에 의해 점유되어 충돌이 난 상태입니다. * **해결 방법**: - `examples/main.go` 의 `port` 변수값과 [server.go](../examples/grpcentity/server.go)의 `port` 전역 변수값을 동시에 다른 포트(예: `:9090`)로 변경하고 재시도해야 합니다. @@ -152,7 +171,7 @@ gRPC 서버 및 클라이언트 실습 과정에서 직면할 수 있는 대표 --- -## 6. 다음 단계 (Next Steps) +## 7. 다음 단계 (Next Steps) gRPC 통신 방식을 한층 더 깊이 탐구해 보려면 다음과 같은 후속 실습을 추천합니다: 1. **메시지 스펙 확장**: 루트 디렉토리의 [protoapi.proto](../protoapi.proto)에 새로운 필드를 추가하거나 메서드를 정의한 뒤, Stub을 재컴파일([examples/grpcentity/README.md](../examples/grpcentity/README.md) 컴파일 가이드 참고)해 보십시오. @@ -160,6 +179,6 @@ gRPC 통신 방식을 한층 더 깊이 탐구해 보려면 다음과 같은 후 --- -## 7. 참고 자료 +## 8. 참고 자료 * [gRPC와 REST의 차이점 (AWS)](https://aws.amazon.com/ko/compare/the-difference-between-grpc-and-rest/)