本文详解 teamtailor rest api 调用中因 json 格式不规范、异常处理缺失及 http 客户端混用导致的“看似成功实则失败”问题，并提供安全、可维护的 java 实现方案。
本文详解 teamtailor rest api 调用中因 json 格式不规范、异常处理缺失及 http 客户端混用导致的“看似成功实则失败”问题，并提供安全、可维护的 java 实现方案。
在集成 TeamTailor API 时，开发者常遇到一种典型矛盾现象：API 请求实际成功（如候选人已创建，HTTP 状态码为 201 Created），但客户端却抛出异常、中断后续流程（如无法继续创建职位申请）。你提供的代码中，createCandidateUniRest 方法使用了拼接字符串方式构造 JSON 请求体，这是问题根源所在——非法 JSON 格式触发了底层加密/解析层的意外行为（如报错 “Must use either different key or iv for GCM encryption”），该错误并非来自 TeamTailor 服务端，而是由客户端 JSON 解析器或 HTTP 库（如 OkHttp 或 Unirest 内部依赖）在处理畸形 JSON 时引发的底层安全机制异常。
✅ 正确做法：始终使用 JSON 库生成请求体
手动拼接 JSON 字符串极易引入引号转义错误、空格/换行不兼容、特殊字符（如单引号、反斜杠、Unicode）未编码等问题。TeamTailor 的 API 严格遵循 JSON:API 规范，要求 Content-Type: application/vnd.api+json 及结构精确的 payload。应改用成熟 JSON 库（如 org.json.JSONObject、com.google.gson.Gson 或 Jackson）序列化对象。
以下是重构后的 createCandidateUniRest 方法（使用 org.json）：
private String createCandidateUniRest(String nome, String cognome, String email) throws UnirestException {
// 构建符合 JSON:API 规范的 request body（自动处理转义与格式）
JSONObject data = new JSONObject();
data.put("type", "candidates");
JSONObject attributes = new JSONObject();
attributes.put("first-name", nome);
attributes.put("last-name", cognome);
attributes.put("email", email);
data.put("attributes", attributes);
JSONObject requestBody = new JSONObject();
requestBody.put("data", data);
Unirest.setTimeouts(0, 0);
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(requestBody.toString()) // ← 安全、标准的 JSON 字符串
.asString();
// 检查 HTTP 状态码，避免“假成功”
if (response.getStatus() != 201) {
throw new UnirestException(
String.format("TeamTailor candidate creation failed: %d %s | Response: %s",
response.getStatus(), response.getStatusText(), response.getBody())
);
}
JSONObject jsonResponse = new JSONObject(response.getBody());
return jsonResponse.getJSONObject("data").getString("id");
}⚠️ 关键注意事项
- 绝不混合使用 HTTP 客户端库：你的 createJobApplication 方法在 createCandidateUniRest 后突然切换至 OkHttpClient。这不仅增加维护成本，更可能因不同库对连接池、SSL 配置、超时策略的差异引入隐蔽故障。建议统一使用一套客户端（推荐 OkHttp + Gson，或 Unirest v3+，二者均更现代稳定）。
- 必须校验 HTTP 状态码：TeamTailor 返回 201 表示成功；若收到 4xx/5xx，即使 response.getBody() 可解析，也代表业务失败。忽略状态码是“候选人被创建但方法仍报错”的根本原因。
- 异常需明确分类与传播：UnirestException 和 IOException 是底层网络异常，而 TeamTailorValidationException（如邮箱格式错误）应从响应体中提取并封装为业务异常，便于上层区分重试策略。
- 敏感信息脱敏日志：调试时打印 response.getBody() 可能泄露 PII（个人身份信息）。生产环境应禁用或脱敏（如 email: "u***@e***.com"）。
✅ 推荐的统一 OkHttp + Gson 实现（片段）
// 初始化一次（建议作为 Bean 或静态 final）
private static final OkHttpClient client = new OkHttpClient.Builder()
.connectTimeout(30, TimeUnit.SECONDS)
.readTimeout(30, TimeUnit.SECONDS)
.build();
private static final Gson gson = new Gson();
// 创建候选人（返回 ID 或抛出明确异常）
private String createCandidate(String firstName, String lastName, String email) {
JsonObject data = new JsonObject();
data.addProperty("type", "candidates");
JsonObject attributes = new JsonObject();
attributes.addProperty("first-name", firstName);
attributes.addProperty("last-name", lastName);
attributes.addProperty("email", email);
data.add("attributes", attributes);
JsonObject requestBody = new JsonObject();
requestBody.add("data", data);
Request request = new Request.Builder()
.url("https://api.teamtailor.com/v1/candidates")
.post(RequestBody.create(
MediaType.get("application/vnd.api+json"),
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 RuntimeException("API error: " + response);
}
JsonObject json = gson.fromJson(response.body().string(), JsonObject.class);
return json.getAsJsonObject("data").get("id").getAsString();
} catch (IOException e) {
throw new RuntimeException("Network error while creating candidate", e);
}
}通过强制使用 JSON 库生成 payload、统一 HTTP 客户端、显式校验状态码，即可彻底规避“GCM 加密异常”等伪错误，并构建出高可靠性、易调试的 TeamTailor 集成链路。
