前言

在 Spring Boot 開發(fā)中，HTTP 請求頭（Header）是客戶端和服務(wù)器之間傳遞元數(shù)據(jù)的重要方式。通過請求頭，客戶端可以傳遞認證信息、內(nèi)容類型、語言偏好等數(shù)據(jù)。Spring Boot 提供了 @RequestHeader 注解，用于方便地從 HTTP 請求頭中提取數(shù)據(jù)。本文將詳細介紹 @RequestHeader 注解的使用方法，包括基本用法、默認值處理、多值頭處理以及實際應(yīng)用場景。

一、注解定義與核心屬性

1.1 @RequestHeader 是什么

在構(gòu)建現(xiàn)代 Web 應(yīng)用或 RESTful API 時，我們經(jīng)常需要從 HTTP 請求中提取元數(shù)據(jù)信息。其中，請求頭（Request Headers） 是傳遞客戶端身份、認證令牌、內(nèi)容類型、語言偏好等關(guān)鍵信息的重要載體。@RequestHeader 是 Spring Framework 提供的一個方法參數(shù)注解，用于將 HTTP 請求頭中的特定字段值自動綁定到控制器方法的參數(shù)上。它屬于 Spring MVC 的數(shù)據(jù)綁定機制的一部分，與 @RequestParam、@PathVariable、@RequestBody 等注解共同構(gòu)成 Spring 對 HTTP 請求的結(jié)構(gòu)化解析能力。

??注意：@RequestHeader 僅在 Spring MVC 的控制器方法（@Controller、@RestController）中有效，在 Service、Util 或普通 Bean 方法中使用將被忽略。

1.2 源碼定義

@RequestHeader 注解的實現(xiàn)基于Spring MVC的參數(shù)綁定機制，它通過 @Target 和 @Retention 注解指定其作用于方法參數(shù)級別，并在運行時通過 Spring 的內(nèi)部機制將請求頭的值注入到相應(yīng)的參數(shù)上。

@Target({ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RequestHeader {
    @AliasFor("name")
    String value() default "";
    @AliasFor("value")
    String name() default "";
    boolean required() default true;
    String defaultValue() default ValueConstants.DEFAULT_NONE;
}

需要注意的是，value() 和 name() 是別名關(guān)系，二者等價，通常使用 value。如果方法參數(shù)的名稱與請求頭名稱相同，那么可以省略 value 元素。然而，需要注意的是，某些請求頭名稱（如User-Agent）并不是有效的Java變量名，因此在這種情況下，我們不能省略value元素。

二、工作原理與請求處理流程

2.1 請求頭處理流程

2.2 核心處理階段

1. 參數(shù)解析器選擇：RequestHeaderMethodArgumentResolver 處理帶有 @RequestHeader 的參數(shù)

2. 請求頭獲取：從 HttpServletRequest 獲取指定請求頭值

3. 類型轉(zhuǎn)換：使用 ConversionService 轉(zhuǎn)換為目標類型

   public class DefaultFormattingConversionService implements ConversionService {
       public <T> T convert(@Nullable Object source, Class<T> targetType) {
           // 查找合適的轉(zhuǎn)換器
           GenericConverter converter = getConverter(sourceType, targetType);
           return (T) converter.convert(source, sourceType, targetType);
       }
   }

4. 默認值處理：當請求頭缺失且存在默認值時應(yīng)用

   @Override
   protected Object resolveArgument(MethodParameter parameter, 
                                   ModelAndViewContainer mavContainer,
                                   NativeWebRequest webRequest, 
                                   WebDataBinderFactory binderFactory) throws Exception {
       Object arg = super.resolveArgument(parameter, mavContainer, webRequest, binderFactory);
       // 處理默認值
       if (arg == null && !ValueConstants.DEFAULT_NONE.equals(namedValueInfo.defaultValue())) {
           arg = resolveDefaultValue(namedValueInfo.defaultValue());
       }
       return arg;
   }

5. 必填校驗：檢查必需請求頭是否存在

三、使用場景與最佳實踐

3.1 基本用法

如果只需要獲取某個特定的請求頭，可以使用 @RequestHeader 注解并指定 Header 名稱。假設(shè)我們需要根據(jù)用戶的 Accept-Language 請求頭來返回不同語言的響應(yīng)，使用 @RequestHeader 可以輕松實現(xiàn)：

@GetMapping("/locale")
public String getProfile(@RequestHeader("Accept-Language") String language) {
  // 根據(jù)locale返回不同語言的響應(yīng)
  return "response in " + language;
}

??注意：如果請求中沒有 accept-language 這個 Header，默認會返回 400 錯誤。

如上這段代碼用于根據(jù)客戶端的 Accept-Language 請求頭返回相應(yīng)語言的響應(yīng)，其功能是根據(jù)客戶端的 HTTP 請求頭 Accept-Language 來返回不同語言的響應(yīng)。使用這種方式代碼簡潔、語義清晰，無需注入 HttpServletRequest，自動完成字符串轉(zhuǎn)換（支持基本類型、枚舉等）。在某些情況下，可能會過度依賴Spring框架的注解，導(dǎo)致代碼難以移植。

3.2 可選參數(shù)與默認值

默認情況下，Header 是必須的。如果請求中沒有該 Header，將拋出異常并返回 400。如果希望在請求頭缺失時不出現(xiàn)異常，可以將 required 設(shè)置為 false，此時需要手動判斷?；蛘咴O(shè)置 Header 默認值，required 會自動設(shè)置為 false，這樣即使請求中沒有該 Header，也會使用默認值，避免 null 判斷。

@PostMapping("/submit")
public ResponseEntity<?> submit(
    @RequestHeader(value = "X-Request-Id", required = false) String requestId,
    @RequestHeader(value = "User-Agent", defaultValue = "unknown") String userAgent) {
  if(traceId == null){
    // 自動生成
    traceId = generateTraceId(); 
  }
    return AppInfo(traceId, userAgent);
}

defaultValue 僅在 required = false 且請求頭缺失時生效，若同時設(shè)置 required = true 和 defaultValue，defaultValue 不會被使用（因為 Spring 認為該頭必須存在）。

3.3 獲取所有 Headers

@RequestHeader 可以獲取單個請求頭的值，也可以獲取所有請求頭，并將其作為 MultiValueMap 或 Map 類型傳遞給方法參數(shù)。如果不確定請求中會包含哪些 Headers，或者不希望方法參數(shù)列表太長，可以使用 @RequestHeader 不指定名稱，直接獲取所有 Headers，可以選擇使用以下幾種類型接收：

• 使用 Map 接收所有請求頭，只獲取每個 Header 的第一個值。

  @GetMapping("/analytics")
  public Map<String, String> analyzeHeaders(@RequestHeader Map<String, String> headers) {
    // headers 包含所有請求頭（key 不區(qū)分大小寫，統(tǒng)一轉(zhuǎn)為小寫。注意：實際保留原始大小寫）
    return headers;
  }

• 使用 MultiValueMap 接收請求頭，可以獲取多個值。

  @RequestMapping("/listHeaders")
  public Map<String, Object> listHeaders(@RequestHeader MultiValueMap<String, String> headers) {
    Map<String, Object> result = new HashMap<>();
    headers.forEach((key, value) -> {
         // 日志中輸出所有請求頭
        System.out.println(String.format("Header '%s' = %s", key, value));
    });
    result.put("code", 0);
    result.put("msg", "success");
    result.put("headers", headers);
    return result;
  }

• 使用 HttpHeaders 接收請求頭，這是Spring提供的一個專門用于處理請求頭的類，它實現(xiàn)了 MultiValueMap<String, String> 接口，主要用于獲取標準 Header。

  @RequestMapping("/getAllHttpHeaders")
  public Map<String, Object> getAllHttpHeaders(@RequestHeader HttpHeaders headers) {
    headers.forEach((key, value) -> {
         // 日志中輸出所有請求頭
        System.out.println(String.format("getAllHttpHeaders '%s' = %s", key, value));
    });
    Map<String, Object> result = new HashMap<>();
    result.put("code", 0);
    result.put("msg", "success");
    result.put("headers", headers);
    return result;
  }

?? 注意：如果指定的 Header 不存在，從 Map、MultiValueMap 或 HttpHeaders 獲取時會返回 null。

3.4 處理多值請求頭

某些請求頭可能包含多個值（如 Accept 頭），可以使用 List<String> 或 MultiValueMap<String, String> 來提取。

import java.util.List;
@GetMapping("/accept-header")
public String getAcceptHeader(@RequestHeader("Accept") List<String> acceptHeaders) {
    return "Accept Headers: " + acceptHeaders.toString();
}

四、最佳實踐總結(jié)

4.1 請求頭使用規(guī)范

4.2 與 HttpServletRequest.getHeader() 的對比

五、總結(jié)

在現(xiàn)代Web應(yīng)用程序中，安全性是一個至關(guān)重要的方面，特別是當我們處理敏感數(shù)據(jù)或執(zhí)行受限操作時。@RequestHeader 注解在這方面發(fā)揮了重要作用，它允許開發(fā)者輕松地從HTTP請求頭中提取信息，例如認證令牌，并據(jù)此進行安全決策。通過這種方式，我們能夠精確控制對受限端點的訪問，僅允許通過身份驗證的用戶訪問敏感數(shù)據(jù)。這不僅增強了應(yīng)用程序的安全性，還提供了一種靈活的方法來處理各種基于請求頭的邏輯。

然而，合理使用這一工具的同時，開發(fā)者也需要關(guān)注安全性的其它方面，比如確保敏感信息的加密存儲、使用HTTPS來保護數(shù)據(jù)傳輸?shù)陌踩?。此外，實現(xiàn)魯棒的身份驗證邏輯和錯誤處理機制也是至關(guān)重要的，以確保應(yīng)用程序能夠妥善處理無效或惡意的請求。

到此這篇關(guān)于Spring注解秘籍之如何優(yōu)雅地使用@RequestHeader的文章就介紹到這了,更多相關(guān)Spring注解@RequestHeader內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！