简介

Retrofit 是一个Square开发的类型安全的REST安卓客户端请求库。这个库为网络认证、API请求以及用OkHttp发送网络请求提供了强大的框架。Retrofit库让从web api下载JSON 或者xml数据变的非常简单直接。一旦数据下载完成即将其解析成普通java类(POJO)。

Retrofit turns your HTTP API into a Java interface.

Retrofit将你的HTTP API请求变为一个Java接口

public interface GitHubService {
@GET("users/{user}/repos")
Call<List<Repo>> listRepos(@Path("user") String user);
}

The Retrofit class generates an implementation of the GitHubService interface.

Retrofit生成了一个GitHubService接口的对象。

Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com/")
.build(); GitHubService service = retrofit.create(GitHubService.class);

Each Call from the created GitHubService can make a synchronous or asynchronous HTTP request to the remote webserver.

每一个GitHubService的请求都可以设为同步或者异步的HTTP请求。

Call<List<Repo>> repos = service.listRepos("octocat");

Use annotations to describe the HTTP request:

使用注释去描述HTTP请求

  • URL parameter replacement and query parameter support

  • Object conversion to request body (e.g., JSON, protocol buffers)

  • Multipart request body and file upload

  • 支持替换URL参数和询问参数

  • 对象可以转换成请求体(比如JSON,协议buffers)

  • 混合请求和文件上传

API声明

Annotations on the interface methods and its parameters indicate how a request will be handled.

接口方法和参数的注释说明了请求将如何被使用。

REQUEST METHOD请求方法

Every method must have an HTTP annotation that provides the request method and relative URL. There are five built-in annotations: GET, POST, PUT, DELETE, and HEAD. The relative URL of the resource is specified in the annotation.

每一个方法必须具有提供了请求方法和URL的HTTP注释,这里有五种注释,GETPOSTPUTDELETE和HEAD。资源相关的URL在注释中需特别声明。

@GET("users/list")

You can also specify query parameters in the URL.

你也可以将查询参数放在URL中

@GET("users/list?sort=desc")

URL MANIPULATION URL操作

A request URL can be updated dynamically using replacement blocks and parameters on the method. A replacement block is an alphanumeric string surrounded by { and }. A corresponding parameter must be annotated with @Path using the same string.

一个URL请求可以在方法中通过替换模块与参数进行动态更新,一个替换的模块是一串由{}包围的字符串。相关的参数必须使用@Path注释申明,申明的名称与之前的字符串一致。

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId);

Query parameters can also be added.

也可以添加查询参数。

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @Query("sort") String sort);

For complex query parameter combinations a Map can be used.

复杂的参数可以使用map。

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options);

REQUEST BODY请求体

An object can be specified for use as an HTTP request body with the @Body annotation.

一个对象可以通过@Body注释在HTTP请求中被使用。

@POST("users/new")
Call<User> createUser(@Body User user);

The object will also be converted using a converter specified on the Retrofit instance. If no converter is added, only RequestBody can be used.

一个对象可以被转换器转换成Retrofit实例,如果没有添加转换器,则只能使用RequestBody。

FORM ENCODED AND MULTIPART 表格编码和混合参数

Methods can also be declared to send form-encoded and multipart data.

方法也可以声明发送表格编码与混合数据。

Form-encoded data is sent when @FormUrlEncoded is present on the method. Each key-value pair is annotated with @Field containing the name and the object providing the value.

@FormUrlEncoded代表发送表格编码。每一个键值对通过@Field声明,包括名称和提供值的对象。

@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);

Multipart requests are used when @Multipart is present on the method. Parts are declared using the @Part annotation.

在方法中,混合参数请求使用@Multipart。每一部分通过@Part注释声明。

@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);

Multipart parts use one of Retrofit's converters or they can implement RequestBody to handle their own serialization.

混合部分使用Retrofit的转换器,或者他们使用RequestBody去处理自己的序列。

HEADER MANIPULATION 请求头操作

You can set static headers for a method using the @Headers annotation.

你可以在方法中使用@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);

Note that headers do not overwrite each other. All headers with the same name will be included in the request.

注意头文件不能互相覆盖,所有相同名称的头文件必须包含在请求中。

A request Header can be updated dynamically using the @Header annotation. A corresponding parameter must be provided to the @Header. If the value is null, the header will be omitted. Otherwise, toString will be called on the value, and the result used.

一个请求头可以通过@Header动态更新,相关的参数必须使用@Header提供。如果值为空,则头会被删除。否则,将调用toString的值,并使用结果。

@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)

Headers that need to be added to every request can be specified using an OkHttp interceptor.

如果每一个请求都需要增加头,可以使用OkHttp interceptor。

SYNCHRONOUS VS. ASYNCHRONOUS同步VS异步

Call instances can be executed either synchronously or asynchronously. Each instance can only be used once, but calling clone() will create a new instance that can be used.

调用实例可以同步或异步地执行。 每个实例只能使用一种,但是调用clone()将创建一个可以使用的新实例。

On Android, callbacks will be executed on the main thread. On the JVM, callbacks will happen on the same thread that executed the HTTP request.

在Android上,回调将在主线程上执行。 在JVM上,回调将发生在执行HTTP请求的同一个线程上。

Retrofit Configuration 设置

Retrofit is the class through which your API interfaces are turned into callable objects. By default, Retrofit will give you sane defaults for your platform but it allows for customization.

Retrofit是将API接口转换为可调用对象的类。 默认情况下,Retrofit将为您的平台提供的默认值,但也允许自定义设置。

CONVERTERS 转换器

By default, Retrofit can only deserialize HTTP bodies into OkHttp's ResponseBody type and it can only accept its RequestBody type for @Body.

默认情况下,Retrofit只能反序列化HTTP的请求体到OkHttp的ResponseBody类型,它只能接受@Body的RequestBody类型。

Converters can be added to support other types. Six sibling modules adapt popular serialization libraries for your convenience.

可以添加转换器来支持其他类型,包括六个流行的兄弟模块适应流行的序列化库,方便你使用。

  • Gson: com.squareup.retrofit2:converter-gson
  • Jackson: com.squareup.retrofit2:converter-jackson
  • Moshi: com.squareup.retrofit2:converter-moshi
  • Protobuf: com.squareup.retrofit2:converter-protobuf
  • Wire: com.squareup.retrofit2:converter-wire
  • Simple XML: com.squareup.retrofit2:converter-simplexml
  • Scalars (primitives, boxed, and String): com.squareup.retrofit2:converter-scalars

Here's an example of using the GsonConverterFactory class to generate an implementation of the GitHubService interface which uses Gson for its deserialization.

以下是使用GsonConverterFactory类生成使用Gson进行反序列化的GitHubService接口的实现的示例。

Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com")
.addConverterFactory(GsonConverterFactory.create())
.build(); GitHubService service = retrofit.create(GitHubService.class);

CUSTOM CONVERTERS自定义转化

If you need to communicate with an API that uses a content-format that Retrofit does not support out of the box (e.g. YAML, txt, custom format) or you wish to use a different library to implement an existing format, you can easily create your own converter. Create a class that extends the Converter.Factory class and pass in an instance when building your adapter.

如果您与API通信时,需要使用Retrofit不支持的内容格式(例如YAML,txt,自定义格式),或希望使用不同的库来实现现有格式,你可以轻松创建 你自己的转换器 创建一个扩展Converter.Factory类的类,并在构建适配器时传递一个实例。

原文网址:Retrofit A type-safe HTTP client for Android and Java

Retrofit简介与使用方法(翻译)的更多相关文章

  1. NetCat简介与使用方法

    精品学习网考试频道小编应广大考生的需要,特为参加考试的考生策划了“NetCat简介与使用方法”专题等有关资料,供考生参考! 在入侵中它是最经典的工具之一 ,NetCat被所有的网络安全爱好者和研究者称 ...

  2. Retrofit 简介 wiki 文档

    简介 Type-safe HTTP client for Android and Java by Square, Inc. GitHub主页:https://github.com/square/ret ...

  3. PHP Socket(套接字连接)扩展简介和使用方法

    PHP socket扩展是基于流行的BSD sockets,实现了和socket通讯功能的底层接口,它可以和客户端一样当做一个socket服务器. 使用这些函数时请注意,虽然他们中有很多和C函数同名的 ...

  4. nc之一:NetCat简介与使用方法

    精品学习网考试频道小编应广大考生的需要,特为参加考试的考生策划了“NetCat简介与使用方法”专题等有关资料,供考生参考! 在入侵中它是最经典的工具之一 ,NetCat被所有的网络安全爱好者和研究者称 ...

  5. python学习之路-1 python简介及安装方法

    python简介 一种面向对象.解释型计算机程序设计语言,由Guido van Rossum于1989年发明,第一个公开发行版发行于1991年. 目前最新版本为3.5.1,发布于2015年12月07日 ...

  6. git简介及使用方法

    一.git简介及安装1.git简介 Git 是用于 Linux 内核开发的版本控制工具.与常用的版本控制工具 CVS, Subversion 等不同,它采用了分布式版本库的方式,不必服务器端软件支持, ...

  7. JavaScript简介与使用方法

    1.JavaScript简介 1.1.JavaScript简史 最初:网络通信很慢,网页上的数据要传送到数据库验证,然后再返回错误结果,找客观过程要等很久,于是,网景公司开发出一门新语言,当时Java ...

  8. Android OkHttp + Retrofit 取消请求的方法

    本文链接 前言 在某一个界面,用户发起了一个网络请求,因为某种原因用户在网络请求完成前离开了当前界面,比较好的做法是取消这个网络请求.对于OkHttp来说,具体是调用Call的cancel方法. 如何 ...

  9. SAP Web Service简介与配置方法

    [版权声明]本文为博主原创文章,转载请在明显位置注明出处. 一. SAP Web Service简介 二. SAP Web Service配置准备工作 1. 通过RZ10配置服务器名称和其他参数 2. ...

随机推荐

  1. MSSQL 2012 密钥

    MICROSOFT SQL SERVER 2012 企业核心版激活码序列号: FH666-Y346V-7XFQ3-V69JM-RHW28 MICROSOFT SQL SERVER 2012 商业智能版 ...

  2. PREV-5_蓝桥杯_错误票据

    问题描述 某涉密单位下发了某种票据,并要在年终全部收回. 每张票据有唯一的ID号.全年所有票据的ID号是连续的,但ID的开始数码是随机选定的. 因为工作人员疏忽,在录入ID号的时候发生了一处错误,造成 ...

  3. Hadoop是怎么分块Block的?

    不多说,直接上干货! hadoop的分块有两部分. 第一部分就是数据的划分(即把File划分成Block),这个是物理上真真实实的进行了划分,数据文件上传到HDFS里的时候,需要划分成一块一块,每块的 ...

  4. [转]Win 10 的 Win 按键没反应

    来自:http://www.pc0359.cn/article/win10/66397.html 方法步骤: 1.首先我们需要将任务管理器运行出来.方法有两种,第一种:使用鼠标右键单击屏幕下方的任务栏 ...

  5. RPM安装MYSQL5.7

    RPM安装MYSQL5.7 1:YUM安装依赖库 yum install perl libaio numactl 2:下载安装需要的RPM包 https://dev.mysql.com/get/Dow ...

  6. mysql查询中取差集的问题

    有个场景 现在有个打卡的记录表(daka),记录了用户每天的打卡信息,同时还有个运动打卡表(sport_daka),如果用户有运动打卡则在运动打卡表里面记录. 现在要统计用户的每天的打开信息,包括运动 ...

  7. CentOS 7安装Oracle 11gR2以及设置自启动(1)

    一.环境准备 1.正确无误的CentOS 7系统环境 虚拟机要求: 内存至少2G 处理器至少2个 根分区要大于20G(安装oracle很占空间,空闲空间要足够) 2.正确的JDK环境 CentOS 7 ...

  8. python的68个内置函数

    内置函数 内置函数就是python给你提供的, 拿来直接用的函数, 比如print., input等. 截止到python版本3.6.2 python一共提供了68个内置函数. #68个内置函数 # ...

  9. [UE4]游戏中服务器切换地图,控制台命令Execute console Command

    Execute console Command ServerTravel {地图名称}?listen 在服务器执行了这个命令,所有连接到该服务器的客户端都会跟着服务器同时切换到指定的地图. 1.创建一 ...

  10. [UE4]死亡后调整视角

    AddLocalOffset:本地坐标偏移. 脱离控制器操作 会影响“OnDie”方法里面的相机移动操作,而函数里面又不允许使用“Delay”方法,但可以使用“Set Timer By Functio ...