Flask 的 app.route 不能直接写在业务模块里，因为会导致路由与业务逻辑耦合，难以测试和复用；应将请求解析收口至视图层，业务函数只依赖明确输入输出，使用 Pydantic 或 dataclass 定义接口，异常由视图层统一处理。
为什么 Flask 的 app.route 不能直接写在业务模块里
接口服务化不是把函数加个 @app.route 就完事。一旦路由装饰器和业务逻辑混在同一个文件，比如 user_service.py 里既写 @app.route('/api/user') 又写数据库查询，后续就很难单独测试这个查询逻辑，也无法被其他非 HTTP 场景复用（比如定时任务、管理脚本）。
真正要解耦，得让业务函数「不知道自己被谁调用」——它只关心输入参数和返回结果，不依赖 request、jsonify 或 Flask 上下文。
- 所有请求解析（如
request.json、request.args.get）必须收口到视图层（views） - 业务函数签名应尽量用普通 Python 类型：比如接收
user_id: int，而不是request - 避免在业务模块中 import
flask、current_app等框架对象
如何设计可复用的业务函数接口
关键不是“怎么写得漂亮”，而是“怎么让同事或半年后的你，能不看注释就安全调用”。推荐统一用数据类（dataclass）或 Pydantic BaseModel 描述入参和出参。
比如用户创建接口，不要这样写：
def create_user(name, email, age=None):
# 参数类型模糊，age 是 int 还是 str？可选但没说明默认值？
pass而应该定义明确结构：
from pydantic import BaseModelclass CreateUserInput(BaseModel): name: str email: str age: int | None = None
def create_user(input_data: CreateUserInput) -> dict:
返回 dict 而非 jsonify，保持无框架依赖
return {"id": 123, "name": input_data.name}
- 输入校验交给
CreateUserInput.model_validate()，不在业务函数里写 if-else 判空 - 返回值不用
JSONResponse或dict混搭，统一用dict或自定义 result class - 异常不抛
HTTPException，改用自定义业务异常（如UserExistsError），由视图层统一转成 400/409
Flask 蓝图（Blueprint）该怎么组织才不变成新包袱
很多人用蓝图只是为“分文件”，结果每个蓝图里还是 from app.models import * + @bp.route + 业务逻辑三合一，和没拆一样。
正确做法是按「能力域」而非「技术层」切分蓝图，并且蓝图只做三件事：解析请求、调用业务函数、包装响应。
- 蓝图文件（如
user_bp.py）里不应出现 SQL、Redis 调用、配置读取 - 蓝图导入路径必须是稳定接口：只 import
user_service.create_user，不 importuser_dao或cache_client - 一个蓝图对应一个 API 前缀（如
/api/v1/users），但内部函数名不要带api_或http_前缀
示例视图函数：
from flask import Blueprint, request, jsonify from user_service import create_user from user_schema import CreateUserInputuser_bp = Blueprint("user", name, url_prefix="/api/v1/users")
@user_bp.route("", methods=["POST"]) def handle_create_user(): data = CreateUserInput.model_validate(request.get_json()) try: result = create_user(data) return jsonify(result), 201 except UserExistsError as e: return jsonify({"error": str(e)}), 409
本地调试时怎么绕过 Flask 启动直接跑业务逻辑
解耦后最直接的好处：你可以完全不启动 Web 服务，就在 Python shell 或单元测试里调用 create_user(...)。但前提是——它真不依赖任何全局状态。
常见破功点：
- 业务函数里写了
current_app.config["DB_URL"]→ 改成显式传参或依赖注入 - 用了
g.db或session→ 把数据库连接作为参数传入，或用工厂函数封装 - 日志写的是
current_app.logger.info→ 改用标准库logging.getLogger(__name__)
验证是否真解耦：在 python -i 下执行
>>> from user_service import create_user
>>> from user_schema import CreateUserInput
>>> create_user(CreateUserInput(name="test", email="t@x.com"))
{'id': 123, 'name': 'tes
t'}
t'}如果这行能直接跑通，说明业务层已干净。至于它将来跑在 Flask、FastAPI 还是 Celery 里，已经不重要了。
模块解耦真正的难点，从来不是代码怎么分，而是团队对「谁该负责哪一层错误处理」「配置从哪来」「日志怎么打」有共识。没有约束的自由拆分，只会换来更难 debug 的分布式面条代码。
