Cloudflare Turnstile 在 Java 后端的人机验证实践

用户完成验证后，Turnstile 会自动注入隐藏字段 cf-turnstile-response，这就是传给后端的 Token。

三、Spring Boot 后端验证

1. 依赖准备

确保项目包含 Web 和 Jackson 依赖。

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
  </dependency>
</dependencies>

2. 控制器逻辑

这里使用 JDK 自带的 HttpClient 发起请求，避免额外依赖。

package com.example.demo;

import org.springframework.web.bind.annotation.*;
import org.springframework.stereotype.Controller;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.Map;
import com.fasterxml.jackson.databind.ObjectMapper;

@Controller
public class TurnstileController {
    private static final String VERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
    private final HttpClient httpClient = HttpClient.newHttpClient();
    private final ObjectMapper json = new ObjectMapper();

    @PostMapping("/verify")
    @ResponseBody
    public String verifyForm(
        @RequestParam String name,
        @RequestParam("cf-turnstile-response") String token,
        @RequestHeader(value = "X-Forwarded-For", required = false) String ip) throws Exception {

        // 从环境变量读取 secret，生产环境务必如此
        String secret = System.getenv("TURNSTILE_SECRET");
        if (secret == null || secret.isEmpty()) {
            return "❌ 未配置环境变量 TURNSTILE_SECRET";
        }

        // 构造请求体
        String body = "secret=" + URLEncoder.encode(secret, StandardCharsets.UTF_8)
                    + "&response=" + URLEncoder.encode(token, StandardCharsets.UTF_8);
        if (ip != null) {
            body += "&remoteip=" + URLEncoder.encode(ip, StandardCharsets.UTF_8);
        }

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(VERIFY_URL))
                .timeout(Duration.ofSeconds(10))
                .header("Content-Type", "application/x-www-form-urlencoded")
                .POST(HttpRequest.BodyPublishers.ofString(body))
                .build();

        HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
        Map<String, Object> result = json.readValue(response.body(), Map.class);
        boolean success = Boolean.TRUE.equals(result.get("success"));

        if (success) {
            return "✅ 验证成功！你好，" + name + "。";
        } else {
            return "❌ 验证失败：" + result;
        }
    }
}

四、运行与测试

启动项目前，设置环境变量以注入 Secret Key。

Linux/Mac:

export TURNSTILE_SECRET="你的_secret_key"
mvn spring-boot:run

Windows:

set TURNSTILE_SECRET=你的_secret_key
mvn spring-boot:run

访问 http://localhost:8080/ 填写表单并提交。若验证通过，将看到成功提示。

五、安全最佳实践

1. 密钥管理：Secret Key 必须放在环境变量或密钥管理系统中，严禁硬编码。
2. Token 时效：Turnstile Token 有效期仅 5 分钟，且只能使用一次。
3. HTTPS：生产环境务必启用 HTTPS，防止中间人攻击窃取 Token。
4. 日志记录：对验证失败的错误码（如 invalid-input-secret）进行记录以便排查。

六、总结

Cloudflare Turnstile 无需用户手动点选，体验流畅且保护隐私。对于 Java 开发者而言，结合 Spring Boot 快速集成，既能提升表单安全性，又不会牺牲用户体验。

参考文档：

• Cloudflare Turnstile 官方文档
• Server-side Validation API