以偶的经验，项目中的严重的事故大多是由于“沟通不到位”所致，很少由于技术导致。而很多问题导致没必要的沟通，如果团队里有一套成熟的协作工具和工作职责约定，各个成员间协作既轻松愉快又高效。 本篇来说说服务器端与客户端协作实践。

1. 维护一份接口文档，接口文档存放在方便访问、方便检索接口、不需要密码登录的地方。公司内部wiki很适合存放接口文档。

大部分公司是没有专职的接口文档维护人员的，一般来说是谁开发谁维护。

2. 接口文档的书写应提供必要的信息，易读的格式

可借鉴新浪微博开放平台(http://open.weibo.com/wiki/2/statuses/public_timeline)的文档格式，可在它基础上做简化。

  • 提供必要的信息：url, 请求方式，请求参数（标明类型、必选/可选，参数说明），返回结果，返回字段说明。
  • 提供易读的格式

不好的格式：

检测token与微信code对应的mid是否一致http://aa-api.fmenjoy.com/auth/checktcpost参数{“code”:”xxxhhhfff”“token”:”yyyyyyyyyy”}返回值：{“ret”:1, //1表示成功，非1表示错误”data”:{ //如果mid不一致，则有data数据返回，为code认证后的mid和token”mid”:123,”token”:”xxxxx”,”lid”:”yyyyy”,”nick”:”zzzz”,”hurl”:”bbbb”}}

好的格式：

略（可看新浪微博开放平台API文档）

3. 开发接口应先定义，后实现，及时更新接口状态。

接口提供者遵循先定义、后实现的原则，调用者可以尽早了解接口并开始开发工作，而不需要等接口实现完毕再动手开发。

接口状态分为：未实现，开发中，已完成。调用者了解接口状态，可以灵活调整开发/测试顺序。接口提供者应及时更新接口状态，建议也发消息通知调用者。

4. 接口提供者在通知接口调用者某接口可用前应先确保接口可用、能返回正确的数据格式。

5. 必要时接口先提供假数据给调用者。

有时候会遇到这种情况：接口开发需要较长时间，调用者等待的状态。这时候如果提供假数据给调用者暂用，调用者可先跑通本地逻辑，节省后期联调时间。

6. 接口废弃应标注，如果接口升级应在旧接口的地方标注上新接口链接，以避免调用者还继续使用旧接口。

作者 侯振永
写于2015 年 12月 4日