17370845950

新闻动态
优化API设计：为何应避免直接返回列表并封装为自定义对象

在api设计中，直接返回数据列表看似简洁，但随着业务需求演进，这种做法会引入类型不明确、数据结构不一致等问题，严重影响api的可维护性和可扩展性。本文将深入探讨直接返回列表的弊端，特别是使用list的陷阱，并推荐通过封装为自定义数据对象来构建清晰、健壮且易于扩展的api响应结构。

引言：API响应中的列表问题

在构建RESTful API时，我们经常需要返回一组数据。例如，一个电影评分API可能最初设计为返回一个Rating对象的列表，其中Rating类定义如下：

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

其API响应示例如下：

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

这种设计在初期非常直观和有效。然而，当业务需求发生变化，例如我们需要为这组评分添加一个归属信息（如“这些评分属于谁”），问题便随之而来。如果试图直接在现有列表中混入不同类型的数据，就会触及API设计中的一个核心痛点。

直接返回List的陷阱

为了在不改变API返回列表结构的前提下添加新的信息，有人可能会尝试将返回类型更改为List，并将新信息（如字符串“John Doe”）直接添加到列表中。

@GetMapping("-sth-")
public List foo() {
    List finalList = new ArrayList<>();
    finalList.add(new Rating(5870L, 5));
    finalList.add(new Rating(1234L, 3));
    finalList.add("John Doe"); // 添加一个字符串类型的数据

    return finalList;
}
此时的API响应可能看起来像这样：
[
  {"movieId":5870,"rating":5},
  {"movieId":1234,"rating":3},
  "John Doe"
]
尽管代码能够编译并返回这种结构，但这种做法在API设计中被视为不良实践，并带来一系列严重问题：


    

  1. 类型不明确与契约失效： API本质上是一种契约。当返回List时，API的消费者（客户端）无法明确知道列表中每个元素的具体类型。这破坏了API的明确性，客户端必须依赖“隐式知识”或猜测来处理数据，例如“最后一个元素总是字符串类型的用户名称”。这种隐式约定极易出错且难以维护。
    2. 

  2. 

    反序列化复杂性： 现代编程语言和框架通常提供强大的JSON解析库（如Jackson, Gson）。当API返回一个明确的List时，这些库可以轻松地将其反序列化为对应的Java对象列表。然而，当返回List并混杂多种类型时，自动反序列化将变得不可能。客户端需要：
    

      

    • 首先将响应反序列化为List。

      • 

    • 然后手动遍历列表，通过instanceof等操作判断每个元素的实际类型。
      • 

    • 根据类型进行相应的处理或二次转换。
这显著增加了客户端的开发和维护负担。
      • 

    

    3. 

  3. 维护性与扩展性差： 想象一下，如果未来需要添加更多元数据，或者“John Doe”的位置不固定，甚至可能不存在。客户端代码将变得异常复杂和脆弱，每次API响应结构发生微小变化，都可能导致客户端解析失败。这种设计无法优雅地应对需求变化，阻碍了API的长期演进。
    4. 

  4. 违背面向对象原则： 面向对象语言旨在通过定义清晰的类和对象来建模现实世界。将不同类型的数据混杂在同一列表中，并且依赖其顺序或位置来区分，违背了通过类型来表达数据模型的初衷。
    5. 



推荐做法：封装为自定义数据对象


解决上述问题的最佳实践是：将列表及其相关的元数据封装在一个自定义的、语义明确的数据传输对象（DTO）中。这为API提供了一个清晰、类型安全且易于扩展的契约。


例如，我们可以定义一个RatedActor类来封装评分列表及其归属人信息：
public class RatedActor {
    private String name;
    private List ratings;

    // 构造函数、Getter和Setter方法
    public RatedActor(String name, List ratings) {
        this.name = name;
        this.ratings = ratings;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public List getRatings() {
        return ratings;
    }

    public void setRatings(List ratings) {
        this.ratings = ratings;
    }
}
此时，API的返回类型将是RatedActor，其响应示例如下：
{
  "name": "John Doe",
  "ratings": [
    {"movieId":5870,"rating":5},
    {"movieId":1234,"rating":3}
  ]
}
这种设计带来了显著的优势：


    

  1. 
清晰的API契约： API明确声明它返回一个RatedActor对象，该对象包含一个name字段和一个ratings列表。客户端无需猜测，即可知道响应的完整结构。
    2. 

  2. 
类型安全与易于解析： JSON解析库可以直接将响应反序列化为RatedActor对象。客户端代码简洁明了，无需手动处理类型判断。
    3. 

  3. 
提升可维护性与可扩展性： 如果未来需要添加更多关于RatedActor的信息（例如，其ID、邮箱等），只需在RatedActor类中添加新的字段即可，而不会影响现有的ratings列表结构，也不会破坏客户端的解析逻辑。
    4. 

  4. 
符合面向对象原则： 这符合面向对象语言通过类来建模复杂数据结构的理念，使数据模型更加细粒度、易于理解和管理。
    5. 



总结与最佳实践


API是服务与客户端之间的通信桥梁，其设计应如同签订一份明确的合同。避免直接返回不确定的List或在列表中混杂多种类型的数据，是构建健壮、可维护和可扩展API的关键。


核心原则：


    

  • 
API即契约： 确保API的响应结构是明确、可预测和类型安全的。
    • 

  • 
封装胜于暴露： 当需要返回一个列表以及与该列表相关的元数据时，始终将其封装在一个自定义的数据传输对象（DTO）中。
    • 

  • 
拥抱类型安全： 利用语言的类型系统来提供编译时检查和运行时便利，减少客户端的错误处理负担。
    • 

  • 
为未来扩展做准备： 自定义对象结构天然具备更好的扩展性，能够平滑地应对未来可能的需求变化。
    • 



通过遵循这些最佳实践，开发者可以构建出更专业、更易用、更具生命力的API。
 
	









            
            

              
              
            

          
        
      
      


  
赣ICP备2024031479号