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);
每个Call从被创造的GitHubService可以向远程web服务器发出同步或异步HTTP请求。
Call<List<Repo>> repos = service.listRepos("octocat");
使用注释来描述HTTP请求:
- URL参数替换和查询参数支持
- 到请求体的对象转换(例如，JSON、协议缓冲区)
- 多部分请求正文和文件上传
API声明
接口方法及其参数上的注释表明了如何处理请求。
请求方法
每个方法都必须有一个提供请求方法和相对URL的HTTP注释。有八个内置注释:HTTP, GET, POST, PUT, PATCH, DELETE, OPTIONS和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);
请求正文
对象可以被指定用作HTTP请求体@Body注释。
@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);
请注意，标头不会相互覆盖。所有具有相同名称的标头都将包含在请求中。
可以使用@Header注释。必须向提供相应的参数@Header。如果该值为null，将省略标头。否则，function toString() { [native code] }将对该值调用，并使用结果。
@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)
与查询参数类似，对于复杂的标题组合，一个Map可以使用。
@GET("user")
Call<User> getUser(@HeaderMap Map<String, String> headers)
需要添加到每个请求中的标头可以使用OkHttp拦截器.
同步与异步
Call实例可以同步或异步执行。每个实例只能使用一次，但是调用clone()将创建一个可以使用的新实例。
在Android上，回调将在主线程上执行。在JVM上，回调将发生在执行HTTP请求的同一个线程上。
改装配置
Retrofit是将API接口转换成可调用对象的类。默认情况下，改型将为您的平台提供合理的默认值，但它允许定制。
转换器
默认情况下，翻新只能将HTTP主体反序列化为OkHttpResponseBody类型，并且它只能接受其RequestBody类型为@Body.
可以添加转换器来支持其他类型。为了方便起见，六个兄弟模块采用了流行的序列化库。
- Gson:
com.squareup.retrofit2:converter-gson - 杰克逊:
com.squareup.retrofit2:converter-jackson - 魔石:
com.squareup.retrofit2:converter-moshi - 原蟾蜍:
com.squareup.retrofit2:converter-protobuf - 电线:
com.squareup.retrofit2:converter-wire - 简单XML:
com.squareup.retrofit2:converter-simplexml - JAXB:
com.squareup.retrofit2:converter-jaxb - 标量(基元、装箱和字符串):
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);
定制转换器
如果您需要与一个API进行通信，而该API使用的内容格式是翻新不支持的现成格式(例如YAML、txt、自定义格式)，或者您希望使用不同的库来实现现有的格式，您可以轻松地创建自己的转换器。创建一个扩展Converter.Factory班级并在构建适配器时传入一个实例。
[计] 下载
改造的源代码，它的样本和这个网站是可在GitHub上获得.
专家
<dependency> <groupId>com.squareup.retrofit2</groupId> <artifactId>retrofit</artifactId> <version>(insert latest version)</version> </dependency>
格拉德勒
implementation 'com.squareup.retrofit2:retrofit:(insert latest version)'
改造至少需要Java 8+或Android API 21+。
R8 /进步
如果您使用的是R8，收缩和模糊规则会自动包括在内。
ProGuard用户必须手动添加选项复古2.pro.
您可能还需要以下规则OkHttp和奥基奥它们是该库的依赖项。
贡献的
如果您想贡献代码，您可以通过GitHub来完成，方法是分叉存储库并发送一个pull请求。
提交代码时，请尽一切努力遵循现有的惯例和风格，以尽可能保持代码的可读性。也请确保您的代码通过运行./gradlew build(或者gradlew.bat build适用于Windows)。
在项目接受您的代码之前，您还必须签署个人贡献者许可协议(CLA).
许可证
Copyright 2013 Square, Inc. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
