collections.singletonmap 是构建单键值 http 头或查询参数最轻量、语义最清晰的方式，一行代码生成线程安全不可变映射，兼容 jdk 1.2+，零哈希计算、内存恒定 o(1)，且禁止修改、支持 null 值。
Collections.singletonMap 是 Java 中构建单键值 HTTP 头（Header）或查询参数（Query）最轻量、最语义清晰的方式——无需 new HashMap、不引入第三方依赖，一行代码即可生成线程安全、不可修改的映射结构。
为什么适合 Header 和 Query 场景
HTTP 请求中的 Header 或 Query 参数常只需传一个固定键值对，例如：
• Header："Authorization: Bearer abc123" → singletonMap("Authorization", "Bearer abc123")
• Query：?format=json → singletonMap("format", "json")
这类场景天然满足 singletonMap 的设计前提：元素唯一、无需后续增删、读多写无。
它返回的是内部 SingletonMap 实例，零哈希计算、无扩容逻辑、内存占用恒定 O(1)，比 new HashMap().put(...) 少分配至少两个对象，也比 Map.of("k","v")（Java 9+）更早兼容（支持 JDK 1.2+）。
实际调用示例（适配主流 HTTP 客户端）
多数 Java HTTP 客户端（如 OkHttp、Apache HttpClient、Spring RestTemplate）接受 Map<string string></string> 类型的 Header 或 Query 参数。直接传入 singletonMap 即可：
- OkHttp 添加 Header：
request.newBuilder().headers(Headers.of(Collections.singletonMap("X-Trace-ID", "req-789"))).build() - RestTemplate 设置 Query：
rest.exchange("https://api.com/user?id=1001", HttpMethod.GET, null, String.class, Collections.singletonMap("id", "1001"))（注意：部分封装需配合 UriComponentsBuilder 手动拼接） - Feign 客户端中作为
@RequestLine的 queryMap 参数（需 Feign 支持 Map 解析）
关键注意事项
虽极简，但需留意以下行为边界：
- 返回的 Map 禁止任何修改操作：调用
put()、remove()、clear()或通过keySet().iterator().remove()均抛UnsupportedOperationException - 允许 key 或 value 为
null（如singletonMap("Cookie", null)），但多数 HTTP 客户端会跳过 null 值，建议显式判空或使用空字符串 - 若需多个 Header 或 Query 参数，请改用
Map.of()（Java 9+）、ImmutableMap.of()（Guava）或传统HashMap，不要重复调用 singletonMap 后合并 - 与
Collections.singletonList不同，它返回的是Map接口实例，不能误传给只接受List的 API
对比其他写法的优势
相比常见替代方案，singletonMap 在单参数场景下更干净可靠：
- 比
new HashMap() {{ put("k", "v"); }}（双大括号初始化）避免了匿名内部类带来的内存泄漏风险和额外 class 文件 - 比
Arrays.asList(new AbstractMap.SimpleEntry("k", "v")).stream().collect(Collectors.toMap(...))更直白，无流开销 - 比
Map.of("k", "v")兼容更老 JDK 版本，且明确传达“仅此一项”的语义，而非泛化的不可变 Map
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
