|
|
"""
|
|
|
简化的动态路由发现与注册。
|
|
|
|
|
|
目录与命名规范（不满足则无法注册或导入失败）：
|
|
|
- 插件必须放在 ``app/plugin`` 下，且**顶级目录名**必须以 ``module_`` 开头，例如
|
|
|
``module_example``、``module_yourfeature``（扫描模式：``module_*/**/controller.py``）。
|
|
|
- 控制器文件名必须为 ``controller.py``（大小写敏感，Linux 上 ``Controller.py`` 无效）。
|
|
|
- 从 ``module_xxx`` 到 ``controller.py`` 的**每一级目录名**须为合法 Python 标识符
|
|
|
（仅字母数字下划线、不以数字开头；不要使用中划线、空格、中文目录名等）。
|
|
|
- 每一级目录应可作为包导入：通常需有 ``__init__.py``（或符合 namespace package 规则）。
|
|
|
- 在 ``controller.py`` 的**模块顶层**定义 ``APIRouter`` 实例并赋值给变量
|
|
|
（如 ``DemoRouter = APIRouter(...)``）；定义在函数内部的 router **不会被**扫描到。
|
|
|
|
|
|
路由前缀：顶级目录 ``module_xxx`` 映射为容器前缀 ``/xxx``（去掉前缀 ``module_`` 共 7 个字符）。
|
|
|
|
|
|
常见「路由没注册」原因：
|
|
|
- 目录不叫 ``module_*``，或 ``controller.py`` 不在该树下的任意子路径中。
|
|
|
- 包无法导入：缺 ``__init__.py``、目录名非法、拼写不一致。
|
|
|
- ``controller.py`` 无语法错误但模块内没有任何顶层 ``APIRouter`` 变量。
|
|
|
"""
|
|
|
|
|
|
# 标准库导入
|
|
|
import importlib
|
|
|
import sys
|
|
|
from pathlib import Path
|
|
|
|
|
|
# 第三方库导入
|
|
|
from fastapi import APIRouter
|
|
|
from fastapi import FastAPI as _FastAPI
|
|
|
|
|
|
# 内部库导入
|
|
|
from app.core.logger import logger
|
|
|
|
|
|
# 模块级缓存：最近一次构建的动态路由实例
|
|
|
_dynamic_router_cache: APIRouter | None = None
|
|
|
# 记录最近一次注册到 app 的插件路径前缀，用于热重载时精准移除
|
|
|
_registered_plugin_prefixes: set[str] = set()
|
|
|
# 运行时引用，由 init_app.py 设置
|
|
|
_app_ref: _FastAPI | None = None
|
|
|
|
|
|
|
|
|
def set_app_ref(app: _FastAPI) -> None:
|
|
|
"""由 init_app.py 在 app 创建后调用，存储引用供热重载使用。"""
|
|
|
global _app_ref
|
|
|
_app_ref = app
|
|
|
|
|
|
|
|
|
def _build_dynamic_router() -> APIRouter:
|
|
|
"""实际执行扫描，返回新的动态路由 APIRouter 实例。"""
|
|
|
logger.info("🚀 开始动态路由发现与注册")
|
|
|
|
|
|
root_router = APIRouter()
|
|
|
seen_router_ids: set[int] = set()
|
|
|
try:
|
|
|
base_package = importlib.import_module("app.plugin")
|
|
|
base_dir = Path(next(iter(base_package.__path__)))
|
|
|
|
|
|
controller_files = list(base_dir.glob("module_*/**/controller.py"))
|
|
|
controller_files.sort()
|
|
|
|
|
|
container_routers: dict[str, APIRouter] = {}
|
|
|
|
|
|
for file in controller_files:
|
|
|
rel_path = file.relative_to(base_dir)
|
|
|
path_parts = rel_path.parts
|
|
|
top_module = path_parts[0]
|
|
|
|
|
|
suffix = top_module[7:] if top_module.startswith("module_") else ""
|
|
|
if not suffix:
|
|
|
logger.error(
|
|
|
f"❌ 跳过异常顶级目录名（须为 module_ 前缀且后面还有名称）: {top_module!r}，"
|
|
|
f"文件: {file}"
|
|
|
)
|
|
|
continue
|
|
|
prefix = f"/{suffix}"
|
|
|
|
|
|
if prefix not in container_routers:
|
|
|
container_routers[prefix] = APIRouter(prefix=prefix)
|
|
|
container_router = container_routers[prefix]
|
|
|
|
|
|
module_path = f"app.plugin.{'.'.join(path_parts[:-1])}.controller"
|
|
|
try:
|
|
|
module = importlib.import_module(module_path)
|
|
|
registered_here = 0
|
|
|
for attr_name in dir(module):
|
|
|
attr_value = getattr(module, attr_name, None)
|
|
|
if isinstance(attr_value, APIRouter):
|
|
|
router_id = id(attr_value)
|
|
|
if router_id not in seen_router_ids:
|
|
|
seen_router_ids.add(router_id)
|
|
|
container_router.include_router(attr_value)
|
|
|
registered_here += 1
|
|
|
logger.info(f" ↳ 注册 APIRouter 变量 `{attr_name}` ← {module_path}")
|
|
|
|
|
|
if registered_here == 0:
|
|
|
logger.warning(
|
|
|
f"⚠️ 模块已加载但未注册任何路由: {module_path}\n"
|
|
|
f" 原因：该文件中未找到**顶层** APIRouter 实例。\n"
|
|
|
f" 规范：在 controller.py 模块顶层定义，例如 "
|
|
|
f"`XxxRouter = APIRouter(route_class=..., prefix=..., tags=[...])`，"
|
|
|
f"不要仅在函数内创建 APIRouter。"
|
|
|
)
|
|
|
|
|
|
except Exception as e:
|
|
|
hint = _import_failure_hint(e)
|
|
|
logger.error(f"❌ 处理模块失败: {module_path}\n {hint}\n 异常: {e!s}")
|
|
|
|
|
|
for prefix, container_router in sorted(container_routers.items()):
|
|
|
route_count = len(container_router.routes)
|
|
|
root_router.include_router(container_router)
|
|
|
if route_count == 0:
|
|
|
logger.warning(
|
|
|
f"⚠️ 容器前缀 {prefix} 下未挂载任何子路由（可能该 module 下所有 controller 均未导出 APIRouter）"
|
|
|
)
|
|
|
logger.info(f"✅ 注册容器: {prefix} (子路由数: {route_count})")
|
|
|
|
|
|
# 记录本次注册的所有插件前缀，供热重载时精准移除
|
|
|
global _registered_plugin_prefixes
|
|
|
_registered_plugin_prefixes = set(container_routers.keys())
|
|
|
|
|
|
logger.info(f"✅ 动态路由发现完成: 共 {len(container_routers)} 个容器前缀")
|
|
|
return root_router
|
|
|
|
|
|
except Exception as e:
|
|
|
logger.error(f"❌ 动态路由发现整体失败: {e!s}")
|
|
|
return root_router
|
|
|
|
|
|
|
|
|
def get_dynamic_router() -> APIRouter:
|
|
|
"""
|
|
|
获取动态路由实例（带缓存）。
|
|
|
|
|
|
返回:
|
|
|
- APIRouter: 包含所有动态路由的根路由实例
|
|
|
"""
|
|
|
global _dynamic_router_cache
|
|
|
if _dynamic_router_cache is None:
|
|
|
_dynamic_router_cache = _build_dynamic_router()
|
|
|
return _dynamic_router_cache
|
|
|
|
|
|
|
|
|
def reload_dynamic_router() -> APIRouter:
|
|
|
"""
|
|
|
清除插件模块缓存并重新扫描，同时更新已挂载到 FastAPI app 的路由。
|
|
|
|
|
|
工作机制：
|
|
|
1. 根据 _registered_plugin_prefixes 精准移除 app.routes 中已注册的插件路由
|
|
|
2. 清除 sys.modules 中缓存的插件模块
|
|
|
3. 重新扫描并构建新的动态路由
|
|
|
4. 将新路由挂载回 app（include_router）
|
|
|
|
|
|
要求：init_app.py 在创建 app 后调用 discover.set_app_ref(app)，
|
|
|
否则路由重载仅重建 Router 对象，不会更新运行中的 app。
|
|
|
|
|
|
返回:
|
|
|
- APIRouter: 重新构建后的动态路由实例
|
|
|
"""
|
|
|
global _dynamic_router_cache, _registered_plugin_prefixes, _app_ref
|
|
|
|
|
|
app = _app_ref
|
|
|
|
|
|
# ── 1. 从运行中的 app 移除旧的插件路由 ──
|
|
|
if app and _registered_plugin_prefixes:
|
|
|
before = len(app.routes)
|
|
|
app.routes = [
|
|
|
r for r in app.routes
|
|
|
if not any(
|
|
|
getattr(r, "path", "").startswith(p)
|
|
|
for p in _registered_plugin_prefixes
|
|
|
)
|
|
|
]
|
|
|
removed = before - len(app.routes)
|
|
|
logger.info(f"🧹 已移除 {removed} 条旧插件路由（前缀: {_registered_plugin_prefixes}）")
|
|
|
elif not app:
|
|
|
logger.warning("⚠️ _app_ref 未设置，无法更新运行中的 app 路由；请确认 init_app.py 已调用 discover.set_app_ref(app)")
|
|
|
|
|
|
# ── 2. 清除插件模块缓存，迫使 importlib 重新执行模块代码 ──
|
|
|
_purge_plugin_modules()
|
|
|
|
|
|
# ── 3. 将新路由挂载回 app ──
|
|
|
if app:
|
|
|
# 构造与 init_app.py 中相同的依赖项
|
|
|
app.include_router(_build_dynamic_router())
|
|
|
logger.info("✅ 新插件路由已挂载到运行中的 app")
|
|
|
|
|
|
logger.info("✅ 插件动态路由热重载完成")
|
|
|
return _build_dynamic_router()
|
|
|
|
|
|
|
|
|
def _purge_plugin_modules() -> None:
|
|
|
"""
|
|
|
从 sys.modules 中清除所有 app.plugin.module_* 模块，
|
|
|
使下一次 importlib.import_module 时重新执行模块代码。
|
|
|
"""
|
|
|
prefix = "app.plugin.module_"
|
|
|
purged: list[str] = []
|
|
|
for mod_name in list(sys.modules):
|
|
|
if mod_name.startswith(prefix):
|
|
|
del sys.modules[mod_name]
|
|
|
purged.append(mod_name)
|
|
|
|
|
|
if purged:
|
|
|
logger.info(f"🧹 已清除 {len(purged)} 个插件模块缓存，将重新导入")
|
|
|
else:
|
|
|
logger.info("🧹 未发现需要清除的插件模块缓存")
|
|
|
|
|
|
|
|
|
def _import_failure_hint(exc: BaseException) -> str:
|
|
|
"""根据异常类型给出简短排查提示（中文日志）。"""
|
|
|
if isinstance(exc, ModuleNotFoundError):
|
|
|
missing = getattr(exc, "name", None) or str(exc)
|
|
|
return (
|
|
|
f"无法解析模块（ModuleNotFoundError: {missing}）。"
|
|
|
"常见原因：① 从 app.plugin 到 controller 的某级目录缺少 __init__.py；"
|
|
|
"② 目录名不是合法 Python 标识符（禁用连字符、空格、中文等）；"
|
|
|
"③ 磁盘路径与 import 路径不一致（大小写、子目录名拼写）。"
|
|
|
)
|
|
|
if isinstance(exc, ImportError):
|
|
|
return (
|
|
|
"导入失败（ImportError）。常见原因：controller 或其依赖模块循环导入、"
|
|
|
"第三方依赖未安装、或相对导入路径错误。"
|
|
|
)
|
|
|
if isinstance(exc, SyntaxError):
|
|
|
return f"controller.py 存在语法错误：{exc.msg}（约第 {exc.lineno} 行）。"
|
|
|
if isinstance(exc, PermissionError):
|
|
|
return (
|
|
|
"权限错误（PermissionError）。多见于受限环境（沙箱、部分 CI）："
|
|
|
"import 链上某模块初始化时调用了被禁止的系统能力（如进程池），与目录命名无关。"
|
|
|
"在完整操作系统下重试；若仍失败再结合堆栈排查。"
|
|
|
)
|
|
|
return (
|
|
|
f"未分类异常（{type(exc).__name__}）。请查看下方堆栈；"
|
|
|
"若与命名/包结构无关，可能是 controller 顶层 import 的依赖在加载时失败。"
|
|
|
)
|
|
|
|
|
|
|
|
|
# 重新导出函数供外部使用
|
|
|
__all__ = ["get_dynamic_router", "reload_dynamic_router"]
|