파일 업로드 기능, 첨부 성공만 확인하면 충분할까요?

안녕하세요. 사랑받는 IT 프로덕트의 첫걸음, 똑똑한개발자입니다.

오늘의 인사이트 요약

- 허용하는 파일의 형식·크기·개수를 선택 전에 안내합니다.

- 파일 전송과 서비스에서 사용할 준비가 끝난 상태를 구분합니다.

- 실패한 이유와 다시 할 일을 파일별로 안내합니다.

파일 업로드 기능을 의뢰할 때는 파일을 선택하고 목록에 나타나는지만 확인하기 쉽습니다. 그런데 실제 서비스에서는 휴대폰으로 찍은 사진이나 암호가 걸린 문서가 들어오고, 전송 도중 연결이 끊기기도 합니다. 첨부 버튼 하나에 어디까지 구현을 요청해야 할지 고민되는 이유입니다.

이 조건을 검수 막바지에 발견하면 안내 문구만 바꿀지 서버 처리까지 수정할지 다시 논의하게 됩니다. 오늘은 파일 업로드 기능을 기획하고 검수할 때 파일 선택부터 실제 사용까지 확인할 기준을 정리해보았습니다.

파일을 고르기 전에 제출 조건을 알 수 있어야 합니다

사용자가 파일을 준비할 때 필요한 정보를 선택 버튼 가까이에 둡니다.

허용 형식과 파일 하나의 최대 크기, 한 번에 올릴 수 있는 개수는 서로 다른 조건입니다. 여러 파일의 총용량도 제한한다면 그 기준을 따로 적습니다. 크기를 초과한 뒤에야 제한을 알려주면 사용자는 파일을 다시 줄이고 처음부터 시도해야 합니다.

예를 들어 증빙서류를 받는 서비스를 만든다고 가정해 보겠습니다.

PDF만 허용할지 휴대폰 사진도 받을지에 따라 사용자가 준비하는 과정이 달라집니다. 이미지라면 흐릿한 사진을 받았을 때 다시 제출하게 할지도 논의합니다. 허용 형식을 넓히면 서버에서 읽고 미리보기를 만드는 범위도 바뀌므로, 화면 문구와 개발 범위를 함께 결정합니다.

똑똑한개발자팀은 업로드 조건을 정할 때 파일을 받은 뒤 담당자가 어떤 일을 하는지부터 확인하는 편이 좋다고 생각하는데요. 단순히 보관할 문서와 내용을 추출해 심사할 문서는 필요한 조건이 다르기 때문입니다. 업무상 받지 않아도 되는 파일이라면 첨부를 필수로 두어야 하는지도 다시 살펴봅니다.

검수할 때는 정상 파일뿐 아니라 경계 조건을 준비합니다.

허용 크기와 같은 파일, 그보다 큰 파일, 빈 파일을 각각 넣어보는 식입니다. 이때 화면에 적힌 허용 조건과 서버가 받아들이는 조건이 일치하는지를 확인합니다. 구체적인 크기와 개수는 서비스 요구사항에서 정할 값이며 모든 업로드 기능에 공통으로 적용할 정답은 없습니다.

파일 전송이 끝난 뒤에도 처리 중일 수 있습니다.

파일이 서버에 도착했다고 곧바로 사용할 수 있는 것은 아닙니다. 서비스에 따라 파일 검사, 압축 해제, 미리보기 생성이나 내용 추출이 뒤따릅니다. 전송 완료를 최종 완료로 표시하면 사용자는 다음 단계로 넘어갔는데 운영 담당자는 파일을 열지 못하는 상황이 생길 수 있습니다.

이런 후속 처리가 있다면 파일을 고른 상태, 보내는 상태, 검사하는 상태, 사용 가능한 상태를 나누어 표시합니다. 전송률이 끝까지 찼는데 검사가 남았다면 무엇을 기다리는지 알립니다. 진행률을 정확히 계산할 수 없는 처리에는 근거 없는 숫자를 보여주기보다 현재 작업을 설명하는 편이 낫습니다. 제출 버튼을 언제 누를 수 있는지도 이 상태와 맞춰 정합니다.

업로드 보안을 점검할 때는 브라우저에서 선택 가능한 확장자만 제한하는 것으로 검증을 끝내지 않습니다.

서버에서도 허용 형식과 크기를 확인하고 파일을 올릴 권한과 저장 후 열람 권한을 점검합니다. 확장자나 전송된 Content-Type 정보 하나만으로 파일의 실제 내용과 안전성을 판단할 수는 없습니다. 검사 항목과 저장 위치를 함께 설계하는 방법은 OWASP의 파일 업로드 보안 가이드를 참고해 보세요.

검수표에는 화면 상태와 서버 결과를 나란히 적습니다. 후속 검사에서 거절된 파일이 성공 목록에 남는지, 처리 중에 페이지를 다시 열면 현재 상태를 확인할 수 있는지 살펴봅니다. 파일을 교체할 때 기존 파일을 언제 제거할지도 정해두면, 새 파일의 처리가 실패했을 때 필요한 자료까지 사라지는 문제를 예방하는 데 도움이 됩니다.

실패한 파일만 다시 제출할 수 있나요?

오류 안내는 사용자가 다음에 할 행동을 알려줘야 합니다.

형식이 맞지 않는 경우에는 허용 형식을, 용량이 큰 경우에는 허용 크기를 보여줍니다. 파일을 바꿔야 하는 오류와 잠시 후 같은 파일로 다시 시도할 수 있는 오류를 같은 문구로 처리하지 않습니다. 원인을 확인하지 못했다면 파일이 손상됐다고 단정하지 않고 재시도 방법을 안내합니다.

실패 원인을 설명합니다. 암호가 걸린 파일이나 내용이 비어 있는 파일처럼 이유가 확인된 경우에는 그 사실을 구체적으로 알립니다. 이런 오류 유형별 문구를 설계할 때는 GOV.UK의 파일 업로드 컴포넌트 지침에서 파일 미선택·형식·용량·암호 설정 등에 맞춘 안내 예시를 살펴보실 수 있습니다.

여러 파일 중 하나가 실패했다면 어떤 파일인지 이름과 함께 표시합니다.

앞서 성공한 파일을 유지한 채 실패한 항목만 다시 선택할 수 있는지도 확인합니다. 같은 이름의 파일을 다시 올렸을 때 교체인지 추가인지 알 수 있어야 하고, 사용자가 삭제한 항목이 제출 목록에도 남지 않아야 합니다. 똑똑한개발자팀은 이때 성공한 작업을 보존하는 것이 재시도 버튼을 제공하는 일만큼 중요하다고 보고 있습니다.

화면 안내와 서버 처리를 함께 검수합니다

업로드 검수는 파일 선택 화면에서 끝나지 않습니다. 사용자에게 보이는 완료 상태와 운영 담당자가 확인하는 첨부 목록이 일치하는지까지 이어집니다. 기획 단계에서 허용 조건, 처리 상태, 오류 후 행동을 한 흐름으로 정리하면 디자인과 개발에서 서로 다르게 이해한 부분을 찾기 쉽습니다.

똑똑한개발자는 웹·앱과 관리자 시스템, SaaS를 기획·디자인·개발·운영해온 경험을 바탕으로 서비스 개발을 돕습니다. 파일을 제출하는 사람과 이를 확인하는 담당자의 업무를 함께 살피면 화면만으로 해결할 부분과 서버 처리가 필요한 부분을 구분해 논의할 수 있습니다. 새 기능을 만드는 경우뿐 아니라 운영 중인 서비스의 불편을 개선할 때도 필요한 접근입니다.

파일 업로드를 포함한 서비스 기능의 사용 흐름과 개발 범위를 정리하고 싶다면 아래 똑똑한개발자 링크로 이야기 나눠주세요. 감사합니다. :)