Retrofit 2 – Query和Path参数示例

       Retrofit 2 通过使用@Query和@Path注解来处理单个，多个甚至可选的查询参数和路径参数请求
 

1.查询参数

Retrofit使用@Query注释来定义请求的查询参数。查询参数在方法参数之前定义。在注释中，我们传递将附加在URL中的查询参数名称。

1.1。单个或多个查询参数

使用与@Query我们要发送的参数一样多的注释

https://<DOMAIN>/api/users?page=2&per_page=10

@GET("/api/users")
public Call<UsersApiResponse> getUsers(@Query("per_page") int pageSize, 
					@Query("page") int currentPage);

实际API调用时传递参数值。
 

1.2。具有相同名称的多个查询参数

假设我们想要发送多个具有相同名称的参数，例如userId。这是非常罕见的情况 – 这仍然可以帮助我们遇到这个要求。

https://<DOMAIN>/api/users?userId=1&userId=2&userId=3

在服务器上，它将被收到userId = [1,2,3]。

@GET("/api/users")
public Call<UsersApiResponse> getUsers(@Query("userId") List<Integer> ids);

1.3。编码查询参数

@Query注释采用属性即encoded。它属于boolean类型，无论是真还是假。
它指定带注释的方法参数的参数值是否已经过URL编码。根据它的值，对传递的值执行URL编码。如果值已经过URL编码，则不会进行默认的URL编码。
默认情况下，传递的值将转换为编码字符串。

1.4。可选的查询参数

根据API设计，在上面的示例中，查询参数可能是可选的。如果我们不想通过请求传递参数，我们应该只传递null值。
null在创建请求时，Retrofit会跳过参数并忽略它们。

我们不能传递'null'给原始类型。因此，始终建议使用包装类作为参数类型。

例如，调用service.getUsers(null, null)将导致'https://DOMAIN/api/users'。

2.路径参数

Retrofit 2中的路径参数用@Path注释表示。它们也来自方法参数。它们在URL路径段中被命名为替换。
路径参数可能不是null。
@Path在完整API路径解析之前修改注释中传递的值并对其进行URL编码。

2.1。简单路径参数

在Retrofit 2中使用@Path参数的示例。

@GET("/api/users/{id}")
public Call<UserApiResponse> getUser(@Path("id") Long id);

使用service.getUser（1）调用上面的API会产生'/ api / users / 1'。

2.2。编码路径参数

@Path注释采用属性即encoded。它属于boolean类型，无论是真还是假。
它指定带注释的方法参数的参数值是否已经过URL编码。根据它的值，对传递的值执行URL编码。如果值已经过URL编码，则不会进行默认的URL编码。
默认情况下，传递的路径参数将转换为编码字符串。

2.2.1。encoded = true

@GET("/user/{name}")
Call<ResponseBody> getUserByName(@Path(value="name") String name);
 
//OR - encoded is default 'true'
 
@GET("/user/{name}")
Call<ResponseBody> getUserByName(@Path(value="name", encoded=true) String name);

service.getUserByName("John+Doe")将被解析'/user/John%2BDoe'。
2.2.2。encoded = false

@GET("/user/{name}")
Call<ResponseBody> getUserByName(@Path(value="name", encoded=false) String name);

service.getUserByName("John+Doe")将被解决'/user/John+Doe'。
 

3.结论

在这个Retrofit教程中，我们已经看到了如何使用单个，多个和可选的查询参数。我们还学会了使用路径参数。