.Net Core Rest API 请求/响应最佳实践

Question

我需要一些关于如何最好地构建我的Rest API请求和响应的建议。

我主要尝试将自己限制在一个资源的CRUD操作上，并且我使用一个对象：例如，如果资源是“书籍”，则控制器中会出现以下操作

• [HttpPost("books")] Book Create(Book book)
• [HttpGet("books")] Book Get(int id)

这相对来说比较简单。

现在，对于一个更复杂的示例，我需要接收一个与我的资源不同的复杂对象并返回包含资源和额外数据的对象。例如，对于订单资源，我在控制器中有以下操作：

[HttpPost("/order")] CreateOrderResponse CreateOrder(CreateOrderRequest createOrderRequest)

在这里，我的操作将使用“CreateOrderRequest”对象创建一个订单。然后，我想返回一个“createOrderResponse”对象，其中包含订单以及客户端需要的额外信息。

我不确定这是否是最佳方法，有什么建议吗？

提前感谢您的帮助。

- Rachid

Answer 1

我更喜欢以下选项：

[HttpPost("/order")] CreateOrderResponse CreateOrder(CreateOrderRequest createOrderRequest)

原因在于：

• 通过这种方法，您可以保护公共API免受实现细节的影响。如果将模型暴露给API，那么您无法做出同样的保证。
• 您还可以使验证特定于请求格式。在某些情况下，您可能需要在创建记录时使用模型的一个子集，在编辑数据时使用另一个子集。这种方法也可以处理这种情况。
• 安全性。您要将该Book添加到DbContext并保存吗？还是直接附加并更新？从安全和数据质量的角度来看，这些都可能存在潜在问题。

但是这种方法也有缺点：

• 这种方法非常耗时。如果您正在编写某个学习项目或需要快速实现某个功能，则可能不值得投入时间。而且它会增加复杂性。但是，当您意识到Book对象在所有情况下都不足够时，您可能会发现复杂性。
• 您会觉得有重复代码存在于不同的地方。代码可能看起来相同，但用例实际上是不同的，并且随着时间的推移可能会分叉。此时拥有一个Book参数将成为一种负担。

- CPerson

---

我会将"order"改为"orders"，因为它是一个集合，其中正在添加一个单独的元素。另外，请记住，从RESTful纯粹主义的角度来看，你不应该返回新创建的实体（只返回一个带有资源URI的201状态码）。但在这种情况下，我会坚持使用请求/响应特定的对象，即使它们（显而易见地）存在一些缺点。 - undefined