리액트 api axios 엑셀 다운로드 버튼 구현 react.JS filesaver.saveAs javascript blob response.headers 값에서 filename추출하기

리액트 api axios 엑셀 다운로드 버튼 구현 react.JS filesaver.saveAs javascript blob response.headers 값에서 filename추출하기

리액트로 프로젝트를 진행하면서 서버로부터 엑셀 파일을 다운로드 받는 기능을 구현해야 할 경우가 종종 있습니다. 특히 API 호출 시 Axios를 사용하여 데이터를 받아오고, 그 데이터를 파일로 저장하는 과정에서 여러 가지 제약과 이슈를 마주하게 됩니다. 이번 포스팅에서는 리액트 환경에서 Axios를 활용하여 엑셀 파일 다운로드 버튼을 구현하는 방법과 함께, response.headers에 포함된 파일명을 추출하는 꼼수에 대해 자세히 다루고자 합니다.

리액트 프로젝트 개요 및 구현 배경

리액트는 단순한 컴포넌트 기반 라이브러리로서, 기존의 PHP나 Angular와 달리 파일 다운로드와 같은 기능을 직접 구현하는 데 있어 제약이 따르는 경우가 많습니다. 그 중에서도 엑셀 파일 다운로드는 서버에서 생성된 파일을 클라이언트로 전송받아 저장해야 하므로, 인증 토큰과 같은 보안 요소 및 파일 형식 처리 등이 추가적으로 필요합니다.

실제 구현 시, Axios를 이용하여 백엔드 API를 호출하고, 그 결과로 받아온 blob 데이터를 FileSaver 라이브러리를 사용하여 사용자가 바로 다운로드 받을 수 있도록 처리하게 됩니다. 다만, 이 과정에서 백엔드에서 전송하는 HTTP 응답 헤더에 포함된 파일명을 바로 사용하지 못하는 문제가 발생하는데, 이는 리액트의 response.headers 객체가 Angular와 다르게 동작하는 점에서 기인합니다. 특히, HTTP 헤더의 key 값에 하이픈(-)이 포함되어 있을 경우, 일반적인 접근 방식으로는 값을 추출할 수 없는 경우가 발생합니다.

Axios를 이용한 API 호출과 파일 다운로드 처리

우선, 파일 다운로드 기능을 구현하기 위해 Axios 인스턴스를 생성하고, 백엔드 API로부터 엑셀 파일을 blob 형식으로 받아오는 기본적인 구조를 살펴보겠습니다. 리액트 프로젝트에서 Axios를 사용할 때, 토큰과 같은 인증 정보가 필요하다면 Axios 인스턴스 생성 시 인터셉터나 기본 헤더에 해당 정보를 추가할 수 있습니다.

아래는 Axios를 활용하여 API를 호출하고, 응답 데이터의 blob을 받아오는 예시 코드입니다.

// axios 인스턴스 생성 예시 (인증 토큰 포함)
import axios from "axios";

const authAxios = axios.create({
  baseURL: "/api/v1",
  headers: {
    "Content-Type": "application/json",
    // 토큰이 필요한 경우 아래와 같이 Authorization 헤더 추가
    // "Authorization": `Bearer ${token}`
  }
});

위와 같이 Axios 인스턴스를 생성한 후, 엑셀 파일 다운로드를 위한 API 호출을 진행합니다. 이때 responseType을 "blob"으로 설정해야 서버로부터 파일 데이터를 제대로 받아올 수 있습니다.

파일 다운로드 시 FileSaver 라이브러리 활용

엑셀 파일 다운로드 기능을 보다 손쉽게 구현하기 위해 FileSaver 라이브러리를 사용합니다. FileSaver는 브라우저에서 blob 데이터를 파일로 저장할 수 있도록 도와주는 라이브러리입니다. 프로젝트에 FileSaver를 설치하려면 아래와 같이 명령어를 실행합니다.

yarn add file-saver

설치 후, 컴포넌트 내에서 FileSaver를 임포트하여 사용할 수 있습니다.

import FileSaver from "file-saver";

이제 FileSaver를 활용하여 받아온 blob 데이터를 사용자의 컴퓨터에 파일로 저장할 수 있습니다.

react.JS에서는 리스폰스 헤더 값에서 let filename = response.headers.content-disposition 과 같은 형태로 값을 추출할 수가 없다.

응답 헤더에서 파일명 추출의 문제점과 해결 방법

대부분의 백엔드 서버는 파일을 전송할 때 HTTP 응답 헤더의 content-disposition 항목에 파일명을 포함시킵니다. 일반적인 형태는 아래와 같습니다.

Content-Disposition: attachment; filename="sample.xlsx"

Angular와 같이 일부 프레임워크에서는 response.headers.get('content-disposition')와 같이 간단히 파일명을 추출할 수 있습니다. 그러나 리액트에서 Axios를 사용하여 응답을 받을 경우, response.headers는 단순한 객체 형태로 제공되며, 하이픈(-)이 포함된 key 값에 직접 접근하는 데 제약이 있습니다. 예를 들어, 아래와 같이 시도하면 제대로 된 값을 얻기 어렵습니다.

let filename = response.headers.content-disposition; // Syntax Error 발생

또는

let filename = response.headers.get("content-disposition"); // null 반환

이러한 문제를 해결하기 위해, JSON.stringify()를 사용하여 headers 객체를 문자열로 변환한 후, 문자열 내에서 "filename=" 부분을 찾아 추출하는 방식으로 해결할 수 있습니다. 실제 구현 예시는 다음과 같습니다.

let filename = JSON.stringify(res.headers)
  .split("filename=")[1]
  .split('",')[0];

이 방식은 headers 객체를 문자열로 변환한 후, 특정 패턴("filename=")을 기준으로 분리(split)하여 파일명만 추출하는 꼼수입니다. 물론 이 방식은 다소 우회적인 방법일 수 있으나, 리액트에서 해당 문제를 우회하기 위한 효과적인 해결책으로 많이 사용되고 있습니다.

엑셀 다운로드 버튼 구현 예제 코드 상세 분석

다음은 실제로 엑셀 파일 다운로드 버튼을 클릭할 때 동작하는 핸들러 함수의 전체 코드입니다. 이 코드는 검색 조건에 따라 API 호출 파라미터를 구성하고, Axios로 엑셀 파일 데이터를 blob 형식으로 받아온 후, FileSaver를 이용하여 파일로 저장하는 로직을 포함하고 있습니다.

// 엑셀 다운로드 핸들러 함수
const handleDown = async (e) => {
  // 검색 조건 데이터 (예: 캠페인 제목, 발송 시작일, 발송 종료일)
  const { cmpgn_title, send_start_dt, send_end_dt } = campaignSearchData;

  // 다운로드 파라미터 객체 생성
  let downXls = { send_start_dt: "", send_end_dt: "" };
  downXls.cmpgn_title = cmpgn_title;

  // 날짜 형식 변환: null 체크 후 YYYY-MM-DD 포맷으로 변경
  if (send_start_dt !== null) {
    downXls.send_start_dt = changeFormat(send_start_dt, "YYYY-MM-DD");
  }
  if (send_end_dt !== null) {
    downXls.send_end_dt = changeFormat(send_end_dt, "YYYY-MM-DD");
  }

  try {
    // API 호출: 엑셀 파일 다운로드 요청, responseType을 blob으로 설정
    const res = await authAxios.get(
      `/api/v1/campaign-report/download?send_start_dt=${downXls.send_start_dt}&send_end_dt=${downXls.send_end_dt}&cmpgn_title=${downXls.cmpgn_title}`,
      { responseType: "blob" }
    );

    console.log("응답 헤더:", res.headers);

    // 응답 헤더에서 파일명을 추출하는 로직
    let filename = JSON.stringify(res.headers)
      .split("filename=")[1]
      .split('",')[0];

    // FileSaver를 이용하여 blob 데이터를 파일로 저장
    FileSaver.saveAs(res.data, filename);
  } catch (error) {
    // 에러 처리: 필요에 따라 사용자에게 알림 또는 로깅 처리
    console.error("엑셀 파일 다운로드 중 오류 발생:", error);
  }
};

위 코드에서 주목할 점은 다음과 같습니다.

1. 검색 조건 데이터 처리
   사용자 입력 또는 검색 조건에 따라 API 호출 파라미터를 동적으로 구성합니다. 캠페인 제목과 발송 날짜(시작일, 종료일)를 받아와서, 날짜 형식은 별도의 changeFormat 함수를 통해 "YYYY-MM-DD" 형식으로 변경합니다.
2. Axios API 호출 시 responseType 설정
   엑셀 파일과 같이 이진 데이터(blob)를 받아올 때에는 responseType: "blob"을 설정하여 서버로부터 올바른 데이터 형식을 받아옵니다. 이 설정이 없으면 파일 다운로드 시 데이터가 깨지거나 에러가 발생할 수 있습니다.
3. 응답 헤더에서 파일명 추출
   서버가 전송한 HTTP 응답 헤더에는 Content-Disposition 항목에 파일명이 포함되어 있습니다. 그러나 리액트의 Axios 응답 객체에서는 해당 헤더에 직접 접근하는 데 문제가 발생하므로, JSON.stringify를 이용해 문자열로 변환한 후 문자열 조작을 통해 파일명을 추출합니다.
4. FileSaver를 통한 파일 저장
   파일 다운로드를 위해 FileSaver.saveAs() 함수를 호출합니다. 이때 첫 번째 인자로 blob 데이터를, 두 번째 인자로 저장할 파일명을 전달하여 사용자가 파일을 다운로드 받을 수 있도록 합니다.

파일명 추출 방식의 한계와 보완점

앞서 소개한 문자열 조작 방식을 통한 파일명 추출은 리액트 환경의 한계를 극복하기 위한 임시방편에 가깝습니다. 실제 운영 환경에서는 다음과 같은 보완점을 고려해볼 수 있습니다.

1. 백엔드에서 파일명 전송 방식 개선
   만약 가능하다면 백엔드에서 파일명을 별도의 HTTP 헤더(예: custom-header: filename)로 전송하는 방법을 고려할 수 있습니다. 이렇게 하면 클라이언트 측에서 보다 안정적으로 파일명을 추출할 수 있습니다.
2. Axios 응답 인터셉터 활용
   Axios의 응답 인터셉터를 사용하여 모든 응답에 대해 공통적으로 파일명 추출 로직을 적용할 수 있습니다. 이 경우, 코드 중복을 줄이고 유지보수를 용이하게 할 수 있습니다.
3. 정규 표현식 사용
   문자열 분리(split) 방식 대신 정규 표현식을 사용하면, 파일명이 포함된 문자열에서 보다 유연하게 값을 추출할 수 있습니다. 예를 들어, 아래와 같이 구현할 수 있습니다.이 방식은 파일명이 없는 경우 기본 파일명("download.xlsx")을 사용하고, 정규 표현식을 활용하여 보다 정확하게 파일명을 추출합니다.
4. const contentDisposition = res.headers["content-disposition"] || ""; const filenameRegex = /filename[^;=\n]*=((['"]).*?\2|[^;\n]*)/; const matches = filenameRegex.exec(contentDisposition); const filename = matches != null && matches[1] ? matches[1].replace(/['"]/g, '') : "download.xlsx";

리액트 컴포넌트 내 구현 예제

다음은 위에서 설명한 내용을 바탕으로 리액트 컴포넌트 내에서 엑셀 다운로드 버튼을 구현한 예제입니다. 이 예제는 상태 관리와 이벤트 핸들러를 포함하여 실제 동작하는 형태로 구성되어 있습니다.

import React, { useState } from "react";
import axios from "axios";
import FileSaver from "file-saver";

const ExcelDownloadComponent = () => {
  const [campaignSearchData, setCampaignSearchData] = useState({
    cmpgn_title: "",
    send_start_dt: null,
    send_end_dt: null,
  });

  // 날짜 형식을 YYYY-MM-DD로 변경하는 유틸리티 함수 예시
  const changeFormat = (date, format) => {
    // 실제 구현 시 moment.js나 date-fns와 같은 라이브러리를 활용하여 형식 변환 가능
    const d = new Date(date);
    const year = d.getFullYear();
    const month = ("0" + (d.getMonth() + 1)).slice(-2);
    const day = ("0" + d.getDate()).slice(-2);
    return `${year}-${month}-${day}`;
  };

  // Axios 인스턴스 생성 (인증 토큰을 사용하는 경우 헤더 추가 가능)
  const authAxios = axios.create({
    baseURL: "/api/v1",
    headers: {
      "Content-Type": "application/json",
      // "Authorization": `Bearer ${token}`,
    },
  });

  // 엑셀 다운로드 핸들러 함수
  const handleDown = async (e) => {
    const { cmpgn_title, send_start_dt, send_end_dt } = campaignSearchData;
    let downXls = { send_start_dt: "", send_end_dt: "" };
    downXls.cmpgn_title = cmpgn_title;

    if (send_start_dt !== null) {
      downXls.send_start_dt = changeFormat(send_start_dt, "YYYY-MM-DD");
    }
    if (send_end_dt !== null) {
      downXls.send_end_dt = changeFormat(send_end_dt, "YYYY-MM-DD");
    }

    try {
      const res = await authAxios.get(
        `/campaign-report/download?send_start_dt=${downXls.send_start_dt}&send_end_dt=${downXls.send_end_dt}&cmpgn_title=${downXls.cmpgn_title}`,
        { responseType: "blob" }
      );

      console.log("응답 헤더:", res.headers);

      // 응답 헤더에서 파일명 추출 (정규표현식 사용)
      const contentDisposition = res.headers["content-disposition"] || "";
      const filenameRegex = /filename[^;=\n]*=((['"]).*?\2|[^;\n]*)/;
      const matches = filenameRegex.exec(contentDisposition);
      const filename =
        matches != null && matches[1]
          ? matches[1].replace(/['"]/g, "")
          : "download.xlsx";

      // FileSaver를 사용하여 파일 다운로드 실행
      FileSaver.saveAs(res.data, filename);
    } catch (error) {
      console.error("엑셀 파일 다운로드 중 오류 발생:", error);
    }
  };

  return (
    <div>
      <h2>엑셀 파일 다운로드</h2>
      <div>
        {/* 사용자 입력을 위한 간단한 폼 예시 */}
        <input
          type="text"
          placeholder="캠페인 제목"
          value={campaignSearchData.cmpgn_title}
          onChange={(e) =>
            setCampaignSearchData({
              ...campaignSearchData,
              cmpgn_title: e.target.value,
            })
          }
        />
        <input
          type="date"
          placeholder="발송 시작일"
          onChange={(e) =>
            setCampaignSearchData({
              ...campaignSearchData,
              send_start_dt: e.target.value,
            })
          }
        />
        <input
          type="date"
          placeholder="발송 종료일"
          onChange={(e) =>
            setCampaignSearchData({
              ...campaignSearchData,
              send_end_dt: e.target.value,
            })
          }
        />
      </div>
      <button onClick={handleDown}>엑셀 다운로드</button>
    </div>
  );
};

export default ExcelDownloadComponent;

위 컴포넌트는 사용자로부터 캠페인 제목과 발송 날짜를 입력받아, 해당 조건에 맞는 데이터를 엑셀 파일로 다운로드 받도록 구현되어 있습니다. 특히, API 호출 후 response.headers에 포함된 content-disposition에서 파일명을 추출하는 부분은 실제 서비스 환경에서도 자주 필요한 기술로, 본 예제를 참고하여 커스터마이징 할 수 있습니다.

구현 시 고려해야 할 보안 및 성능 이슈

실제 프로젝트에서 파일 다운로드 기능을 구현할 때는 단순한 기능 구현 외에도 몇 가지 추가적인 고려 사항이 있습니다.

1. 인증 및 권한 관리
   API 호출 시 토큰 기반 인증이 필수적입니다. Axios 인스턴스 생성 시 Authorization 헤더를 추가하여 사용자 인증을 철저히 관리하고, 권한이 없는 사용자가 파일 다운로드를 시도할 경우 적절한 에러 처리를 구현해야 합니다.
2. 파일 크기 및 다운로드 시간
   대용량 파일을 다운로드할 경우, 브라우저 메모리 사용량과 다운로드 시간에 주의해야 합니다. 필요에 따라 다운로드 진행 상태(progress)를 사용자에게 시각적으로 제공하는 것도 좋은 UX를 위해 고려해볼 수 있습니다.
3. 에러 처리 및 사용자 피드백
   파일 다운로드 중 네트워크 오류나 서버 오류가 발생할 수 있습니다. 이러한 경우, 사용자에게 명확한 에러 메시지를 제공하고, 재시도 옵션이나 대체 경로를 안내하는 것이 중요합니다.
4. 크로스 브라우저 호환성
   FileSaver 라이브러리는 대부분의 최신 브라우저에서 지원되지만, 특정 환경에서는 동작하지 않을 가능성도 있습니다. 크로스 브라우저 테스트를 통해 다양한 환경에서 파일 다운로드 기능이 원활히 작동하는지 확인해야 합니다.

결론

리액트 환경에서 엑셀 파일 다운로드 버튼을 구현하는 것은 단순히 API를 호출하는 것 이상의 복잡한 과정을 내포하고 있습니다. Axios를 이용하여 서버로부터 blob 데이터를 받아오고, FileSaver를 사용하여 파일을 저장하는 과정에서 HTTP 헤더에 포함된 파일명을 추출하는 부분은 특히 주의가 필요합니다.
이번 포스팅에서는 파일명 추출을 위해 JSON.stringify()와 문자열 조작, 또는 정규 표현식을 활용한 방법을 소개하였으며, 실제 코드 예제를 통해 보다 구체적으로 구현 방법을 설명드렸습니다. 이와 같은 기술을 활용하면, 리액트 프로젝트 내에서도 엑셀 파일 다운로드 기능을 손쉽게 구현할 수 있으며, 다양한 조건에 따른 검색 결과를 바로 엑셀 파일로 저장하는 기능을 제공하여 사용자 경험을 크게 향상시킬 수 있습니다.

앞으로도 다양한 파일 처리 및 다운로드 관련 기능에 대해 지속적으로 학습하고 적용해 나가시길 바라며, 이번 포스팅이 여러분의 개발 업무에 도움이 되길 바랍니다.