API设计最佳实践：避免返回异构列表，拥抱结构化数据模型

在api设计中，直接返回异构或泛型列表（如`list

API数据返回的挑战：为何应避免直接返回异构列表

在构建RESTful API时，我们经常需要返回一组数据。一个常见的场景是返回一个特定类型的对象列表，例如一个电影评分列表。

假设我们有一个Rating类，定义如下：

public class Rating {
    private Long movieId;
    private Integer rating;
    // ... 其他字段和getter/setter
}

一个API可能返回List<Rating>，其JSON响应示例如下：

[
  {"movieId":5870,"rating":5},
  {"movieId":1234,"rating":3}
]

这种方式在多数情况下是清晰且类型安全的。客户端可以很容易地将此JSON响应反序列化为List<Rating>。

然而，当需求发生变化，我们需要在现有数据基础上添加额外信息时，问题便浮现了。例如，我们想在评分列表之外，额外指明这些评分属于哪个用户（例如“John Doe”）。一些开发者可能会尝试将额外信息直接添加到现有列表中，导致返回一个异构列表，例如List<Object>：

@GetMapping("/ratings-with-owner")
public List<Object> getRatingsWithOwner() {
    List<Object> finalList = new ArrayList<>();
    finalList.add(new Rating(5870L, 5));
    finalList.add(new Rating(1234L, 3));
    finalList.add("John Doe"); // 添加一个字符串
    return finalList;
}

对应的JSON响应可能看起来像这样：

[
  {"movieId":5870,"rating":5},
  {"movieId":1234,"rating":3},
  "John Doe"
]

这种做法虽然在技术上可行，但却是API设计中的一个反模式，存在以下严重问题：

1. 类型安全丧失与解析复杂性： 当API返回List<Object>时，JSON解析器无法自动推断列表中每个元素的具体类型。客户端在接收到响应后，必须手动遍历列表，逐一检查每个元素的类型（例如，判断是Rating对象还是String），并根据类型进行相应的处理。这不仅增加了客户端代码的复杂性，也极易出错。

   例如，客户端可能需要编写类似以下的逻辑：

   List<Object> response = apiService.getRatingsWithOwner();
   String ownerName = null;
   List<Rating> ratings = new ArrayList<>();
   for (Object item : response) {
       if (item instanceof Rating) {
           ratings.add((Rating) item);
       } else if (item instanceof String) {
           ownerName = (String) item;
       }
   }
   // ... 后续处理

   登录后复制

   这种手动判断和类型转换的过程繁琐且脆弱。

   

   Medeo

   AI视频生成工具

   191

   查看详情

2. API契约模糊不清： 一个良好的API应该提供清晰、明确的契约，告知消费者预期的数据结构。返回List<Object>模糊了这一契约。客户端无法确定：

   • “John Doe”这个字符串是否总是会出现在列表中？
   • 如果出现，它会固定在哪个位置（例如，总是在末尾）？
   • 未来是否还会添加其他类型的元素？ 这种不确定性使得API难以理解和使用，也难以编写健壮的客户端代码。

3. 可维护性与可扩展性差： 如果未来需要添加更多信息（例如，评分的平均值、用户ID等），或者改变这些额外信息的顺序，现有客户端代码将很可能被破坏。每次API响应结构发生细微变化，都可能需要客户端进行大规模的修改和重新部署。这严重阻碍了API的演进和维护。

最佳实践：使用数据传输对象（DTO）封装数据

为了解决上述问题，最佳实践是始终将API响应封装在一个专门的数据传输对象（DTO）中，即使响应的核心内容是一个列表。这个DTO应该明确定义所有字段及其类型，从而提供一个清晰、类型安全且易于扩展的API契约。

针对我们之前添加用户名的例子，我们可以创建一个RatedActor DTO：

public class RatedActor {
    private String name;
    private List<Rating> ratings;

    public RatedActor(String name, List<Rating> ratings) {
        this.name = name;
        this.ratings = ratings;
    }

    // ... getter/setter
}

现在，API可以返回一个RatedActor对象，而不是一个异构列表：

@GetMapping("/ratings-with-owner")
public RatedActor getRatingsWithOwnerStructured() {
    List<Rating> userRatings = new ArrayList<>();
    userRatings.add(new Rating(5870L, 5));
    userRatings.add(new Rating(1234L, 3));

    return new RatedActor("John Doe", userRatings);
}

对应的JSON响应将是结构化的：

{
  "name": "John Doe",
  "ratings": [
    {"movieId":5870,"rating":5},
    {"movieId":1234,"rating":3}
  ]
}

这种方法带来了显著的优势：

• 清晰的API契约： 客户端现在清楚地知道API将返回一个包含name（字符串）和ratings（Rating对象列表）的RatedActor对象。
• 类型安全： JSON解析器可以轻松地将响应反序列化为RatedActor对象，无需手动类型检查。
• 易于扩展： 如果未来需要添加更多信息（例如，averageRating），只需在RatedActor类中添加新字段即可，通常不会破坏现有客户端。
• 可读性与可维护性： 服务器端和客户端代码都更加清晰、易于理解和维护。
• 符合面向对象原则： 这种方式利用了面向对象语言的数据模型能力，将相关数据封装在一起，形成一个有意义的实体。

总结

API是服务提供者与消费者之间的契约。一个设计良好的API应该提供清晰、稳定且易于理解的契约。直接返回异构或泛型列表（如List<Object>) 违背了这些原则，引入了类型安全问题、模糊了契约，并增加了客户端的解析负担和未来的维护成本。

核心原则：

1. 明确的API契约： 确保API响应的数据结构是明确且可预测的。
2. 类型安全： 尽量避免在API响应中使用泛型或异构类型，以便客户端能够轻松地进行类型推断和反序列化。
3. 封装数据： 即使是简单的列表，如果需要附带额外信息，也应将其封装在一个专用的数据传输对象（DTO）中。

通过遵循这些最佳实践，我们可以构建出更健壮、更易用、更易于维护和扩展的API，从而提升开发效率和系统稳定性。记住，API的清晰度就像一份合同，越明确，合作就越顺畅。

以上就是API设计最佳实践：避免返回异构列表，拥抱结构化数据模型的详细内容，更多请关注php中文网其它相关文章！