本文详解 TeamTailor API 调用中因 JSON 格式不规范导致 Unirest 或 OkHttpClient 报错（如 GCM 加密异常、响应解析失败）的问题，提供安全、健壮的候选人创建与职位申请全流程实现方案。

本文详解 teamtailor api 调用中因 json 格式不规范导致 `unirest` 或 `okhttpclient` 报错（如 gcm 加密异常、响应解析失败）的问题，提供安全、健壮的候选人创建与职位申请全流程实现方案。

在集成 TeamTailor API 时，开发者常遇到“请求在 Postman 中成功（返回 201），但在 Java 代码中却抛出异常”的典型问题——例如 Must use either different key or iv for GCM encryption 这类看似与加密相关的错误，实则多为底层 HTTP 客户端对非法 JSON 或响应体处理异常所触发的误导性堆栈信息。根本原因往往并非加密配置问题，而是请求体（body）构造不合规，尤其是手动拼接 JSON 字符串时引入了不可见字符、换行符、未转义引号或结构缺失。

? 问题定位：JSON 格式是关键瓶颈

原始 createCandidateUniRest 方法中，body() 直接传入硬编码的多行字符串：

.body("{\n    " +
      "\"data\": {\n        " +
      "\"type\": \"candidates\",\n        " +
      "\"attributes\": {\n            " +
      "\"first-name\": \"" + nome + "\",\n            " +
      "\"last-name\": \"" + cognome + "\",\n            " +
      "\"email\": \"" + email + "\"\n        }\n    }\n}")

该写法存在三重风险：

• ✅ JSON 注入漏洞：nome/cognome/email 若含双引号（"）、反斜杠（\）或换行符，将直接破坏 JSON 结构；
• ❌ 不可见字符污染：\n 和缩进空格虽合法，但部分 HTTP 客户端（尤其旧版 Unirest）在解析响应时可能因格式敏感而误判；
• ⚠️ 缺少顶层 relationships 或 meta 字段兼容性处理：TeamTailor API 严格遵循 JSON:API 规范，但部分版本对空白/冗余空格容忍度低。

? 提示：Must use either different key or iv for GCM encryption 这类错误通常源于 OkHttp 或 Unirest 在尝试解密/校验响应体失败后抛出的底层 SSL/TLS 异常，其真实诱因往往是服务端返回了非标准 JSON（如 HTML 错误页、空响应、格式错误的 JSON），客户端无法解析，进而触发加密层异常——这是典型的“症状掩盖病因”。

✅ 正确实践：使用 JSON 库构建请求体 + 健壮错误处理

推荐使用 org.json.JSONObject 或 com.google.gson.Gson 构造请求体，确保语法绝对合法，并统一处理 HTTP 状态码与业务错误：

✅ 重构后的 createCandidate 方法（推荐 Gson）

import com.google.gson.Gson;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

private String createCandidate(String nome, String cognome, String email) throws Exception {
    Gson gson = new Gson();
    JsonObject data = new JsonObject();
    data.addProperty("type", "candidates");

    JsonObject attributes = new JsonObject();
    attributes.addProperty("first-name", nome);
    attributes.addProperty("last-name", cognome);
    attributes.addProperty("email", email);
    data.add("attributes", attributes);

    JsonObject requestBody = new JsonObject();
    requestBody.add("data", data);

    HttpResponse<String> response = Unirest.post("https://api.teamtailor.com/v1/candidates")
            .header("Authorization", "Token token=" + authToken)
            .header("X-Api-Version", "20210218")
            .header("Content-Type", "application/vnd.api+json")
            .body(gson.toJson(requestBody))
            .asString();

    // 关键：检查 HTTP 状态码，而非仅依赖 try-catch
    if (response.getStatus() != 201) {
        throw new RuntimeException(
            String.format("Failed to create candidate: %d %s | Response: %s",
                response.getStatus(), response.getStatusText(), response.getBody())
        );
    }

    JsonObject jsonResponse = JsonParser.parseString(response.getBody()).getAsJsonObject();
    return jsonResponse.getAsJsonObject("data").get("id").getAsString();
}

✅ createJobApplication 同步升级（避免嵌套异常掩盖根源）

public Response createJobApplication(String nome, String cognome, String email) throws Exception {
    String candidateId;
    try {
        candidateId = createCandidate(nome, cognome, email);
    } catch (Exception e) {
        throw new CandidateCreationException("Failed to create candidate", e);
    }

    // 构建 job-application 请求体（同样使用 Gson）
    JsonObject data = new JsonObject();
    data.addProperty("type", "job-applications");

    JsonObject attributes = new JsonObject();
    attributes.addProperty("cover-letter", "");
    attributes.addProperty("sourced", true);
    attributes.addProperty("send-user-notifications", true);
    data.add("attributes", attributes);

    JsonObject relationships = new JsonObject();

    JsonObject candidateRel = new JsonObject();
    candidateRel.addProperty("type", "candidates");
    candidateRel.addProperty("id", candidateId);
    relationships.add("candidate", candidateRel);

    JsonObject jobRel = new JsonObject();
    jobRel.addProperty("type", "jobs");
    jobRel.addProperty("id", jobId);
    relationships.add("job", jobRel);

    data.add("relationships", relationships);

    JsonObject requestBody = new JsonObject();
    requestBody.add("data", data);

    Request request = new Request.Builder()
            .url("https://api.teamtailor.com/v1/job-applications")
            .post(RequestBody.create(
                MediaType.get("application/vnd.api+json"),
                new Gson().toJson(requestBody)
            ))
            .header("Authorization", "Token token=" + authToken)
            .header("X-Api-Version", "20210218")
            .build();

    try (Response response = client.newCall(request).execute()) {
        if (!response.isSuccessful()) {
            throw new IOException("Job application creation failed: " + response);
        }
        return response;
    }
}

⚠️ 必须注意的 4 项最佳实践

• 永远验证 HTTP 状态码：不要仅依赖 try/catch 捕获 IOException；200–299 外的状态（如 400 Bad Request）需主动检查并解析 response.getBody() 中的错误详情（TeamTailor 通常返回 {"errors": [...]} 结构）。
• 禁用手动字符串拼接 JSON：JSONObject / Gson 自动处理转义与格式，杜绝注入与语法错误。
• 设置合理的超时：Unirest.setTimeouts(0, 0) 表示无限等待，生产环境应设为 5_000（5秒）连接+读取超时。
• 启用日志调试（临时）：在开发期添加 .header("X-Debug", "true") 并打印完整 requestBody 与 response.getBody()，快速比对 Postman 差异。

✅ 总结

TeamTailor API 集成失败的绝大多数案例，根源在于不严谨的 JSON 构造方式，而非认证、网络或加密配置。通过弃用手动拼接、改用成熟 JSON 库、强化状态码校验与错误反馈，即可彻底规避 GCM encryption 类误导性异常，实现稳定、可维护的候选人全生命周期管理。记住：API 的契约是 JSON:API，你的代码必须成为最守约的一方。