1 quickStart

Zain Zhu 发表于 2015-06-27 09:31 12600 阅读
公司项目急需一个简单的API，没有人做，正好前阵子看了遍Falcon的教程，所以就参考着做了下，做完的感觉是太简单了，简直简单得让人不敢相信。因为之前没有任何服务端开发经验，连基本的SQL语句都不太熟悉，但这次用falcon,python-mysqldb和gunicorn配合使用，居然很快就搭建起服务器，而且REST API也跑通了。虽然是个相当简单的API，而且肯定会有大量没意识到的问题存在，但还是把这一过程记录下来，总结一下。

  1. 首先是各种安装（我的电脑上之前就装了MySQL，Ubuntu系统自带Python）
    • $ sudo apt-get install python-pip（安装python的包管理器）
    • $ pip install —upgrade [cython] falcon（如果加上cython好像比较快，没有比较过）
    • $ pip install gunicorn（这个是后面运行服务器的，关于这个目前就知道这么多）
    • $ sudo apt-get install python-mysqldb（这个用来使用Python操作MySQL数据库）
  2. 安装完就可以开始干活了
    • 使用falcon开发API
    • 使用gunicorn运行服务器
    • 使用mysqldb操作数据库

falcon使用起来感觉非常简单，当然也有可能是因为没有深入去了解的原因。只要导入falcon模块，剩下的几乎就是纯逻辑代码的编写了。因为之前尝试过PHP+Apache，光各种配置文件简直就是噩梦般的存在，使用falcon的时候甚至感觉不到是在做服务器API开发，展示一段代码吧，自己敲的，可以运行：

  1. import falcon
  2. class Test(object):
  3. def on_get(self, req, resp):
  4.     resp.body = '{"message": "Hello world!"}'
  5.     resp.status = falcon.HTTP_200

就是这么简单！你已经实现了一个可以响应get请求的类了，同样的post请求只要写成on_post就行了，是不是简单到不敢相信？先将上面的代码保存为test.py,接下来，继续编写代码，然后试着运行，就能让你的服务器真正的跑起来了。再写个app.py，内容如下：

  1. import falcon
  2. import test
  3. api = application = falcon.API()
  4. test = test.Test()
  5. # 添加路由控制
  6. api.add_route('/test', test)

还是那么简单，现在这两个.py文件在同一个目录下，打开终端到当前目录下运行以下命令：

  1. $ gunicorn [-b 127.0.0.1:8000] app

现在你可以去浏览器打开127.0.0.1：8000/test了，会出现{“message”: “Hello world”}，你的服务器已经跑起来了，是不是感觉很棒！这差不多就是用falcon开发API所要做的所有事情了（至少我目前为止只用到了这些， -b参数可以绑定ip和端口号，默认就是127.0.0.1：8000）。
接下来的这段代码是使用mysqldb连操作数据库的，依旧很简单：

  1. import MySQLdb  
  2. class DBTest(object):
  3.     def test(self):
  4.         try:
  5.             conn = MySQLdb.connect(host='host',user='user',passwd='psw',port=3306)
  6.             cur = conn.cursor()
  7.             cur.execute('create database if not exists test default character set utf8 default collate utf8_general_ci') # 加上后面的两句default就可以解决中文乱码问题啦
  8.             conn.select_db('test')
  9.             cur.execute('create table test(id int, title varchar(20))')
  10.             conn.commit()
  11.             cur.close()
  12.             conn.close()
  13.         except MySQLdb.Error, e:
  14.             print "Error >>> " + str(e)

以上，几乎就是这次做这个简单的API所用到的所有技术了。

2. 开始(First Steps)

在开始之前，先得保证falcon已经安装。然后创建一个新的project目录“look”，然后切换到该目录:

  1. $ mkdir look
  2. $ cd look

然后，创建一个新文件app.py作为应用入口:

  1. $touch app.py

打开app.py，加入下面的内容:

  1. import falcon
  2. api = application = falcon.API()

这样就创建了一个WSGI应用，并且设置别名为api。我们可以使用任何变量名，Gunicorn希望我们默认使用application。
WSGI应用只是一个可调用的明确定义的签名，你可以在任何支持WSGI协议的web server上托管你的应用。下面我们来看falcon.API类。
首先安装IPython，并且启动它:

  1. $ pip install ipython
  2. $ ipython

然后，输入下面的命令来查看falcon.API的调用

  1. In [1]: import falcon
  2. In [2]: falcon.API.__call__？

或者，你可以使用内建的help函数去查看:

  1. In [3]: help(falcon.API.__call__)

注意method签名。env和start_response是标准WSGI参数。Falcon在这些参数上层添加了少许抽象，所以我们不必直接去操作它们。
Falcon框架包含大量的内联文档，你可以通过使用上面介绍的技巧来查询。经过Falcon团队对文档可读性的大量优化，我们可以很快浏览和查找我们需要的。
Tip
bpython是另一个非常给力的REPL(交互式解释器)，可以加入我们的工具箱，以便以后浏览新的library(库)。

3. 托管应用(Hosting Your App)

现在我们已经创建了一个简单的Falcon应用，我们可以让它运行在WSGI server上。Python包含一个自托管的参考server，但是我们还是使用实际部署时使用的server。

  1. $ pip install gunicorn
  2. $ gunicorn app

现在我们使用curl尝试查询它:

  1. $ curl localhost:8000 -v

你将会获取到404。这很正常，因为我们没有设定任何路由(route)。Falcon包含默认的404响应处理(response handler)，用来处理没有匹配到任何路由的请求地址。
使用curl可能会有点蛋疼，我们可以安装HTTPie，从今以后就使用它了。

  1. $ pip install --upgrade httpie
  2. $ http localhoost:8000

4. 创建资源(Creating Resources)

Falcon从REST架构风格引入了一些术语，如果你熟悉REST概念，那么对Falcon应该会比较熟悉。不过，就算完全不懂REST，也不用担心。Falcon的设计理念是，尽可能直观地让所有人理解HTTP基本原理。
在Falcon中，我们可以把传入的请求(incoming requests)称为资源(Resources)。资源只是一个常规class，包含一些遵循一定命名规则的方法(method)。每个方法对应一个动作(API客户端为了获取或转换资源，去请求执行的动作)。
假设我们在构建一个图片分享API，那我们可以创建一个image资源。在我们的项目目录中，创建一个image.py的文件，可以在里面添加下面的代码:

  1. import falcon
  2. class Resource(object):
  4.     def on_get(self, req, resp):
  5.         resp.body = '{"message":"Hello woeld!"}'
  6.         resp.status = falcon.HTTP_200

可见,Resource只是一个很常规的class，类名可以任意取。Falcon使用duck-typing，所以不需要继承任何特定的基类。
上面的image资源定义了单一方法on_get。对于resource想要支持的任何HTTP方法，只需要简单在resource上加on_x类方法(class method)，x可以是标准HTTP方法中的任何一个，例如on_get,on_put,on_head(小写)等等。
我们将这些著名的方法称作responders(响应器)。每个responder至少需要两个参数，一个代表HTTP请求，另一个代表对应请求的HTTP响应。根据习惯，我们一般写作req和resp。route(路由)模板和hooks(钩子)可以添加一些额外的参数，在后面将会讲到。
现在，image资源对GET请求作出响应：200 ok和一个JSON对象。Falcon默认是application/json作为互联网媒体类型，但是你可以设置成任何你想使用的类型。例如，你可以使用MessagePack或者其他序列化格式。
如果你想在上面的例子中使用MessagePack，你需要为Python安装序列化/反序列化。通过运行pip install msgpack-python，然后更新你的responder中相应的响应数据(response data)和内容类型(content_type):

  1. import falcon
  2. import msgpack
  3. class Resource(object):
  4.     def on_get(self, req, resp):
  5.         resp.data = msgpack.packb({'message':'Hello world!'})
  6.         resp.content_type  = 'application/msgpack'
  7.         resp.status = falcon.HTTP_200

注意，使用resp.data代替resp.body。如果你给后者resp.body指定一个bytestring，Falcon也能处理，但是通过直接指定resp.data你将获得一些性能提升。
现在关联上resource，看其运行得如何。回到app.py，并且将其修改成下面的形式:

  1. import falcon
  2. import images
  3. api = application = falcon.API()
  4. images = images.Resource()
  5. api.add_route('/images', images)

现在，如果传入一个“/images”的请求，Falcon请会调用images的资源中的响应器(responder)—对应所需要的HTTP方法。
重启gunicorn，并且尝试向resource(资源)发送一个GET请求:

  1. $ http GET localhost:8000/images

Tip
duck-typing:动态类型的一种风格。在这种风格中，一个对象有效的语义，不是由继承自特定的类或实现特定的接口，而是由当前方法和属性的集合决定。在duck typing中，关注的不是对象的类型本身，而是它是如何使用的。

5. 请求对象和响应对象(Request and Response Objects)

资源(resource)中的每个响应器(responder)接收一个请求对象(request oject)—可以被用作读取headers、查询参数和请求的body。你可以使用我们之前提到的help函数去列举Request类的成员:

  1. In [1]: import falcon
  2. In [2]: help(falcon.Request)

每个响应器(responder)也能接收一个响应对象(response object)—可以被用作设置HTTP状态码、headers和响应的body。你可以通过使用同样的技巧来列举Response的类成员:

  1. In [3]: help(falcon.Response)

让我们探究一下他们如何运作。当客户端(client)POST到images集合(collection)时，我们要创建一个新的image资源。首先，我们需要指定images保存在什么地方(对于真实的service，你将需要使用一个对象储存服务，例如Cloud Files 或者Amazon S3)。
编辑你的images.py文件，添加下列代码到resource:

  1. def __init__(self, storage_path)
  2.     self.storage_path = storage_path

然后，编辑app.py，然后传入一个path参数到resource的初始化器。
最后，实现POST响应器(responder):

  1. import os
  2. import time
  3. import uuid
  4. import falcon
  5. def _media_type_to_ext(media_type):
  6.     #剥离'/images/'前缀
  7.     return media_type[6:]
  9. def _generate_id():
  10.     return str(uuid.uuid4())
  11. class Resource(object):
  12.     def __init__(self, storage_path):
  13.         self.storage_path = storage_path
  15.     def on_post(self, req, resp):
  16.         image_id = _generate_id()
  17.         ext = _media_type_to_ext(req.content_type)
  18.         filename = image_id + '.' + ext
  20.         image_path = os.path.join(self.storage_path, filename)
  21.         with open(image_path, 'wb') as image_file:
  22.             while True:
  23.                 chunk  = req.stream.read(4096)
  24.                 if not chunk:
  25.                     break
  27.                 image_file.write(chunk)
  29.         resp.status = falcon.HTTP_201
  30.         resp.location = '/images/' + image_id

正如我们所看见的，我们给新图片生成了一个唯一的ID和文件名，然后从req.stream读取出来，再写入文件。调用stream而不是body去强调事实—你确实正在从输入流读取;Falcon不会输出(spool)或解码(decode)请求数据(request data)，而是让你直接访问由WSGI server提供的二进制输入流(incoming binary stream)。
注意，我们将HTTP response status code设置为“201 Created”。预定义的状态字符清单，我们可以通过对falcon.status_codes调用help函数来查看:

  1. In [4]: help(falcon.status_codes)

在on_post响应器的最后一行，给新创建的资源设置Location Header。(我们很快就给该路径(path)创建一个了路由(route))注意，Request类和Response类包含一些读取和设置通用header的便利属性，但是通过声明req.get_header和resp.set_header方法，我们总是可以使用任何header.
重启gunicorn，然后尝试给resource发送一个POST请求(可以将test.jpg替换成任何你想操作的JPEG文件的路径)

  1. $ http POST localhost:8000/images Content-type:image/jpeg < test.jpg

如果现在去查看你储存目录，将会包含你刚才POST的图片的复制品。

6. 提供图片(Serving Images)

我们现在已经可以上传图片到服务了，我们还要能获取他们。我们要做的就是，通过带有路径的请求，让服务器返回一张图片到Location header，就像这样:

  1. $ http GET localhost:8000/images/87db45ff42

接下来，我们可以在images资源中添加on_get响应器，这样做对于比较简单的resource是可行的，但是这种方法会导致一个问题—当同一个HTTP方法(例如GET)需要作出不同的响应。所以具体取决于使用者想要处理一系列的事件还是单个事件。
按照这个思路，如果我们要处理多张图片，除了表示单张图片资源的类以外，还需要新建一个类。我们可以在新的类中添加on_get响应器。
我们按照下面这样，继续编辑images.py：

  1. import os
  2. import time
  3. import uuid
  4. import falcon
  5. def _media_type_to_ext(media_type):
  6.     # 剥离'/images/'前缀
  7.     return media_type[6:]
  8. def _ext_to_media_type(ext):
  9.     return 'image/' + ext
  10. def _generate_id():
  11.     return str(uuid.uuid4())
  14. class Collection(object):
  15.     def __init__(self, storage_path):
  16.         self.storage_path = storage_path
  17.     def on_post(self, req, resp):
  18.         image_id = _generate_id()
  19.         ext = _media_type_to_ext(req.content_type)
  20.         filename = image_id + '.' + ext
  21.         image_path = os.path.join(self.storage_path, filename)
  22.         with open(image_path, 'wb') as image_file:
  23.             while True:
  24.                 chunk = req.stream.read(4096)
  25.                 if not chunk:
  26.                     break
  27.                 image_file.write(chunk)
  28.         resp.status = falcon.HTTP_201
  29.         resp.location = '/images/' + filename
  30. class Item(object):
  31.     def __init__(self, storage_path):
  32.         self.storage_path = storage_path
  34.     def on_get(self, req, resp, name):
  35.         ext = os.path.splitext(name)[1][1:]
  36.         resp.content_type = _ext_to_media_type(ext)
  38.         image_path = os.path.join(self.storage_path, name)
  39.         resp.stream = open(image_path, 'rb')
  40.         resp.stream_len = os.path.getsize(image_path)

可以看到，刚才我们将Resource重命名为Collection，并且添加了一个Item类去表示单张图片资源。还有，我们需要注意到on_get响应器中的name参数。任何在路由中指定的URL参数都将被转换成对应的kwargs参数，同时传递到目标响应器(responder)中。之后，将会讲解如何指定URL参数。
在on_get响应器中，我们按照文件名扩展去设置内容类型的header，然后通过打开文件操作来直接以数据流形式输出图片。还有需要注意resp.stream_len的用法。每当我们使用resp.stream来代替resp.body或resp.data的时候，我们必须给数据流指定一个预期的长度，以便web客户端知道从响应(response)中读取的数据有多大。
Tips
如果你事先不知道数据流的大小，你可以通过使用分块编码，这个用法超过该教程范围。
如果resp.status没有明确地设定，其默认值为200 OK，确切的说，这应该是我们应该在on_get响应器去做的。
现在我们将事件关联上，然后尝试运行一下。首先按照下面的例子来编辑app.py:

  1. import falcon
  2. import images
  3. api = application = falcon.API()
  4. storage_path = '/usr/local/var/look'
  5. image_collection = images.Collection(storage_path)
  6. image = image.Item(storage_path)
  7. api.add_route('/images', image_collection)
  8. api.add_route('/images/(name)', image)

可见，我们定义了一个新的路由/images/{name}。这会让Falcon将所有的对应的响应器(responder)和获取的name参数关联起来。
Tips
Falcon还支持更加复杂的参数化路径段(包含多个值)。例如，类Grasshopper(GH-like,可以通过参数的调整直接改变模型形态)的API能够使用下面的模板为两个分支添加一个路由。

  1. /repo/{org}/{repo}/compare/{usr0}:{branch0}...{usr1}:{branch1}

然后，我们重启gunicorn，并且post并一张图片给service:

  1. $  http POST localhost:8000/images Content-type:image/jpeg < test.jpg

记下在Location header中返回的路径，然后使用该路径去GET这张图片:

  1. $ http localhost:8000/images/6daa465b7b.jpeg

HTTPie默认不会下载图片，但是我们可以看到响应(response)的header被设置好了。更有趣的是，我们可以继续在浏览器中输入刚才的URL，图片会被正确的显示出来。

7. “钩子”简介(Introducing Hooks)

看到这里，我们应该对Falcon基础API有了较好的理解。在教程结束前，我们需要花费一点时间去整理代码，并且加上一些错误处理。
第一步，当接收到一个POST请求时，检查输入的媒体类型(incoming media type)去确认是否为通用图像类型。我们可以通过使用Falcon的before钩子来完成。
@wjy 2015-12-22 18:26 字数 8599 阅读 22
首先，我们需要定义一个service接收的媒体类型列表。将这些常量定义放在代码顶部，也就是images.py文件的import声明后面。

ALLOWED_IMAGE_TYPES = (
    'image/gif',
    'image/jpeg',
    'image/png',
)

这样声明只接收GIF、JPEG、PNG图像格式，当然你也可以添加你想要的其它格式。
接下来，在每个请求post消息前创建一个钩子。并且在ALLOWED_IMAGE_TYPES下面添加该方法:

def validate_image_type(req, resp, params):
    if req.content_type not in ALLOWED_IMAGE_TYPES:
        msg = 'Image type not allowed. Must be PNG, JPEG, or GIF'
        raise falcon.HTTPBadRequest('Bad request', msg)

然后将这个钩子附加在on_post响应器上，如下:

@falcon.before(validate_image_type)
def on_post(self, req, resp):

这样，每当这个on_post响应器被调用前，Falcon将先执行(invoke)validate_image_type这个方法。除了必须接受三个参数外，该方法并没有什么特别的。对于每个钩子，会引用传递进对应响应器(responder)的req和reqsp对象，作为前2个参数。第三个参数，习惯上被称作params，引用自Falcon为每个request创建的kwarg字典。如果params存在的话，将包含路由的URL模板参数及其对应的值。
由此可见，我们可以使用req去获得关于传入的请求的相关信息。而且需要的话，我们也可以使用resp去操作HTTP响应，为了避免重复代码(in a DRY way)我们甚至可以给响应器(responder)添加额外的kwarg，例如:

def extract_project_id(req, resp, params):
    """
    为所有响应器的params添加'project_id'。
    意味着将在'before'钩子中被使用
    """
    params['project_id'] = req.get_header('X-PROJECT-ID')

现在我们可以想象，这样的一个钩子应该适用于一个资源(resource)的所有响应器(responder)，甚至可以适用于全局范围内的所有资源。我们还可以将钩子应用到整个资源上，如下:

@falcon.before(extract_project_id)
class Message(object):
    #...

而且，在API类初始化时将钩子作为参数传递进去，我们可以全局应用:

falcon.API(before=[extract_project_id])

如果想对钩子(hooks)进一步了解，可以查阅API类的帮助文档，也有装饰器falcon.before和falcon.after的帮助文档。
至此，我们已经添加了一个钩子—在图像被POST时确认媒体类型。你可以实际操作一下，比如传入一些邪恶的东西，看看发生什么:

$ http POST localhost:8000/images Content-Type:image/jpx < test.jpx

不出意外，会返回400 Bad Request状态和结构分明的错误body。当出现错误时，我们通常想给用户一些信息，来帮助他们解决问题。这个规则有个例外，用户请求访问未授权的东西时产生的错误。这种情况，我们应该希望去仅仅返回一个404 Not Found的空body，防止恶意用户想要获得一些能帮助他们破解我们API的信息。
Tip
可以关注一下我们的姊妹项目—Talcons，由社区贡献的一些游泳的Falcon钩子。如果你创建了一些有趣的钩子，同时你认为别人也需要，可以考虑贡献到该项目。

8. 错误处理(Error Handling)

通常来讲，Falcon假定资源的响应器(onget,on_post等)在大部分情况下能正确运作。也就是说，Falcon在保护响应器代码上没有做太多工作。
(通常)这样可以减少多余的检查，Falcon可以专注运行一些核心代码，使得框架更高效。在这种理念下，利用Falcon构建一个高质量的API需要:
1.资源响应器将响应变量设置为完整值
2.大部分代码易于测试
3.错误应该是可预见、易查明，并且能在每个响应器中做作相应处理。
Tip
除非已经注册自定义处理这种情况的程序,不要继承falcon.HTTPError，否则Falcon将会重新抛出错误。(详情请见：falcon.API)_
谈到错误处理，当发生一些可怕的(轻度的)错误，我们可以手动设置错误状态、合适的响应header、甚至是一个使用resp对象的错误body。然而，Falcon通过提供一套在错误发生时可能抛出的异常，使得处理更加容易。事实上，如果Falcon捕获到(catch)继承自falcon.HTTPError的响应器(responder)抛出的任何异常，框架会将异常转换成对应的HTTP错误响应。
你可以抛出falcon.HTTPError的实例，或者使用一些预定义的错误类—尝试做一些正确的事情去设置header和body。查阅下面的文档，你可以获得横多关于在你的API中如何使用的信息：

falcon.HTTPBadGateway
falcon.HTTPBadRequest
falcon.HTTPConflict
falcon.HTTPError
falcon.HTTPForbidden
falcon.HTTPInternalServerError
falcon.HTTPLengthRequired
falcon.HTTPMethodNotAllowed
falcon.HTTPNotAcceptable
falcon.HTTPNotFound
falcon.HTTPPreconditionFailed
falcon.HTTPRangeNotSatisfiable
falcon.HTTPServiceUnavailable
falcon.HTTPUnauthorized
falcon.HTTPUnsupportedMediaType
falcon.HTTPUpgradeRequired

例如，你可以这样处理没找到的图片:

try:
    resp.stream = open(image_path, 'rb')
except IOError:
    raise falcon.HTTPNotFound()

或者你也可以这样处理一个假冒的文件名:

VALID_IMAGE_NAME = re.compile(r'[a-f0-9]{10}\.(jpeg|gif|png)$')
#...
class Item(object):
    def __init__(self, storage_path):
        self.storage_path = storage_path

    def on_get(self, req, resp, name):
        if not VALID_IMAGE_NAME.match(name):
            raise falcon.HTTPNotFound()

有时候你可能对获取抛出异常的类型没有太多把握。为了解决这个问题，Falcon允许创建解决任何错误类型的自定义处理程序。例如，如果数据库抛出继承自清楚的数据库错误(NiftyDBError)异常，我们可以设置一个特殊的错误处理程序去处理对应的数据库错误(NiftyDBError),但是你不必跨多个响应器(respondee)去粘贴复制你的错误处理代码。
查阅关于falcon.API.add_error_handler的文档，获取更多这些特性的信息，使你的代码尽可能精简漂亮：

In [7]: help(falcon.API.add_error_handler)

9. 现在该怎么做？

我们友好的社区可以回答你的问题，帮助你解决棘手的问题。
参照:获取帮助
之前有提到，Falcon的文档覆盖面是相当广的。所以通过Python交互式解释器(REPL,例如IPython、bpython)查阅Falcon的模块，你可以学到很多。
同时，千万不要吝啬将Github上的Falcon源代码pull下来，并用你喜欢的编辑器去查看Falcon代码。开发团队已经尽可能将代码写的简洁明了、高可读性;文档可能会有些不足，但是代码基本上不会出错的

作者：legolas_v
链接：https://www.jianshu.com/p/0c2535da7600
来源：简书
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。