Retrofit 2 0很是简单的入门（翻译官方文档）

若是本文帮助到你，本人不胜荣幸，若是浪费了你的时间，本人深感抱歉。 但愿用最简单的大白话来帮助那些像我同样的人。若是有什么错误，请必定指出，以避免误导你们、也误导我。 本文来自：www.jianshu.com/users/320f9… 感谢您的关注。

声明：本文是转载的 转自：blog.csdn.net/leilba/arti… 很好奇这么好的东西，为何没人看。

Retrofit：Square提供的开源产品，为Android平台的应用提供一个类型安全的REST客户端。听说网络请求很是的快。 这个是官方文档（英文）：square.github.io/retrofit/

开始正文。

---

1. 介绍

Retrofit能够将你的HTTP API转化为JAVA的接口的形式。例如：

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

而Retrofit类可以生成对应接口的实现。例如：

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .build();

GitHubService service = retrofit.create(GitHubService.class);
复制代码

每个由接口返回的Call对象均可以与远程web服务端进行同步或者异步的HTTP请求通讯。例如：

Call<List<Repo>> repos = service.listRepos("octocat");
复制代码

Retrofit使用注解来描述HTTP请求： 1.URL参数的替换和query参数的支持 2.对象转化为请求体（如：JSON，protocol buffers等） 3.多重请求体和文件上传 注意：本站仍在为2.0扩展新的API

2. API说明

Retrofit须要注解接口的请求方法和方法的参数来代表该请求须要怎么样的处理。

2.1请求方法 每个方法必需要有一个HTTP注解来标明请求的方式和相对URL。有五种内置的注解方式：GET、POST、PUT、DELETE以及HEAD。资源的相对URL须要在注解里面明确给出：

@GET("users/list")
复制代码

固然你也能够将query参数直接写在URL里：

@GET("users/list?sort=desc")
复制代码

2.2 URL操做 一个请求的URL能够经过替换块和请求方法的参数来进行动态的更新。替换块是由被{}包裹起来的数字或字母组成的字符串构成的，相应的方法参数须要由@Path来注解一样的字符串。例如：

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId);
复制代码

Query参数也能同时添加。

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @Query("sort") String sort);
复制代码

复杂的query参数能够用Map来构建

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options);
复制代码

---

2.3请求主体 可以经过@Body注解来指定一个方法做为HTTP请求主体

@POST("users/new")
Call<User> createUser(@Body User user);
复制代码

这个参数对象会被Retrofit实例中的converter进行转化。若是没有给Retrofit实例添加任何converter的话则只有RequestBody能够做为参数使用。

**2.4 form encode 和 multipart ** 方法也能够经过声明来发送form-encoded和multipart类型的数据。 能够经过@FormUrlEncoded注解方法来发送form-encoded的数据。每一个键值对须要用@Filed来注解键名，随后的对象须要提供值。

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

也能够经过@Multipart注解方法来发送Mutipart请求。每一个部分须要使用@Part来注解。

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

多个请求部分须要使用Retrofit的converter或者是本身实现 RequestBody来处理本身内部的数据序列化。

2.5头部操做 你能够经过使用@Headers注解来设置请求静态头。

@Headers("Cache-Control: max-age=640000")
@GET("widget/list")
Call<List<Widget>> widgetList();
复制代码

@Headers({
    "Accept: application/vnd.github.v3.full+json",
    "User-Agent: Retrofit-Sample-App"
})
@GET("users/{username}")
Call<User> getUser(@Path("username") String username);
复制代码

注意的是头部参数并不会相互覆盖，同一个名称的全部头参数都会被包含进请求里面。 固然你能够经过 @Header 注解来动态更新请求头。一个相应的参数必须提供给 @Header 注解。若是这个值是空（null）的话，那么这个头部参数就会被忽略。不然的话， 值的 toString 方法将会被调用，而且使用调用结果。

@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)
复制代码

固然你能够经过OkHttp interceptor来指定每个须要的头部参数。

2.6同步 VS 异步 你能够同步或者异步地来执行实例。每一个示例只能使用一次，可是可使用 clone() 来建立一个可使用的新的实例。 在Android环境中，callback将会在主线程中执行；而在JVM环境中，callback将会在和Http请求的同一个线程中执行。

3. Retrofit配置

Retrofit类会经过你定义的API接口转化为可调用的对象。默认状况下，Retrofit会返还给你合理的默认值，但也容许你进行指定。

3.1转化器（Converters） 默认状况下，Retrofit只能将HTTP体反序列化为OKHttp的 ResonseBody 类型，并且只能接收 RequestBody类型做为 @Body。 转化器的加入能够用于支持其余的类型。如下六个同级模块采用了经常使用的序列化库来为你提供方便。

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

下面提供一个使用GsonConverterFactory类生成 GitHubService的接口实现gson反序列化的例子。

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.github.com")
    .addConverterFactory(GsonConverterFactory.create())
    .build();

GitHubService service = retrofit.create(GitHubService.class);
复制代码

3.2自定义转化器 若是你须要与没有使用Retrofit提供的内容格式的API进行交互的话或者是你但愿使用一个不一样的库来实现现有的格式，你也能够轻松建立使用本身的转化器。你须要建立一个继承自Converter.Factory的类而且在构建适配器的时候加入到实例里面。

4. 下载

↓ Latest JAR

源代码、例子和网站在 available on GitHub

4.1 maven

<dependency>
  <groupId>com.squareup.retrofit2</groupId>
  <artifactId>retrofit</artifactId>
  <version>2.0.0</version>
</dependency>
复制代码

4.2 gradle

compile 'com.squareup.retrofit2:retrofit:2.0.0'
复制代码

Retrofit支持最低 Java7 和 Android 2.3

4.3 混淆 若是你的工程中使用了代码混淆，那么你的配置中须要添加一下的几行

-dontwarn retrofit2.**
-keep class retrofit2.** { *; }
-keepattributes Signature
-keepattributes Exceptions
复制代码