Java 獲取 HttpServletRequest Header 完整指南

HTTP Header 攜帶客戶端信息、認證憑證、代理鏈路、緩存控制等關鍵元數據。本文系統講解在 Servlet、Spring MVC、JSP 中獲取 Header 的多種方式，含單值/多值獲取、遍歷所有 Header、常見 Header 含義、偽造風險與防範。

核心 API：HttpServletRequest

// 單值獲取 (取首個)
String userAgent = request.getHeader("User-Agent");
String token = request.getHeader("Authorization");

// 多值獲取 (如多個 Cookie、X-Forwarded-For)
Enumeration headers = request.getHeaders("X-Forwarded-For");
while (headers.hasMoreElements()) {
    System.out.println(headers.nextElement());
}

// 獲取所有 Header 名稱
Enumeration names = request.getHeaderNames();
while (names.hasMoreElements()) {
    String name = names.nextElement();
    String value = request.getHeader(name); // 取首個
    System.out.println(name + ": " + value);
}

Spring MVC 中優雅獲取

方式 1：@RequestHeader 參數綁定

@GetMapping("/api/user")
public UserInfo getUser(
    @RequestHeader("User-Agent") String ua,
    @RequestHeader(value = "X-Request-Id", required = false) String requestId,
    @RequestHeader Map allHeaders // 全量綁定為 Map
) {
    // 自動處理缺失、類型轉換
}

方式 2：注入 HttpServletRequest (不推薦耦合)

@Autowired HttpServletRequest request; // 請求作用域 Bean，線程安全

@GetMapping("/legacy")
public void legacy() {
    String ua = request.getHeader("User-Agent");
}

方式 3：ControllerAdvice 統一提取 (跨域、日誌、認證)

@ControllerAdvice
public class HeaderInterceptor {
    private static final Logger log = LoggerFactory.getLogger(HeaderInterceptor.class);

    @ModelAttribute
    public void extractCommonHeaders(HttpServletRequest request, Model model) {
        String traceId = request.getHeader("X-Trace-Id");
        String userId = request.getHeader("X-User-Id");
        model.addAttribute("traceId", traceId);
        model.addAttribute("userId", userId);
        
        // 結構化日誌
        log.info("Request: {} {} | TraceId: {} | UA: {}", 
            request.getMethod(), request.getRequestURI(), traceId, 
            request.getHeader("User-Agent"));
    }
}

JSP 中獲取 (傳統專案)

<%-- header.jsp --%>
<%
    out.println("User-Agent: " + request.getHeader("User-Agent") + "
");
    out.println("Referer: " + request.getHeader("Referer") + "
");
    out.println("Accept-Language: " + request.getHeader("Accept-Language") + "
");
    out.println("X-Forwarded-For: " + request.getHeader("X-Forwarded-For") + "
");
    
    // 遍歷所有
    Enumeration e = request.getHeaderNames();
    while (e.hasMoreElements()) {
        String name = e.nextElement();
        out.println(name + " = " + request.getHeader(name) + "
");
    }
%>

常見 Header 含義速查表

獲取真實客戶端 IP 最佳實踐

public static String getRealIp(HttpServletRequest request) {
    // 1. 優先從代理 Header 獲取 (Nginx/網關配置透傳)
    String ip = request.getHeader("X-Forwarded-For");
    if (ip != null && !ip.isEmpty() && !"unknown".equalsIgnoreCase(ip)) {
        // 可能多級代理，取第一個非未知 IP
        return ip.split(",")[0].trim();
    }
    
    // 2. 備選 Header
    ip = request.getHeader("X-Real-IP");
    if (ip != null && !ip.isEmpty() && !"unknown".equalsIgnoreCase(ip)) {
        return ip;
    }
    
    // 3. 最後回退到 Servlet API
    return request.getRemoteAddr(); // 可能是代理 IP
}

前提：反向代理 (Nginx/網關) 必須正確設置：

# Nginx 配置
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;

Header 偽造風險與防範

Spring Boot 2.6+ / Servlet 6.0 注意事項

• 默認限制 Header 名稱字符範圍 (RFC 7230 token 規則)，包含特殊字符的 Header 可能被拒絕。
• 可通過 `server.max-http-header-size` 調整最大 Header 大小 (默認 8KB)。
• Tomcat 10+ (Servlet 6) 更嚴格解析 Header 折行，舊客戶端可能不兼容。

總結

1. 優先使用 @RequestHeader 聲明式綁定，類型安全、可選參數、文檖化友好。
2. 需遍歷/動態獲取時注入 HttpServletRequest。
3. 真實 IP 獲取**必須**配合反向代理正確透傳 `X-Forwarded-For`/`X-Real-IP`。
4. 所有來自客戶端的 Header **不可信**，涉及安全決策時需經過網關清洗驗證。
5. 分布式系統務必傳遞 `Trace-Id` 串聯全鏈路日誌。