保持力量：接口开发最佳实践.pdf

保持的⼒量：接⼜开发最佳实践 神啊，求你赐给我平静的⼼，去接受我⽆法改变的事；赐给我勇⽓，去做我能改变的 事；赐给我智慧，去分辨两者的 同。 --平静之祷 1.30.1 论保持的⼒量 追到⼀个⼼仪的⼥⽣ 难，难于如何保持和培养⼀份真挚的感情；获得⼀时的财富也 难，难于如何长久保持收益；创业的公司很容易博得⼀时媒体的关注以及某次天使 的投资，但难于如何排除各种障碍、充分利⽤各⽅资源发展成中企业及⾄上市公司。 同样，提供⼀时的接⼜很容易，但当我们需要 断为接⼜提供升级，以及当我们维护 提供⼀整套接⼜时，⾯临的困难和问题会越来越⼤。 所以，这是⼀场持久的战役。需要我们⽤稳重的⼼态、专业的能⼒在背后持久⽀撑、 推动。 值得庆幸的是，这些都是问题⽽ 是限制，都是可以被解决的。 以下是结合 @郭了个浩浩 同学提供的apigee .web_api .pdf⽂档，以及我们多年来的项⽬ 实际开发经验为新⼿提供的⼀些建议，对⽼同学相信也会有所帮助。 每个建议通常会包括三部分： 现在主流的做法、PhalApi 的做法以及项⽬的选取。 1.30.2 最佳实践建议 为了⼤家查阅和翻看，这⾥先罗列本章的全部建议： (1)接⼜风格和协议的选择 - HTTP (2)接⼜域名 - 使⽤api单独域名 (3)异常处理 - 200/400/500三⼤接⼜结果状态码 (4)对外的命名规则 - 使⽤⼩写加下划线 (5)对内的命名规则 - 使⽤驼峰法和遵循PEAR命名 (6)安全与验证 - 使⽤接⼜签名和t ken登录态双重机制 (7)返回结果格式 - JSON (8)URL规则与路由映射 - 统⼀service接⼜服务，可⼀个⽂件⼀个接⼜ (9)SDK包 - 给客户端⾃由的调⽤空间和⾃由 (10)接⼜⽂档 - 使⽤markd wn快速编写 (11)测试驱动开发 - 坚持单元测试 1.30.3 建议 说 (1)接⼜风格和协议的选择 - HTTP ⽬前，后台接⼜开发可以⽤RESTFull风格，也可以⽤Web Service ；可以⽤SOAP协 议、RPC协议，也可以⽤HTTP协议；可以⽤短链接，也可以使⽤长链接。如果我们 希望继续进⾏划分，还可以分为同步或异步、单个或批量、是否有SDK包、内部接⼜ 还是开放接⼜平台等。 主流的做法 现在看来，⼤部分⼤型的企业以及⼤多数的⼩公司使⽤的都是HTTP协议下的接⼜开 发，部分使⽤RESTFull ，但Web Service较少。如： 优酷开放平台，⽰例请点击 微信公众号-服务器接⼜协议，⽰例请点击 新浪微博开放平台，使⽤REST风格，⽰例请点击 Amaz n ，采⽤Web Service 、SOAP 、REST等多种风格和协议提供服务，⽰例 请点击 PhalApi 的做法 我们选取了HTTP的协议，在于其⽆论是客户端接⼊、开发调试，还是部署构建上都 很容易实现，⽽且也符合主流，因为⼤家都⽐较熟悉。 这⼀点是⾮常重要的：因为简单，后台接⼜开发的同学才会更容易上⼿；因为容易， 客户端接⼊才会更加⽆压⼒⽽ ⽤担⼼处处受挫。 项⽬的选取 根据项⽬ 同的项⽬背景和需求，可以选择你合适的风格或者协议。但是即使出于安 全、性能或者其他技术或⾮技术的原因⽽ 采⽤HTTP协议的情况下，你也可以在 PhalApi原有的接⼜开发实现时，轻松扩展你需要的协议。如使⽤SOAP ，PHPRpc或者 sw le下的TCP协议。其中，部分协议已有扩展类库提供⽀持。 (2)接⼜域名 - 使⽤api单独域名 ⾸先，有⼀点是可以肯定的。 接⼜系统应该有⾃⼰单独的域名，⽽ 应该附属于⽹站或者管理后台。 主流的做法 显然，主流做法也是这样做的。如： 优酷开放平台：https:// penapi .y uku .c m 微信公众号： https://api .weixin .qq .c m 新浪微博： https://api .weib .c m 项⽬的选取 如果可以，尽量让接⼜系统使⽤独⽴的域名，并且使⽤api作为⼀级域名。如： //你的⽹站为： http://www . //则对应的接⼝为： (3)异常处理 - 200/400/500三⼤接⼜结果状态码 对于接⼜的异常处理，在使⽤HTTP协议下，可以通过HTTP本⾝的响应状态码