Protobuf (프로토콜 버퍼)
Proxyman에서 .desc 파일 디스크립터와 Message Type 규칙을 사용해 Protobuf HTTP 및 HTTPS 요청, 응답, WebSocket 메시지를 디코딩하세요.
1. Protobuf
- Proxyman macOS는 지정한 Protobuf desc 파일로 HTTP/HTTPS 요청과 응답의 Protobuf 본문을 디코딩할 수 있습니다.
- Protobuf 바이너리를 디코딩해 일반 텍스트로 표시합니다.
- 하나의 Protobuf 바이너리에서 단일 메시지나 여러 개의 구분된 메시지(Delimited Messages)를 지원합니다.
- desc 파일을 가져와 모든 Message Type을 읽고 Protobuf 바이너리를 디코딩합니다.
- WebSocket의 Protobuf 메시지를 디코딩합니다.
2. Protobuf 파일 디스크립터 (*.desc)
Proxyman이 Protobuf 데이터를 올바르게 파싱하려면 File Descriptor (*.desc)가 필요합니다.
다음과 같은 방법으로 File Descriptor를 얻을 수 있습니다.
1. 동료에게 물어보세요.
회사에서 Protobuf를 사용한다면, 특히 백엔드와 프론트엔드 팀의 동료들이 이 파일을 이미 가지고 있을 가능성이 높습니다.
디스크립터 파일은 하나일 수도 있고 여러 개일 수도 있습니다.
2. *.proto 파일에서 생성하기
*.proto 파일이 많다면 다음 명령어로 *.desc 파일 하나를 생성할 수 있습니다.
# Install protobuf cli if need
brew install protobuf
# Create `input` folder on the Desktop
# Copy all proto files to the `input` folder
# Generate 1 descriptor file with multiple proto files
protoc --descriptor_set_out=output.desc --include_imports -I=/Users/<your_name>/Desktop/input /Users/<your_name>/Desktop/input/*.proto
# Done
# output.desc
디스크립터 파일을 준비했다면 Proxyman으로 가져오세요.
- Tools 메뉴 -> Protobuf… -> Protobuf Schema... 버튼을 클릭합니다.
- + 버튼을 클릭하고 output.desc 파일을 선택합니다.
Proxyman 3.6.0 이상에서는 더 나은 Protobuf 파싱을 위해 **File Descriptor (*.desc)**만 허용합니다.
*.proto 파일이 있다면 *.desc로 변환할 수 있습니다. 위의 *.proto 파일에서 생성하기를 참고하세요.
Proxyman은 Timestamp, Struct, Value, Enum, Method 등 Google Protobuf의 일반 타입을 모두 자동으로 가져옵니다.
Proxyman은 proto2와 proto3 문법을 모두 지원합니다. 자세히 보기
3. Protobuf 설정
Protobuf를 사용하기 전에, Proxyman이 Protobuf 데이터를 파싱할 때 사용할 Message Type을 설정해야 합니다.
다음 표는 각 설정을 설명합니다.
| 이름 | 설명 |
|---|---|
| Schema | 필요하면 .desc 파일을 추가하세요 |
| Message Type | Protobuf 바이너리에서 루트 객체의 클래스 이름입니다. Package 이름을 반드시 포함해야 합니다 |
| Payload Type: Auto | Protobuf 바이너리가 단일 메시지인지 구분된 메시지(Delimited Message)인지 자동으로 감지합니다 |
| Payload Type: Single Message | Protobuf 바이너리 안의 단일 메시지 |
| Payload Type: Delimited List | Protobuf 바이너리 안의 여러 메시지(길이 접두사 방식) |
Proxyman으로 Protobuf HTTPS 응답 디코딩하기
4. 사용 방법
필드 이름을 포함해 Protobuf를 올바르게 파싱하는 방법은 두 가지입니다.
- Protobuf 규칙 정의하기
- Content-Type 헤더에서 읽기
4.1 Protobuf 규칙 정의하기
- Protobuf 요청에는 Content-Type 헤더가 있어야 합니다:
Content-Type: application/x-protobuf또는Content-Type: application/protobuf - Proxyman은 Protobuf 페이로드를 감지하고, 메시지 타입이 없어 올바르게 파싱할 수 없다는 경고를 표시합니다. Add를 클릭해 Protobuf Settings를 여세요.
또는 요청을 마우스 오른쪽 버튼으로 클릭한 다음 -> Tools -> **Protobuf…**를 선택할 수도 있습니다.
3. Protobuf 규칙 창에서 이 요청/응답의 Message Type을 선택하세요(필요하면 desc 파일을 추가하세요).
요청과 응답이 서로 다른 Protobuf Message Type을 사용한다면 `Use different Message Type for Request / Response` 체크박스를 선택하세요.
4. Add를 클릭하고 본문을 JSON 형식으로 확인하세요.
4.2 Content-Type 헤더에서 읽기
Content-Type에서 Protobuf 설정을 동적으로 제공할 수 있습니다.
예를 들어 요청 또는 응답의 Content-Type은 다음과 같을 수 있습니다.
Content-Type: application/x-protobuf; messageType="tutorial.Address"; delimited=true
Content-Type: application/x-protobuf; messageType="com.proxyman.User"; delimited=false
이 값은 Proxyman에 Message Type과 Protobuf 본문의 페이로드 인코딩 방식을 알려줍니다.
5. ✅ WebSocket의 Protobuf (macOS 6.5.0 이상)
- 단일 바이너리 WebSocket 프레임을 디코딩하려면 websocket.md 문서를 읽어보세요.
- WebSocket용 Protobuf 규칙을 만들 수 있습니다. 클라이언트 메시지에는 Request Message Type을, 서버 메시지에는 Response Message Type을 사용하세요.
6. 문제 해결
6.1 일부 이름 필드가 누락됨
정의가 Protobuf File Descriptor에 없으면 일부 필드 이름이 누락될 수 있습니다. 디스크립터가 오래되었을 수도 있습니다.
해결 방법:
- 기존 Protobuf Schema를 삭제하고, 서버에서 받은 최신 디스크립터 파일을 추가하세요.
- Proxyman 3.5.2 이하를 사용 중이라면 3.6.0 이상으로 업데이트하세요. 그다음 더 나은 결과를 위해 File Descriptor (*.desc)를 사용하세요.