Godopu/grpccanary
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: split MANUSCRIPT.md into distinct JSON, HTTP, and GRPC documents

Browse Source
This commit is contained in:
Godopu
2026-07-17 13:20:32 +09:00
parent ab594e4391
commit f3c003fdf3
4 changed files with 273 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/GRPC.md
+131
View File
@@ -0,0 +1,131 @@
# gRPC & Protocol Buffers 심화 학습
이 문서는 `grpccanary` 프로젝트의 **3단계: gRPC 통신 구현**에 대한 이론적 배경, 스키마 명세, 컴파일 기법 및 구체적인 소스코드 분석을 설명합니다.
gRPC는 HTTP/2를 기반으로 구축된 구글의 고성능 오픈소스 원격 프로시저 호출(RPC) 시스템입니다. 사물인터넷(IoT) 장비나 에이전트 간의 데이터 통신 시 가볍고 구조화된 데이터 통신을 유지하는 데에 가장 적합한 프레임워크입니다.
---
## 1. gRPC 개요 및 기술 배경
### 1.1 gRPC의 핵심 차별점
* **강력한 스키마 계약**: `.proto` 파일 하나로 서비스 통신 규약을 명확히 선언하고, 컴파일 단계에서 이를 바탕으로 여러 언어의 클라이언트/서버 코드를 자동 생성합니다. 따라서 런타임 단계에서의 통신 필드 누락이나 타입 불일치 버그를 완벽하게 방지합니다.
* **이진 프로토콜 (바이너리 포맷)**: 텍스트가 아닌 컴팩트한 이진 형식을 사용하므로 데이터 크기가 매우 작고 네트워크 대역폭 리소스 효율이 뛰어납니다.
* **HTTP/2 기반**: 하나의 네트워크 커넥션을 재사용해 다중화(Multiplexing) 전송이 가능하고, 실시간 스트리밍(양방향 스트리밍 포함) 서비스에 탁월한 환경을 제공합니다.
### 1.2 Protobuf (프로토콜 버퍼)의 장단점
* **장점**
* **높은 전송 효율성**: 데이터 교환 시 텍스트가 아닌 바이너리 인코딩 형식을 사용하므로 JSON에 비해 직렬화/역직렬화 속도가 매우 빠르고 크기도 가볍습니다.
* **일관성 있는 코드 생성 (Stub)**: 동일한 정의서로부터 다국어 API 클라이언트를 빌드하여 중복 작성 오버헤드를 획득합니다.
* **하위 호환성**: 고유 필드 번호 매핑 방식을 사용하므로 스키마가 개정되어도 이전 시스템과의 통신 호환을 보장합니다.
* **단점**
* **가독성 부재**: 패킷이 암호화는 아니지만 바이너리로 전달되므로 사람이 브라우저 개발자 도구 등으로 바로 읽어 디버깅하기 곤란합니다.
* **빌드 종속성**: 명세 변경 시마다 Stub 코드를 컴파일하여 빌드에 바인딩하는 과정이 요구됩니다.
---
## 2. 인터페이스 명세서 (`protoapi.proto`)
저장소 루트의 [protoapi.proto](file:///home/godopu16/PuKi/lab/canary_projects/grpccanary/protoapi.proto) 파일은 의사 난수, 비밀번호, 날짜 데이터를 교환하는 `Random` 서비스를 제공하기 위해 아래와 같이 사양을 선언해 둡니다.
```proto
syntax = "proto3";
option go_package = "./protoapi/;protoapi";
service Random {
rpc GetDate (RequestDateTime) returns (DateTime);
rpc GetRandom (RandomParams) returns (RandomInt);
rpc GetRandomPass (RequestPass) returns (RandomPass);
}
message RandomParams {
int64 Seed = 1;
int64 Place = 2;
}
message RandomInt {
int64 Value = 1;
}
message DateTime {
string Value = 1;
}
message RequestDateTime {
string Value = 2;
}
message RequestPass {
int64 Seed = 1;
int64 Length = 8;
}
message RandomPass {
string Password = 1;
}
```
---
## 3. Go Stub 컴파일 및 도구 체인
`.proto` 파일을 Go 파일로 출력하기 위해 프로토콜 버퍼 컴파일러(`protoc`)와 플러그인이 로컬에 갖추어져야 합니다.
### 3.1 OS별 설치 가이드
* **macOS**:
```bash
brew install protobuf
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
```
* **Linux**:
```bash
sudo apt install -y protobuf-compiler
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
```
### 3.2 컴파일 실행 명령어
```bash
protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. \
--go-grpc_opt=paths=source_relative protoapi.proto
```
실행 결과로 `protoapi/` 아래에 `protoapi.pb.go`(메시지 정의)와 `protoapi_grpc.pb.go`(인터페이스 및 원격 호출)가 자동 생성됩니다.
---
## 4. 실습 코드 구현 상세 분석
### 4.1 gRPC 서버 구현 ([server.go](file:///home/godopu16/PuKi/lab/canary_projects/grpccanary/examples/grpcentity/server.go))
* **구조체 정의**:
```go
type RandomServer struct {
protoapi.UnimplementedRandomServer
}
```
`UnimplementedRandomServer`를 임베딩하여, 향후 메서드가 새로 추가되더라도 기존 서버가 빌드 에러 없이 최소한의 호환( unimplemented 에러 응답 )을 가지게 강제합니다.
* **서버 기동 흐름**:
```go
server := grpc.NewServer()
var randomServer RandomServer
protoapi.RegisterRandomServer(server, randomServer)
reflection.Register(server) // grpcurl 등 외부 디버깅 목적
listen, _ := net.Listen("tcp", port)
server.Serve(listen)
```
### 4.2 gRPC 클라이언트 구현 ([client.go](file:///home/godopu16/PuKi/lab/canary_projects/grpccanary/examples/grpcentity/client.go))
* **연결 수립**:
```go
conn, _ := grpc.Dial(addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
defer conn.Close()
client := protoapi.NewRandomClient(conn)
```
`insecure.NewCredentials()`를 전달하여 TLS를 건너뛴 채 평문으로 빠르고 간단한 로컬 테스트 환경을 구축합니다.
* **원격 호출**:
`client.GetDate()`, `client.GetRandom()`, `client.GetRandomPass()`를 차례로 호출하여 매개변수와 결과를 콘솔로 확인합니다.
docs/HTTP.md
+64
View File
@@ -0,0 +1,64 @@
# HTTP 프로토콜 & Gin 웹 프레임워크 학습
이 문서는 `grpccanary` 프로젝트의 **2단계: HTTP 서버 예제**에 대한 이론적 배경과 코드 구조를 설명합니다.
HTTP(Hypertext Transfer Protocol)는 클라이언트와 웹 서버가 웹에서 리소스를 교환하기 위해 정의한 규약입니다. Go 언어에서는 전통적인 `net/http` 표준 라이브러리 외에도, 성능이 우수하고 사용하기 쉬운 서드파티 웹 프레임워크인 **Gin-gonic**을 주로 사용하여 RESTful API를 신속하게 설계합니다.
---
## 1. REST API와 HTTP 통신
REST(Representational State Transfer)는 웹 상의 리소스를 HTTP 메서드(`GET`, `POST`, `PUT`, `DELETE` 등)와 URI 경로를 활용해 상태를 제어하는 아키텍처 스타일입니다.
* **JSON 데이터 연계**: 대다수의 HTTP REST API는 클라이언트와 데이터를 송수신할 때 데이터 교환 바디(Body)에 텍스트 기반의 **JSON 포맷**을 담아 통신합니다.
* **유연성과 한계**: JSON을 사용한 HTTP 통신은 어떤 기기에서나 쉽게 파싱이 가능해 클라이언트-서버 통신에 널리 쓰이지만, 엄격한 스키마 정의가 없어 타입 런타임 오류가 발생하기 쉽고 바이너리 통신에 비해 무겁다는 특징이 있습니다.
---
## 2. Gin 웹 프레임워크
Go 진영에서 대표적으로 사랑받는 웹 프레임워크 중 하나로, 빠른 속도와 미들웨어 체인 구성, 편리한 라우팅 그룹 관리 기능을 지원합니다.
### `gin.Default()` vs `gin.New()`
* **`gin.New()`**: 미들웨어가 탑재되지 않은 완전히 빈 라우터 엔진을 인스턴스화합니다. 성능에 민감하고 로깅이나 복구 미들웨어를 직접 커스텀할 때 활용합니다.
* **`gin.Default()`**: 기본적인 로깅 미들웨어(`gin.Logger()`)와 오류 복구 미들웨어(`gin.Recovery()`)가 사전 탑재된 상태로 기동되어 보통의 개발 시에 편리하게 사용됩니다.
---
## 3. 실습 코드 분석 (`examples/httpentity/server.go`)
저장소의 [server.go](file:///home/godopu16/PuKi/lab/canary_projects/grpccanary/examples/httpentity/server.go) 파일에는 Gin 라우터를 구성하고 API 서버와 정적 웹 서빙을 혼합하여 라우팅을 우회 처리하는 설계 패턴이 주석 상태로 존재합니다.
### 3.1 라우터 엔진 분리 및 통합 핸들링
```go
apiEngine := gin.New()
apiGroup := apiEngine.Group("/api")
{
apiGroup.GET("/randomNumber", GET_RandomNumber)
apiGroup.GET("/randomPassword", GET_RandomPassword)
apiGroup.GET("/randomDate", GET_RandomDate)
}
staticEngine := gin.New()
staticEngine.Static("/", "./web")
```
* **API 그룹 분리**: `/api`로 들어오는 모든 요청을 `apiEngine`이 받아서 각각 `/randomNumber`, `/randomPassword` 등의 실제 비즈니스 로직 핸들러로 전달하게 설계되어 있습니다.
* **정적 서빙**: 그 외의 요청에 대해서는 `./web` 경로의 정적 파일(HTML, CSS, JS)을 제공하기 위한 `staticEngine`을 별개 구성합니다.
* **단일 엔트리 우회**: 메인 엔진(`r`)은 전방위 라우팅 `/*any`를 구성하여, 경로 패턴에 `/api`가 들어있으면 API 엔진에 역할을 위임하고, 그렇지 않으면 정적 파일 서버로 포워딩합니다.
### 3.2 JSON 디코딩 및 API 핸들러
```go
func GET_RandomNumber(c *gin.Context) {
dec := json.NewDecoder(c.Request.Body)
obj := map[string]interface{}{}
dec.Decode(&obj)
response := map[string]interface{}{
"value": 10,
}
c.JSON(http.StatusOK, response)
}
```
* `c.Request.Body`를 `json.NewDecoder`로 받아서 맵에 디코딩하여 요청 매개변수(시드 등)를 취득합니다.
* 비즈니스 연산 후 `c.JSON()` 함수를 통해 원하는 응답 구조를 손쉽게 클라이언트에 JSON 문자열 형태로 내보내 줍니다.
docs/JSON.md
+59
View File
@@ -0,0 +1,59 @@
# Go 언어와 JSON 다루기
이 문서는 `grpccanary` 프로젝트의 **1단계: JSON 데이터 다루기**에 대한 이론적 배경과 코드 예시를 설명합니다.
Go 표준 라이브러리에는 JSON 데이터를 처리하기 위한 `encoding/json` 패키지가 포함되어 있습니다. Go는 구조체 태그(Struct Tag)를 사용하여 Go 구조체와 JSON 필드를 손쉽게 매핑할 수 있는 기능을 제공합니다. 이 태그는 Go 구조체를 JSON으로 변환하거나, JSON을 Go 구조체로 변환하는 과정을 제어합니다. 이 과정을 각각 **Marshaling**과 **Unmarshaling**이라고 부릅니다.
---
## 1. `Marshal()`과 `Unmarshal()` 이해하기
Go 구조체로 JSON 데이터를 다룰 때 핵심적인 과정입니다.
* **Marshaling (마샬링)**: Go 구조체(메모리 상의 데이터)를 JSON 바이트 슬라이스(`[]byte`, 텍스트 데이터)로 변환하는 과정입니다. 주로 API 응답으로 JSON을 보내거나, 데이터를 파일로 저장할 때 사용됩니다.
* **Unmarshaling (언마샬링)**: JSON 문자열/바이트 데이터를 Go 구조체 또는 맵 구조로 변환하는 과정입니다. 주로 외부 API로부터 받은 JSON 데이터를 다루거나 파일에서 데이터를 읽어올 때 사용됩니다.
> [!IMPORTANT]
> **자주 발생하는 필드 노출(Exported) 에러**
> `encoding/json` 패키지가 구조체의 필드에 접근하려면, 해당 필드는 **반드시 대문자로 시작해야 합니다 (Exported Field)**. 구조체 필드명이 소문자로 시작할 경우 JSON 파서가 이에 접근할 수 없어 Marshaling이나 Unmarshaling 시 값이 누락되는 문제가 발생합니다.
---
## 2. 실습 코드 분석 (`examples/jsonexample/json_parser.go`)
저장소의 [json_parser.go](file:///home/godopu16/PuKi/lab/canary_projects/grpccanary/examples/jsonexample/json_parser.go) 파일은 (1) `map[string]interface{}`와의 직렬화 및 (2) 구조체(`Person`)를 이용한 매핑 방식을 모두 다룹니다.
### 2.1 구조체 태그(Struct Tag) 정의
```go
type Person struct {
Name string `json:"name"`
Age int `json:"age"`
History []string `json:"history"`
}
```
* 필드 옆의 `` `json:"..."` `` 부분을 **구조체 태그**라고 부릅니다.
* 이 태그는 각 필드가 JSON 데이터에서 어떤 키(key) 이름과 1:1로 매핑되는지 매칭해 줍니다.
* Go 내부적으로는 대문자 필드(`Name`)를 쓰고, 외부 JSON 통신 규약으로는 소문자 키(`name`)를 사용하도록 매핑합니다.
### 2.2 Go 맵(`map`) 데이터 마샬링
```go
obj := map[string]interface{}{
"name": "홍길동",
"age": 623,
"history": []string{
"1900-양반집을 털었다",
"1910-왕에게 잡혀감",
},
}
b, err := json.Marshal(obj)
```
* 구조체뿐만 아니라 동적 타입 맵인 `map[string]interface{}` 데이터도 `json.Marshal()`을 통해 쉽게 JSON 문자열로 변환할 수 있습니다.
### 2.3 구조체 언마샬링
```go
var p2 Person
err = json.Unmarshal(b, &p2)
```
* `json.Unmarshal()` 함수는 바이트 슬라이스(`[]byte`) 형태의 JSON 데이터와, 결과를 받아올 변수의 **메모리 주소 포인터(`&p2`)**를 인자로 받습니다.
* 포인터를 넘겨주어야 함수 내부에서 값을 정상적으로 갱신하여 반환할 수 있습니다.
docs/MANUSCRIPT.md
+19 -151
View File
@@ -1,6 +1,18 @@
# gRPC 튜토리얼 원고 (Manuscript) # gRPC 튜토리얼 통합 개념서 (MANUSCRIPT)
본 문서는 `grpccanary` 프로젝트의 개념적 학습 자료를 모아둔 문서입니다. JSON 데이터 포맷의 이해부터 HTTP, 그리고 마이크로서비스 환경에서 gRPC가 왜 필요한지에 대한 상세한 배경을 설명합니다. 본 문서는 `grpccanary` 프로젝트의 전반적인 학습 경로와 각 단계별 통신 규약의 입문 배경을 설명하는 **통합 가이드북(GENERAL)**입니다.
각 장의 기초 개념을 습득한 후, 연결된 심화 학습 가이드를 통해 구체적인 코드 분석과 실습 가이드를 학습하실 수 있습니다.
---
## 🧭 학습 로드맵 및 가이드 바로가기
| 단계 | 실습 주제 | 심화 학습 가이드 링크 |
| :--- | :--- | :--- |
| **1단계** | JSON 데이터 직렬화 및 구조체 매핑 | [JSON 상세 가이드 (JSON.md)](JSON.md) |
| **2단계** | HTTP 프로토콜 및 Gin 웹 서버 라우팅 | [HTTP 상세 가이드 (HTTP.md)](HTTP.md) |
| **3단계** | gRPC 통신, Protobuf 컴파일 및 서버/클라이언트 구현 | [gRPC 상세 가이드 (GRPC.md)](GRPC.md) |
--- ---
@@ -8,6 +20,8 @@
JSON(JavaScript Object Notation)은 데이터를 구조화하여 전송하기 위해 널리 사용되는 가볍고 읽기 쉬운 텍스트 기반의 데이터 포맷입니다. 대부분의 현대 프로그래밍 언어에서 기본적으로 지원하며, 특히 HTTP 기반 REST API의 데이터 교환 규격으로 오랫동안 사랑받아 왔습니다. JSON(JavaScript Object Notation)은 데이터를 구조화하여 전송하기 위해 널리 사용되는 가볍고 읽기 쉬운 텍스트 기반의 데이터 포맷입니다. 대부분의 현대 프로그래밍 언어에서 기본적으로 지원하며, 특히 HTTP 기반 REST API의 데이터 교환 규격으로 오랫동안 사랑받아 왔습니다.
👉 **[Go 언어와 JSON 다루기 상세 학습 가이드 (JSON.md)](JSON.md)**
--- ---
## 2. HTTP란? ## 2. HTTP란?
@@ -17,6 +31,8 @@ HTTP(Hypertext Transfer Protocol)는 웹 브라우저와 웹 서버 간에 데
### `gin-gonic`을 이용한 http 서버 구현하기 ### `gin-gonic`을 이용한 http 서버 구현하기
Go 언어에서는 전통적인 `net/http` 표준 라이브러리 외에도, 성능이 뛰어나고 라우팅 기능이 강력한 `gin-gonic/gin` 프레임워크를 널리 활용하여 RESTful 웹 API 서버를 구축합니다. Go 언어에서는 전통적인 `net/http` 표준 라이브러리 외에도, 성능이 뛰어나고 라우팅 기능이 강력한 `gin-gonic/gin` 프레임워크를 널리 활용하여 RESTful 웹 API 서버를 구축합니다.
👉 **[HTTP 프로토콜 & Gin 웹 프레임워크 상세 학습 가이드 (HTTP.md)](HTTP.md)**
--- ---
## 3. gRPC란? ## 3. gRPC란?
@@ -40,152 +56,4 @@ REST와 JSON은 단순하고 사람이 읽기 쉽다는 훌륭한 장점이 있
* **바이너리 프로토콜**: 텍스트가 아닌 이진 데이터 형식을 사용하여 통신 속도가 JSON 방식에 비해 훨씬 빠르고 가볍습니다. * **바이너리 프로토콜**: 텍스트가 아닌 이진 데이터 형식을 사용하여 통신 속도가 JSON 방식에 비해 훨씬 빠르고 가볍습니다.
* **HTTP/2 기반**: 하나의 커넥션을 다중화(Multiplexing)하여 사용하므로 네트워크 리소스 효율성이 매우 높습니다. * **HTTP/2 기반**: 하나의 커넥션을 다중화(Multiplexing)하여 사용하므로 네트워크 리소스 효율성이 매우 높습니다.
--- 👉 **[gRPC & Protocol Buffers 상세 학습 가이드 (GRPC.md)](GRPC.md)**
## 4. gRPC 개요
위와 같이 gRPC가 고안된 배경과 필요성을 바탕으로, 구체적인 특징과 개발 프로세스를 살펴보겠습니다.
gRPC 서버와 클라이언트를 개발하는 과정은 크게 세 단계로 나뉩니다:
1. **인터페이스 정의 언어(IDL) 파일 생성**: 인터페이스를 계약(Contract)으로 정의합니다.
2. **gRPC 서버 개발**: 이 정의를 기반으로 서비스를 구현합니다.
3. **gRPC 클라이언트 개발**: 해당 서버와 통신하는 코드를 개발합니다.
### 4.1 장점
gRPC의 주요 장점은 다음과 같습니다:
* **빠른 데이터 교환**: 바이너리 데이터 형식을 사용하여 일반 텍스트 기반 서비스보다 훨씬 빠르게 데이터를 교환합니다.
* **간편한 개발 도구**: 풍부한 명령줄 도구들을 제공하여 개발 작업을 더욱 간단하고 신속하게 만듭니다.
* **쉬운 서버/클라이언트 생성**: gRPC 서비스의 함수와 메시지를 정의한 후에는 RESTful 서비스보다 서버와 클라이언트를 더 쉽게 생성할 수 있습니다.
* **스트리밍 지원**: 스트리밍 서비스에 효과적으로 활용될 수 있습니다.
* **세부 사항 자동 처리**: 데이터 교환의 복잡한 세부 사항을 gRPC가 자동으로 처리해주므로 개발자가 신경 쓸 필요가 없습니다.
> [!NOTE]
> 이 장점 목록만 보고 gRPC가 모든 문제의 완벽한 해결책이라고 오해해서는 안 됩니다. 항상 현재 작업에 가장 적합한 도구나 기술을 선택하는 것이 중요합니다.
### 4.2 프로토콜 버퍼 (Protobuf)
프로토콜 버퍼(Protobuf)는 구조화된 데이터를 효율적으로 직렬화하는 방법입니다. IDL(인터페이스 정의 언어) 역할을 하는 `.proto` 파일을 사용해 통신 규약을 명확히 정의합니다.
#### Protobuf의 주요 장단점
* **장점**
* **높은 전송 효율성**: 데이터 교환 시 텍스트 기반이 아닌 바이너리 형식을 사용하므로 JSON에 비해 데이터 크기가 매우 작고 직렬화/역직렬화 속도가 빠릅니다.
* **강력한 스키마 계약**: 하나의 정의 파일(`.proto`)로부터 다국어 클라이언트/서버 코드를 자동 생성(Stub 코드)하므로 컴파일 단계에서 타입 불일치 에러를 방지할 수 있습니다.
* **하위 호환성 유지**: 필드 번호를 기반으로 직렬화하므로 데이터 스키마가 업데이트되더라도 기존 시스템과의 호환성을 유연하게 보존합니다.
* **단점**
* **사람이 읽기 어려운 가독성 (Binary Format)**: 바이너리 형태로 데이터가 전송되므로, JSON처럼 네트워크 패킷을 사람이 직접 눈으로 확인하거나 텍스트 편집기로 디버깅하기 어렵습니다.
* **빌드 복잡성**: 스펙이 바뀔 때마다 `protoc` 컴파일러와 관련 플러그인을 활용하여 코드를 재생성(Stub 컴파일)해야 하는 추가적인 개발 파이프라인 단계가 필요합니다.
---
## 5. 실습: gRPC 기반 서비스 구현 및 컴파일
이 저장소에 기동되어 실행되는 gRPC 예제(`Random` 서비스)의 구체적인 IDL 명세와 컴파일, 그리고 구현 코드를 상세히 분석합니다.
### 5.1 인터페이스 정의 언어(IDL) `protoapi.proto` 분석
우리가 개발할 gRPC 서비스는 다음 기능을 제공합니다:
* 서버는 클라이언트에게 현재 날짜와 시간을 반환해야 합니다.
* 서버는 클라이언트에게 주어진 길이의 무작위 비밀번호를 반환해야 합니다.
* 서버는 클라이언트에게 무작위 정수를 반환해야 합니다.
이 통신 규약은 루트 디렉토리의 [protoapi.proto](file:///home/godopu16/PuKi/lab/canary_projects/grpccanary/protoapi.proto) 파일에 다음과 같이 기술되어 있습니다.
```proto
syntax = "proto3";
option go_package = "./protoapi/;protoapi";
service Random {
rpc GetDate (RequestDateTime) returns (DateTime);
rpc GetRandom (RandomParams) returns (RandomInt);
rpc GetRandomPass (RequestPass) returns (RandomPass);
}
message RandomParams {
int64 Seed = 1;
int64 Place = 2;
}
message RandomInt {
int64 Value = 1;
}
message DateTime {
string Value = 1;
}
message RequestDateTime {
string Value = 2;
}
message RequestPass {
int64 Seed = 1;
int64 Length = 8;
}
message RandomPass {
string Password = 1;
}
```
* **`syntax = "proto3"`**: 프로토콜 버퍼 언어의 proto3 버전을 활용합니다. 명시하지 않으면 구버전인 proto2로 인식되므로 파일 최상단에 반드시 기술해야 합니다.
* **`option go_package`**: 컴파일 시 Go 코드로 출력될 패키지의 이름을 `protoapi`로 지정하며, 출력 디렉토리를 `./protoapi/`로 명시합니다.
* **`service Random`**: 서버와 클라이언트가 사용할 3가지 RPC 메서드명(`GetDate`, `GetRandom`, `GetRandomPass`)과 해당 메서드들이 수용/반환할 메시지 포맷을 상호 정의합니다.
* **`message` 필드 및 태그**: 각 메시지 필드마다 데이터 타입(예: `int64`, `string`)과 바이너리 인코딩 시 키값 역할을 하는 고유 태그 번호(예: `= 1`, `= 2`)를 부여합니다.
### 5.2 Go에서 IDL 파일 컴파일 및 Stub 생성
`.proto` 정의를 실제 Go 소스 코드로 컴파일하려면 프로토콜 버퍼 컴파일러(`protoc`)와 Go용 플러그인(`protoc-gen-go`, `protoc-gen-go-grpc`)이 로컬 시스템에 설치되어 있어야 합니다.
#### 도구 설치 방법
* **macOS (Homebrew)**:
```bash
brew install protobuf
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
```
* **Linux (Ubuntu/Debian)**:
```bash
sudo apt install -y protobuf-compiler
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
```
#### 컴파일 실행 명령어
설치 완료 후 리포지토리 루트에서 다음 컴파일 명령어를 수행합니다:
```bash
protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. \
--go-grpc_opt=paths=source_relative protoapi.proto
```
* 이 실행을 통해 `protoapi/` 디렉토리 밑에 메시지 포맷 정의가 담긴 `protoapi.pb.go`와 gRPC 클라이언트/서버 인터페이스 및 메서드 껍데기가 들어있는 `protoapi_grpc.pb.go` 파일이 자동 생성됩니다.
### 5.3 gRPC 서버 구현 ([server.go](file:///home/godopu16/PuKi/lab/canary_projects/grpccanary/examples/grpcentity/server.go))
IDL을 통해 생성된 Go 패키지(`protoapi`)를 가져와 실제 비즈니스 로직을 수행할 gRPC 서버를 구현합니다.
* **구조체 정의**: `RandomServer` 구조체 타입을 선언하고 `protoapi.UnimplementedRandomServer`를 임베딩하여 gRPC 인터페이스 호환을 확보합니다.
* **비즈니스 메서드 구현**:
* **`GetDate`**: 현재 시간 문자열을 반환합니다.
* **`GetRandom`**: 시드값을 기반으로 지정된 위치에 있는 의사 난수를 반환합니다.
* **`GetRandomPass`**: 요청된 시드와 길이 매개변수를 활용해 무작위 비밀번호 문자열을 조립해 반환합니다.
* **서버 기동 (`ServerRun`)**:
* `grpc.NewServer()`로 서버 인스턴스를 확보하고 서비스를 등록합니다.
* 외부 디버깅 도구(예: `grpcurl` 등)가 인터페이스 사양을 동적으로 검색할 수 있도록 `reflection.Register(server)`를 호출해 리플렉션을 활성화합니다.
* `net.Listen("tcp", port)`를 통해 네트워크 채널을 열고 대기 상태(`server.Serve`)를 개시합니다.
### 5.4 gRPC 클라이언트 구현 ([client.go](file:///home/godopu16/PuKi/lab/canary_projects/grpccanary/examples/grpcentity/client.go))
서버에 원격 호출을 요청하고 응답 데이터를 가공해 출력하는 클라이언트 흐름입니다.
* **채널 접속**: `grpc.Dial` 함수를 통해 주소로의 연결 통로를 엽니다. 로컬 테스트 및 통신 단순화를 위해 평문(TLS 미적용) 커넥션(`insecure.NewCredentials()`)을 수립합니다.
* **클라이언트 인스턴스 생성**: `protoapi.NewRandomClient(conn)`를 통해 원격 서비스 호출 인터페이스 객체를 생성합니다.
* **호출 래퍼**: `AskingDateTime`, `AskPass`, `AskRandom` 등의 헬퍼 함수를 통해 실제 RPC 메서드에 요청 파라미터(시드, 길이 등)를 태워 호출합니다.
* **콘솔 출력 (`ClientRun`)**: 최종 수신한 시간, 생성된 무작위 비밀번호, 임의의 난수를 받아 콘솔 표준 출력에 정상 표시해 줍니다.
---
## 6. 참고 자료
* [gRPC와 REST의 차이점 (AWS)](https://aws.amazon.com/ko/compare/the-difference-between-grpc-and-rest/)