📚 课程目录第2章审计SDK核心概念与设计原则

审计SDK核心概念与设计原则

好，我们正式开始动手前的概念准备。这一章是整门课的地基，我会带你梳理审计SDK里那几个跑不掉的核心抽象，以及它们之间的协作方式。我个人习惯在做架构之前，先把这些概念在脑子里过一遍，不然写出来的代码很容易变成一锅粥。

本章核心目标：掌握审计事件、采集器、处理器三大抽象，理解松耦合的设计原则。看完这章，你应该能画出一张清晰的类协作图。

审计事件：一切数据的载体

先说审计事件。说白了，它就是一条审计记录的“标准信封”。你在系统里做的每一次敏感操作——比如用户登录、数据导出、权限变更——最终都会被包装成一个事件对象，发往后端。

我在项目中见过最糟糕的情况，是每个业务方自定事件格式，有的用JSON字符串，有的用Protobuf，还有的直接拼文本塞到日志里。到了审计中心那边，解析脚本写了十几个版本。想想都头疼。

所以，我们需要一个统一的事件模型。我个人习惯把它拆成三个部分：

部分	内容	示例
事件头	事件ID、时间戳、事件类型、来源系统	event_id=uuid, ts=1700000000, type=login
主体信息	操作者ID、角色、IP、设备指纹	user_id=1001, role=admin, ip=192.168.1.1
业务载荷	操作对象、变更内容、结果状态	target=order_123, action=delete, success=true

// 一个简化的审计事件结构
public class AuditEvent {
    private String eventId;        // 全局唯一
    private long timestamp;        // 纳秒级时间
    private String type;           // login / export / permission_change
    private String sourceSystem;   // trading-service / risk-service
    private String operatorId;     // 谁做的
    private String operatorRole;   // admin / auditor / user
    private String target;         // 对什么做的
    private String action;         // create / update / delete
    private boolean success;       // 操作是否成功
    private Map<String, Object> details; // 扩展信息
}

我的建议：事件头一定要包含全局唯一ID和精确到纳秒的时间戳。否则审计链路追溯时，你根本分不清两条记录谁先谁后。

采集器：从哪里来

采集器的职责很纯粹——把业务代码里的零散操作点，转化成标准事件。

你想想看，业务系统的操作点到处都是：Controller层拦截HTTP请求，Service层记录数据库变更，MQ消费者处理第三方回调。每个地方都需要审计，但你不能在每个地方复制粘贴同一段报审计的代码。

这就是采集器的意义。它帮你抽离出“取数据”和“发数据”的动作。常见的采集方式有几种：

AOP拦截：通过注解或切面自动捕获方法调用
中间件钩子：从消息队列、数据库CDC流接入
SDK主动上报：业务方调用一个api直接传入关键字段

我去过一家金融科技公司，他们的SDK就是无侵入的AOP采集器。开发人员只需要加一个@Audit("资金划转")注解，后续的参数提取、事件构造、异步发送，全部由采集器自动完成。很舒坦，对吧？

// 注解驱动的采集器示例
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Audit {
    String action();        // 操作名
    String resource();      // 资源类型
}

// 使用方
@Service
public class TransferService {
    @Audit(action = "fund_transfer", resource = "account")
    public boolean transfer(String fromId, String toId, BigDecimal amount) {
        // 业务逻辑
    }
}

处理器：到哪里去

事件被采集之后，需要一组处理器来完成后续工作。处理器的职责同样单一——接住事件，做一件事。

嗯，这里要注意：处理器之间不能相互依赖。我习惯让每个处理器只看事件本身，不关心其他处理器做了什么。

典型的处理器链路：

校验处理器：检查事件字段是否完整，时间戳是否合法
增强处理器：补充IP地理位置、设备信息等上下文
持久化处理器：写入ES、ClickHouse或专用审计库
告警处理器：命中风险规则时推送钉钉/邮件
归档处理器：超过保存周期的事件冷备到OSS

我曾经踩过一个坑：持久化处理器和告警处理器之间有隐式调用，持久化报错直接导致告警没发出来。后来我把它们彻底拆开，用事件总线解耦，一个处理器挂了不影响其他的。

// 处理器接口定义
public interface EventProcessor {
    void process(AuditEvent event);
}

// 实现示例
public class PersistenceProcessor implements EventProcessor {
    @Override
    public void process(AuditEvent event) {
        // 写入数据库，失败记录到死信队列
    }
}

public class AlertProcessor implements EventProcessor {
    @Override
    public void process(AuditEvent event) {
        // 检查规则，触发告警
    }
}

松耦合设计：让SDK活下来

为什么要强调松耦合？你做的是SDK，不是单体应用。SDK一旦发布出去，你就无法控制使用方的代码版本。如果各组件耦合紧密，未来任何一个改动——比如升级采集器版本、替换序列化方案——都可能导致整个使用方系统出问题。

我推荐三条设计原则：

组件依赖接口，不依赖实现：采集器和处理器之间通过EventBus或Channel通信，不直接调用
每个组件只做一件事：校验的不写库，告警的不增强
配置驱动而非代码驱动：处理器顺序、采集器开关、重试策略全走配置文件

你想想看，假如你的SDK里采集器直接new了一个ES客户端去写数据，哪天ES集群换成了ClickHouse，你是不是得重新发版让所有业务方升级？但如果采集器和持久化处理器之间只通过队列传递事件，替换方案只是个配置项的事。

整体架构图

下面这张图展示了审计SDK内部三大核心概念之间的流转关系。你可能觉得简单，但这正是我要的效果——复杂的东西藏在细节里，架构本身应该一目了然。

我的经验：架构图画成这样已经够用了。不要在一张图里塞太多细节——每个组件的配置项、线程模型、重试策略，应该单独用文档或者代码注释说明。图是用来沟通核心关系的，不是用来装所有信息的。

总结：记住这三点

第二章的内容就这些。你不需要记住所有细节，但下面三点建议你刻在脑子里：

审计事件是唯一的数据契约，头信息、主体、业务载荷三段式不要随便改
采集器只管把原始操作转成标准事件，不要越界去做持久化或告警
处理器各司其职，彼此独立，通过事件总线串联

只要掌握这些核心抽象，后面几章我们开始动手写代码时，你就知道每一行应该放在哪个模块里了。不会有模棱两可的“这段该放哪里”的问题。