📚 课程目录第4章 SDK快速接入指南

第4章 SDK快速接入指南

这一章，我带你亲手把 SDK 跑起来。你别看文档上写了一大堆初始化参数，其实核心就三步。我自己接过不下十种不同厂商的 SDK，踩过的坑比吃过的盐还多。今天我把最干净的路线给你画出来，你照着走就行。

4.1 获取 SDK

SDK 去哪拿？通常两个渠道：

官方仓库：GitHub Release 或者内网 Maven / npm 私服
控制台下载：在平台「SDK 管理」页面选好版本，一键下载

我个人习惯用 Maven/Gradle 直接引用，方便版本锁死。如果你从官网手动下载，注意核对文件的 checksum——我之前遇到过包损坏，初始化直接崩，排查了半天。

版本选择建议：不要追最新版，先看 Release Notes。选最近三个月内稳定发布的版本，并看一眼已知 Bug 列表。

解压后你会看到这些目录：

目录/文件	说明
lib/	核心 jar 包或 .so / .dylib
config/	默认配置文件模板
demo/	官方示例代码（这个很有用）
CHANGELOG.md	版本更新日志

4.2 初始化流程三步走

别被那些长篇大论的配置吓到。说白了你只需要做三件事：

引入依赖 – 把 jar 放到 classpath 里，或者一行 Maven 坐标。
配置凭证 – 你的 AppKey、Secret，还有服务端地址。
启动 SDK – 调一个方法，比如 RiskMonitor.init(context, config)。

我在项目中遇到过一个问题：第二步和第三步顺序反了。有些人先调 init，再设置配置，结果 SDK 用了空配置启动，所有规则都没生效。你想想看，这就像车子没加油就点火——能跑才怪。

注意：init 方法必须在主线程调用一次，之后的所有操作要放到后台线程。SDK 内部有线程池，你不需要自己 new Thread。

4.2.1 第一步：添加依赖

如果你是 Maven 项目，在 pom.xml 里加：

<dependency>
    <groupId>com.example</groupId>
    <artifactId>risk-monitor-sdk</artifactId>
    <version>4.2.1</version>
</dependency>

Gradle 类似。如果是纯 Java 工程，把 lib/ 下的 jar 扔进项目，记得右键 Add as Library。

4.2.2 第二步：准备配置文件

在 resources 下建一个 risk-monitor.properties：

sdk.appKey = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
sdk.secret = yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
sdk.serverUrl = https://api.risk.example.com/v3
sdk.logLevel = INFO
sdk.bufferSize = 5000

我曾经把 appKey 和 secret 写反了，日志里疯狂报 401，折腾了半天才发现是字符顺序问题。所以你复制粘贴后，最好肉眼扫一遍。

4.2.3 第三步：调用初始化

在你的应用启动入口（比如 Spring Boot 的 @PostConstruct 或者 main 方法）里写：

RiskConfig config = new RiskConfig();
config.setAppKey("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
config.setSecret("yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy");
config.setServerUrl("https://api.risk.example.com/v3");

RiskMonitor.init(config);
RiskMonitor.start(); // 别忘了这个

嗯，这里要注意，init 只是加载配置，start 才真正启动采集线程。少调任何一个，SDK 都是摆设。

4.3 配置最小化示例

你不需要配全所有参数。一个能正常工作最小化配置长这样：

参数	值	说明
appKey	你的 AppKey	必填
secret	你的 Secret	必填
serverUrl	网关地址	必填，带协议和版本
logLevel	INFO	调试时可改为 DEBUG

其他参数都有默认值。比如事件上报间隔默认 5 秒，内存队列大小 5000。这些对 Hello World 级 Demo 足够了。

  核心思路：先跑通，再调优。不要一上来就想着「我要不要改线程池大小」——默认值是经过压测的。

4.4 Hello World 级 Demo

来吧，写一个能打印日志的完整 Demo。代码很短：

import com.example.risk.RiskMonitor;
import com.example.risk.RiskConfig;

public class HelloRisk {
    public static void main(String[] args) {
        // 1. 配最简单的配置
        RiskConfig config = new RiskConfig();
        config.setAppKey("demo-app-key");
        config.setSecret("demo-secret");
        config.setServerUrl("https://sandbox.risk.example.com/v3");
        config.setLogLevel("DEBUG"); // 这里用 DEBUG 看详细信息

        // 2. 初始化并启动
        RiskMonitor.init(config);
        RiskMonitor.start();

        System.out.println("SDK 已启动，等待 5 秒后检查日志...");
        try {
            Thread.sleep(5000);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }

        // 3. 主动触发一次事件采集（Hello World！）
        RiskMonitor.reportCustomEvent("page_view", "{\"page\":\"home\"}");

        System.out.println("事件已上报，查看控制台输出或日志文件。");
        
        // 4. 为了演示优雅关闭
        RiskMonitor.shutdown();
    }
}

跑这个 Demo 之前，确保你的 sandbox 服务端是开着的。我当时第一次跑就忘了开沙箱，日志里全是一行行 Connection refused，可别学我。

4.5 接入后的基础日志验证

SDK 跑起来之后，怎么看它正常工作？三个地方：

控制台 stdout – 如果你用 DEBUG 级别，心跳日志会每分钟出现一次，类似 [RiskMonitor] Heartbeat sent, status: 200。
本地日志文件 – SDK 默认写在 logs/risk-monitor.log。看看有没有 ERROR 和 WARN。
平台监控页面 – 登录控制台，看「应用接入状态」，如果显示在线且最近有数据上报，说明通了。

有一个快速验证技巧：在 Demo 里故意写错 secret，然后观察日志。如果出现 403 Forbidden，说明 SDK 至少和服务通信了，只是鉴权没过。这反而是一个正向信号——证明你的网络、初始化、配置读取都没问题。

我常用的验证清单：
✓ 启动无报错，日志中出现 RiskMonitor started successfully
✓ 一分钟内看到 Heartbeat sent
✓ 手动上报一个事件后，3秒内出现 Event queued 或 Event dispatched

4.6 知识体系：SDK 接入流程全景图

下面这张图把整个接入过程串起来了——从获取 SDK 到验证日志，你每一步干什么都在上面：

接入了吗？跑通了吗？日志里有 Heartbeat 了吗？如果都 yes，恭喜你，SDK 已经稳了。下一件事就是理解它采集了哪些事件——那是第 5 章的事，咱们先到这。