Retrofit之请求参数

Posted 2023-03-16

参考技术A 在上文，我们了解了如何定义请求Url，感兴趣的朋友可以参见 《Retrofit之请求Url》 。Retrofit系列持续更新，本文介绍如何使用Retrofit定义请求参数。

请求参数从传递方式可分三种：url参数，请求主体以及表单编码。我们来一一讨论。

url参数就是在url链接后面的键值对，例如 https://api.weibo.com/2//statuses/public_timeline.json?access_token=xxx 中，access_token就是url参数，xxx为其值。

Retrofit定义url参数非常直接，只要在方法参数前面添加@Query("key")注解即可。@Query中key的值与url中的参数名称是一致的，Retrofit会自动添加这些参数到url中。

以之前获取微博公共动态的API为例，具体API详见 http://open.weibo.com/wiki/2/statuses/public_timeline 。从接口中看到，必选参数只有access_token一个，我们定义个方法如下：

方法timelineForPublic需要参数token，Retrofit会通过@Query中定义的名称access_token将token映射成请求参数access_token。此时，请求url就会变成：

从获取微博公共动态的API中我们可以看到，除了必选的access_token，还有三个可选参数count、page以及base_app，也就是说现在请求参数有四个了。有了上面定义请求参数的介绍，我们只需要往方法上添加相应的参数并用@Query进行注解：

此时，如果我们只需要传递access_token，而不需要其他参数，则可以在调用方法的时候传null。当然，我们不能传null给int这样的原生类型，而需要使用对应的Integer。而Retrofit会跳过值为null的参数，并在组装请求的时候忽略它们。

获取公共微博最多有四个参数，那么我们再查看下获取好友微博API http://open.weibo.com/wiki/2/statuses/friends_timeline ，发现其有一个必选参数以及七个可选参数，也就是方法会有八个参数。那么问题来了，如果有更多的可选参数，那方法的参数是不是也会特别多，而且很多时候我们只需要其中一两个请求参数，却需要提供所有的参数值，显然很繁琐。为了处理这种情况，QueryMap就该登场了。

我们可以使用下面的方式定义获取公共微博API的方法：

@QueryMap后面需要紧跟着一个Map< String, String >类型，这样就可以动态地添加查询参数了。如果说只需要accept_token参数，则可以像下面这样调用：

这样，我们只需要传递我们需要设置的参数就可以了。

在我们查看微博的各个API时，会发现每个请求都需要一个access_token参数，于是我们就在所有的方法中都添加了对应的参数。那么有没有简单的方式来给每个请求都添加相同的参数，从而不需要每个请求都做相同处理呢？

强大的Retrofit是支持的，但是是通过OkHttp中的拦截器来实现的。我们在 《Retrofit之初体验》 提及过，Retrofit直接依赖OkHttp，使用OkHttp作为底层网络客户端。而使用OkHttp可以添加拦截器，用来修改即将发出去的请求，这个可以参见 《OkHttp之拦截器》 。这样我们就可以在拦截器中，对每个请求添加一个access_token参数了：

首先获取到了HttpUrl对象，然后基于原始的HttpUrl对象创建一个新的构建器，从而可以使用addQueryPatameter()方法添加额外的查询参数，最后将这个新的HttpUrl对象通过Request.Builder方法设置到Request中。

在我们实际应用中，大多数时候会通过请求主体向服务器发送数据。以我们的惯例，都会以微博API为例，但可惜的是并没有找过微博使用这种方式的API，而都使用的是表单方式，这个会在后面讨论。所以个很常见的例子，那就是登陆，通常请求参数如下：

好的，登录的方法定义如下：

其中LoginParam.java类如下：

首先，我们使用了@Body注解了方法参数，而我们在创建Retrofit.Builder的时候也为其添加了GsonConverter转换器。

这样，Retrofit会将LoginParam对象转换为Json，并将其作为主体数据添加到请求中，支持了使用请求主体向服务器发送数据。

在上面我们使用了用请求主体的方式来向服务器发送数据，除了这种方式，还可以通过表单编码(form-urlencoded)的形式。微博API中的写入接口都是采用这种方式向服务器发送数据的，我们这里以转发微博为例，具体API详见 http://open.weibo.com/wiki/2/statuses/repost 。

首先，定义转发微博的方法：

我们看到了@FormUrlEncoded注解，这个注解不能使用在GET请求上，因为它代表要想服务器发送数据。此外，在参数id上使用@Field注解，表示请求会发送此参数到服务器，而@Field("id")中的id则定义的是参数名称。

与@Query类似，当你有多个参数要发送时，只需要使用@Field注解它们即可。同样与@QueryMap对应的有个@FieldMap注解，具体使用类似。

@Field与@FieldMap都有一个属性encoded，表示键值对是否进行url编码，默认为false。以@Field为例，使用如下：

了解完@Field之后，我们讨论下表单编码与url参数的区别：表单编码使用在POST请求中的，而url参数是用在GET请求中的。表单编码使用请求主体发送数据到服务器，而不是url参数。而url参数的使用主要是为了从服务器过滤或者获取指定的数据。

Ok，本文就讨论到这里，感谢大家的阅读，下文我们将讨论Retrofit如何定义请求头。

如果你对retrofit感兴趣，同时你也觉得我的文章可以给你带来那么一丢丢的帮助，敬请关注，后续会继续介绍Retrofit的相关使用。

源码地址：
https://github.com/FILWandroid/DevJourney

关于源码：