字节跳动Java后端面试深度解析（二）：API 可选字段兼容性设计 — 优雅处理新旧版本透传

1
{
2
  "id": "chatcmpl-abc123",
3
  "choices": [{
4
    "message": {
5
      "role": "assistant",
6
      "content": "答案内容",
7
      "reasoning": "让我先分析一下这个问题..."
8
    }
9
  }]
10
}

1
public record ChatMessage(
2
    String role,
3
    String content
4
) {}

1
@JsonIgnoreProperties(ignoreUnknown = true)
2
public record ChatMessage(
3
    String role,
4
    String content
5
) {}

1
@Configuration
2
public class JacksonConfig {
3
    @Bean
4
    public ObjectMapper objectMapper() {
5
        return new ObjectMapper()
6
            .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
7
    }
8
}

1
public record ChatMessage(
2
    String role,
3
    String content,
4
    @JsonAnySetter Map<String, Object> extraFields
5
) {
6
    public ChatMessage {
7
        if (extraFields == null) extraFields = Map.of();
8
    }
9
}

1
public record ChatMessage(
2
    String role,
3
    String content,
4
    @JsonIgnore Map<String, Object> extraFields
5
) {
6
    public ChatMessage {
7
        if (extraFields == null) extraFields = Map.of();
8
    }
9

10
    /** 获取推理过程，仅新版API返回 */
11
    public Optional<String> reasoning() {
12
        return Optional.ofNullable(extraFields.get("reasoning"))
13
            .map(Object::toString);
14
    }
15

16
    /** 是否包含新字段 */
17
    public boolean hasReasoning() {
18
        return extraFields.containsKey("reasoning");
19
    }
20
}

1
public class ApiViews {
2
    public interface V1 {}
3
    public interface V2 extends V1 {}
4
}

1
public record ChatMessage(
2
    @JsonView(ApiViews.V1.class) String role,
3
    @JsonView(ApiViews.V1.class) String content,
4
    @JsonView(ApiViews.V2.class) String reasoning
5
) {}

1
ObjectMapper mapper = new ObjectMapper();
2
mapper.setConfig(
3
    mapper.getDeserializationConfig()
4
        .withView(ApiViews.V1.class) // 或 V2
5
);
6
ChatMessage msg = mapper.readValue(json, ChatMessage.class);

1
/**
2
 * AI 响应的透传模型：
3
 * - 已知字段解析为强类型
4
 * - 未知字段保留在 rawJson 中，原样透传给客户端
5
 */
6
public class PassThroughResponse {
7

8
    // === 已知字段（强类型） ===
9
    private String id;
10
    private String model;
11
    private List<PassThroughChoice> choices;
12

13
    // === 原始 JSON（保留完整响应，用于透传） ===
14
    @JsonIgnore
15
    private JsonNode rawJsonNode;
16

17
    // 反序列化完成后回调，保存原始节点
18
    @JsonCreator
19
    public PassThroughResponse() {}
20

21
    // 由自定义反序列化器设置
22
    public void setRawJsonNode(JsonNode node) {
23
        this.rawJsonNode = node;
24
    }
25

26
    /**
27
     * 将完整响应序列化为 JSON（包含所有字段，包括未知的）
28
     * 用于透传给客户端
29
     */
30
    public String toRawJson(ObjectMapper mapper) {
31
        return rawJsonNode.toString();
32
    }
33

34
    /**
35
     * 获取特定版本客户端需要的字段子集
36
     */
37
    public JsonNode getFieldsForVersion(ObjectMapper mapper, Set<String> fields) {
38
        ObjectNode result = mapper.createObjectNode();
39
        if (rawJsonNode == null) return result;
40
        fields.forEach(field -> {
41
            JsonNode value = rawJsonNode.get(field);
42
            if (value != null) result.set(field, value);
43
        });
44
        return result;
45
    }
46
}

1
public class PassThroughDeserializer extends JsonDeserializer<PassThroughResponse> {
2

3
    private final ObjectMapper mapper = new ObjectMapper();
4

5
    @Override
6
    public PassThroughResponse deserialize(
7
            JsonParser p, DeserializationContext ctxt) throws IOException {
8
        JsonNode rootNode = p.getCodec().readTree(p);
9

10
        // 1. 保留原始 JSON
11
        PassThroughResponse response = new PassThroughResponse();
12
        response.setRawJsonNode(rootNode);
13

14
        // 2. 只解析已知的、稳定的字段
15
        response.setId(rootNode.path("id").asText(null));
16
        response.setModel(rootNode.path("model").asText(null));
17

18
        // 3. choices 数组按需解析
19
        JsonNode choicesNode = rootNode.path("choices");
20
        if (choicesNode.isArray()) {
21
            List<PassThroughResponse.PassThroughChoice> choices = new ArrayList<>();
22
            for (JsonNode choiceNode : choicesNode) {
23
                choices.add(parseChoice(choiceNode));
24
            }
25
            response.setChoices(choices);
26
        }
27

28
        return response;
29
    }
30

31
    private PassThroughResponse.PassThroughChoice parseChoice(JsonNode node) {
32
        JsonNode message = node.path("message");
33
        return new PassThroughResponse.PassThroughChoice(
34
            message.path("role").asText(),
35
            message.path("content").asText(null)
36
            // 注意：不解析 reasoning，保留在 rawJson 中
37
        );
38
    }
39
}

1
@RestController
2
@RequestMapping("/api/v1/chat")
3
public class ChatController {
4

5
    private final ChatService chatService;
6
    private final ObjectMapper objectMapper;
7

8
    @PostMapping("/completions")
9
    public ResponseEntity<String> chat(
10
            @RequestBody ChatRequest request,
11
            @RequestHeader(value = "X-Client-Version", defaultValue = "1.0") String clientVersion) {
12

13
        // 调用 AI 服务，获取透传响应
14
        PassThroughResponse response = chatService.callAi(request);
15

16
        // 根据客户端版本决定返回内容
17
        if (isV2Client(clientVersion)) {
18
            // V2 客户端：返回完整 JSON（包含 reasoning）
19
            return ResponseEntity.ok()
20
                .header("X-Response-Version", "2.0")
21
                .body(response.toRawJson(objectMapper));
22
        } else {
23
            // V1 客户端：只返回它认识的字段
24
            Set<String> v1Fields = Set.of("id", "model", "choices", "usage");
25
            JsonNode filtered = response.getFieldsForVersion(objectMapper, v1Fields);
26
            return ResponseEntity.ok()
27
                .header("X-Response-Version", "1.0")
28
                .body(filtered.toString());
29
        }
30
    }
31

32
    private boolean isV2Client(String version) {
33
        // 语义化版本比较
34
        return VersionComparator.compare(version, "2.0.0") >= 0;
35
    }
36
}