Java 实现 Claude API 请求签名与安全校验

Java 实现 Claude API 请求签名与安全校验一、为什么 Java 接入 Claude API 需要关注签名安全搜索Java调用Claude API你会发现现有教程要么是 Python 示例要么只有安装说明真正能跑起来的 Java 实现几乎找不到。更头疼的是大多数教程完全跳过了签名与安全校验这一环直接把 API Key 硬编码进代码——这在生产环境里是绝对不能接受的做法。在正式开始之前有必要先把两种完全不同的签名场景说清楚免得后面混淆主动调用签名你的 Java 服务作为客户端向 Anthropic API 发送请求时在 HTTP Header 中携带 API Key 完成身份认证。Webhook 被动验签Anthropic 向你的服务器推送事件时你需要校验请求头里的anthropic-signature确认请求确实来自 Anthropic从而防止伪造和重放攻击。两者的安全逻辑截然不同本文会分别处理。另外Java 开发者接入 Claude 主要有两条路直连 Anthropic API适合大多数场景和通过 AWS Bedrock适合已在 AWS 生态、有合规要求的企业。这两条路本文都会覆盖。二、Anthropic API 鉴权机制详解Anthropic API 采用基于 HTTP Header 的静态 API Key 鉴权而不是 OAuth 动态 Token。每次请求都必须带上以下三个核心 HeaderHeader 名称必填说明x-api-key是你的 API Key格式为sk-ant-...anthropic-version是API 版本号目前应使用2023-06-01Content-Type是固定为application/json关于x-api-key和Authorization: Bearer的区别Anthropic 官方用的是x-api-key这个自定义 Header而不是标准的 Bearer 格式。部分第三方兼容代理比如 ClaudeAPI 这类兼容接入平台可能两种都支持具体以其官网文档为准。但直连 Anthropic 官方端点时必须用x-api-key。anthropic-version这个 Header 也不能省略。它告诉服务端用哪个版本的接口规范来解析请求传错或漏传会直接触发400错误。三、Java 直连 Claude API 实现3.1 依赖配置Maven官方 SDKdependency groupIdcom.anthropic/groupId artifactIdanthropic-java/artifactId version0.8.0/version !-- 请以 Maven Central 最新版本为准 -- /dependencyGradleimplementation com.anthropic:anthropic-java:0.8.0版本号请以 Maven Central 最新发布为准不要照搬本文中的版本号。3.2 方案一官方 anthropic-java SDK推荐import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.MessageCreateParams; import com.anthropic.models.Message; public class ClaudeApiExample { public static void main(String[] args) { // 从环境变量读取 API Key禁止硬编码 String apiKey System.getenv(ANTHROPIC_API_KEY); if (apiKey null || apiKey.isBlank()) { throw new IllegalStateException(ANTHROPIC_API_KEY 环境变量未设置); } AnthropicClient client AnthropicOkHttpClient.builder() .apiKey(apiKey) .build(); MessageCreateParams params MessageCreateParams.builder() .model(claude-opus-4-5) // 模型 ID 请以官方文档为准 .maxTokens(1024L) .addUserMessage(请用简洁的语言解释什么是 HMAC-SHA256。) .build(); Message message client.messages().create(params); System.out.println(message.content().get(0)); } }用官方 SDK 的好处是x-api-key、anthropic-version、Content-Type这些 Header 都会自动注入完全不需要手动构造。3.3 方案二Java 11 HttpClient 手动构造请求如果不想引入第三方 SDK或者需要精细控制 HTTP 请求可以直接用 Java 11 原生的 HttpClientimport java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.time.Duration; public class ClaudeHttpClientExample { private static final String API_URL https://api.anthropic.com/v1/messages; private static final String ANTHROPIC_VERSION 2023-06-01; public static void main(String[] args) throws Exception { String apiKey System.getenv(ANTHROPIC_API_KEY); String requestBody { model: claude-opus-4-5, max_tokens: 1024, messages: [ {role: user, content: 你好请介绍一下你自己。} ] } ; HttpClient httpClient HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .build(); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(API_URL)) .header(x-api-key, apiKey) .header(anthropic-version, ANTHROPIC_VERSION) .header(Content-Type, application/json) .POST(HttpRequest.BodyPublishers.ofString(requestBody)) .timeout(Duration.ofSeconds(60)) // 读取超时建议 30-60 秒 .build(); HttpResponseString response httpClient.send( request, HttpResponse.BodyHandlers.ofString()); System.out.println(状态码: response.statusCode()); System.out.println(响应体: response.body()); } }3.4 方案三Spring Boot WebClientimport org.springframework.web.reactive.function.client.WebClient; import reactor.core.publisher.Mono; Service public class ClaudeService { private final WebClient webClient; public ClaudeService(Value(${anthropic.api-key}) String apiKey) { this.webClient WebClient.builder() .baseUrl(https://api.anthropic.com) .defaultHeader(x-api-key, apiKey) .defaultHeader(anthropic-version, 2023-06-01) .defaultHeader(Content-Type, application/json) .build(); } public MonoString sendMessage(String userMessage) { String body String.format( {model:claude-opus-4-5,max_tokens:1024, messages:[{role:user,content:%s}]} , userMessage); return webClient.post() .uri(/v1/messages) .bodyValue(body) .retrieve() .onStatus(status - status.is4xxClientError() || status.is5xxServerError(), resp - resp.bodyToMono(String.class) .map(err - new RuntimeException(API 错误: err))) .bodyToMono(String.class); } }application.yml中这样配置Key 绝对不要写进代码里anthropic: api-key: ${ANTHROPIC_API_KEY} # 从环境变量注入四、API Key 安全存储与管理硬编码 API Key 是最常见的安全漏洞代码一旦提交到 Git 仓库密钥就等于公开了。按安全级别这里推荐三种方案Level 1环境变量基础export ANTHROPIC_API_KEYsk-ant-your-key-hereJava 中读取System.getenv(ANTHROPIC_API_KEY)Level 2Spring Boot 外部配置推荐通过Value(${anthropic.api-key})注入配合.env文件或容器环境变量使用明文 Key 不会出现在代码仓库里。Level 3企业级密钥管理生产推荐// AWS Secrets Manager 示例 SecretsManagerClient client SecretsManagerClient.builder() .region(Region.AP_NORTHEAST_1) .build(); GetSecretValueResponse response client.getSecretValue( GetSecretValueRequest.builder() .secretId(prod/claude/api-key) .build()); String apiKey response.secretString();HashiCorp Vault 的思路类似通过 Vault Java Driver 在应用启动时动态拉取再配合密钥轮换策略避免长期使用同一把 Key。五、Webhook 签名校验实现这部分是很多教程完全缺失的内容也是生产环境里最容易出安全漏洞的地方值得认真对待。5.1 anthropic-signature Header 格式Anthropic 推送 Webhook 时请求头里会附带anthropic-signature: t1700000000,v1abc123def456...其中t是 Unix 时间戳秒v1是 HMAC-SHA256 签名的十六进制字符串。5.2 HMAC-SHA256 验签 Java 实现import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; import java.security.MessageDigest; import java.util.HexFormat; public class WebhookVerifier { private static final long TOLERANCE_SECONDS 300L; // 允许 ±5 分钟时间偏差 /** * 校验 Webhook 签名 * param signatureHeader anthropic-signature Header 的完整值 * param rawBody 请求原始字节不能经过任何解析处理 * param secret Webhook 密钥与 Anthropic 控制台配置一致 */ public static void verify(String signatureHeader, byte[] rawBody, String secret) throws Exception { // 第一步解析 Header String timestamp null; String receivedSignature null; for (String part : signatureHeader.split(,)) { if (part.startsWith(t)) timestamp part.substring(2); if (part.startsWith(v1)) receivedSignature part.substring(3); } if (timestamp null || receivedSignature null) { throw new SecurityException(签名 Header 格式不合法); } // 第二步防重放校验时间戳 long now System.currentTimeMillis() / 1000L; long ts Long.parseLong(timestamp); if (Math.abs(now - ts) TOLERANCE_SECONDS) { throw new SecurityException(请求时间戳超出允许范围可能是重放攻击); } // 第三步构造签名原文格式为 timestamp . 请求体 byte[] tsBytes timestamp.getBytes(StandardCharsets.UTF_8); byte[] dotBytes ..getBytes(StandardCharsets.UTF_8); byte[] payload new byte[tsBytes.length dotBytes.length rawBody.length]; System.arraycopy(tsBytes, 0, payload, 0, tsBytes.length); System.arraycopy(dotBytes, 0, payload, tsBytes.length, dotBytes.length); System.arraycopy(rawBody, 0, payload, tsBytes.length dotBytes.length, rawBody.length); // 第四步计算 HMAC-SHA256 Mac mac Mac.getInstance(HmacSHA256); mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), HmacSHA256)); String computed HexFormat.of().formatHex(mac.doFinal(payload)); // 第五步常量时间比较防止时序攻击 if (!MessageDigest.isEqual(computed.getBytes(), receivedSignature.getBytes())) { throw new SecurityException(签名校验失败); } } }5.3 Spring Boot Filter 集成这里有个坑需要特别说明Spring MVC 里如果直接用RequestBody String body接收参数框架会把请求流解码成 String这个过程可能引入编码变换进而破坏签名计算。所以必须从HttpServletRequest里直接读取原始字节流。RestController RequestMapping(/webhook) public class ClaudeWebhookController { Value(${anthropic.webhook-secret}) private String webhookSecret; PostMapping(/events) public ResponseEntityVoid handleEvent( HttpServletRequest request, RequestHeader(anthropic-signature) String signature) throws Exception { // 读取原始字节不经过任何字符串转换 byte[] rawBody request.getInputStream().readAllBytes(); // 先做签名校验 WebhookVerifier.verify(signature, rawBody, webhookSecret); // 校验通过后再处理业务逻辑 // ObjectMapper objectMapper ... // WebhookEvent event objectMapper.readValue(rawBody, WebhookEvent.class); return ResponseEntity.ok().build(); } }六、错误处理与生产级重试策略常见错误码速查状态码错误类型处理建议400invalid_request_error检查请求体格式、模型 ID 是否有效401authentication_errorAPI Key 无效或未传检查 Header403permission_errorKey 无权限访问该模型或功能429rate_limit_error触发速率限制需指数退避重试500api_errorAnthropic 服务内部错误可短暂重试529overloaded_error服务过载建议延迟后重试指数退避重试示例public String callWithRetry(SupplierString apiCall, int maxRetries) throws InterruptedException { int attempt 0; while (attempt maxRetries) { try { return apiCall.get(); } catch (RuntimeException e) { if (e.getMessage().contains(429) || e.getMessage().contains(529)) { long waitMs (long) (Math.pow(2, attempt) * 1000) (long)(Math.random() * 500); Thread.sleep(waitMs); attempt; } else { throw e; // 非速率限制错误直接抛出 } } } throw new RuntimeException(超过最大重试次数 maxRetries); }关于超时配置连接超时建议设 10 秒读取超时则根据任务复杂度设在 30 到 120 秒之间。流式Streaming调用需要单独配置更长的读取超时。七、AWS Bedrock 路径的 Java 实现对于已经在 AWS 体系内运营的企业通过 Bedrock 接入 Claude 可以统一走 AWS IAM 鉴权不需要单独管理 Anthropic API Key在合规和权限管理上会方便很多。!-- Maven 依赖 -- dependency groupIdsoftware.amazon.awssdk/groupId artifactIdbedrockruntime/artifactId version2.26.0/version !-- 以 AWS SDK 最新版为准 -- /dependencyimport software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.bedrockruntime.BedrockRuntimeClient; import software.amazon.awssdk.services.bedrockruntime.model.InvokeModelRequest; import software.amazon.awssdk.core.SdkBytes; public class BedrockClaudeExample { public static void main(String[] args) { BedrockRuntimeClient client BedrockRuntimeClient.builder() .region(Region.US_EAST_1) .credentialsProvider(DefaultCredentialsProvider.create()) // 从环境或 IAM Role 自动获取凭证 .build(); String requestBody { anthropic_version: bedrock-2023-05-31, max_tokens: 1024, messages: [ {role: user, content: 请介绍 AWS Bedrock 的优势。} ] } ; InvokeModelRequest request InvokeModelRequest.builder() .modelId(anthropic.claude-opus-4-5-v1:0) // Bedrock 模型 ID 格式与直连不同以 AWS 文档为准 .contentType(application/json) .body(SdkBytes.fromUtf8String(requestBody)) .build(); String responseBody client.invokeModel(request).body().asUtf8String(); System.out.println(responseBody); } }走 Bedrock 路径最大的好处是SigV4 签名由 AWS SDK 全程自动处理你只需要确保运行环境有合法的 AWS 凭证EC2 实例角色、ECS Task Role 或本地~/.aws/credentials均可完全不需要手动构造任何签名 Header。八、方案选型对比与总结维度官方 anthropic-java SDK手写 HttpClientSpring WebClientAWS Bedrock SDK接入难度低中中高需 AWS 账号配置依赖引入较重无额外依赖需 Spring WebFluxAWS SDK较重签名处理自动手动手动AWS SigV4 自动适用场景快速开发、标准调用轻量项目、定制化需求Spring Boot 响应式项目AWS 企业合规环境Webhook 验签需自行实现需自行实现需自行实现N/ABedrock 无 Webhook选型上有几条比较实用的建议普通 Java 项目优先选官方 SDK能少踩很多手动处理 Header 的坑Spring Boot 项目推荐 WebClient天然融入响应式架构如果已有 AWS 基础设施、有数据不出区域这类合规要求那 Bedrock 路径更合适。另外第三方兼容接入平台比如 ClaudeAPI通常兼容 Anthropic 原生接口格式切换时基本只需要改baseUrl和 Key签名逻辑不需要动具体以平台文档为准。最后提几个容易踩的坑时区问题Webhook 时间戳校验用的是 UTC Unix 时间戳System.currentTimeMillis() / 1000L本身不受 JVM 时区影响但如果是从 HTTP Header 解析日期字符串就需要格外注意时区转换。UTF-8 BOM部分 Windows 环境生成的 JSON 文件可能带有 BOM这会导致请求体签名和实际内容对不上发送前建议显式指定StandardCharsets.UTF_8编码。代理环境企业内网如果有 HTTP 代理Java 11 的 HttpClient 需要通过ProxySelector单独配置。另外如果代理会对 TLS 做中间人解包可能导致证书验证失败这个问题需要提前和网络团队确认清楚。