API开发/运维经验1

对于维护API的经验，推荐《软件框架设计的艺术》这本书，无论是webService还是Rest还是其他什么，都很有帮助。

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

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

[b]1.参数命名规范[/b]

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

由此得出经验：参数规范化很重要，但对于以被使用的通用参数名，还是遵从以前的规则。
顺便附带第二个经验，开发根本不会细看接口文档……啊啊啊！！！！（虽然我也有这毛病，但我还是要鄙视）

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

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