不加 @functools.wraps 就废，装饰器必须 return wrapper 且用 @functools.wraps 保留原函数签名；凭据提取需动态支持多来源；权限应通过函数注解驱动而非硬编码。
@functools.wraps 不加就废，这是最常被忽略的硬性前提。
Flask路由注册失败：装饰器没return func 或漏掉 @functools.wraps
Flask 的 @app.route 本质是把函数注册进内部路由表；如果自定义装饰器没正确透传原函数，比如写成 def my_auth(func): ... # 忘了 return wrapper，那最终注册进去的就是 None，直接报 AssertionError: View function mapping is overwriting an existing endpoint function 或 404。
实操建议：
- 所有装饰器末尾必须明确 return wrapper（或包装后的可调用对象）
- 每个 wrapper 函数前必须加 @functools.wraps(func)，否则 flask.url_for('view_user_profile') 会找不到函数名，调试器里也看不到原始函数签名
- 别用 print(func.__name__) 测试——它可能显示 wrapper，但真正影响的是框架内部反射逻辑
鉴权逻辑失效：凭据提取方式写死在闭包里
常见错误是直接在装饰器顶层读 request.args.get("token")，结果 POST JSON 接口根本取不到 token——因为 token 在 Header 或 request body 里。
问题根源在于凭据来源没抽象，导致装饰器只能适配一种场景。
实操建议：
- 把提取策略做成参数，例如 @require_auth(auth_from="header", key="Authorization")
- 真正取值动作必须放在 wrapper 内部，而不是装饰器定义时（避免 RuntimeError: Working outside of application context）
- 支持多种来源：Header、JSON body、Cookie、Query 参数，统一转成 token 字符串再校验
权限粒度失控：硬编码角色 vs 动态注解驱动
写成 @require_permission("admin") 看似简单，但一旦权限规则变复杂（比如“编辑文章需 author_id == current_user.id”），就得重写装饰器逻辑。
更灵活的做法是结合函数注解：
- 在函数上标注 def edit_post(post_id: int) -> None: ...，同时加注解 edit_post.__annotations__["permission"] = "post:write"
- 装饰器从 func.__annotations__.get("permission") 动态读取策略，再调用对应校验器
- 这样业务函数本身不耦合鉴权细节，权限变更只需改注解或后端策略，不碰路由函数
全局拦截 vs 单点控制：别用 @app.before_request 替代装饰器
@login_required 类装饰器不是“可选优化”，而是精准控制开关的必要手段。用 @app.before_request 做全量鉴权，健康检查、静态资源、Swagger UI 全都会被拦住，返回一堆 401。
实操建议：
- 装饰器按需加在具体视图函数上，天然支持免检路径
- 若需批量应用，可用 for rule in app.url_map.iter_rules(): if rule.rule.startswith('/api/'): ... 动态注册，而非一刀切
- 注意执行顺序：多个装饰器叠加时，@require_auth 应在 @cache 外层，否则未鉴权就缓存了错误响应
装饰器简化 API 鉴权，核心不在“少写几行代码”，而在把「谁能在何时以何种方式访问」这个策略，从函数体里彻底抽离出来——但抽离的前提是，你得先让 wrapper 真正能跑通、能取到数据、能动态响应变化。漏掉 @functools.wraps、写死凭据来源、忽略注解潜力，这三个点踩中任意一个，装饰器就从利器变成隐患。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
