API 的设计

    当你的 API Server 接口服务比较多，那么上面的方法显然不适合我们（太啰嗦）。这里推荐一下 REST 风格。

    什么是 REST

    从资源的角度来观察整个网络，分布在各处的资源由 URI 确定，而客户端的应用通过 URI 来获取资源的表示方式。获得这些表徵致使这些应用程序转变了其状态。随着不断获取资源的表示方式，客户端应用不断地在转变着其状态，所谓表述性状态转移（Representational State Transfer）。

    这一观点不是凭空臆造的，而是通过观察当前 Web 互联网的运作方式而抽象出来的。Roy Fielding 认为，

    REST 通常基于使用 HTTP，URI，和 XML 以及 HTML 这些现有的广泛流行的协议和标准。

    • 资源是由 URI 来指定。
    • 通过操作资源的表现形式来操作资源。
    • 资源的表现形式则是 XML 或者 HTML，取决于读者是机器还是人，是消费 Web 服务的客户软件还是 Web 浏览器。当然也可以是任何其他的格式。
    • 客户端和服务器结构
    • 连接协议具有无状态性
    • 能够利用 Cache 机制增进性能

    REST 使用举例

    按照 REST 的风格引导，我们有关数据的 API Server 就可以变成这样。

    对于 接口，这时候我们可以用下面的方法，完成对应的方法调用。

    还有办法压缩不？

    引用一下 HttpLuaModule 官方示例代码。

    这下世界宁静了，每天写 Lua 代码的同学，再也不用去每次修改 Nginx 主配置了。有新业务，直接开工。顺路还强制了入口文件命名规则。对于后期检查维护更容易。

    REST 风格的缺点

    需要一定的学习成本，如果你的接口是暴露给运维、售后、测试等不同团队，那么他们经常不去确定当时的 method。当他们查看、模拟的时候，具有一定学习难度。

    REST 推崇使用 HTTP 返回码来区分返回结果, 但最大的问题在于 HTTP 的错误返回码 (4xx 系列为主) 不够多，而且订得很随意。比如用 API 创建一个用户，那么错误可能有：

    • 调用格式错误(一般返回 400, 405)
    • 授权错误(一般返回 403)
    • “运行期”错误
      • 用户名冲突
      • 用户名不合法
      • email 不合法