单机使用手册

1 服务管理

1.1 配置管理

1.1.1 配置全览

conf/config.py(APP 配置)

# coding:utf8
"""
Butterfly config
"""
import os

# Build paths inside the project like this: os.path.join(BASE_DIR, ...)
BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

SERVER_LISTEN_ADDR = ("0.0.0.0", 8585)
SERVER_THREAD_NUM = 16
SERVER_NAME = "Butterfly_app"
# Reqid prefix, two characters
SERVER_ID = "BF"
SERVER_IDC = "default"

# static
STATIC_PATH = "static"
STATIC_PREFIX = "static"

# DB
"""
# wuxing/ruqi use default database
"""
DATABASES = {
    "default": "mysql+retrypool://root:password@127.0.0.1:3306/test?max_connections=300&stale_timeout=300",
}

# Redis
"""
# eg1:"redis://[[username]:[password]]@localhost:6379/0"
# eg2:"redis://@localhost:6379/0?socket_timeout=2&socket_connect_timeout=1&retry_on_timeout=true"
"""
CACHES = {
    "default": "redis://@localhost:6379/0",
    # for cache: connect_timeout 100ms, read_timeout 200ms
    # "wuxing": "redis://@localhost:6379/0?socket_timeout=0.2&socket_connect_timeout=0.1&retry_on_timeout=false",
    # for mq: connect_timeout 500ms, read_timeout 2000ms
    # "baichuan": "redis://@localhost:6379/0?socket_timeout=2&socket_connect_timeout=0.5&retry_on_timeout=false",
}

# Local data or cache
LOCALDATA_DIR = os.path.join(BASE_DIR, "data")

# Auth
SECRET_KEY = None               # If it is None, a key will be randomly generated each time butterfly is started
JWT_TOKEN_TTL = 28800           # default 8 hours
HEADER_USERNAME = "HTTP_X_USERNAME"

# Scheduler
scheduler_store = "memory"      # ("mysql"/"memory")

# Adaptor
"""
# {"stat":"ERR", "data":{}} --> {"stat":"ERR", "success":False, "message":"ERR", "data":{}}
STAT_ADAPTOR={"status_name":"success", "status_map":{"OK":True,"default":False}, "message_name":"message"}
"""
STAT_ADAPTOR = None

config/logger_conf.py(日志配置)

# coding:utf8
"""
初始化配置日志

acclog : Butterfly 访问日志
errlog : Butterfly 错误日志
initlog: Butterfly 启动相关信息
"""
import os
import logging

from xlib import logger
from conf import config

# --------------------------LOG PATH-----------------------------
LOG_SIZE_LIMIT = 1024 * 1024 * 2
LOG_BATCH_WRITE = 0
PATH_INIT_LOG = os.path.join(config.BASE_DIR, "logs/init.log")
PATH_ACC_LOG = os.path.join(config.BASE_DIR, "logs/acc.log")
PATH_INFO_LOG = os.path.join(config.BASE_DIR, "logs/info.log")
PATH_WARNING_LOG = os.path.join(config.BASE_DIR, "logs/warning.log")
PATH_ERR_LOG = os.path.join(config.BASE_DIR, "logs/err.log")
PATH_CRIT_LOG = os.path.join(config.BASE_DIR, "logs/crit.log")

PATH_COMMON_LOG = os.path.join(config.BASE_DIR, "logs/common.log")
PATH_SCHEDULER_LOG = os.path.join(config.BASE_DIR, "logs/scheduler/scheduler.log")
PATH_SCHEDULER_WORKER_LOG = os.path.join(config.BASE_DIR, "logs/scheduler/scheduler-worker.log")

PATH_SERVICE_LOG = os.path.join(config.BASE_DIR, "logs/service.log")
PATH_RAL_LOG = os.path.join(config.BASE_DIR, "logs/ral/ral-worker.log")

# --------------------------LOG logger---------------------------
# 通用 logging 初始化( root logger ), 此日志没有 reqid
logger.init_log(PATH_COMMON_LOG)
# Butterfly scheduler 日志初始化, 此日志没有 reqid
logger.init_log(PATH_SCHEDULER_LOG, logger_name="apscheduler", level=logging.INFO)
logger.init_log(PATH_SCHEDULER_WORKER_LOG, logger_name="apscheduler_worker", level=logging.INFO)

# Butterfly service 日志初始化, 此日志含有 reqid
logger.init_bf_log(PATH_SERVICE_LOG, logger_name="service")
# Butterfly ral 日志初始化(Resource Access Layer), 此日志含有 reqid
logger.init_bf_log(PATH_RAL_LOG, logger_name="ral", level=logging.DEBUG)

critlog = logger.LoggerBase(PATH_CRIT_LOG, False, LOG_SIZE_LIMIT, LOG_BATCH_WRITE)
errlog = logger.LoggerBase(PATH_ERR_LOG, False, LOG_SIZE_LIMIT, LOG_BATCH_WRITE)
warninglog = logger.LoggerBase(PATH_WARNING_LOG, False, LOG_SIZE_LIMIT, LOG_BATCH_WRITE)
infolog = logger.LoggerBase(PATH_INFO_LOG, False, LOG_SIZE_LIMIT, LOG_BATCH_WRITE)
acclog = logger.LoggerBase(PATH_ACC_LOG, False, LOG_SIZE_LIMIT, LOG_BATCH_WRITE)
initlog = logger.LoggerBase(PATH_INIT_LOG, False, LOG_SIZE_LIMIT, LOG_BATCH_WRITE)

1.1.2 SERVER

SERVER_LISTEN_ADDR = ("0.0.0.0", 8585)  # 监听端口
SERVER_THREAD_NUM = 16                  # 线程数
SERVER_NAME = "Butterfly_app"           # 服务名标识，用于百川 worker

1.1.3 LOG

LOG_SIZE_LIMIT = 1024 * 1024 * 2                                    # 日志大小，大于此值时，日志文件将会被清空
LOG_BATCH_WRITE = 0
PATH_INIT_LOG = os.path.join(BASE_DIR, "logs/init.log")             # 启动日志，记录 handler 信息等
PATH_ACC_LOG = os.path.join(BASE_DIR, "logs/acc.log")               # 访问日志
PATH_INFO_LOG = os.path.join(BASE_DIR, "logs/info.log")
PATH_WARNING_LOG = os.path.join(BASE_DIR, "logs/warning.log")
PATH_ERR_LOG = os.path.join(BASE_DIR, "logs/err.log")               # 错误日志
PATH_CRIT_LOG = os.path.join(BASE_DIR, "logs/crit.log")
PATH_COMMON_LOG = os.path.join(BASE_DIR, "logs/common.log")         # logging 日志
PATH_COMMON_BF_LOG = os.path.join(BASE_DIR, "logs/common_bf.log")   # logging 日志

1.1.4 STATIC

STATIC_PATH = "static"                  # 静态文件路径，默认为 {butterfly_project}/static/{file_path}
STATIC_PREFIX = "static"                # 静态文件前缀，判断请求 URL 是否为请求静态文件

1.1.5 DB

"""
# wuxing/ruqi use default database
"""
DATABASES = {
    "default": "mysql+retrypool://root:password@127.0.0.1:3306/test?max_connections=300&stale_timeout=300",
}

1.1.6 Redis

"""
# eg1:"redis://[[username]:[password]]@localhost:6379/0"
# eg2:"redis://@localhost:6379/0?socket_timeout=2&socket_connect_timeout=1&retry_on_timeout=true"
"""
CACHES = {
    "default": "redis://@localhost:6379/0",
    # for cache: connect_timeout 100ms, read_timeout 200ms
    # "wuxing": "redis://@localhost:6379/0?socket_timeout=0.2&socket_connect_timeout=0.1&retry_on_timeout=false",
    # for mq: connect_timeout 500ms, read_timeout 2000ms
    # "baichuan": "redis://@localhost:6379/0?socket_timeout=2&socket_connect_timeout=0.5&retry_on_timeout=false",
}

1.1.7 LOCALDATA

LOCALDATA_DIR = os.path.join(BASE_DIR, "data")

存储本地数据目录

1.1.8 AUTH

SECRET_KEY = None                   # If it is None, a key will be randomly generated each time butterfly is started
JWT_TOKEN_TTL = 28800               # default 8 hours
HEADER_USERNAME = "HTTP_X_USERNAME"

SECRET_KEY : jwt SECRET_KEY
JWT_TOKEN_TTL : jwt token ttl
HEADER_USERNAME : 用户名 handler
- 请求方法：若此项配置的 "HTTP_X_USERNAME" 则请求时可传 -H "x_username:meetbill" header

1.1.9 Scheduler

scheduler_store = "memory"      # ("mysql"/"memory")

主要用于【如期】使用

1.1.10 Adaptor

"""
# {"stat":"ERR", "data":{}} --> {"stat":"ERR", "success":False, "message":"ERR", "data":{}}
STAT_ADAPTOR={"status_name":"success", "status_map":{"OK":True,"default":False}, "message_name":"message"}
"""
STAT_ADAPTOR = None

用于扩展 API 接口的状态字段

STAT_ADAPTOR 需要有三个信息

status_name: 状态名
status_map: 状态映射，默认值为 "default" value, 若可以匹配到映射中的值，则以映射值为值
message_name: 信息名

1.2 启动管理

Usage: run.sh {start|stop|restart|status}
 start          Start butterfly processes.
 docker_start   Start butterfly processes for docker.
 stop           Kill all butterfly processes.
 restart        Kill all butterfly processes and start again.
 status         Show butterfly processes status.

备注：bash run.sh docker_start 用于打 docker 镜像时使用

如何修改启动项标识

在日常使用中可能会在同一台机器上启动多个 butterfly，不同的 butterfly 提供着不同的服务，可能是测试服务，可能是做配置管理服务使用的，等等，当然这些 butterfly 的端口是不一样的，那如何根据进程看出是什么服务尼？

只需要在服务启动前修改下，run.sh 的 PROC_SIG="954216e9" 修改为想要使用的用途即可，比如 PROC_SIG="test_dev"

注：此项修改需要在服务启动前修改，因为 run.sh 对进程的管理，也会对 PROC_SIG 进行匹配

1.3 日志管理

1.3.1 启动日志

启动相关信息日志会记录在 __stdout

如果启动失败，可以在这个日志文件中找到原因

1.3.2 butterfly 框架日志

1.3.2.1 acc 访问日志

acc 日志路径在 logs/acc.log

日志内容

2021-02-08 21:35:30    91640    /meetbill/butterfly/xlib/httpgateway.py:259    127.0.0.1    1FA15BDE4B6CD7A0    GET    /demo_api/hello    cost:0.000162    stat:OK    user:-    talk:ceshi1=0.098;ceshi2=0.002    params:str_info=hello    error_msg:    res:ceshi2=5.4;ceshi1=5.3

备注：
(1) access 日志中各 field 使用 '\t' 进行分割
(2) COST，STAT，USER，TALK，PARAMS，ERROR_MSG，RES field 会有 field 前缀，使用 `:` 进行分割
    field 中多个 item 使用 `;` 进行分割，每个 item 使用 `=` 进行分割 item_name 和 item_value
    即：{field_prefix}:{item_name1}={item_value1};{item_name2}={item_name2}
    如：talk:ceshi1=0.098;ceshi2=0.002

DATE: 2021-02-08
TIME: 21:35:30
PID : 91640
CODE_INFO: /meetbill/butterfly/xlib/httpgateway.py:259
IP: 127.0.0.1
REQID: 1FA15BDE4B6CD7A0 （请求 ID)
METHOD: GET
PATH: /demo_api/hello
COST: cost:0.000162 （整体耗时，单位是秒）
STAT: stat:OK （执行结果状态，若自定义 HTTP 方式时，则此处会是 HTTP 状态码）
USER: user:- （用户名）
TALK: talk:ceshi1=0.098;ceshi2=0.002 （代码片段耗时，比如一个 SQL 语句，请求 Redis 的耗时等）
PARAMS: params:str_info=hello （请求参数）
ERROR_MSG: error_msg:（错误信息）
RES: res:ceshi2=5.4;ceshi1=5.3 （需要记录的结果数据信息）

在 handler 逻辑中可以通过如下方式写入日志到 logs/acc.log

记录额外参数

req.log_params["x"] = 1

记录程序运行耗时

# req.start_timming() 为可选项，若不加此语句，则默认以本次请求开始记录耗时
req.start_timming()
...
req.timming("ceshi1") # 会记录 req.start_timming() 到此行的耗时
...
req.timming("ceshi2") # 会记录 req.timming("ceshi1") 到 req.timming("ceshi2") 间的耗时

将会打印日志如下：
ceshi1=0.001;ceshi2=0.003

记录错误信息（推荐）

req.error_str = err_msg

使用此方式，错误日志不但可以记录到 acc.log , 而且响应头中也会返回给客户端此信息，如下：

reply: 'HTTP/1.1 200 OK\r\n'
header: ruqi: 1.0.1
header: Content-Length: 15
header: butterfly: 1.1.4
header: x-reqid: 3B2BBCF470912A79
header: x-cost: 7.732843
header: x-reason: u'Job identifier (test1) conflicts with an existing job'
header: Connection: close
header: Date: Sat, 02 Jan 2021 01:18:47 GMT
header: Server: XXXXXXXXXXXXXXXX
{u'stat': u'ERR'}

记录 response 信息

req.log_res:(set)

代码：
req.log_res.add("test1=info")

日志：
... res:test1=info

1.3.2.2 err 异常日志

err 日志路径在 logs/err.log

例子（不常用，主要用于 butterfly 框架捕获未处理的异常逻辑使用）

req.log(self._errlog, "Json dump failed\n%s" % traceback.format_exc())

req.log 用于记录异常日志以及其他类型日志，日志中会记录 reqid, 需要传入 logger 和日志信息

1.3.2.3 init 日志

init 日志路径在 logs/init.log, 日志中会记录如下信息

日志中会打印自动加载的 handler 的日志信息
如果开启了 scheduler, 则打印 scheduler 是否启动成功

1.3.3 自定义日志输出

acc.log 和 err.log 均为框架本身产生的日志，用于接口统计以及服务异常排查问题等等

这里的自定义日志内容有两种方式

将需要的日志，通过接口写入到 acc.log
使用 logging 模块『推荐』，将日志写入 common.log 和 common.log.wf

这个来说明下如何使用 logging 将日志写入 common.log 和 common.log.wf

from xlib import retstat
from xlib.middleware import funcattr
import logging

logger = logging.getLogger("service")

__info = "test_api"
__version = "1.0.1"

@funcattr.api
def hello(req, str_info):
    isinstance(req, Request)
    # 打印 info log
    logger.info("test info log")
    # 打印 error log
    logger.error("test error log")
    return retstat.OK, {"data": {"str_info": str_info}}, [(__info, __version)]

备注：

如果使用了 logging 日志记录方式
(1) 默认 info 级别以上的 logging 日志都会打印到 config.py 设置的 PATH_COMMON_LOG = "logs/common.log" 日志中
(2) 默认 error 级别以上的 logging 日志都会打印到 logs/common.log.wf 中
(3) 如果是用户发起的请求 (handler 应用程序），logging 日志中会默认加上 reqid, 如果没有获取到 reqid（比如 Main 线程） 则会打印 "XXXXXXXXXXXXXXXX"

2 接口开发

2.1 编写函数（根据返回值，区分为两种方式）

2.1.1 推荐方式

(1) 函数文件

handlers/demo_api/__init__.py

例子

@funcattr.api
def hello(req, str_info):
    """
    带参数请求例子

    Args:
        req     : Request
        str_info: (str)
    Returns:
        json_status, Content, headers
    """
    isinstance(req, Request)
    return retstat.OK, {"str_info": str_info}, [(__info, __version)]

返回值分别为：状态信息字段，数据信息字段, 自定义 HTTP 报文头信息列表

2.1.2 自定义 HTTP 码返回方式

(1) 函数文件

handlers/demo_httpapi/__init__.py

(2) 编写对应方法

参数
- 第一个参数为 req, 固定
返回值 (httpstatus, [content], [headers])
- httpstatus: (int) 必须有
- content: (str/dict) 非必须（当返回值为 2 个的时候，第 2 个返回值为 Content)
  - 当 content 为 dict 时，会自动转为 json ，并且设置 header("Content-Type","application/json")
  - 当 content 为其他时，会自动设置为 ("Content-Type","text/html")
- headers: 非必须（当返回值为 3 个的时候，第 3 个返回值为 headers)
  如：
  def hello(req, str_info): isinstance(req, Request) return retstat.HTTP_OK, {"stat":"OK","str_info": str_info}, [(__info__, __version__)]
  返回值分别为：HTTP 返回码，状态信息字段 + 数据信息字段, 自定义 HTTP 报文头信息列表

2.2 路由注册

(1) 函数文件

wsgiapp.py

handlers package 和 handlers 下的 package 都会默认注册到路由中

2.3 访问接口函数

get 请求

Request:

curl -v "http://ip:port/demo_api/hello?str_info=happy"

如：
curl -v "http://127.0.0.1:8585/demo_api/hello?str_info=happy"

同时可以使用 -v 查看额外 headers 信息，如下：

Response:

* Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to 127.0.0.1 (127.0.0.1) port 8585 (#0)
> GET /demo_api/hello?str_info=happy HTTP/1.1
> Host: 127.0.0.1:8585
> User-Agent: curl/7.54.0
> Accept: **/**
>
< HTTP/1.1 200 OK
< meetbill: 1.0.1  --------------------------------- 函数中返回的 headers 信息
< Content-Length: 35 ------------------------------- Content 的长度
< butterfly: 1.1.3 --------------------------------- Butterfly 版本信息
< x-reqid: C31582ED1FBBFA2D ------------------------ 请求 id，此 id 会打印到日志文件中
< x-cost: 0.003114 --------------------------------- 耗时 (time.time() UNIX 时间戳
<                                                    格林尼治时间 1970 年 01 月 01 日 00 时 00 分 00 秒 起至现在的总秒数之差）
< Date: Mon, 04 Mar 2019 09:33:26 GMT
< Server: XXXXXXXXXXXXXXXX
<
* Connection #0 to host 127.0.0.1 left intact
{"stat": "OK", "str_info": "happy"}%

post 请求

request:

curl -v   -d '{"str_info":"happy"}' http://127.0.0.1:8585/demo_api/hello

Response:

* Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to 127.0.0.1 (127.0.0.1) port 8585 (#0)
> POST /demo_api/hello HTTP/1.1
> Host: 127.0.0.1:8585
> User-Agent: curl/7.54.0
> Accept: */*
> Content-Length: 20
> Content-Type: application/x-www-form-urlencoded
>
* upload completely sent off: 20 out of 20 bytes
< HTTP/1.1 200 OK
< meetbill: 1.0.1
< Content-Length: 35
< butterfly: 1.1.3
< x-reqid: 1A805D21CC791F3E
< x-cost: 0.000142
< Date: Mon, 04 Mar 2019 11:48:04 GMT
< Server: XXXXXXXXXXXXXXXX
<
* Connection #0 to host 127.0.0.1 left intact
{"stat": "OK", "str_info": "happy"}

备注 1 ：JSON 格式数据属性必须用双引号包裹

var json = '{"name":"imooc"}'; // 这个是正确的 JSON 格式
var json = "{\"name\":\"imooc\"}"; // 这个也是正确的 JSON 格式
var json = '{name:"imooc"}'; // 这个是错误的 JSON 格式，因为属性名没有用双引号包裹
var json = "{'name':'imooc'}";// 这个也是错误的 JSON 格式，属性名用双引号包裹，而它用了单引号

备注 2 ：可传多级 json

# Request:
curl -d '{"str_info":{"field1": "value1", "field2": "value2"}}' http://127.0.0.1:8585/demo_api/hello

# Response:
{"stat": "OK", "str_info": {"field2": "value2", "field1": "value1"}}

python post 方式提交 json 字符串

import urllib2
import json

data = {"str_info":"hello info"}

headers = {'Content-Type':'application/json'}
request = urllib2.Request(url='http://127.0.0.1:8585/demo_api/hello',headers=headers,data=json.dumps(data))
response = urllib2.urlopen(request)

print response.read()

2.4 handler 访问本目录文件

通过 cur_path 与文件进行拼接

cur_path = os.path.split(os.path.realpath(__file__))[0]

3 手动测试 handler

测试方法

$ python test_handler.py

Previous五分钟体验指南 Next应用规范

Last updated 1 year ago

hashtag1 服务管理

hashtag1.1 配置管理

hashtag1.1.1 配置全览

hashtag1.1.2 SERVER

hashtag1.1.4 STATIC

hashtag1.1.5 DB

hashtag1.1.6 Redis

hashtag1.1.7 LOCALDATA

hashtag1.1.8 AUTH

hashtag1.1.9 Scheduler

hashtag1.1.10 Adaptor

hashtag1.2 启动管理

hashtag如何修改启动项标识

hashtag1.3 日志管理

hashtag1.3.1 启动日志

hashtag1.3.2 butterfly 框架日志

hashtag1.3.3 自定义日志输出

hashtag2 接口开发

hashtag2.1 编写函数（根据返回值，区分为两种方式）

hashtag2.1.1 推荐方式

hashtag2.1.2 自定义 HTTP 码返回方式

hashtag2.2 路由注册

hashtag2.3 访问接口函数

hashtagget 请求

hashtagpost 请求

hashtagpython post 方式提交 json 字符串

hashtag2.4 handler 访问本目录文件

hashtag3 手动测试 handler

1 服务管理

1.1 配置管理

1.1.1 配置全览

1.1.2 SERVER

1.1.4 STATIC

1.1.5 DB

1.1.6 Redis

1.1.7 LOCALDATA

1.1.8 AUTH

1.1.9 Scheduler

1.1.10 Adaptor

1.2 启动管理

如何修改启动项标识

1.3 日志管理

1.3.1 启动日志

1.3.2 butterfly 框架日志

1.3.3 自定义日志输出

2 接口开发

2.1 编写函数（根据返回值，区分为两种方式）

2.1.1 推荐方式

2.1.2 自定义 HTTP 码返回方式

2.2 路由注册

2.3 访问接口函数

get 请求

post 请求

python post 方式提交 json 字符串

2.4 handler 访问本目录文件

3 手动测试 handler