// ❌ 错误示范：if-else 硬编码
public boolean verify(String token, String provider) {
    if ("cloudflare".equals(provider)) {
        // Cloudflare 验证逻辑
    } else if ("google".equals(provider)) {
        // Google 验证逻辑
    } else if ("tencent".equals(provider)) {
        // 腾讯云验证逻辑
    }
    // 每新增一个服务商，就要改这里...
}

package com.example.turnstile.common;

import lombok.Data;

/**
 * 统一响应封装
 * <p>
 * 所有接口都返回这个结构，前端可以统一处理：
 * - code: 200 表示成功，其他表示失败
 * - message: 提示信息
 * - data: 业务数据
 */
@Data
public class Result<T> {

    /** 响应码 */
    private Integer code;

    /** 提示信息 */
    private String message;

    /** 业务数据 */
    private T data;

    private Result(Integer code, String message, T data) {
        this.code = code;
        this.message = message;
        this.data = data;
    }

    /**
     * 成功响应（带数据）
     */
    public static <T> Result<T> success(T data) {
        return new Result<>(200, "操作成功", data);
    }

    /**
     * 成功响应（无数据）
     */
    public static <T> Result<T> success() {
        return success(null);
    }

    /**
     * 失败响应
     */
    public static <T> Result<T> fail(String message) {
        return new Result<>(500, message, null);
    }

    /**
     * 失败响应（自定义错误码）
     */
    public static <T> Result<T> fail(Integer code, String message) {
        return new Result<>(code, message, null);
    }
}

package com.example.turnstile.common.exception;

import lombok.Getter;

/**
 * 业务异常
 * <p>
 * 用于业务逻辑中的主动异常抛出，会被全局异常处理器捕获
 */
@Getter
public class BizException extends RuntimeException {

    /** 错误码 */
    private final Integer code;

    public BizException(String message) {
        super(message);
        this.code = 500;
    }

    public BizException(Integer code, String message) {
        super(message);
        this.code = code;
    }
}

package com.example.turnstile.common.exception;

import com.example.turnstile.common.Result;
import lombok.extern.slf4j.Slf4j;
import org.springframework.validation.BindException;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

/**
 * 全局异常处理器
 * <p>
 * 捕获所有异常并转换为统一的 Result 格式返回
 */
@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {

    /**
     * 处理业务异常
     */
    @ExceptionHandler(BizException.class)
    public Result<?> handleBizException(BizException e) {
        log.warn("业务异常: code={}, message={}", e.getCode(), e.getMessage());
        return Result.fail(e.getCode(), e.getMessage());
    }

    /**
     * 处理参数校验异常（@RequestBody）
     */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<?> handleValidException(MethodArgumentNotValidException e) {
        String message = e.getBindingResult().getFieldError() != null
                ? e.getBindingResult().getFieldError().getDefaultMessage()
                : "参数校验失败";
        log.warn("参数校验失败: {}", message);
        return Result.fail(400, message);
    }

    /**
     * 处理参数绑定异常
     */
    @ExceptionHandler(BindException.class)
    public Result<?> handleBindException(BindException e) {
        String message = e.getBindingResult().getFieldError() != null
                ? e.getBindingResult().getFieldError().getDefaultMessage()
                : "参数绑定失败";
        log.warn("参数绑定失败: {}", message);
        return Result.fail(400, message);
    }

    /**
     * 处理其他未知异常
     */
    @ExceptionHandler(Exception.class)
    public Result<?> handleException(Exception e) {
        log.error("系统异常", e);
        return Result.fail("系统异常，请稍后重试");
    }
}

package com.example.turnstile.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
import org.springframework.web.filter.CorsFilter;

/**
 * 跨域配置
 * <p>
 * 允许前端开发服务器（localhost:5173）访问后端接口
 */
@Configuration
public class CorsConfig {

    @Bean
    public CorsFilter corsFilter() {
        CorsConfiguration config = new CorsConfiguration();

        // 允许的前端地址
        config.addAllowedOrigin("http://localhost:5173");

        // 允许携带 Cookie
        config.setAllowCredentials(true);

        // 允许所有请求方法（GET、POST 等）
        config.addAllowedMethod("*");

        // 允许所有请求头
        config.addAllowedHeader("*");

        // 预检请求缓存时间（秒）
        config.setMaxAge(3600L);

        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", config);

        return new CorsFilter(source);
    }
}

package com.example.turnstile.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

/**
 * 验证码配置属性
 * <p>
 * 映射 application.yml 中 captcha 开头的配置项
 */
@Data
@Component
@ConfigurationProperties(prefix = "captcha")
public class CaptchaProperties {

    /**
     * 当前使用的服务商标识
     * 可选值：cloudflare / google
     */
    private String provider = "cloudflare";

    /**
     * Cloudflare Turnstile 配置
     */
    private CloudflareConfig cloudflare = new CloudflareConfig();

    /**
     * Google reCAPTCHA v3 配置
     */
    private GoogleConfig google = new GoogleConfig();

    /**
     * Cloudflare 配置项
     */
    @Data
    public static class CloudflareConfig {
        /** 前端 Site Key */
        private String siteKey;
        /** 后端 Secret Key */
        private String secretKey;
        /** 验证接口地址 */
        private String verifyUrl = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
    }

    /**
     * Google 配置项
     */
    @Data
    public static class GoogleConfig {
        /** 前端 Site Key */
        private String siteKey;
        /** 后端 Secret Key */
        private String secretKey;
        /** 验证接口地址 */
        private String verifyUrl = "https://www.google.com/recaptcha/api/siteverify";
        /** 评分阈值（0.0 - 1.0） */
        private Double scoreThreshold = 0.5;
    }
}

package com.example.turnstile.service.captcha;

/**
 * 验证码验证策略接口
 * <p>
 * 所有验证服务商（Cloudflare、Google 等）都需要实现此接口。
 * 这是策略模式的核心：定义统一契约，具体实现各自封装。
 */
public interface CaptchaVerifier {

    /**
     * 获取服务商标识
     * <p>
     * 用于策略工厂根据配置选择对应的实现类。
     * 返回值必须与 application.yml 中的 captcha.provider 值匹配。
     *
     * @return 服务商标识，如 "cloudflare"、"google"
     */
    String getProvider();

    /**
     * 获取前端 Site Key
     * <p>
     * 前端加载验证码组件时需要此参数。
     * 将此方法放在接口中，Controller 无需关心当前是哪个服务商。
     *
     * @return Site Key
     */
    String getSiteKey();

    /**
     * 验证 Token
     *
     * @param token    前端传来的验证 Token
     * @param remoteIp 用户真实 IP 地址（可选，但推荐传递以提高准确性）
     * @return true 表示验证通过，false 表示验证失败
     */
    boolean verify(String token, String remoteIp);
}

package com.example.turnstile.service.captcha.impl;

import cn.hutool.core.util.StrUtil;
import cn.hutool.http.HttpUtil;
import cn.hutool.json.JSONObject;
import cn.hutool.json.JSONUtil;
import com.example.turnstile.config.CaptchaProperties;
import com.example.turnstile.service.captcha.CaptchaVerifier;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

import java.util.HashMap;
import java.util.Map;

/**
 * Cloudflare Turnstile 验证实现
 * <p>
 * 调用 Cloudflare siteverify 接口验证前端传来的 Token。
 * 验证逻辑简单：只需检查响应中的 success 字段。
 */
@Slf4j
@Service
@RequiredArgsConstructor
public class CloudflareCaptchaVerifier implements CaptchaVerifier {

    private final CaptchaProperties properties;

    @Override
    public String getProvider() {
        return "cloudflare";
    }

    @Override
    public String getSiteKey() {
        return properties.getCloudflare().getSiteKey();
    }

    @Override
    public boolean verify(String token, String remoteIp) {
        CaptchaProperties.CloudflareConfig config = properties.getCloudflare();

        // 构建请求参数
        Map<String, Object> params = new HashMap<>();
        params.put("secret", config.getSecretKey());
        params.put("response", token);
        if (StrUtil.isNotBlank(remoteIp)) {
            params.put("remoteip", remoteIp);
        }

        try {
            // 发送请求并解析响应
            String body = HttpUtil.post(config.getVerifyUrl(), params, 5000);
            JSONObject result = JSONUtil.parseObj(body);
            boolean success = result.getBool("success", false);

            if (success) {
                log.info("Cloudflare 验证通过, hostname={}", result.getStr("hostname"));
            } else {
                log.warn("Cloudflare 验证失败, error-codes={}", result.getJSONArray("error-codes"));
            }

            return success;

        } catch (Exception e) {
            log.error("Cloudflare 验证异常", e);
            return false;
        }
    }
}

package com.example.turnstile.service.captcha.impl;

import cn.hutool.core.util.StrUtil;
import cn.hutool.http.HttpUtil;
import cn.hutool.json.JSONObject;
import cn.hutool.json.JSONUtil;
import com.example.turnstile.config.CaptchaProperties;
import com.example.turnstile.service.captcha.CaptchaVerifier;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

import java.util.HashMap;
import java.util.Map;

/**
 * Google reCAPTCHA v3 验证实现
 * <p>
 * 与 Cloudflare 的核心差异：
 * 1. 不仅要检查 success 字段
 * 2. 还要检查 score 评分是否达到阈值
 * <p>
 * score 范围是 0.0（机器人）到 1.0（人类），通常阈值设为 0.5
 */
@Slf4j
@Service
@RequiredArgsConstructor
public class GoogleCaptchaVerifier implements CaptchaVerifier {

    private final CaptchaProperties properties;

    @Override
    public String getProvider() {
        return "google";
    }

    @Override
    public String getSiteKey() {
        return properties.getGoogle().getSiteKey();
    }

    @Override
    public boolean verify(String token, String remoteIp) {
        CaptchaProperties.GoogleConfig config = properties.getGoogle();

        // 构建请求参数
        Map<String, Object> params = new HashMap<>();
        params.put("secret", config.getSecretKey());
        params.put("response", token);
        if (StrUtil.isNotBlank(remoteIp)) {
            params.put("remoteip", remoteIp);
        }

        try {
            // 发送请求并解析响应
            String body = HttpUtil.post(config.getVerifyUrl(), params, 5000);
            JSONObject result = JSONUtil.parseObj(body);

            boolean success = result.getBool("success", false);
            Double score = result.getDouble("score");

            // Google v3 的核心逻辑：success 且 score 达到阈值
            if (success && score != null && score >= config.getScoreThreshold()) {
                log.info("Google reCAPTCHA 验证通过, score={}, action={}", score, result.getStr("action"));
                return true;
            }

            log.warn("Google reCAPTCHA 验证失败, success={}, score={}, threshold={}",
                    success, score, config.getScoreThreshold());
            return false;

        } catch (Exception e) {
            log.error("Google reCAPTCHA 验证异常", e);
            return false;
        }
    }
}

package com.example.turnstile.service.captcha;

import com.example.turnstile.common.exception.BizException;
import com.example.turnstile.config.CaptchaProperties;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;

import java.util.List;
import java.util.Map;
import java.util.function.Function;
import java.util.stream.Collectors;

/**
 * 验证策略工厂
 * <p>
 * 核心职责：根据配置文件中的 provider 值，返回对应的验证器实现。
 * <p>
 * 实现原理：
 * 1. Spring 自动注入所有 CaptchaVerifier 实现类
 * 2. 构造时将它们按 provider 标识存入 Map
 * 3. 调用时根据配置从 Map 中取出对应实现
 */
@Slf4j
@Component
public class CaptchaVerifierFactory {

    private final Map<String, CaptchaVerifier> verifierMap;
    private final CaptchaProperties properties;

    public CaptchaVerifierFactory(List<CaptchaVerifier> verifiers, CaptchaProperties properties) {
        this.properties = properties;
        this.verifierMap = verifiers.stream()
                .collect(Collectors.toMap(CaptchaVerifier::getProvider, Function.identity()));

        log.info("验证策略工厂初始化完成, 已加载服务商: {}", verifierMap.keySet());
    }

    /**
     * 获取当前配置的验证器
     */
    public CaptchaVerifier getVerifier() {
        String provider = properties.getProvider();
        CaptchaVerifier verifier = verifierMap.get(provider);

        if (verifier == null) {
            log.error("未找到验证服务商: {}, 可用: {}", provider, verifierMap.keySet());
            throw new BizException("未知的验证服务商: " + provider);
        }

        return verifier;
    }
}

package com.example.turnstile.model.dto;

import jakarta.validation.constraints.NotBlank;
import lombok.Data;

/**
 * 登录请求 DTO
 */
@Data
public class LoginRequest {

    @NotBlank(message = "用户名不能为空")
    private String username;

    @NotBlank(message = "密码不能为空")
    private String password;

    @NotBlank(message = "验证码 Token 不能为空")
    private String captchaToken;
}

package com.example.turnstile.controller;

import cn.hutool.core.map.MapUtil;
import cn.hutool.extra.servlet.JakartaServletUtil;
import com.example.turnstile.common.Result;
import com.example.turnstile.common.exception.BizException;
import com.example.turnstile.model.dto.LoginRequest;
import com.example.turnstile.service.captcha.CaptchaVerifier;
import com.example.turnstile.service.captcha.CaptchaVerifierFactory;
import jakarta.servlet.http.HttpServletRequest;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

/**
 * 认证接口
 */
@Slf4j
@RestController
@RequestMapping("/auth")
@RequiredArgsConstructor
public class AuthController {

    private final CaptchaVerifierFactory verifierFactory;

    /**
     * 获取验证码配置
     * <p>
     * 前端需要调用此接口获取 Site Key，用于加载验证码组件。
     * 通过策略工厂获取，Controller 无需关心当前是哪个服务商。
     */
    @GetMapping("/captcha/config")
    public Result<Map<String, String>> getCaptchaConfig() {
        CaptchaVerifier verifier = verifierFactory.getVerifier();

        Map<String, String> config = MapUtil.builder("provider", verifier.getProvider())
                .put("siteKey", verifier.getSiteKey())
                .build();

        log.debug("返回验证码配置: provider={}", verifier.getProvider());
        return Result.success(config);
    }

    /**
     * 登录接口
     */
    @PostMapping("/login")
    public Result<String> login(@Validated @RequestBody LoginRequest request,
                                HttpServletRequest httpRequest) {
        // 1. 获取客户端真实 IP（Hutool 自动处理代理头）
        String remoteIp = JakartaServletUtil.getClientIP(httpRequest);
        log.info("收到登录请求, 用户: {}, IP: {}", request.getUsername(), remoteIp);

        // 2. 验证码校验
        CaptchaVerifier verifier = verifierFactory.getVerifier();
        boolean verified = verifier.verify(request.getCaptchaToken(), remoteIp);

        if (!verified) {
            log.warn("人机验证失败, 用户: {}", request.getUsername());
            throw new BizException(4001, "人机验证失败，请重试");
        }

        // 3. 执行登录逻辑
        // TODO: 实际项目中应该校验用户名密码、生成 JWT Token 等
        log.info("用户 {} 登录成功", request.getUsername());

        return Result.success("登录成功");
    }
}

config.addAllowedOrigin("https://your-production-domain.com");