服务API设计 之 API设计原则

你是否也感同身受？

1. 对接XX业务时，XX业务具备的功能和API全靠跑业务负责人那反复逐个询问、确认。用哪个API；怎么用；有没有限制；等等
2. 各个业务间，甚至同一业务内，API风格不统一。
   • API命名：按自然语义全翻译的；按属性角度定义的；按操作角度定义的；动宾、非动宾的；复数、非复数的；等等
   • API入参：带Map的；相同语义字段名称不一样；
   • API出参：有包装Resoponse的；直接返回结果数据的；相同数据，返回格式和字段名称有差别的；
   • 错误信息：直接返回中文提示的；返回提示信息编码的；返回异常类型的；等等
3. XX业务API性能方面未知。
4. 随着业务的演进，开放的API持续在增加，但类同的很多

API编码规范迫在眉睫

---

优秀API的特质

1. 自解释
   • 从API本身一眼就能看懂API是干什么的，支持的用法，适用的场景，异常的处理等
2. 易学习
   • 有完善的文档，以及提供尽可能多的示例和可copy－paste的代码。
3. 易使用
   • 功能强大，但使用简单。不增加调用方的使用成本（例如要求业务方用API时需要额外的配置和依赖），不暴露复杂的细节、冗长的使用流程给