curl 완벽 활용 — API 디버깅에 꼭 쓰는 옵션 | 기술노트

Q: -d로 JSON을 보냈는데 서버가 못 읽어요.

Content-Type: application/json 헤더를 빠뜨렸을 가능성이 큽니다. curl은 -d 기본값을 application/x-www-form-urlencoded 로 보내므로, JSON이면 헤더를 명시해야 서버가 올바르게 파싱합니다.

Q: -v와 -i는 뭐가 다른가요?

-i 는 응답 헤더를 본문과 함께 출력하고, -v 는 요청 헤더·응답 헤더·TLS 핸드셰이크 과정까지 전부 보여줍니다. 문제가 어디서 나는지 모를 땐 -v 가 유용합니다.

핵심 요약

curl은 API 디버깅의 스위스 army knife다. -i(응답 헤더 포함), -X(메서드), -H(헤더), -d(본문), -v(상세 추적), -L(리다이렉트 따라가기) 여섯 개만 알면 대부분의 요청을 재현하고 진단할 수 있다.

1. 기본 GET과 응답 보기

curl https://api.example.com/users      # 본문만
curl -i https://api.example.com/users   # 상태줄+헤더+본문
curl -s -o /dev/null -w "%{http_code}\n" URL  # 상태코드만

2. POST — JSON 보내기

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{"name":"철수","age":20}'

-d를 쓰면 메서드가 자동으로 POST가 되므로 -X POST는 생략 가능하다.

3. 진단에 강한 옵션

옵션	용도
`-v`	요청/응답 헤더·TLS 과정까지 상세 출력
`-L`	301/302 리다이렉트를 끝까지 따라감
`-I`	HEAD 요청 — 헤더만 확인
`-k`	인증서 검증 무시(로컬 테스트 전용)
`--resolve`	DNS를 무시하고 특정 IP로 접속(배포 전 검증)

4. 응답 타이밍 측정

curl -s -o /dev/null -w \
 "dns:%{time_namelookup} connect:%{time_connect} ttfb:%{time_starttransfer} total:%{time_total}\n" \
 https://youngsam.net

어디서 느린지(DNS냐 연결이냐 서버 응답이냐)를 한 줄로 분해할 수 있다.

5. 실전 팁

브라우저 개발자도구 → Network → 요청 우클릭 → "Copy as cURL"로 복잡한 요청을 그대로 재현
쿠키는 -b "k=v"로 전송, -c cookies.txt로 저장
파일 업로드는 -F "file=@a.png"(multipart)

자주 묻는 질문

-d로 JSON을 보냈는데 서버가 못 읽어요.

Content-Type: application/json 헤더를 빠뜨렸을 가능성이 큽니다. curl은 -d 기본값을 application/x-www-form-urlencoded로 보내므로, JSON이면 헤더를 명시해야 서버가 올바르게 파싱합니다.

-v와 -i는 뭐가 다른가요?

-i는 응답 헤더를 본문과 함께 출력하고, -v는 요청 헤더·응답 헤더·TLS 핸드셰이크 과정까지 전부 보여줍니다. 문제가 어디서 나는지 모를 땐 -v가 유용합니다.

curl로 보낸 요청을 코드로 옮기려면요?

반대로 브라우저 Network 탭에서 "Copy as cURL"로 실제 요청을 복사한 뒤 curl로 재현하고, 동작을 확인한 다음 코드로 옮기는 흐름이 안전합니다. 헤더·쿠키 누락으로 인한 차이를 줄일 수 있습니다.