URI raw query 怎样保留原始查询

在 Java 里想保留 URI 的原始查询串，直接读取 getRawQuery()。它返回的是查询组件的原始形式，百分号编码不会被解开；getQuery() 则返回解码后的查询组件，适合读取语义值，不能替代原文。

官方文档：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/net/URI.html

签名、缓存键、代理转发或审计记录需要保留请求原貌时，先保存原始 URI 或 getRawQuery() 的结果，再决定是否另行解析参数。

先从 URI 读取 raw query

下面的查询串同时包含百分号编码、加号、空值和重复键。getRawQuery() 只去掉开头的问号，不会替你把查询内容改写成另一种表示。

import java.net.URI;

public class RawQueryDemo {
    public static void main(String[] args) {
        URI uri = URI.create(
                "https://example.com/search?q=Java%20URI&tag=a+b&empty=&q=second");

        // 原始查询用于签名、缓存键或透传，保留 %20、+、空值和重复键
        String rawQuery = uri.getRawQuery();
        System.out.println(rawQuery);
    }
}

这里得到的原始查询仍包含 q=Java%20URI，不会因为读取动作变成带空格的文本。要把整条 URI 原样交给下游时，优先保留原来的 URI 对象或 uri.toString()，不要先调用解码方法再拼接。

raw query 和 decoded query 不是同一份数据

getQuery() 会解码百分号表示的字节。例如 %20 会还原为空格，而字面量 + 仍然是加号；它不是表单编码器，不应凭经验把加号改成空格。

URI uri = URI.create("https://example.com/search?q=Java%20URI&tag=a+b");

// 读取语义值：百分号转义被解码，适合展示或业务判断
String decodedQuery = uri.getQuery();

// 读取传输形态：百分号转义保持原样，适合签名或透传
String rawQuery = uri.getRawQuery();

System.out.println(decodedQuery); // q=Java URI&tag=a+b
System.out.println(rawQuery);     // q=Java%20URI&tag=a+b

因此两者的选择取决于下游契约：展示和业务筛选通常需要解码后的文本；校验请求是否被改写、计算基于原文的签名，或把查询串转发给另一个服务时，应使用 raw query。不要先用 getQuery() 再尝试“编码回去”，那样可能改变原始写法。

null、空查询和重复参数要分开处理

URI 的字符串组件可能是未定义，也可能定义为空字符串，这两种状态不能合并。没有查询组件时，getRawQuery() 返回 null；如果 URI 明确带有空查询组件，返回值可以是空字符串。重复键也不会被 URI 自动合并。

URI withoutQuery = URI.create("https://example.com/search");
URI emptyQuery = URI.create("https://example.com/search?");
URI repeated = URI.create("https://example.com/search?tag=a&tag=b");

// null 表示没有查询组件，空字符串表示查询组件存在但没有内容
if (withoutQuery.getRawQuery() == null) {
    System.out.println("没有 query");
}
if (emptyQuery.getRawQuery() != null && emptyQuery.getRawQuery().isEmpty()) {
    System.out.println("query 存在但为空");
}

// 重复参数仍是一段原始文本，参数语义交给上层协议决定
System.out.println(repeated.getRawQuery());

如果业务需要把参数转成键值集合，应在明确协议规则后再解析，并决定是否保留顺序、空值和重复键。直接使用 Map 往往会丢掉重复参数；而把空查询和无查询都当成 null，则可能影响缓存键或签名结果。

转发、签名和缓存键怎样选输入

“保留原始查询”通常不是为了打印，而是为了让下游看到与上游一致的字符。可以按下面的边界选择输入：

还要注意片段的边界：# 后面的 fragment 不属于 query，getRawQuery() 不会把它包含进来。如果只需保留查询组件，可以单独保存 raw query；如果要求整条请求目标完全一致，则保存原始 URI 字符串更稳妥。

常见问题

getRawQuery 会包含开头的问号吗？

不会。它返回查询组件本身；是否存在查询组件通过返回值是否为 null 判断，不能用是否以问号开头来判断。

getQuery 会把加号变成空格吗？

不会。它按 URI 的百分号转义规则解码，字面量加号仍是加号。只有在明确采用表单编码规则时，才由相应的表单解析器解释加号。

为什么不能把 raw query 先拆成 Map？

因为 Map 可能丢失参数顺序、空值或重复键。签名、缓存和透传场景应先保留原文，业务解析放在确定协议之后。