使用Retrofit2调用HTTP API

前言

Retrofit会将你的HTTP接口调用转换为java的interface,你不必去实现这个接口,交给Retrofit来创建动态代理.
首先,贴上官网和Javadoc.

官网上的例子

加依赖,下jar包什么的就跳过了,来一个官网例子就知道怎么用了.

//interface
public interface GitHubService {
  @GET("users/{user}/repos")
  Call<List<Repo>> listRepos(@Path("user") String user);
}

//创建工厂
Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .build();
    
//创建代理对象
GitHubService service = retrofit.create(GitHubService.class);

//调用方法获得Call对象
Call<List<Repo>> repos = service.listRepos("octocat");

此时还没有发送请求去调用HTTP API.Call对象提供了同步和异步两种方式来发送请求:

//同步,出错时抛出IO或者Runtime异常
Response response = call.execute();

//异步
call.enqueue(new Callback() {
    @Override
    public void onResponse(Call call, Response response)
    {
        //TODO 成功时的回调
    }

    @Override
    public void onFailure(Call call, Throwable t) {
        //TODO 失败时的回调
    }
});

关于Reponse和Call的细节,可以去看Javadoc.

注解介绍

Retrofit的类还是挺少的,这里就介绍些我用过的注解吧.

请求方式的注解

@GET,@POST,@DELETE,@HEAD,@PUT,@PATCH和@HTTP.除了@HTTP之外都没什么好说的.
@HTTP有三个参数:method,hasBody和path:

@HTTP(method = "DELETE", path = "admin/delete_user", hasBody = true)
Call<Message> deleteUser(@Body UserVO vo, @Header("Apitoken") ApiToken apiToken
        , @Header("X-Forwarded-For") String forwardedFor);

一些蛋疼的DELETE,POST或者PUT API的response会有body,但是@DELETE,@POST,@PUT都不能有body,这时候就要用@HTTP了.

参数位置的注解

@Header,@Body,@Path,@Query,@QueryMap,'@Headers'
对应的参数如果不是基本类型包装类的话会自动转换为json,没有记错的话,@Query,@QueryMap不能和'@POST','@PUT'搭配使用,直接来点例子吧.

@GET("strategy")
Call<List<Strategy>> getStrategyList(@Query("tid") Long tid,
                                     @Header("Apitoken")ApiToken apiToken,
                                     @Header("X-Forwarded-For") String forwardedFor);

@GET("graph/endpoint_counter")
Call<List<String>> getCounterOfEndpoint(@QueryMap Map<String, String> map,
                                        @Header("Apitoken") ApiToken apiToken,
                                        @Header("X-Forwarded-For") String forwardedFor);

//不要在意这个奇怪的API
@Headers({"Content-type: application/x-www-form-urlencoded"})
@GET("alarm/eventcases")
Call<List<EventCase>> getEventCasesById(@Query("eventid") String eventId, @Header("Apitoken") ApiToken apiToken,
                                        @Header("X-Forwarded-For") String forwardedFor);

请求数据格式的注解

需要注意的是格式和参数的注解是对应的.

@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);

@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);

转换器

通过添加不同的依赖来使用不同的转换器:

• Gson: com.squareup.retrofit2:converter-gson
• Jackson: com.squareup.retrofit2:converter-jackson
• Moshi: com.squareup.retrofit2:converter-moshi
• Protobuf: com.squareup.retrofit2:converter-protobuf
• Wire: com.squareup.retrofit2:converter-wire
• Simple XML: com.squareup.retrofit2:converter-simplexml
• Scalars (primitives, boxed, and String): com.squareup.retrofit2:converter-scalars