Web API 2 分离请求和响应模型

Question

我们正在使用 .NET WebAPI 开发一些 RESTful API。团队正在尝试做出一个设计决策：我们是否应该始终在 WebAPI 级别分离请求模型和响应模型？

例如，我们有一个暴露客户资源的端点：

GET api/customers/1返回客户信息（CustomerResponse）

POST api/customers 接受客户信息。 （客户请求）

最初，这两个模型之间的所有字段都是相同的，只是响应包含CustomerID，而这不在请求中。

我知道，将这两个模型分开将使我们受益，因为它们可以隔离请求/响应，因为它们将来可能会有所不同。并且验证仅在请求模型上进行。但是，它也带来了开销，因为我们现在需要维护两个模型。

我在那里找不到任何标准。只是想看看有没有推荐的最佳做法。

Answer 1

我发现将两者分开是最容易的。 如前所述，两者可能会随着时间的推移而分道扬镳。例如，发布一个新资源可能没有 id，但响应对象有。

通过分离，您可以：

1. 利用 API 框架模型验证（即轻松注释哪些字段是必需的和可选的）。这将返回一个错误，指定缺少哪个字段。

2. 利用工具（例如我最喜欢的工具之一，Swashbuckle https://github.com/domaindrivendev/Swashbuckle）从您的路线和模型中自动生成文档。 如果请求和响应字段被捆绑到同一个模型中，文档将看起来不太好。