Routes

2017-05-20

按照官方介绍，Routes 是 Rails routes 的 Python 版，用于将不同的 URL 映射到对应的应用上，这对于开发 Restful URL 非常便利：

Routes is a Python re-implementation of the Rails routes system for mapping URLs to application actions, and conversely to generate URLs. Routes makes it easy to create pretty and concise URLs that are RESTful with little effort.

注：关于 REST API，可参考以下优秀博文：

REST API 作者的博文论文：Architectural Styles and the Design of Network-based Software Architectures （中文版）
Best Practices for Designing a Pragmatic RESTful API （中文版）

基本使用

对于 Routes，我们平常使用得比较多的就是其 Mapper 工具了。可以看看官方提供的样例：

# Setup a mapper
from routes import Mapper
map = Mapper()
map.connect(None, "/error/{action}/{id}", controller="error")
map.connect("home", "/", controller="main", action="index")

# Match a URL, returns a dict or None if no match
result = map.match('/error/myapp/4')
# result == {'controller': 'error', 'action': 'myapp', 'id': '4'}

Routes in OpenStack

这里我们仿照 OpenStack Keystone 写了下边一个样例：

import webob.dec
import webob.exc
import routes.middleware
from wsgiref.simple_server import make_server


# Environment variable used to pass the request context
CONTEXT_ENV = 'openstack.context'

# Environment variable used to pass the request params
PARAMS_ENV = 'openstack.params'


class BaseController(object):
    def _normalize_arg(self, arg):
        return arg.replace(':', '_').replace('-', '_')

    def _normalize_dict(self, d):
        return {self._normalize_arg(k): v for (k, v) in d.items()}

    def _render_response(self, body=None, status=None, method=None):
        '''Form a WSGI response.'''
        resp = webob.Response(body=body, status=status)
        resp.method = method
        return resp

    @webob.dec.wsgify
    def __call__(self, req):
        arg_dict = req.environ['wsgiorg.routing_args'][1]
        action = arg_dict.pop('action')
        del arg_dict['controller']

        params = req.environ.get(PARAMS_ENV, {})
        params.update(arg_dict)

        method = getattr(self, action)
        params = self._normalize_dict(params)
        result = method(req, **params)

        return self._render_response(body=result.body, status=result.status, method=req.method)


class UserController(BaseController):
    def get_user(self, req, user_id):
        return webob.Response('I am a user, my ID is %s.' % user_id)


class TenantController(BaseController):
    def get_tenant(self, req, tenant_id):
        return webob.Response('I am a tenant, my ID is %s.' % tenant_id)


class Router(object):
    def __init__(self):
        self._mapper = routes.Mapper()
        self._mapper.connect('/users/{user_id}',
                             controller=UserController(),
                             action='get_user',
                             conditions={'method': ['GET']})
        self._mapper.connect('/tenants/{tenant_id}',
                             controller=TenantController(),
                             action='get_tenant',
                             conditions={'method': ['GET']})

        self._router = routes.middleware.RoutesMiddleware(self._dispatch, self._mapper)

    @webob.dec.wsgify
    def __call__(self, req):
        return self._router

    @staticmethod
    @webob.dec.wsgify
    def _dispatch(req):
        match = req.environ['wsgiorg.routing_args'][1]

        if not match:
            return webob.exc.HTTPNotFound()

        app = match['controller']
        return app


router = Router()
httpd = make_server('localhost', 8080, router)
httpd.serve_forever()

这里有几点需要注意的：

因为服务端跟应用之间交互的标准是 WSGI，所以 Router 本身必须是一个 WSGI 应用（__call__(self.req)）。
Controller 路由 —— Router 对象初始化时会调用 routes 中间件（RoutesMiddleware），然后调用 self._dispatch 应用，将路由转发给相应的应用（UserController 和 TenantController）。Router 实际做的只是路由到具体到 Controller 而已，而具体要路由到的最终方法（action）是不知道的，且看下句：
具体方法路由 —— UserController 或 TenantController 被调用时（__call__(self.req)），对传入参数进行处理，并决定要调用的方法（method = getattr(self, action)），最后调用该方法并将结果标准化后返回。

对于 routes 中间件 RoutesMiddleware 和 self._dispatch，这里详细说一下：

self._dispatch 本身是一个 WSGI 应用，它和 self._mapper 一起作为参数初始化 routes.middleware.RoutesMiddleware 这个类。

RoutesMiddleware 也是一个 WSGI 应用（注意跟 self._dispatch 不是一个应用），当调用该应用时（__call__），会进行路由的匹配（注意这个参数 wsgiorg.routing_args）：

# routes/middleware.py

class RoutesMiddleware(object):
    ......

    def __call__(self, environ, start_response):
        """Resolves the URL in PATH_INFO, and uses wsgi.routing_args
        to pass on URL resolver results."""
        ......

        # Run the actual route matching
        # -- Assignment of environ to config triggers route matching
        if self.singleton:
            config = request_config()
            config.mapper = self.mapper
            config.environ = environ
            match = config.mapper_dict
            route = config.route
        else:
            results = self.mapper.routematch(environ=environ)
            if results:
                match, route = results[0], results[1]
            else:
                match = route = None

        ......

        url = URLGenerator(self.mapper, environ)
        environ['wsgiorg.routing_args'] = ((url), match)
        environ['routes.route'] = route
        environ['routes.url'] = url

        ......

        response = self.app(environ, start_response)  # 调用 self._dispatch 这个 WSGI 应用

        # Wrapped in try as in rare cases the attribute will be gone already
        try:
            del self.mapper.environ
        except AttributeError:
            pass
        return response

RoutesMiddleware 最后会调用 self._dispatch 这个 WSGI 应用，然后再由其调用对象的 Controller（WSGI 应用）。

Routes Resource

在实际中，对某个资源一般会有一些常见操作，如 CRUD，于是乎，用上一小节的方法，我们可能就要自己添加多个路由映射：

class Router(object):
    def __init__(self):
        self._mapper = routes.Mapper()
        self._mapper.connect('/users',
                             controller=UserController(),
                             action='create_user',
                             conditions={'method': ['POST']})
        self._mapper.connect('/users/{user_id}',
                             controller=UserController(),
                             action='get_user',
                             conditions={'method': ['GET']})
        self._mapper.connect('/users/{user_id}',
                             controller=UserController(),
                             action='update_user',
                             conditions={'method': ['PUT']})
        self._mapper.connect('/users/{user_id}',
                             controller=UserController(),
                             action='delete_user',
                             conditions={'method': ['DELETE']})
        ......

        self._router = routes.middleware.RoutesMiddleware(self._dispatch, self._mapper)

但我们要操作的资源较少时，这种做法问题不大，但当资源种类特别多的时候，这种方法就有点笨拙了，尤其是像 OpenStack Nova 模块涉及的资源太多，要是单纯为每个资源都添加个 CRUD，这个路由映射表就够大的了；另外，这种做法也不符合复用的思想。所以，我们期望，对资源的一些常见操作，我们希望 routes 包能够帮我们封装好；对一些非常见操作提供支持。要做到这个，就要用到 routes.resource 这个工具了。

关于 routes.resource 详细介绍，可参考其官方文档。接下来我们就直接上样例吧：

......


class BaseController(object):
    ......


class UserController(BaseController):

    def index(self, req):
        msg = 'in UserController.index'
        print msg
        return webob.Response(msg)

    def create(self, req):
        msg = 'in UserController.create'
        print msg
        return webob.Response(msg)

    def show(self, req, id):    # The same with get_user(self, req, id)
        msg = 'in UserController.show'
        print msg
        return webob.Response(msg)

    def update(self, req, id):
        msg = 'in UserController.update'
        print msg
        return webob.Response(msg)

    def delete(self, req, id):
        msg = 'in UserController.delete'
        print msg
        return webob.Response(msg)

    def ask_delete(self, req, id):  # Special action
        msg = 'in UserController.ask_delete'
        print msg
        return webob.Response(msg)


class Router(object):
    def __init__(self):
        self._mapper = routes.Mapper()
        self._mapper.resource('user', 'users',
                              controller=UserController(),
                              member={'ask_delete': 'DELETE'})  # ask_delete 是非常见操作

        self._router = routes.middleware.RoutesMiddleware(self._dispatch, self._mapper)

    ......


......

我们可以利用发包工具（如 POSTMAN）向服务器发送请求，下边是服务器截获到的请求：

127.0.0.1 - - [21/May/2017 15:39:37] "GET /users HTTP/1.1" 200 23
in UserController.index
127.0.0.1 - - [21/May/2017 15:39:47] "POST /users HTTP/1.1" 200 24
in UserController.create
127.0.0.1 - - [21/May/2017 15:39:56] "GET /users/520 HTTP/1.1" 200 22
in UserController.show
127.0.0.1 - - [21/May/2017 15:40:02] "PUT /users/520 HTTP/1.1" 200 24
in UserController.update
127.0.0.1 - - [21/May/2017 15:40:09] "DELETE /users/520 HTTP/1.1" 200 24
in UserController.delete
127.0.0.1 - - [21/May/2017 15:40:12] "DELETE /users/520/ask_delete HTTP/1.1" 200 28
in UserController.ask_delete

不同的路由就会进入不同的处理函数。

Routes and PasteDeploy

只有将 Routes 和 PasteDeploy 相结合起来，才能算完满！那就开始吧！

这两者一旦放在一起就容易混淆，不过只要清楚它们的作用，区分开来还是比较简单的。简单点讲，PasteDeploy “主外”，Routes “主内”，也即，PasteDeploy 关注的是中间件加应用的流水线，流水线终点是 Router，是大的方面；Routes 关注的是最终 URL 的分发，关注的是分发到具体应用（Controller），是小的方面。下边我们来直接看样例吧：

配置文件：

# resource.ini

[DEFAULT]
key1 = value1
key2 = value2
key3 = values

[filter:logrequest]
username = root
password = root123
paste.filter_factory = resource:LogFilter.factory

[app:router]
paste.app_factory = resource:Router.factory  # 注意这里是 Router 而不是 UserController 之类的 Controller

[pipeline:router_pipeline]
pipeline = logrequest router

[composite:main]
use = egg:Paste#urlmap
/ : router_pipeline     # 注意，如果我们这里写为 /router : router_pipeline，那这里的 router 实际是
                        # 给 PasteDeploy 匹配用的，在传给 Router 时，这个 URL 中的 router 会被去掉，
                        # 也就是说，如果我们想访问 UserController，那我们的 URL 就要写为 
                        # GET http://ip:port/router/users/id。一般情况下，我们是不用这么做的，直接用“/”就可以了。

                        # 另外，我们一般会有多个版本的 API，这里如写为 /v1 : router_pipeline 就很适合，
                        # 这样我们在最外层就已经做了 API 版本分流，而不用在 Router 里边分流。

源码：

# resource.py

import os
import webob.dec
import webob.exc
import routes.middleware
from paste.deploy import loadapp
from wsgiref.simple_server import make_server


# Environment variable used to pass the request context
CONTEXT_ENV = 'openstack.context'

# Environment variable used to pass the request params
PARAMS_ENV = 'openstack.params'


class LogFilter(object):
    def __init__(self, app):
        self.app = app

    @webob.dec.wsgify
    def __call__(self, req):
        print 'filter:LogFilter is called.'
        return self.app

    @classmethod
    def factory(cls, global_conf, **kwargs):
        print 'in LogFilter.factory', global_conf, kwargs
        return cls	# 注意 PasteDeploy 流水线中间件返回的不是类实例，因为它还要用于应用初始化（__init__(self, app)）


class BaseController(object):
    def _normalize_arg(self, arg):
        return arg.replace(':', '_').replace('-', '_')

    def _normalize_dict(self, d):
        return {self._normalize_arg(k): v for (k, v) in d.items()}

    def _render_response(self, body=None, status=None, method=None):
        '''Form a WSGI response.'''
        resp = webob.Response(body=body, status=status)
        resp.method = method
        return resp

    @webob.dec.wsgify
    def __call__(self, req):
        arg_dict = req.environ['wsgiorg.routing_args'][1]
        action = arg_dict.pop('action')
        del arg_dict['controller']

        params = req.environ.get(PARAMS_ENV, {})
        params.update(arg_dict)

        method = getattr(self, action)
        params = self._normalize_dict(params)
        result = method(req, **params)

        return self._render_response(body=result.body, status=result.status, method=req.method)


class UserController(BaseController):

    def index(self, req):
        msg = 'in UserController.index'
        print msg
        return webob.Response(msg)

    def create(self, req):
        msg = 'in UserController.create'
        print msg
        return webob.Response(msg)

    def show(self, req, id):    # The same with get_user(self, req, id)
        msg = 'in UserController.show'
        print msg
        return webob.Response(msg)

    def update(self, req, id):
        msg = 'in UserController.update'
        print msg
        return webob.Response(msg)

    def delete(self, req, id):
        msg = 'in UserController.delete'
        print msg
        return webob.Response(msg)

    def ask_delete(self, req, id):  # Special action
        msg = 'in UserController.ask_delete'
        print msg
        return webob.Response(msg)


class TenantController(BaseController):
    def get_tenant(self, req, tenant_id):
        return webob.Response('I am a tenant, my ID is %s.' % tenant_id)


class Router(object):
    def __init__(self):
        self._mapper = routes.Mapper()
        self._mapper.resource('user', 'users',
                              controller=UserController(),
                              member={'ask_delete': 'DELETE'})
        self._mapper.connect('/tenants/{tenant_id}',
                             controller=TenantController(),
                             action='get_tenant',
                             conditions={'method': ['GET']})

        self._router = routes.middleware.RoutesMiddleware(self._dispatch, self._mapper)

    @webob.dec.wsgify
    def __call__(self, req):
        return self._router

    @staticmethod
    @webob.dec.wsgify
    def _dispatch(req):
        match = req.environ['wsgiorg.routing_args'][1]

        if not match:
            return webob.exc.HTTPNotFound()

        app = match['controller']
        return app

    @classmethod
    def factory(cls, global_conf, **kwargs):
        print 'in Router.factory', global_conf, kwargs
        return cls()	# PasteDeploy 流水线最终应用，直接返回类实例即可

if __name__ == '__main__':
    app_name = 'main'
    config_file = 'resource.ini'
    wsgi_app = loadapp('config:%s' % os.path.abspath(config_file), app_name)
    server = make_server('localhost', 8080, wsgi_app)
    server.serve_forever()

先这样吧，有需要再继续改进！