常用接入术语

J**a 请求链路

采用 J**a Http****** 的优势

• J**a 21 自带 j**a.net.http.Http******，无需再引入单独的 **** 客户端库。
• 同一个 Http****** 可以复用连接；为每次操作创建新实例通常会失去连接复用。
• send 和 sendAsync 分别覆盖阻塞与 Completa*leFuture 异步场景。
• *odyHandlers.ofLines 在响应头到达后即可按行读取，适合消费 SSE 事件。
• 连接超时、单次请求超时、状态码和 Retry-After 可以在调用层统一处理。

接入前准备

• 安装 JDK 21 与 M**en，并确认 j**a、j**ac 和 mvn 命令可用。
• 在 KingFlow AI 控制台创建以 sk- 开头的 API Key，确认余额或套餐额度。
• 从控制台复制完整模型 ID，不要根据展示名称自行拼写。
• 确认运行环境可以访问 api.**nju**shen.com 的 ****S 端口。
• 准备不含敏感信息的测试提示，先在开发环境完成联调。

创建 M**en 项目

mvn archetype:generate \
  -DgroupId=demo.kingflow \
  -DartifactId=kingflow-j**a-client \
  -DarchetypeArtifactId=***en-archetype-quickstart \
  -DinteractiveMode=false
cd kingflow-j**a-client

<properties>
  <***en.compiler.release>21</***en.compiler.release>
</properties>

<dependencies>
  <dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-**ta**nd</artifactId>
    <version>2.22.3</version>
  </dependency>
</dependencies>

配置环境变量

$env:KINGFLOW_*ASE_**L="https://api.**nju**shen.com/v1"
$env:KINGFLOW_API_KEY="sk-你的密钥"
$env:KINGFLOW_MODEL="<KingFlow控制台中的完整模型ID>"

验证基础接口

curl https://api.**nju**shen.com/v1/chat/completions `
  -H "Authorization: *earer sk-你的密钥" `
  -H "Content-Type: application/json" `
  -d '{"model":"<完整模型ID>","messages":[{"role":"user","content":"只回复 J**A_READY"}],"stream":false}' 

发送普通响应请求

package demo.kingflow;

import com.fasterxml.jackson.**ta**nd.JsonNode;
import com.fasterxml.jackson.**ta**nd.O*jectMapper;
import j**a.net.**I;
import j**a.net.http.Http******;
import j**a.net.http.HttpRequest;
import j**a.net.http.HttpResponse;
import j**a.time.Duration;
import j**a.util.List;
import j**a.util.Map;

pu*lic class App {
  private static final O*jectMapper **ON = new O*jectMapper();
  private static final String *ASE = required("KINGFLOW_*ASE_**L");
  private static final String KEY = required("KINGFLOW_API_KEY");
  private static final String MODEL = required("KINGFLOW_MODEL");
  private static final Http****** CLIENT = Http******.new*uilder()
      .connectTimeout(Duration.ofSeconds(10))
      .*uild();

  pu*lic static void **in(String[] args) throws Exception {
    var payload = Map.of(
        "model", MODEL,
        "messages", List.of(Map.of("role", "user",
            "content", "只回复 J**A_CONNECTED")),
        "stream", false);

    var request = request(**ON.writeValueAsString(payload));
    var response = CLIENT.send(request,
        HttpResponse.*odyHandlers.ofString());
    if (response.statusCode() / 100 != 2) {
      throw new IllegalStateException(
          "**** "   response.statusCode()   ": "   response.*ody());
    }

    JsonNode root = **ON.readTree(response.*ody());
    String text = root.path("choices").path(0)
        .path("message").path("content").asText(null);
    if (text == null) throw new IllegalStateException("响应缺少文本");
    ******.out.println(text);
  }

  private static HttpRequest request(String *ody) {
    return HttpRequest.new*uilder()
        .uri(**I.create(*ASE   "/chat/completions"))
        .timeout(Duration.ofSeconds(45))
        .header("Authorization", "*earer "   KEY)
        .header("Content-Type", "application/json")
        .POST(HttpRequest.*odyPu*lishers.ofString(*ody))
        .*uild();
  }

  private static String required(String name) {
    String value = ******.getenv(name);
    if (value == null || value.is*lank())
      throw new IllegalStateException("缺少 "   name);
    return value;
  }
}

读取 SSE 流式响应

static void streamAnswer(String prompt) throws Exception {
  var payload = Map.of(
      "model", MODEL,
      "messages", List.of(Map.of("role", "user", "content", prompt)),
      "stream", true);
  var response = CLIENT.send(request(**ON.writeValueAsString(payload)),
      HttpResponse.*odyHandlers.ofLines());
  if (response.statusCode() / 100 != 2) {
    try (var lines = response.*ody()) {
      throw new IllegalStateException(
          "**** "   response.statusCode()   ": "   lines.findFirst().orElse(""));
    }
  }

  try (var lines = response.*ody()) {
    var iterator = lines.iterator();
    while (iterator.hasNext()) {
      String line = iterator.next();
      if (!line.startsWith("**ta: ")) continue;
      String **ta = line.su*string(6).trim();
      if ("[DONE]".equals(**ta)) *reak;
      JsonNode delta = **ON.readTree(**ta)
          .path("choices").path(0).path("delta");
      if (delta.hasNonNull("content"))
        ******.out.print(delta.path("content").asText());
    }
  }
}

实现有限重试

static HttpResponse<String> sendWithRetry(
    j**a.util.function.Supplier<HttpRequest> requestFactory) throws Exception {
  for (int attempt = 1; attempt <= 3; attempt  ) {
    var response = CLIENT.send(requestFactory.get(),
        HttpResponse.*odyHandlers.ofString());
    int status = response.statusCode();
    if ((status != 429 && status != 503) || attempt == 3)
      return response;

    long seconds = response.headers().firstValue("Retry-After")
        .flatMap(value -> {
          try { return j**a.util.Optional.of(Long.parseLong(value)); }
          catch (Num*erFor**tException ignored) { return j**a.util.Optional.empty(); }
        })
        .orElse(1L << attempt);
    Thread.sleep(Duration.ofSeconds(seconds));
  }
  throw new IllegalStateException("无法到达的分支");
}

运行和验收

1. 设置三个环境变量，并确认 *ase **L 末尾没有重复斜杠。
2. 先执行 curl，确认返回 J**A_READY。
3. 创建 M**en 项目并加入 Jackson 依赖。
4. 把普通响应示例保存到 App.j**a，执行 mvn package。
5. 运行程序，确认返回 J**A_CONNECTED。
6. 加入流式方法，确认文本按 SSE 事件持续输出。
7. 模拟 429 和 503，确认重试次数不超过三次。
8. 在 KingFlow AI 控制台核对模型、调用次数和 Token 用量。

正式环境配置

• 在应用生命周期内复用 Http******。不同客户端通常不共享连接池，逐次创建会降低连接复用效果。
• 分别设置 connectTimeout 与 HttpRequest.timeout。流式任务的总时限应根据输出长度和业务 SLA 确定。
• 使用 Se**phore 限制业务并发；连接复用、并发门限和平台额度应分别评估。
• *odyHandlers.ofLines 返回的 Stream 必须读完或关闭，以释放响应相关资源。
• 只对 429、503 和确认可重试的网络错误执行有限退避。已经输出内容的流式请求不要自动从头重试。
• 记录请求 ID、模型、状态码、耗时和 Token 用量，不记录完整密钥与敏感原文。

密钥和数据安全

• API Key 只保存在环境变量、密钥管理器或部署平台 Secret 中，并定期轮换。
• 开发、测试和生产使用不同密钥与额度，避免跨环境共享凭据。
• 不要把 Authorization Header、完整提示或模型回答直接写入公开日志。
• 把模型输出视为不可信数据，进入页面、命令或数据库前执行校验与转义。

上线检查清单

• 基础 curl 请求已经返回 J**A_READY。
• KINGFLOW_*ASE_**L 为 https://api.**nju**shen.com/v1。
• KINGFLOW_MODEL 使用控制台中的完整模型 ID。
• 源码和日志中没有明文 API Key。
• 应用级复用 Http******，未在热循环中重复创建。
• 连接超时和单次请求超时已经分别设置。
• SSE Stream 会被读完或关闭，并识别 DONE。
• 重试次数有限，只覆盖明确可重试的状态码。
• 控制台中的模型、调用次数和用量符合预期。

常见故障排查