第三方接口开发规范

一、前言

       最近公司业务需要希望能够连接东亚银行的接口直接对商家进行转账付款，但由于前期可行性研究的准备工作没有做好，导致在开发进入两周后才发现原先的设计存在重大安全漏洞，不得不停止项目开发。

      接口开发是开发中经常遇到的问题，为避免此类问题再次发生，因而结合本次项目的经验及网上查找到的资料整理出本文，希望能够对以后的第三方接口开发交互提供指导。

二、接口开发流程

1.确定需要哪些接口

    重点是要确定每个接口的具体功能。确保这些接口是必须的，功能相互间没有交叉。

2.接口设计及细节分析

针对每一个接口确定如下事项

a)发送参数名、参数含义、参数数据类型、长度、精度

b)接收参数名、参数含义、参数数据类型、长度、精度

   接口的使用的类型变量尽量通用，特别是对使用此接口的用户一无所知情况下，对方可能是Java，也可能是VB6，也可能是C#，不要使用某种编程语言的特定类型，比较好的一种方式是，参数和返回值都使用string类型，这样基本上的编程语言都能支持。

c)发送信息时的数据格式：xml格式还是json格式

d)网络传输时的编码格式。

  虽然在网络传输时均是以字节的形式进行传输，但不同的编码格式生成的字节是不同的，因而需要对此进行统一。如果双方系统的编码格式不同则在进行数据处理时必须进行转码。例如我们在对接招商银行的接口时，招商银行采用的GBK编码格式，而我们系统采用的是UTF-8编码格式，导致在页面显示招商银行的反馈信息均为乱码。关于乱码转换请见我的另一篇博客（http://www.cnblogs.com/sunzhenchao/archive/2012/12/05/2802658.html）

在确定发送数据时，还需考虑：

对方需要的数据自己系统是否存在，如果存在这些数据的格式是否和对方要求的一致，不一致如何进行处理；

如果不存在，是在自己系统中新增这些数据还是采取什么样的变通措施。

例子：使用东亚银行的接口进行转账时需提供收款方的银行联行号（http://baike.baidu.com/view/3048635.htm），而我们公司的crm系统中是没有银行联行号的。后来和东亚银行沟通他们提供了一个支行名称和银行联行号的对照表（下左图），但拿到对照表发现我们crm系统中填写的支行名称很不规范，8万多条收款信息没有一条能够直接匹配上的。比如收款银行，在crm系统中有填工行的，也有填工商银行的，也有填中国工商银行（下右图）；而在东亚银行提供的对照表中则是“中国工商银行股份有限公司”。还有一些支行名称在crm系统中根本就没有填写，一个银行在一个城市有多个支行，比如工行在无锡有多个支行，而crm系统中填的都是无锡支行，这样即使使用人工也无法进行匹配。

  

而东亚银行说如果银行联行号错误则可能会支付失败，如果支付成功率比较低则会影响到用户体验了。再次情况下不得不对crm系统的收款方信息数据录入进行规范，从源头解决该问题。

注意：当接口根据实际需要进行调整，同时更新详细设计文档，保持接口详细设计的可追溯性。

3.确定数据交互的安全性

   交互传输的数据中是否有敏感数据，如果有，如何处理？如果要加密，采用何种加密方式？接口是公开的还是受限定访问的？如果是受限定访问的，如何确定信息的发送方或者获取方是合法的，而不是冒仿者？

例如电子商务网站一般都会调用支付宝的接口进行付款，在传送基本的金额、通知url、用户名等信息外，支付宝为验证调用的合法性还需要传送“安全码、加密方式”等字段进行校验，以防止用户将货款付到其他人或公司的支付宝账户中。

在调用招商银行的支付接口时招商银行会限定IP，并且会用自己的客户端将发送信息按照分配的U盾进行加密处理。

4.编码

1).不要程序各个地方直接使用其它的系统的接口，最好是写一个类来封装其它系统的接口，如果其它系统的接口很多，可以专门建一个项目或包来管理这些类，这样当接口发生变化时（如接口名，接口方式），可以集中修改找一个类中的函数，而程序的其它地方都可以不用改，将“变化”限定在最小的范围内，将封装的优点大大的发挥出来。切忌在程序的各个地方直接调用其它系统的接口

2）对于调用会产生数据交易的其它系统接口，一定要写Log,这对将来数据出错时，查找问题的根源很必要，特别是对方系统的接口没有写log时，一旦出现数据问题，往往会不知从何查起，是我们给的数据有问题，还是对方系统处理我们给的数据有问题？在最近的一个项目中，因为我们产生数据的逻辑很复杂，而对方接口收到我们产生的数据后，也会做一个很复杂数据交易动作，在系统上线初期，出现了很多莫名其秒的数据，而我们正是通过在调用对方接口时的写log数据，很快查出一些是我们生成的数据有问题，一些是对方处理数据有问题

3)对接口接收过来的数据，最好进行数据效验，因为你不能保证其它系统会传给你完全符合标准的数据。 对数据校验不通过的和执行失败的，最好能有清淅明了的提示返回给调用方

5.测试

包括接口内部测试、修改，和第三方的联调。

6.上线

     接口正式上线，测试通过则上线成功，失败则回退,并从第4步开始新一轮的测试，直到系统上线成功。

三、常见问题及注意事项

1.详细设计文档应付了事，甚至不写设计文档。

实际的开发过程中，由于时间的原因，或者开发团队对设计文档的不重视，造成有的开发者忽视接口设计文档的作用，甚至不写设计文档。

     设计文档的缺失，往往会造成：人员流动时，系统无法顺利交接；会给接口的升级，带来重重困难。

2.接口开发过程中，发现原有功能设计有不合理的地方，应该对系统重构，还是仅仅实现功能了事？

   以我的经验而言，总的来说大多因为原有接口缺乏可扩展性，导致添加新功能或者接口更改后代码冗余的问题。究其原因，有下面几种情况的原因：

1）.开发周期比较紧张，来不及对原有代码重构。

2）.开发人员懒得去重构，或者不具备重构的能力。

个人认为，这些问题归根结底要由开发流程来约束和控制。

开发周期紧张的情况下，技术负责人一方面要争取尽量多的开发时间，另一方面要根据开发任务的难度安排水平尽量高的人员来做；如果高水平的人员有了，时间还是紧张，可以考虑在以后某个合适的时间来重构这部分代码,千万不要让这部分待重构的代码永远的等待下去。应该制定合理的重构时间表，作为正常的开发流程的一部分。

3.技术负责人在系统构建过程中应该担负哪些责任？

无论系统对外接口，还是系统内部功能，都是整个系统的一部分，都是技术负责人的控制范围。

技术负责人应该对开发流程的建立、系统质量负主要责任。能否建立合理的开发流程，能否领导开发人员产出高质量的软件系统，是一个技术负责人是否合格的很重要的判断标准。

就算开发团队中，开发人员数量充足，水平够高，但是开发流程不完善，缺乏合理的约束，往往会导致一部分人滋生得过且过的心态，编码完了基本上就算了事。有的人争取尽量多的空闲时间来学习新技术，为将来谋划；有的人刚接了私活，人家催的比较急，需要上班时抽空做呢；这种情况并不少见，怎样在这中恶劣的情况下保证开发工作在规定的时间内、高质量的完成？没有严谨的、合理的开发流程根本不可能领导这些"各怀心腹事"的开发人员研发出高质量的系统。

个人认为，技术负责人一定要抓住软件开发过程中的三个关键点：测试、代码复查、模块重构，一定要重视再重视，程序员和老板讲解它们的重要性，他很可能不明白其重要性，但是技术负责人千万不能不重视这三个环节，如果您都不懂或者不重视，那最终产出的是什么样的系统，大家可想而知了。