Flask 动态模块注册

1. 项目概述

这个项目是一个基于Flask的动态模块注册系统，它允许你以一种模块化的方式组织API端点，并且能够自动发现和注册这些模块。这种架构特别适合构建可扩展的Web API服务，让你可以轻松地添加新功能而无需修改核心代码。

2. 项目结构

flask_path_test/
├── .venv/                  # Python虚拟环境目录
├── api/                    # API模块目录
│   ├── __init__.py         # 核心功能：动态模块注册系统
│   ├── product_app.py      # 产品模块
│   ├── user_app.py         # 用户模块
│   └── sdk/                # SDK模块目录
│       └── auth.py         # 认证SDK模块
├── .gitignore              # Git忽略文件配置
├── .python-version         # Python版本配置文件
├── pyproject.toml          # 项目配置文件
├── README.md               # 项目说明文档
├── setup_demo.py           # 应用程序入口文件
└── uv.lock                 # 依赖锁定文件

环境准备

uv init
uv venv
source .venv/bin/activate
uv pip install flask

3. 核心组件解析

3.1 动态模块注册系统 (api/__init__.py)

这个文件是整个系统的核心，它实现了以下功能：

• 自动发现模块：搜索所有符合命名规则的模块文件
• 动态加载模块：使用Python的importlib机制动态加载模块
• 注册Flask蓝图：将每个模块注册为Flask蓝图，并设置合适的URL前缀
• 提供主页视图：显示所有已注册的模块及其URL

关键函数：

• search_pages_path()：搜索所有以_app.py结尾的文件和SDK目录下的Python文件
• register_page()：将找到的模块文件注册为Flask蓝图
• auto_register_pages()：自动注册所有找到的模块
  代码：

import sys
from pathlib import Path
from importlib.util import spec_from_file_location, module_from_spec
from flask import Flask, Blueprint

# 创建Flask应用
app = Flask(__name__)
API_VERSION = "v1"
registered_urls = []

def search_pages_path(pages_dir):
    """搜索页面路径"""
    app_path_list = [
        path for path in pages_dir.glob("*_app.py") if not path.name.startswith(".")
    ]

    # 搜索根目录下的sdk
    api_sdk_path_list = [
        path for path in pages_dir.glob("*sdk/*.py") if not path.name.startswith(".")
    ]
    
    app_path_list.extend(api_sdk_path_list)
    return app_path_list

def register_page(page_path):
    """注册页面模块为Flask蓝图"""
    path = f"{page_path}"
    
    # 获取页面名称（去掉_app后缀）
    page_name = page_path.stem.rstrip("_app")
    
    # 构建模块名称
    module_name = ".".join(
        page_path.parts[page_path.parts.index("api"): -1] + (page_name,)
    )
    print(f"module_name: {module_name}")
    # 动态加载模块
    spec = spec_from_file_location(module_name, page_path)
    page = module_from_spec(spec)
    
    # 先设置app和manager，再执行模块代码
    page.app = app
    page.manager = Blueprint(page_name, module_name)
    sys.modules[module_name] = page
    spec.loader.exec_module(page)
    
    # 获取页面名称（可能在模块中重新定义）
    page_name = getattr(page, "page_name", page_name)
    
    # 确定URL前缀
    sdk_path = "\\sdk\\" if sys.platform.startswith("win") else "/sdk/"
    url_prefix = (
        f"/api/{API_VERSION}" if sdk_path in path else f"/{API_VERSION}/{page_name}"
    )
    print(f"url_prefix: {url_prefix}")
    # 注册蓝图
    app.register_blueprint(page.manager, url_prefix=url_prefix)
    return url_prefix

def auto_register_pages():
    """自动注册所有页面模块"""
    global registered_urls
    # 创建api目录结构
    api_dir = Path("api")
    api_dir.mkdir(exist_ok=True)
    
    # 搜索并注册所有页面
    page_paths = search_pages_path(api_dir)
    result = []
    print(page_paths)
    for page_path in page_paths:
        try:
            url_prefix = register_page(page_path)
            result.append((page_path.name, url_prefix))
            print(f"已注册模块: {page_path.name} -> {url_prefix}")
        except Exception as e:
            print(f"注册模块 {page_path.name} 失败: {e}")
    
    return result

@app.route('/')
def index():
    """主页显示所有注册的模块"""
    global registered_urls
    
    html = "<h1>Flask 动态模块注册演示</h1>"
    html += "<h2>已注册的模块:</h2><ul>"
    
    for module_name, url_prefix in registered_urls:
        html += f"<li><strong>{module_name}</strong>: <a href='{url_prefix}'>{url_prefix}</a></li>"
    
    html += "</ul>"
    html += "<p>访问上面的链接查看各个模块的功能</p>"

    return html

3.2 应用程序入口 (setup_demo.py)

这个文件是应用程序的入口点，它：

• 导入核心组件
• 调用auto_register_pages()注册所有模块
• 启动Flask应用服务器

from api import app, auto_register_pages, registered_urls

# 如果需要，可以在这里进行额外的配置
# app.config['SOME_CONFIG'] = 'some_value'

# 运行应用程序
if __name__ == '__main__':
    # 清空已注册的URL列表
    registered_urls.clear()
    
    # 手动注册所有模块
    result = auto_register_pages()
    registered_urls.extend(result)
    print(f"已注册的URL: {registered_urls}")
    
    # 运行应用程序
    app.run(debug=True, port=5000)

4. 模块开发指南

4.1 标准模块 (*_app.py)

标准模块文件需要遵循以下规则：

1. 文件名必须以_app.py结尾（例如：user_app.py、product_app.py）
2. 模块中可以定义page_name变量来自定义URL路径（可选）
3. 使用@manager.route()装饰器定义路由

示例（product_app.py）：

from flask import jsonify

# 可以自定义页面名称
page_name = "products"

@manager.route('/')
def product_list():
    """产品列表接口"""
    return jsonify({
        "message": "产品模块",
        "products": [
            {"id": 1, "name": "笔记本电脑", "price": 5999},
            {"id": 2, "name": "智能手机", "price": 2999}
        ]
    })

@manager.route('/<int:product_id>')
def product_detail(product_id):
    """产品详情接口"""
    return jsonify({
        "message": f"产品详情 - ID: {product_id}",
        "product": {"id": product_id, "name": f"产品{product_id}", "price": 1000 + product_id * 100}
    })

示例（user_app.py）：

from flask import jsonify

@manager.route('/')
def user_list():
    """用户列表接口"""
    return jsonify({
        "message": "用户模块",
        "users": [
            {"id": 1, "name": "张三", "email": "zhangsan@example.com"},
            {"id": 2, "name": "李四", "email": "lisi@example.com"}
        ]
    })

@manager.route('/<int:user_id>')
def user_detail(user_id):
    """用户详情接口"""
    return jsonify({
        "message": f"用户详情 - ID: {user_id}",
        "user": {"id": user_id, "name": f"用户{user_id}", "email": f"user{user_id}@example.com"}
    })

4.2 SDK模块 (sdk/*.py)

SDK模块放置在api/sdk/目录下，它们会被自动注册到/api/v1路径下。

示例（sdk/auth.py）：

from flask import jsonify, request

@manager.route('/', methods=['GET'])
def login():
    """登录接口"""
    return jsonify({
        "message": "SDK认证模块 - 登录",
        "token": "fake_jwt_token_12345",
        "expires_in": 3600
    })

5. URL路径规则

系统会根据模块类型和名称自动生成URL路径：

• 标准模块：/v1/{page_name}/
  • 例如：/v1/products/、/v1/user/
• SDK模块：/api/v1/
  • 例如：/api/v1/（auth模块）

6. 如何使用

6.1 启动应用

uv run setup_demo.py

应用将在http://localhost:5000启动，访问主页可以看到所有已注册的模块列表。

6.2 添加新模块

1. 在api/目录下创建新的*_app.py文件
2. 定义路由函数
3. 重启应用，新模块会被自动发现和注册

示例（创建新的order_app.py）：

from flask import jsonify

# 可以自定义页面名称
page_name = "orders"

@manager.route('/')
def order_list():
    """订单列表接口"""
    return jsonify({
        "message": "订单模块",
        "orders": [
            {"id": 1, "product_id": 1, "user_id": 1, "status": "已付款"},
            {"id": 2, "product_id": 2, "user_id": 2, "status": "待发货"}
        ]
    })

7. 工作原理

1. setup_demo.py启动时调用auto_register_pages()
2. auto_register_pages()搜索所有符合规则的模块文件
3. 对每个找到的文件，调用register_page()进行注册
4. register_page()动态加载模块，并将其注册为Flask蓝图
5. 所有注册的URL保存在registered_urls列表中，并在主页中显示

这个Flask动态模块注册系统提供了一种优雅的方式来组织和扩展你的API服务。通过遵循简单的命名约定和目录结构，你可以轻松添加新功能而无需修改核心代码。这种模块化的设计特别适合大型项目，让团队成员可以独立开发不同的功能模块。