handler specs
handler 规范
1 代码分层设计
MVC 的 View 已经单独剥离出去,
而剩下的 MC, 也逐渐演变成了 CSDM
controller-->service-->dao---->model
|
+------>sdk---->第三方服务butterfly
├── conf
│ ├── fx
│ │ └── <app>_<resource>_<action>.toml
│ ├── app
│ │ └── <app>.toml
│ └── servicer
│ ├── mysql_<servicer>.py # 第三方服务配置
│ ├── redis_<servicer>.py # 第三方服务配置
│ └── xx_<xxx>.py # config
└── handlers
└── <app>
├── api_<resource>_<action1>.py # controller
├── api_<resource>_<action2>.py # controller
├── lib_<servicer>.py # service
├── model_xxx.py # dao/model
├── sdk_xxx.py # 第三方服务
├── retstat.py # handler 返回值状态字段
├── const.py # handler 常量定义，避免出现魔数(Magic number)
└── __init__.py1.1 函数命名
<资源>_<行为>2 接口规范
默认
返回值如果是 dict 则会自动转换为 json 协议，即响应头 ("Content-Type","application/json")
否则则会返回 HTML 格式，即响应头 ("Content-Type","text/html")json(JavaScript Object Notation)
如下接口规范参考 baidu/NoahV 接口规范
2.1 接口格式组成
Butterfly 框架接口返回包含状态信息字段 stat 和数据信息字段 data
关于状态字段
butterfly 默认以 stat 作为状态信息字段
butterfly-fe 前端支持后端以 stat(str) 或者 code(int) + message(str) 方式作为状态信息返回数据即以下通用接口，如果使用其他框架实现后端逻辑，同时要对接 butterfly-fe 时，可以将返回接口中的 stat(str), 替换为 code(int) + message(str)
例子
// butterfly
{
"stat": "OK",
"data": {}
}
// 使用其他框架，接入 butterfly-fe 的话，也可以使用如下实现
{
"code": 0,
"message": "success",
"data": {}
}2.2 接口格式例子
2.2.1 通用接口格式
请求成功接口格式
{
"stat": "OK", // str
"data": {name: "liming"} // object
{list: [{name: "liming"}, {name: "fengchengcheng"}]}
{} // 如果是提交表单这类 API，没有数据需要返回的话，可以返回空的 object
}请求失败接口格式
{
"stat": "ERR", // str
"data": {} // 空的 object
}2.2.2 登录跳转接口格式
登录跳转接口
当接口有鉴权，前端请求数据发现权限校验不通过时，需要让用户跳转到登录地址，因为是 ajax 请求，如果直接返回 302，登录地址和当前地址不一致时候，可能存在跨域问题。
这时候要求接口按照如下格式返回数据，前端在收到对应数据格式之后，在前端做跳转，绕过跨域问题。
{
"stat": "ERR_UNAUTHORIZED", // str
"data": {
'redirect': 'http://xx.baidu.com' // 需要跳转到的登录页
}
}2.2.3 表格分页数据接口格式
适用于需要后端分页的情况
参数
page_index: 页索引, 从 1 开始
page_size : 每页展示个数GET /products?page_index=1&page_size=15
{
"stat": "OK", // str
"data": {
"list": [{...}], // 具体数据
"total": 20, // 总数
}
}2.2.4 图表展示接口格式
适用于前端展示图表数据
{
"stat": "OK", // str
"data": {
"list": [
{
"key": "2020-04-30",
"value": 25, // int
},
{
"key": "2020-05-01",
"value": 22,
},
{
"key": "2020-05-02",
"value": 23,
}
],
"name": "异常实例个数", // list 中的 value 说明
"title": "异常实例统计" // 图表标题
}
}3 装饰器
3.1 handler 装饰器
# coding=utf8
"""
# Description:
api demo
"""
import logging
from xlib import retstat
from xlib.util import wrapt
from xlib.util import funcsigs
from xlib.middleware import funcattr
from xlib.httpgateway import Request
__info = "demo"
__version = "1.0.1"
logger = logging.getLogger("service")
def requested(method):
"""
装饰器：限制请求方法
"""
@wrapt.decorator
def wrapper(wrapped, instance, args, kwargs):
"""
Args:
- wrapped：被装饰的函数或类方法
- instance：
- 如果被装饰者为普通类方法，该值为类实例
- 如果被装饰者为 classmethod 类方法，该值为类
- 如果被装饰者为类/函数/静态方法，该值为 None
- args：调用时的位置参数（注意没有 * 符号）
- kwargs：调用时的关键字参数（注意没有 ** 符号）
"""
# 提取原 func 中的 req, 不论使用位置参数还是关键字参数
sig = funcsigs.signature(wrapped)
kargs = dict(zip([k for k in sig.parameters if k not in kwargs], args))
req = kargs.get("req", kwargs.get("req"))
if req.wsgienv.get("REQUEST_METHOD") != method:
req.error_str = "method not support"
return retstat.ERR, {}, [(__info, __version)]
return wrapped(*args, **kwargs)
return wrapper
@funcattr.api
@requested("GET")
def hello(req, str_info):
"""
demo
"""
isinstance(req, Request)
logger.info("str_info={str_info}".format(str_info=str_info))
return retstat.OK, {"str_info": str_info}, [(__info, __version)]Last updated