API开发/运维经验1

◇◆丶佛笑我妖孽 提交于 2021-02-19 10:51:46
对于维护API的经验,推荐《软件框架设计的艺术》这本书,无论是webService还是Rest还是其他什么,都很有帮助。

不过这书在概念上还是离平时工作太远,知识很精华,但和我的实际工作并不接轨,所以逐渐萌生“把我自己开发/运维API的一些经验整理出来,写一篇大的博文”这样的想法

不过最近又忙且病,所以一条条慢慢往外挤……

1. 参数命名规范

我曾经接手一个已经运行一段时间的API系统,它对外暴露的接口的参数,没有采用通用的第一个后单词首字母的规范
我在新开发接口时,决定采用新的规范;
但问题来了,接口的以前使用者,在调用新接口时,总也调不通,原因就是,以前用来标记访问来源的参数visitsystem,被我不经意间改成了visit**S**ystem,一字之差,接口在验证时找不到访问来源,于是不允许访问;

由此得出经验:参数规范化很重要,但对于以被使用的通用参数名,还是遵从以前的规则。
因为开发最不喜欢细看接口文档……啊啊啊!!!!(虽然我也有这毛病,但我还是要鄙视)

2. 接口返回值 对于错误信息的返回,非常重要。调用接口的系统,会根据错误信息,提示用户进行对应操作。 我负责这个系统,最开始是用数字(errcode),代表错误信息;但用数字用来标示每个错误,则粒度太细,用来标示一类错误,则对信息的提示又不足; 比如对于系统异常,和参数错误,是同级别的错误类型,和某个具体参数的具体错误,如email不符合规范,就不是同级别; 因而增加errMsg,填写具体错误信息(中文) 当然,系统架构上, 最好有对应的字典表,标记每个errcode对应哪类错误;

这种方式的优缺点如下: 优点:错误信息规范化,接口调用者可方便查询; 缺点:增加开发者工作量和运维量。

标签
易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!