Flask装饰器必须返回函数且正确透传元信息，否则路由注册失败；需用@functools.wraps保留函数名，避免在闭包中访问request等上下文对象，权限检查应支持多种凭据来源并抛出标准HTTPException异常。
装饰器必须接收并返回函数，否则 Flask 路由注册会失败
Flask 的 @app.route 本质是把函数注册进路由表，如果自定义装饰器没正确透传原函数（比如忘了 return func 或漏了 @functools.wraps(func)），会导致视图函数变成 None 或丢失元信息，最终报错 AssertionError: View function mapping is overwriting an existing endpoint function 或 404。
实操建议：
- 所有装饰器内部必须以
return func（或包装后的可调用对象）结尾，不能只执行逻辑不返回 - 务必加
@functools.wraps(func)，否则flask.url_for、调试器、日志里的函数名都会变成装饰器内层名字 - 不要在装饰器里直接
return "xxx"响应，除非你明确要拦截请求——那得返回合法的响应对象，比如flask.Response或字符串（Flask 会自动转）
权限检查类装饰器要兼容函数参数，别硬编码 request.args
很多人写鉴权装饰器时直接读 request.args.get("token")，结果用在 POST JSON 接口上就取不到值，因为 token 其实放在 Header 或 body 里。这类装饰器失效的根本原因是没抽象出「如何取凭据」的策略。
实操建议：
- 把凭据提取逻辑抽成可选参数，例如
auth_from="header"、auth_from="json"、auth_from="cookie" - 避免在装饰器闭包里直接访问
request全局对象——它只在请求上下文中有效，单元测试或离线调用会报RuntimeError: Working outside of application context - 真要访问
request，确保装饰器实际生效时机是在视图函数被调用时（即内层 wrapper 中），而不是定义时
@login_required 这类装饰器不能替代 before_request 的全局检查
@login_required 看起来方便，但每个路由都得手动加，容易漏；而全量用 @app.before_request 又没法跳过健康检查、静态资源等免检路径，导致 401 泛滥。
实操建议：
- 用装饰器标记「需要认证」的视图，再配合
before_request统一处理：先查当前 endpoint 是否被某个认证装饰器标记（比如设func.requires_auth = True），再决定是否校验 - 避免在装饰器里做重定向（如
return redirect("/login")），尤其当它和before_request嵌套时，可能触发多次跳转或响应已提交错误 - 如果项目有多个认证方式（JWT / Session / API Key），装饰器最好支持传入验证函数，而不是写死逻辑，例如
@require_auth(verify_func=verify_jwt)
装饰器里抛异常要小心，Flask 默认不捕获非 HTTPException
在装饰器里写 raise ValueError("invalid token")，结果前端收到 500 而不是 401，日志里还堆着 traceback。这是因为 Flask 只自动处理继承自 werkzeug.exceptions.HTTPException 的异常（比如 abort(401) 或 HTTPException 子类）。
实操建议：
- 统一用
from werkzeug.exceptions import Unauthorized, Forbidden等标准异常，或自定义继承它们的类 - 不要依赖
try/except ValueError在装饰器里“优雅降级”，它不会被 Flask 的错误处理器捕获，除非你额外配@app.errorhandler(ValueError) - 如果必须用业务异常，至少在装饰器 wrapper 里包一层
raise Unauthorized()，并把原始信息记到日志里，别暴露给前端
最常被忽略的是装饰器的「延迟执行」特性——它看起来在定义时运行，其实逻辑全在请求进来后才触发。任何试图在装饰器外层闭包里操作 request、session 或调用 url_for 的行为，基本都会在测试或 CLI 调用时崩掉。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
