FastHTML 支持将路由逻辑按功能拆分到多个 Python 模块中，通过共享同一 FastHTML 实例实现解耦，提升大型项目的可维护性与协作效率。
fasthtml 支持将路由逻辑按功能拆分到多个 python 模块中，通过共享同一 `fasthtml` 实例实现解耦，提升大型项目的可维护性与协作效率。
在 FastHTML（基于 FastAPI 的轻量级全栈框架）中，路由本质上是绑定到 FastHTML 应用实例的函数装饰器（如 @app.get(...)）。因此，实现路由模块化的核心原则是：所有路由模块必须导入并复用同一个 app 实例，而非各自创建新应用——这与 Flask 的 Blueprint 思路不同，但更贴近 FastAPI 原生风格。
✅ 推荐结构：单实例 + 多路由模块
以下是一个清晰、生产就绪的模块化组织方式：
1. app.py —— 全局应用实例定义
此文件集中初始化 FastHTML 实例、全局中间件、静态资源挂载及基础配置，不定义任何路由：
# app.py
from fasthtml import common as fh
from fastapi.staticfiles import StaticFiles
myHeaders = [
fh.Meta(charset='UTF-8'),
fh.Meta(name='viewport', content='width=device-width, initial-scale=1'),
fh.Link(rel='stylesheet', href='https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.6.0/css/all.min.css')
]
# 创建唯一 FastHTML 实例
app = fh.FastHTML(
hdrs=myHeaders,
secret_key="your-secure-secret-key-here" # ⚠️ 生产环境请使用环境变量管理
)
# 挂载静态资源（如 CSS/JS）
app.mount("/static", StaticFiles(directory="static"), name="static")
? 提示：
secret_key不应硬编码；建议使用os.getenv("FASTHTML_SECRET")并配合.env文件管理。
2. routes/__init__.py —— 路由聚合入口
用于显式导入各子路由模块，确保其装饰器生效（Python 导入即执行），也便于统一管理依赖：
# routes/__init__.py from .tree import * # 加载 tree.py 中所有 @app.get 路由 from .field_event import * # 可继续添加：from .auth import *; from .api import *
3. routes/tree.py —— 功能路由模块示例
每个模块只关注自身业务逻辑，通过 from app import app 获取共享实例：
# routes/tree.py
from app import app
from fastapi import Request
# 注意：此处需确保 menuDict 和 getGeneralTreeViewCodeFH 已在作用域内
# 推荐做法：将业务函数放入 services/ 或 utils/ 模块中，再在此处导入
from services.menu import getGeneralTreeViewCodeFH
from utils.xmother import newId
@app.get("/softprop/tree")
def get_tree_view(request: Request):
request.session['id'] = newId(10)
return getGeneralTreeViewCodeFH(menuDict=menuDict)
4. routes/field_event.py —— 另一功能模块
# routes/field_event.py
from app import app
from fastapi import Request
from services.menu_params import getFieldEventDef
@app.get("/softprop/fieldEvent")
def handle_field_event(request: Request):
return getFieldEventDef(request)
5. main.py —— 启动入口
仅负责导入路由并调用 serve()，保持极简：
# main.py
from app import fh
import routes # ← 关键：触发 routes/__init__.py 的导入，从而加载所有子路由
if __name__ == "__main__":
fh.serve()
⚠️ 注意事项与最佳实践
-
导入顺序至关重要：必须先导入
app，再导入routes；否则路由无法绑定到实例。 -
避免循环导入：确保
app.py不反向依赖routes/中的模块（如业务函数应放在services/或utils/下）。 -
类型提示支持：FastHTML 完全兼容 FastAPI 的
Request、Response、依赖注入等特性，可在路由中自由使用。 -
调试技巧：启动前打印
len(app.routes)可验证路由是否成功注册。 -
扩展性建议：随着项目增长，可进一步按层级组织（如
routes/api/v1/,routes/pages/），并配合fh.add_middleware()添加统一日志或认证中间件。
通过以上结构，你不仅能干净地分离路由职责，还能无缝集成 FastHTML 的 HTMX 增强能力、会话管理、静态资源服务等全部特性——真正实现「小而精」框架下的「大而稳」工程实践。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
