4、快速集成入门：添加SDK依赖、配置最小化参数、验证集成是否成功（Hello World示例）

说实话，我见过太多团队把SDK集成搞得很复杂。

明明一个Hello World就能跑通的事，非要先读三天文档，结果第一步就卡在依赖冲突上。所以这章咱们直奔主题——**先让SDK跑起来**，其他细节后面慢慢聊。

4.1 三步走，不废话

我个人的经验是：快速集成只要搞定三件事——加依赖、配参数、写一行验证代码。下面这张图把流程说清楚了。

4.2 添加SDK依赖

以Java生态为例。我个人习惯把SDK版本统一放到<properties>里管理，省得后面更新时到处找。

<properties>
    <audit-sdk.version>1.2.0</audit-sdk.version>
</properties>

<dependency>
    <groupId>com.yourcompany.audit</groupId>
    <artifactId>data-access-audit-sdk</artifactId>
    <version>${audit-sdk.version}</version>
</dependency>

Gradle用户看这里：

dependencies {
    implementation 'com.yourcompany.audit:data-access-audit-sdk:1.2.0'
}

4.3 配置最小化参数

说白了，SDK要正常工作只需要两个东西：应用标识（appId）和密钥（appSecret）。别的参数后面再慢慢调。

配置方式有两种，我推荐第二种——从环境变量读取，这样不会把密钥提交到Git仓库。

对应的Java Config代码（Spring Boot环境下）：

@Configuration
public class AuditConfig {

    @Value("${audit.app-id}")
    private String appId;

    @Value("${audit.app-secret}")
    private String appSecret;

    @Bean
    public AuditSdkClient auditSdkClient() {
        return AuditSdkClient.builder()
                .appId(appId)
                .appSecret(appSecret)
                .build();
    }
}

4.4 验证集成：Hello World

SDK初始化完成后，怎么写第一行审计日志？

我一般会在项目启动后、第一个业务接口里加一段最简单的测试代码。目的只有一个：确认SDK能正常收发消息。

@RestController
public class HelloController {

    @Autowired
    private AuditSdkClient auditClient;

    @GetMapping("/hello-audit")
    public String hello() {
        // 发送一条最简单的审计事件
        auditClient.audit(AuditEvent.builder()
                .eventType("HELLO_WORLD")
                .operator("system")
                .resource("test")
                .action("check")
                .result(AuditResult.SUCCESS)
                .build());

        return "集成成功！请查看审计日志控制台。";
    }
}

启动项目后，访问 /hello-audit，然后去SDK自带的日志控制台（或对接的日志平台）查看。如果看到类似下面的输出，那就说明集成成了：

[AUDIT] 2025-03-21 14:30:00 | HELLO_WORLD | system | test | check | SUCCESS

4.5 常见问题速查

如果上面步骤走完了还没看到日志，别慌。八成是下面三个原因之一：

• 依赖冲突——用 mvn dependency:tree 检查是否有其他库引入了旧版本的 okhttp 或 jackson，排除掉就好。
• appSecret不正确——我遇到过有人把开发库的密钥复制成带空格的……肉眼看不出来。建议先写死一个已知正确的值，跑通了再改回环境变量。
• 网络不通——SDK初始化时会试图连接配置的审计服务地址。可以手动 curl 一下那个地址，看能不能通。