APP数据接口开发的一些经验

刚接到这样的任务时，没有感觉到任何压力，不就是给移动端应用提供数据吗？那边发来参数，这边处理数据，返回JSON。做网站开发时经常使用ajax请求后台数据，不就是这么回事吗。于是，在确认完需求后就开始干了，很快，进入联调阶段，这个时候各种问题来了，忙得不可开交。吃一堑，长一智，项目结束后总结了下，大致分为以下几点：

一、什么时候应该增加接口。
      一般一个页面不存在二次请求的需求时，使用一个接口，像一般的详情页，个人信息页等；页面单一功能又需要二次请求的，像带分页功能的列表页，使用一个接口；页面含多个功能，其中有一个需要二次请求的，则需要定义多个接口了，比如个人信息页下带一个待办事项的列表，又支持分页，那如果一个接口返回全部信息的话，以后每次翻页都要刷新个人信息内容，这样就造成了不必要的信息传递。

 二、 应该努力让接口的URL看上去易懂又美观。
      在创建接口时就应该考虑到接口地址，文件目录不要太深，个人觉得不应超过三层，层次最好是和APP的菜单层次保持一致，这样的好处起码在以后维护也会方便很多。接口地址不应该轻易的改动，包括增加参数，因为这会导致APP重新打包，如果是已经上线，那意味着APP需要升级。

      三、参数与返回值。
      先说参数，笔者目前的做法是一般查询采用URL传参，增改采用POST传递JSON字符串提交数据，删除同样使用POST方式。再说返回值，我们在项目中所有接口统一返回JOSN数据，并且约定一个格式，比如这个JSON对象含三个Key，分别是data，msg和status，分别代表了返回的数据，data可能是对象或者数组，请求反馈信息和反馈状态码，这样就不用每个接口都说明一遍了。再谈一些细节，在高级语言中，数据有多种类型，String，Int，DateTime等等。而序列化为JSON后，全部变为字符串，这个时候没有给值的字段就需要注意一下，像值类型，为可空时，序列化后值直接是null表示，没有引号；为不可空时，值为默认值，同样没有引号，而DateTime则带引号，"0001-01-01T00:00:00"；而像引用类型String，无值时，序列化后也变成null，而不是空串""，要想用空串""表示，必须给一个默认值，如String.Empty，说这点是因为当时iOS告诉我说字段值返回null时，他们那边报错。还有一种情况是之前遇到过的，就是数值类型的精度问题，当时接口返回一个价格字段，服务器端当然用decimal类型，并且保留两位小数，但是iOS端接收到的值小数点后却多出很多位，而Android没有任何问题，最后只好在序列化前先转成字符串类型。其它需要包含小数位的数值类型当小数点后全是0时，序列化变为整型，这种情况同样需要先转为字符串再序列化。关于DateTime类型，在作为增改参数接收时，就是反序列化后要插入到数据库，如果你正好使用了Sql Server，又使用了DateTime类型，请注意它的范围是1753-01-01 00:00:00 到9999-12-31 23:59:59，而空串转为时间为"0001-01-01 00:00:00"，会报异常。最后，笔者感觉，是不是没有特殊情况，所有字段都可以给移动端返回字符串呢，像时间类型，手机上要显示到日，我就不返回时分秒了，以字符串类型返回，这样以后产品说要显示时分秒，直接在后台处理下就OK了，是不是这样的？

 四、接口如何联调。
      这里的联调包含两层含义，一是VS环境下的远程调试，这个具体方法在网上有很多，在这就不多说了。另一个含义就是和移动端联合测试软件功能。这次项目并没有真正远程调试几次，因为记录了详细的调试日志，所以大部分问题都能很快的定位。调试日志一般都包含了两项内容：当前环境下的关键变量值及当前方法的信息。

 五、错误处理和返回错误码。
      首先，切忌把异常直接抛给调用者。因为这样不论是对体验还是定位错误都没有任何益处，而是应该在后台捕获，并记录详细的日志，然后定义一套全局的错误码，返回对应的错误码给接口调用者。关于异常的捕获应该在哪里处理，个人觉得但应该不是最佳，最外层应该用try catch包裹，并记录日志，保证异常不会抛出到调用方，其它位置如果有非托管资源的使用，应该捕获，然后记录日志，释放资源，并继续把错误向上抛。

六、接口文档。
      提到写文档，程序员貌似天生反感，但是开发接口，不写文档，似乎是不可能的，并且还要写得规范，别人能看懂。接口文档写得好，真的是件一劳永逸的事，写一份好文档省出的时间要远远大于写文档的时间，当然要做到及时更新，与程序同步。一般接口文档包含了功能、请求方式（GET/POST）、 地址、参数、返回值、请求示例、返回示例以及全局的安全验证方式、错误码等。

写这篇文章的目的就是想把这几个月的接口开发工作做个总结，结果拖拖拉拉写了好几天，写完再读时发现都有点变味了。文章中可能很多地方写到的处理方法或者对知识的理解并不是很正确，希望您不吝赐教，留下宝贵建议。