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 版本。