[Android] Retrofit2 기본 설명

출처

ChatGPT

---

Retrofit2는 Android 애플리케이션에서 RESTful API와 통신하기 위해 널리 사용되는 HTTP 클라이언트 라이브러리이다. Retrofit2는 간단한 인터페이스로 API 요청을 처리하고, JSON, XML 같은 데이터를 자동으로 파싱하는 기능을 제공하여 Android 개발자들이 더욱 쉽게 서버와 통신할 수 있도록 도와준다.

 

Retrofit2 기본 개념

Retrofit2 특징

1. 인터페이스 기반의 선언적 HTTP 클라이언트

• Retrofit은 API 요청을 인터페이스로 정의하여, 인터페이스 메소드에 어노테이션을 사용해 HTTP 메소드를 선언적으로 작성할 수 있다.

2. 자동 데이터 파싱

• Retrofit은 Gson, Moshi 등과 같은 JSON 파서와 통합되어, 서버로부터 받은 JSON 데이터를 자동으로 자바/코틀린 객체로 변환한다.

3. 동기 및 비동기 호출 지원

• Retrofit은 네트워크 요청을 동기적으로 처리할 수 있을 뿐만 아니라 비동기적으로 처리하여 UI 쓰레드를 차단하지 않고 네트워크 작업을 수행할 수 있다.

4. 플러그블 아키텍처

• Interceptors, Converters, CallAdapters와 같은 다양한 기능을 플러그인 방식으로 추가하여 커스터마이징할 수 있다.

5. RxJava와의 통합

• Retrofit은 RxJava와 쉽게 통합되어, 반응형 프로그래밍을 이용한 네트워크 요청 처리가 가능하다.

 

Retrofit의 주요 구성 요소

 

• Base URL: 모든 HTTP 요청의 기본이 되는 URL.
• Converter: JSON과 같은 데이터를 자바 객체로 변환하는 역할. 기본적으로 Gson을 사용하지만, 필요에 따라 Moshi나 다른 컨버터를 사용할 수 있다.
• Call: API 요청을 추상화한 인터페이스로, Call 객체를 통해 네트워크 요청을 수행한다.
• Annotations: HTTP 메소드와 엔드포인트, 요청 파라미터 등을 인터페이스 메소드에 어노테이션으로 지정한다.
• Retrofit 객체: Retrofit 설정을 관리하며, 인터페이스를 구현한 서비스를 생성하는 데 사용된다.

 

 

Retrofit2 설치

Retrofit2를 Android 프로젝트에 설치하려면 'build.gradle'파일에 필요한 라이브러리르 추가해야 한다.

Gradle 설정

1. 프로젝트의 'build.gradle'파일에 다음과 같은 종속성을 추가한다.

dependencies {
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'      // Retrofit 라이브러리
    implementation 'com.squareup.retrofit2:converter-gson:2.9.0' // Gson 컨버터
    implementation 'com.squareup.okhttp3:logging-interceptor:4.9.1' // 로그 인터셉터 (선택 사항)
}

 

2. 프로젝트를 싱크해 라이브러리를 다운로드하고 적용한다.

 

Retrofit2 사용법

1.Retrofit 설정

Retrofit을 사용하기 위해서는 먼저 Retrofit 객체를 설정해야 한다. 이 객체는 HTTP 클라이언트를 구성하고, API 서비스 인터페이스를 생성하는 데 사용된다.

import retrofit2.Retrofit;
import retrofit2.converter.gson.GsonConverterFactory;

public class ApiClient {
    private static final String BASE_URL = "https://api.example.com/";
    private static Retrofit retrofit = null;

    public static Retrofit getClient() {
        if (retrofit == null) {
            retrofit = new Retrofit.Builder()
                    .baseUrl(BASE_URL)
                    .addConverterFactory(GsonConverterFactory.create()) // Gson 컨버터 설정
                    .build();
        }
        return retrofit;
    }
}

 

2. API 인터페이스 정의

Retrofit은 API 요청을 인터페이스로 정의한다. 각 API 엔드포인트에 대해 인터페이스 메소드를 작성하고, 어노테이션을 사용해 HTTP 메소드 및 URL 경로를 지정한다.

import retrofit2.Call;
import retrofit2.http.GET;
import retrofit2.http.Path;

public interface ApiService {
    // GET 요청: 사용자 목록 가져오기
    @GET("users")
    Call<List<User>> getUsers();

    // GET 요청: 특정 사용자 정보 가져오기
    @GET("users/{id}")
    Call<User> getUserById(@Path("id") int userId);
}

 

코틀린 예제

import retrofit2.Call
import retrofit2.http.GET
import retrofit2.http.Header
import retrofit2.http.Headers
import retrofit2.http.Path

interface ApiService {

    // 동적으로 Authorization 헤더 추가
    @GET("users/{id}")
    fun getUserById(@Path("id") userId: Int, @Header("Authorization") token: String): Call<User>

    // 고정된 헤더 추가
    @Headers("Content-Type: application/json")
    @GET("users/{id}")
    fun getUserByIdWithHeaders(@Path("id") userId: Int): Call<User>
}

 

3. 데이터 모델 정의

서버로부터 받는 JSON 데이터를 매핑할 클래스를 정의한다. Gson 라이브러리가 JSON 데이터를 자바 객체(코틀린은 데이터 클래스)로 변환한다.

public class User {
    private int id;
    private String name;
    private String email;

    // Getter 및 Setter 메소드
    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }
}

 

코틀린 예제

data class User(
    val id: Int,
    val name: String,
    val email: String
)

 

4. 네트워크 요청 실행

Retrofi 인스턴스를 사용해 API 인터페이스를 구현한 객체를 생성하고, 해당 객체를 통해 네트워크 요청을 수행한다.

import retrofit2.Call;
import retrofit2.Callback;
import retrofit2.Response;
import retrofit2.Retrofit;

public class MainActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // Retrofit 객체 생성 및 API 서비스 초기화
        Retrofit retrofit = ApiClient.getClient();
        ApiService apiService = retrofit.create(ApiService.class);

        // 사용자 목록 요청
        Call<List<User>> call = apiService.getUsers();

        // 비동기 요청 실행
        call.enqueue(new Callback<List<User>>() {
            @Override
            public void onResponse(Call<List<User>> call, Response<List<User>> response) {
                if (response.isSuccessful()) {
                    // 요청 성공
                    List<User> users = response.body();
                    // 사용자 목록 처리
                    for (User user : users) {
                        Log.d("MainActivity", "User ID: " + user.getId());
                        Log.d("MainActivity", "User Name: " + user.getName());
                        Log.d("MainActivity", "User Email: " + user.getEmail());
                    }
                } else {
                    // 요청 실패 (상태 코드)
                    Log.e("MainActivity", "Request Failed. Code: " + response.code());
                }
            }

            @Override
            public void onFailure(Call<List<User>> call, Throwable t) {
                // 네트워크 오류
                Log.e("MainActivity", "Network Error: " + t.getMessage());
            }
        });
    }
}

 

코틀린 예제

import retrofit2.Call
import retrofit2.Callback
import retrofit2.Response

fun main() {
    val apiService = ApiClient.getClient().create(ApiService::class.java)

    // 동적 헤더를 사용하는 예제
    val call: Call<User> = apiService.getUserById(1, "Bearer YOUR_TOKEN_HERE")
    call.enqueue(object : Callback<User> {
        override fun onResponse(call: Call<User>, response: Response<User>) {
            if (response.isSuccessful) {
                val user = response.body()
                // 사용자 정보 처리
                println("User: $user")
            } else {
                println("Request failed with code: ${response.code()}")
            }
        }

        override fun onFailure(call: Call<User>, t: Throwable) {
            // 오류 처리
            println("Request failed with error: ${t.message}")
        }
    })
}

 

설명

• enqueue(object : Callback<User>): Retrofit2의 비동기 호출을 수행하며, 응답을 처리하기 위한 콜백을 제공한다.

 

Retrofit2의 주요 기능

1. HTTP 요청 메소드

Retrofit2는 다양한 HTTP 요청 메소드를 지원하며, 각 메소드를 어노테이션으로 선언한다.

 

• @GET: GET 요청을 수행한다. 주로 데이터를 조회할 때 사용된다.
• @POST: POST 요청을 수행한다. 주로 데이터를 생성할 때 사용된다.
• @PUT: PUT 요청을 수행한다. 주로 데이터를 업데이트할 때 사용된다.
• @DELETE: DELETE 요청을 수행한다. 주로 데이터를 삭제할 때 사용된다.
• @PATCH: PATCH 요청을 수행한다. 주로 데이터를 부분적으로 업데이트할 때 사용된다.

예시 : 다양한 HTTP 메소드

public interface ApiService {
    // POST 요청: 새 사용자 생성
    @POST("users")
    Call<User> createUser(@Body User user);

    // PUT 요청: 사용자 정보 업데이트
    @PUT("users/{id}")
    Call<User> updateUser(@Path("id") int userId, @Body User user);

    // DELETE 요청: 사용자 삭제
    @DELETE("users/{id}")
    Call<Void> deleteUser(@Path("id") int userId);
}

 

 

2. 쿼리 파라미터와 경로 파라미터

• 경로 파라미터: URL 경로의 일부로 사용되는 변수이다. @Path 어노테이션을 사용한다.
• 쿼리 파라미터: URL 쿼리 문자열로 전달되는 변수이다. @Query 어노테이션을 사용한다.

예시 : 경로 파라미터와 쿼리 파라미터

public interface ApiService {
    // 경로 파라미터 사용
    @GET("users/{id}")
    Call<User> getUserById(@Path("id") int userId);

    // 쿼리 파라미터 사용
    @GET("users")
    Call<List<User>> getUsersByAge(@Query("age") int age);
}

 

 

3. 요청 본문 Request Body

POST, PUT 요청에서 JSON 데이터를 전송하기 위해 '@Body' 어노테이션을 사용하여 요청 본문을 정의할 수 있다.

 

예시 : 요청 본문

public interface ApiService {
    // POST 요청: 새 사용자 생성
    @POST("users")
    Call<User> createUser(@Body User user);
}

 

4. 헤더 Headers

API 요청 시 특정 헤더를 추가해야 하는 경우, '@Header' 또는 '@Headers' 어노테이션을 사용해 HTTP 헤더를 설정할 수 있다.

 

예시 : 헤더 설정

public interface ApiService {
    // 단일 헤더 설정
    @GET("users")
    Call<List<User>> getUsers(@Header("Authorization") String token);

    // 복수 헤더 설정
    @Headers({
        "Accept: application/json",
        "User-Agent: Retrofit-Sample-App"
    })
    @GET("users")
    Call<List<User>> getUsersWithHeaders();
}

 

• 공통 헤더 추가 방법  -> [Retrofit2] Retrofit2에서 API 호출 시 공통 헤더 값 추가 방법

 

5. Interceptors

Interceptros를 사용하여 네트워크 요청 및 응답을 수정하거나 로그를 출력할 수 있다. 이를 통해 인증 토큰을 자동으로 추가하거나, 디버깅 시 네트워크 요청/응답을 로깅할 수 있다.

 

예시 : Interceptor 사용

import okhttp3.Interceptor;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

import java.io.IOException;

public class ApiClient {
    private static final String BASE_URL = "https://api.example.com/";
    private static Retrofit retrofit = null;

    public static Retrofit getClient() {
        if (retrofit == null) {
            // Interceptor 설정
            OkHttpClient client = new OkHttpClient.Builder()
                    .addInterceptor(new Interceptor() {
                        @Override
                        public Response intercept(Chain chain) throws IOException {
                            Request original = chain.request();
                            Request request = original.newBuilder()
                                    .header("Authorization", "Bearer YOUR_TOKEN_HERE")
                                    .method(original.method(), original.body())
                                    .build();
                            return chain.proceed(request);
                        }
                    })
                    .addInterceptor(new HttpLoggingInterceptor().setLevel(HttpLoggingInterceptor.Level.BODY)) // 로그 출력
                    .build();

            retrofit = new Retrofit.Builder()
                    .baseUrl(BASE_URL)
                    .client(client)
                    .addConverterFactory(GsonConverterFactory.create())
                    .build();
        }
        return retrofit;
    }
}

 

Retrofit2와 RxJava 통합

Retrofit2는 RxJava와 통합되어 반응형 프로그래밍을 통해 비동기 요청을 더욱 간단하게 처리할 수 있다.

Gradle 설정

RxJava와 함께 사용할 수 있도록 추가 라이브러리를 설치한다.

dependencies {
    implementation 'com.squareup.retrofit2:adapter-rxjava2:2.9.0'
    implementation 'io.reactivex.rxjava2:rxjava:2.2.21'
    implementation 'io.reactivex.rxjava2:rxandroid:2.1.1'
}

 

RxJava를 활용한 Retrofit 예제

import io.reactivex.Observable;
import retrofit2.http.GET;

public interface ApiService {
    // RxJava Observable로 사용자 목록 요청
    @GET("users")
    Observable<List<User>> getUsers();
}

// Retrofit 객체 생성 시 RxJava Adapter 추가
Retrofit retrofit = new Retrofit.Builder()
        .baseUrl(BASE_URL)
        .addConverterFactory(GsonConverterFactory.create())
        .addCallAdapterFactory(RxJava2CallAdapterFactory.create()) // RxJava 어댑터 추가
        .build();

ApiService apiService = retrofit.create(ApiService.class);

// RxJava Observable 구독 및 처리
apiService.getUsers()
    .subscribeOn(Schedulers.io())
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe(users -> {
        // 사용자 목록 처리
    }, throwable -> {
        // 오류 처리
    });

 

결론

Retrofit2는 Android 개발에서 RESTful API와의 통신을 간편하게 만들어주는 강력한 라이브러리다. Retrofit의 인터페이스 기반 선언, 데이터 변환, 비동기 요청 지원 등의 기능은 RESTful API 통합을 단순화하고, 개발자의 생산성을 높여준다.

Retrofit2를 통해 서버와의 통신을 효과적으로 관리하고, RxJava와의 통합을 통해 복잡한 비동기 작업을 보다 쉽게 처리할 수 있다. 이를 통해 더욱 빠르고 안정적인 Android 애플리케이션을 개발할 수 있다.

 

---

관련 글

• 2024.07.29 - [빈 구멍 채우기] - [Retrofit2] Retrofit2에서 타임아웃 및 리트라이 설정