Retrofit官方文档翻译

本文详细介绍了Retrofit网络请求框架的基本使用方法,包括HTTP API转换为Java接口、动态URL参数处理、请求体和响应体的序列化与反序列化、头部操作、同步与异步调用等核心功能。同时,提供了丰富的示例代码,帮助开发者快速掌握Retrofit的使用技巧。

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 个内置的注解:GETPOSTPUTDELETEHEAD。资源相关的 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 主体反序列化为 OkHttpResponseBody 类型,并且只能接收 @BodyResponseBody 类型。
  可以添加转换器来支持其他类型。可以方便的使用 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" 基础上发布,没有任何形式的保证或条件,无论是明示还是暗示。
  有关许可证下的权限和限制的特定语言,请参阅许可证。

转载于:https://www.cnblogs.com/zhangmiao14/p/10096227.html

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值