支付宝什么时候能重新设计 API?

By Rei on 04 Jun 2014

支付宝的 API 非常糟糕。也许在国内提供 API 的服务之中,支付宝还不是最糟糕的,但因为它占领支付这一重要领域的统治地位,让我不得不跟它打交道,所以我必须写点什么。

为了表明我不是纯粹的抱怨者,我要指出我维护着一个 Ruby 语言的 alipay 程序库。这个库质量也不咋的,因为我没有利益驱动投入更多精力为一家商业公司擦屁股,但我相信这已经帮助一部分人节省很多时间了。

从支付宝的 API 质量可以看出,他们公司内部没人为此真正负责。似乎自公司创始之初搭建了这些 API 原型后,就再也没人改动过,并且谁也不敢动。如果觉得反正用着没问题,支付宝还是份额第一,我只能期望国内另一个巨头公司多给它点压力了。

话不多说了,来看看支付宝 API 哪些地方很糟糕。

问题

代码风格不统一

Alipay 的每个接口都像是独立的部门写出来的,每个接口都不一样。看这三个接口,命名规则是什么?

create_partner_trade_by_buyer # 担保交易
create_direct_pay_by_user     # 即时到帐
trade_create_by_buyer         # 标准双接口

设计者肯定很喜欢探索名词组合的可能性。

另外,消息认证接口,Web 验证的参数是:

notify_id=NOTIFY_ID

Wap 验证的参数却是:

<notify_id>NOTIFY_ID</notify_id>

为什么这两个接口不一样!要补充的是,Wap 验证的其他参数都是 form 参数,唯独这个 notify_id 要放在 XML 里面,设计的时候怎么没觉得别扭?

还有,交易接口的物流类型,在文档中没有 DIRECT(无需物流)这一类型,但在发货接口的文档却有。于是我试着给交易接口提交了 DIRECT 类型,结果能用,这又是什么问题?(千万不要发现这是 Bug 然后给移除了!!!)

支付宝接口中充满了这些不符合直觉的行为,非常干扰开发调试,我第一次调试几乎花了一周时间才通过,过程只能用痛苦来形容。

没有 SDK

如果支付宝提供了 SDK 的话,可能我的抱怨就少很多。当然,支付宝也不一定提供我需要的 Ruby SDK,我还是得自己写。但如果他们内部进行了 SDK 的开发,估计就能提前发现很多问题,也不会发布这么让人痛苦的 API 了。

现在支付宝的技术支持里面是有 Java/.Net/PHP 的开发包,但这个开发包里面提供的是 demo 而不是 SDK。打开任意一个源码文件,你会看到以下注释:

/**
* 功能:支付宝确认发货接口接口调试入口页面
* 版本:3.3
* 日期:2012-07-23
* 说明:
* 以下代码只是为了方便商户测试而提供的样例代码,商户可以根据自己网站的需要,按照技术文档编写,并非一定要使用该代码。
*/

什么叫“并非一定要使用该代码”,开发者下载开发包就是想直接用的好不好。因为这个 demo 本身就抱着“给你参考而已,你最好自己写哦”的心态完成的,所以只有程序注释,没有使用文档。所以得把它所有代码看完,然后评估哪个部分能用哪个部分要自己写。

PDF 文档

也许 PDF 会给人一种虚幻的正规、可靠的感觉,但用 PDF 作为唯一的程序文档真不是一个好主意。PDF 给人一种眼看手勿动的压迫感,而且我也怀疑这种压迫感对支付宝内部开发者也一样的:什么?你要更新文档?你知道这有多严重么?

开发者已经习惯了遇到问题,Google 一下,进入官方文档。支付宝的接口文档放在一个压缩包里,无法索引,也无法通过搜索引擎搜到有效内容。我所用的 PDF 阅读器功能已经很完善,但 PDF 的阅读体验就是不好。

那么该用什么载体发布文档?很明显是——网页。我想不出还有哪个互联网服务是用 PDF 来发布文档的,如果你知道也不用告诉我,多半我不会感兴趣。

补充一点,国内服务的 API 网页文档普遍排版很乱,编写文档的同时请安排网页设计师参与。

沙盒测试

担保交易等 Web 接口没有提供沙盒环境,我留意到 AlipayInside 是有沙盒支持的。很明显,这又是两个部门各搞各的。我也搞不清楚这个 AlipayInside 是干啥的,为什么 Alipay 有这么多不同的接口。

不管如何,对于支付这种需要频繁线上调试的接口,务必添加沙盒环境。

移动优化

支付宝似乎为了进入移动支付市场,新增了很多移动支付接口,但为什么不优化原有的 Web 接口对移动的适应性?

在支付宝页面使用话费充值的时候,有一个“手机付款”的选项,但是在 Web 支付就没有,加上这个按钮不就可以增加手机端的使用率了吗?

alt
请给 Web 接口也加上手机付款的按钮

还有不知道有没有人留意到,即时到帐接口在未登录状态是有个二维码支付的,但是登录之后就没有了,真是分裂。

国际化支持

也许这个问题言之过早了,国内的企业普遍没想过要走出去。但既然阿里巴巴已经计划赴美上市,以后也应该提供英文界面和英文文档。我做了那个 Ruby 库之后,发现我还要义务做英文客服

好的例子

要想知道好的 API 例子,建议看看国外同类服务是怎么做的:

看看这些 API 和文档设计,使用他们的 API 就是一种享受。没错,支付宝这种规模的服务要重整是不容易的,但这是他们自己积累的技术债。现在支付宝乱七八糟的接口根本让人看不懂,让人怀疑他们真的想夺取下一个十年的支付领导地位吗?

好了,抱怨完了,该用的还是得用的,我不奢望这篇牢骚能改变什么。反正我也痛苦过了,网站运行也没问题。我只能在心里小小的盼望,将来会有优秀的支付服务出现。