对于维护API的经验,推荐《软件框架设计的艺术》这本书,无论是webService还是Rest还是其他什么,都很有帮助。
不过这书在概念上还是离平时工作太远,知识很精华,但和我的实际工作并不接轨,所以逐渐萌生“把我自己开发/运维API的一些经验整理出来,写一篇大的博文”这样的想法。
不过最近又忙且病,所以一条条慢慢往外挤……
[b]1.参数命名规范[/b]
我曾经接手一个已经运行一段时间的API系统,它对外暴露的接口的参数,没有采用通用的第一个后单词首字母的规范,例如username;
我在新开发接口时,决定采用新的规范;
但问题来了,接口的以前使用者,在调用新接口时,总也调不通,原因就是,以前用来标记访问来源的参数visitsystem,被我不经意间改成了visit**S**ystem,一字之差,接口在验证时找不到访问来源,于是不允许访问;
由此得出经验:参数规范化很重要,但对于以被使用的通用参数名,还是遵从以前的规则。
顺便附带第二个经验,开发根本不会细看接口文档……啊啊啊!!!!(虽然我也有这毛病,但我还是要鄙视)
[b]2.接口返回值[/b]
对于错误信息的返回,非常重要。调用接口的系统,会根据错误信息,提示用户进行对应操作。
我负责这个系统,最开始是用数字(errcode),代表错误信息;但用数字用来标示每个错误,则粒度太细,用来标示一类错误,则对信息的提示又不足;
比如对于系统异常,和参数错误,是同级别的错误类型,和某个具体参数的具体错误,如email不符合规范,就不是同级别;
因而增加errMsg,填写具体错误信息(中文)
当然,系统架构上, 最好有对应的字典表,标记每个errcode对应哪类错误;
这种方式的优缺点如下:
优点:错误信息规范化,接口调用者可方便查询。
缺点:增加开发者工作量和运维量。
不过这书在概念上还是离平时工作太远,知识很精华,但和我的实际工作并不接轨,所以逐渐萌生“把我自己开发/运维API的一些经验整理出来,写一篇大的博文”这样的想法。
不过最近又忙且病,所以一条条慢慢往外挤……
[b]1.参数命名规范[/b]
我曾经接手一个已经运行一段时间的API系统,它对外暴露的接口的参数,没有采用通用的第一个后单词首字母的规范,例如username;
我在新开发接口时,决定采用新的规范;
但问题来了,接口的以前使用者,在调用新接口时,总也调不通,原因就是,以前用来标记访问来源的参数visitsystem,被我不经意间改成了visit**S**ystem,一字之差,接口在验证时找不到访问来源,于是不允许访问;
由此得出经验:参数规范化很重要,但对于以被使用的通用参数名,还是遵从以前的规则。
顺便附带第二个经验,开发根本不会细看接口文档……啊啊啊!!!!(虽然我也有这毛病,但我还是要鄙视)
[b]2.接口返回值[/b]
对于错误信息的返回,非常重要。调用接口的系统,会根据错误信息,提示用户进行对应操作。
我负责这个系统,最开始是用数字(errcode),代表错误信息;但用数字用来标示每个错误,则粒度太细,用来标示一类错误,则对信息的提示又不足;
比如对于系统异常,和参数错误,是同级别的错误类型,和某个具体参数的具体错误,如email不符合规范,就不是同级别;
因而增加errMsg,填写具体错误信息(中文)
当然,系统架构上, 最好有对应的字典表,标记每个errcode对应哪类错误;
这种方式的优缺点如下:
优点:错误信息规范化,接口调用者可方便查询。
缺点:增加开发者工作量和运维量。