Flask RESTful 应用框架

基于 Flask 快速搭建 RESTful 接口应用，支持丰富插件扩展。

快速开始

本地开发

pip3 install -e .

发布到 PyPI

rm -rf dist && python3.12 setup.py sdist bdist_wheel && twine upload dist/*

镜像构建

# 主镜像
docker build . --force-rm=true -f docker/Dockerfile.python -t wuhanchu/python:flask_frame_master && docker push wuhanchu/python:flask_frame_master

# Alpine 镜像
nohup docker build . --force-rm=true -f docker/Dockerfile.alpine -t wuhanchu/python:3_alpine && docker push wuhanchu/python:3_alpine > build_alpine.log 2>&1 &
nohup docker build . --force-rm=true -f docker/Dockerfile.alpine_continue -t wuhanchu/python:3_alpine && docker push wuhanchu/python:3_alpine &

应用编译

  • 普通编译：docker build -f ./frame/docker/Dockerfile.source .
  • 加密编译：docker build -f ./frame/docker/Dockerfile.encrypt .

默认接口

  • GET / - 健康检查（返回 "app is running"）
  • GET /healthy - 健康状态（JSON）
  • GET /flask/log - 日志文件列表
  • GET /flask/log/download - 下载日志压缩包
  • GET /debug-sentry - 触发错误（调试 Sentry）
  • 任意接口加 ?profile 参数可获取性能分析报告

OpenAPI 文档生成

从 Flask 路由自动生成 API 规范，支持导入 Apifox 或通过 API 自动推送（增量同步）。

VS Code Task 配置

在业务项目中创建 .vscode/tasks.json：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "sync_to_apifox",
      "type": "shell",
      "command": "/usr/bin/python3.12",
      "args": [
        "-m", "flask_frame", "sync_apifox",
        "--token", "afxp_xxx",
        "--project-id", "xxx"
      ],
      "group": "build",
      "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": true,
        "panel": "dedicated",
        "showReuseMessage": false,
        "clear": false
      },
      "problemMatcher": []
    }
  ]
}

Ctrl+Shift+B 选择 sync_to_apifox 即可推送。

约定：框架自动检测业务项目结构创建应用——导入 config 调 create_app(config)，检测 module/context 包自动初始化，最后用 flasgger 生成 swagger spec。项目只需有 config.py（含 config 变量）和标准的 module、context 模块即可。

如需自定义 app 创建逻辑，可传 --app 参数指定工厂函数：

python -m flask_frame sync_apifox --app "app:create_app" --token xxx --project-id xxx

获取凭据：Apifox 项目设置 → API 认证获取 Token，项目设置 → 基本信息获取项目 ID。

配置项

基础配置

配置项 类型 默认值 说明
PRODUCT_KEY str 项目名称，也作为数据库 schema、锁前缀等
SQLALCHEMY_DATABASE_URI str 数据库连接地址（PostgreSQL）
DB_SCHEMA str 数据库 schema，支持逗号分隔多 schema（如 "public,user_auth"）
AUTO_UPDATE bool True 启动时自动执行数据库迁移
DB_UPDATE_SWITCH bool False 是否执行 DB_UPDATE_FILE
RECREATE_SCHEMA bool False 是否强制重建 schema
DB_INIT_FILE str/list 初始化 SQL 脚本路径
DB_VERSION_FILE str/list 版本迁移脚本路径，默认扫描 sql/migrate/ 目录
DB_UPDATE_FILE str/list 开发更新脚本路径
ENABLED_EXTENSION list 启用的插件列表，如 ['database', 'redis', 'lock']
FETCH_USER bool True 是否获取用户信息（需 permission 插件）
CHECK_API bool True 是否启用 API 权限校验（需 permission 插件）
ADMIN_TOKEN str 可跳过鉴权的固定 Token
ENCRYPTION_KEY str 数据加密 Key，未指定时使用 PRODUCT_KEY
DB_POOL_SIZE int 5 数据库连接池大小
DB_MAX_OVERFLOW int 30 最大溢出连接数
DB_VERSION str 指定数据库版本号（兼容 GaussDB）

插件配置

配置项 关联插件 说明
REDIS_URL redis, lock, celery Redis 连接地址，支持 Sentinel 模式（sentinel://...）
REDIS_MASTER_NAME redis, lock, celery Sentinel 模式的 master 名称
SENTRY_DSN / SENTRY_DS sentry Sentry DSN 地址（优先 SENTRY_DSN，兼容 SENTRY_DS）
LOG_LEVEL sentry, loguru 日志级别
MINIO_SERVER minio MinIO 服务地址（host:port）
MINIO_ACCESS_KEY minio MinIO Access Key
MINIO_SECRET_KEY minio MinIO Secret Key
MINIO_ACCESS_URL minio MinIO 文件访问基础 URL
MINIO_USE_HTTPS minio 是否使用 HTTPS（"1"/"true"/"yes"/"on"）
CONSUL_HOST consul Consul 地址
CONSUL_PORT consul Consul 端口
CONSUL_TOKEN consul Consul Token（必需）
API_LOG_DB_URI api_log API 日志数据库地址
API_LOG_RETENTION_DAYS api_log API 日志保留天数，默认 30
CELERY_DEFAULT_QUEUE celery Celery 默认队列名
PROXY_SERVICE_URL postgrest PostgREST 代理服务地址
PROXY_LOCAL postgrest 是否使用本地数据库代理（"True"/"False"）
PROXY_CUSTOM postgrest 是否自定义代理路由
USER_AUTH_URL permission 用户认证服务地址
LICENSE_CHECK permission 是否检查 License

工具类

框架提供常用工具函数，位于 src/flask_frame/util/。

数据转换

函数 导入路径 说明
result_to_dict flask_frame.util.db 数据库原始查询结果（有 .keys() 方法的 Result 对象）→ dict 列表
model_to_dict flask_frame.util.param_tool SQLAlchemy Model 实例 → dict，自动剔除 _sa_instance_state 
from flask_frame.util.db import result_to_dict
from flask_frame.util.param_tool import model_to_dict

# 原始 SQL 查询
result = db.session.execute(text("SELECT * FROM users"))
data = result_to_dict(result)  # [{"id": 1, "name": "张三"}, ...]

# Model 实例
user = User.query.first()
data = model_to_dict(user)  # {"id": 1, "name": "张三", "_sa_instance_state": 已剔除}

推荐：复杂序列化场景使用 Marshmallow Schema（extension/marshmallow），支持字段过滤、嵌套关系、验证等。

其他工具

模块 说明
util.db 数据库操作（result_to_dict、批量插入等）
util.file 文件操作
util.json JSON 处理
util.lock 锁工具
util.rsa RSA 加解密
util.sql SQL 工具
util.fernet Fernet 对称加密

插件系统

插件目录：src/flask_frame/extension/

在 ENABLED_EXTENSION 配置列表中添加插件名称即可启用。每个插件实现 init_app(app) 方法。

插件名称 说明 依赖
database SQLAlchemy 数据库 + 自动迁移 -
redis Redis 客户端（支持 Sentinel） -
lock 分布式锁（优先 Redis，降级文件锁） redis
celery Celery 异步任务（使用 REDIS_URL 作为 broker） redis
permission 用户鉴权 + API 权限校验 -
api_log API 请求日志记录 database, celery
sentry Sentry 错误监控 -
minio MinIO 文件存储 -
consul Consul 服务发现 + KV 配置 -
loguru Loguru 日志系统 lock
marshmallow Flask-Marshmallow 集成 -
postgrest PostgREST 代理（本地/远程） database

项目结构

src/flask_frame/
├── app.py                     # 应用工厂 create_app()
├── openapi.py                 # OpenAPI 文档生成（generate_openapi）
├── api/                       # 请求/响应/异常处理
│   ├── request.py             #   get_request_param(), proxy()
│   ├── response.py            #   Response.make_flask_response()
│   └── exception.py           #   ResourceError, CallException, BusiError(deprecated)
├── annotation/                # @deprecated, @profile 装饰器
├── extension/                 # 插件系统
│   ├── __init__.py            #   遍历 ENABLED_EXTENSION 动态加载
│   ├── database/              #   数据库插件（SQLAlchemy + 自动迁移 + reflect）
│   ├── redis.py               #   Redis 客户端
│   ├── lock.py                #   分布式锁
│   ├── celery.py              #   Celery 任务
│   ├── permission.py          #   权限校验
│   ├── api_log/               #   API 日志
│   ├── sentry.py              #   Sentry 监控
│   ├── minio.py               #   MinIO 文件存储
│   ├── consul.py              #   Consul 服务发现
│   ├── loguru/                #   Loguru 日志
│   ├── marshmallow.py         #   Marshmallow 集成
│   └── postgrest/             #   PostgREST 代理
├── schema/                    # BaseSchema（自动剔除空值字段）
├── algorithm/                 # 算法扩展
├── sql/                       # 内置 SQL 脚本（api_log, param）
├── util/                      # 工具类（db, file, json, lock, rsa, sql, fernet）
└── thread/                    # 线程相关

其他目录

  • tasks/ — 应用层代码，含权限初始化逻辑（tasks/database.py），非框架核心
  • docker/ — Docker 构建文件
  • test/ — 测试目录（失效测试已清理，当前无可运行用例）
  • doc/ — 迁移文档

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for chenxuejun from gravatar.com chenxuejun Avatar for wuhanchu from gravatar.com wuhanchu

Credits

Author: wuhanchu

License expression

MIT
View SPDX License List

Requires

Python >=3.12

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

flask_frame-1.3.11.tar.gz (74.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

flask_frame-1.3.11-py3-none-any.whl (87.2 kB view details)

Uploaded Python 3

File details

Details for the file flask_frame-1.3.11.tar.gz.

File metadata

  • Download URL: flask_frame-1.3.11.tar.gz
  • Upload date:
  • Size: 74.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.11

File hashes

Hashes for flask_frame-1.3.11.tar.gz
Algorithm Hash digest
SHA256 1fb0e99973126db92d61361b501e715518629b3a91a9fe03072333634e97a329
MD5 1ff8098109352fd347f0f1d19500c0cc
BLAKE2b-256 36c58f7dc91769270154d188150c4e6c15300c9bfaf6e3646aec87ffc2c50e45

See more details on using hashes here.

File details

Details for the file flask_frame-1.3.11-py3-none-any.whl.

File metadata

  • Download URL: flask_frame-1.3.11-py3-none-any.whl
  • Upload date:
  • Size: 87.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.11

File hashes

Hashes for flask_frame-1.3.11-py3-none-any.whl
Algorithm Hash digest
SHA256 8d3ccfb9b443fecb94cbf5ae6e6aa61aa9448a5f9d41e98cf47a5d72ffd18c4a
MD5 d30af0ff0f4ac76aa20e651937ea6277
BLAKE2b-256 406b4d7f62bc2b44964ee7cb56b2c040d1c455a798843a8352386fce7e82bb0b

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

1.3.11

1.3.10

1.3.9

1.3.8

1.3.7

1.3.6

1.3.4

1.3.3

1.3.2

1.3.1

1.3.0

1.2.2

1.2.1

1.2.0

1.1.40

1.1.39

1.1.38

1.1.37

1.1.36

1.1.35

1.1.34

1.1.33

1.1.32

1.1.31

1.1.30

1.1.29

1.1.28

1.1.27

1.1.26

1.1.25

1.1.24

1.1.23

1.1.22

1.1.21

1.1.20

1.1.19

1.1.18

1.1.17

1.1.16

1.1.15

1.1.14

1.1.13

1.1.12

1.1.11

1.1.10

1.1.9

1.1.8

1.1.7

1.1.6

1.1.5

1.1.3

1.1.2

1.1.1

1.1.0

1.0.17

1.0.16

1.0.15

1.0.14

1.0.13

1.0.12

1.0.11

1.0.10

1.0.9

1.0.8

1.0.7

1.0.6

1.0.5

1.0.4

1.0.3

1.0.2

1.0.1

1.0.0

0.8.4

0.8.3

0.8.2

0.8.1

0.8

0.7.9

0.7.8

0.7.7

0.7.6

0.7.5

0.7.4

0.7.3

0.7.2

0.7.1

0.7

0.6.8

0.6.7

0.6.6

0.6.5

0.6.4

0.6.3

0.6.2

0.6.1

0.6

0.5.11

0.5.10

0.5.9

0.5.8

0.5.7

0.5.6

0.5.5

0.5.4

0.5.3

0.5.2

0.5.1

0.5

0.4.19

0.4.18

0.4.17

0.4.16

0.4.15

0.4.14

0.4.13

0.4.12

0.4.11

0.4.10

0.4.9

0.4.8

0.4.7

0.4.6

0.4.5

0.4.4

0.4.3

0.4.2

0.4.1

0.4

0.3.18

0.3.17

0.3.16

0.3.15

0.3.14

0.3.13

0.3.12

0.3.11

0.3.10

0.3.9

0.3.8

0.3.7

0.3.6

0.3.5

0.3.4

0.3.3

0.3.2

0.3.1

0.3

0.2.27

0.2.26

0.2.25

0.2.24

0.2.23

0.2.22

0.2.21

0.2.20

0.2.19

0.2.18

0.2.17

0.2.16

0.2.15

0.2.14

0.2.13

0.2.11

0.2.10

0.2.9

0.2.8

0.2.7

0.2.6

0.2.5

0.2.4

0.2.3

0.2.2

0.2.1

0.2

0.1.13

0.1.12

0.1.11

0.1.10

0.1.9

0.1.8

0.1.7

0.1.6

0.1.5

0.1.4

0.1.3

0.1.2

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page