java - 选择哪个选项来设计此 API 端点

Question

假设我们有一个 API 端点:/cars/1，它返回有关汽车的基本信息(id、名称、描述)。

但我们也可以请求 GET/cars/1?info=extra，这也将返回有关汽车的额外信息(价格、库存)。这些额外信息作为另一个表存储在我们的数据库中，该表与汽车具有一对一的关系。

如果有帮助的话，我们的后端是 Java Spring Boot 应用程序。

返回数据的方法有很多种。您是否会在两个请求中返回相同的对象，并在 ?info=extra 请求中将相应的额外参数设置为 null？或者您会为每个请求返回不同的对象吗？

对我来说，在请求“基本”信息时返回所有空值的优点是使用相同的类来映射两个请求，只需更改 JPA 存储库中的 @Query，从而更易于维护。

返回所有空值也有一个缺点，即返回许多用户甚至没有请求的无用值。它还使 API 更难以阅读(有人可能认为所有这些值实际上都是 null，但实际上可能不是)。说到类，我们将有一个 MappedSuperClass Car 和另外两个类 CarBasic 和 CarExtra，它们都扩展了 Car，每个类都有相应的 getter 来创建输出 JSON。

选项 1:

/汽车/1

{
    id: 1,
    name: "Honda Civic",
    description: "The best car of Honda"
}

/cars/1?info=extra

{
    id: 1,
    name: "Honda Civic",
    description: "The best car of Honda",
    extraInfo: {
    {
        price: 25000,
        stock: 24
    }
}

选项 2:

/汽车/1

{
    id: 1,
    name: "Honda Civic",
    description: "The best car of Honda",
    extraInfo: null
}

/cars/1?info=extra

{
    id: 1,
    name: "Honda Civic",
    description: "The best car of Honda",
    extraInfo: {
    {
        price: 25000,
        stock: 24
    }
}

选项 3:

/汽车/1

{
    id: 1,
    name: "Honda Civic",
    description: "The best car of Honda"
}

/cars/1?info=extra

{
    id: 1,
    name: "Honda Civic",
    description: "The best car of Honda",
    price: 25000,
    stock: 24
}

你觉得怎么样？

Answer 1

虽然这并不是一个 StackOverflow 类型的问题，但仍然是一个非常有趣的问题。

我个人更喜欢选项 3。

就代码而言，您甚至可以使用带有额外字段的模型来扩展普通的 Car 类。