SimpleWebUtils
ENKO

문서 작업 가이드

배포 전에 코드를 안전하게 포맷하고 압축하는 방법

작은 출력과 검증된 동작을 혼동하지 않고 CSS, HTML, JavaScript, JSON, GraphQL, YAML, XML, Go를 포맷하거나 압축하는 파서 우선 실전 절차입니다.

작성 및 검수 게시일: 검토일:

이 작업 흐름을 검증한 방법

검토에서는 수정하지 않은 “URL과 정규식 토큰을 깨뜨리지 않고 JavaScript 릴리스 파일 압축” 샘플을 코드 포맷 워크벤치에 불러왔습니다. “소스 문법과 실제 소비 대상을 확인합니다”에서 “정확한 출력, 크기, 실행 동작을 비교합니다”까지의 흐름을 실행해 화면 또는 다운로드 결과를 예시와 비교했습니다. 별도 조사 항목은 “작은 파일을 얻자마자 원본 삭제”, “HTML 복구를 XML 검증으로 간주”였습니다.

Terser 처리는 식별자 난독화를 끈 채 측정 바이트를 줄였고, 라이선스 주석·URL·escape 정규식·template literal·export 동작을 보존했습니다.

코드 포맷 워크벤치 | CSS, HTML, JavaScript 외 열기

문제 상황

팀이 코드를 일반 포맷터에 붙여넣고 비어 있지 않은 출력만 나오면 공백은 항상 무의미하다고 생각해 커밋하는 경우가 많습니다. 그러면 큰 JSON 식별자가 반올림되거나, 라이선스·운영에 필요한 주석이 지워지거나, 잘못된 HTML이 다른 DOM으로 복구되거나, ES 모듈이 일반 스크립트로 압축되거나, CSS 재구성으로 캐스케이드가 달라지거나, 빠진 구조를 만든 XML 출력이 생길 수 있습니다. 목적은 언어가 실제로 지원하는 작업을 선택하고, 잘못된 구조 입력을 실패로 처리하며, 재현 가능한 원본과 설정을 남기고, 생성 자산을 실제 소비 환경에서 증명하는 것입니다.

이럴 때 사용하세요

  • 코드 검토 전 CSS, HTML, JavaScript, JSON, GraphQL, YAML, XML, Go 파일을 정규화하거나 팀 포맷터와 비교해야 할 때
  • 릴리스용 프런트엔드 자산이나 JSON payload를 압축하고 원본을 잃지 않은 채 바이트 감소량을 측정할 때
  • 복사한 설정, API fixture, 쿼리, XML 문서에 파서 오류, 중복 키, 큰 숫자, 오해하기 쉬운 복구 동작이 있을 수 있을 때
  • 브라우저 로컬 결과가 Prettier, Terser, CSSO, gofmt, CI 빌드, 운영 파서와 다르고 정확한 설정 차이를 분리해야 할 때

단계

  1. 1단계

    소스 문법과 실제 소비 대상을 확인합니다

    언어, 파일 역할, 파서 또는 런타임 버전, 소스 유형, 스키마, 후속 빌드 단계를 기록합니다. HTML과 XML, 엄격한 JSON과 JSONC, YAML 설정과 애플리케이션 스키마, JavaScript 일반 스크립트와 ES 모듈을 구분하세요. 목표에 맞을 때만 포맷, 압축, CSS 구문 검사를 선택하고 포맷을 컴파일·스키마 검증·렌더링·테스트의 대체물로 사용하지 마세요.

  2. 2단계

    원본을 보존하고 민감한 값을 제거합니다

    소스는 버전 관리나 별도 fixture에 유지하고 작은 조각으로 작업합니다. 클립보드 기록, 스크린샷, 브라우저 확장, 오류 보고서, 다운로드 파일에 들어가기 전에 자격 증명, 비공개 URL, 고객 값, 토큰, 독점 내용을 제거하세요. 정확한 바이트 비교가 중요하면 체크섬이나 diff 기준도 기록합니다.

  3. 3단계

    명시적 설정으로 형식별 작업을 실행합니다

    코드 포맷 워크벤치에서 언어와 제공되는 작업을 선택합니다. 포맷에는 들여쓰기와 출력 폭을 설정하고 JavaScript에는 일반 스크립트/ES 모듈과 스타일 옵션을 정합니다. 수동으로 실행하고 파서 오류, NUL, 문자·바이트 제한, 잘못된 JSON, 중복 YAML 키, 짝이 맞지 않는 XML, 잘못된 GraphQL, gofmt 오류가 나오면 일반 도구가 출력을 낼 때까지 소스를 임의로 고치지 말고 중단하세요.

  4. 4단계

    진단과 형식별 불변 조건을 검토합니다

    CSS 구문 검사는 브라우저 지원이나 캐스케이드를 증명하지 않습니다. HTML은 복구된 DOM과 보이는 인라인 공백을 확인합니다. JavaScript는 라이선스 주석과 소스 유형을 확인합니다. JSON은 큰 정수·소수·지수·이스케이프·중복 키 토큰을 비교합니다. YAML은 주석과 스키마 규칙, XML은 스키마 전 well-formedness, Go는 gofmt가 포맷일 뿐 컴파일이 아님을 확인하세요.

  5. 5단계

    정확한 출력, 크기, 실행 동작을 비교합니다

    표시된 출력과 설정을 저장하고 원본과 의미 diff를 비교합니다. 입력·출력 바이트, 변경 여부, 압축 절약량을 기록하되 작다는 이유로 올바르다고 가정하지 마세요. 해당되는 실제 브라우저·접근성 검사, JavaScript 빌드·테스트, CSS 시각 회귀, HTML 템플릿, JSON 소비자, GraphQL 스키마, YAML 로더, XML DTD/XSD 정책, Go 컴파일러에 후보를 통과시킵니다.

  6. 6단계

    승인된 포맷터와 롤백 경로를 자동화합니다

    대상 결과를 검증한 뒤 저장소에 포맷터·압축기 버전과 설정을 고정하고 대표 경계 fixture를 추가하며 CI가 자산을 결정론적으로 비교하거나 다시 만들게 합니다. 소스 맵, 라이선스 처리, 원본 파일, 롤백 조건을 유지하고 검토하지 않은 브라우저 다운로드를 운영 자산의 유일한 사본으로 두지 마세요.

예시

URL과 정규식 토큰을 깨뜨리지 않고 JavaScript 릴리스 파일 압축

입력

/*! license */ 주석, https://example.com/a//b 문자열, /a\/b/ 정규식, 템플릿 리터럴, export 동작 테스트가 있는 일반 스크립트

출력

안전한 Terser 압축 1회, 식별자 난독화 끄기, /*! 주석과 리터럴 보존, 측정된 바이트 절약, 빌드·단위·브라우저·소스 맵·라이선스 검사 통과

흔한 실수

작은 파일을 얻자마자 원본 삭제

압축 자산은 검토하기 어렵고 소스 맵이나 주석이 빠질 수 있습니다. 정식 원본, 재현 가능한 설정, 검증된 빌드 경로를 유지하세요.

정규식으로 구조화 언어 압축

정규식 치환은 문자열, URL, 정규식 리터럴, calc 식, preformatted HTML, 이스케이프, 중첩 구문을 깨뜨릴 수 있습니다. 선택한 문법을 이해하는 파서를 사용하세요.

HTML 복구를 XML 검증으로 간주

HTML 파서는 잘못된 구조를 복구할 수 있지만 XML은 올바르게 중첩되어야 합니다. HTML DOM을 검사하고 XML에는 전용 well-formedness 검사를 적용하세요.

공백 제거 중 JSON 값 변경

JavaScript 숫자로 파싱하면 큰 정수가 반올림되고 직렬화 과정에서 토큰 표기나 중복 키가 바뀔 수 있습니다. 작업이 압축뿐이라면 정확한 토큰을 보존하세요.

포맷터를 전체 도구 체인과 동일시

Prettier, CSSO, Terser, XML 파서, gofmt는 각각 좁은 계약만 다룹니다. 스키마, 컴파일러, 타입 검사, 브라우저, 접근성, 보안 정책, 애플리케이션 테스트를 대체하지 않습니다.

자주 묻는 질문

생성된 압축 파일을 저장소에 커밋해야 하나요?

배포나 배포 패키지 모델이 체크인 자산을 요구할 때만 커밋하세요. 그 외에는 CI에서 재현 가능하게 빌드하는 편이 낫습니다. 어느 경우든 버전과 설정을 고정하고 원본을 유지하며 라이선스·소스 맵을 검증하고 자산 drift를 탐지해야 합니다.

포맷이 동작을 바꿀 수 있나요?

올바른 포맷터는 일반적으로 언어 의미를 보존하지만 파서 복구, HTML 공백, JavaScript 소스 유형, CSS 재구성, 도구가 읽는 주석, 대상별 규칙은 관찰 가능한 동작을 바꿀 수 있습니다. 실제 소비자에서 검증하세요.

브라우저 압축기에서 식별자 난독화를 끈 이유는 무엇인가요?

한 번 생성한 결과를 쉽게 검토하고 reflection이나 외부 이름 계약에 대한 가정을 줄이기 위해서입니다. 운영 빌드는 전체 의존성 그래프, 속성 정책, 소스 맵, 테스트와 함께 난독화를 켤 수 있습니다.

유효한 YAML이나 GraphQL 구문이면 배포에 충분한가요?

아닙니다. YAML은 대상 애플리케이션 스키마와 사용자 태그 정책이 필요합니다. GraphQL은 스키마 검증, 권한, 변수, resolver 동작, 비용 통제가 필요합니다. 구문은 첫 번째 게이트일 뿐입니다.

포맷 또는 압축 변경에 어떤 증거를 첨부해야 하나요?

원본·대상 식별자, 도구와 버전, 정확한 설정, 입력·출력 바이트, 의미 diff, 파서 진단, 경계 fixture, 대상 빌드·테스트 결과, 필요한 시각·접근성 증거, 라이선스·소스 맵 검사, 롤백 조건을 남기세요.