docs: update README.md to emphasize educational and AIoT pre-study goals
This commit is contained in:
@@ -1,84 +1,97 @@
|
||||
# grpccanary
|
||||
# grpccanary: gRPC & Multi-Agent Interface Study Repository
|
||||
|
||||
`grpccanary`는 Go 언어를 활용하여 데이터 직렬화(JSON)부터 HTTP 웹 서버, 그리고 최종적으로 gRPC 서버/클라이언트 호출까지 단계별로 학습할 수 있는 실습 프로젝트입니다.
|
||||
`grpccanary`는 Go 언어를 활용한 데이터 직렬화(JSON) ➡️ 웹 서버(HTTP/Gin) ➡️ 원격 프로시저 호출(gRPC)의 기본기를 단계별로 익힐 수 있는 학습용 실습 저장소입니다.
|
||||
|
||||
개념적인 상세 학습 자료 및 이론적 배경은 [docs/MANUSCRIPT.md](docs/MANUSCRIPT.md) 문서를 참고해 주시기 바랍니다.
|
||||
---
|
||||
|
||||
## 🎯 프로젝트 목적 및 배경
|
||||
|
||||
# gRPC 실행하기
|
||||
본 프로젝트는 단순한 학습 튜토리얼을 넘어 아래와 같은 명확한 지향점을 가지고 관리되고 있습니다.
|
||||
|
||||
이 리포지토리에 포함된 예제 코드를 사용해 gRPC 서버와 클라이언트를 실행하고 통신해 볼 수 있습니다.
|
||||
1. **gRPC 기반 AIoT 멀티 에이전트(Multi-Agent) 인터페이스 개발을 위한 사전 학습**
|
||||
- 사물인터넷(IoT) 환경과 지능형 에이전트들이 유기적으로 데이터를 주고받는 분산 AIoT 시스템을 설계하기 위해서는 빠르고, 가벼우며, 타입 안전성이 보장되는 통신 프로토콜이 필수적입니다.
|
||||
- 본 프로젝트는 추후 개발할 **gRPC 기반 AIoT 멀티 에이전트 인터페이스 모듈**의 핵심 통신 기법을 선제적으로 실습하고 검증하기 위한 기술적 초석입니다.
|
||||
2. **후배 개발자 교육 및 공동 협업을 위한 가이드북**
|
||||
- 사용자 본인의 지식 내재화뿐만 아니라, 함께 개발에 참여할 후배 개발자들의 빠른 온보딩(Onboarding)과 체계적인 백엔드 통신 교육 자료 제공을 주요 목적으로 합니다.
|
||||
- 이를 위해 단계적 예제와 한국어 주석, 상세 이론 원고([docs/MANUSCRIPT.md](docs/MANUSCRIPT.md))를 꼼꼼하게 구성해 두고 있습니다.
|
||||
|
||||
---
|
||||
|
||||
## 📂 프로젝트 구조 및 학습 단계 (3-Step Curriculum)
|
||||
|
||||
본 예제는 데이터의 형태를 정하는 기초적인 단계부터 고성능 네트워크 통신까지 난이도별로 3단계 학습을 진행할 수 있도록 구조화되어 있습니다.
|
||||
|
||||
## 1. 사전 준비사항
|
||||
gRPC를 구동하기 전에 아래 요구사항이 충족되었는지 확인하십시오:
|
||||
* **Go 설치 확인**: Go 버전이 1.25.4 이상이어야 합니다.
|
||||
```bash
|
||||
go version
|
||||
```
|
||||
* **의존성 모듈 설치**: 리포지토리 루트 디렉토리에서 다음 명령을 실행하여 필요한 Go 모듈들을 다운로드합니다:
|
||||
grpccanary/
|
||||
├── README.md # 본 프로젝트 종합 소개 및 실행 가이드 (교육용)
|
||||
├── go.mod / go.sum # Go 모듈 의존성 정의 (Go 1.25.4+)
|
||||
├── protoapi.proto # gRPC 인터페이스 정의서 (IDL)
|
||||
├── protoapi/ # protoc로 컴파일 생성된 Go Stub 코드
|
||||
├── examples/
|
||||
│ ├── main.go # 학습 예제 통합 실행 진입점 (수동 전환)
|
||||
│ ├── jsonexample/ # [1단계] encoding/json 표준 직렬화 예제
|
||||
│ ├── httpentity/ # [2단계] Gin-gonic 기반 HTTP API 서버 (WIP)
|
||||
│ └── grpcentity/ # [3단계] gRPC 서비스 구현체 (서버/클라이언트 데모)
|
||||
└── docs/
|
||||
└── MANUSCRIPT.md # JSON, HTTP, gRPC에 대한 통합 상세 개념서
|
||||
```
|
||||
|
||||
### 1단계: JSON 데이터 다루기 (`examples/jsonexample`)
|
||||
* Go 표준 라이브러리인 `encoding/json`을 활용하여 구조체(Struct)와 JSON 데이터 간의 마샬링(Serialization) 및 언마샬링(Deserialization) 기법을 학습합니다.
|
||||
|
||||
### 2단계: Gin 기반 HTTP 웹 서버 (`examples/httpentity`)
|
||||
* 대중적인 Go 웹 프레임워크 `gin-gonic`을 활용해 RESTful API 사양을 구축하는 방법을 이해합니다. (현재 주석 해제 후 실습하도록 설계된 Work-in-Progress 단계)
|
||||
|
||||
### 3단계: gRPC 통신 구현 (`examples/grpcentity`)
|
||||
* `.proto` 정의를 바탕으로 통신 스키마 계약을 강제하고, Go 언어로 gRPC 서버를 띄워 클라이언트가 날짜/시간, 무작위 비밀번호 및 정수 데이터를 실시간 원격 호출로 송수신하는 분산 통신 기초를 학습합니다.
|
||||
|
||||
---
|
||||
|
||||
## 🤖 AI 에이전트 협업 인프라 (`multi-agent-mux`)
|
||||
|
||||
본 저장소에는 학습용 Go 소스코드 외에도 **AI 에이전트(Claude, Cline 등)가 TMUX와 MQTT 브로커를 활용해 스스로 개발하고 검수하는 다중 에이전트 협업 인프라**가 함께 내장되어 있습니다.
|
||||
|
||||
* **[AGENTS.md](AGENTS.md)**: AI 코딩 에이전트가 코드를 안전하게 수정할 수 있도록 제한하는 핵심 행동 지침(Surgical Changes, Simplicity First)입니다.
|
||||
* **`.agents/MULTI_AGENT_RULES.ko.md`**: 총괄 매니저, 개발 팀장, 리뷰어 팀장 간의 역할 정의 및 비동기 작업 결재 루프 프로토콜을 다룹니다.
|
||||
* **[resume_all.sh](resume_all.sh)**: 로컬에서 멈춘 작업 에이전트의 세션을 동적으로 한 번에 복원해 주는 자동화 복구 스크립트입니다. (로컬 전용 헬퍼로 Git 추적에서 제외됨)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 실행 및 실습 방법
|
||||
|
||||
### 1. 사전 준비사항
|
||||
* Go 개발 환경이 필요합니다. (버전 **1.25.4 이상** 권장)
|
||||
* 리포지토리 루트에서 다음 명령어로 의존성 모듈을 설치합니다.
|
||||
```bash
|
||||
go mod download
|
||||
```
|
||||
|
||||
## 2. (선택) IDL 파일 컴파일 및 Stub 생성
|
||||
이미 컴파일된 stub 파일들(`protoapi/protoapi.pb.go`, `protoapi/protoapi_grpc.pb.go`)이 리포지토리에 기본 포함되어 있어 **이 단계를 건너뛰고 바로 실행할 수 있습니다.**
|
||||
만약 `.proto` 정의 파일을 직접 수정하고 코드를 다시 빌드하고 싶다면, 구체적인 `protoc` 설치 및 컴파일 절차는 [grpcentity README](examples/grpcentity/README.md) 가이드를 참고하여 진행해 주시기 바랍니다.
|
||||
### 2. 실습 예제 실행 방법 (진입점 전환)
|
||||
이 프로젝트는 교육적 목적을 위해 **하나의 `main.go` 파일 안에서 주석 처리를 통해 학습 단계를 수동 전환**하여 실행하도록 설계되어 있습니다.
|
||||
|
||||
## 3. 실습용 코드 준비 (main.go 편집)
|
||||
이 프로젝트의 진입점 파일인 `examples/main.go`는 기본적으로 JSON 파싱 예제만 실행하도록 설정되어 있습니다. gRPC 예제를 실행하기 위해서는 아래와 같이 진입점을 변경해야 합니다:
|
||||
|
||||
1. [examples/main.go](examples/main.go) 파일을 엽니다.
|
||||
2. `import` 블록에서 미사용 임포트 오류(`imported and not used`)를 방지하기 위해 `"grpccanary/examples/jsonexample"` 줄을 주석 처리(또는 삭제)하고, `main()` 함수에서 `grpcSample()`을 호출하도록 수정합니다.
|
||||
|
||||
**수정 후 코드 스니펫 예시:**
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
entity "grpccanary/examples/grpcentity"
|
||||
// "grpccanary/examples/jsonexample" // 미사용 임포트 주석 처리
|
||||
"time"
|
||||
)
|
||||
|
||||
var port = ":8080"
|
||||
|
||||
func main() {
|
||||
// jsonexample.JsonParsingExample() // 기존 JSON 예제 주석 처리
|
||||
grpcSample() // gRPC 예제 실행 호출로 변경
|
||||
}
|
||||
```
|
||||
3. 수정 내용을 저장합니다.
|
||||
|
||||
## 4. gRPC 예제 실행하기
|
||||
리포지토리 루트 디렉토리에서 다음 Go 실행 명령을 입력합니다:
|
||||
1. **[examples/main.go](examples/main.go)** 파일을 엽니다.
|
||||
2. 아래와 같이 실행하고자 하는 예제의 주석을 해제하고 다른 예제는 주석 처리합니다.
|
||||
* *JSON 예제 실행 시*: `jsonexample.JsonParsingExample()` 활성화
|
||||
* *gRPC 예제 실행 시*: `grpcSample()` 활성화 (미사용 import 에러를 피하기 위해 `jsonexample` import는 주석 처리 필요)
|
||||
3. 루트 디렉토리에서 다음 명령어로 실행합니다:
|
||||
```bash
|
||||
go run ./examples
|
||||
```
|
||||
|
||||
## 5. 기대 출력 결과
|
||||
명령어가 정상적으로 실행되면, `examples/main.go`에 정의된 `grpcSample()` 함수가 구동되어 백그라운드 고루틴으로 `:8080` 포트에서 gRPC 서버를 실행한 뒤, gRPC 클라이언트가 서버로 RPC 호출을 보냅니다. 터미널에는 아래와 유사한 출력 로그가 나타납니다:
|
||||
|
||||
### 3. gRPC 예제 동작 흐름 및 기대 출력
|
||||
gRPC 예제 실행 시, 서버가 백업 고루틴으로 `:8080` 포트에 대기한 후 클라이언트가 접속하여 다음과 같은 출력을 냅니다.
|
||||
```text
|
||||
Serving requests...
|
||||
Client:
|
||||
Server Date and Time: 2026-07-12 20:00:00.123456789 +0900 KST m=+1.000000001
|
||||
Server Date and Time: 2026-07-12 20:00:00.123456789 +0900 KST
|
||||
Random Password: &c(D7f/G#s%d
|
||||
Random Integer 1: 42
|
||||
Random Integer 2: 87
|
||||
```
|
||||
|
||||
* **동작 흐름**:
|
||||
1. 클라이언트가 서버의 `GetDate` 메서드를 호출하여 현재 날짜와 시간 문자열을 받아옵니다.
|
||||
2. 클라이언트가 `GetRandomPass` 메서드를 호출하여 무작위 비밀번호(`&c(D7f/G#s%d`)를 생성하여 받아옵니다.
|
||||
3. 클라이언트가 `GetRandom` 메서드를 두 차례 호출하여 각각 무작위 정수 값을 받아옵니다.
|
||||
---
|
||||
|
||||
## 6. 트러블슈팅 가이드
|
||||
* **`listen tcp :8080: bind: address already in use`**:
|
||||
이미 다른 프로세스가 `8080` 포트를 점유하고 있는 상태입니다. 점유 중인 프로세스를 종료하거나, `examples/main.go` 및 `examples/grpcentity/server.go`에서 `port` 변수 값을 다른 값(예: `:9090`)으로 변경한 후 다시 실행하십시오.
|
||||
* **`module grpccanary: package ... is not in GOROOT`**:
|
||||
모듈 로드 에러가 발생한 경우, 리포지토리 루트 경로(작업 디렉토리)에서 명령어를 올바르게 실행했는지 재확인하고, `go clean -modcache` 후 `go mod tidy`를 수행해 보십시오.
|
||||
|
||||
## 7. 다음 단계
|
||||
gRPC 동작 방식을 깊이 이해하고 통신 명세(IDL)를 확장해 보려면, [protoapi.proto](protoapi.proto)의 메시지 타입을 편집해 보거나 [grpcentity README](examples/grpcentity/README.md)로 이동해 다음 실습 단계를 탐색하십시오.
|
||||
## 📚 추가 학습 리소스
|
||||
|
||||
* **[docs/MANUSCRIPT.md](docs/MANUSCRIPT.md)**: JSON, HTTP, gRPC 통신의 원리와 배경지식(REST의 한계와 gRPC 도입 이유 등)을 담은 본 프로젝트 공식 개념서
|
||||
* **[examples/grpcentity/README.md](examples/grpcentity/README.md)**: Protobuf 빌드 컴파일 가이드 및 상세 소스코드 구현체 분석 자료
|
||||
|
||||
Reference in New Issue
Block a user