一个基于werkzeug
和jinja2
的web
框架,简单易用、架构清晰、模块化。
使用如下命令安装KaKa:
pip install KaKa
使用如下命令将框架引入你的项目:
from kaka import KaKa
使用如下语句实例化一个KaKa
应用对象:
app = KaKa()
使用如下语句定义一个简单的视图函数,此函数将会接受http
请求并返回一个简单的hello world
字符串:
from kaka.response import TextResponse
def hello(request):
return TextResponse('hello world')
使用如下语句定义一个路由表以指导http
请求的正确路由:
app.router.register([
('index/', hello),
])
执行如下语句启动服务器,KaKa
会帮助我们启动底层的WSGI
服务器,默认地址是127.0.0.1
,端口号是8888
:
app.run_server()
KaKa
为run_server
接口提供了一个debug
参数,默认值是False
,若置为True
则会启动debug
模式。
在debug
模式中,任何对源代码的修改都将自动重启服务器,且一旦发生了错误将会在浏览器上以页面的形式显示出错误栈信息。
可以这样开启debug
模式:
app.run_server(debug=True)
打开浏览器并访问http://127.0.0.1:8888/index/
,你将会看到视图函数返回的hello world
字符串。
然而,一个简单的hello world
页面是不足以解决我们的问题的,下面是KaKa
框架目前支持的功能介绍和使用说明。
路由系统是web
框架最核心的功能之一,KaKa
使用术语路由器
和路由表
来描述路由系统。
KaKa
的路由系统底层引用了Werkzeug
的Map
和Rule
模块。
一张路由表由一个元组列表表示,其中的元组代表着路由条目信息。
KaKa
设定路由条目由3
个参数组成:url, view, name
,其中name
可以不提供。
但若为name
提供了一个值,你就可以通过reverse
函数来反向解析url
,像这样:
from kaka.utils import reverse
# 路由表
table = [
('index/', index_view), # 路由条目1
('articles/', article_view), # 路由条目2
('home/', home_view, 'home'), # 路由条目3
]
url = reverse('home') # url的值是: '/home/'
如果url
中有动态的元素,KaKa
也可以处理,动态元素将会作为视图函数的参数传入,就像这样:
table = [
('articles/<int:id>/', show_articles, 'article'),
]
KaKa
的路由系统还支持多级路由,这一部分的介绍和使用我将会放到产品文档中。
视图系统是处理http
请求并返回http
响应的地方。
KaKa
为所有的视图函数提供了一个request
第一参数,代表当前的请求对象,用户可以通过此对象访问有底层请求环境的相关数据。
KaKa
使用TextResponse
类来封装字符串形式的返回值,这种返回值的mimetype=text/plain
,所以它不会被浏览器当做html
页面渲染,而是直接打印字符串。
像这样使用视图系统:
from kaka.response import TextResponse
def show_articles(request, nid):
print(request.path)
print(request.cookies)
print(request.method)
print(nid)
return TextResponse('show articles view')
模板渲染功能可以让我们方便的制造含有动态元素的html
页面。
在渲染功能上,KaKa
目前没有做太多事情,仅是在底层引用了jinja2
模块并为模板渲染过程提供了一层方便调用的接口。
在使用渲染功能前首先定义模板文件目录:
# 设定模板文件所在目录
template_path = 'your template directory'
app.render.register(template_path)
KaKa
为用户提供了一个RenderResponse
响应对象,其底层调用了jinja2
的渲染接口。
渲染的结果类型将会是mimetype=text/html
,所以浏览器会将结果当做html
页面渲染并展示。
from kaka.response import RenderResponse
# 在视图函数中使用模板渲染功能
def show_articles(request, id):
title = 'hello kaka'
content = 'a web framework'
return RenderResponse('article.html', title=title, content=content)
当然,KaKa
也支持Restful
形式的请求处理,KaKa
使用了一个RestView
来帮助分发请求,像这样定义restful
的视图函数:
from kaka.restful import RestView
# 定义restful形式的处理视图,必须以类的形式定义
class ArticlesView(RestView):
def get(self, request, id):
pass
def post(self, request)
pass
... # 其他与http method同名的函数
restful
的视图函数可以像这样添加到路由表中:
table = [
('index/', index),
('articles/', ArticlesView.restful, 'article), # 使用类名.restful即可
]
KaKa
除了支持restful
的请求之外还支持restful
的响应,使用了RestResponse
响应类,它的mimetype=application/json
, 所以一个restful
响应的使用和样式是这样的:
from kaka.restful import RestView
from kaka.response import RestResponse # restful风格的响应类
class ArticlesView(RestView):
def get(self, request, id):
data = {'title': 'hello kaka', 'content': 'a web framework'}
extra_dict = {
'data': data,
}
return RestResponse(code=1200, status='success', extra_dict=extra_dict)
# 这样的响应在浏览器中看起来是这样的:
{
"code": 1200,
"status": "success",
"data": {
"title": "hello kaka",
"content": "a web framework"
}
}
在restful
的支持上,KaKa
还提供了更高一层的SUCCESS
和FAIL
接口,为用户提供了更加方便的操作restful
响应的形式,不过这两个接口的介绍和使用说明我将会放到产品文档中。
KaKa
提供了中间件系统,让用户可以在视图处理前和处理后对请求(或响应)对象完成必要的中间操作。
我认为中间件系统的主要目的是修改流经的请求或响应对象,而不是伪造一个新的对象,这意味着KaKa
提供的中间件系统的处理机制是这样的:
-
视图前
KaKa
的中间件系统在视图前的处理只允许返回None
或一个响应对象(这意味着后续中间件不再有机会处理请求,视图函数也是)。换句话说,返回None
意味着中间件仅仅对请求对象执行修改操作而不是替换它,返回一个响应对象意味着中间件拦截了这个请求并直接返回。 -
视图后
KaKa
的中间件系统在视图后的处理只允许返回None
,这意味着中间件只能修改响应对象而不能替换它。
关于中间件系统的详细设计思路和结构请参考产品文档。
我们可以通过这种方式自定义一个中间件:
from kaka.middlewares import AbstractMiddleWare # 抽象中间件类,用于约束处理接口
from kaka.response import TextResponse
class MyMiddleWare(AbstractMiddleWare):
def pre_process(self, request):
print('对请求对象做各种修改操作')
return None
# 如果要拦截当前请求,则这样写:
# return TextResponse('中间件拦截请求,直接返回响应对象')
def after_process(self, request, response):
print('对响应对象做各种修改操作', response)
return None
然后通过中间件管理器注册这个中间件以使其生效:
import MyMiddleWare
app.mw_manager.register([
(5, MyMiddleWare), # priority, cls
])
其中,5
是表示优先级的数字,最小为0,最大无限制,数字越小优先级越高。
如果定义了多个中间件(很常见的情况),则它们的处理顺序是这样的:
app.mw_manager.register([
(5, MW1),
(7, MW2),
(9, MW3),
])
# 视图前:MW1处理请求 -> MW2处理请求 -> MW3处理请求
# 视图后:MW3处理响应 -> MW2处理响应 -> MW1处理响应
KaKa
对请求对象和响应对象均设置了一个storage
属性用以共享数据,它使用起来像这样:
# 请求中间件中的使用
def pre_process(self, request):
request.storage['is_handled'] = True
return None
# 视图中的使用
def show_articles(request):
print(request.storage.get('is_handled'))
response = TextResponse('hello world')
response.storage['name'] = 'kaka'
return response
# 响应中间件中的使用
def after_process(self, request, response):
print(request.get('is_handled'))
print(response.get('name'))
return None