接口开发及技术负责人的职责随笔

对于网站或者平台，大多不可避免的要和第三方合作、或者接入第三方平台，合作的实现多是通过对对方接口的调用实现的。例如：网站用户共享、网银支付的接入、无纸化彩票投注平台的接入等等。

 

和第三方合作的接口开发工作，我做了没10次大概也有7，8次了吧。在这些合作的开发过程中，遇到过很多这样那样的问题，有些问题觉得还是有必要记录下来，反思一下，另外也由此延伸，想到了关于技术负责人应该担负的责任等问题。
 

第一：接口开发的流程问题。

 

接口开发的大致流程：
1.和第三方讨论需要实现哪些接口。
重点是要确定每个接口的具体功能。接口参数在开发过程中常常会有变动，所以讨论中一般不会明确定义。

 

2.编写详细设计文档。
文档包括接口名，参数名，参数类型，返回消息格式等，并提供给合作方。

 

3.编码
接口根据实际需要进行调整，同时更新详细设计文档，保持接口详细设计的可追溯性。

 

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

 

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

 

常见问题：
1.详细设计文档应付了事，甚至不写设计文档。
实际的开发过程中，由于时间的原因，或者开发团队对设计文档的不重视，造成有的开发者忽视接口设计文档的作用，甚至不写设计文档。设计文档的缺失，往往会造成：人员流动时，系统无法顺利交接；会给接口的升级，带来重重困难。

 

2.不按合作双方的接口定义，私下决定不实现某些接口。
这种情况不一定每个人都会遇到，但我确实遇到过这种事情。某一次和一个比较有名的体育社区的合作过程中，由于我们的平台是类电子商务的，所以要给用户建立财务账户，如果我们系统中不保存用户的基本信息，就没法为用户创建账户。

 

所以我方提供的接口文档中，有一个注册接口，需要用户在体育社区的注册时，同时把信息传递到我们的平台，这样我们就会为这个用户创建财务账户，否则，用户登录时就会有问题。

 

合作方对接口文档没有提出异议，但双方接口上线一段时间后，一次偶然的聊天过程中，对方开发人员透露，他们根本没有调用注册接口。吓了我一大跳，多亏我们前期的设计和编码中考虑得比较完善，否则，接口上线后，不堪设想。

 

所以，大家一定要遵守事先的约定，不要违背事先的约定，否则会出大乱子。

第二：接口开发过程中，发现原有功能设计有不合理的地方，应该对系统重构，还是仅仅实现功能了事？
以我的经验而言，总的来说大多因为原有接口缺乏可扩展性，导致添加新功能或者接口更改后代码冗余的问题。究其原因，有下面几种情况的原因：

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

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

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

 

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

 

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

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

 

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

 

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

 

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

 

评论

22 楼 Turbo 2010-01-15  

重构肯定是要的,没人一写出来的代码就优雅的.

21 楼 charles751 2009-12-30  

凤舞凰扬 写道

   楼上这些职责作为接口开发人员或者开发团队的lead，是可以理解的。但是如果技术负责人的话，那对不起，没有真正理解什么叫接口设计了。
   对于系统间的接口，关键因素是必须了解不同系统间架构的差别（比如是否异构，是否在不同物理环境），系统级需求上的差别（比如两边的处理能力差异，响应时间的差异等）以及业务应用的差别（是否实时，是否异步，是否需要事务支持等）。只有在充分了解这些因素后，才会做出准确的分析设计。（接口的设计也就是系统集成的设计）
    过了这一步，接下来，技术负责人要负责的是接口的协议（这里的协议不仅仅是API的方法等，包括接口内容的元数据信息，数据的表现形式，交互的控制方式等）
    至于楼上列出的关于代码审查，测试等，其实和接口开发本身并无太大关系了。

基本上都赞同，尤其是系统间的接口的几个关键因素，很受教。

对“技术负责人要负责的是接口的协议”这点表示疑义，不同的公司，技术负责人的职责定义很可能是不同的。

20 楼 charles751 2009-12-27  

接口真正做的好的并不多，就连易宝，环迅等用户较多的支付接口都或多或少有点问题，有的测试示例测通后，上线时出问题；有的...，就不一一详述了，所以我觉得无论公司还是开发团队，都应该更重视自己产品的质量。

由此延伸就想到了规范开发流程的问题，大家别忘了开发流程是谁来制定的，由此想到了技术负责人的职责。

个人观点：能否开发出一个好的产品，技术负责人起决定性作用。
因为他能否制定出合理的开发流程，很大程度上决定了产品的质量。

19 楼 jayo 2009-12-27  

最佩服是是那些业务员
没有的功能都能买出去，真是牛
上次接某ERP公司的一个接口，钱交了才知道根本不符合要求
最后是交了好几w，还得自己做该服务！

18 楼 jayo 2009-12-27  

大大小小的接口做了很多了
感觉最重要的几点是：
1、文档描述清晰，无歧义，错误代码完整
2、相关的资料齐全
3、最好要有技术支持的联系方式，而不是业务员;

17 楼 vieri122 2009-12-23  

我现在就是在做接口设计与实现，那个痛苦啊

16 楼 凤舞凰扬 2009-12-22  

   楼上这些职责作为接口开发人员或者开发团队的lead，是可以理解的。但是如果技术负责人的话，那对不起，没有真正理解什么叫接口设计了。
   对于系统间的接口，关键因素是必须了解不同系统间架构的差别（比如是否异构，是否在不同物理环境），系统级需求上的差别（比如两边的处理能力差异，响应时间的差异等）以及业务应用的差别（是否实时，是否异步，是否需要事务支持等）。只有在充分了解这些因素后，才会做出准确的分析设计。（接口的设计也就是系统集成的设计）
    过了这一步，接下来，技术负责人要负责的是接口的协议（这里的协议不仅仅是API的方法等，包括接口内容的元数据信息，数据的表现形式，交互的控制方式等）
    至于楼上列出的关于代码审查，测试等，其实和接口开发本身并无太大关系了。

15 楼 hell_liul 2009-12-22  

学习一下经验之谈

14 楼 nishizhutoua 2009-12-21  

两个公司一起做事情,烦恼啊.

13 楼 airu 2009-12-21  

我也做了几年的接口吧。
如果是两家公司同时为甲方做接口，还是比较痛苦的。
所以我总结：
1、接口定义清晰。设计方面。
2、双方责任人即时沟通。
3、通过甲方督促确保deadline能完成。

12 楼 yzzh9 2009-12-21  

写得很好，但是关于那个注册接口，应该在联调的时候很容易发现啊。

11 楼 charles751 2009-12-18  

提供外部服务的话不外乎以下几种形式：
1.直接开放url地址给接入商，链接中传递参数。
适用于参数较少的情况。

2.直接使用web服务引擎，例如：axis,CXF等，工作量会小一些，但数据传输效率可能不是特别好。

3.自己定义传输的数据格式，如自定义的xml格式，需要自己开发客户端jar包给接入商使用。

4.JSON格式的数据格式。

具体选择哪个，还得根据自己的实际情况来选择。

10 楼 fengsky491 2009-12-18  

同事有用Apache的Shindig实现了一个简单的功能，但交接给我了，目前就我一个负责
我也不了解Shindig，问问前辈一般采用什么技术

9 楼 fengsky491 2009-12-18  

我想在的系统也要给外部系统提供接口，我想请问下，用什么现实比较容易

8 楼 charles751 2009-12-18  

topcode 写道

charles751 写道

mock1234 写道

合作方对接口文档没有提出异议，但双方接口上线一段时间后，一次偶然的聊天过程中，对方开发人员透露，他们根本没有调用注册接口。吓了我一大跳，多亏我们前期的设计和编码中考虑得比较完善，否则，接口上线后，不堪设想。

---------------------------------------------------------------------

如果说你们自己做的个别界面不测试也许说的过去，难道对于接口的实现你们也不测试吗？

接口是给对方调用的，你从哪里看到我们的接口实现没有测试？

至少自己测试过该接口没有问题

我方接口被调用一次可以记录日志的啊.系统上线后一直没有日志你都不怀疑啊!

自测试当然是必须的，好像没人不做测试直接上新功能的吧。

生产环境的日志监控是必须的，这点你说的没错。但我们这边没有做详细的监控，具体原因不好一一说明，和我们系统的特殊性有关系。

7 楼 topcode 2009-12-18  

charles751 写道

mock1234 写道

合作方对接口文档没有提出异议，但双方接口上线一段时间后，一次偶然的聊天过程中，对方开发人员透露，他们根本没有调用注册接口。吓了我一大跳，多亏我们前期的设计和编码中考虑得比较完善，否则，接口上线后，不堪设想。

---------------------------------------------------------------------

如果说你们自己做的个别界面不测试也许说的过去，难道对于接口的实现你们也不测试吗？

接口是给对方调用的，你从哪里看到我们的接口实现没有测试？

至少自己测试过该接口没有问题

我方接口被调用一次可以记录日志的啊.系统上线后一直没有日志你都不怀疑啊!

6 楼 xindeman 2009-12-18  

mock1234 写道

合作方对接口文档没有提出异议，但双方接口上线一段时间后，一次偶然的聊天过程中，对方开发人员透露，他们根本没有调用注册接口。吓了我一大跳，多亏我们前期的设计和编码中考虑得比较完善，否则，接口上线后，不堪设想。

---------------------------------------------------------------------

如果说你们自己做的个别界面不测试也许说的过去，难道对于接口的实现你们也不测试吗？

确实没听说过没必要重构时进行重构的。

5 楼 拥抱变化之美 2009-12-17  

楼主在技术交流方面开了好头，希望我们每个技术人员都能畅谈自己的感受，相互学习交流。

4 楼 freej 2009-12-17  

同意，但是忽略了一个很重要的方面，团队的建设和维持。这也应该是技术负责人该重视的。

3 楼 charles751 2009-12-17  

mock1234 写道

重构不要过度渲染其戏剧化的一面。重构就是一个新的任务定义，可以做也可以不做，不要再在没有必要重构时过分夸张重构。

有人说在没有必要重构的时候要进行重构了吗？好像没人这么说吧。

重构关键在其合理性，合理地重构可提高功能的可扩展性，减少代码冗余，有利于后期维护和扩展。