RESTful API 框架 HUG 指南

如果你在用 Python3,如果你需要搭建一个 API 服务,如果时间很紧,那么 HUG 可能就是你的最佳选择!本文将用轻松易懂的实例教程来带大家走入 HUG 的世界。


更新历史

  • 2017.03.09: 完成初稿

准备工作

HUG 是基于 Python3 的,所以我们来安装一下。一般来说我们会使用 virtualenv 来隔离不同的环境,不然不同的包容易『打架』。比较简单,跟着敲命令即可。

# 安装 Python3,其中 pip3 会随着 Python3 一并安装
# 编译时间会比较长,请耐心等待
brew install python3
# 安装 VirtualEnv 方便隔离开发
pip3 install virtualenv
# 新建一个 ~/hug 文件夹来保存
virtualenv -p python3 ~/hug
# 激活环境
source ~/hug/bin/activate
# 离开环境
deactivate

配置完成之后,我们就可以安装 hug 啦,直接 pip3 install hug --upgrade 即可。恭喜,一切完事儿!(如果你手滑,可以再 pip3 install bottle 一下,之后有用)

Hello World

按照通常的 Hello World 惯例,我们就来写一个 API,给访问这个 API 的用户问好。就是如下 7 行(文件名为 hello.py):

import time
import hug
@hug.get('/hello')
def hello(name):
"""Say Hello to the User"""
ticks = time.time()
return "Hello {name}! Now is {ticks}".format(**locals())

然后我们在命令行里输入 hug -f hello.py,就可以看到如下萌萌的启动界面:

然后我们来访问一下 127.0.0.1:8000,发现返回的结果是这个:

{
"404": "The API call you tried to make was not defined. Here's a definition of the API to help you get going :)",
"documentation": {
"handlers": {
"/hello": {
"GET": {
"usage": "Say Hello to the User",
"outputs": {
"format": "JSON (Javascript Serialized Object Notation)",
"content_type": "application/json"
},
"inputs": {
"name": {
"type": "Basic text / string value"
}
}
}
}
}
}
}

这个告诉我们,嘿这个 API 我们没有定义噢,但是我们很贴心的给你列出来已经定义的 API,剩下的你自己看咯!

好,我们现在知道了,要访问的是 127.0.0.1:8000/hello,于是我们打开浏览器再试一次,发现结果是这个:

{
"errors":
{
"name": "Required parameter 'name' not supplied"
}
}

噢,这个错误提醒我们,一定要给出 name 这个参数,好,那我们访问 127.0.0.1:8000/hello?name=wdxtub,结果终于对了,像这样(给出了名字,也给出了当前的时间戳):

"Hello wdxtub! Now is 1489061160.552566"

但是这个方法还有一点不好,就是我们改动了代码,并不会自动重新载入,每次都要手动重启很麻烦,那怎么办呢?下一节我们就来搞这个问题。

自动重启及 API 测试

还记得我们之前手滑安装的 bottle 吗?接下来就有用啦,我们把代码改成如下(注意新增的 import 和下面的 if 部分):

import hug
import time
from bottle import run
@hug.get('/hello')
def hello(name):
"""Say Hello to the User"""
ticks = time.time()
return "Hello {name}! Now is {ticks}".format(**locals())
if __name__ == "__main__":
app = __hug__.http.server()
run(app=app, reloader=True, port=8000)

然后在命令行中输入 python hello.py,就可以看到我们的 API 服务器启动起来了,如果这个时候我们对 hello.py 做些修改,bottle 会自动帮我们重启,非常方便!比如我们可以加入下面几行:

@hug.get('/', output=hug.output_format.json)
def root():
return {'msg': "欢迎来到 HUG 指南"}

稍等一下,就可以访问 127.0.0.1:8000 了。当然,使用浏览器测试 API 其实是不太方便的,这里推荐一下 Postman 这个 Chrome 应用,可以很方便地进行各类测试。比如像这样:

重新认识 HUG

官方的标题起的很威武霸气 - 拥抱未来的 API(Embrace the APIs of the future)。借用其简介:

Drastically simplify API development over multiple interfaces. With hug, design and develop your API once, then expose it however your clients need to consume it. Be it locally, over HTTP, or through the command line - hug is the fastest and most modern way to create APIs on Python3.

从前面的例子中我们其实也可以简单领略到 HUG 的魅力,这里简单总结一下:

  • 性能高。在如此高的抽象层仍旧不损失太多性能,值得称赞(接近最快的 falcon
  • 自带版本管理。简单制定所属的 API 版本,就可以用 v1, v2 这样的方式来切换,方便
  • 自动化文档。只要简单地在代码中写注释及标注好类型,文档就自动生成了,省事儿
  • 标记即验证。利用 Python 3 的 type annotation 能力,可以对每个参数进行验证和转换
  • 写一次到处用。只能用作 API 吗?错!还可以用在命令行和其他 python 代码中,因为业务逻辑很干净

好了!现在你已经准备好了!可能教程不是特别『丰富』,但是相信你可以的,毕竟参考链接里可是有完整的教程呢!

参考链接

捧个钱场?