支付中心接口设计之参数命名

96
buguge
2017.06.10 21:26* 字数 1111

目前,java版支付中心处在研发阶段。下午,特有钻研精神的云龙同学饶有兴趣的问我“战哥,你觉得表字段用哪种命名方式比较好呢?”

所用的db是mysql,他是想征求一下我的看法,是用驼峰式命名还是小写加下划线方式。

我直截了当地说用驼峰式。为什么? 我认为,像java语言或.net语言,实体类的属性一般是遵从驼峰式命名的(稍有不同的是java一般首字母小写,而.net是首字母大写)。我们的程序里的数据访问层一般均采用ORM框架。如果表字段是小写字母+下划线,那么,相应的POJO/POCO实体类的属性也会是小写字母+下划线,这样,违背了驼峰式命名规范,有违代码的整洁度。

接着,如我所期,云龙问“那你支付中心对外的api接口参数为什么用小写+下划线的方式呢?”

我答道,对外提供的接口,

  • 如果用驼峰式。 首先,我们用word编写接口说明文档时,在参数表格列里输入参数名后,如果按tab键,则word默认首字母是大写的。而如果恰好我们的首字母是小写时,如果我们在编写时忽略了这个细节,这就会给对接者带来疑惑(产品设计上有一条重要的原则:Don't Make Me Think,同样适用于软件设计); 更甚之,如果签名规则要求的签名原串包括参数名时,那么,因字母大小写所致的验签失败往往不那么容易排查出来,进而造成双方的“不必要”沟通。
  • 如果用小写+下划线。 首先,这种方式规避了上面驼峰式命名的不足。 其次,考虑到商户对接存在不同的编程语言如php/java/.net,跨语言程序员之间也都会认可。

云龙和伟业听后表示赞同。
我解释,我们在接口开发和商户对接支持这些事情上踩过的坑太多了,逐渐的就要考虑这些细节。


api接口文档
letter-case

【另面观】
其实,也许是从事IT项目管理的职业病,我喜欢考虑项目成本,系统设计方面,始终坚持通过合理设计规避不必要的沟通和互撕。

像上面支付接口的参数,如果不考虑命名形式,用驼峰式,势必会增加后续甲乙双方联调过程中的沟通成本。那么,倘若我们改为小写加下划线的形式,就会规避这些真的是不必要的沟通。 ——这就是软件意识。
有些程序员一天的工作就是商户接口对接联调支持。有些领导看到下属员工一天忙碌的对接,认为其工作很饱满。

【延伸】
我也饶有兴趣,忽然在想,我们支付中心对外提供的这种接口在技术层面叫作什么呢? api是应用程序接口,即程序包里的公开的方法及对这些方法的说明。而这种通过http发布的接口,是什么呢? rpc接口?rmi接口?webapi? 我也去找云龙和伟业探讨,他们说就是接口嘛,笑我太爱琢磨了。
我常常就这样较真儿,当然,我也不认为这种较真儿是什么缺点。于是,为了一个细节,我会去查看好些技术帖子和blog。于是,我也再了解了一下rpc、web Service、web api。

今天周六,加班的同事早已回家。我从洗手间回到工位,办公区周围的昏黑,窗外三环上疾驰的车辆,CBD夜景灯火阑珊,不觉中渲染出我的孤寂。大周末的,是时候回家陪陪孩子做点家务了。


techArt
Web note ad 1