[CS - 네트워크] API 호출로 보는 네트워크

시나리오: Next.js(브라우저) → Spring Boot API 호출

• 프론트: https://app.example.com (브라우저)
• 백엔드: https://api.example.com (Spring Boot + (앞단에) Nginx/ALB 같은 프록시 있을 수도 있음)
• 호출: 로그인 후 유저정보 조회
  GET https://api.example.com/api/user

---

1) “한 번의 API 호출”이 실제로 지나가는 전체 흐름 (Spring Boot 기준)

브라우저에서 fetch/axios 호출

프론트 코드에서 fetch("https://api.example.com/api/user") 실행.
여기서부터 네트워크 시작.

---

DNS: 도메인 → IP로 변환 (7계층 서비스)

브라우저는 api.example.com의 IP 주소가 필요함.

• DNS 질의 → IP 응답 받음

DNS가 실패하면 아직 HTTP도 안 보냄.

---

TCP 연결: 3-way handshake (4계층)

브라우저(클라이언트)가 서버 IP의 443 포트로 TCP 연결을 만듦.

• SYN → SYN/ACK → ACK
• 이때 “연결”은 선이 아니라 상태 공유(세션 상태, 시퀀스 번호 관리 등)

여기서 실패하면 “연결 자체가 안 됨”류 에러가 나옴.

---

TLS Handshake: HTTPS 암호화 협상 (6계층 개념, 실제는 TCP 위)

HTTPS니까 TLS로:

• 서버 인증서 확인
• 키 합의
• 이후 데이터 암호화

여기서 실패하면 “SSL/TLS 관련 에러”가 뜸.

---

HTTP 요청 전송 (7계층)

이제야 진짜 요청이 나감:

• 메서드/경로/헤더/쿠키/Authorization 등 포함

이 HTTP 메시지가 내려가면서:

• TCP 헤더(포트/시퀀스/ACK 등) 붙고
• IP 헤더(목적지 IP) 붙고
• MAC 프레임이 되어 전송됨 (캡슐화)

---

(있다면) L7 프록시/로드밸런서 통과

실무는 보통 구조가:
브라우저 → (CDN/WAF/ALB/Nginx) → Spring Boot

• L7 장비는 HTTP 내용을 보고 라우팅/차단/리라이트 가능
• L4 장비는 TCP 연결 기준으로 분산

---

Spring Boot가 요청을 받는 지점

Spring Boot(Tomcat/Netty)가 443(혹은 내부 8080)에서 요청을 수신.

• 연결은 커넥션 풀/스레드 풀로 처리
• 필터/인터셉터/스프링 시큐리티 체인 탄 뒤
• Controller → Service → DB 호출

---

HTTP 응답 생성 → 동일 경로로 돌아감

Spring Boot가 200 OK + JSON 같은 응답을 만들고,
역방향으로 다시 캡슐화되어 브라우저로 돌아감.

---

2) 에러를 “네트워크 정의”로 딱 연결해서 보기

이제부터가 핵심.
에러는 결국 “흐름의 어느 계층/단계에서 끊겼냐”로 분류하면 됨.

---

A. DNS 단계 에러

 증상

• ERR_NAME_NOT_RESOLVED
• Could not resolve host

 네트워크 정의로 원인

• DNS는 도메인→IP 변환 서비스
• 변환이 안 되면 목적지(IP) 자체를 몰라서 TCP 연결을 시작할 수 없음

 흔한 이유

• 도메인 오타 / 레코드 누락
• 로컬 DNS 문제 / 회사망 DNS 차단

---

B. TCP 연결 단계 에러 (4계층)

증상

• ECONNREFUSED
• Connection refused
• No route to host
• Connection timed out(연결 시도 중 타임아웃)

 정의로 원인

• TCP는 포트 기반 프로세스 연결
• “refused”는 보통 대상 IP:PORT에 리스닝 프로세스가 없거나 방화벽/정책이 거부하는 상태
• “timeout”은 패킷이 돌아오지 않음 (중간에서 드랍 / 라우팅 문제 / 보안그룹 문제)

흔한 이유

• 서버가 안 떠있음(프로세스 다운)
• 보안그룹/방화벽에서 443 차단
• 포트 착각(8080 열었는데 443로 접근)

---

C. TLS(HTTPS) 단계 에러

증상

• NET::ERR_CERT_AUTHORITY_INVALID
• SSL handshake failed
• certificate verify failed

정의로 원인

• TLS는 암호화 통신 전에 신뢰(인증서) + 키 합의를 한다
• 인증서 체인이 신뢰되지 않거나, 도메인 불일치면 브라우저가 통신을 중단

흔한 이유

• 인증서 만료
• api.example.com이 아니라 다른 도메인으로 발급
• 중간 인증서 누락

---

D. CORS 에러 (7계층 정책 에러)

 증상

• 브라우저 콘솔에 CORS 에러
• 실제로는 서버가 200을 줬어도 브라우저가 막음

정의로 원인

• CORS는 네트워크 장애가 아니라 브라우저 보안 정책
• “다른 Origin(도메인/스킴/포트)”에 요청할 때,
  서버가 Access-Control-Allow-Origin 등으로 허용해야 브라우저가 응답을 JS에 넘김

흔한 이유

• Spring CORS 설정 누락
• 프리플라이트(OPTIONS) 응답이 401/403로 떨어짐

---

E. 401 / 403 (인증/인가) — HTTP 의미 단계 문제

증상

• 401 Unauthorized
• 403 Forbidden

정의로 원인

• 네트워크는 잘 연결되었고(=TCP/TLS/HTTP 전송 성공),
• HTTP 레벨에서 서버가 요청 의미를 거절한 것
• 401 = “너 누구냐(인증 필요/실패)”
• 403 = “너인 건 알겠는데 권한 없음(인가 실패)”

흔한 이유 (Spring Security)

• Authorization 헤더 누락/만료
• 토큰 검증 실패
• 권한(Role) 체크 실패

---

F. 404 (라우팅/리소스 매칭 실패)

정의로 원인

• 서버까지는 도달했는데,
• Spring MVC가 해당 path/method에 매칭되는 컨트롤러를 못 찾음

흔한 이유

• /api/user vs /api/users 오타
• 게이트웨이/Nginx 리라이트 설정 문제

---

G. 405 (Method Not Allowed)

정의로 원인

• 경로는 맞는데 HTTP method(GET/POST/PUT)가 틀림
• 스프링의 @GetMapping/@PostMapping 매칭 문제

---

H. 413 Payload Too Large

정의로 원인

• 요청 본문(파일 업로드 등)이 프록시/서버 제한보다 큼
• 대개 Nginx/ALB에서 컷

---

I. 429 Too Many Requests

정의로 원인

• 서버가 “요청 속도가 정책을 넘었다”라고 응답
• Rate limit 정책(7계층)

---

J. 500 (서버 내부 에러)

정의로 원인

• 네트워크는 성공.
• Spring 내부 로직/DB/예외 처리 문제

---

K. 502 Bad Gateway / 504 Gateway Timeout (프록시/게이트웨이 관점)

502 Bad Gateway

• 프록시(L7)가 뒤(Spring Boot)로 요청을 전달했는데
  뒤에서 “정상적인 HTTP 응답”을 못 받음

정의로 보면:

게이트웨이가 upstream과의 HTTP 통신에 실패

흔한 이유:

• Spring Boot 다운
• upstream 주소/포트 잘못됨
• upstream이 연결을 끊음

504 Gateway Timeout

• 프록시가 upstream에 요청을 보냈는데
  정해진 시간 내 응답이 안 옴

정의로 보면:

게이트웨이의 timeout 정책에 걸린 것

흔한 이유:

• Spring 처리 시간이 너무 김(외부 API/DB 지연)
• SSE/WebSocket 같은 장기 연결을 일반 타임아웃으로 처리
• 스레드 풀 고갈로 요청이 큐에서 대기

---

L. Read Timeout / Socket Timeout (클라이언트 관점)

정의

• TCP 연결은 됐고 요청도 갔는데,
• 응답 바이트가 지정 시간 내 도착하지 않음

보통:

• 서버 처리 지연
• 네트워크 끊김
• 중간 프록시가 응답을 버퍼링/차단

---

3) “에러를 보면 어느 계층 문제인지” 바로 찍는 규칙

이거 하나만 잡아도 디버깅 속도 확 늘어.

• DNS 에러: 도메인→IP 못 구함 (시작도 못 함)
• Connection refused/timeout: TCP 연결 단계(4계층)
• SSL handshake: TLS 단계
• CORS: 브라우저 정책(7계층)
• 401/403/404/405: HTTP 의미/라우팅(7계층)
• 502/504: 게이트웨이가 upstream과 통신 실패
• 500: 서버 내부 로직