Retrofit官方文档翻译
官方文档网址http://square.github.io/retrofit/
介绍
Retrofit 将你的 HTTP API 转换为 Java 接口。
public interface GitHubService { @GET("users/{user}/repos") Call > 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 都会向远程 Web 服务端发送一个同步或异步的 HTTP 请求。
Call
> repos = service.listRepos("octocat");
使用注解描述 HTTP 的请求：
- URL 参数替换和查询参数支持
- 对象转换为请求体（如， JSON ，协议缓存区）
- 多方面请求体和文件上传
API 声明
接口方法及其参数注释说明如何处理请求。
请求方法
每个方法必须有一个提供请求方法和相关的 URL 的 HTTP 注解。有 5 个内置的注解：GET、POST、PUT、DELETE和HEAD。资源相关的 URL 由注解指定。
@GET("users/list") 还可以在 URL 中指定查询参数。
@GET("users/list?sort=desc") URL 操作
可以使用替换块和方法的参数动态更新请求的URL。替换块是一个由 { 和 } 包裹的字符字符串。对应的参数必须使用同样的字符串 @Path 注解。
@GET("group/{id}/users") Call > groupList(@Path("id") int groupId)
请求参数也可以增加。
@GET("group/{id}/users") Call > groupList(@Path("id") int groupId,@Query("sort") String sort)
对于复杂的请求参数组合可以使用 Map。
@GET("group/{id}/users") Call > groupList(@Path("id")int groupId,@QueryMap Map options);
请求体
@Body 注解被指定作为 HTTP 的请求体去使用。
@POST("users/new") Call createUser(@Body User user) 对象可以在 Retrofit 实例中使用指定的转换器来进行转换。如果不添加转换器，则只能使用 RequestBody 。
格式转码和表单
也可以声明方法发送格式变化和表单数据。
当方法中提供了@FormUrlEncoded 时，发送表单数据。@Field 的每一个键值对注解包含名称和提供的值。 @FormUrlEncoded @POST("user/edit") Call updateUser(@Field("first_name") String first,@Field("last_name") String last) 当方法中提供了 @Multipart 时，表单请求被使用。 单子声明使用 @Part 注解。
@Multipart @PUT("user/photo") Call updateUser(@Part("photo") RequestBody photo,@Part("description") RequestBody description); 表单部分使用 Retrofit 的一个转换器，也可以通过实现 RequestBody 处理它们自己的序列化。
头部操作
可以使用 @Headers 注解为方法这只静态的头。
@Headers("Cache-Control: max-age=640000") @GET("widget/list") Call > widgetList();
@Headers({ "Accept: application/vnd.github.v3.full+json", "User-Agent: Retrofit-Sample-App" }) @GET("users/{username}") Call getUser(@Path("username") String username); 注意，头不会覆盖彼此，相同名字的所有头都被包含在请求中。
一个请求头可以使用@eader 注解动态更新。相应的参数必须提供 @Header。如果该值为空，头将会被忽略。否则，在数值上调用 toString 并且使用结果。 @GET("user") Call getUser(@Header("Authorization") String authorization) 与查询参数相同，对于复杂的头组合，可以使用 Map。
@GET("user") Call getUser(@HeaderMap Map headers) 可以使用 OkHttp 拦截器指定需要添加到每一个请求的头。
同步与异步
调用实例可以同步或异步执行。每一个实例只能使用一次，但调用 clone() 将创建一个可以使用的新的实例。
Retrofit 配置
Retrofit 是将 API 接口转换为回调对象的类。默认情况下， Retrofit 将提供平台合适的默认值并且允许自定义。
转换器
默认情况下，Retrofit 只能将 HTTP 主体反序列化为 OkHttp 的 ResponseBody 类型，并且只能接收 @Body 的 ResponseBody 类型。
- Gson : com.squareup.retrofit2:cenverter-gson
- Jackson : com.squareup.retrofit2:converter-jackson
- Moshi : con.squareup.retrofit2:converter-moshi
- Protobuf : com.squareup.retrofit2:converter-protobuf
- Wire : com.squareup.retrofit2:cenver-wire
- Simple XML : com.squareup.retrofir2:converter-simplexml
- Scalars(primitives,boxed,and String):com.square.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); 自定义转换器
如果需要与使用 Retrofit 不支持的内容格式（如， YAML , txt , 自定义格式）的 API 或者希望使用实现现有格式的不同库，可以轻松创建自己的转换器。创建继承 Converter.Factory 类的类并且在创建适配器是传入实例。
下载
Retrofit的源码、例子和解释都在 上。
MAVEN
com.squareup.retrofit2 retrofit (insert latest version)
GRADLE
implementation 'com.squareup.retrofit2:retrofit:(insert latest version)'
Retrofit请求的最低是 Java 7 或 Android 2.3 。
R8/PROGUARD
如果使用 R8 或者 ProGuard ，则添加选项到文件中。
如果使用 OKHTTP 和 Okio 的库，也需要同样的方法。贡献
如果希望贡献代码，可以通过 GitHub fork 库并发送提交请求。
提交代码时，请尽一切努力遵循校友的约定和样式以确保保持代码的可能性。请确保代码的运行和测试完整。 在代码被合并到项目之前需要遵守个人贡献者许可协议。许可
版权所有 2013 Square,Inc。
根据 Apache 许可证 2.0 （License）获得许可；除非符合许可，否则不得使用此文件。可以在处获得许可。除非适用法律或书面同意，根据许可证发布的软件按 "AS IS" 基础上发布，没有任何形式的保证或条件，无论是明示还是暗示。
有关许可证下的权限和限制的特定语言，请参阅许可证。