Retrofit官方文档翻译
官方文档网址
http://square.github.io/retrofit/
介绍
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 都会向远程 Web 服务端发送一个同步或异步的 HTTP 请求。
Call<List<Repo>> 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<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 的请求体去使用。
@POST("users/new")
Call<User> createUser(@Body User user)
对象可以在 Retrofit 实例中使用指定的转换器来进行转换。如果不添加转换器，则只能使用 RequestBody 。
格式转码和表单
也可以声明方法发送格式变化和表单数据。
当方法中提供了 @FormUrlEncoded 时，发送表单数据。@Field 的每一个键值对注解包含名称和提供的值。
@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first,@Field("last_name") String last)
当方法中提供了 @Multipart 时，表单请求被使用。 单子声明使用 @Part 注解。
@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo,@Part("description") RequestBody description);
表单部分使用 Retrofit 的一个转换器，也可以通过实现 RequestBody 处理它们自己的序列化。
头部操作
可以使用 @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);
注意，头不会覆盖彼此，相同名字的所有头都被包含在请求中。
一个请求头可以使用 @eader 注解动态更新。相应的参数必须提供 @Header。如果该值为空，头将会被忽略。否则，在数值上调用 toString 并且使用结果。
@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)
与查询参数相同，对于复杂的头组合，可以使用 Map。
@GET("user")
Call<User> getUser(@HeaderMap Map<String,String> headers)
可以使用 OkHttp 拦截器指定需要添加到每一个请求的头。
同步与异步
调用实例可以同步或异步执行。每一个实例只能使用一次，但调用 clone() 将创建一个可以使用的新的实例。
在 Android ，回调将在主线程上执行，在 JWM ,回调将发生在执行 HTTP 请求的同意线程上。
Retrofit 配置
Retrofit 是将 API 接口转换为回调对象的类。默认情况下， Retrofit 将提供平台合适的默认值并且允许自定义。
转换器
默认情况下，Retrofit 只能将 HTTP 主体反序列化为 OkHttp 的 ResponseBody 类型，并且只能接收 @Body 的 ResponseBody 类型。
可以添加转换器来支持其他类型。可以方便的使用 6 个常用的模块模式序列化库。
- 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的源码、例子和解释都在 Github 上。
MAVEN
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>retrofit</artifactId>
<version>(insert latest version)</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）获得许可；除非符合许可，否则不得使用此文件。可以在http://www.apache.org/licenses/LICENSE-2.0处获得许可。除非适用法律或书面同意，根据许可证发布的软件按 "AS IS" 基础上发布，没有任何形式的保证或条件，无论是明示还是暗示。
有关许可证下的权限和限制的特定语言，请参阅许可证。