문서 작업 가이드
데이터 전달용 바이너리-텍스트 인코딩 선택하고 검증하기
수신 측의 모호한 인코딩 요청을 문자 집합, 알파벳, 패딩, 바이트 순서, 컨테이너 계약으로 구체화하고 원본 증거를 보존한 채 검증합니다.
작성 및 검수 SimpleWebUtils게시일: 검토일:
이 작업 흐름을 검증한 방법
검토에서는 수정하지 않은 “UTF-8 텍스트 필드용 RFC 4648 Base32 검증” 샘플을 인코딩 워크벤치에 불러왔습니다. “변환 전에 수신기 계약 작성하기”에서 “실제 수신기를 양방향으로 시험하기”까지의 흐름을 실행해 화면 또는 다운로드 결과를 예시와 비교했습니다. 별도 조사 항목은 “가장 짧은 출력만 고르기”, “모든 Base62·Base85가 같다고 가정하기”였습니다.
UTF-8 “café!”는 RFC 4648 계약에 따라 패딩을 포함한 MNQWNQ5JEE======로 인코딩됐고, 같은 계약으로 디코딩했을 때 원래 바이트가 복원됐습니다.
문제 상황
“Base62로 보내기”, “XML용으로 escape하기”, “Unicode로 변환하기” 같은 지시는 실제 바이트를 결정하는 조건을 빠뜨립니다. 원본이 텍스트인지 임의 바이트인지, 텍스트의 문자 집합은 무엇인지, Base62 알파벳과 선행 0 규칙은 무엇인지, UTF-16 바이트 순서는 무엇인지, 엔티티가 들어갈 문맥은 어디인지가 필요합니다. 로컬에서 되돌릴 수 있는 결과도 수신기가 다른 계약을 따르면 운영 환경에서 실패합니다. 이 흐름은 모든 가정을 보이게 만들고 원본을 버리기 전에 실제 경계를 시험합니다.
이럴 때 사용하세요
- API나 데이터 필드가 완전한 예제와 변형 없이 Base32, Base58, Base62, Base85, binary, hexadecimal만 지정합니다.
- 텍스트 가져오기에 알 수 없는 UTF-8, Latin-1, Windows-1252, UTF-16, BOM, 바이트 순서 가정이 섞여 있습니다.
- HTML·XML 텍스트를 escape하는데 목적지 문맥, 이름 엔티티 정책, sanitizer 경계가 불분명합니다.
- IDN, quoted-printable 이메일 본문, Unicode escape, UUEncode 블록이 로컬에서는 되지만 다른 parser에서 실패합니다.
- 작은 이미지를 Base64나 데이터 URI로 바꿔야 하며 수신기에 크기, MIME, CSP, 컨테이너 조건이 있습니다.
단계
- 1단계
변환 전에 수신기 계약 작성하기
입력이 텍스트인지 임의 바이트인지 기록하고, 텍스트라면 문자 집합을 적습니다. 정확한 표현 이름, 알파벳 또는 표준, 패딩 정책, 줄바꿈, 바이트 순서, BOM 정책, 파일명 메타데이터, MIME wrapper, 최대 크기를 추가합니다. 짧은 이름으로 변형을 추측하지 말고 권위 있는 입출력 벡터 하나를 요청합니다.
- 2단계
원본을 보존하고 공유용 비밀 제거하기
손대지 않은 비공개 원본과 필요하면 checksum 또는 길이를 보관합니다. 이 도구의 로컬 처리는 업로드를 막지만 복사한 결과를 기밀로 만들지 않으므로 화면과 협업용 fixture에서는 비밀을 제거합니다. 텍스트 상자에 붙여 넣을 수 있다는 이유로 알 수 없는 파일을 텍스트로 변환하지 않습니다.
- 3단계
계약과 일치하는 워크벤치 모드·옵션 고르기
Encoding Workbench에서 지정한 표현을 선택합니다. Bitcoin Base58, 0-9/A-Z/a-z Base62, Adobe ASCII85 또는 ZeroMQ Z85, RFC 4648 Base32 패딩, UTF-16 바이트 순서, HTML 엔티티 형식, XML 따옴표 정책, UUEncode 파일명·8진 권한을 작성한 계약과 맞춥니다. 원본 문자 집합을 정말 모르면 Charset Detector를 먼저 사용합니다.
- 4단계
작은 기준 벡터를 실행하고 알림 전부 읽기
수신기 벡터나 ASCII, 비ASCII 문자, 필요할 때 선행 0바이트, 패딩 또는 줄바꿈 경계를 포함한 fixture로 시작합니다. 입력·출력 바이트, 출력 문자, 정규화 알림, 왕복 결과를 확인합니다. 비표준 Base62, 패딩 생략, 줄바꿈, Latin-1, BOM 알림은 장식이 아니라 계약의 일부입니다.
- 5단계
실제 수신기를 양방향으로 시험하기
정리한 fixture만 실제 API, parser, library, DNS validator, 이메일 stack, 브라우저 문맥의 통제된 환경에 보냅니다. 수신기가 만든 결과를 로컬에서 디코딩하고 로컬 결과도 수신기가 디코딩하게 합니다. 눈에 보이는 텍스트뿐 아니라 바이트를 비교하며 선행 0, 빈 값, 보조 평면 Unicode, 줄바꿈, 패딩, 파일명, 최대 크기 경계를 포함합니다.
- 6단계
벡터를 문서화하고 실패 증거 보존하기
정확한 표준 또는 알파벳, 옵션, 원본 바이트 설명, 예상 결과, 수신기 버전, 통과 벡터 하나를 integration 옆에 보관합니다. 결과가 다르면 공백을 정규화하거나 재시도하기 전에 양쪽 raw 문자열과 byte dump를 남깁니다. 가역성이 필요한 전달이 운영 동등 테스트를 통과한 뒤에만 원본을 대체합니다.
예시
UTF-8 텍스트 필드용 RFC 4648 Base32 검증
입력
계약: UTF-8 텍스트, RFC 4648 Base32 알파벳, 대문자, 정규 패딩. fixture: café!출력
MNQWNQ5JEE======; 같은 계약으로 디코딩하면 café!를 복원하며 수신기도 같은 패딩 벡터를 생성하거나 허용해야 함흔한 실수
가장 짧은 출력만 고르기
출력 길이는 한 가지 속성일 뿐입니다. 수신기의 표준, 허용 문자, checksum 필요성, 복사 채널, 줄 규칙, 기존 library가 올바른 표현을 결정합니다.
임의 바이트를 UTF-8 텍스트라고 부르기
엄격한 텍스트 decoder는 정상 binary data를 거부할 수 있습니다. 페이로드가 텍스트로 정의되지 않았다면 바이트를 보존하고 파일 또는 바이트 중심 encoder를 사용합니다.
모든 Base62·Base85가 같다고 가정하기
Base62 알파벳 순서와 선행 0 처리 방식은 다릅니다. ASCII85와 Z85도 알파벳, 구분자, 블록 조건이 다르므로 변형을 명시해야 합니다.
엔티티 인코딩을 sanitization으로 사용하기
HTML·XML escape는 text, attribute, URL, style, script, parser 문맥에 따라 다릅니다. 문자 변환만으로 allowlist sanitizer나 XML 보안 정책이 되지 않습니다.
로컬 왕복만 보고 끝내기
로컬 역변환은 하나의 구현과 옵션 집합만 검사합니다. 실제 수신기 버전, 크기 한도, 줄 처리, MIME wrapper, 오류 동작을 교차 시험해야 합니다.
자주 묻는 질문
Base64, Base32, Base58, Base85 중 무엇을 골라야 하나요?
먼저 수신기가 문서화한 표준을 따르세요. Base64는 흔하고 조밀하지만 +, /, 패딩을 사용하고, Base32는 더 작은 알파벳이라 대소문자 무관 채널에 유리하며, Bitcoin Base58은 헷갈리는 글자를 빼고, Base85는 더 조밀하지만 변형·블록 조건이 많습니다. 어떤 것도 암호화하지 않습니다.
Base62 계약에 왜 알파벳이 필요한가요?
단일 Base62 표준이 없기 때문입니다. 시스템마다 숫자와 대소문자 순서가 다르고 선행 0바이트 처리도 다릅니다. 이 워크벤치는 0-9, A-Z, a-z를 사용하며 그 선택을 비표준이라고 표시합니다.
왕복 성공은 정보가 전혀 손실되지 않았다는 뜻인가요?
이 구현과 선택 옵션, 문서화된 정규화 아래 복원되었다는 뜻입니다. Morse는 대소문자를 잃고 quoted-printable은 교환을 위해 줄바꿈을 정규화하며, 다른 구현은 다른 규칙을 쓸 수 있습니다. 필요한 의미 또는 바이트 동일성을 직접 비교하세요.
알 수 없는 텍스트 파일을 바로 Latin-1이나 UTF-16으로 변환해도 되나요?
신뢰하기 어렵습니다. 신뢰할 수 있는 명세, BOM, 메타데이터, 증거로 원본 encoding을 먼저 정하세요. Latin-1과 Windows-1252는 다르고 UTF-16은 byte order가 필요합니다. 시험 중에는 원본 바이트를 보존하세요.
이미지 데이터 URI는 언제 적합한가요?
수신기가 명시적으로 허용한 작은 fixture나 embedded asset에만 크기와 CSP 규칙을 확인한 뒤 사용하세요. Base64는 데이터를 키우고 caching을 어렵게 하며 원본 바이트를 모두 드러냅니다. 서명 검사는 이미지 내용을 scan하거나 metadata를 제거하지 않습니다.
워크벤치가 원문이나 인코딩 결과를 전송하나요?
원문 변환에는 network request가 필요하지 않고 전용 browser Worker에서 실행합니다. 운영 분석에는 선택 모드, 안전한 option 이름, 시간, byte 수, 합계 알림 수만 들어가며 원문, 이미지 byte, 파일명, domain, 출력은 포함하지 않습니다.