SOAP API 参数最佳实践

Question

我有一组肥皂网络服务，它们与同一架构中的应用程序紧密耦合，但我还需要它作为 API 以供其他应用程序挂钩。

目前，服务使用这样的参数（和方法）结构

Entity GetEntity(int entityId) 实体 GetEntityByName(string entityName) ....等等。

在创建的情况下，我使用： void CreateEntity（实体实体）

我想知道这样做会更好吗：

EntityResponse GetEntity(EntityRequest requestObj) .....

在 requestObj 中，我有 id、entityName 以及根据用户提供的内容，我可以执行任一功能。

对于创建它会是：

CreateEntityResponse CreateEntity(CreateEntityRequest requestObj).

我的想法是，通过这样做，API 可以在内部进行更改...添加新参数等，而不会立即破坏已经完成的任何集成。

Answer 1

我认为您可能需要考虑几个设计原则：

1) 数据库实体与数据传输对象 DTO

看起来那些实体直接来自数据库映射？只是将您的实体公开为 API，基本上是一个花哨的 SQL 查询浏览器。这不一定是错误的，但如果您在 API 中公开 DTO，您将获得更好的解耦。 DTO 可能比实体更具未来性，并且更通用。

2) SOAP 与 REST

如果您想最大限度地进行未来验证，您可能需要考虑 REST。使用 REST 规范，您可以在以后扩展 API 的更多选项。 例如，如果您查看像 Facebook 这样的 API，它们纯粹传递参数，然后您会收到返回的参数的键值映射。非常通用。 在 SOAP 中，您总是会预先定义所有这些最终属性。您基本上需要引入占位符等。 SOAP 是一个很好的合约协议，并且具有代码生成工具更新和更多等优点，这当然是有原因的。但是使用 REST，您可以更加灵活，同时失去 SOAP 中的一些优点。

这也是一本很好的读物： https://www.mulesoft.com/lp/whitepaper/api/secrets-great-api 或者一般来说，Mule 的 RAML 设计规范在设计 REST API 时是一个非常强大的工具。