파이썬 Requests 마이그레이션 가이드 HTTP/2 미지원과 Brotli 선택 의존 핵심 정리

파이썬 Requests 마이그레이션 가이드 HTTP/2 미지원과 Brotli 선택 의존 핵심 정리

🚀 업그레이드 전 꼭 확인할 호환성 체크포인트

프로덕션에서 오래 활용해 온 HTTP 클라이언트를 교체하거나 버전을 올릴 때 가장 많이 놓치는 부분이 바로 기본 프로토콜과 압축 코덱 지원 범위입니다. Requests는 친숙한 API 덕분에 수많은 코드베이스에 깊이 스며들어 있고, 파이썬 생태계의 사실상 표준처럼 쓰여 왔죠. 하지만 HTTP/2 채택이 늘고, 트래픽 최적화를 위한 브로틀리 압축 사용 사례가 확대되면서, 기존 설정을 그대로 가져가면 성능 이슈나 예기치 않은 호환성 문제가 드러나기도 합니다. 이 글에서는 Requests 중심의 마이그레이션·점검 관점에서 반드시 알아야 할 핵심 쟁점을 정리하고, 안전한 대안과 체크리스트까지 바로 적용할 수 있도록 도와드립니다.

핵심부터 짚어보면, Requests는 기본적으로 HTTP/1.1을 사용하는 라이브러리입니다. 즉, 기본값만으로는 HTTP/2가 활성화되지 않으며, HTTP/2 기능이 필요하다면 적절한 대안을 선택하거나 하위 스택의 지원 여부를 세심하게 확인해야 합니다. 또한 브로틀리(br) 콘텐츠 인코딩은 선택적 의존성으로 제공됩니다. 브로틀리 또는 brotlicffi 패키지가 설치되어 있을 때에만 ‘Accept-Encoding’ 협상이 br을 포함하도록 확장되는 구조이므로, 성능 최적화가 중요하다면 의존성 명시와 배포 이미지에의 포함 여부를 반드시 점검하세요. 만약 본격적인 HTTP/2가 필요하다면, httpx 같이 HTTP/2를 공식 지원하는 대안을 고려하는 것이 일반적입니다.

🔗 요약과 적용 대상

이 글의 핵심은 두 가지입니다.
첫째, Requests는 기본적으로 HTTP 1.1을 사용하며 HTTP 2는 기본 미지원입니다.
둘째, 브로틀리 압축은 선택적 의존성으로, 별도 패키지 설치가 있을 때에만 활성화됩니다.
즉, 성능이나 최신 프로토콜 요구가 있는 환경에서 “그대로 쓰면 되는가”를 먼저 따져봐야 합니다.
특히 CDN이나 API 게이트웨이가 HTTP 2를 적극 활용하는 조직, 리소스 전송량을 최대한 줄이고 싶은 모바일·글로벌 서비스, 고압축 응답을 자주 주고받는 데이터 파이프라인은 기본 설정만으로는 기대 성능을 내기 어렵습니다.

Requests로도 많은 서비스가 안정적으로 운영됩니다.
HTTP 1.1 기반의 엔드포인트, 사내용 통신, 단순 REST 호출 자동화, 레거시 시스템 연동이라면 큰 문제 없이 유지할 수 있습니다.
반면, HTTP 2의 멀티플렉싱이 사실상 필수이거나 서버가 br 압축을 기본 제공하는 상황에서는 선택적 의존을 정확히 걸어두거나, 아예 HTTP 2를 정식 지원하는 대안을 검토하는 편이 리스크를 줄입니다.
브로틀리 의존을 명시하지 않으면 배포 환경마다 동작이 달라질 수 있고, 성능 측정 결과가 일관되지 않게 나타나기 쉽습니다.

• 🧭제품 또는 파트너 API가 HTTP 2 강제인가요? 그렇다면 Requests 기본 설정만으로는 요구사항을 충족하지 않습니다.
• 📦서버 응답에 Content-Encoding: br이 빈번한가요? 배포 이미지에 brotli 또는 brotlicffi 설치를 포함했는지 확인하세요.
• 🚦동시성·지연시간 최적화가 핵심 KPI인가요? HTTP 2 멀티플렉싱 또는 대안 클라이언트 도입을 비교 검토하세요.
• 🧪스테이징에서 압축·프로토콜별 벤치마크를 진행했나요? 환경마다 결과가 달라질 수 있습니다.

💬 Requests는 기본 HTTP 1.1, 브로틀리는 선택적 의존이라는 전제만 정확히 반영해도 마이그레이션 리스크의 절반은 줄일 수 있습니다.

🛠️ HTTP 2 미지원과 대안

Requests는 오랜 기간 동안 HTTP 1.1을 기반으로 개발되어 왔습니다.
그 결과 HTTP 2 기능은 기본적으로 지원되지 않습니다.
이는 단순히 헤더 교환이나 압축 수준이 다르다는 문제를 넘어, 병렬 요청 처리 방식 자체에 영향을 미칩니다.
HTTP 2는 하나의 TCP 연결 안에서 여러 요청을 동시에 처리할 수 있는 멀티플렉싱 구조를 가지지만, Requests는 각 요청마다 별도의 연결을 생성하는 구조이므로 대규모 API 호출 환경에서는 비효율이 생길 수 있습니다.

따라서 HTTP 2 프로토콜을 사용하는 서버나 서비스와 통신해야 한다면, Requests 대신 HTTPX 같은 대체 라이브러리를 고려하는 것이 바람직합니다.
HTTPX는 Requests와 유사한 인터페이스를 제공하지만, 내부적으로 h2 모듈을 통해 HTTP 2를 완전하게 지원합니다.
게다가 비동기(async) 호출까지 지원해, 고성능 네트워크 환경에서도 효율적으로 작동합니다.

import httpx

# HTTP/2를 사용하는 클라이언트 예시
with httpx.Client(http2=True) as client:
    response = client.get("https://example.com/api")
    print(response.http_version)  # HTTP/2
    print(response.text)

위 예시에서처럼, HTTPX는 http2=True 플래그 하나로 간단히 HTTP 2를 활성화할 수 있습니다.
이와 달리 Requests는 동일한 기능을 제공하지 않으며, 서드파티 확장 패키지로도 완전한 HTTP 2 스택을 구성하기는 어렵습니다.

또한, 일부 서버는 HTTP 2를 지원하더라도 클라이언트 협상 과정에서 1.1로 폴백(fallback)되기도 합니다.
이 경우 클라이언트 단에서 프로토콜 버전을 강제 지정하거나, 세션 풀링을 비활성화해야 합니다.
Requests에서는 이 설정이 불가능하므로, 근본적으로 HTTP 2 성능 개선을 체감하기 어렵습니다.

💬 Requests는 안정성과 범용성 면에서 여전히 탁월하지만, HTTP 2의 성능적 장점을 활용하려면 HTTPX나 aiohttp 같은 대체 라이브러리가 현실적인 선택입니다.

⚙️ 브로틀리 선택적 의존과 압축

브로틀리(Brotli)는 Google이 개발한 차세대 압축 알고리즘으로, gzip보다 약 15~20% 더 높은 압축률을 제공합니다.
웹 서버와 CDN이 콘텐츠 전송 속도를 높이기 위해 널리 채택하고 있으며, 최신 브라우저는 물론 다양한 언어의 HTTP 클라이언트도 이를 지원합니다.
하지만 파이썬 Requests에서는 브로틀리 지원이 선택적 의존성(optional dependency)으로 처리되어 있습니다.
즉, 기본 설치만으로는 Brotli 압축을 자동 해제하지 않습니다.

Requests는 내부적으로 urllib3를 사용합니다.
urllib3는 brotli 또는 brotlicffi 모듈이 존재할 경우에만 이를 활용해 Accept-Encoding 헤더를 자동 확장합니다.
그렇지 않으면 gzip, deflate 정도만 협상에 포함되며, 서버가 br 압축으로 응답할 때는 해제에 실패하거나 원시 데이터가 그대로 반환될 수 있습니다.
따라서 Brotli 압축을 사용하는 API와 통신한다면 명시적으로 패키지를 추가해야 합니다.

# Brotli 또는 brotlicffi 중 하나 설치
pip install brotli
# 또는
pip install brotlicffi

두 패키지는 모두 Requests와 호환되지만, 환경에 따라 성능 차이가 존재합니다.
brotlicffi는 순수 파이썬 버전보다 설치가 빠르고, 멀티플랫폼에서 안정적으로 작동합니다.
반면 brotli 패키지는 C 기반 구현으로 압축·해제 속도가 빠릅니다.
빌드 환경에 따라 선택하면 됩니다.

• 🧩Requests만 설치되어 있다면 Brotli 해제가 지원되지 않습니다.
• 📦Brotli 압축을 사용하려면 brotli 또는 brotlicffi 중 하나를 추가로 설치하세요.
• ⚙️배포 이미지(Docker 등)에 브로틀리 패키지를 포함해야 일관된 동작을 보장합니다.
• 🧪서버 응답 헤더에 Content-Encoding: br이 표시되는지 로그로 확인하세요.

💬 Requests는 브로틀리를 ‘선택적’으로만 지원합니다. 즉, brotli 또는 brotlicffi 모듈이 없다면 단순히 무시되므로 반드시 환경 구성 단계에서 포함시켜야 합니다.

🔌 마이그레이션 체크리스트

Requests 기반 프로젝트를 마이그레이션하거나 유지보수할 때는 단순히 버전만 올리는 것보다, 의존성과 전송 계층의 변화까지 함께 점검해야 합니다.
특히 HTTP/2 비지원과 브로틀리의 선택적 의존성은 런타임 환경별로 결과가 달라질 수 있는 중요한 요인입니다.
아래 체크리스트를 기반으로 현재 시스템의 구성과 배포 전략을 재검토해 보세요.

• 🧭현재 사용 중인 서버가 HTTP/2 전용인지 확인합니다. HTTP/1.1 전용이라면 Requests 그대로 사용해도 무방합니다.
• 📦brotli 또는 brotlicffi 패키지가 배포 이미지에 포함되어 있는지 점검합니다.
• 🧰HTTP/2가 필요한 경우 HTTPX나 aiohttp 같은 대체 클라이언트를 검토합니다.
• 🚀서버 응답 헤더에서 Content-Encoding: br 여부를 로깅하거나, 미들웨어에서 자동 검증하도록 구성합니다.
• 🔒HTTP/2 전환 시 TLS 설정과 ALPN 협상(프로토콜 네고시에이션)을 반드시 검증합니다.
• 🧮성능 측정을 통해 HTTP/1.1 vs HTTP/2의 차이를 수치로 확인하고, 필요한 최적화를 도출합니다.

마이그레이션 과정에서는 종종 “서버가 HTTP/2를 지원하니 클라이언트도 당연히 HTTP/2로 통신하겠지”라는 착각이 생깁니다.
하지만 Requests는 이 협상을 자동으로 수행하지 않습니다.
이로 인해 일부 CDN이나 로드밸런서 환경에서는 의도치 않게 요청이 다운그레이드되어, 속도나 압축 효율이 떨어지는 현상이 발생하기도 합니다.

💬 Requests는 안정적인 HTTP/1.1 환경에 적합합니다.
그러나 HTTP/2와 Brotli 압축을 모두 활용해야 하는 프로젝트에서는 구성 검증과 의존성 관리가 핵심입니다.

💡 코드 예제와 권장 설정

Requests를 계속 사용하면서도 환경별 안정성과 성능을 개선하려면, 기본 구성과 헤더를 명시적으로 설정하는 것이 중요합니다.
HTTP/2는 지원되지 않지만, 세션 풀링이나 압축 지원을 적극 활용해 성능 손실을 최소화할 수 있습니다.
아래는 실무에서 자주 쓰이는 구성 예시입니다.

import requests

# 세션 재사용으로 연결 오버헤드 최소화
session = requests.Session()

# 브로틀리 압축을 활용하기 위해 brotli 또는 brotlicffi 설치 필요
headers = {
    "Accept-Encoding": "gzip, deflate, br",
    "User-Agent": "MyApp/1.0"
}

response = session.get("https://example.com/data", headers=headers)

print("응답 코드:", response.status_code)
print("Content-Encoding:", response.headers.get("Content-Encoding"))
print("응답 길이:", len(response.content))

위 코드에서 Accept-Encoding 헤더를 명시하면, 브로틀리 패키지가 설치된 환경에서는 자동으로 br 인코딩을 인식하고 해제할 수 있습니다.
하지만 패키지가 없다면 해당 압축을 해제하지 못하고 바이너리 응답을 그대로 반환할 수 있으므로 반드시 의존성을 포함해야 합니다.

대규모 서비스 환경에서는 이러한 설정 외에도 로깅과 예외 처리를 강화해야 합니다.
특히 압축 해제 오류, SSL 협상 실패, 콘텐츠 디코딩 문제는 배포 환경에 따라 다르게 나타날 수 있으므로 주기적으로 확인해야 합니다.

• 🧩브로틀리 해제 오류가 발생하면 brotli 설치 여부를 먼저 확인합니다.
• 🔍세션 객체를 재사용하면 HTTP/1.1에서도 상당한 성능 향상을 기대할 수 있습니다.
• ⚙️HTTP/2가 필요한 경우 httpx 또는 hyper 기반의 클라이언트로 전환하세요.
• 🧾압축 관련 문제를 추적하려면 logging.getLogger(“urllib3”)로 상세 로그를 활성화하세요.

💬 Requests는 여전히 강력한 도구이지만, 최신 네트워크 표준과 성능 최적화를 위해서는 작은 설정 하나에도 주의를 기울이는 것이 좋습니다.

❓ 자주 묻는 질문 (FAQ)

📘 Requests 환경 점검으로 안정성과 성능을 동시에

Requests는 여전히 파이썬 생태계에서 가장 널리 쓰이는 HTTP 클라이언트입니다.
그러나 최신 네트워크 환경에서는 HTTP/2와 Brotli 압축이 점점 보편화되고 있기 때문에, 이를 지원하지 않는 기본 설정만으로는 성능 최적화의 기회를 놓치게 됩니다.
따라서 프로젝트 환경을 점검하고, 필요한 경우 의존성을 명시적으로 추가하거나 HTTPX 같은 대안을 고려하는 것이 중요합니다.

브로틀리의 선택적 의존 구조는 단순히 성능 문제가 아니라, 운영 환경별 동작 차이를 야기할 수 있는 부분입니다.
배포 이미지나 CI/CD 단계에서 이를 포함하는지 반드시 확인해야 하며, HTTP/2 전환 여부는 서비스 요구사항과 인프라 구조에 맞춰 신중히 결정해야 합니다.
결국 안정성과 효율 사이의 균형이 핵심이며, Requests를 계속 활용하더라도 세심한 설정 관리로 충분한 성능 향상을 이끌어낼 수 있습니다.

🏷️ 관련 태그 : 파이썬requests, HTTP2, httpx, brotli, brotlicffi, urllib3, 웹성능최적화, API클라이언트, 프로토콜호환성, 파이썬개발팁