functools.wraps是必选项，否则原函数的__name__、__doc__、__annotations__丢失，导致日志、监控、OpenAPI工具无法识别真实函数；埋点需用try-except兜底，禁用同步HTTP请求；带参装饰器须冻结参数避免闭包污染；Annotated仅作类型提示，无法替代运行时埋点逻辑。
装饰器加埋点时，为什么 functools.wraps 不是可选项而是必选项
不加 functools.wraps 会导致原函数的 __name__、__doc__、__annotations__ 全部丢失，日志、监控系统或 OpenAPI 自动生成工具会拿不到真实函数信息，埋点打上去也查不到归属。
- 典型现象：
logger.info(f"calling {func.__name__}")打出的是"wrapper"而不是真实函数名 - 调试时
help(my_func)显示空文档，IDE 自动补全失效 - FastAPI/Flask 的路由注册可能失败，因为框架依赖
__name__做唯一标识 - 必须写成：
@functools.wraps(func)，不能只导入不调用
埋点装饰器里怎么安全处理异常，避免拖垮主逻辑
埋点本身是旁路行为，一旦出错（比如网络超时、JSON 序列化失败）绝对不能让原函数跟着抛异常或卡住。
- 所有埋点逻辑必须包在
try...except Exception:里，且except中不做raise - 别用
logging.exception，它会打完整 traceback，高频调用下 I/O 压力大；改用logging.debug+ 简短错误描述 - 异步场景下禁用同步 HTTP 请求埋点；可用
asyncio.create_task发 fire-and-forget 请求，但要设timeout - 示例关键行：
try: send_to_monitoring(...); except Exception as e: logger.debug("track failed: %s", type(e).__name__)
带参数的埋点装饰器怎么避免闭包变量污染
写成 @track(category="api") 这种带参装饰器时，最容易踩的坑是外层函数返回的 wrapper 捕获了循环变量或上层局部变量，导致所有被装饰函数共享同一份参数。
- 常见错误：用
for category in ["a", "b"]:动态生成装饰器，结果所有函数都记成最后一个category - 正确做法：参数必须通过装饰器工厂的闭包「冻结」，即
def decorator(category=...): def wrapper(...): ... return wrapper - 验证方式：打印
wrapper.__closure__[0].cell_contents，确认值是你传进去的那个，不是引用或 None - 如果用了类装饰器，确保
__init__存的是不可变值（如str、int），别存dict或list后续被意外修改
Python 3.9+ 的 typing.Annotated 能替代装饰器埋点吗
不能。虽然 Annotated 可以附着元数据，但它只是类型提示的一部分，运行时不执行、不触发任何逻辑，对埋点这种需要副作用的操作完全无效。
-
def foo() -> Annotated[str, Track("login")]: ...这行代码在运行期和普通def foo() -> str:完全等价 - 类型检查器（mypy/pyright）可能读到注解，但不会调用你的埋点函数
- 想靠它自动注入逻辑，得配合第三方库如
beartype或自定义 AST 重写——成本远高于写个装饰器 - 真要减少装饰器侵入，可以考虑 AOP 框架如
aspectlib，但小项目没必要，反而增加部署复杂度
