📚 课程目录第2章 SDK简介

第 2 章：SDK 简介——功能与架构设计

好了，进入正题。
上一章我们聊了为什么需要双人审批。那这一章，咱们就来拆开这个SDK，看看它里面到底装了些什么东西。

我个人习惯，在集成任何一个SDK之前，先搞清楚两件事：它能做什么，以及它怎么长的。说白了，就是功能清单和架构草图。

你想想看，如果连这东西的核心能力和调用链路都不清楚，贸然往项目里一塞，后期排查问题会非常痛苦。我在项目中就遇到过好几次，因为没搞懂SDK的异步回调机制，结果审批状态死活不同步，最后加班到凌晨三点。

2.1 SDK 核心功能概览

这个双人审批流程SDK，不是让你从头造轮子的。
它的目标很明确：让任何一个业务系统，都能在30分钟内接入一个可靠的双人审批流。

具体来说，它提供了以下几项核心能力：

双人审批规则引擎：支持“第一审批人”、“第二审批人”的角色定义，以及审批顺序（会签、或签）的配置。
业务系统无缝对接：通过标准的API接口（RESTful），允许你的订单系统、工单系统或内容发布系统快速发起审批。
审批节点与状态机：内置了从“待提交”、“审批中”、“已通过”、“已驳回”到“已撤销”的完整状态流转。
通知与回调机制：审批结果通过Webhook实时回调到你业务系统的指定URL，支持失败重试。
操作日志与审计：每一次“同意”或“驳回”操作，都带有精确的时间戳和操作人信息，方便溯源。

    重点注意：这个SDK不处理“谁是你的用户”，它只处理“谁审批了什么”。用户体系和权限认证需要你的业务系统自己提供。

2.2 功能参数速查表

为了方便你快速评估，我把核心功能的参数列成了表格。你可以在设计数据库字段或配置DTO时直接参考。

功能模块	关键参数	说明
审批定义	approvalId, approverList[ ]	唯一审批流ID，以及包含顺序的审批人列表
审批动作	action (APPROVE/REJECT), operatorId, comment	操作类型、执行人身份、审批意见
回调配置	callbackUrl, retryCount, secretKey	结果推送地址、重试次数、签名密钥
状态查询	approvalId, status (枚举)	实时查询当前审批流的状态

个人小习惯：我在设计回调URL时，通常会强制要求使用HTTPS，并且配置一个secretKey做HMAC-SHA256签名。这么做能有效防止回调地址被伪造。

2.3 整体架构设计

架构这东西，说白了就是分层。
我见过很多新手把SDK搞成一个大泥球，所有逻辑揉在一起。但好的SDK一定是边界清晰的。

这个SDK的内部架构，我把它总结为“三层一总线”：

接入层（API Gateway）：负责接收外部请求。包括鉴权、限流、参数校验。
核心服务层（Core Engine）：审批流程的调度中心。包含状态机引擎和规则匹配器。
数据持久层（Data Store）：与数据库交互。只存储审批单、节点记录和操作日志。

而贯穿这三层的，是一条事件总线。所有状态变更，都通过事件驱动。

嗯，这里要注意：事件总线是异步的。如果你在回调里做一些耗时操作（比如发邮件、写额外的数据库），记得把它们放到业务系统的消息队列里，别阻塞了回调主线程。

下面这张图，就是我对这个架构的直观理解：

2.4 关键集成步骤预览

光看架构图可能还觉得有点虚。那咱们把集成步骤快速过一下，看看SDK到底怎么“接”进来。

我总结了4个核心步骤：

引入依赖：在项目的 pom.xml 或 build.gradle 中添加SDK的Maven/Gradle坐标。
配置数据源与回调地址：在 application.yml 中配置审批表单的数据库连接，以及接收审批结果的回调URL。
初始化 SDK Client：在应用启动时，调用 ApprovalClient.init(config) 完成初始化。
发起审批：在业务代码中，构造一个 ApprovalRequest 对象，然后调用 client.create(approvalRequest)。

避坑提示：我曾经在一个项目里发现，团队把回调URL配成了内网IP，导致公网无法访问。结果审批结束了，业务系统毫不知情。记得配置成公网可达且稳定的地址，或者配置内网穿透。

2.5 核心代码骨架

讲理论不如给代码。下面这段是初始化SDK并创建一个审批流的骨架代码：

// 1. 创建配置对象
ApprovalConfig config = new ApprovalConfig();
config.setCallbackUrl("https://your-system.com/api/approval/callback");
config.setSecretKey("your-secret-key");

// 2. 初始化客户端（建议在Spring Boot的@PostConstruct中执行）
ApprovalClient client = ApprovalClient.init(config);

// 3. 构造审批请求（双人场景）
ApprovalRequest request = new ApprovalRequest();
request.setBizId("ORDER_2024001");         // 业务单号
request.setTitle("退款金额超过10000元审批");

// 设置审批人，保持顺序
request.setApprovers(Arrays.asList(
    new Approver("user_001", 1),   // 第一审批人
    new Approver("user_002", 2)    // 第二审批人
));

// 4. 发起审批
ApprovalResponse response = client.create(request);
if (response.isSuccess()) {
    System.out.println("审批发起成功，审批流ID: " + response.getApprovalId());
} else {
    System.err.println("发起失败: " + response.getErrorMsg());
}

这段代码跑通之后，你的系统就算正式接入了双人审批能力。
后续的所有操作——审批、驳回、查询——都只需要调用 client 对象上的不同方法即可。

2.6 本节核心要点

SDK核心能力是标准的双人审批流程引擎，不包含用户体系。用户由你们业务系统自己管。
架构采用三层一总线：接入层（安全防护） -> 核心层（状态流转） -> 持久层（数据存储），事件总线贯穿其中。
集成关键点在于回调URL的稳定性与安全性。确保网络可达，并做好签名验证。
代码集成非常简洁：配置 -> 初始化 -> 构造请求 -> 发起，4步走完。