📚 课程目录第4章快速开始

快速开始：SDK 集成第一步——创建项目

好，咱们直接动手。这一章我带你从零搭一个双人审批流程的项目骨架。别小看这一步——很多人集成到一半出问题，回头看都是项目结构没立好。

我个人习惯，先把依赖管理、目录分层、配置文件这三个地基打牢。后面写代码才会顺手。

1. 准备工作

先确认你的环境。这张表列了最低版本要求，你别低于它，否则 SDK 底层会有兼容问题。

组件	版本要求	备注
JDK	≥ 1.8	建议用 11 或 17
Maven / Gradle	Maven 3.6+ / Gradle 7+	我用的 Maven
Spring Boot	2.7.x 或 3.x	与 SDK 版本匹配
数据库	MySQL 8.0+	建议用 5.7 以上字符集 utf8mb4

我曾经踩过坑：JDK 1.8 和 Spring Boot 2.7 组合下，SDK 的异步回调线程池默认配置会报错。原因是旧版线程池拒绝策略不一致。后来我把 JDK 升到 11 就好了。所以如果你也用 1.8，记得手动调整线程池参数。

2. 创建项目结构

我是 Maven 党，直接用 mvn archetype:generate 生成一个 Spring Boot 模块。项目名字就叫 approval-demo。你看看我的目录规划：

approval-demo/
├── pom.xml
├── src/
│   ├── main/
│   │   ├── java/com/example/approval/
│   │   │   ├── config/          // SDK 配置类
│   │   │   ├── controller/      // 审批接口
│   │   │   ├── service/         // 业务逻辑
│   │   │   ├── entity/          // 数据模型
│   │   │   └── ApprovalDemoApplication.java
│   │   └── resources/
│   │       ├── application.yml
│   │       └── sdk-config.yml   // SDK 专属配置
│   └── test/
│       └── java/...
└── README.md

为什么要单独放一个 sdk-config.yml？因为 SDK 参数（如节点超时、审批人策略）经常变动，拆出来方便热更新。我在项目中遇到过一次，把所有配置塞进 application.yml，结果运维改一个参数就要重启整个应用，很烦。

小技巧：SDK 配置文件的路径用 classpath:sdk-config.yml，然后在 application.yml 里用 spring.config.import 引入。这样既隔离了业务配置，又保持了 Spring 的加载顺序。

3. 引入 SDK 依赖

在 pom.xml 里加入核心依赖。我建议直接锁定版本号，别用 LATEST。你想想看，生产环境如果自动升级了不兼容版本，半夜出问题你找谁？

<dependency>
    <groupId>com.example</groupId>
    <artifactId>dual-approval-sdk</artifactId>
    <version>2.1.0.RELEASE</version>
</dependency>

<!-- 数据库 + MyBatis-Plus （可选，但推荐） -->
<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
    <version>3.5.3.1</version>
</dependency>

为什么推荐 MyBatis-Plus？因为 SDK 默认提供了审批流程记录表的自动建表脚本，MP 可以直接映射成实体。你只用关注业务字段就行。

4. 核心配置说明

SDK 的初始化需要三个关键参数：应用ID、密钥和 回调地址。它们通常在内部管理平台上申请。下图是整个初始化流程：

拿到这三个值后，在 sdk-config.yml 里配好：

dual-approval:
  app-id: "your-app-id"
  secret: "your-app-secret"
  callback:
    url: "https://your-domain.com/approval/callback"
    retry-count: 3
  node-timeout: 600   # 单节点超时时间，单位秒
  max-idle-connections: 20

  注意：回调 URL 必须指向你项目里的一个真实接口。SDK 会在审批结果更新时推送通知。我曾经见过有人配了 localhost，结果内网服务器根本访问不到。线上环境一定要用域名或者公网IP。

5. 启动类与验证

最后，在 ApprovalDemoApplication.java 中添加 @EnableDualApproval 注解，开启 SDK 自动装配：

import com.example.dualapproval.sdk.annotation.EnableDualApproval;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@EnableDualApproval
public class ApprovalDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(ApprovalDemoApplication.class, args);
    }
}

启动项目后，看控制台日志。如果看到类似 DualApproval SDK initialized successfully，说明项目创建成功。你还可以访问 /actuator/health（需引入 spring-boot-starter-actuator）检查 SDK 的健康状态。

又一个坑：我遇到过启动时日志显示初始化成功，但审批流程一直超时。查了半天，发现是数据库连接池太小，SDK 的持久化线程一直在等待连接。建议你至少配置 spring.datasource.hikari.maximum-pool-size=20。

6. 本章小结

走到这里，项目已经跑起来了。你有了清晰的项目结构、稳定的依赖版本、正确的配置入口。后面的审批流程、多人协同、回调处理都基于这个骨架展开。