diff --git a/.flake8 b/.flake8 index 429afa5..c30c4a0 100644 --- a/.flake8 +++ b/.flake8 @@ -25,7 +25,10 @@ exclude = dist # 与 black/isort 冲突项（必须忽略，否则与自动格式化互相打架） +# E203：切片冒号前空格（black 风格） +# W503：二元运算符换行（black 风格） +# E501：行过长（交由 black 处理） extend-ignore = - E203, # 切片冒号前空格（black 风格） - W503, # 二元运算符换行（black 风格） - E501, # 行过长（交由 black 处理） + E203, + W503, + E501, diff --git a/app.py b/app.py index f25a055..50ffbc5 100644 --- a/app.py +++ b/app.py @@ -11,7 +11,7 @@ → Gunicorn 通过 `app:app` 导入 app 对象，不执行 __main__ 块 """ -from application import create_app +from application.factory import create_app from config import FLASK_HOST, FLASK_PORT, FLASK_DEBUG, FLASK_USE_RELOADER # 创建应用实例 diff --git a/application/__init__.py b/application/__init__.py index f979c41..e1ea106 100644 --- a/application/__init__.py +++ b/application/__init__.py @@ -40,130 +40,22 @@ # +====================================================================== """ -应用工厂模块 -负责创建和配置 Flask 应用实例 +application 包 +============================================================= + +Flask 应用核心包。 + +包结构： + - factory.py 应用工厂（create_app） + - constants/ 常量定义 + - forms/ 表单验证 + - middleware/ 请求/响应中间件 + - models/ 数据模型 + - services/ 业务逻辑 + - views/ 路由控制器 + +说明： + 应用工厂独立于 factory.py，保持本包导入轻量，避免包初始化时 + 触发全量导入（修复循环导入，支持单元测试与模块级导入）。 + 重构方向：本包后续整体迁移至 src/（见重构方案-v2.md）。 """ - -import os - -from flask import Flask -from flask_cors import CORS -from werkzeug.middleware.proxy_fix import ProxyFix - -from application.middleware.transaction import register_transaction -from application.middleware import register_middleware -from application.middleware.error_handler import register_error_handlers -from application.middleware.op_log import register_operation_log -from application.views import register_blueprint -from config import DatabaseConfig, REDIS_URL -from extensions import register_extends -from utils.json import JSONEncoder - - -def create_app(): - """ - 创建并配置 Flask 应用实例 - - 配置流程： - 1. 创建 Flask 核心对象 - 2. 配置 Redis 连接 - 3. 加载数据库配置 - 4. 设置 JSON 序列化器 - 5. 配置跨域资源共享 - 6. 初始化数据库 - 7. 初始化 Redis 缓存 - 8. 注册路由蓝图 - 9. 初始化第三方扩展 - 10. 注册中间件 - - Returns: - Flask: 配置完成的应用实例 - """ - # ============================================================ - # 创建 Flask 核心对象 - # ============================================================ - app = Flask( - __name__, - template_folder='../templates', - static_folder='../static' - ) - - # ============================================================ - # Redis 配置（用于缓存和会话存储） - # ============================================================ - app.config['REDIS_URL'] = REDIS_URL - - # ============================================================ - # 加载数据库配置 - # ============================================================ - app.config.from_object(DatabaseConfig) - - # ============================================================ - # 自定义 JSON 序列化器（支持 datetime 等特殊类型） - # ============================================================ - app.json = JSONEncoder(app) - - # ============================================================ - # 跨域资源共享配置 - # ============================================================ - # 注意：origins="*" 与 supports_credentials=True 不兼容， - # 浏览器会拒绝携带凭证的通配符CORS响应。 - # 配置了 CORS_ALLOWED_ORIGINS 时使用指定源（支持凭证）， - # 未配置时使用通配符（不支持凭证）。 - from config import CORS_ALLOWED_ORIGINS - if CORS_ALLOWED_ORIGINS: - allowed_origins = [origin.strip() for origin in CORS_ALLOWED_ORIGINS.split(',') if origin.strip()] - CORS( - app, - resources={r"/*": {"origins": allowed_origins}}, - supports_credentials=True - ) - else: - CORS( - app, - resources={r"/*": {"origins": "*"}}, - supports_credentials=False - ) - - # ============================================================ - # 可信代理配置（反向代理环境下获取真实客户端IP） - # ============================================================ - # PROXY_NUM: 可信代理层数，默认0（无代理，不信任任何转发头） - # 设为1表示前面有1层可信代理（如Nginx），ProxyFix会从 - # X-Forwarded-For 最右侧取1个IP作为真实客户端IP - proxy_num = int(os.getenv('PROXY_NUM', 0)) - if proxy_num > 0: - app.wsgi_app = ProxyFix(app.wsgi_app, x_for=proxy_num, x_proto=proxy_num) - - # ============================================================ - # 注册操作日志自动记录中间件（必须在事务拦截器之前注册， - # 确保 after_request 中日志写入先于事务提交，日志随事务一起持久化） - # ============================================================ - register_operation_log(app) - - # ============================================================ - # 注册 AOP 事务拦截器（核心：一行代码搞定所有事务） - # ============================================================ - register_transaction(app) - - # ============================================================ - # 注册蓝图（路由分组管理） - # ============================================================ - register_blueprint(app) - - # ============================================================ - # 初始化第三方扩展 - # ============================================================ - register_extends(app) - - # ============================================================ - # 注册中间件（请求/响应拦截处理） - # ============================================================ - register_middleware(app) - - # ============================================================ - # 注册全局异常处理器（确保最后注册，能捕获所有环节异常） - # ============================================================ - register_error_handlers(app) - - return app diff --git a/application/factory.py b/application/factory.py new file mode 100644 index 0000000..ad26c24 --- /dev/null +++ b/application/factory.py @@ -0,0 +1,176 @@ +# +====================================================================== +# | DjangoAdmin 企业数字化开发平台 [ 赋能开发者，助力企业发展 ] +# +---------------------------------------------------------------------- +# | Copyright (c) 2021-2026 一米阳光团队 版权所有 +# +---------------------------------------------------------------------- +# | 开源协议: Apache-2.0 +# | 重要声明: 未经书面许可，不得移除或修改本框架相关版权标识。 +# +---------------------------------------------------------------------- +# | 官方网站: https://www.djangoadmin.cn +# +---------------------------------------------------------------------- +# | 研发团队: 一米阳光团队 荣誉出品 +# +====================================================================== +# | 版权和免责声明: +# | 一、知识产权声明 +# | 本团队对该软件框架产品（以下简称“本产品”）拥有完整知识产权，包括但不限于商标权、专利权、 +# | 著作权、商业秘密等。前述权利均受中华人民共和国及相关国际法律法规保护。未经本团队书面授权， +# | 任何个人或单位不得基于本产品本身申请任何形式的知识产权。 +# | 二、使用限制与禁止条款 +# | 您理解并同意，禁止将本产品用于以下任何行为： +# | 1. 任何违反中华人民共和国法律法规的用途； +# | 2. 任何侵害他人合法权益（包括但不限于人身权、财产权、知识产权等）的行为； +# | 3. 任何危害国家安全、公共利益及社会道德风尚的行为。 +# | 三、责任豁免 +# | 因使用本产品而产生的任何损失或法律纠纷（包括但不限于直接损失、间接损失、附带损失、衍生损失 +# | 以及因违约、侵权等引发的责任），本团队均不承担任何法律责任。若因违规使用本产品导致任何第三 +# | 方提起索赔或行政机关进行调查，您应独立承担全部责任。 +# | 四、违约与法律责任 +# | 如发现任何违反本声明的行为，本团队有权： +# | 1. 无条件配合公安机关及其他有权机关的调查取证工作； +# | 2. 依法追究相关方的民事责任，并要求赔偿全部损失； +# | 3. 保留进一步采取刑事控告等法律措施的权利。 +# | 五、许可范围说明 +# | 1、被授权方应视本产品源代码为核心机密信息，负有最高标准的保密与保管义务。禁止以任何形式（包 +# | 括但不限于直接或间接的分享、复制、传播、分发、转售、出租、开源、反向工程、反编译、反汇编或通 +# | 过网络服务提供给任何第三方）泄露、披露或处置源代码的全部或部分内容。任何未经授权的复制、使用、 +# | 传播行为均构成对本团队知识产权的严重侵权，本团队有权依法追究其全部法律责任，并要求赔偿因此造 +# | 成的一切经济损失及商誉损害。 +# | 2、本产品仅限于公司或个人在法律允许范围内，用于内部且合规的软件产品研发。具体权利义务以《软件 +# | 许可协议》附件为准。 +# +====================================================================== + +""" +应用工厂模块 +============================================================= + +负责创建和配置 Flask 应用实例。 + +说明： + 应用工厂从 application/__init__.py 独立至此模块，使 application + 包保持轻量，避免包初始化时触发全量导入（修复循环导入，支持单元测试）。 + 重构方向：本模块后续迁移至 src/app.py（见重构方案-v2.md P2）。 +""" + +import os + +from flask import Flask +from flask_cors import CORS +from werkzeug.middleware.proxy_fix import ProxyFix + +from application.middleware.transaction import register_transaction +from application.middleware import register_middleware +from application.middleware.error_handler import register_error_handlers +from application.middleware.op_log import register_operation_log +from application.views import register_blueprint +from config import DatabaseConfig, REDIS_URL +from extensions import register_extends +from utils.json import JSONEncoder + + +def create_app(): + """ + 创建并配置 Flask 应用实例 + + 配置流程： + 1. 创建 Flask 核心对象 + 2. 配置 Redis 连接 + 3. 加载数据库配置 + 4. 设置 JSON 序列化器 + 5. 配置跨域资源共享 + 6. 初始化数据库 + 7. 初始化 Redis 缓存 + 8. 注册路由蓝图 + 9. 初始化第三方扩展 + 10. 注册中间件 + + Returns: + Flask: 配置完成的应用实例 + """ + # ============================================================ + # 创建 Flask 核心对象 + # ============================================================ + app = Flask( + __name__, + template_folder='../templates', + static_folder='../static' + ) + + # ============================================================ + # Redis 配置（用于缓存和会话存储） + # ============================================================ + app.config['REDIS_URL'] = REDIS_URL + + # ============================================================ + # 加载数据库配置 + # ============================================================ + app.config.from_object(DatabaseConfig) + + # ============================================================ + # 自定义 JSON 序列化器（支持 datetime 等特殊类型） + # ============================================================ + app.json = JSONEncoder(app) + + # ============================================================ + # 跨域资源共享配置 + # ============================================================ + # 注意：origins="*" 与 supports_credentials=True 不兼容， + # 浏览器会拒绝携带凭证的通配符CORS响应。 + # 配置了 CORS_ALLOWED_ORIGINS 时使用指定源（支持凭证）， + # 未配置时使用通配符（不支持凭证）。 + from config import CORS_ALLOWED_ORIGINS + if CORS_ALLOWED_ORIGINS: + allowed_origins = [origin.strip() for origin in CORS_ALLOWED_ORIGINS.split(',') if origin.strip()] + CORS( + app, + resources={r"/*": {"origins": allowed_origins}}, + supports_credentials=True + ) + else: + CORS( + app, + resources={r"/*": {"origins": "*"}}, + supports_credentials=False + ) + + # ============================================================ + # 可信代理配置（反向代理环境下获取真实客户端IP） + # ============================================================ + # PROXY_NUM: 可信代理层数，默认0（无代理，不信任任何转发头） + # 设为1表示前面有1层可信代理（如Nginx），ProxyFix会从 + # X-Forwarded-For 最右侧取1个IP作为真实客户端IP + proxy_num = int(os.getenv('PROXY_NUM', 0)) + if proxy_num > 0: + app.wsgi_app = ProxyFix(app.wsgi_app, x_for=proxy_num, x_proto=proxy_num) + + # ============================================================ + # 注册操作日志自动记录中间件（必须在事务拦截器之前注册， + # 确保 after_request 中日志写入先于事务提交，日志随事务一起持久化） + # ============================================================ + register_operation_log(app) + + # ============================================================ + # 注册 AOP 事务拦截器（核心：一行代码搞定所有事务） + # ============================================================ + register_transaction(app) + + # ============================================================ + # 注册蓝图（路由分组管理） + # ============================================================ + register_blueprint(app) + + # ============================================================ + # 初始化第三方扩展 + # ============================================================ + register_extends(app) + + # ============================================================ + # 注册中间件（请求/响应拦截处理） + # ============================================================ + register_middleware(app) + + # ============================================================ + # 注册全局异常处理器（确保最后注册，能捕获所有环节异常） + # ============================================================ + register_error_handlers(app) + + return app diff --git a/tests/conftest.py b/tests/conftest.py index 7a6298f..412e23a 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -2,18 +2,30 @@ pytest 全局配置 ============================================================= -P1 阶段仅搭建骨架，保证 `pytest` 可空跑。 -测试 App 构建、数据库/Redis fixture 在 P8（测试完善阶段）补充： -- app fixture：create_app() + 测试库 DATABASE_URL 覆盖 -- db fixture：事务内建表/清库 -- client fixture：Flask test_client +P1 阶段： + - flask_app fixture：最小 Flask 应用（供 jsonify 等需应用上下文的功能测试） + - 项目根目录加入 sys.path + +P8 阶段补充（测试完善）： + - app fixture：create_app() + 测试库 DATABASE_URL 覆盖 + - db fixture：事务内建表/清库 + - client fixture：Flask test_client """ import os import sys +import pytest +from flask import Flask + # 项目根目录加入 sys.path（tests/ 已有 __init__.py 时 pytest 通常自动处理， # 此处显式补充，兼容从任意目录启动 pytest 的场景） ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) if ROOT not in sys.path: sys.path.insert(0, ROOT) + + +@pytest.fixture +def flask_app(): + """最小 Flask 应用实例（无数据库/中间件，仅提供应用上下文）。""" + return Flask(__name__) diff --git a/tests/unit/test_core/test_response.py b/tests/unit/test_core/test_response.py index 8081ecf..2336282 100644 --- a/tests/unit/test_core/test_response.py +++ b/tests/unit/test_core/test_response.py @@ -3,6 +3,9 @@ R 统一响应格式单元测试 验证 `R.ok()` / `R.failed()` 返回的 JSON 响应结构符合前后端约定： {code, data, msg, ok}（code=0 成功，非 0 失败）。 + +说明：`R.ok()` 内部使用 `jsonify`，须在 Flask 应用上下文内调用 +（fixture：flask_app，见 tests/conftest.py）。 """ from utils import R @@ -11,8 +14,9 @@ from utils import R class TestOk: """成功响应""" - def test_ok_default_format(self): - resp = R.ok() + def test_ok_default_format(self, flask_app): + with flask_app.app_context(): + resp = R.ok() body = resp.get_json() assert body["code"] == 0 @@ -20,33 +24,38 @@ class TestOk: assert body["data"] is None assert body["msg"] - def test_ok_with_data(self): - resp = R.ok(data={"id": 1, "name": "张三"}) + def test_ok_with_data(self, flask_app): + with flask_app.app_context(): + resp = R.ok(data={"id": 1, "name": "张三"}) body = resp.get_json() assert body["code"] == 0 assert body["data"] == {"id": 1, "name": "张三"} - def test_ok_with_kwargs(self): - resp = R.ok(data=[], total=100) + def test_ok_with_kwargs(self, flask_app): + with flask_app.app_context(): + resp = R.ok(data=[], total=100) body = resp.get_json() + assert body["code"] == 0 assert body["total"] == 100 class TestFailed: """失败响应""" - def test_failed_default_format(self): - resp = R.failed() + def test_failed_default_format(self, flask_app): + with flask_app.app_context(): + resp = R.failed() body = resp.get_json() assert body["code"] != 0 assert body["ok"] is False assert body["data"] is None - def test_failed_custom_code(self): - resp = R.failed(msg="未授权访问", code=401) + def test_failed_custom_code(self, flask_app): + with flask_app.app_context(): + resp = R.failed(msg="未授权访问", code=401) body = resp.get_json() assert body["code"] == 401 diff --git a/重构方案-v2.md b/重构方案-v2.md index faecf76..99a5162 100644 --- a/重构方案-v2.md +++ b/重构方案-v2.md @@ -351,7 +351,7 @@ from src.core.database import db # 统一 db 单例 | 阶段 | 内容 | 验收标准 | 风险 | |---|---|---|---| | **P0 基线** | `git init`；`.gitignore` 补 `logs/ instance/ *.pyc`；基线提交 | git 仓库可用，可 `git reset --hard` 回滚 | 无 | -| **P1 工具链** | pyproject.toml / requirements-dev.txt / .flake8 / .pre-commit / Makefile / pytest 骨架 | 现有代码 `flake8` 通过（或登记存量告警）；`pytest` 空跑通过 | 低 | +| **P1 工具链** | pyproject.toml / requirements-dev.txt / .flake8 / .pre-commit / Makefile / pytest 骨架 | 现有代码 `flake8` 通过（或登记存量告警）；`pytest` 空跑通过。**已登记存量告警：154 条（F401×111 / E402×36 / 其余 7）；pytest 5 passed** | 低 | | **P2 core+common** | 建 `src/core/` `src/common/`；extensions/utils 打 shim；模型聚合器建 `src/models_registry.py` | `python app.py` 启动；`flask db migrate` 仍全量识别表；全接口冒烟 | 高（依赖面最大） | | **P3 模块搬迁** | 按 §2.5 顺序逐组迁移 23 个模块（models→forms→services→views），每批打 shim + 验证 | 每批后 `python app.py` 启动 + 该模块接口回归通过 | 中 | | **P4 服务层改造** | 26 个服务文件改「入参数据/出参数据」；router 取参包 R；引入 base_service/base_repository + BizError | 核心服务（auth/user/role/menu）单测可写可跑；接口回归全绿 | 高（最大工作量） |