[jQuery] $.ajax 사용 시 사용자 정의 헤더(Custom Header) 추가하는 방법

jQuery의 $.ajax를 이용해 API 통신을 하다 보면, 인증 토큰이나 클라이언트 정보 전달을 위해 표준 헤더 외에 **사용자 정의 변수(Custom Header)**를 심어야 할 때가 있습니다.

 

결론부터 말씀드리면, headers 속성을 사용하면 아주 간단하게 해결됩니다!

1. 기본 적용 코드

질문하신 코드 구조를 바탕으로, headers 옵션을 추가한 완성형 코드입니다.

$.ajax({
    url: condData.dataURL,
    type: 'POST',
    dataType: 'text',
    contentType: 'text/plain',
    /* 👇 사용자 정의 헤더 추가 부분 */
    headers: {
        'X-Custom-Auth-Key': 'my-secret-key-123', // 사용자 정의 변수 1
        'X-Client-Version': '1.0.2',             // 사용자 정의 변수 2
        'Device-Type': 'Web'                     // 사용자 정의 변수 3
    },
    data: paramStr,
    success: function(result) {
        // 응답 데이터 복호화 및 파싱 로직
        result = JSON.parse(decodeByAES128(sKey, result));
        
        if(result.successYn == 'Y'){
            console.log(result.resultData);
            document.getElementById('resultData').textContent = JSON.stringify(result.resultData, undefined, 2);
        } else {
            alert(result.errMsg);
            document.getElementById('resultData').textContent = "";
        }
    },
    error: function(xhr, status, error) {
        console.error("통신 에러 발생:", error);
    }
});

---

2. 주요 포인트 정리

① headers 속성 활용

• headers 객체 안에 {'헤더명': '값'} 형태로 넣으면 됩니다.
• 값은 반드시 문자열(String) 형태여야 합니다.

② CORS와 Preflight 요청

• 커스텀 헤더를 추가하면 브라우저는 보안상의 이유로 **Preflight(사전 요청)**을 보냅니다.
• 이때 서버 응답에 Access-Control-Allow-Headers 설정이 되어 있어야 통신이 차단되지 않습니다.
• 서버 설정 예시 (Node.js/Express): res.header("Access-Control-Allow-Headers", "X-Custom-Auth-Key");

③ 명명 규칙 (Naming)

• 과거에는 사용자 정의 헤더에 X-를 붙이는 것이 관례였으나(예: X-Access-Token), 현재는 필수는 아닙니다. 하지만 협업 시 표준 헤더와 구분하기 위해 여전히 자주 사용됩니다.

---

3. (꿀팁) 모든 AJAX 요청에 공통 헤더 적용하기

로그인 토큰처럼 모든 API 호출마다 헤더를 붙여야 한다면, 매번 적지 말고 전역 설정을 이용하세요.

$.ajaxSetup({
    headers: {
        'Authorization': 'Bearer ' + userToken,
        'App-Service-ID': 'MY_APP_01'
    }
});

이렇게 한 번 선언해두면, 이후 호출되는 모든 $.ajax 요청에 해당 헤더가 자동으로 포함되어 코드가 훨씬 간결해집니다.

---

글을 마치며 보안이 중요한 AES128 암호화 통신 환경에서는 헤더를 통한 2차 검증이 필수적입니다.

 

위 방식을 통해 안전하고 깔끔한 API 통신 로직을 구현해 보시기 바랍니다!