在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

spring-projects/spring-framework

菜单

HTTP 抽象和 URI 处理

相关源文件

本文档涵盖 Spring Framework 的 HTTP 消息表示和 URI 构建/解析功能。它包括用于处理 HTTP 标头、请求/响应实体、URI 组件和 URI 模板处理的类。有关 Spring MVC 控制器等特定于 Web 框架的功能，请参阅Spring MVC。有关响应式 Web 客户端功能，请参阅WebFlux 和响应式编程。

HTTP 消息抽象

Spring 为 HTTP 消息提供了全面的抽象，包括标头、实体和状态处理。

HttpHeaders

HttpHeaders 类提供了 HTTP 标头的类型安全表示，以及用于常见标头和操作的便捷方法。

主要功能

  • 不区分大小写的标头名称处理
  • 标准 HTTP 标头的类型安全访问器
  • 支持多值标头
  • 内置的复杂标头值解析，如 Accept、Content-Type
  • 身份验证标头构建器（setBasicAuth、setBearerAuth）

来源： spring-web/src/main/java/org/springframework/http/HttpHeaders.java59-97

HTTP 实体类

Spring 提供了 HttpEntity、RequestEntity 和 ResponseEntity，用于表示完整的 HTTP 消息。

RequestEntity 表示包含方法、URL、标头和主体的出站 HTTP 请求

ResponseEntity 表示包含状态、标头和主体的 HTTP 响应

来源： spring-web/src/main/java/org/springframework/http/ResponseEntity.java34-81 spring-web/src/main/java/org/springframework/http/RequestEntity.java33-68

内容处置

ContentDisposition 类处理文件下载和表单提交中使用的 Content-Disposition 标头。

主要功能

  • Content-Disposition 标头的解析和生成
  • 支持用于国际字符的 RFC 5987 文件名编码
  • 用于构建处置标头的构建器模式
  • 文件名中特殊字符的自动转义

来源： spring-web/src/main/java/org/springframework/http/ContentDisposition.java41-51

URI 处理

Spring 的 URI 处理功能主要围绕 UriComponents 和 UriComponentsBuilder 展开，用于构建、解析和操作 URI。

UriComponentsBuilder

URI 构建和解析操作的主要入口。

解析器类型

  • RFC：严格遵循 RFC 3986 规范，适用于格式良好的 URI
  • WHAT_WG：遵循浏览器 URL 标准的宽松解析

常见使用模式

来源： spring-web/src/main/java/org/springframework/web/util/UriComponentsBuilder.java44-74

URI 模板扩展

URI 模板支持变量替换并进行适当的编码

变量扩展

  • 基于 Map 的：uri.expand(Map.of("id", 123, "type", "user"))
  • 基于数组的：uri.expand("value1", "value2")
  • 部分扩展：变量可以增量扩展

编码策略

  • encode()：先编码模板，然后单独编码变量
  • 模板编码：编码时跳过 URI 变量占位符
  • 组件编码：根据其规则编码每个 URI 组件

来源： spring-web/src/main/java/org/springframework/web/util/HierarchicalUriComponents.java422-438

URI 编码和工具

UriUtils 为不同的 URI 组件提供精细的编码控制

组件特定编码

  • 每个 URI 组件都有不同的允许字符
  • 保留字符在不同组件中处理方式不同
  • 非 ASCII 字符始终进行百分号编码

编码方法

  • encodeUriVariables()：对变量值进行严格编码
  • encode()：组件感知编码
  • 编码操作的自定义字符集支持

来源： spring-web/src/main/java/org/springframework/web/util/UriUtils.java34-55

URI 构建器工厂

DefaultUriBuilderFactory 提供了工厂模式，用于创建具有通用配置的 UriBuilder 实例。

编码模式

  • TEMPLATE_AND_VALUES：预编码模板，严格编码变量
  • VALUES_ONLY：仅编码变量值，不编码模板
  • URI_COMPONENT：扩展后编码最终的 URI 组件
  • NONE：不应用任何编码

配置选项

  • 用于相对路径解析的基础 URI
  • 用于常见替换的默认 URI 变量
  • 解析器类型选择（RFC vs WhatWG）
  • 用于编码的路径解析行为

来源： spring-web/src/main/java/org/springframework/web/util/DefaultUriBuilderFactory.java33-44

URI 解析实现

Spring 支持两种具有不同权衡的 URI 解析算法

RFC 解析器

  • 严格遵循 RFC 3986 语法规则
  • 对格式错误的输入抛出异常
  • 适用于格式良好、通过编程生成的 URI

WhatWG 解析器

  • 遵循浏览器 URL 解析标准
  • 对用户输入的 URL 更加宽松
  • 优雅地处理边缘情况和格式错误的输入

解析器选择

  • 默认：为向后兼容性使用 RFC 解析器
  • 建议将 WhatWG 解析器用于用户输入的 URL
  • 两者都产生等效的 UriComponents 输出

来源： spring-web/src/main/java/org/springframework/web/util/UriComponentsBuilder.java171-217 spring-web/src/main/java/org/springframework/web/util/RfcUriParser.java28-36

集成点

这些 HTTP 和 URI 抽象与 Spring Framework 的其他组件集成

在 Web 框架中的用法

  • RequestEntity/ResponseEntity 作为控制器方法参数和返回类型
  • HttpHeaders 用于过滤器和拦截器中的标头操作
  • UriComponentsBuilder 用于链接生成和重定向

客户端使用

  • RestTemplate 和 WebClient 在内部使用这些抽象
  • UriBuilderFactory 配置用于一致的 URI 处理
  • 通过 Accept 和 Content-Type 标头进行内容协商

来源： spring-web/src/main/java/org/springframework/http/ResponseEntity.java35-80 spring-webflux/src/main/java/org/springframework/web/reactive/function/client/ClientRequest.java35-47