Spring中的@RequestHeader注解使用及说明

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RequestHeader {
    // 指定要绑定的请求头名称
    @AliasFor("name")
    String value() default "";

    @AliasFor("value")
    String name() default "";

    // 是否必须存在，默认为 true
    boolean required() default true;

    // 当请求头不存在时的默认值（仅在 required = false 时生效）
    String defaultValue() default ValueConstants.DEFAULT_NONE;
}

GET /api/user/profile HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Accept-Language: zh-CN
X-Client-Version: 2.1.0

@RestController
@RequestMapping("/api/user")
public class UserController {

    @GetMapping("/profile")
    public UserProfile getProfile(
        @RequestHeader("Authorization") String authHeader,
        @RequestHeader("Accept-Language") String lang,
        @RequestHeader("X-Client-Version") String clientVersion
    ) {
        // authHeader = "Bearer eyJhbGci..."
        // lang = "zh-CN"
        // clientVersion = "2.1.0"
        return userService.getProfile(authHeader, lang);
    }
}

@GetMapping("/info")
public AppInfo getAppInfo(
    @RequestHeader(value = "X-Trace-ID", required = false) String traceId,
    @RequestHeader(value = "User-Agent", defaultValue = "unknown") String userAgent
) {
    if (traceId == null) {
        traceId = generateTraceId(); // 自动生成
    }
    return new AppInfo(traceId, userAgent);
}

@GetMapping("/debug")
public Map<String, String> debugHeaders(@RequestHeader Map<String, String> headers) {
    // headers 包含所有请求头（key 不区分大小写，统一转为小写？注意：实际保留原始大小写）
    return headers;
}

// 或使用 HttpHeaders（推荐，支持多值头）
@GetMapping("/debug2")
public ResponseEntity<?> debugWithHttpHeaders(@RequestHeader HttpHeaders headers) {
    List<String> authList = headers.get("Authorization"); // 支持同名多值
    String contentType = headers.getFirst("Content-Type");
    return ResponseEntity.ok().build();
}

@GetMapping("/config")
public void getConfig(
    @RequestHeader("X-Retry-Count") int retryCount,          // 转为 int
    @RequestHeader("X-Enable-Feature") boolean enableFeature, // 转为 boolean ("true"/"false")
    @RequestHeader("X-Priority") PriorityLevel priority       // 自定义枚举
) {
    // ...
}

// 枚举示例
public enum PriorityLevel {
    LOW, MEDIUM, HIGH;

    // Spring 会调用 valueOf(String) 进行转换
}

@PostMapping("/order")
public Order createOrder(@RequestHeader("Authorization") String authHeader) {
    if (authHeader == null || !authHeader.startsWith("Bearer ")) {
        throw new IllegalArgumentException("Invalid token");
    }
    String token = authHeader.substring(7); // 去掉 "Bearer "
    User user = jwtService.validate(token);
    return orderService.create(user);
}

@GetMapping("/message")
public String getMessage(@RequestHeader("Accept-Language") Locale locale) {
    return messageSource.getMessage("welcome.message", null, locale);
}

@GetMapping("/feature")
public FeatureResponse getFeature(
    @RequestHeader("X-App-Version") String appVersion
) {
    if (VersionUtils.compare(appVersion, "2.0.0") >= 0) {
        return newFeature();
    } else {
        return legacyFeature();
    }
}

@PostMapping("/process")
public void processEvent(@RequestHeader("X-B3-TraceId") String traceId) {
    MDC.put("traceId", traceId); // 写入日志上下文
    eventService.handle();
}

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addFormatters(FormatterRegistry registry) {
        registry.addConverter(new StringToPriorityLevelConverter());
    }
}

// 推荐：与标准头保持一致
@RequestHeader("Authorization")
@RequestHeader("Content-Type")

// 自定义头建议使用 X- 前缀或统一命名规范
@RequestHeader("X-Api-Key")

// ❌ 无效！defaultValue 不会被使用
@RequestHeader(value = "X-Debug", required = true, defaultValue = "false")

// ✅
@RequestHeader(value = "X-Debug", required = false, defaultValue = "false")

// 示例：拦截器中处理
public class AuthInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, ...) {
        String token = request.getHeader("Authorization");
        User user = authService.validate(token);
        RequestContextHolder.setAttribute("currentUser", user);
        return true;
    }
}

public class HeaderConstants {
    public static final String AUTHORIZATION = "Authorization";
    public static final String TRACE_ID = "X-Trace-ID";
}

// 使用
@RequestHeader(HeaderConstants.AUTHORIZATION) String auth

@Slf4j
@RestController
public class ApiController {
    @GetMapping("/data")
    public Data getData(@RequestHeader("X-Request-ID") String requestId) {
        log.info("Processing request [{}]", requestId);
        // ...
    }
}

@PostMapping("/upload")
public UploadResult upload(
    @RequestHeader("Content-Type") String contentType,
    @RequestParam("file") MultipartFile file,
    @PathVariable("userId") Long userId,
    @RequestBody Metadata metadata
) {
    // 组合使用，各司其职
}