Retrofit GET请求含特殊字符的查询参数调用方法咨询

问题根源 #

你遇到的报错是因为**错误地将查询参数（URL中?后的参数）当作了路径参数（URL路径里的占位符）**使用。Retrofit的@Path注解对参数名有严格规则，只允许字母开头，后跟字母、数字、下划线或连字符，显然metadata.tags.sys.id不符合这个要求。

正确解决方案 #

你的参数metadata.tags.sys.id[in]属于查询参数，应该用以下方式处理：

1. 单个参数直接用@Query

把完整的参数名作为@Query的value传入，变量名可以用合法的名称代替：

@GET("your/api/resource/path")
Call<YourResponseBody> fetchResources(
    // 括号内是真实的参数名，变量名可以自定义
    @Query("metadata.tags.sys.id[in]") String targetTagId
);

调用时直接传入参数值即可，Retrofit会自动处理特殊字符的URL编码。

2. 多个特殊参数用@QueryMap

如果有多个带特殊字符的查询参数，用Map来统一管理更高效：

@GET("your/api/resource/path")
Call<YourResponseBody> fetchResources(
    @QueryMap Map<String, String> queryParams
);

调用时构建参数Map：

Map<String, String> params = new HashMap<>();
params.put("metadata.tags.sys.id[in]", "your_target_id");
// 可添加其他参数
params.put("another.param[like]", "value");

yourApiService.fetchResources(params);

特殊情况：如果是路径中的特殊部分

如果这个带点的字段确实是URL路径的一部分（比如/api/{metadata.tags.sys.id}/data），Retrofit的@Path不支持这种命名，此时可以用@Url动态拼接完整URL：

@GET
Call<YourResponseBody> fetchResources(@Url String fullEncodedUrl);

需要自己提前拼接好包含特殊路径的URL，并确保完成正确的URL编码。

内容的提问来源于stack exchange，提问作者Bhoomika Brahmbhatt