Retrofit 2.X使用详解之基本使用

概述

        Retrofit是由Square公司出品的针对于Android和Java的类型安全的Http客户端，网络服务基于OkHttp 。

gradle配置

配置Retrofit 2.X

    Retrofit 2.X -compile 'com.squareup.retrofit2:retrofit:2.1.0'    OkHttp3 - compile 'com.squareup.okhttp3:okhttp:3.4.1'

配置Adapter

    Retrofit允许在执行Http时，调用不同的机制及第三方库，以便满足其他的线程模型或者开发框架，    做到无缝隙连接。此时，为满足对流行框架的适配，我们应当配置相应的适配器。Rertrofit现支持RxJava、    Guava及Java 8。    RxJava Observable & Single - com.squareup.retrofit2:adapter-rxjava    Guava ListenableFuture - com.squareup.retrofit2:adapter-guava    Java 8 CompleteableFuture - com.squareup.retrofit2:adapter-java8

配置Converters

    使用RestAdapter的转换器把HTTP请求结果（默认为JSON）转换为Java对象。    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 Framework - com.squareup.retrofit2:converter-simpleframework    Scalars - com.squareup.retrofit2:converter-scalars    LoganSquare - com.github.aurae.retrofit2:converter-logansquare    FastJson - org.ligboy.retrofit2:converter-fastjson                    or                    org.ligboy.retrofit2:converter-fastjson-android

注解

请求方式

@DELETE    String value：默认为""，值为请求的相对URL路径@GET    String value：默认为""，值为请求的相对URL路径@HTTP    String method()：请求方式    String path()：默认为""，值为请求的相对URL路径    boolean hasBody()：默认为false    @HTTP(method = "DELETE", path = "remove/", hasBody = true)    Call<ResponseBody> deleteObject(@Body RequestBody object);@OPTIONS    String value：默认为""，值为请求的相对URL路径@PATCH    String value：默认为""，值为请求的相对URL路径@POST    String value：默认为""，值为请求的相对URL路径@PUT    String value：默认为""，值为请求的相对URL路径@FormUrlEncoded         注解发送表单数据，使用@Field或者@FieldMap注解和参数来指定每个表单项的key，    value为参数的值。@Multipart      注解用与发送multipart数据，使用@Part或者@PartMap注解定义即将发送的每一个文件// 请求头设置    @HEAD    包含Head的Request请求@Streaming    注解请求方式，将返回值okhttp3.Response.body() body()转换为byte[]  

请求参数

@Body        请求体，声明一个对象作为请求体发送到服务器，用于POST/PUT请求        @POST("users/new")        Call<ResponseBody> getInfo(@Body User user);    @Field    String value：默认为""，参数名称    bolean encoded：指定的名称和值是否已URL编码，默认为false，    @FormUrlEncoded    @POST("login")    Call<ResponseBody> login(@Field("name") String name,                                                @Field("pwd") String pwd);    // {@code name=Bob+Smith&pwd=123}    @FormUrlEncoded    @POST("queryScore")    Call<ResponseBody> queryScore(@Field("name") String... name);                   // {@code name=Bob&name=Jane}@FieldMap    bolean encoded：指定的名称和值是否已URL编码，默认为false，    @FormUrlEncoded    @POST("things")    Call<ResponseBody> things(@FieldMap Map<String, String> fields);@Part       String value()：默认为""，参数名称    String encoding()：默认编码格式为 "binary";    @Multipart    @POST("upload")    Call<ResponseBody> upload(@Part("description") String description,                                                  @Part(value = "image", encoding = "8-bit") RequestBody image);@PartMap    String encoding()：默认编码格式为 "binary";    @Multipart    @POST("upload")    Call<ResponseBody> upload(@Part("file") RequestBody file,@PartMap Map<String, RequestBody> params);@Path    String value()：参数名称    boolean encoded() ：指定的名称和值是否URL编码，默认为false(URL编码)。设置为true时，不进行URL编码    @GET("image/{id}")    Call<ResponseBody> getInfo(@Path("id") int id);    // 指定的名称和值默认URL编码    @GET("user/{name}")    Call<ResponseBody> encoded(@Path("name") String name);    // 指定的名称和值取消URL编码    @GET("user/{name}")    Call<ResponseBody> notEncoded(@Path(value="name", encoded=true) String name);@Query      String value：默认为""，参数名称    bolean encoded：指定的名称和值是否已URL编码，默认为false，    @GET("list")    Call<ResponseBody> list(@Query("page") int page);    /* https://api.example.com/tasks?id=123  */    @GET("list")    Call<ResponseBody> list(@Query("category") String ... page);    @GET("search")    Call<ResponseBody> list(@Query(value="foo", encoded=true) String foo);    @GET("tasks")    Call<List<Task>> getTask(@Query("id") List<Long> taskIds);    /* https://api.example.com/tasks?id=123&id=124&id=125   */@QueryMap       bolean encoded：指定的名称和值是否已URL编码，默认为false，        @GET("search")    Call<ResponseBody> list(@QueryMap Map<String, String> filters);    @GET("search")    Call<ResponseBody> list(@QueryMap(encoded=true) Map<String, String> filters);@Url    注解的值为请求的相对URL路径    @GET    Call<ResponseBody> list(@Url String url);

请求头

@Headers    String[] value();    @Headers({        "X-Foo: Bar",        "X-Ping: Pong"    })    @GET("deleteObject")     Call(ResponseBody) deleteObject(@Query("id") String id);@Header    String value：默认为""，参数名称    @GET("query")    Call<ResponseBody> query(@Header("Accept-Language") String lang);@HeaderMap@GET("query")Call<ResponseBody> query(@HeaderMap Map<String, String> headers);

URL定义方式

public interface UserService{    @GET("query")    Call<ResponseBody> query(@Query("id") String id);    @GET()    Call<ResponseBody> profilePicture(@Url String url);     }

静态URL

Retrofit retrofit = Retrofit.Builder()  .baseUrl("https://teapy.api.url/");.build();UserService service = retrofit.create(UserService.class);  service.query("123");// 请求URL// https://teapy.api.url/query

动态URL

Retrofit retrofit = Retrofit.Builder()      .baseUrl("https://teapy.api.url/");    .build();UserService service = retrofit.create(UserService.class);  service.profilePicture("https://s3.amazon.com/profile-picture/path");// request url results in:// https://s3.amazon.com/profile-picture/pathRetrofit retrofit = Retrofit.Builder()  .baseUrl("https://teapy.api.url");.build();UserService service = retrofit.create(UserService.class);  service.profilePicture("profile-picture/path");// request url results in:// https://teapy.api.url/profile-picture/pathRetrofit retrofit = Retrofit.Builder()  .baseUrl("https://your.api.url/v2/");.build();UserService service = retrofit.create(UserService.class);  service.profilePicture("/profile-picture/path");// request url results in:// https://teapy.api.url/profile-picture/path

备注：

• Base URL: 总是以 /结尾

• @Url: 不要以 / 开头

同步请求

Retrofit retrofit = Retrofit.Builder()      .baseUrl("https://teapy.api.url/");    .build();UserService service = retrofit.create(UserService.class);  <ResponseBody> call = service.query("123");ResponseBody body = call.execute();

备注： 
同步请求是耗时操作，且执行时是在当前线程执行。若在UI线程执行同步请求，此时会阻塞UI线程。耗时过长，容易造成ANR。故执行同步请求时，需自行开辟线程，以免造成ANR。

异步请求

Retrofit retrofit = Retrofit.Builder()      .baseUrl("https://teapy.api.url/");    .build();UserService service = retrofit.create(UserService.class);  <ResponseBody> call = service.query("123");call.enqueue(new Callback<Repo>() {    @Override    public void onResponse(Response<Repo> response) {        // Get result Repo from response.body()    }    @Override    public void onFailure(Throwable t) {    }});

取消请求

call.cancel();

自定义转换器

        在定义API时，Call都是使用封装的Java对象作为泛型，但是请求返回的数据均是Json类型。Retrofit并不支持此格式数据与API进行通信。如果想实现此操作，应添加相应的转换器。

 Retrofit retrofit = new Retrofit.Builder()    .baseUrl(BASE_URL)    .addCallAdapterFactory(RxJavaCallAdapterFactory.create()) // 使用RxJava作为回调适配器    .addConverterFactory(GsonConverterFactory.create()) // 使用Gson作为数据转换器    .build();

RxJava、Gson、OkHttp支持

Retrofit 2.0：有史以来最大的改进已做了详细的介绍，不了解可看此文。

参考资料

1.Retrofit 2.0：有史以来最大的改进

2.官方文档

3.RxJava教程