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,标题应该包含单词的第一个字母的大写字符,并用连字符分隔。但是,在技术上可以是任何大写字母并且技术上仍然可以接受,例如。