开放原子开发者工作坊

　　以下为来自Github的retrofit的介绍。话说，翻译还真蛋疼，就这个花了快3个小时。

Retrofit 
一个在Android和Java上类型安全的HTTP客户端

介绍
Retrofit可以把你的HTTP API转换成java接口。
public interface GitHubService {
    @GET("users/{user}/repos")
    Call<List<Repo>> listRepos(@Path("user") String user);
}
Retrofit类实现GitHubService接口的实现。
Retrofit retrofit = new Retrofit.Builder().baseUrl("https://api.github.com").build();
GitHubService service = retrofit.create(GitHubService.class);
创建的GitHubService的每个 Call 可以产生一个同步的或者异步的HTTP请求到远程网络服务器。
Call<List<Repo>> repos = service.listRepos("octocat");
使用注释来描述HTTP请求：
1.支持URL参数替换和查询参数
2.请求body的对象转换(例如JSON,协议buffers)
3.Multipart的请求body和file上传

API描述
在接口方法和它的参数上面的注解暗示了请求怎么处理。

请求方法
每个方法必须有一个提供请求方法和相关URL的HTTP注解。这里有五个内置的注解：GET,POST,PUT,DELETE,和
HEAD.相关资源的URL被指定在注解中。
@GET("users/list")
你也可以在URL中指定查询的参数。
@GET("users/list?sort=desc")

URL操作
一个请求的URL可以用替代块和方法中的参数来动态更新。一个替代块是一个由{and}环绕的字母数字字符串。
一个匹配的参数必须使用同样的字符串的 @Path来注解。
@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId);
也可以添加查询参数
@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId,@Query("sort") String sort);
复杂的查询参数可以用一个组合的Map.
@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId),@QueryMap Map<String,String> options);

请求块
一个对象可以指定成一个用 @Body注解的HTTP请求body
@POST("users/new")
Call<User> createUser(@Body User user);
这个对象可以被Retrofit实例指定的转换者converter来转换。如果没有添加转换者，那么仅仅RequestBody可以被添加。

编码形式和Multipart
方法可以被定义来发送form-encoded和multipart 数据。
当 @FormUrlEncoded出现在方法中编码形式的数据就可以发送。每个键值对被用包含了名字和提供了值的对象的 
@Field注解。
@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first,@Field("last_name") String last);
当 @Multipart 出现在方法中可以使用Multipart 请求。Parts可以用 @Part注解来声明。
@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo,@Part("description") RequestBody description);
Multipart部分使用Retrofit的一个转换器或者它们可以实现RequestBody来处理它们自己的序列化。

头操作(HEADER MANIPULATION)
你可以用 @Headers 注解来给方法设置静态的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)
需要被添加到每个请求的Header头部可以用OkHttp interceptor插值器来指定。

同步与异步
Call 实例可以被同步或者异步来调用。每个实例仅仅被使用一次，但是呼叫clone()将会在使用的时候创建一个
新的实例。
在Android中，回调将会在main线程中执行。在JVM中，回调将会执行了HTTP请求的同一个线程中发生。

Retrofit配置
Retrofit是一个通过将你的API接口转换成可调用的对象的类。默认地，Retrofit将针对你的平台给你一个健全的
默认配置，但是也允许定制。

转换器
默认的，Retrofit仅仅可以支持反序列化HTTP的Body到OkHttp的ResponseBody类型，而且仅仅只能用 @Body 接受它的
RequestBody类型。
转换器可以被添加支持其它类型。六个同级的模块可以方便适配流行的序列化库。
1.Gson:com.squareup.retrofit2:converter-gson
2.Jackson:com.squareup.retrofit2:converter-jackson
3.Moshi:com.squareup.retrofit2:converter-protobuf
4.Wire:com.squareup.retrofit2:converter-wire
5.Simple XML:com.squareup.retrofit2:converter-simplexml
6.Scalars(原始的primitives，打包的boxed，和字符串String):com.squareup.retrofit2:converter-scalars
这里是一个使用GsonConverterFactory类生成使用了Gson的反序列化的GitHubService接口的实现的例子。
Retrofit retrofit = new Retrofit.Builder().baseUrl("https://api.github.com").addConverterFactory(
GsonConverterFactory.create()).build();
GitHubService service = retrofit.create(GitHubService.class);

定制的转换器
如果你需要和使用了Retrofit不支持的内容格式(例如YAML，txt,定制的格式)的API交流或者你希望使用不同的库
来实现一个存在的格式，那么你可以轻易地创建你自己的转换器。通过继承Converter.Factory类创建一个类，并且当
构建你的适配器时传到实例里面去。

MAVEN
<dependency>
  <groupId>com.squareup.retrofit2</groupId>
  <artifactId>retrofit</artifactId>
  <version>(insert latest version)</version>
</dependency>

GRADLE
compile 'com.squareup.retrofit2:retrofit:(insert latest version)'

Retrofit要求最小Java7或者Android 2.3

混淆
如果你在你的工程中使用混淆器，那么在你的配置中添加下列行：
-dontwarn retrofit2.**
-keep class retrofit2.** { *; }
-keepattributes Signature
-keepattributes Exceptions

Apache 版权