常见的API错误以及如何避免它们 - LogRocket Blog

19-09-11 banq
              

本文中的建议适用于任何API。但是,当应用程序使用动态语言(如JavaScript)编写而不是更静态的语言(如Java)时,我们会考虑更容易遇到的一些问题。

Node.js有时被称为胶水,它将系统导向的体系结构保持在一起,因为它易于与多个后端服务通信并将结果拼接在一起。出于这些原因,我们将看到的示例将使用Node.js风格的JavaScript编写。

对数据很吝啬

当遇到要在API响应中使用的对象时,很容易传递对象的每个属性。实际上,通常更容易发送未经修改的整个对象,而不是整个对象的属性进行一些添加或删除。

想想您从社交媒体平台获得用户的情况。也许在您的应用程序中,该对象类似于以下内容:

{
  "id": 10,
  "name": "Thomas Hunter II",
  "username": "tlhunter",
  "friend_count": 1337,
  "avatar": "https://example.org/tlhunter.jpg",
  "updated": "2018-12-24T21:13:22.933Z",
  "hometown": "Ann Arbor, MI"
}

假设是您自己正在构建API,并且您已经被特别要求提供用户的标识符,用户名,人类可读的名称以及他们的头像。但是,将完整对象提供给API的使用者非常简单,因为可以简单地执行以下操作:

res.send(user);

但是,按照需求和要求却应该发送如下用户属性:

res.send({
  id: user.id,
  name: user.name,
  username: user.username,
  avatar: user.avatar
});

应始终关注业务需求并确定可满足这些要求的绝对最小数据量。API的消费者真正需要什么?

这是编程中的一个重要概念,它甚至有一个名字:你不需要它(YAGNI)。总是对你发送的数据感到吝啬。可以通过使用定义良好的对象表示数据来实现此问题的解决方案以及其他问题。

将上游数据表示为明确定义的领对象

通过将数据表示为明确定义的业务对象,当我们从上游服务请求数据并将其转换为对象时,我们现在已经创建了一个POJO(Plain Old JavaScript Object)。这样的对象既方便又有风险。

相反,让我们将这些对象表示为DO(领域对象)。这些领域对象将要求我们将一些规则应用于我们从上游检索过来的数据,它们还可检查存在的属性是否属于正确类型。

使用向前兼容的属性命名

在API响应中命名对象的属性时,请确保以这样的方式命名它们,使它们与将来计划进行的任何更新都向前兼容。

规范化概念和属性

使用积极的,“快乐”的名字

负面的示例如disable_notification,应该使用正面enable_notification,原因是作为开发人员很容易被双重否定所迷惑:如unavailable: false, 而正面available: true很容易理解。

这里有一些负面词语尽量避免:broken, taken, secret, debt,它们相应正面词语是: functional, free, public, credit

public是积极的,private是负面的。

应用鲁棒性原则

确保遵循可靠性原则,无论它适用于您的API。引自维基百科,这个原则是:

保守你的所作所为,要接受别人的自由。(严以律己 宽以待人)

这个原则最明显的应用是关于HTTP头。根据HTTP RFC,标题应该包含单词的第一个字母的大写字符,并用连字符分隔。但是,在技术上可以是任何大写字母并且技术上仍然可以接受,例如。Content-Typecontent-TYPE

鲁棒性原则的前半部分是保守的。这意味着您应始终使用首选标头大小写响应客户端。您无法确切地知道您的API的使用者能够正确读取格式良好且格式化的标题。并且API应该可以被尽可能多的不同消费者使用。

这个原则的后半部分是你从别人那里接受的自由。这意味着,对于HTTP标头,您应该将每个传入标头规范化为一致的格式,以便您可以读取预期值而不管大小写。

测试所有错误条件

如果可能,创建接受测试,调用各种错误并测试响应。

退后一步

在企业环境中,很容易进入允许复杂客户端库处理与服务的所有通信的模式。同样,很容易允许复杂的服务库将对象的所有序列化处理成客户端可消费的格式。有了这么多的抽象,公司可能会达到这样的程度,即没有人知道通过线路发送的数据是什么样的。

当这些情况发生时,通过网络传输的数据量可能会失控。转移个人身份信息(PII)的风险也会增加。并且,如果您的API需要被外部世界消费,这可能会导致大量痛苦的重构以进行清理。

时不时地“退后一步”很重要。停止使用组织事实上的工具来查看API。相反,使用通用的现成产品来查看API。使用HTTP API时,实现此目的的一个此类产品是Postman。此工具对于查看原始HTTP有效负载非常有用。它甚至还有一个方便的界面来生成请求和解析响应。

 

              

1