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

目前,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夜景灯火阑珊,不觉中渲染出我的孤寂。大周末的,是时候回家陪陪孩子做点家务了。


最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 158,560评论 4 361
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 67,104评论 1 291
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 108,297评论 0 243
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 43,869评论 0 204
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 52,275评论 3 287
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 40,563评论 1 216
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 31,833评论 2 312
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 30,543评论 0 197
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 34,245评论 1 241
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 30,512评论 2 244
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 32,011评论 1 258
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 28,359评论 2 253
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 33,006评论 3 235
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 26,062评论 0 8
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 26,825评论 0 194
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 35,590评论 2 273
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 35,501评论 2 268

推荐阅读更多精彩内容

  • 1、引言 数据库设计过程中表、字段等的命名规范也算是设计规范的一部分,不过设计规范更多的是为了确保数据库设计的合理...
    SnowflakeCloud阅读 40,637评论 0 48
  • Spring Cloud为开发人员提供了快速构建分布式系统中一些常见模式的工具(例如配置管理,服务发现,断路器,智...
    卡卡罗2017阅读 134,099评论 18 139
  • 1. 简介 1.1 什么是 MyBatis ? MyBatis 是支持定制化 SQL、存储过程以及高级映射的优秀的...
    笨鸟慢飞阅读 5,281评论 0 4
  • 周杰伦是一个时代的象征,作为90年这一代人,我们真的是听着杰伦的歌长大的呢~ 现在,立刻,这一秒,请你唱出周杰伦的...
    王婉妮阅读 610评论 0 0
  • 你是否经常陷入这样一个怪圈,你在一天的时间内,不管有空没空,都会不断的刷微博刷朋友圈,不停的点开工作群里时不时跳出...
    桐花与猫阅读 4,390评论 37 200