转自：http://ranseti.top/article/retrofit
Retrofit是Square公司支持的开源资源，适用于Android和Java的类型安全的HTTP客户端，了解Square公司点击https://squareup.com/global/en/pos，更多Square开源资源点击http://square.github.io/
Introduction(介绍)
Retrofit turns your HTTP API into a Java interface.
把你的HTTP API改造成java接口。
public interface GitHubService {
@GET("users/{user}/repos")
Call<List<Repo>> listRepos(@Path("user") String user);
}
The Retrofit class generates an implementation of the GitHubService interface.
Retrofit生成的GitHubService接口的实现。
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com/")
.build();
GitHubService service = retrofit.create(GitHubService.class);
Each Call from the created GitHubService can make a synchronous or asynchronous HTTP request to the remote webserver.
来自创建的GitHubService的每个调用都可以向远程Web服务器发出同步或异步的HTTP请求。
Call<List<Repo>> repos = service.listRepos("octocat");
Use annotations to describe the HTTP request:
使用注释来描述HTTP请求：
- URL parameter replacement and query parameter support(URL参数替换和查询参数支持)
- Object conversion to request body (e.g., JSON, protocol buffers)(将对象转换为请求正文（例如，JSON，协议缓冲区）)
- Multipart request body and file upload(Multipart 请求正文和文件上传)
API Declaration（API声明）
Annotations on the interface methods and its parameters indicate how a request will be handled.(接口方法及其参数的注解指示如何处理请求.)
REQUEST METHOD 请求方法
Every method must have an HTTP annotation that provides the request method and relative URL. There are five built-in annotations: GET, POST, PUT, DELETE, and HEAD. The relative URL of the resource is specified in the annotation.(每个方法都必须有一个提供请求方法和相对URL的HTTP注释。 有五个内置的注释：GET，POST，PUT，DELETE和HEAD。 资源的相对URL是在注释中指定的。)
@GET("users/list")
You can also specify query parameters in the URL.(您也可以在URL中指定查询参数。)
@GET("users/list?sort=desc")
URL MANIPULATION(URL操作)
A request URL can be updated dynamically using replacement blocks and parameters on the method. A replacement block is an alphanumeric string surrounded by { and }. A corresponding parameter must be annotated with @Path using the same string.(请求URL可以使用方法中的替换块和参数动态更新。 替换块是由{和}包围的字母数字字符串。 相应的参数必须用@Path使用相同的字符串进行注释。)
@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId);
Query parameters can also be added.(查询参数也可以被添加。)
@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @Query("sort") String sort);
For complex query parameter combinations a Map can be used.(对于复杂的查询参数组合，可以使用Map。)
@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options);
REQUEST BODY(请求体)
An object can be specified for use as an HTTP request body with the @Body annotation.(可以指定一个对象作为带有@Body注解的HTTP请求体。)
@POST("users/new")
Call<User> createUser(@Body User user);
The object will also be converted using a converter specified on the Retrofit instance. If no converter is added, only RequestBody can be used.(该对象也将使用Retrofit实例上指定的转换器进行转换。 如果没有添加转换器，则只能使用RequestBody。)
</br>
FORM ENCODED AND MULTIPART(表格编码和multipart)
Methods can also be declared to send form-encoded and multipart data.(方法也可以被声明为发送表单编码和multipart数据。)
Form-encoded data is sent when @FormUrlEncoded is present on the method. Each key-value pair is annotated with @Field containing the name and the object providing the value.(当方法中存在@FormUrlEncoded时，将发送表单编码的数据。 每个键值对都用@Field进行注释，包含名称和提供值的对象。)
@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);
Multipart requests are used when @Multipart is present on the method. Parts are declared using the @Part annotation.(当@Multipart出现在方法中时，使用Multipart请求。 参数是使用@Part注释声明的。)
@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);
Multipart parts use one of Retrofit's converters or they can implement RequestBody to handle their own serialization.（Multipart使用Retrofit的转换器之一，或者他们可以实现RequestBody来处理自己的序列化。）
HEADER MANIPULATION(请求头)
You can set static headers for a method using the @Headers annotation.(你可以使用@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);
Note that headers do not overwrite each other. All headers with the same name will be included in the request.(请注意，请求头不会相互覆盖。 所有名称相同的请求头将包含在请求中。)
A request Header can be updated dynamically using the @Header annotation. A corresponding parameter must be provided to the @Header. If the value is null, the header will be omitted. Otherwise, toString will be called on the value, and the result used.(请求标头可以使用@Header标注动态更新。 相应的参数必须提供给@Header。 如果该值为空，则标题将被省略。 否则，toString将被调用的值，并使用结果。)
@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)
Headers that need to be added to every request can be specified using an OkHttp interceptor.(需要添加到每个请求的头可以使用OkHttp拦截器来指定。)
SYNCHRONOUS VS. ASYNCHRONOUS(同步VS异步)
Call instances can be executed either synchronously or asynchronously. Each instance can only be used once, but calling clone() will create a new instance that can be used.(Call实例既可以同步执行，也可以异步执行。 每个实例只能使用一次，但调用clone（）将创建一个可以使用的新实例。)
On Android, callbacks will be executed on the main thread. On the JVM, callbacks will happen on the same thread that executed the HTTP request.(在Android上，回调将在主线程上执行。 在JVM上，回调将在执行HTTP请求的同一个线程上发生。)
Retrofit Configuration(Retrofit配置)
Retrofit is the class through which your API interfaces are turned into callable objects. By default, Retrofit will give you sane defaults for your platform but it allows for customization.(Retrofit类是API接口转换为可调用对象的类。 默认情况下，Retrofit会为你的平台提供理智的默认值，但是可以自定义。)
CONVERTERS（转换器）
By default, Retrofit can only deserialize HTTP bodies into OkHttp's ResponseBody type and it can only accept its RequestBody type for @Body.(默认情况下，Retrofit只能将HTTP主体反序列化为OkHttp的ResponseBody类型，并且只能接受其@Body的RequestBody类型。)
Converters can be added to support other types. Six sibling modules adapt popular serialization libraries for your convenience.(可以添加转换器来支持其他类型。 为了您的方便，六个兄弟模块适应流行的序列化库。)
- 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
Here's an example of using the GsonConverterFactory class to generate an implementation of the GitHubService interface which uses Gson for its deserialization.(下面是一个使用GsonConverterFactory类生成GitHubService接口的实现的示例，该接口使用Gson进行反序列化。)
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com")
.addConverterFactory(GsonConverterFactory.create())
.build();
GitHubService service = retrofit.create(GitHubService.class);
CUSTOM CONVERTERS(自定义转换器)
If you need to communicate with an API that uses a content-format that Retrofit does not support out of the box (e.g. YAML, txt, custom format) or you wish to use a different library to implement an existing format, you can easily create your own converter. Create a class that extends the Converter.Factory class and pass in an instance when building your adapter.(如果您需要与使用Retrofit不支持的内容格式（例如，YAML，txt，自定义格式）的API进行通信，或者您希望使用不同的库来实现现有格式，则可以轻松地创建 你自己的转换器。 创建一个继承Converter.Factory类的类，并在构建适配器时传递一个实例。)
