docs: refactor docs structure by splitting README.md and update .gitignore

2026-07-17 11:37:09 +09:00
parent 989529e8ba
commit 5e6f7defd3
3 changed files with 92 additions and 76 deletions
@@ -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/