docs: add Random Service project introduction in GRPC.md and re-index sections
This commit is contained in:
+32
-13
@@ -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/)
|
||||
|
||||
Reference in New Issue
Block a user