注解是日志埋点与脱敏的核心手段，通过@logpoint、@logparam和@mask等声明式注解实现逻辑解耦、字段级控制及环境化策略，需注意作用域、序列化适配与上下文传递。
注解在日志埋点与脱敏中不是“锦上添花”，而是降低侵入性、提升可维护性的核心手段。关键在于把日志采集逻辑和业务代码解耦，同时让敏感字段的识别与处理变得声明式、可配置。
用自定义注解标记埋点位置
通过定义如 @LogPoint 的注解，标注在方法或参数上，明确此处需记录日志。注解可携带 level（INFO/WARN）、module（模块名）、desc（行为描述）等元数据，避免硬编码日志语句。
- 在切面（AOP）中统一拦截带该注解的方法，自动提取类名、方法名、入参、返回值、异常等上下文
- 支持对特定参数加 @LogParam 注解，只记录该参数（如订单ID），跳过整个 request 对象
- 结合 SpEL 表达式（如
#{#user.phone}）动态提取字段，兼顾灵活性与类型安全
用注解驱动字段级脱敏策略
不靠正则全局匹配手机号或身份证，而是让开发者在 DTO 或实体类字段上显式声明脱敏规则，例如 @Mask(type = MaskType.PHONE)。
- 脱敏逻辑在序列化前或日志拼装时触发，不影响业务层数据结构
- 支持多级策略：全掩码（138****1234）、部分保留（138***1234）、哈希脱敏（SHA256后取前8位）
- 可配合环境开关（如 dev 环境不脱敏、prod 强制脱敏），通过 Spring Profile 控制是否启用脱敏处理器
注解与日志框架协同的关键细节
Spring AOP 默认无法拦截 private 方法或内部调用，埋点注解需作用在 public 方法且被代理对象调用；脱敏注解若用于 JSON 序列化，则需适配 Jackson 的 JsonSerializer 或 FastJSON 的 SerializeFilter 。
- 避免在 @LogPoint 方法内手动调用 logger.info()，否则重复记录
- 脱敏注解若用于日志参数而非响应体，需在 AOP 中解析参数树，递归查找被注解的字段并替换值
- 建议为注解添加 @Documented 和 @Retention(RetentionPolicy.RUNTIME)，确保运行期可用
规避常见陷阱
注解看似简洁，但落地时容易因设计粒度或执行时机不当导致失效。
- 不要用一个注解同时承担埋点 + 脱敏 + 权限校验，职责混杂会增加维护成本
- 避免在 lombok 的 @Data 类上直接对 getter 加注解——JVM 不会识别，应注在字段上
- 异步线程中丢失 MDC 上下文，导致日志链路断裂，需在 AOP 中显式传递 traceId 并绑定到新线程
