前言

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

一、注解定義與核心屬性

1.1 @RequestHeader 是什么

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

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

1.2 源碼定義

@RequestHeader 注解的實(shí)現(xiàn)基于Spring MVC的參數(shù)綁定機(jī)制，它通過(guò) @Target 和 @Retention 注解指定其作用于方法參數(shù)級(jí)別，并在運(yùn)行時(shí)通過(guò) Spring 的內(nèi)部機(jī)制將請(qǐng)求頭的值注入到相應(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)系，二者等價(jià)，通常使用 value。如果方法參數(shù)的名稱與請(qǐng)求頭名稱相同，那么可以省略 value 元素。然而，需要注意的是，某些請(qǐng)求頭名稱（如User-Agent）并不是有效的Java變量名，因此在這種情況下，我們不能省略value元素。

二、工作原理與請(qǐng)求處理流程

2.1 請(qǐng)求頭處理流程

2.2 核心處理階段

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

2. 請(qǐng)求頭獲取：從 HttpServletRequest 獲取指定請(qǐng)求頭值

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

   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. 默認(rèn)值處理：當(dāng)請(qǐng)求頭缺失且存在默認(rèn)值時(shí)應(yīng)用

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

5. 必填校驗(yàn)：檢查必需請(qǐng)求頭是否存在

三、使用場(chǎng)景與最佳實(shí)踐

3.1 基本用法

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

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

??注意：如果請(qǐng)求中沒(méi)有 accept-language 這個(gè) Header，默認(rèn)會(huì)返回 400 錯(cuò)誤。

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

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

默認(rèn)情況下，Header 是必須的。如果請(qǐng)求中沒(méi)有該 Header，將拋出異常并返回 400。如果希望在請(qǐng)求頭缺失時(shí)不出現(xiàn)異常，可以將 required 設(shè)置為 false，此時(shí)需要手動(dòng)判斷?；蛘咴O(shè)置 Header 默認(rèn)值，required 會(huì)自動(dòng)設(shè)置為 false，這樣即使請(qǐng)求中沒(méi)有該 Header，也會(huì)使用默認(rèn)值，避免 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){
    // 自動(dòng)生成
    traceId = generateTraceId(); 
  }
    return AppInfo(traceId, userAgent);
}

defaultValue 僅在 required = false 且請(qǐng)求頭缺失時(shí)生效，若同時(shí)設(shè)置 required = true 和 defaultValue，defaultValue 不會(huì)被使用（因?yàn)?Spring 認(rèn)為該頭必須存在）。

3.3 獲取所有 Headers

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

• 使用 Map 接收所有請(qǐng)求頭，只獲取每個(gè) Header 的第一個(gè)值。

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

• 使用 MultiValueMap 接收請(qǐng)求頭，可以獲取多個(gè)值。

  @RequestMapping("/listHeaders")
  public Map<String, Object> listHeaders(@RequestHeader MultiValueMap<String, String> headers) {
    Map<String, Object> result = new HashMap<>();
    headers.forEach((key, value) -> {
         // 日志中輸出所有請(qǐng)求頭
        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 接收請(qǐng)求頭，這是Spring提供的一個(gè)專門用于處理請(qǐng)求頭的類，它實(shí)現(xiàn)了 MultiValueMap<String, String> 接口，主要用于獲取標(biāo)準(zhǔn) Header。

  @RequestMapping("/getAllHttpHeaders")
  public Map<String, Object> getAllHttpHeaders(@RequestHeader HttpHeaders headers) {
    headers.forEach((key, value) -> {
         // 日志中輸出所有請(qǐng)求頭
        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 獲取時(shí)會(huì)返回 null。

3.4 處理多值請(qǐng)求頭

某些請(qǐng)求頭可能包含多個(gè)值（如 Accept 頭），可以使用 List<String> 或 MultiValueMap<String, String> 來(lái)提取。

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

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

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

4.2 與 HttpServletRequest.getHeader() 的對(duì)比

五、總結(jié)

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

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

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