kksanic 0.1.0__py3-none-any.whl

kksanic/__init__.py

@@ -0,0 +1,187 @@
+"""kksanic —— 基于 Sanic + Tortoise 的小工具箱。
+
+包根只导出最常用的入口，其余按模块取：
+
+    from kksanic import Request          # 等价于 from kksanic.request import Request
+    from kksanic import Validator, Rule  # 等价于 from kksanic.validator import ...
+    from kksanic import ApiException     # 等价于 from kksanic.response import ...
+    from kksanic import BaseModel, AbstractUser   # 等价于 from kksanic.model import ...
+
+规则默认建议按字段类型选子类（``StringRule`` / ``IntRule`` / ``FloatRule`` / ``FileRule`` ...），
+写错维度会在定义期报 ``TypeError``；``Rule`` 是「什么都能写」的基类，两者可以混用：:
+
+    from kksanic import StringRule, IntRule
+
+    class UserValidator(Validator):
+        name: Annotated[str, '名称', StringRule(min_length=3, max_length=20)]
+        age:  Annotated[int, '年龄', IntRule(min_value=0, max_value=150)]
+
+命令行侧（``python -m kksanic`` / 装好后直接 ``kksanic``）::
+
+    kksanic init [--db postgres]     # 生成 Sanic + Tortoise 骨架
+    kksanic doc  [--app main:app]    # 返回 JSON 的接口 → Markdown + OpenAPI +
+                                     # 自带 Swagger UI 的 api.html
+
+运行期把同一份页面挂成 ``/swagger``（带登录框，登录后 Try it out 就带票）::
+
+    from kksanic import add_swagger_ui
+
+    add_swagger_ui(app)             # GET /swagger（路由都注册完之后再调）
+    kksanic admin [--app main:app]   # 挂了 @admin 的接口 → 单文件后台管理站
+
+生成出来是静态文件，跑起来要再挂一次（一行，放在所有 blueprint 之后）::
+
+    from kksanic import add_admin_site
+
+    add_admin_site(app, 'admin')     # GET /admin（软删开着时自带回收站接口）
+
+页面默认用 ``settings.LANG`` 的语言；侧栏底部（``minimal`` 风格在顶栏右侧）
+和登录页右上角还各有一个切换器，使用者可以自己切，选过的记在浏览器里。
+
+``doc`` 的实现在 :mod:`kksanic.doc`，``admin`` 的实现在 :mod:`kksanic.admin`，
+挂载与回收站接口在 :mod:`kksanic.admin_server`。包根只导出装饰器
+``admin`` / ``Admin`` 和 ``add_admin_site``（写接口时不用再 import 子模块）；
+真正扫路由表的动作（``kksanic doc`` / ``kksanic admin``）由命令行按需触发。
+
+库被装进 ``site-packages`` 后无法从自身位置推断使用者的**项目根**，所以
+``<项目根>/settings.py``、``<项目根>/media`` 这类路径要靠运行时探测。
+探测链覆盖不到的部署方式（典型是 ``sanic server:app``），在启动代码里
+显式指定一次即可：
+
+    import kksanic
+    kksanic.set_project_root('/path/to/your/project')
+
+也可以用环境变量 ``KKSANIC_PROJECT_ROOT``。
+
+Note:
+    导入 ``Validator`` 会连带把 ``tortoise`` 拉进来（校验器要读模型元信息生成字段），
+    所以包根现在同时依赖 ``sanic`` 与 ``tortoise``。
+"""
+
+__version__ = '0.1.0'
+
+from .access_log import add_request_logging
+from .i18n import get_lang, is_english, tr
+from .request import Request
+from .response import ApiException, get_response, register_exception_handler
+from .serializer import ModelSerializer, SerializerTypeError
+from .utils import (
+    ADMIN_STYLES,
+    as_bool,
+    get_admin_settings,
+    get_datetime_settings,
+    get_project_root,
+    get_request_log_settings,
+    get_restful_settings,
+    is_soft_delete_enabled,
+    set_project_root,
+)
+from .validator import (
+    BoolRule,
+    DateRule,
+    DateTimeRule,
+    DictRule,
+    File,
+    FileRule,
+    FloatRule,
+    IntRule,
+    ListRule,
+    ModelRule,
+    Optional,
+    PaginationValidator,
+    Rule,
+    StringRule,
+    ValidateError,
+    Validator,
+)
+from .model import AbstractUser, BaseModel
+from .restful import (
+    CreateConfig,
+    DeleteConfig,
+    DetailConfig,
+    ListConfig,
+    ListMode,
+    Method,
+    MethodConfig,
+    UpdateConfig,
+    add_rest_ful_apis,
+    add_restful_apis,
+    get_or_404,
+    get_paging_settings,
+)
+from .admin import Admin, admin
+from .admin_server import add_admin_site
+from .shard import (
+    ShardError,
+    ShardedModel,
+    ShardRule,
+    expand,
+    is_shard,
+    root_of,
+    shards_of,
+)
+from .swagger import SwaggerMount, add_swagger_ui
+
+__all__ = [
+    'Request',
+    'add_request_logging',
+    'add_rest_ful_apis',
+    'add_restful_apis',
+    'Method',
+    'ListMode',
+    'MethodConfig',
+    'CreateConfig',
+    'ListConfig',
+    'DetailConfig',
+    'UpdateConfig',
+    'DeleteConfig',
+    'get_restful_settings',
+    'get_paging_settings',
+    'get_request_log_settings',
+    'get_admin_settings',
+    'get_datetime_settings',
+    'ADMIN_STYLES',
+    'is_soft_delete_enabled',
+    'as_bool',
+    'get_or_404',
+    'admin',
+    'Admin',
+    'add_admin_site',
+    'add_swagger_ui',
+    'SwaggerMount',
+    'ApiException',
+    'get_response',
+    'register_exception_handler',
+    'tr',
+    'get_lang',
+    'is_english',
+    'BaseModel',
+    'AbstractUser',
+    'ShardRule',
+    'ShardedModel',
+    'ShardError',
+    'expand',
+    'shards_of',
+    'is_shard',
+    'root_of',
+    'Validator',
+    'PaginationValidator',
+    'ModelSerializer',
+    'SerializerTypeError',
+    'Rule',
+    'StringRule',
+    'IntRule',
+    'FloatRule',
+    'BoolRule',
+    'DateRule',
+    'DateTimeRule',
+    'ListRule',
+    'DictRule',
+    'File',
+    'FileRule',
+    'ModelRule',
+    'Optional',
+    'ValidateError',
+    'get_project_root',
+    'set_project_root',
+]

kksanic/__main__.py

@@ -0,0 +1,10 @@
+"""``python -m kksanic`` 的入口 —— 等价于 ``kksanic`` 控制台脚本。
+
+注意：``python -m kksanic`` 会先执行 ``kksanic/__init__.py``，所以
+sanic / tortoise 必须已经装好 —— 对脚手架来说这不构成限制（要让 ``main.py``
+跑起来本来就得先装它们）。本模块自己只额外拉起 ``.cli``，那个子包死守标准库。
+"""
+from .cli import main
+
+if __name__ == '__main__':
+    raise SystemExit(main())

kksanic/access_log.py

@@ -0,0 +1,493 @@
+"""请求日志：一行一个请求（方法 / 路径 / 状态码 / 耗时 / 用户 / 来源 IP）。
+
+为什么值得单独一个模块
+----------------------
+出问题时第一个要回答的问题是「**这个请求到底进来了没有、走的哪条路、慢在哪**」。
+Sanic 自带的 access log 只打「收到一行」，没有状态码、没有耗时、更不知道是谁 ——
+线上排查只能靠猜。这里补的就是这三样。
+
+用法::
+
+    from kksanic.access_log import add_request_logging
+
+    add_request_logging(app)
+
+输出（一行一个请求）::
+
+    GET /api/posts?page=1&page_size=10 200 12.4ms user=3 ip=127.0.0.1 rid=8f3a1c22
+    GET /api/me 401 0.3ms user=- ip=127.0.0.1 rid=bb02fe19
+
+第三格是**真实 HTTP 状态码**：本框架的失败都用状态码表达（400 / 401 /
+403 / 404），不再从 body 里额外抠一个业务码 —— 日志里每一次 401 都是
+真的 401，肉眼和监控都能直接筛。
+
+超过 ``SLOW_MS``、或 HTTP ``>= 500`` 的行会升到 ``WARNING``，日志级别
+一眼就能筛出「慢」和「错」。
+
+配置（项目根 ``settings.py``，全部**运行时**读取）::
+
+    REQUEST_LOG = {
+        'SLOW_MS': 500,                      # 超过这个耗时升 WARNING；0 = 不区分
+        'INCLUDE_QUERY': True,               # 日志里带查询串（敏感值自动打码）
+        'SKIP_PATHS': ('/static', '/media'), # 免记录的路径前缀
+        'FILE': 'logs/access.log',           # 落盘位置；None = 只走 logger
+        'FILE_MAX_BYTES': 10 * 1024 * 1024,  # 单文件上限；0 = 不轮转
+        'FILE_BACKUP_COUNT': 5,              # 保留 access.log.1 ~ .5
+    }
+
+也可以直接传参覆盖（参数优先于 settings）::
+
+    add_request_logging(app, slow_ms=200, include_query=False)
+    add_request_logging(app, log_file='logs/access.log')
+
+日志文件放在哪
+--------------
+``FILE`` 写相对路径时按**项目根**解析（``utils.get_project_root()``），
+不是按进程 cwd —— 双击运行、计划任务、systemd 的 cwd 各不相同，按 cwd 解析
+的结果是「日志跑到别的目录去了」，属于最难查的那类问题。
+
+    'logs/access.log'       -> <项目根>/logs/access.log   （目录自动创建）
+    '/var/log/app/api.log'  -> 原样                       （绝对路径不加工）
+
+轮转：单文件超过 ``FILE_MAX_BYTES`` 改名成 ``access.log.1``，最多留
+``FILE_BACKUP_COUNT`` 份，再老的删掉；总占用上限约
+``FILE_MAX_BYTES * (FILE_BACKUP_COUNT + 1)``。
+
+**多进程 worker 不要写同一个文件**：``RotatingFileHandler`` 不是进程安全的，
+几个 worker 同时轮转会互相抢文件。多 worker 就让它走 stdout、交给 systemd /
+docker 收；确实要落盘就用单 worker。
+
+三个必须知道的点
+----------------
+1. **要注册在鉴权中间件之前**（先调 :func:`add_request_logging`，再调
+   ``permission.add_permission_middleware``）。请求中间件按注册顺序执行，排在
+   后面时，被 401 拦下的请求拿不到开始时间，耗时那一栏是 ``-``（会照样记一行，
+   只是没有耗时）。
+2. **不记请求体**。``Authorization`` 头、密码、上传内容都可能在里面，记进日志
+   等于二次泄漏。查询串里的 token / password 一类参数会被打成 ``***``。
+3. **``OPTIONS`` 预检也记**。CORS 预检被 401 / 405 是常见的跨域故障，正好需要
+   这一行；嫌吵用 ``skip_methods=('OPTIONS',)`` 关掉。
+"""
+
+import logging
+import os
+import time
+from logging.handlers import RotatingFileHandler
+
+from . import utils
+from .i18n import tr
+
+logger = logging.getLogger(__name__)
+
+
+DEFAULT_LOG_NAME = __name__
+
+_SENSITIVE_KEYWORDS = (
+    'token',
+    'password',
+    'passwd',
+    'secret',
+    'auth',
+    'session',
+    'signature',
+)
+
+MAX_QUERY_LENGTH = 200
+
+DEFAULT_SKIP_PATHS = utils.BUILTIN_LOG_SKIP_PATHS
+
+DEFAULT_SLOW_MS = utils.BUILTIN_SLOW_MS
+
+FILE_FORMAT = '%(asctime)s %(levelname)s %(message)s'
+
+FILE_DATE_FORMAT = '%Y-%m-%d %H:%M:%S'
+
+DEFAULT_LOG_MAX_BYTES = utils.BUILTIN_LOG_MAX_BYTES
+DEFAULT_LOG_BACKUP_COUNT = utils.BUILTIN_LOG_BACKUP_COUNT
+
+
+def _is_sensitive(name: str) -> bool:
+    """参数名是否像凭证。"""
+    low = name.lower()
+    if low == 'key' or low.endswith('_key'):
+        return True
+    return any(word in low for word in _SENSITIVE_KEYWORDS)
+
+
+def _mask_query(query_string: str, limit: int = MAX_QUERY_LENGTH) -> str:
+    """把查询串里的敏感值打成 ``***`` 并截断。
+
+    为什么不用 ``parse_qsl`` + ``urlencode``：那是「解析 → 重建」，两个来回
+    大约 10µs，而这条链路在**每个请求**上都要跑一次。按 ``&`` / ``=`` 切一刀
+    足够了 —— 这里的目的只是「别把 token 写进日志文件」，不是做一个通用解析器。
+
+    Args:
+        query_string: 原始的 ``request.query_string``（不含 ``?``）。
+        limit: 截断长度；超长时补 ``...``。
+
+    Returns:
+        str: 打码后的查询串；空查询串返回空串。
+    """
+    if not query_string:
+        return ''
+
+    parts = []
+    for item in query_string.split('&'):
+        name, sep, _value = item.partition('=')
+        parts.append(f'{name}=***' if sep and _is_sensitive(name) else item)
+
+    text = '&'.join(parts)
+    if len(text) > limit:
+        return text[:limit] + '...'
+    return text
+
+
+def _user_id(user):
+    """从 ``request.ctx.user`` 里取主键（dict / UserView / 模型实例都认）。
+
+    刻意在本模块重写一份、不 import ``permission._user_attr``：``permission``
+    一导入就拉 ``python-jose``，而「只想加个请求日志」的项目不该被拖下水。
+    """
+    if user is None:
+        return None
+
+    if isinstance(user, dict):
+        value = user.get('id')
+        if value is None:
+            value = user.get('pk')
+    else:
+        value = getattr(user, 'id', None)
+        if value is None:
+            value = getattr(user, 'pk', None)
+
+    return value
+
+
+def _client_ip(request) -> str:
+    """来源 IP。
+
+    优先 ``client_ip``（Sanic 23.6 起的新入口）：它是「反代给的 remote_addr，
+    没有就退回 socket 对端 ip」。**不能直接用 ``remote_addr``** —— 那个属性只
+    反映 ``X-Forwarded-For``，本机 / 没配反代时永远是空串（实测踩过：日志里
+    ``ip=`` 后面什么都没有）。
+
+    老版本 Sanic 没有 ``client_ip``，退回 ``remote_addr`` / ``ip``。
+    """
+    address = getattr(request, 'client_ip', None)
+    if not address:
+        address = (
+            getattr(request, 'remote_addr', None)
+            or getattr(request, 'ip', '')
+        )
+    return str(address or '')
+
+
+def _format_elapsed(started) -> str:
+    """耗时字段：拿不到开始时间就是 ``-``（别写成 0.0ms，那是假的）。"""
+    if started is None:
+        return '-'
+    return f'{(time.perf_counter() - started) * 1000:.1f}ms'
+
+
+def _request_id(request) -> str:
+    """Sanic 给每个请求生成的 id，取前 8 位做 ``rid``（和 Sanic 自己的错误日志对得上）。"""
+    value = getattr(request, 'id', None)
+    if not value:
+        return ''
+    return str(value)[:8]
+
+
+def add_request_logging(
+    app,
+    log=None,
+    log_file=None,
+    log_max_bytes=None,
+    log_backup_count=None,
+    level='INFO',
+    slow_level='WARNING',
+    slow_ms=None,
+    skip_paths=None,
+    skip_methods=(),
+    include_query=None,
+    include_user=True,
+    include_ip=True,
+    include_request_id=False,
+):
+    """给整站挂上「一行一个请求」的访问日志。
+
+    Args:
+        app: Sanic 实例。
+        log: 自定义 ``logging.Logger``；不传用 ``kksanic.access_log`` 模块的
+            logger（跟随项目根 logger 的配置，不需要额外 basicConfig）。
+        log_file: 日志文件路径；``None`` 时读 ``settings.REQUEST_LOG['FILE']``，
+            都没有就**不落盘**（只交给 ``log``，去哪由项目的 logging 配置决定）。
+            相对路径按**项目根**解析、目录自动创建，详见模块文档「日志文件放在哪」。
+        log_max_bytes: 单文件上限（字节）；``None`` 时读
+            ``settings.REQUEST_LOG['FILE_MAX_BYTES']``，默认 10 MB。
+            ``0`` 表示不轮转（一个文件一直往下写）。
+        log_backup_count: 保留几份历史文件（``access.log.1`` ~ ``.N``）；
+            ``None`` 时读 ``settings.REQUEST_LOG['FILE_BACKUP_COUNT']``，
+            默认 5。``0`` 表示不保留（轮转时直接覆盖旧文件）。
+        level: 正常请求的日志级别，默认 ``'INFO'``。可写字符串或
+            ``logging.INFO`` 这类整数。
+        slow_level: 慢请求 / 5xx 的级别，默认 ``'WARNING'``。
+        slow_ms: 超过这个耗时（毫秒）升到 ``slow_level``；``None`` 时读
+            ``settings.REQUEST_LOG['SLOW_MS']``，两者都没有则 ``500``；
+            ``0`` 表示不区分快慢。
+        skip_paths: 不记录的**路径前缀**元组；``None`` 时读
+            ``settings.REQUEST_LOG['SKIP_PATHS']``，都没有则
+            ``('/static', '/media')``。判断口径与鉴权中间件一致：等于前缀，或
+            「前缀 + / 开头」，所以 ``'/static'`` 不会误跳过 ``/staticfoo``。
+        skip_methods: 直接不记录的方法，默认不跳（``OPTIONS`` 预检也记 ——
+            跨域故障往往就出在预检上）。
+        include_query: 是否把查询串写进日志；``None`` 时读
+            ``settings.REQUEST_LOG['INCLUDE_QUERY']``，都没有则 ``True``。
+        include_user: 是否记录 ``user=<主键>``，默认 ``True``。
+        include_ip: 是否记录 ``ip=``，默认 ``True``。
+        include_request_id: 是否记录 ``rid=``（Sanic 的请求 id 前 8 位），
+            默认 ``False``。打开它每请求要多花 ~8µs —— ``request.id`` 是
+            **首次访问才生成**的 uuid，而 Sanic 自己不生成它（除非你访问）。
+            要和 Sanic 自己的报错日志对时间线时再开。
+
+    Returns:
+        tuple: ``(请求中间件, 响应中间件)``。已经注册进 ``app``，返回它们只为
+        方便单测直接调用。
+
+    Raises:
+        TypeError: ``level`` / ``slow_level`` 不是合法的日志级别。
+
+    Note:
+        重复调用是幂等的 —— 同一个 ``app`` 上第二次调用直接返回已注册的那一对
+        中间件，不会再挂一层（挂两层的结果是每个请求打两行）。
+
+    Note:
+        **请在鉴权中间件之前调用**。请求中间件按注册顺序跑，排在
+        ``add_permission_middleware`` 之后时，被它 401 挡掉的请求拿不到开始
+        时间，耗时栏是 ``-``（行数照记，状态码也对）。
+
+    Note:
+        配了 ``log_file`` 是**加**一个输出端，不是替换 ``log``：终端里照样有，
+        文件里也多一份。只想留文件，就自己传一个 ``propagate = False`` 的
+        logger 进来。同一个文件重复调用只会挂一个 handler，不会写两遍。
+
+    Note:
+        落盘是**同步写**（每请求一次 ``write`` + ``flush``）。单 worker 每秒
+        几千请求没问题，再高就该让日志走 stdout 交给外面的收集器。
+    """
+    existing = getattr(app.ctx, '_kk_access_log_middlewares', None)
+    if existing is not None:
+        return existing
+
+    number_level = _resolve_level(level, 'level')
+    slow_number_level = _resolve_level(slow_level, 'slow_level')
+
+    config = utils.get_request_log_settings()
+
+    if slow_ms is None:
+        slow_ms = config['SLOW_MS']
+    if skip_paths is None:
+        skip_paths = config['SKIP_PATHS']
+    if include_query is None:
+        include_query = config['INCLUDE_QUERY']
+    if log_file is None:
+        log_file = config['FILE']
+    if log_max_bytes is None:
+        log_max_bytes = config['FILE_MAX_BYTES']
+    if log_backup_count is None:
+        log_backup_count = config['FILE_BACKUP_COUNT']
+
+    prefixes = tuple(
+        str(item).rstrip('/') or '/' for item in (skip_paths or ())
+    )
+    skipped = tuple(str(item).upper() for item in (skip_methods or ()))
+    target = log if log is not None else logging.getLogger(DEFAULT_LOG_NAME)
+    threshold = max(0.0, float(slow_ms)) / 1000.0
+
+    if log_file:
+        _attach_file_handler(target, log_file, log_max_bytes, log_backup_count)
+        if number_level == logging.INFO and target.level == logging.NOTSET:
+            if target.getEffectiveLevel() > number_level:
+                target.setLevel(number_level)
+
+    @app.middleware('request')
+    async def _kk_access_log_start(request):
+        if getattr(request.ctx, '_kk_started', None) is None:
+            request.ctx._kk_started = time.perf_counter()
+        return None
+
+    @app.middleware('response')
+    async def _kk_access_log_write(request, response):
+        try:
+            _write_line(
+                request,
+                response,
+                log=target,
+                level=number_level,
+                slow_level=slow_number_level,
+                threshold=threshold,
+                prefixes=prefixes,
+                skipped=skipped,
+                include_query=bool(include_query),
+                include_user=bool(include_user),
+                include_ip=bool(include_ip),
+                include_request_id=bool(include_request_id),
+            )
+        except Exception:
+            logger.warning(tr('写请求日志失败'), exc_info=True)
+        return response
+
+    pair = (_kk_access_log_start, _kk_access_log_write)
+    app.ctx._kk_access_log_middlewares = pair
+    return pair
+
+
+def _resolve_log_path(path: str) -> str:
+    """把配置里的路径变成绝对路径：相对路径按**项目根**解析。
+
+    Raises:
+        RuntimeError: 项目根确定不了（既没有 ``KKSANIC_PROJECT_ROOT``，也推断
+            不出来），而路径又是相对的。这时候猜一个 cwd 出来只会让日志落到
+            意料之外的目录，不如直接在启动期报错。
+    """
+    expanded = os.path.expanduser(str(path).strip())
+    if os.path.isabs(expanded):
+        return os.path.abspath(expanded)
+
+    root = utils.get_project_root()
+    if root is None:
+        raise RuntimeError(
+            tr('请求日志用相对路径 {path!r} 时需要项目根目录，但没能确定（项目里没有 settings.py？）；请改成绝对路径，或设置环境变量 {PROJECT_ROOT_ENV}', path=path, PROJECT_ROOT_ENV=utils.PROJECT_ROOT_ENV)
+        )
+
+    return os.path.abspath(os.path.join(str(root), expanded))
+
+
+def _attach_file_handler(log, path, max_bytes, backup_count):
+    """给 logger 挂一个写文件的 handler；同一个文件只挂一次。
+
+    用 ``delay=True``：文件在第一次真正写的时候才打开。启动时先建好目录
+    （否则第一请求才炸，报错还落在请求里），但不创建一个空文件 —— 空文件
+    和「日志没写成功」在排查时很难区分。
+
+    Returns:
+        logging.Handler: 复用或新建的 handler。
+    """
+    absolute = _resolve_log_path(path)
+
+    for handler in log.handlers:
+        if getattr(handler, 'baseFilename', None) == absolute:
+            return handler
+
+    directory = os.path.dirname(absolute)
+    if directory:
+        os.makedirs(directory, exist_ok=True)
+
+    if max_bytes and int(max_bytes) > 0:
+        handler = RotatingFileHandler(
+            absolute,
+            maxBytes=int(max_bytes),
+            backupCount=int(backup_count),
+            encoding='utf-8',
+            delay=True,
+        )
+    else:
+        handler = logging.FileHandler(absolute, encoding='utf-8', delay=True)
+
+    handler.setFormatter(logging.Formatter(FILE_FORMAT, FILE_DATE_FORMAT))
+    log.addHandler(handler)
+    return handler
+
+
+def _resolve_level(value, name: str) -> int:
+    """把 ``'INFO'`` / ``20`` 统一成 int 级别；认不出就报错。
+
+    不静默回落：写错级别（``'INFOO'``）时 ``logging`` 收到的是不合法的字符串，
+    表现为「日志一行都没有」，比启动时报错难查得多。
+    """
+    if isinstance(value, int) and not isinstance(value, bool):
+        return value
+
+    if isinstance(value, str):
+        number = logging.getLevelName(value.strip().upper())
+        if isinstance(number, int):
+            return number
+
+    raise TypeError(
+        tr('add_request_logging({name}=...) 需要日志级别（"INFO" / logging.INFO），收到 {value!r}', name=name, value=value)
+    )
+
+
+def _write_line(
+    request,
+    response,
+    log,
+    level,
+    slow_level,
+    threshold,
+    prefixes,
+    skipped,
+    include_query,
+    include_user,
+    include_ip,
+    include_request_id,
+) -> None:
+    """拼一行并写出去；被跳过的请求在这里就返回，连字符串都不拼。"""
+    method = request.method or ''
+
+    if method in skipped:
+        return
+
+    path = request.path or ''
+    for prefix in prefixes:
+        if prefix == '/':
+            return
+        if path == prefix or path.startswith(prefix + '/'):
+            return
+
+    started = getattr(request.ctx, '_kk_started', None)
+    elapsed_text = _format_elapsed(started)
+    elapsed = 0.0 if started is None else time.perf_counter() - started
+
+    status = getattr(response, 'status', 0) or 0
+    is_slow = bool(threshold) and elapsed >= threshold
+    is_error = status >= 500
+    number = slow_level if (is_slow or is_error) else level
+
+    if not log.isEnabledFor(number):
+        return
+
+    target = path
+    if include_query:
+        query = _mask_query(request.query_string or '')
+        if query:
+            target = f'{path}?{query}'
+
+    parts = [method, target, str(status), elapsed_text]
+
+    if include_user:
+        user_id = _user_id(getattr(request.ctx, 'user', None))
+        parts.append(f'user={user_id}' if user_id is not None else 'user=-')
+
+    if include_ip:
+        parts.append(f'ip={_client_ip(request)}')
+
+    if include_request_id:
+        rid = _request_id(request)
+        if rid:
+            parts.append(f'rid={rid}')
+
+    if is_slow:
+        parts.append(f'slow>{int(threshold * 1000)}ms')
+
+    log.log(number, ' '.join(parts))
+
+
+__all__ = [
+    'add_request_logging',
+    'DEFAULT_SLOW_MS',
+    'DEFAULT_SKIP_PATHS',
+    'DEFAULT_LOG_MAX_BYTES',
+    'DEFAULT_LOG_BACKUP_COUNT',
+    'FILE_FORMAT',
+    'FILE_DATE_FORMAT',
+]