ZLink HTTP Client For Java — 사용자 가이드

⚠️ 이 가이드는 최신이 아니다. 현재 리뷰·정비가 끝난 가이드는 .NET 가이드 하나뿐이다. 이 문서는 그 이전 상태이며, .NET 가이드가 완성되면 이 문서를 삭제하고 그것을 기준으로 다시 쓴다.

계약을 확인할 때는 이 문서를 믿지 말고 spec 트리를 본다.

zlink-http-client는 Java에서 HTTP request를 보내기 위한 범용 HTTP client다. zlink 스타일 fluent builder로 사용하며 공개 표면은 java.net.http 타입을 노출하지 않는다.

HttpResponse<CreateGameRes> game = ZLinkHttpClient.create("https://game-api.example.internal")
    .post("/games")
    .body(new CreateGameReq("ranked-match-0611"))
    .submit(CreateGameRes.class)
    .toCompletableFuture().join();   // 핸들러에서는 join 대신 thenCompose로 합성

목차

장	문서	내용
1	개요	설계 철학, 산출물 경계, 실행 모델
2	시작하기	의존성, 첫 요청, 한 줄 요청
3	Client 구성	builder 옵션, client 재사용, java.net.http 매핑
4	Request 만들기	HTTP 메서드, query, 헤더, request timeout
5	Request Body	JSON, raw, form, multipart, streaming 업로드
6	Response 다루기	응답 구조, submit/fetch, status 처리
7	비동기	CompletionStage, non-blocking, blocking 규칙
8	Streaming	download(sink) 다운로드, chunked 업로드
9	인증과 TLS	Basic/Bearer, HTTPS 검증, mTLS
10	Redirect · Retry · Cookie	redirect 의미론, 재시도, cookie jar
11	Proxy	HTTP proxy, proxy 인증
12	압축	gzip/deflate 투명 해제
13	에러 처리	예외 모델, retriable, 예외 경로

Kotlin coroutine(suspend) 확장과 DSL은 Kotlin coroutine 확장에서 다룬다 (java 런타임을 공유하는 얇은 idiom 레이어).

정식 계약과 회귀 테스트 축은 spec 문서 java-http-client.ko.md가 정본이다.