{End Bracket} : 完美的 API 设计

项目
10/14/2015

{End Bracket}

完美的 API 设计

James Waletzky

为什么很好的应用程序编程接口 (API) 设计如此困难？只引发对它们的一起具有几个基本的方法的几个类，并调用它来完成。

如果您不介意 cursing 在其他开发人员可以执行此，），并引用您为一个反模式的 API。如何可以避免此问题？旨在与 API 设计完美的。是，完美。

设计 API 与类似设计用户界面。都为应用程序和首先与用户（或开发人员）交互的入口点。与其竞争对手，结合图片最喜欢的消费电子设备。我是我喜爱的 TiVo 数字视频录像机。使 TiVo UI 很好？

用法是简单
误用很难
TiVo 还会有一件事情
它不执行任何意外操作
它具有永远不会崩溃多年的使用
操作 / 任务是直观且易于发现
在用户界面是一致、完美完美，或接近于

相同的原则包含 true API 设计。让我们从 COM 世界上我最喜欢的 API 反模式之一上进行选择： IOleCommandTarget::Exec。此 API 通常用于启用某种类型的对象和位于在相互发送命令的容器。

示例实现是与其容器，以修改菜单项和工具栏通信的 COM 控件。此 API 是听写实现应该为通用字符串中的命令接口的稍有更强的类型化版本。

下面是 IOleCommandTarget::Exec API 签名：

HRESULT Exec( 
  const GUID *pguidCmdGroup,  // Pointer to command group
  DWORD nCmdID,               // Identifier of command to execute
  DWORD nCmdExecOpt,          // Options for executing the command
  VARIANTARG *pvaIn,          // Pointer to input arguments
  VARIANTARG *pvaOut          // Pointer to command output
);

让我们分析只讨论这些原则根据此 API。

直观和可发现是 API？是否的首先看一名开发人员来修改工具栏？可能它并不，除非您有此 API tribal 了解。甚至在搜索 MSDN 文档将结尾受挫。

是其简单？ API 将通常名为五个参数。文档才能完全了解每个参数的使用情况。简单的 API 展示目的和只会将其按对象的该名称，（对于上下文) 和方法的名称的清晰度。

强类型化和难度要误用是 API？否。该变量不强类型，并且执行选项不枚举，但泛型 DWORDs。强类型的参数帮助在编译而不是在运行时发现错误。

是 API 为内聚性? 此函数的实现通常具有许多职责不只是一个。一个 well-named 的 API，用于一个特定目的（例如，AddToolbarButton) 是更为内聚性。可能在执行方法的实现切换的命令 ID，并已根据此条件的不同操作。

是 API 可用？执行难例如，但 API 的实现可能几乎任何操作由于即可它缺乏 cohesion。

是在可靠？著名的设计原则"设计接口"可以帮助实施 testability 对象上。此 API 是本质上是可测试，但要验证的测试案例数量可能由于到它缺乏 cohesion 大。可靠性是风险。

它是否一致？它返回一个 HRESULT，并使用 GUID 标识的信息集，此 API 也有一些一致性。但是，很难判断一致性不知道如何不佳设计对象上接口的其余部分是。

任何人学习使用 IOleCommandTarget::Exec 可能需要有关其用法从对等或简介册的指令。最佳的 API 是简单和文档，不可用，尽管文档可能还需要了解详细信息，如错误处理。

conclusion，您 API 和查看的 API 应为易于使用作为 TiVo。一个高发现，强键入，为内聚性，副作用免费、可靠、一致和完美的 API 轻松开发人员的生活通过提高满意度，和降低支持成本。 Microsoft.NET Framework 中的许多接口都是很好的示例。若要实现所有这些设计提高，目标设计或审阅任何 API 设计时的完美的。

James Waletzky 处于高级开发主管 Windows Mobile 中使用者 Internet 和开发人员经验的团队。除了前导产品开发团队，James 是热衷有关改进在 Microsoft 的工程实践的。

其他资源