Signal-CLI HTTP服务中查询字符串解析问题的分析与修复

问题背景

在Signal-CLI项目的HTTP服务实现中，处理事件端点时存在一个关键的查询字符串解析问题。当用户通过HTTP接口发送包含电话号码参数的请求时，系统无法正确识别以"+"开头的电话号码账号。

技术细节

问题的核心在于Java的URI.getQuery()方法和自定义的URL解码处理之间的冲突。具体表现为：

1. 当用户发送类似?account=[phone]或?account=%2B335544777的查询参数时
2. URI.getQuery()方法会返回解码后的查询字符串
3. 随后自定义的getQueryMap方法再次对已经解码的字符串进行URL解码
4. 导致加号("+")被错误地转换为空格

问题影响

这个缺陷导致所有以国际电话号码格式(以"+"开头)发送的账号参数都无法被正确识别，因为：

• 原始参数中的"+"或编码后的"%2B"
• 经过双重解码后变成了空格字符
• 最终账号变成了以空格开头的无效格式

解决方案

修复方案非常简单但有效：使用URI.getRawQuery()替代URI.getQuery()。这是因为：

• getRawQuery()返回未解码的原始查询字符串
• 确保后续的自定义解码只执行一次
• 保持编码字符(%2B)的完整性直到最终解码

技术验证

开发者提供了一个简洁的Java示例程序来验证这个问题：

import java.net.URI;
import java.net.URLDecoder;
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.Map;

public class ServerSimulation {
    public static void main(String[] args) {
        String uriString = "http://localhost:8080/resource?account=%2B3434523423";
        URI uri = URI.create(uriString);
        
        String queryString = uri.getQuery();
        Map<String, String> query = queryString == null ? Map.of() : getQueryMap(queryString);
        
        System.out.println("Query Parameters:");
        query.forEach((key, value) -> System.out.println(key + " = " + value));
    }
    
    public static Map<String, String> getQueryMap(String query) {
        // 解码实现...
    }
}

这个示例清晰地展示了双重解码导致的问题，以及为什么使用getRawQuery()是更合适的选择。

总结

这个案例展示了在Web开发中处理URL编码时常见的陷阱。关键教训包括：

1. 理解不同层级解码的相互作用
2. 明确每个解码步骤的职责边界
3. 在需要精确控制解码过程时，优先使用原始(raw)数据
4. 对于敏感数据(如电话号码)，需要特别注意特殊字符的处理

Signal-CLI团队迅速响应并修复了这个问题，确保了国际电话号码在HTTP接口中的正确处理能力。