@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RequestHeader {
    // 指定要綁定的請(qǐng)求頭名稱
    @AliasFor("name")
    String value() default "";

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

    // 是否必須存在，默認(rèn)為 true
    boolean required() default true;

    // 當(dāng)請(qǐng)求頭不存在時(shí)的默認(rèn)值（僅在 required = false 時(shí)生效）
    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(); // 自動(dòng)生成
    }
    return new AppInfo(traceId, userAgent);
}

@GetMapping("/debug")
public Map<String, String> debugHeaders(@RequestHeader Map<String, String> headers) {
    // headers 包含所有請(qǐng)求頭（key 不區(qū)分大小寫(xiě)，統(tǒng)一轉(zhuǎn)為小寫(xiě)？注意：實(shí)際保留原始大小寫(xiě)）
    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,          // 轉(zhuǎn)為 int
    @RequestHeader("X-Enable-Feature") boolean enableFeature, // 轉(zhuǎn)為 boolean ("true"/"false")
    @RequestHeader("X-Priority") PriorityLevel priority       // 自定義枚舉
) {
    // ...
}

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

    // Spring 會(huì)調(diào)用 valueOf(String) 進(jìn)行轉(zhuǎn)換
}

@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); // 寫(xiě)入日志上下文
    eventService.handle();
}

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

// 推薦：與標(biāo)準(zhǔn)頭保持一致
@RequestHeader("Authorization")
@RequestHeader("Content-Type")

// 自定義頭建議使用 X- 前綴或統(tǒng)一命名規(guī)范
@RequestHeader("X-Api-Key")

// ? 無(wú)效！defaultValue 不會(huì)被使用
@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
) {
    // 組合使用，各司其職
}