Learn Rust Coding · 강의

Protobuf와 서비스 정의

proto로 API를 설명해 보세요.

Protobuf와 서비스 정의은(는) CoddyKit의 무료 Learn Rust Coding 강의입니다. 이것은 4개 중 1번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 Learn Rust Coding 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. Learn Rust Coding 강의에는 총 4개의 강의가 포함되어 있습니다.

gRPC와 Protobuf를 사용하는 이유

gRPC는 HTTP/2와 Protocol Buffers를 기반으로 구축된 고성능 RPC 프레임워크입니다. Rust에서는 tonic 크레이트가 gRPC의 전체 기능을 구현합니다.

Protobuf는 인터페이스 정의 언어(IDL)입니다. .proto 파일에 메시지와 서비스를 한 번 정의하면 코드 생성기가 강한 타입의 클라이언트 및 서버 스텁을 생성합니다.

.proto 파일의 구조

모든 proto 파일은 문법 버전과 패키지를 선언합니다. 패키지는 생성된 타입에 네임스페이스를 제공하여 충돌을 방지합니다.

tonic에서는 proto3를 사용하십시오. 패키지 이름은 생성 후 Rust 모듈 경로로 매핑됩니다.

syntax = "proto3";

package greeter.v1;

메시지 정의하기

메시지는 타입이 지정된 레코드입니다. 각 필드에는 타입, 이름, 그리고 전송 인코딩에 사용되는 고유한 필드 번호가 있습니다.

필드 번호는 안정적으로 유지해야 합니다. 데이터가 존재한 후에는 필드 번호를 재사용하거나 변경하지 마십시오. 호환성이 깨집니다.

message HelloRequest {
  string name = 1;
  int32 age = 2;
}

스칼라 타입과 Rust 매핑

Protobuf 스칼라 타입은 prost를 통해 Rust 타입으로 매핑됩니다. string은 String으로, int32는 i32로, bool은 bool로, bytes는 Vec<u8>로 변환됩니다.

proto3에서 모든 스칼라 타입에는 기본값(빈 문자열, 0, false)이 있습니다. 별도로 표시하지 않는 한 선택 사항이 아닙니다.

message Metric {
  string label = 1;
  double value = 2;
  bool active = 3;
}

서비스 정의하기

service는 RPC 메서드를 묶습니다. 각 rpc는 메서드 이름, 요청 메시지, 응답 메시지를 선언합니다.

tonic은 이 블록에서 서버 트레이트와 클라이언트 구조체를 생성합니다. 동작을 제공하려면 해당 트레이트를 구현해야 합니다.

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
}

message HelloReply {
  string message = 1;
}

네 가지 RPC 메서드 종류

gRPC는 네 가지 스트리밍 형태를 지원합니다. 단일 요청-응답, 서버 스트리밍, 클라이언트 스트리밍, 양방향 스트리밍입니다.

요청 측이나 응답 측 또는 양쪽에 stream 키워드를 사용하여 스트림임을 나타냅니다.

service Chat {
  rpc Unary (Msg) returns (Msg);
  rpc ServerStream (Msg) returns (stream Msg);
  rpc ClientStream (stream Msg) returns (Msg);
  rpc BiDi (stream Msg) returns (stream Msg);
}

Protobuf의 열거형

열거형은 정수로 뒷받침됩니다. proto3에서는 첫 번째 값의 번호가 반드시 0이어야 하며 기본값으로 사용됩니다.

전송 과정에서 알 수 없는 값이 들어올 수 있으므로 prost는 Rust 열거형과 기본 i32에서 변환하는 도우미를 함께 생성합니다.

enum Status {
  STATUS_UNKNOWN = 0;
  STATUS_ACTIVE = 1;
  STATUS_BANNED = 2;
}

중첩 필드와 반복 필드

repeated 필드는 목록이며 Rust에서는 Vec<T>로 매핑됩니다. 메시지는 중첩하거나 이름으로 참조할 수 있습니다.

이를 통해 별도의 번거로운 코드 없이 컬렉션과 복합 페이로드를 모델링할 수 있습니다.

message Order {
  string id = 1;
  repeated Item items = 2;
}

message Item {
  string sku = 1;
  int32 qty = 2;
}

Empty와 잘 알려진 타입

아무것도 받지 않거나 반환하지 않는 메서드에는 google/protobuf/empty.proto를 가져오고 Empty를 사용하십시오.

그 밖의 잘 알려진 타입으로는 Timestamp와 Duration이 있습니다. tonic은 이러한 정의를 함께 제공하므로 빌드에서 가져올 수 있습니다.

import "google/protobuf/empty.proto";

service Health {
  rpc Ping (google.protobuf.Empty) returns (google.protobuf.Empty);
}

패키지로 버전 관리하기

greeter.v1처럼 패키지에 버전을 포함하면 API를 안전하게 발전시킬 수 있습니다. 호환성을 깨는 변경 사항은 greeter.v2에 추가하고 v1은 계속 서비스할 수 있습니다.

이 규칙은 생성된 Rust 모듈을 깔끔하게 유지합니다. greeter::v1과 greeter::v2가 함께 존재할 수 있습니다.

package greeter.v1;
// later, a parallel file:
// package greeter.v2;

필드 호환성 규칙

새 번호를 사용하는 새 필드를 추가하는 것은 하위 호환됩니다. 이전 클라이언트는 이를 무시합니다. 필드를 제거하는 것은 해당 번호와 이름을 reserve하지 않는 한 위험합니다.

예약하면 누구도 폐기된 필드 번호를 재사용하여 디코딩을 손상시키는 일을 막을 수 있습니다.

message User {
  reserved 3, 5;
  reserved "legacy_token";
  string id = 1;
  string email = 2;
}

빠른 확인

proto3 서비스 정의에 대한 이해도를 확인해 보십시오.

정리

proto3에서 서비스와 메시지를 정의했습니다. 안정적인 필드 번호, 스칼라 타입과 Rust의 매핑, 열거형, 반복 필드와 중첩 필드, 네 가지 RPC 형태, 잘 알려진 타입, 패키지를 통한 버전 관리까지 다뤘습니다.

다음에는 tonic-build를 사용하여 이러한 정의를 Rust 코드로 변환합니다.

자주 묻는 질문

“Protobuf와 서비스 정의” 강의는 무료인가요?

네 — “Protobuf와 서비스 정의” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 Learn Rust Coding 강의 전체를 잠금 해제할 수 있습니다. Learn Rust Coding 강의에는 총 4개의 강의가 포함되어 있습니다.

“Protobuf와 서비스 정의”에서 뭘 배우나요?

proto로 API를 설명해 보세요. 브라우저에서 직접 실행하는 실습 코드로 Learn Rust Coding을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

Learn Rust Coding을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 Learn Rust Coding은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 1번째 강의입니다.

“Protobuf와 서비스 정의” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 Learn Rust Coding 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 Learn Rust Coding 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

← Learn Rust Coding(으)로 돌아가기