在微服务 REST api 调用中返回对象列表是不好的做法吗？

Posted 2023-02-26

【中文标题】在微服务 REST api 调用中返回对象列表是不好的做法吗？

【英文标题】：Is it bad practice to return a list of objects in a microservice REST api call?

【发布时间】：2020-11-20 03:59:25

【问题描述】：

我正在关注 swagger 驱动的 api 开发。 在浏览代码库时，我观察到只要期望返回对象列表，服务就会返回父对象。

给出的原因是“在 api 中返回对象列表是不好的做法”。这个流行的教程很可能是灵感的来源：- https://www.youtube.com/watch?v=Dmvhe2cw-_k 它说“如果服务返回对象而不是列表，则 api 可能会中断”

但是，我不相信这种千篇一律的格言，因为每个 api 合同都以 swagger 的形式记录在案，所有开发人员都必须严格遵循该文件来开发他们的服务和服务调用。

我仍然更喜欢返回一个对象列表而不是返回一个包装对象。专家们有何建议？

非常感谢您提供指向任何文档的链接、最佳实践的开发人员指南。

【问题讨论】：

返回列表完全没问题。在返回对象的视频中，仅当您需要在列表旁边的顶层返回数据时才适用。

API 遵循 Swagger/OpenAPI/... 文档 have hardly anything to do with REST

有（真的）No Best Practices ...所以在这里要求链接到它们的列表是双重错误的。 （这也是题外话。）

【参考方案1】：

如果是“收藏”资源如：

/employees

然后，作为消费者，我希望得到一个项目列表 + 任何分页详细信息（接收有关符合条件的员工总数的一些汇总信息（如果您提供一些查询参数）等也会非常有帮助）

本指南应该可以帮助您更多地了解不同类型的资源https://restfulapi.net/resource-naming/