你是否也感同身受?
- 对接XX业务时,XX业务具备的功能和API全靠跑业务负责人那反复逐个询问、确认。用哪个API;怎么用;有没有限制;等等
- 各个业务间,甚至同一业务内,API风格不统一。
- API命名:按自然语义全翻译的;按属性角度定义的;按操作角度定义的;动宾、非动宾的;复数、非复数的;等等
- API入参:带Map的;相同语义字段名称不一样;
- API出参:有包装Resoponse的;直接返回结果数据的;相同数据,返回格式和字段名称有差别的;
- 错误信息:直接返回中文提示的;返回提示信息编码的;返回异常类型的;等等
- XX业务API性能方面未知。
- 随着业务的演进,开放的API持续在增加,但类同的很多
API编码规范迫在眉睫
优秀API的特质
- 自解释
- 从API本身一眼就能看懂API是干什么的,支持的用法,适用的场景,异常的处理等
- 易学习
- 有完善的文档,以及提供尽可能多的示例和可copy-paste的代码。
- 易使用
- 功能强大,但使用简单。不增加调用方的使用成本(例如要求业务方用API时需要额外的配置和依赖),不暴露复杂的细节、冗长的使用流程给