React QR 코드 라이브러리 오픈소스 기여: 비 ASCII 문자 깨짐 현상 해결 및 UTF-8 지원 개선

핵심 기술

본 콘텐츠는 react-qr-code 라이브러리에서 비 ASCII 문자(특히 한국어)가 포함된 QR 코드를 생성할 때 발생하는 깨짐 현상을 해결하기 위한 오픈소스 기여 과정을 상세히 공유합니다. 핵심은 TextEncoder API를 활용하여 UTF-8 인코딩을 명시적으로 적용하고, 이를 QR 코드 라이브러리가 올바르게 처리하도록 변경하는 것입니다.

기술적 세부사항

• 문제 정의: react-qr-code 라이브러리에서 value 값으로 비 ASCII 문자를 직접 전달할 시, charCodeAt() 메서드가 UTF-16 코드 유닛을 8비트 단위로 처리하면서 상위 바이트가 잘려 문자가 깨지는 현상 발생.
• 임시 해결책: encodeURIcomponent 함수를 사용하여 비 ASCII 문자를 URL 인코딩하지만, 이는 사용자에게 디코딩 불편함을 야기하고 데이터 길이를 증가시키며 UX를 저해함.
• 근본적인 해결 방법:
  • TextEncoder().encode(input)을 사용하여 입력 문자열을 UTF-8 바이트 배열로 변환.
  • bytesToBinaryString 함수를 통해 UTF-8 바이트 배열을 QR 코드가 인식할 수 있는 이진 문자열(binary string) 형식으로 변환.
  • qrcode.addData(binaryString, "Byte")를 호출하여 이진 문자열 형태로 데이터를 라이브러리에 전달.
• 라이브러리 수정: qrcode.js 내부 로직에서 qrcode.addData(value) 대신 qrcode.addData(binaryString, "Byte")로 변경하여 UTF-8 바이트 단위 처리를 명시.
• 테스트 및 검증: 한국어, 일본어, 이모지 등 다양한 비 ASCII 문자를 포함한 QR 코드 생성 및 스캔 테스트를 통해 문제 해결 확인.
• 오픈소스 기여 과정: GitHub 이슈 확인, 코드 수정, PR 제출, 리뷰 피드백 반영 (예: TextEncoder 단일 사용 권장), README 업데이트 (비 ASCII 문자 테스트 예시 추가).

개발 임팩트

• 라이브러리 안정성 향상: react-qr-code 라이브러리의 국제화 지원을 강화하여 전 세계 다양한 언어 사용자들이 문제없이 QR 코드를 생성하고 사용할 수 있게 함.
• 개발 생산성 증대: 프론트엔드 개발자가 QR 코드 생성 시 문자 인코딩 문제로 겪는 시간 소모와 번거로움을 줄여줌.
• 오픈소스 생태계 기여: 실제 서비스(구름톤 유니브 참가자 출석 체크 시스템)에 적용될 기능을 오픈소스에 반영함으로써 개발 커뮤니티 발전에 기여.

커뮤니티 반응

• 라이브러리 구현자로부터 긍정적인 리뷰를 받고, 영어로 소통하며 코드를 개선하는 경험을 함.
• README에 비 ASCII 문자 테스트 예시가 반영되는 등, 기여가 실제 라이브러리에 통합됨.
• 작성자가 "감사합니다"라는 메시지와 함께 PR이 Merge된 것에 대한 뿌듯함을 표현함.