의존성 라이브러리 추가

Retrofit을 사용하기 위해선 먼저 Gradle에 필요한 라이브러리를 포함해야 한다. 아래는 주요 의존성 설정 예시이다.

implementation 'com.squareup.retrofit2:retrofit:2.9.0'
implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
implementation 'com.squareup.okhttp3:okhttp:4.9.0'
implementation 'com.squareup.retrofit2:converter-scalars:2.9.0'

Retrofit 인스턴스 생성

기본 URL을 지정하고 변환기를 등록하여 Retrofit 객체를 구성한다. JSON 응답 처리를 위해 GsonConverter를, 문자열 응답이 필요할 경우 ScalarsConverter를 사용할 수 있다.

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(GsonConverterFactory.create()) // JSON → Object
    .addConverterFactory(ScalarsConverterFactory.create()) // String 처리
    .client(new OkHttpClient.Builder().build())
    .build();

API 인터페이스 정의

HTTP 요청은 인터페이스를 통해 선언되며, 어노테이션으로 메서드와 매개변수를 설정한다.

폼 데이터 전송 (FormUrlEncoded)

public interface AuthService {
    @POST("auth/register")
    @FormUrlEncoded
    Call<UserResponse> signUp(
        @Field("username") String username,
        @Field("password") String password
    );
}

파일 업로드 (Multipart)

이미지나 파일을 포함한 요청은 @Multipart를 사용하며, 각 파트는 @Part로 전달된다.

public interface ProfileService {
    @POST("user/update")
    @Multipart
    Call<String> updateProfile(
        @Part MultipartBody.Part avatar,
        @Part("userId") RequestBody userId,
        @Part("nickname") RequestBody nickname,
        @Part("gender") RequestBody gender
    );
}

실제 파일을 Multipart로 변환하는 코드 예시:

File file = new File(imagePath);
RequestBody requestFile = RequestBody.create(MediaType.parse("image/jpeg"), file);
MultipartBody.Part body = MultipartBody.Part.createFormData("avatar", file.getName(), requestFile);

RequestBody userId = RequestBody.create(MediaType.parse("text/plain"), "12345");

비동기 및 동기 요청 실행

생성된 인터페이스를 통해 Call 객체를 얻고, 이를 통해 네트워크 호출을 수행한다.

비동기 방식 (권장)

Call<UserResponse> call = retrofit.create(AuthService.class).signUp("john", "pass123");
call.enqueue(new Callback<UserResponse>() {
    @Override
    public void onResponse(Call<UserResponse> call, Response<UserResponse> response) {
        if (response.isSuccessful()) {
            UserResponse user = response.body();
            // 성공 로직 처리
        }
    }

    @Override
    public void onFailure(Call<UserResponse> call, Throwable t) {
        // 네트워크 오류 처리
    }
});

동기 방식 (별도 스레드에서 실행 필수)

try {
    Response<UserResponse> response = call.execute();
    if (response.isSuccessful()) {
        UserResponse user = response.body();
    }
} catch (IOException e) {
    e.printStackTrace();
}

요청 취소

더 이상 필요하지 않은 요청은 다음과 같이 취소할 수 있다.

if (!call.isCanceled()) {
    call.cancel();
}

Retrofit 주요 어노테이션 요약

• @GET, @POST, @PUT, @DELETE: HTTP 메서드 지정
• @HTTP: 커스텀 메서드와 경로를 직접 설정 가능
• @FormUrlEncoded: 폼 데이터 전송 시 사용 (application/x-www-form-urlencoded)
• @Multipart: 파일 업로드 등 multipart/form-data 요청에 사용
• @Field: POST 폼 필드 값 전달
• @Query: GET 요청의 쿼리 파라미터 추가
• @Header: 동적 헤더 값 설정
• @Url: 전체 URL을 매개변수로 전달

응답 변환기 선택 가이드

Retrofit은 다양한 Converter를 지원하며, 목적에 맞게 선택해야 한다.

• GsonConverterFactory: JSON 응답을 자동으로 Java 객체로 매핑
• ScalarsConverterFactory: 단순 문자열, 정수 등 기본형 반환 시 필요

두 변환기를 동시에 등록하면, Gson이 우선 적용되고, String이 필요할 때 Scalars가 대체적으로 작동한다.