Java API 中输入的版本控制

Question

我有一个 Spring Boot API，它将 JSON 作为输入，并使用数据填充发送到另一个应用程序的 XML。

我目前正在为此寻找版本控制。 我采用的一种方法是添加基于 URI 或 header 的版本控制。 通过将版本包含在接受 header 中，我很可能将 go 用于基于 header 的选项。

我也在研究对输入数据本身进行版本控制的选项。 输入 JSON 最近发生了相当大的变化，这导致了任何更新都必须与客户端应用程序的更新相协调的问题。 如果可能的话，我想包括某种形式的版本控制，这样就可以发布 API 更新，而无需与客户端更新协调。

更改的示例包括以下内容，其中 JSON 结构已更改：

{
  "customer": {
    "dateOfBirth": "01/01/1970",
    "occupation": "TCH",
    "contractDetails": {
        "startDate": "08/12/2022"
    }
}

到：

{
  "customer": {
    "personalDetails: {
      "dateOfBirth": "01/01/1970",
      "occupation": "TCH"
    },
    "contractDetails": {
        "startDate": "08/12/2022"
    }
}

在我的应用程序中，我有一个客户 model，它看起来像这样：

@Data
@AllArgsConstructor(access=AccessLevel.PACKAGE)
@NoArgsConstructor(access=AccessLevel.PACKAGE)
@Builder(toBuilder=true)
public class Customer {
  @NotEmpty 
  private String dateOfBirth;

  @NotNull
  @Pattern(regexp="^[A-Z]{3}", message=INVALID_CODE)
  private String occupation;

  @Valid @NotNull private ContractDetails contractDetails;
}

现已更改为：

@Data
@AllArgsConstructor(access=AccessLevel.PACKAGE)
@NoArgsConstructor(access=AccessLevel.PACKAGE)
@Builder(toBuilder=true)
public class Customer {
  @Valid @NotNull private PersonalDetails personalDetails;
  @Valid @NotNull private ContractDetails contractDetails;
}


@SuperBuilder(toBuilder=true)
@Data
@AllArgsConstructor(access=AccessLevel.PACKAGE)
@NoArgsConstructor(access=AccessLevel.PACKAGE)
public class PersonalDetails {
  @NotEmpty 
  private String dateOfBirth;

  @NotNull
  @Pattern(regexp="^[A-Z]{3}", message=INVALID_CODE)
  private String occupation;
}

有什么方法可以识别具有某种版本控制类型的变量或类，以便一个客户端可能继续使用旧结构而另一个客户端可能使用新结构？ 如果没有某种方法来识别这一点，API 可能会迅速积累大量重复代码，并且任何人都可能难以增强/调试。 最后，我想包括一些流程，用于识别不再使用的版本并将它们弃用。

Answer 1

在 Spring Boot API 中有多种版本输入数据的方法。一些选择：

在 JSON 负载中使用版本字段：您可以向 API 发送一个版本字段。 该字段将反映客户端的有效负载结构版本。 然后 API 可能会利用此字段来解析和处理有效负载。

不同 API 版本的各种端点：您可以为不同的 API 版本使用不同的端点。 例如，您可能有 /api/v1/customer 和 /api/v2/customer，其中 v1 需要旧的有效负载结构，而 v2 需要新的。

内容协商：您可以使用内容协商让客户选择使用哪个 API 版本。 Accept header 中的版本参数可能会实现此目的。 例如，“接受：application/vnd.myapi.v1+json”。

各种 package 名称：您可以为不同的 model class 版本使用不同的 package 名称。 例如，您可能有 com.myapi.model.v1.Customer 和 v2.Customer。 这将使您拥有各种 class 版本而不会出现命名问题。

Jackson 的@JsonTypeInfo 和@JsonSubTypes 注解在 class 规范中定义了 class 版本。 如果您指定 class 版本，则 API 将使用正确的 class 版本。