17370845950

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

在api设计中，直接返回异构或泛型列表（如`list`) 会导致类型安全丧失、api契约模糊不清，并增加客户端解析复杂度与未来维护成本。最佳实践是使用专门的数据传输对象（dto）封装数据，即使仅需返回一个列表，也应将其作为dto的一个字段，以提供清晰、类型安全且易于扩展的api接口。

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

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

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

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

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

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

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

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

@GetMapping("/ratings-with-owner")
public List getRatingsWithOwner() {
    List 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时，JSON解析器无法自动推断列表中每个元素的具体类型。客户端在接收到响应后，必须手动遍历列表，逐一检查每个元素的类型（例如，判断是Rating对象还是String），并根据类型进行相应的处理。这不仅增加了客户端代码的复杂性，也极易出错。
    

    例如，客户端可能需要编写类似以下的逻辑：
    List response = apiService.getRatingsWithOwner();
String ownerName = null;
List ratings = new ArrayList<>();
for (Object item : response) {
    if (item instanceof Rating) {
        ratings.add((Rating) item);
    } else if (item instanceof String) {
        ownerName = (String) item;
    }
}
// ... 后续处理
    这种手动判断和类型转换的过程繁琐且脆弱。
    


  2. 

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

      

    • “John Doe”这个字符串是否总是会出现在列表中？
      • 

    • 如果出现，它会固定在哪个位置（例如，总是在末尾）？
      • 

    • 未来是否还会添加其他类型的元素？
这种不确定性使得API难以理解和使用，也难以编写健壮的客户端代码。
      • 

    

    3. 

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


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

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

    针对我们之前添加用户名的例子，我们可以创建一个RatedActor DTO：
    public class RatedActor {
    private String name;
    private List ratings;

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

    // ... getter/setter
}
    现在，API可以返回一个RatedActor对象，而不是一个异构列表：
    @GetMapping("/ratings-with-owner")
public RatedActor getRatingsWithOwnerStructured() {
    List 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) 违背了这些原则，引入了类型安全问题、模糊了契约，并增加了客户端的解析负担和未来的维护成本。
    

    核心原则：
    

      

    1. 
明确的API契约： 确保API响应的数据结构是明确且可预测的。
      2. 

    2. 
类型安全： 尽量避免在API响应中使用泛型或异构类型，以便客户端能够轻松地进行类型推断和反序列化。
      3. 

    3. 
封装数据： 即使是简单的列表，如果需要附带额外信息，也应将其封装在一个专用的数据传输对象（DTO）中。
      4. 

    

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









            
            
    
              
              
            
    
          
        
      
      


      
    赣ICP备2024031479号