人工智能AI 技能AI 评测【免费下载链接】skillsPublic repository for Agent Skills项目地址https://gitcode.com/GitHub_Trending/skills3/skills点击查看免费下载导读本文以本仓库 skills/claude-api/java/claude-api/README.md 为核心骨架系统讲解如何在 Java 工程中通过官方anthropic-javaSDKcom.anthropic.*接入 Claude API。你将掌握依赖安装、客户端初始化、消息请求、自适应思考Adaptive Thinking、Effort 参数、Prompt 缓存、Token 计数、PDF/文档输入、停止原因处理与类型化异常处理等完整实战能力并了解该语言文档配套的 Streaming、Tool Use、Files API 文档结构便于后续按需查阅。注意Java SDK 支持 Claude API 与基于注解类的 beta Tool Use但 Agent SDK 目前尚未提供 Java 版本。包引用速查类型分布一览Java SDK 的类型按包package组织。当示例中没有出现你需要的类时先通过下表定位避免盲目去拉取 SDK 源码import前缀包含内容com.anthropic.client/com.anthropic.client.okhttpAnthropicClient、AnthropicOkHttpClientcom.anthropic.models.messages非 beta 请求/响应类型MessageCreateParams、Model、Message、TextBlockParam、ContentBlockParam、ToolUseBlockParam、ToolResultBlockParam、CacheControlEphemeral、Tool*如ToolBash20250124、ToolTextEditor20250728、StopReason、StructuredMessage*com.anthropic.models.messages.batchesBatch APIBatchResultsParams、MessageBatchIndividualResponsecom.anthropic.models.betaAnthropicBetabeta 标志常量com.anthropic.models.beta.messagesbeta 端点类型MessageCreateParams、BetaMessage、BetaStopReason、BetaContextManagementConfig、BetaMcpToolset、BetaRequestMcpServerUrlDefinition、BetaTool*com.anthropic.coreJsonValue、JsonField、JsonSchemaLocalValidation、com.anthropic.core.http.StreamResponsecom.anthropic.errors类型化异常AnthropicServiceException、RateLimitException、NotFoundException等详见 shared/error-codes.md一个关键区分client.messages()使用com.anthropic.models.messages.*client.beta().messages()使用com.anthropic.models.beta.messages.*。两个包都定义了MessageCreateParams——请根据你实际调用的 client 路径导入对应的那一个。按功能的关键类型对照表编写代码时应直接从此表出发而不是用javap/jar 检查。Endpoint 列决定了使用client.messages()还是client.beta().messages()功能Endpoint关键 Java 类型 / builder 调用User profilesbetaclient.beta().userProfiles().create(...)/.retrieve(id)/.list()将返回的 profile id 传给 beta 版MessageCreateParams需要 beta 头Agent SkillsbetaBetaContainerParams、BetaSkillParams、BetaCodeExecutionTool20250825.addBeta(code-execution-2025-08-25)Skills 已出 beta无需skills-2025-10-02头通过client.beta().files().download(fileId)下载输出Cache 诊断betaBetaDiagnosticsParam、BetaCacheControlEphemeral上下文编辑beta.contextManagement(BetaContextManagementConfig.builder()...)编辑策略为BetaClearToolUses20250919Edit或BetaClearThinking20251015Edit其触发器是单独构建后传给编辑 builder 的BetaInputTokensTrigger编辑 builder 上没有直接的.inputTokensTrigger(N)快捷方法Memory 工具非 beta.addTool(MemoryTool20250818.builder().build())来自com.anthropic.models.messages程序化工具调用非 betaCodeExecutionTool20260120、Tool、ContentBlockParam严格工具使用非 betaTool、Tool.InputSchemaTask budgetsbeta.outputConfig(BetaOutputConfig.builder().taskBudget(BetaTokenTaskBudget.builder()...))工具搜索非 beta.addTool(ToolSearchToolRegex20251119.builder()...)来自com.anthropic.models.messagesWeb 搜索非 betaWebSearchTool20260209来自com.anthropic.models.messages最新带动态过滤的变体Claude Fable 5.1 Claude Opus 5 Opus 4.8/4.7/4.6 Claude Sonnet 5 Sonnet 4.6旧模型或 Vertex 上使用WebSearchTool20250305快速定位类型与成员名如果上述两张表里找不到你需要的类或 builder 方法用 JVM 工具链快速定位即可jar tf anthropic-java-core.jar | grep -i term javap -classpath jar com.anthropic.models....不要为了枚举成员而编译并运行一个独立的反射程序——首次编译本身就足够慢容易陷入轮询等待。正确姿势是先用上面两条命令查出名字直接写出代码文件让编译器报错cannot find symbol来指出任何写错的成员名再迭代修正。依赖安装Maven / GradleMaven 在pom.xml中加入dependency groupIdcom.anthropic/groupId artifactIdanthropic-java/artifactId version2.34.0/version /dependencyGradle 在build.gradle中加入implementation(com.anthropic:anthropic-java:2.34.0)客户端初始化SDK 提供两种初始化方式import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; // 默认方式从环境变量 ANTHROPIC_API_KEY 读取密钥 AnthropicClient client AnthropicOkHttpClient.fromEnv(); // 显式指定 API Key AnthropicClient client AnthropicOkHttpClient.builder() .apiKey(your-api-key) .build();关于认证的完整规则包括ANTHROPIC_AUTH_TOKEN、OAuth profile、Workload Identity Federation 的解析顺序可参考 SKILL.md 的 Authentication 一节Java 侧零参数构造会自动完成 WIF 检测与 token 刷新。基础消息请求client.messages().create(params)是核心入口import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Message; MessageCreateParams params MessageCreateParams.builder() .model(claude-opus-5) // .model(String) 重载——对尚无类型化 Model 常量的 id 使用字符串版 .maxTokens(16000L) .addUserMessage(What is the capital of France?) .build(); Message response client.messages().create(params); response.content().stream() .flatMap(block - block.text().stream()) .forEach(textBlock - System.out.println(textBlock.text()));要点默认模型建议使用claude-opus-5来自 SKILL.md 的模型表字符串重载适合所有新模型 idmaxTokens非流式请求建议默认16000L避免触发 SDK HTTP 超时详见 SKILL.md 的max_tokens默认值说明内容块为强类型用.text()的Optional语义安全取文本。Thinking自适应思考模式Claude 4.6 模型推荐使用自适应思考Adaptive Thinking——由 Claude 动态决定何时思考、思考多少。Java builder 提供了直接的.thinking(ThinkingConfigAdaptive)重载无需手动包裹 union 类型。模型适配规则源自 SKILL.md 的 Thinking Effort 速查表Fable 5、Claude Opus 5、Opus 4.8、Opus 4.7、Opus 4.6、Sonnet 4.6使用自适应思考。ThinkingConfigEnabled.builder().budgetTokens(N)在 Fable 5、Opus 5、4.8、4.7 上已被移除发送即返回 400在 Opus 4.6 和 Sonnet 4.6 上已废弃。Claude Opus 5思考默认开启——省略.thinking(...)即运行自适应模式等价于显式ThinkingConfigAdaptive这与 Opus 4.8/4.7 省略即不思考不同。ThinkingConfigDisabled仅在 effort 为HIGH及以下被接受与XHIGH/MAX组合会返回 400。旧模型使用.thinking(ThinkingConfigEnabled.builder().budgetTokens(N).build())budget 必须 maxTokens最小 1024。import com.anthropic.models.messages.ContentBlock; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; import com.anthropic.models.messages.ThinkingConfigAdaptive; MessageCreateParams params MessageCreateParams.builder() .model(Model.CLAUDE_SONNET_4_6) .maxTokens(16000L) .thinking(ThinkingConfigAdaptive.builder().build()) .addUserMessage(Solve this step by step: 27 * 453) .build(); for (ContentBlock block : client.messages().create(params).content()) { block.thinking().ifPresent(t - System.out.println([thinking] t.thinking())); block.text().ifPresent(t - System.out.println(t.text())); }ContentBlock的窄化方式.thinking()/.text()返回OptionalT用.ifPresent(...)或.stream().flatMap(...)消费另一种方式是isThinking()/asThinking()布尔解包配对变体不匹配时抛异常。Effort 参数控制思考深度与成本Effort 嵌套在OutputConfig内部——MessageCreateParams.Builder上没有直接的.effort()方法import com.anthropic.models.messages.OutputConfig; .outputConfig(OutputConfig.builder() .effort(OutputConfig.Effort.HIGH) // 或 LOW、MEDIUM、XHIGH、MAX .build())与Thinking ThinkingConfigAdaptive组合即可做成本-质量平衡。根据 SKILL.mdeffort 控制思考深度与整体 token 开销默认high等价于省略xhighOpus 4.7 引入最适合大部分编码与 agentic 场景。Prompt 缓存命中率与成本优化System 消息需使用TextBlockParam列表并挂上CacheControlEphemeral。注意必须使用.systemOfTextBlockParams(...)——普通的.system(String)重载无法携带缓存控制。关于放置模式与静默失效器审计清单详见 shared/prompt-caching.md。import com.anthropic.models.messages.TextBlockParam; import com.anthropic.models.messages.CacheControlEphemeral; .systemOfTextBlockParams(List.of( TextBlockParam.builder() .text(longSystemPrompt) .cacheControl(CacheControlEphemeral.builder() .ttl(CacheControlEphemeral.Ttl.TTL_1H) // 可选还有 TTL_5M .build()) .build()))另外MessageCreateParams.Builder顶层和Tool.builder()上也有.cacheControl(CacheControlEphemeral)重载。验证命中通过response.usage().cacheCreationInputTokens()/response.usage().cacheReadInputTokens()检查。根据 shared/prompt-caching.md 的验证清单若重复请求下cacheReadInputTokens恒为 0说明存在静默失效器如 system prompt 里插入了datetime.now()、工具列表不稳定等一个健康的循环应当显示cache_read_input_tokens逐轮增长、cache_creation_input_tokens仅覆盖最新增量。总 prompt 大小 input_tokens cache_creation_input_tokens cache_read_input_tokens注意input_tokens只反映未缓存部分。还需注意最多 4 个cache_control断点/请求最小可缓存前缀因模型而异512–4096 token见 shared/prompt-caching.md 的 API reference 表。Token 计数使用countTokens端点POST /v1/messages/count_tokens获得与模型精确对应的计数。不要使用tiktoken——它是 OpenAI 的分词器对 Claude 典型文本低估约 15–20%代码与非英文输入偏差更大。详见 shared/token-counting.md。import com.anthropic.models.messages.MessageCountTokensParams; long tokens client.messages().countTokens( MessageCountTokensParams.builder() .model(Model.CLAUDE_SONNET_4_6) .addUserMessage(Hello) .build() ).inputTokens();计数必须传入与实际推理相同的model——token 数是模型相关的。PDF / 文档输入DocumentBlockParambuilder 提供 source 快捷方式外层用ContentBlockParam.ofDocument()包裹再通过.addUserMessageOfBlockParams()传入import com.anthropic.models.messages.DocumentBlockParam; import com.anthropic.models.messages.ContentBlockParam; import com.anthropic.models.messages.TextBlockParam; DocumentBlockParam doc DocumentBlockParam.builder() .source(Base64PdfSource.builder().data(base64String).build()) // 或 .source(UrlPdfSource.builder().url(https://...).build()) .title(My Document) // 可选 .build();对于Files API的文档引用需使用 beta 路径与 beta 类型见 files-api.mdBetaRequestDocumentBlock.builder().source(BetaFileDocumentSource.builder().fileId(id).build())——非 beta 的DocumentBlockParam.Source没有 file-ID 变体。.addUserMessageOfBlockParams(List.of( ContentBlockParam.ofDocument(doc), ContentBlockParam.ofText(TextBlockParam.builder().text(Summarize this).build())))停止原因与拒绝详情Stop Details当stopReason()为refusal时响应中会携带结构化的stopDetails()response.stopDetails().ifPresent(details - { System.out.println(Category: details.category()); System.out.println(Explanation: details.explanation()); });根据 SKILL.md 的说明stop_details仅在stop_reason refusal时填充字段含category——开放集合如cyber、bio、reasoning_extraction、frontier_llm或null——以及explanation其他停止原因下为null读取前务必守卫。拒绝回退Refusal fallbacksClaude Fable 5.1——默认建议开启。回退默认是 opt-in不配置时被拒绝的请求直接停止。新的claude-fable-5-1代码应默认携带服务端fallbacks参数beta 头server-side-fallback-2026-06-01回退模型claude-opus-4-8加在 beta messages 调用上。Java builder 方法的确切名称及无服务端支持平台的客户端中间件未在本文档中给出——可 WebFetch Java SDK 仓库的examples/入口见 shared/live-sources.md完整语义见 shared/model-migration.md 的 Migrating to Claude Fable 5.1 - refusal stop reason 章节。类型化异常处理AnthropicServiceException暴露.errorType()返回OptionalErrorType用于程序化错误分类try { client.messages().create(params); } catch (AnthropicServiceException e) { e.errorType().ifPresent(type - System.out.println(Error type: type) // RATE_LIMIT_ERROR、OVERLOADED_ERROR 等 ); }根据 shared/error-codes.md各 HTTP 状态码在 Java 侧映射为com.anthropic.errors.*下的具体异常类400 →BadRequestException、401 →UnauthorizedException、403 →PermissionDeniedException、404 →NotFoundException、422 →UnprocessableEntityException、429 →RateLimitException、≥500 →InternalServerException、网络层 →AnthropicIoException。应按最具体在前的顺序链式捕获try { client.messages().create(params); } catch (NotFoundException e) { // 404模型 id 拼错、资源不存在 ... } catch (RateLimitException e) { // 429退避后重试 ... } catch (AnthropicServiceException e) { // 其他所有非 2xx e.errorType().ifPresent(type - ...); }SDK 默认自动重试 429 与 5xx指数退避默认max_retries2无需自行实现重试避免用字符串匹配错误消息来判断错误类型。功能扩展指引配套文档一览本 Java 文档并非孤立的单文件它隶属于 claude-api 技能体系。Java 目录{lang}/claude-api/采用与其他 SDK 一致的多文件布局建议按需组合阅读流式响应streaming.md —— 使用client.messages().createStreaming(params)StreamResponseRawMessageStreamEvent通过contentBlockDelta逐段消费文本长输入/长输出或高max_tokens请求应默认流式以避免超时工具使用与 agentic 循环tool-use.md ——BetaToolRunner自动循环注解类实现SupplierString、Memory 工具BetaMemoryToolHandler、手动 JSON Schema 工具声明、结构化输出StructuredMessageCreateParams从 POJO 自动派生 schema、Anthropic 定义工具WebSearchTool20260209、ToolBash20250124等以及 MCP/beta 命名空间.addBeta(mcp-client-2025-11-20).addMcpServer(...)文件上传files-api.md ——client.beta().files().upload(...)后可list/delete/download/retrieveMetadata注意当前 SDK 中 Files API 已出 betaclient.beta().files()存在破坏性变更迁移时以稳定命名空间为准概念与平台细节缓存与失效层级见 shared/prompt-caching.md工具概念见 shared/tool-use-concepts.md错误码与各语言异常类见 shared/error-codes.md最新官方文档入口见 shared/live-sources.md。常见陷阱小结基于 SKILL.md 与本文档Java 集成的几个高频踩坑点包选择错误beta 与非 beta 的MessageCreateParams并存务必与所调用的 client 路径匹配BetaTool*类型与非 betaTool*不可互换一次请求只选一个命名空间budget_tokens已过时4.6 一律用ThinkingConfigAdaptive在 Opus 5/4.7/4.8 上继续发送enabled budget_tokens会直接 400effort必须嵌在OutputConfig里没有顶层.effort()快捷方法缓存必须验证改完 prompt 组装代码后用usage().cacheReadInputTokens()复查命中input_tokens只是未缓存部分不要把 SDK 能做的事自己做优先使用类型化异常、StreamResponse、builder 便捷方法避免重复造轮子不要猜测 SDK 用法类名、命名空间、方法签名必须来自本文档或 SDK 官方仓库shared/live-sources.md不要从 cURL 形状或其他语言 SDK 推断 Java API——先用jar tf/javap定位名字再让编译器帮你纠错。赞分享人工智能AI 技能AI 评测【免费下载链接】skillsPublic repository for Agent Skills项目地址https://gitcode.com/GitHub_Trending/skills3/skills点击查看免费下载相关推荐Java 集成 Claude API 完整指南anthropic-java SDK 实战与 RikkaHub 源码对照Java 集成 Claude API 完整指南anthropic java SDK 实战与 RikkaHub 源码对照 本篇技术指南以官方 Claude AP人工智能大模型AI 应用移动开发交互助手Claude API TypeScript 开发实战从消息请求、提示缓存到 Agent 化应用Claude API TypeScript 开发实战从消息请求、提示缓存到 Agent 化应用 本篇技术指南以开源仓库 agentic awesome skiAI 技能AI 插件RikkaHub 集成 Claude Messages API 实战指南基于 Anthropic Python SDK 的调用、缓存与错误处理全解析RikkaHub 集成 Claude Messages API 实战指南基于 Anthropic Python SDK 的调用、缓存与错误处理全解析 本指南以人工智能大模型AI 应用移动开发交互助手上一篇LFM2.5-VL-3B vs Gemma4/E4B多模态基准测试中的3B模型逆袭之路下一篇手机号找回QQ号码Python工具如何帮你3分钟搞定账号关联验证创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Java 开发者 Claude API 集成指南：基于 anthropic-java SDK 的消息请求、Thinking 与缓存实战
人工智能AI 技能AI 评测【免费下载链接】skillsPublic repository for Agent Skills项目地址https://gitcode.com/GitHub_Trending/skills3/skills点击查看免费下载导读本文以本仓库 skills/claude-api/java/claude-api/README.md 为核心骨架系统讲解如何在 Java 工程中通过官方anthropic-javaSDKcom.anthropic.*接入 Claude API。你将掌握依赖安装、客户端初始化、消息请求、自适应思考Adaptive Thinking、Effort 参数、Prompt 缓存、Token 计数、PDF/文档输入、停止原因处理与类型化异常处理等完整实战能力并了解该语言文档配套的 Streaming、Tool Use、Files API 文档结构便于后续按需查阅。注意Java SDK 支持 Claude API 与基于注解类的 beta Tool Use但 Agent SDK 目前尚未提供 Java 版本。包引用速查类型分布一览Java SDK 的类型按包package组织。当示例中没有出现你需要的类时先通过下表定位避免盲目去拉取 SDK 源码import前缀包含内容com.anthropic.client/com.anthropic.client.okhttpAnthropicClient、AnthropicOkHttpClientcom.anthropic.models.messages非 beta 请求/响应类型MessageCreateParams、Model、Message、TextBlockParam、ContentBlockParam、ToolUseBlockParam、ToolResultBlockParam、CacheControlEphemeral、Tool*如ToolBash20250124、ToolTextEditor20250728、StopReason、StructuredMessage*com.anthropic.models.messages.batchesBatch APIBatchResultsParams、MessageBatchIndividualResponsecom.anthropic.models.betaAnthropicBetabeta 标志常量com.anthropic.models.beta.messagesbeta 端点类型MessageCreateParams、BetaMessage、BetaStopReason、BetaContextManagementConfig、BetaMcpToolset、BetaRequestMcpServerUrlDefinition、BetaTool*com.anthropic.coreJsonValue、JsonField、JsonSchemaLocalValidation、com.anthropic.core.http.StreamResponsecom.anthropic.errors类型化异常AnthropicServiceException、RateLimitException、NotFoundException等详见 shared/error-codes.md一个关键区分client.messages()使用com.anthropic.models.messages.*client.beta().messages()使用com.anthropic.models.beta.messages.*。两个包都定义了MessageCreateParams——请根据你实际调用的 client 路径导入对应的那一个。按功能的关键类型对照表编写代码时应直接从此表出发而不是用javap/jar 检查。Endpoint 列决定了使用client.messages()还是client.beta().messages()功能Endpoint关键 Java 类型 / builder 调用User profilesbetaclient.beta().userProfiles().create(...)/.retrieve(id)/.list()将返回的 profile id 传给 beta 版MessageCreateParams需要 beta 头Agent SkillsbetaBetaContainerParams、BetaSkillParams、BetaCodeExecutionTool20250825.addBeta(code-execution-2025-08-25)Skills 已出 beta无需skills-2025-10-02头通过client.beta().files().download(fileId)下载输出Cache 诊断betaBetaDiagnosticsParam、BetaCacheControlEphemeral上下文编辑beta.contextManagement(BetaContextManagementConfig.builder()...)编辑策略为BetaClearToolUses20250919Edit或BetaClearThinking20251015Edit其触发器是单独构建后传给编辑 builder 的BetaInputTokensTrigger编辑 builder 上没有直接的.inputTokensTrigger(N)快捷方法Memory 工具非 beta.addTool(MemoryTool20250818.builder().build())来自com.anthropic.models.messages程序化工具调用非 betaCodeExecutionTool20260120、Tool、ContentBlockParam严格工具使用非 betaTool、Tool.InputSchemaTask budgetsbeta.outputConfig(BetaOutputConfig.builder().taskBudget(BetaTokenTaskBudget.builder()...))工具搜索非 beta.addTool(ToolSearchToolRegex20251119.builder()...)来自com.anthropic.models.messagesWeb 搜索非 betaWebSearchTool20260209来自com.anthropic.models.messages最新带动态过滤的变体Claude Fable 5.1 Claude Opus 5 Opus 4.8/4.7/4.6 Claude Sonnet 5 Sonnet 4.6旧模型或 Vertex 上使用WebSearchTool20250305快速定位类型与成员名如果上述两张表里找不到你需要的类或 builder 方法用 JVM 工具链快速定位即可jar tf anthropic-java-core.jar | grep -i term javap -classpath jar com.anthropic.models....不要为了枚举成员而编译并运行一个独立的反射程序——首次编译本身就足够慢容易陷入轮询等待。正确姿势是先用上面两条命令查出名字直接写出代码文件让编译器报错cannot find symbol来指出任何写错的成员名再迭代修正。依赖安装Maven / GradleMaven 在pom.xml中加入dependency groupIdcom.anthropic/groupId artifactIdanthropic-java/artifactId version2.34.0/version /dependencyGradle 在build.gradle中加入implementation(com.anthropic:anthropic-java:2.34.0)客户端初始化SDK 提供两种初始化方式import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; // 默认方式从环境变量 ANTHROPIC_API_KEY 读取密钥 AnthropicClient client AnthropicOkHttpClient.fromEnv(); // 显式指定 API Key AnthropicClient client AnthropicOkHttpClient.builder() .apiKey(your-api-key) .build();关于认证的完整规则包括ANTHROPIC_AUTH_TOKEN、OAuth profile、Workload Identity Federation 的解析顺序可参考 SKILL.md 的 Authentication 一节Java 侧零参数构造会自动完成 WIF 检测与 token 刷新。基础消息请求client.messages().create(params)是核心入口import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Message; MessageCreateParams params MessageCreateParams.builder() .model(claude-opus-5) // .model(String) 重载——对尚无类型化 Model 常量的 id 使用字符串版 .maxTokens(16000L) .addUserMessage(What is the capital of France?) .build(); Message response client.messages().create(params); response.content().stream() .flatMap(block - block.text().stream()) .forEach(textBlock - System.out.println(textBlock.text()));要点默认模型建议使用claude-opus-5来自 SKILL.md 的模型表字符串重载适合所有新模型 idmaxTokens非流式请求建议默认16000L避免触发 SDK HTTP 超时详见 SKILL.md 的max_tokens默认值说明内容块为强类型用.text()的Optional语义安全取文本。Thinking自适应思考模式Claude 4.6 模型推荐使用自适应思考Adaptive Thinking——由 Claude 动态决定何时思考、思考多少。Java builder 提供了直接的.thinking(ThinkingConfigAdaptive)重载无需手动包裹 union 类型。模型适配规则源自 SKILL.md 的 Thinking Effort 速查表Fable 5、Claude Opus 5、Opus 4.8、Opus 4.7、Opus 4.6、Sonnet 4.6使用自适应思考。ThinkingConfigEnabled.builder().budgetTokens(N)在 Fable 5、Opus 5、4.8、4.7 上已被移除发送即返回 400在 Opus 4.6 和 Sonnet 4.6 上已废弃。Claude Opus 5思考默认开启——省略.thinking(...)即运行自适应模式等价于显式ThinkingConfigAdaptive这与 Opus 4.8/4.7 省略即不思考不同。ThinkingConfigDisabled仅在 effort 为HIGH及以下被接受与XHIGH/MAX组合会返回 400。旧模型使用.thinking(ThinkingConfigEnabled.builder().budgetTokens(N).build())budget 必须 maxTokens最小 1024。import com.anthropic.models.messages.ContentBlock; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; import com.anthropic.models.messages.ThinkingConfigAdaptive; MessageCreateParams params MessageCreateParams.builder() .model(Model.CLAUDE_SONNET_4_6) .maxTokens(16000L) .thinking(ThinkingConfigAdaptive.builder().build()) .addUserMessage(Solve this step by step: 27 * 453) .build(); for (ContentBlock block : client.messages().create(params).content()) { block.thinking().ifPresent(t - System.out.println([thinking] t.thinking())); block.text().ifPresent(t - System.out.println(t.text())); }ContentBlock的窄化方式.thinking()/.text()返回OptionalT用.ifPresent(...)或.stream().flatMap(...)消费另一种方式是isThinking()/asThinking()布尔解包配对变体不匹配时抛异常。Effort 参数控制思考深度与成本Effort 嵌套在OutputConfig内部——MessageCreateParams.Builder上没有直接的.effort()方法import com.anthropic.models.messages.OutputConfig; .outputConfig(OutputConfig.builder() .effort(OutputConfig.Effort.HIGH) // 或 LOW、MEDIUM、XHIGH、MAX .build())与Thinking ThinkingConfigAdaptive组合即可做成本-质量平衡。根据 SKILL.mdeffort 控制思考深度与整体 token 开销默认high等价于省略xhighOpus 4.7 引入最适合大部分编码与 agentic 场景。Prompt 缓存命中率与成本优化System 消息需使用TextBlockParam列表并挂上CacheControlEphemeral。注意必须使用.systemOfTextBlockParams(...)——普通的.system(String)重载无法携带缓存控制。关于放置模式与静默失效器审计清单详见 shared/prompt-caching.md。import com.anthropic.models.messages.TextBlockParam; import com.anthropic.models.messages.CacheControlEphemeral; .systemOfTextBlockParams(List.of( TextBlockParam.builder() .text(longSystemPrompt) .cacheControl(CacheControlEphemeral.builder() .ttl(CacheControlEphemeral.Ttl.TTL_1H) // 可选还有 TTL_5M .build()) .build()))另外MessageCreateParams.Builder顶层和Tool.builder()上也有.cacheControl(CacheControlEphemeral)重载。验证命中通过response.usage().cacheCreationInputTokens()/response.usage().cacheReadInputTokens()检查。根据 shared/prompt-caching.md 的验证清单若重复请求下cacheReadInputTokens恒为 0说明存在静默失效器如 system prompt 里插入了datetime.now()、工具列表不稳定等一个健康的循环应当显示cache_read_input_tokens逐轮增长、cache_creation_input_tokens仅覆盖最新增量。总 prompt 大小 input_tokens cache_creation_input_tokens cache_read_input_tokens注意input_tokens只反映未缓存部分。还需注意最多 4 个cache_control断点/请求最小可缓存前缀因模型而异512–4096 token见 shared/prompt-caching.md 的 API reference 表。Token 计数使用countTokens端点POST /v1/messages/count_tokens获得与模型精确对应的计数。不要使用tiktoken——它是 OpenAI 的分词器对 Claude 典型文本低估约 15–20%代码与非英文输入偏差更大。详见 shared/token-counting.md。import com.anthropic.models.messages.MessageCountTokensParams; long tokens client.messages().countTokens( MessageCountTokensParams.builder() .model(Model.CLAUDE_SONNET_4_6) .addUserMessage(Hello) .build() ).inputTokens();计数必须传入与实际推理相同的model——token 数是模型相关的。PDF / 文档输入DocumentBlockParambuilder 提供 source 快捷方式外层用ContentBlockParam.ofDocument()包裹再通过.addUserMessageOfBlockParams()传入import com.anthropic.models.messages.DocumentBlockParam; import com.anthropic.models.messages.ContentBlockParam; import com.anthropic.models.messages.TextBlockParam; DocumentBlockParam doc DocumentBlockParam.builder() .source(Base64PdfSource.builder().data(base64String).build()) // 或 .source(UrlPdfSource.builder().url(https://...).build()) .title(My Document) // 可选 .build();对于Files API的文档引用需使用 beta 路径与 beta 类型见 files-api.mdBetaRequestDocumentBlock.builder().source(BetaFileDocumentSource.builder().fileId(id).build())——非 beta 的DocumentBlockParam.Source没有 file-ID 变体。.addUserMessageOfBlockParams(List.of( ContentBlockParam.ofDocument(doc), ContentBlockParam.ofText(TextBlockParam.builder().text(Summarize this).build())))停止原因与拒绝详情Stop Details当stopReason()为refusal时响应中会携带结构化的stopDetails()response.stopDetails().ifPresent(details - { System.out.println(Category: details.category()); System.out.println(Explanation: details.explanation()); });根据 SKILL.md 的说明stop_details仅在stop_reason refusal时填充字段含category——开放集合如cyber、bio、reasoning_extraction、frontier_llm或null——以及explanation其他停止原因下为null读取前务必守卫。拒绝回退Refusal fallbacksClaude Fable 5.1——默认建议开启。回退默认是 opt-in不配置时被拒绝的请求直接停止。新的claude-fable-5-1代码应默认携带服务端fallbacks参数beta 头server-side-fallback-2026-06-01回退模型claude-opus-4-8加在 beta messages 调用上。Java builder 方法的确切名称及无服务端支持平台的客户端中间件未在本文档中给出——可 WebFetch Java SDK 仓库的examples/入口见 shared/live-sources.md完整语义见 shared/model-migration.md 的 Migrating to Claude Fable 5.1 - refusal stop reason 章节。类型化异常处理AnthropicServiceException暴露.errorType()返回OptionalErrorType用于程序化错误分类try { client.messages().create(params); } catch (AnthropicServiceException e) { e.errorType().ifPresent(type - System.out.println(Error type: type) // RATE_LIMIT_ERROR、OVERLOADED_ERROR 等 ); }根据 shared/error-codes.md各 HTTP 状态码在 Java 侧映射为com.anthropic.errors.*下的具体异常类400 →BadRequestException、401 →UnauthorizedException、403 →PermissionDeniedException、404 →NotFoundException、422 →UnprocessableEntityException、429 →RateLimitException、≥500 →InternalServerException、网络层 →AnthropicIoException。应按最具体在前的顺序链式捕获try { client.messages().create(params); } catch (NotFoundException e) { // 404模型 id 拼错、资源不存在 ... } catch (RateLimitException e) { // 429退避后重试 ... } catch (AnthropicServiceException e) { // 其他所有非 2xx e.errorType().ifPresent(type - ...); }SDK 默认自动重试 429 与 5xx指数退避默认max_retries2无需自行实现重试避免用字符串匹配错误消息来判断错误类型。功能扩展指引配套文档一览本 Java 文档并非孤立的单文件它隶属于 claude-api 技能体系。Java 目录{lang}/claude-api/采用与其他 SDK 一致的多文件布局建议按需组合阅读流式响应streaming.md —— 使用client.messages().createStreaming(params)StreamResponseRawMessageStreamEvent通过contentBlockDelta逐段消费文本长输入/长输出或高max_tokens请求应默认流式以避免超时工具使用与 agentic 循环tool-use.md ——BetaToolRunner自动循环注解类实现SupplierString、Memory 工具BetaMemoryToolHandler、手动 JSON Schema 工具声明、结构化输出StructuredMessageCreateParams从 POJO 自动派生 schema、Anthropic 定义工具WebSearchTool20260209、ToolBash20250124等以及 MCP/beta 命名空间.addBeta(mcp-client-2025-11-20).addMcpServer(...)文件上传files-api.md ——client.beta().files().upload(...)后可list/delete/download/retrieveMetadata注意当前 SDK 中 Files API 已出 betaclient.beta().files()存在破坏性变更迁移时以稳定命名空间为准概念与平台细节缓存与失效层级见 shared/prompt-caching.md工具概念见 shared/tool-use-concepts.md错误码与各语言异常类见 shared/error-codes.md最新官方文档入口见 shared/live-sources.md。常见陷阱小结基于 SKILL.md 与本文档Java 集成的几个高频踩坑点包选择错误beta 与非 beta 的MessageCreateParams并存务必与所调用的 client 路径匹配BetaTool*类型与非 betaTool*不可互换一次请求只选一个命名空间budget_tokens已过时4.6 一律用ThinkingConfigAdaptive在 Opus 5/4.7/4.8 上继续发送enabled budget_tokens会直接 400effort必须嵌在OutputConfig里没有顶层.effort()快捷方法缓存必须验证改完 prompt 组装代码后用usage().cacheReadInputTokens()复查命中input_tokens只是未缓存部分不要把 SDK 能做的事自己做优先使用类型化异常、StreamResponse、builder 便捷方法避免重复造轮子不要猜测 SDK 用法类名、命名空间、方法签名必须来自本文档或 SDK 官方仓库shared/live-sources.md不要从 cURL 形状或其他语言 SDK 推断 Java API——先用jar tf/javap定位名字再让编译器帮你纠错。赞分享人工智能AI 技能AI 评测【免费下载链接】skillsPublic repository for Agent Skills项目地址https://gitcode.com/GitHub_Trending/skills3/skills点击查看免费下载相关推荐Java 集成 Claude API 完整指南anthropic-java SDK 实战与 RikkaHub 源码对照Java 集成 Claude API 完整指南anthropic java SDK 实战与 RikkaHub 源码对照 本篇技术指南以官方 Claude AP人工智能大模型AI 应用移动开发交互助手Claude API TypeScript 开发实战从消息请求、提示缓存到 Agent 化应用Claude API TypeScript 开发实战从消息请求、提示缓存到 Agent 化应用 本篇技术指南以开源仓库 agentic awesome skiAI 技能AI 插件RikkaHub 集成 Claude Messages API 实战指南基于 Anthropic Python SDK 的调用、缓存与错误处理全解析RikkaHub 集成 Claude Messages API 实战指南基于 Anthropic Python SDK 的调用、缓存与错误处理全解析 本指南以人工智能大模型AI 应用移动开发交互助手上一篇LFM2.5-VL-3B vs Gemma4/E4B多模态基准测试中的3B模型逆袭之路下一篇手机号找回QQ号码Python工具如何帮你3分钟搞定账号关联验证创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考