From 5e6f7defd3e590ecc21579b168e1af52e686fcae Mon Sep 17 00:00:00 2001 From: Godopu Date: Fri, 17 Jul 2026 11:37:09 +0900 Subject: [PATCH] docs: refactor docs structure by splitting README.md and update .gitignore --- .gitignore | 15 +++++++++ README.md | 79 ++-------------------------------------------- docs/MANUSCRIPT.md | 74 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 92 insertions(+), 76 deletions(-) create mode 100644 .gitignore create mode 100644 docs/MANUSCRIPT.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8646416 --- /dev/null +++ b/.gitignore @@ -0,0 +1,15 @@ +.agents/ +.mam/ +.env +.env.example +AGENTS.md +BOOTSTRAP.ko.md +BOOTSTRAP.md +MESSAGING.md +remove.sh +update.sh +# Python virtual environment +/.venv/ + +# Workspace-specific scripts +/resume_all.sh diff --git a/README.md b/README.md index 28d4175..b35120e 100644 --- a/README.md +++ b/README.md @@ -1,77 +1,8 @@ -# JSON이란? +# grpccanary +`grpccanary`는 Go 언어를 활용하여 데이터 직렬화(JSON)부터 HTTP 웹 서버, 그리고 최종적으로 gRPC 서버/클라이언트 호출까지 단계별로 학습할 수 있는 실습 프로젝트입니다. -# HTTP란? - -## `gin-gonic`을 이용한 http 서버 구현하기 - -- 참고 자료 - -# gRPC란? - -이번 장에서는 Go 언어에서 gRPC를 어떻게 활용하는지 전반적으로 살펴보겠습니다. - -### gRPC가 필요한 이유: 어느 개발팀의 이야기 - -어느 날, 성장하는 스타트업의 백엔드 개발자 민우는 골치 아픈 버그를 마주했습니다. 서비스가 마이크로서비스 아키텍처(MSA)로 전환되면서, 회원 서비스(Go)와 주문 서비스(Python)가 서로 HTTP/JSON API로 통신하기 시작했는데, 최근 회원 서비스의 응답 필드 이름이 `user_id`에서 `userId`로 변경되면서 주문 서비스가 마비된 것입니다. - -"사전 공유가 누락되었네요. 죄송합니다..." 회원 담당 팀원의 사과로 버그는 금방 고쳐졌지만, 민우는 근본적인 질문을 던지게 되었습니다. -'왜 서비스 간의 통신 규칙(계약)을 코드 레벨에서 강제할 수 없을까?' - -REST와 JSON은 단순하고 사람이 읽기 쉽다는 훌륭한 장점이 있어 인터넷망을 통한 클라이언트-서버 통신에 널리 쓰입니다. 하지만 대규모 마이크로서비스 환경에서 시스템 내부의 서비스 간 통신(Internal RPC)용으로는 다음과 같은 한계를 드러내곤 합니다: -1. **느슨한 계약(Loose Contract)**: API 스펙 문서가 최신화되지 않으면 언제든 타입 오류나 필드 누락으로 인한 런타임 에러가 발생할 수 있습니다. -2. **비효율적인 직렬화**: 텍스트 기반의 JSON 데이터는 컴퓨터가 처리하기에 너무 무겁고, 네트워크 대역폭도 많이 차지합니다. -3. **반복되는 클라이언트 코드 작성**: 파트너 서비스가 고유한 API를 제공할 때마다, 이를 호출하기 위한 HTTP 클라이언트 패키지 코드를 다국어별로 매번 새로 작성해야 합니다. - -이러한 문제들을 해결하기 위해 구글은 **gRPC**를 개발했습니다. gRPC는 다음과 같은 차별점을 통해 민우가 겪었던 어려움을 해결해 줍니다: -- **프로토콜 버퍼(Protobuf) 기반의 강력한 스키마 계약**: `.proto` 파일 하나로 서비스 통신 규약을 선언하고, 이를 컴파일하여 여러 프로그래밍 언어의 구체적인 클라이언트/서버 코드를 자동으로 생성합니다. 즉, 컴파일 단계에서 스키마 계약 불일치 오류를 차단합니다. -- **바이너리 프로토콜**: 텍스트가 아닌 이진 데이터 형식을 사용하여 통신 속도가 JSON 방식에 비해 훨씬 빠르고 가볍습니다. -- **HTTP/2 기반**: 하나의 커넥션을 다중화(Multiplexing)하여 사용하므로 네트워크 리소스 효율성이 매우 높습니다. - -### gRPC 개요 - -위와 같이 gRPC가 고안된 배경과 필요성을 바탕으로, 구체적인 특징과 개발 프로세스를 살펴보겠습니다. - -gRPC 서버와 클라이언트를 개발하는 과정은 크게 세 단계로 나뉩니다. 첫째, 인터페이스 정의 언어(IDL) 파일을 생성하여 인터페이스를 계약(Contract)으로 정의합니다. 둘째, 이 정의를 기반으로 gRPC 서버를 개발합니다. 셋째, 해당 서버와 통신할 gRPC 클라이언트를 개발합니다. - -### 다룰 주제 - -이번 장에서는 다음 주제들을 다룹니다: - -- gRPC 소개 -- 인터페이스 정의 언어(IDL) 파일 정의 -- gRPC 서버 개발 -- gRPC 클라이언트 개발 - -## gRPC 소개 - -gRPC의 이점과 프로토콜 버퍼에 대해 자세히 알아보겠습니다. - -gRPC는 2015년 구글이 개발한 오픈소스 원격 프로시저 호출(RPC) 시스템입니다. HTTP/2를 기반으로 구축되어 서비스 개발을 용이하게 하며, 메시지 형식과 서비스 인터페이스를 정의하는 IDL(인터페이스 정의 언어)로 프로토콜 버퍼를 사용합니다. - -gRPC 클라이언트와 서버는 서로 다른 프로그래밍 언어로 작성될 수 있습니다. 예를 들어, gRPC 서버가 Go 언어로 구현되었더라도 클라이언트는 Python으로 개발할 수 있습니다. 지원되는 프로그래밍 언어는 Python, Java, C++, C#, PHP, Ruby, Kotlin 등 다양합니다. - -### 장점 - -gRPC의 주요 장점은 다음과 같습니다: - -- **빠른 데이터 교환**: 바이너리 데이터 형식을 사용하여 일반 텍스트 기반 서비스보다 훨씬 빠르게 데이터를 교환합니다. -- **간편한 개발 도구**: 풍부한 명령줄 도구들을 제공하여 개발 작업을 더욱 간단하고 신속하게 만듭니다. -- **쉬운 서버/클라이언트 생성**: gRPC 서비스의 함수와 메시지를 정의한 후에는 RESTful 서비스보다 서버와 클라이언트를 더 쉽게 생성할 수 있습니다. -- **스트리밍 지원**: 스트리밍 서비스에 효과적으로 활용될 수 있습니다. -- **세부 사항 자동 처리**: 데이터 교환의 복잡한 세부 사항을 gRPC가 자동으로 처리해주므로 개발자가 신경 쓸 필요가 없습니다. - -> 참고: 이 장점 목록만 보고 gRPC가 모든 문제의 완벽한 해결책이라고 오해해서는 안 됩니다. 항상 현재 작업에 가장 적합한 도구나 기술을 선택하는 것이 중요합니다. - -다음 섹션에서는 gRPC 서비스의 핵심 기반 기술인 프로토콜 버퍼에 대해 자세히 알아보겠습니다. - -### 프로토콜 버퍼 - -프로토콜 버퍼(Protobuf)는 구조화된 데이터를 효율적으로 직렬화하는 방법입니다. Protobuf는 IDL(인터페이스 정의 언어)의 일부로, 데이터 교환 시 바이너리 형식을 사용하기 때문에 일반 텍스트 기반 직렬화 형식보다 훨씬 적은 공간을 차지합니다. 하지만 데이터를 기계가 사용하고 사람이 읽을 수 있도록 하려면 각각 인코딩과 디코딩 과정이 필요합니다. Protobuf는 각 프로그래밍 언어에서 기본적으로 지원하는 데이터 타입으로 변환되는 자체 데이터 타입을 제공합니다. - -![alt text](README.assets/images/proto_buf.png) - -일반적으로 IDL 파일은 모든 gRPC 서비스의 핵심입니다. 이는 데이터 교환 형식과 서비스 인터페이스를 정의하기 때문입니다. Protobuf 파일 없이는 gRPC 서비스를 구축할 수 없습니다. 더 정확히 말하면, Protobuf 파일에는 서비스 정의, 서비스 메서드, 그리고 교환될 메시지 형식이 모두 포함됩니다. 따라서 gRPC 서비스를 이해하려면 해당 정의 파일을 살펴보는 것이 가장 중요하다고 할 수 있습니다. 다음 레슨에서는 우리가 만들 gRPC 서비스에 사용될 Protobuf 파일을 자세히 보여드릴 것입니다. +개념적인 상세 학습 자료 및 이론적 배경은 [docs/MANUSCRIPT.md](docs/MANUSCRIPT.md) 문서를 참고해 주시기 바랍니다. # gRPC 실행하기 @@ -151,7 +82,3 @@ Random Integer 2: 87 ## 7. 다음 단계 gRPC 동작 방식을 깊이 이해하고 통신 명세(IDL)를 확장해 보려면, [protoapi.proto](protoapi.proto)의 메시지 타입을 편집해 보거나 [grpcentity README](examples/grpcentity/README.md)로 이동해 다음 실습 단계를 탐색하십시오. - -# 참고 자료 - -- https://aws.amazon.com/ko/compare/the-difference-between-grpc-and-rest/ \ No newline at end of file diff --git a/docs/MANUSCRIPT.md b/docs/MANUSCRIPT.md new file mode 100644 index 0000000..aeb60c9 --- /dev/null +++ b/docs/MANUSCRIPT.md @@ -0,0 +1,74 @@ +# gRPC 튜토리얼 원고 (Manuscript) + +본 문서는 `grpccanary` 프로젝트의 개념적 학습 자료를 모아둔 문서입니다. JSON 데이터 포맷의 이해부터 HTTP, 그리고 마이크로서비스 환경에서 gRPC가 왜 필요한지에 대한 상세한 배경을 설명합니다. + +--- + +## 1. JSON이란? + +JSON(JavaScript Object Notation)은 데이터를 구조화하여 전송하기 위해 널리 사용되는 가볍고 읽기 쉬운 텍스트 기반의 데이터 포맷입니다. 대부분의 현대 프로그래밍 언어에서 기본적으로 지원하며, 특히 HTTP 기반 REST API의 데이터 교환 규격으로 오랫동안 사랑받아 왔습니다. + +--- + +## 2. HTTP란? + +HTTP(Hypertext Transfer Protocol)는 웹 브라우저와 웹 서버 간에 데이터를 주고받기 위한 통신 프로토콜입니다. + +### `gin-gonic`을 이용한 http 서버 구현하기 +Go 언어에서는 전통적인 `net/http` 표준 라이브러리 외에도, 성능이 뛰어나고 라우팅 기능이 강력한 `gin-gonic/gin` 프레임워크를 널리 활용하여 RESTful 웹 API 서버를 구축합니다. + +--- + +## 3. gRPC란? + +Go 언어에서 gRPC를 어떻게 활용하는지 전반적으로 살펴보겠습니다. + +### gRPC가 필요한 이유: 어느 개발팀의 이야기 + +어느 날, 성장하는 스타트업의 백엔드 개발자 민우는 골치 아픈 버그를 마주했습니다. 서비스가 마이크로서비스 아키텍처(MSA)로 전환되면서, 회원 서비스(Go)와 주문 서비스(Python)가 서로 HTTP/JSON API로 통신하기 시작했는데, 최근 회원 서비스의 응답 필드 이름이 `user_id`에서 `userId`로 변경되면서 주문 서비스가 마비된 것입니다. + +"사전 공유가 누락되었네요. 죄송합니다..." 회원 담당 팀원의 사과로 버그는 금방 고쳐졌지만, 민우는 근본적인 질문을 던지게 되었습니다. +'왜 서비스 간의 통신 규칙(계약)을 코드 레벨에서 강제할 수 없을까?' + +REST와 JSON은 단순하고 사람이 읽기 쉽다는 훌륭한 장점이 있어 인터넷망을 통한 클라이언트-서버 통신에 널리 쓰입니다. 하지만 대규모 마이크로서비스 환경에서 시스템 내부의 서비스 간 통신(Internal RPC)용으로는 다음과 같은 한계를 드러내곤 합니다: +1. **느슨한 계약(Loose Contract)**: API 스펙 문서가 최신화되지 않으면 언제든 타입 오류나 필드 누락으로 인한 런타임 에러가 발생할 수 있습니다. +2. **비효율적인 직렬화**: 텍스트 기반의 JSON 데이터는 컴퓨터가 처리하기에 너무 무겁고, 네트워크 대역폭도 많이 차지합니다. +3. **반복되는 클라이언트 코드 작성**: 파트너 서비스가 고유한 API를 제공할 때마다, 이를 호출하기 위한 HTTP 클라이언트 패키지 코드를 다국어별로 매번 새로 작성해야 합니다. + +이러한 문제들을 해결하기 위해 구글은 **gRPC**를 개발했습니다. gRPC는 다음과 같은 차별점을 통해 민우가 겪었던 어려움을 해결해 줍니다: +* **프로토콜 버퍼(Protobuf) 기반의 강력한 스키마 계약**: `.proto` 파일 하나로 서비스 통신 규약을 선언하고, 이를 컴파일하여 여러 프로그래밍 언어의 구체적인 클라이언트/서버 코드를 자동으로 생성합니다. 즉, 컴파일 단계에서 스키마 계약 불일치 오류를 차단합니다. +* **바이너리 프로토콜**: 텍스트가 아닌 이진 데이터 형식을 사용하여 통신 속도가 JSON 방식에 비해 훨씬 빠르고 가볍습니다. +* **HTTP/2 기반**: 하나의 커넥션을 다중화(Multiplexing)하여 사용하므로 네트워크 리소스 효율성이 매우 높습니다. + +--- + +## 4. gRPC 개요 + +위와 같이 gRPC가 고안된 배경과 필요성을 바탕으로, 구체적인 특징과 개발 프로세스를 살펴보겠습니다. + +gRPC 서버와 클라이언트를 개발하는 과정은 크게 세 단계로 나뉩니다: +1. **인터페이스 정의 언어(IDL) 파일 생성**: 인터페이스를 계약(Contract)으로 정의합니다. +2. **gRPC 서버 개발**: 이 정의를 기반으로 서비스를 구현합니다. +3. **gRPC 클라이언트 개발**: 해당 서버와 통신하는 코드를 개발합니다. + +### 4.1 장점 +gRPC의 주요 장점은 다음과 같습니다: +* **빠른 데이터 교환**: 바이너리 데이터 형식을 사용하여 일반 텍스트 기반 서비스보다 훨씬 빠르게 데이터를 교환합니다. +* **간편한 개발 도구**: 풍부한 명령줄 도구들을 제공하여 개발 작업을 더욱 간단하고 신속하게 만듭니다. +* **쉬운 서버/클라이언트 생성**: gRPC 서비스의 함수와 메시지를 정의한 후에는 RESTful 서비스보다 서버와 클라이언트를 더 쉽게 생성할 수 있습니다. +* **스트리밍 지원**: 스트리밍 서비스에 효과적으로 활용될 수 있습니다. +* **세부 사항 자동 처리**: 데이터 교환의 복잡한 세부 사항을 gRPC가 자동으로 처리해주므로 개발자가 신경 쓸 필요가 없습니다. + +> [!NOTE] +> 이 장점 목록만 보고 gRPC가 모든 문제의 완벽한 해결책이라고 오해해서는 안 됩니다. 항상 현재 작업에 가장 적합한 도구나 기술을 선택하는 것이 중요합니다. + +### 4.2 프로토콜 버퍼 (Protobuf) +프로토콜 버퍼(Protobuf)는 구조화된 데이터를 효율적으로 직렬화하는 방법입니다. Protobuf는 IDL(인터페이스 정의 언어)의 일부로, 데이터 교환 시 바이너리 형식을 사용하기 때문에 일반 텍스트 기반 직렬화 형식보다 훨씬 적은 공간을 차지합니다. 하지만 데이터를 기계가 사용하고 사람이 읽을 수 있도록 하려면 각각 인코딩과 디코딩 과정이 필요합니다. Protobuf는 각 프로그래밍 언어에서 기본적으로 지원하는 데이터 타입으로 변환되는 자체 데이터 타입을 제공합니다. + +일반적으로 IDL 파일은 모든 gRPC 서비스의 핵심입니다. 이는 데이터 교환 형식과 서비스 인터페이스를 정의하기 때문입니다. Protobuf 파일 없이는 gRPC 서비스를 구축할 수 없습니다. 더 정확히 말하면, Protobuf 파일에는 서비스 정의, 서비스 메서드, 그리고 교환될 메시지 형식이 모두 포함됩니다. + +--- + +## 5. 참고 자료 + +* [gRPC와 REST의 차이점 (AWS)](https://aws.amazon.com/ko/compare/the-difference-between-grpc-and-rest/)