[转载]项目经验总结(一)如何约定接口的定义

原文：http://www.cnblogs.com/ASPNET2008/archive/2010/11/01/1866566.html

 

最近项目终于上线了，上线当天还算正常，没出啥大问题，希望以后继续保持，哈哈，上线前一阵工作特别累，最近脑袋都有点晕，工作累并不是因为工作量大，而是有一些其它主观上的原因。这里我想总结下工作累的原因。我会分几篇来总结，这篇我先来讲讲和其它小组合作开发项目时，如何约定服务接口。

      说到服务接口的约定，大家听起来可能会认为没啥好说的，无非就是服务端提供数据，客户端调用，但往往是简单的事情容易出错。我们小组(其实开发就两人,属于两个不同的部门)，做的项目呢不是一个全新项目，只是公司业务系统的一小部分，直接点说是酒店订单在线取消。酒店的订单有点复杂，从取消的角度来讲，分为三种：

      1:会员预订的普通订单，普通订单的概念需要比较下面两种订单。
      2:会员预订的订单，但这种订单需要信用卡的担保，即预订时先会冻结用户信用卡的部分金额。
      3:会员预订的订单，这种订单需要信用卡预订，费用直接从用户信用卡中扣除。

      之所以给大家描述了项目的具体内容，是因为在这三种订单在取消的过程中，无论是从用户界面上还是取消的逻辑上都大有区别，例如信用卡担保的订单，在取消成功后，需要告诉用户解冻的金额，信用卡预付的订单，因为预付是直接扣款，所以免费取消是有条件的，即有有某些情况下，取消时需要扣费。针对这种扣费的订单，就需要准确,清楚的提示用户扣费的金额等信息。例如在用户订单列表页的取消提示窗口：

      第一：普通取消订单：  
      请于年月日:00前取消订单
    
      第二：预付订单
      2010年月日:00前<span>免费</span>取消；<br />14:00—:00之间<span>扣款</span>取消

      我这边属于接口的调用者，对方属于服务接口的开发者，针对上面取消时需要用到的数据，我当时的邮件部分内容如下：
      第一:如何取订单对象是否会产生罚金?

      第二:如果有罚金是部分罚金还是全额罚金?

      第三:如果有罚金,罚金数从哪个属性上取?

      第四:产生罚金的条件,例如什么时间之后取消会产生罚金。

      大家能否看出上面的内容有可能会有什么不妥的地方吗？

      说明：产生罚金均指上面的那种预付订单。罚金是通过一定的规则来计算得到的，当不满足规则时就不会有罚金。但它有一种非常重要的前提，就是订单需要 经历过确认状态(例如：新单到取消，属于没有经历过,新单到确认再到入住属于经历过)，如果做过在线商城的朋友，对订单状态可能非常有印象，用户下订单后，系统会自动处理，此时就会产生一个接一个的状态，我们这里所说的确认状态就是其中的一种。
      1:问题：针对这个罚金就没有详细指定如何返回，结果接口开发的同事，认为凡是订单确认前的几种状态就取罚金，凡是状态在确认后的就计算罚金，结果就出现这样的问题：当用户从新单直接取消变成已取消时，由于接口认为已取消状态属于确认状态之后的状态，就取罚金，导致客户端不能正确判断是否有罚金，因为客户端以罚金是否大于0做为判断标准。

      小结：没有明确的给出以什么样的标准来判定是否有罚金。如果我告诉对方罚金大于0为标准，什么时候不返回罚金，接口方面就不会有上面的问题出现了。

 

      2:服务的接口最好由客户端及服务端共同定义：服务端的数据是给客户端用，但最好是客户端明确的告诉服务端需要哪些数据，我们可以详细到传入的参数，返回的对象的所有属性内容及详细描述。我们这次开发时，这些数据均是服务端来定义，这样的结果就是，给出的数据有的不完全满足客户端需求，有的给出了客户端可能根本用不上。所以在后期的开发中，经常是客户端开发到一定程度，发现还有数据无法获取，这时又需要找服务端商量如果处理，这一来一去的，导致接口相当不稳定，对双方的时间都是一种考验。

      由客户端来约定服务接口的另外一个好处：当服务端没有提供真正的接口时，我们可以自己定义的接口内容，编写一个假的接口，当真正的服务开发完成后，客户端只需要修改服务层的调用方式即可，大大减少了和服务端的依赖。接口数据结构的定义，如果有客户端参与，那么在开发时，就会针对返回对象的数据意义非常清楚，例如：

 

       /// <summary>
        /// agency信用卡担保金额
        /// </summary>
        public decimal VouchAmount { get; set; }
        /// <summary>
        /// 预付金额
        /// </summary>
        public decimal PrePayAmount { get; set; }
        /// <summary>
        /// 什么日期
        /// </summary>
        public int XDate { get; set; }
        /// <summary>
        /// X小时
        /// </summary>
        public string  XHour { get; set; }
        /// <summary>
        /// 从几点开始
        /// </summary>
        public int FromHour { get; set; }
        /// <summary>
        /// 到几点
        /// </summary>
        public int ToHour { get; set; }
        /// <summary>
        /// 罚金
        /// </summary>
        public decimal Amercement { get; set; }

 

      3:约定服务接口内容的同时，一定不要忘记还是约定服务接口的提交时间，因为服务接口的开发质量以及进度直接影响客户端的开发质量以及进度。由于本次开发过程中，我们两个开发对业务逻辑都有一定的陌生，导致接口的开发出现了延时，这也直接影响了项目的正常提交以及测试环节，由于缺少接口联调时间(接口联调时间就是指测试接口返回数据的正确性的时间)，导致项目提交测试部门测试时，出现很多低级错误。

      总结：上面写的有点乱，但我个人认为对自己以后的工作还是有非常大的帮忙，项目经验的不断总结才能避免下次工作中出现同样的错误。