接口设计小结

接口设计规范

1、接口命名：

命名要有意义，原则上看接口名就能理解接口的作用，且接口涉及的动作包含到接口命名中
getUser 表示获取用户信息，属于查询操作
addUser表示新增一个用户，数据插入操作
如果命名为getUser的接口，实际上有插入操作，说明这个接口命名是失败的

2、事务处理：

涉及多个增删改操作的组合，必须增加事务处理
只有单个增删改操作，或者只有查询操作，则不用事务处理

3、 渠道/调用方设计：

重要的接口要加入渠道统计/IP来源/调用方来源/用户ID等。比如注册接口，增加参数channel，并记录到日志或数据库，可方便统计用户的注册来源

4、日志打印：

增删改、关系绑定这种比较重要的接口，建议打上参数日志、事务日志。尤其是涉及用户的操作，系统又有进行校验的，容易发生歧义的，都要打上日志。比如邀请好友，把邀请码打到日志中，这样用户出现邀请失败的问题时，查看当时用户传递的邀请码，就很容易定义用户的操作是否正常；发送短信操作，把手机打印到日志中，可方便统计短信发送信息

5、 接口实现：

A、 不要出现magic number，比如if(type==1) XXX; else if(type==2) YYY; else ZZZ;
B、 增删改涉及事务处理的，考虑并发处理。
常用的，对整个接口加synchronized，可以处理单体服务的并发；对表记录加锁，可以处理分布式服务的并发
C、 校验在前，实现在后。遍历各个参数，校验临界条件，等到正常条件时，再进行逻辑处理
D、 异常处理：尽量处理可控的异常（如null值处理），不可控的异常可不管（定位错误时通过栈信息也容易知道错误的根源）

6、 分布式事务不好处理，尽量避免用到