如何设计出用户喜爱的API

原文：User experience design for APIs
作者：Francois Chollet
译者：夜风轻扬

译者注：什么样的API才是好的API？如何开发出用户乐于使用的API？请阅读下文。

编写代码不仅仅是人与电脑间的事。代码也不只和电脑有关；还会影响到用户。程序员编写的代码会被其他程序员阅读、使用和维护。程序员只有使用顺手的工具，心情舒畅的时候才会写出更好更多的代码。不幸的是，他们常常会被难用的工具、晦涩的错误消息和不知所云的库弄的心烦意乱。（不好的）工具会给程序员带来痛苦，特别是在复杂的软件工程中。

用户体验（UX）应该在应用程序接口（API）设计中处于核心地位。一个设计优秀的API，会让复杂的任务变得简单，更会减少麻烦的产生。所以API用户体验设计完全不是多余的。为什么在程序员中缺少设计文化呢？

当程序员在电脑前编写代码的时候，用户对于他们来说是个抽象的遥远的概念。只有当他们和用户坐在一起，看到用户痛苦的使用自己编写的API时，才会意识到用户体验的重要性。现在是要重视用户体验的时候了，尽管大部分程序员还从来没做到。

另外一个问题是所谓的“聪明程序员综合征”。程序员会以为最终用户和他们一样拥有丰富的背景知识。但是，事实上，最终用户对API及其实现知之甚少。而且，聪明的程序员还会把问题搞得过于复杂，因为他们自己善于处理复杂问题。但是不够聪明或者是缺乏耐心的人呢？这就决定了软件不能太过复杂–超过特定的难度，就难以使用，用户就会排斥使用转而寻求更为清晰的方法。但是聪明的、有耐心的人呢？他们可以应付复杂事务，他们会不断的构造科学怪物。结果是生产出最差类型的API。

最后一个问题是一些程序员刻意使用敌视用户（user-hostile ）的工具，因为他们将这种超级困难视为一种荣耀，而把设计贴心的工具看成是“给菜鸟用的”。在深度学习社区中这种态度尤为突出，在那里追求时髦和浮华。但是，这种自讨苦吃的态度最后只会弄巧成拙。从长远来看，良好的设计会占上风，因为好的设计会更有效率和影响力，会比敌视用户的负设计（undesign）更受欢迎。好的设计是有传染性的。

和大多事务类似，API设计并不复杂，只要遵循一些原则。而这些原则都源于一个基本准则：应该关心用户。所有的用户，而不只是其中聪明的人，不只是专家。任何时候都要重视用户。是的，包括那些首次使用的懵懵懂懂的用户，他们只有有限的背景知识，耐心也很有限。每一个设计理念都要从用户出发。

对于API设计，这里有三个原则。

1-谨慎设计完整的用户流程

大多数的API开发者只关注单一的方法，而忽略了整体的流程。他们让用户自己摸索出完整的流程。由此产生的用户体验通常是一条长串的技巧，围绕着在各个方法层面上看不见的技术限制。

为了避免此种情况发生，一开始就要列出API使用的最常见流程。这些场景是大多数人都关心的。最好自己演练一下，并做笔记。更好的方式：观察新用户的使用，找出不足之处，并进行改进。特别的：
- 流程应该紧密映射到用户关心的特定领域概念
如果设计的API用于烹饪汉堡，很可能是诸如“肉饼”、“奶酪”、“圆面包”、“烧烤”等对象。如果设计深度学习API，核心的数据结构以及方法，应该映射到该领域用户所熟悉的概念：模型/网络、层、启动、优化器、损耗等。

• 理想状态下，API元素不用处理实现细节。
  普通用户不会在意诸如”primary_frame_fn”, “defaultGradeLevel”, “graph_hook”, “shardedVariableFactory”, 或者 “hash_scope”,因为这些不是问题域中的概念，它们是内部实现中涉及的概念。

• 谨慎设计用户的上手过程
  完全的新手如何利用工具来发现解决问题的最好方法？答案就是确保上手的材料是用户所关心的：不要教新手API是如何实现的，而是要告诉他们如何使用API来解决他们自己的问题。

2-减少用户的认知负担

在设计的完整流程中，应该减少用户理解和记忆的负担。用户的负担越少，在解决实际问题时就会使用的越多。—而不是花费精力去学习如何使用。特别的：

• 使用一致的命名和编码模式
  API的命名约定在内部应该是一致的（如果通常用num_ 前缀来表示数值，就不要在一些场合改用n_），同时也要与外部广泛认可的标准保持一致。例如，如果设计用于在Python中进行数值计算的API，就不能明显的与广泛使用的Numpy API有冲突。敌视用户的API可能在Numpy使用keepdims的场景下使用 keepdim，也可能在Numpy使用axis的场景下使用dim，等等。设计糟糕的API可能对于同一个概念，随意使用axis、dim、dims、axes或者axis-i、dim-i等等。

• 尽可能少的引入新概念
  新概念不仅是额外的数据结构，有一些新的方法和属性需要学习。而是需要更多的心智模型来掌握。最好只需要一种单一的通用心智模型（在Keras中是层/模型结构）。在流程中要必须避免使用超过2-3个心智模型。

• 在类/函数的数量和参数间取得平衡
  每一用户操作的不同类/函数都会带来繁重的认知负担，增加参数同样如此。–谁都不想一个类的构造函数中有35个变量。可以通过数据结构的模块化和组合来达到这样的平衡。

• 尽可能的自动化操作
  尽量减少流程中的用户操作。在用户编写的代码中找出经常重复的部分，并提供公用程序将其抽象化。例如，在一个深度学习API中，应该提供自动的形推论（shape inference）方法，而不是要用户去费力在所有层来计算期望的结果。

• 要有清晰的文档，并附有大量的实例
  与用户交流如何解决问题的最好方式，不是简单的推论解决方案，而是把解决方案展示出来。对于API的每一个特点，都要有简明和可读的代码实例。

检验一个API是否设计优秀可以通过如下方法：
如果一个新用户在第一天使用该流程解决问题（借助文档或者教学），第二天在稍微不同的环境中，解决相同的问题时，他们不查看文档是否还能按流程进行？他们能否一次就记住流程？设计优秀的API中大部分的流程的认知负担非常小，简直可以过目不忘。
这个方法提供一种区分API好坏的方法，就是通过记录普通用户掌握某个流程过程查找文档的次数。最差的是那些经过大量学习还总记不住的流程。

3-给用户提供有帮助的反馈

优秀的设计是交互的。好的API在使用时很少会依赖文档和教学–只简单的按照直觉来尝试并根据API的提示来操作。特别的：

• 尽早捕捉用户的和可预见的常见错误
  尽可能的进行用户输入验证。跟踪用户常犯的错误，或者是通过简化API、增加错误的提示信息来解决这些错误，或者是在文档中增加“解决常见错误”内容。

• 为用户提供答疑的场合
  你有什么需要解决的问题么？

• 为用户的错误提供详细的反馈信息
  一个完整的错误信息应该回答：在哪个环境中？发生了什么，软件期望的结果是什么?用户如何修复？这些应该是有语境的、有内容的和可操作的。为用户提供解决问题方法的错误信息得分，让用户不知所云的错误信息应该减分。

例如：
- 在Python中，下面就是个极坏的错误信息：

AssertionError: '1 != 3'

（一般经常使用ValueError而避免使用assert）
- 同样的坏信息还有：

ValueError: 'Invalid target shape (600, 1).'

• 下面的要好一些，但是依然不够充分，因为没有告知用户通过了什么，也为告知如何修复：

ValueError: 'categorical_crossentropy requires target.shape[1] == classes'

下面是一个好的例子，提示什么通过了，期望是什么以及如何修复问题：

ValueError: '''You are passing a target array of shape (600, 1) while using as loss `categorical_crossentropy`.`categorical_crossentropy` expects targets to be binary matrices (1s and 0s) of shape (samples, classes).If your targets are integer classes, you can convert them to the expected format via:--from keras.utils import to_categoricaly_binary = to_categorical(y_int)--Alternatively, you can use the loss function `sparse_categorical_crossentropy` instead, which does expect integer targets.'''

好的错误信息会提高效率，也会抚慰用户的情绪。
link

结论

这些都是相当简单的原则，遵循这些原则会有助于开发出用户乐于使用的API。相应的，会有更多的人开始使用你的软件，这会有助于提高在领域中的影响。

要牢记：软件是为人而不是为机器服务的。任何时候都要把用户放在心中。

---

PS：推荐一个容器技术线上直播，讲师来自腾讯、华为、思科、58同城、蘑菇街、当当等6位一线专家，议题涵盖容器云、微服务、servicemesh等最新实践，欢迎报名参加