Sumsub Java Web Demo 技术文档

1. 引言

本文档旨在为 Sumsub Java Web Demo 项目提供全面的技术说明。该项目是一个基于 Spring Boot 构建的 Web 应用程序，主要演示了如何与 Sumsub KYC (Know Your Customer) 服务进行集成，特别是如何安全地获取用于 Sumsub Web SDK 的访问令牌 (Access Token)。本文档将详细介绍项目的架构、核心功能、关键组件、技术实现、配置方法以及安全机制，旨在帮助开发人员理解项目结构、维护代码以及进行二次开发。

该应用程序提供了一个简单的前端界面，用户可以通过该界面发起获取访问令牌的请求。后端服务接收这些请求，并负责与 Sumsub API 进行安全的 HTTP 通信，包括构建请求、生成 API 签名、发送请求以及处理响应。通过此项目，开发人员可以学习到与 Sumsub API 交互的最佳实践，例如签名生成逻辑和 API 密钥的安全管理。

2. 项目架构与技术栈

本章节将详细阐述 Sumsub Java Web Demo 项目的整体架构、目录结构、关键技术选型以及主要的第三方依赖库。

2.1. 项目概述与架构

该项目是一个基于 Spring Boot 框架构建的 Java Web 应用程序，其核心目标是演示如何与 Sumsub 用户验证服务进行集成。应用程序采用经典的三层架构模式，即表现层（前端静态资源）、业务逻辑层（Controller 和 Service）以及数据访问/模型层（Model）。这种分层结构有助于代码的模块化、可维护性和可测试性。

前端通过静态 HTML、CSS 和 JavaScript 文件提供用户交互界面，用户可以通过此界面触发后端API调用。后端服务则负责处理这些API请求，执行与 Sumsub API 的通信，包括构建请求、生成安全签名、发送HTTP请求以及解析响应。整个流程清晰地展示了客户端-服务器以及服务器-第三方服务之间的交互模式。

2.2. 项目目录结构

项目的源代码和资源文件遵循标准的 Maven 项目布局，主要分布在 src/main 目录下。以下是关键目录和文件的说明：

• src/main/java/com/example/sumsubdemo/: 此目录是项目 Java 源代码的根路径。
  • SumsubWebDemoApplication.java: 作为 Spring Boot 应用程序的主类，它包含了 main 方法，是整个应用程序的启动入口。通过 @SpringBootApplication 注解，它自动配置了 Spring 上下文并启动了嵌入式的 Web 服务器（如 Tomcat）。
  • controller/SumsubController.java: 该文件定义了项目的API端点。控制器负责接收来自客户端的HTTP请求，对请求参数进行初步校验和处理，然后调用相应的服务层方法来执行业务逻辑。处理完成后，控制器将服务层的返回结果封装成HTTP响应并发送回客户端。
  • model/: 此目录存放了项目中使用的数据模型对象（POJOs - Plain Old Java Objects）。这些对象用于封装业务数据，例如 AccessToken.java 用于表示向 Sumsub API 请求访问令牌时的数据结构，Applicant.java（尽管在当前核心流程中未直接使用）可能用于表示申请人信息等。这些模型类通常会使用 Jackson 等库的注解来进行 JSON 序列化和反序列化。
  • service/SumsubApiService.java: 服务层是项目核心业务逻辑的所在地。SumsubApiService.java 封装了与 Sumsub API 交互的所有细节，包括构建API请求体、根据 Sumsub 的安全要求生成请求签名、使用 HTTP 客户端（如 OkHttp）发送请求、以及处理和解析来自 Sumsub API 的响应。
• src/main/resources/: 此目录存放项目的各类资源文件。
  • application.properties: 这是 Spring Boot 的主配置文件。它用于定义应用程序的各种配置参数，例如服务器端口号、数据库连接信息（如果需要）、以及本项目中至关重要的 Sumsub API 密钥（sumsub.app.token 和 sumsub.secret.key）和 Sumsub API 的基础URL (sumsub.base.url)。
  • static/: 该目录用于存放所有静态Web资源，如HTML页面、CSS样式表和JavaScript脚本文件。这些文件构成了用户在浏览器中直接与之交互的前端界面。
    • index.html: 项目的前端主页面，用户通过此页面发起操作。
    • script.js: 包含了前端页面的 JavaScript 逻辑，负责处理用户事件、向后端API发送AJAX请求，并根据后端响应更新页面内容。
    • style.css: 定义了前端页面的视觉样式。
• pom.xml: 这是 Apache Maven 项目的核心配置文件，即项目对象模型 (Project Object Model)。它定义了项目的基本信息（如 groupId, artifactId, version）、项目依赖的第三方库及其版本、构建过程中的插件（例如 spring-boot-maven-plugin 用于将项目打包成可执行的 JAR 文件）、以及其他构建相关的配置。
• target/: 此目录是 Maven 构建过程的输出目录。当执行 Maven 构建命令（如 mvn package）后，编译后的 .class 文件、处理过的资源文件、以及最终打包生成的 JAR 或 WAR 文件都会存放在这里。

2.3. 主要依赖项与技术栈

项目在其 pom.xml 文件中声明并依赖了多个关键的第三方库和技术，共同构成了其技术栈：

• Spring Boot Starter Web (org.springframework.boot:spring-boot-starter-web): 这是构建 Web 应用程序的核心 Spring Boot 依赖。它自动配置了 Spring MVC 框架，提供了处理 HTTP 请求、RESTful API 开发等功能，并内嵌了 Tomcat 作为默认的 Servlet 容器，使得应用程序可以作为独立的可执行 JAR 文件运行。
• OkHttp (com.squareup.okhttp3:okhttp ): 一个强大且高效的 HTTP 和 HTTP/2 客户端库，用于 Java 和 Android 开发。在本项目中，OkHttp 被用来向 Sumsub API 发送 HTTP POST 请求并接收响应。它提供了连接池、GZIP压缩、缓存等高级功能，简化了网络通信的复杂性。
• Jackson Databind (com.fasterxml.jackson.core:jackson-databind): Jackson 是一个非常流行的 Java JSON 处理库。jackson-databind 模块提供了将 Java 对象序列化为 JSON 字符串以及将 JSON 字符串反序列化为 Java 对象的功能。这在与 Sumsub API（或其他任何基于 JSON 的 API）交互时至关重要，用于处理请求体和响应体的数据转换。
• FastJSON2 (com.alibaba.fastjson2:fastjson2): 这是阿里巴巴开源的一个高性能 Java JSON 解析和生成库。项目中同时引入了 Jackson 和 FastJSON2，可能是在特定场景下利用 FastJSON2 的某些性能优势或特性，或者是在项目演进过程中引入的。在 SumsubApiService 中，响应体的解析使用了 FastJSON2。
• Apache Commons Codec (commons-codec:commons-codec): Apache Commons Codec 库提供了一系列通用的编码器和解码器，例如 Base64、Hexadecimal、Phonetic 等。在本项目中，它主要用于将 HmacSHA256 签名生成的字节数组转换为十六进制字符串（Hex encoding），这是 Sumsub API 签名要求的格式。
• Spring Boot Starter Test (org.springframework.boot:spring-boot-starter-test): 该依赖为 Spring Boot 应用程序提供了全面的测试支持。它包含了 JUnit Jupiter（用于单元测试和集成测试）、Spring Test & Spring Boot Test（用于 Spring 组件的测试）、AssertJ（一个流式断言库）、Hamcrest（匹配器对象库）以及 Mockito（一个流行的 Mocking 框架），方便开发人员编写各种类型的测试用例。
• Java Development Kit (JDK): 项目配置使用 Java 11 (<java.version>11</java.version>)，这意味着它利用了 Java 11 版本所提供的语言特性和 API。

2.4. 构建系统

项目采用 Apache Maven 作为其构建自动化和依赖管理工具。pom.xml 文件是 Maven 的核心，它详细描述了如何构建项目、项目依赖哪些库以及如何管理这些依赖。通过 Maven，开发人员可以轻松地编译代码、运行测试、打包应用程序（例如生成可执行的 JAR 文件）以及管理项目的整个生命周期。spring-boot-maven-plugin 是一个关键插件，它使得将 Spring Boot 应用程序打包成一个包含所有依赖的“胖 JAR” (fat JAR) 变得非常简单，从而简化了部署过程。

3. 核心功能、组件与业务流程

本章节将深入探讨 Sumsub Java Web Demo 应用程序的核心功能、主要软件组件的职责分工，以及关键业务流程的实现细节。这包括用户如何通过前端界面发起请求，后端如何处理这些请求，以及如何与 Sumsub API 进行安全高效的交互。

3.1. 核心功能概述

该 Java Web 应用程序的核心使命是作为 Sumsub 服务集成的一个演示实例和后端代理。其最主要的功能是允许用户通过一个简洁的网页界面，向后端服务请求一个用于 Sumsub Web SDK 的访问令牌（Access Token）。获得此令牌后，前端应用（通常是另一个集成了 Sumsub Web SDK 的应用）便可以使用它来初始化和展示 Sumsub 的用户验证流程界面。

为了实现这一核心功能，后端服务承担了以下关键职责：

1. 接收前端请求：安全地接收来自前端 index.html 页面的 API 调用。
2. 与 Sumsub API 通信：构建符合 Sumsub API 规范的请求，特别是针对获取 SDK 访问令牌的端点。
3. 安全签名生成：实现并应用 Sumsub API 所要求的请求签名机制，确保通信的机密性和完整性。
4. 处理 API 响应：解析来自 Sumsub API 的响应，提取所需的访问令牌，并将其安全地返回给前端。

通过这个过程，项目清晰地展示了集成第三方服务（如 Sumsub）时，后端服务所需扮演的关键角色，尤其是在处理 API 密钥和签名等敏感操作时，将这些逻辑保留在后端是一种推荐的安全实践。

3.2. 主要组件及其职责

项目的整体功能是通过多个协作的组件来实现的，这些组件遵循了典型的分层架构模式。以下是各主要组件及其具体职责的详细说明：

3.2.1. 控制器层 (SumsubController.java)

• 定位与职责: SumsubController 类位于应用程序的Web层，直接面向客户端（即前端JavaScript）。它作为HTTP请求的入口点，负责接收和初步处理来自前端的请求。其核心职责是将这些请求路由到相应的服务层方法进行业务逻辑处理，并将服务层返回的结果封装成标准的HTTP响应（通常是JSON格式）返回给客户端。
• 核心功能实现: 该控制器暴露了一个主要的API端点：
  • GET /api/sumsub/access-token: 此端点用于处理获取 Sumsub SDK 访问令牌的请求。它接受两个可选的查询参数：userId（代表外部系统中的用户唯一标识）和 levelName（指定请求的KYC级别，例如 basic-kyc-level）。
  • 用户ID处理: 如果前端请求中没有提供 userId 或者提供的是一个空字符串，控制器会自动生成一个基于当前系统时间戳的默认用户ID（格式为 java-web-demo-user-<timestamp>）。这种机制确保了即使在演示场景下没有显式用户ID时，也能为每个请求关联一个唯一的标识符。
  • 服务调用: 在准备好用户ID和级别名称后，控制器会调用 SumsubApiService 中的 generateAccessToken 方法，将这些参数传递给服务层以执行实际的令牌生成逻辑。
  • 异常处理: 控制器包含基本的异常处理机制。如果在调用服务层或处理请求过程中发生任何异常（例如，与Sumsub API通信失败），它会捕获这些异常，记录错误信息（在演示代码中是打印到标准错误输出），并向客户端返回一个表示内部服务器错误的HTTP 500响应，响应体中通常会包含错误摘要和详细信息。

3.2.2. 服务层 (SumsubApiService.java)

• 定位与职责: SumsubApiService 类是应用程序业务逻辑的核心。它封装了所有与 Sumsub API 进行直接交互的复杂细节。其主要职责包括构建发送给 Sumsub API 的请求、根据 Sumsub 的安全规范生成请求签名、使用HTTP客户端库执行实际的网络调用，以及解析和处理来自 Sumsub API 的响应。
• 核心功能实现:
  • generateAccessToken(String externalUserId, String levelName): 这是获取 Sumsub SDK 访问令牌的核心方法。它首先根据传入的 externalUserId 和 levelName 创建一个 AccessToken 数据模型对象，该对象将作为POST请求的JSON体。随后，它调用内部的 sendPost 方法，将请求发送到 Sumsub API 的 /resources/accessTokens/sdk 端点。最后，它接收来自 sendPost 方法的响应，使用 FastJSON2 将响应体（通常是JSON字符串）解析为一个 Map<String, Object>，这个Map中就包含了 Sumsub 返回的访问令牌和其他相关信息。
  • sendPost(String url, RequestBody requestBody): 这是一个更为通用的私有方法，负责实际执行到 Sumsub API 的POST请求。它接收目标URL路径和已经构建好的 RequestBody (来自OkHttp库)作为参数。在发送请求之前，此方法会执行以下关键步骤：
    1. 获取当前的时间戳（秒级）。
    2. 调用 createSignature 方法生成请求签名。
    3. 构建一个 OkHttp Request 对象，设置目标URL（通过拼接基础URL和传入的路径）、HTTP方法为POST、以及必要的请求头。这些请求头包括：
       • X-App-Token: 从配置文件中读取的 Sumsub 应用令牌。
       • X-App-Access-Sig: 调用 createSignature 方法生成的请求签名。
       • X-App-Access-Ts: 当前的时间戳。
       • Content-Type: 通常是 application/json; charset=utf-8。
    4. 使用 OkHttp 客户端 (new OkHttpClient().newCall(request).execute()) 同步执行HTTP请求。
    5. 对响应码进行初步检查。如果响应码不是200或201（表示成功或创建），则会打印一条日志提示（在实际生产代码中，这里应该有更完善的错误处理和可能的异常抛出逻辑）。
    6. 返回 OkHttp 的 Response 对象。
  • createSignature(long ts, HttpMethod httpMethod, String path, byte[] body ): 这是实现 Sumsub API 安全通信的核心。此方法严格按照 Sumsub API 文档中描述的签名生成规则，使用 HmacSHA256 算法来创建请求的数字签名。签名的输入包括：
    1. 时间戳 (ts)。
    2. HTTP 请求方法 (httpMethod.name( ), 例如 "POST")。
    3. 请求的相对路径 (path, 例如 "/resources/accessTokens/sdk")。
    4. 请求体 (body) 的字节数组（如果请求是GET或没有请求体，则不包含此部分）。 这些内容按照特定顺序拼接后，使用从配置文件中读取的 SUMSUB_SECRET_KEY 作为 HMAC 密钥进行加密。生成的签名最终通过 Apache Commons Codec 库的 Hex.encodeHexString() 方法转换为十六进制字符串。
  • requestBodyToBytes(RequestBody requestBody): 这是一个辅助工具方法，用于将 OkHttp 的 RequestBody 对象的内容读取为一个字节数组。这在 createSignature 方法中是必需的，因为签名算法需要请求体的原始字节数据。
• 配置注入: SumsubApiService 通过 Spring 的 @Value 注解从 application.properties 文件中注入必要的配置信息，包括 sumsub.app.token (Sumsub应用令牌), sumsub.secret.key (Sumsub秘密密钥), 和 sumsub.base.url (Sumsub API的基础URL)。这种方式使得配置与代码分离，便于管理和修改。

3.2.3. 数据模型层 (model/)

• 定位与职责: model 包下的Java类定义了应用程序内部以及与外部API交互时所使用的数据结构。这些通常是简单的POJO（Plain Old Java Objects），用于封装和传递数据。它们使得代码更具可读性，并且便于使用像Jackson这样的库进行JSON序列化和反序列化。
• 核心模型类:
  • AccessToken.java: 这个类精确地映射了向 Sumsub API 的 /resources/accessTokens/sdk 端点发送POST请求时所需的JSON请求体结构。它包含两个主要属性：userId (字符串类型，表示希望为其生成令牌的用户的唯一标识) 和 levelName (字符串类型，表示请求的KYC验证级别，例如 "basic-kyc-level")。该类使用了 Jackson 的注解：
    • @JsonInclude(JsonInclude.Include.NON_NULL): 指示 Jackson 在将此对象序列化为JSON时，如果某个字段的值为 null，则不应在输出的JSON中包含该字段。这有助于生成更简洁的请求体。
    • @JsonIgnoreProperties(ignoreUnknown = true): 指示 Jackson 在将JSON反序列化为此类型的对象时，如果JSON中包含了此类未定义的属性，则应忽略它们而不是抛出错误。这增强了向前兼容性和处理API响应变化的鲁棒性。
  • HttpMethod.java: 这是一个Java枚举类型，定义了支持的HTTP方法（在当前代码中，主要关注POST）。它在 createSignature 方法中使用，以确保签名的生成与实际的HTTP请求方法一致。
  • Applicant.java, DocType.java, Metadata.java: 虽然这些模型类存在于项目中，但在当前演示的核心功能（即获取访问令牌）中并未被 SumsubController 或 SumsubApiService 的主流程直接使用。它们的存在暗示了该项目最初可能设计用于或可以方便地扩展以支持更广泛的 Sumsub API 功能，例如创建申请人（Applicant）、处理不同类型的文档（DocType）或管理元数据（Metadata）。这些类为未来的功能扩展提供了数据结构基础。

3.2.4. 前端资源 (src/main/resources/static/)

• 定位与职责: static 目录下的文件构成了应用程序的前端用户界面。由于这是一个演示项目，前端界面相对简单，主要目的是提供一种触发后端API调用的方式，并展示结果。
• 核心文件:
  • index.html: 这是用户在浏览器中访问的应用程序主页面。它通常包含一个简单的表单（可能包含输入用户ID和选择级别的字段）和一个提交按钮，用于发起获取 Sumsub 访问令牌的请求。
  • script.js: 该文件包含了前端页面的所有JavaScript逻辑。其主要职责包括：
    1. 事件处理: 监听用户在 index.html 上的操作，例如点击“获取令牌”按钮。
    2. API调用: 当用户触发操作时，使用 fetch API 或 XMLHttpRequest (或者像jQuery的AJAX方法) 向后端的 /api/sumsub/access-token 端点发起异步HTTP GET请求。它会收集 index.html 中用户输入的数据（如用户ID和级别名称）作为请求参数。
    3. 响应处理: 接收来自后端API的响应。如果请求成功，它会解析响应中的JSON数据，提取出访问令牌，并可能将其显示在页面上。如果请求失败（例如，后端返回错误信息），它会捕获错误并向用户显示相应的错误提示。
  • style.css: 此文件定义了 index.html 页面的基本视觉样式和布局，使其具有一定的可观性。

3.3. 核心业务流程：获取 Sumsub SDK 访问令牌

获取 Sumsub SDK 访问令牌是本项目的核心业务流程。以下是该流程从用户在前端发起操作到最终获得令牌并展示的详细步骤：

1. 用户交互 (前端): 用户在浏览器中打开 index.html 页面。页面上通常会有一个按钮，例如“获取访问令牌”。用户可能会被要求输入一个用户ID（可选）和选择一个KYC级别（可选，有默认值）。用户点击该按钮以启动流程。

2. 前端发起请求 (JavaScript): 位于 script.js 中的 JavaScript 代码捕获按钮的点击事件。它从页面的输入字段中读取用户ID和级别名称。然后，它构造一个指向后端 /api/sumsub/access-token 端点的HTTP GET请求，并将用户ID和级别名称作为URL查询参数附加到请求中。例如：GET /api/sumsub/access-token?userId=test-user&levelName=basic-kyc-level。这个请求是异步发送的（AJAX）。

3. 控制器接收与处理 (Spring MVC - SumsubController): Spring Boot应用中的嵌入式Web服务器（如Tomcat）接收到这个HTTP GET请求。Spring MVC框架根据请求路径将其路由到 SumsubController 的 getAccessToken 方法。

   • 该方法通过 @RequestParam 注解提取 userId 和 levelName 参数。
   • 它检查 userId 是否为空。如果为空，则会生成一个默认的、基于时间戳的唯一用户ID，格式为 java-web-demo-user-<currentTimeMillis>。

4. 服务层调用 (SumsubController -> SumsubApiService): 控制器随后调用 SumsubApiService 的 generateAccessToken 方法，并将处理后的 effectiveUserId 和 levelName 作为参数传递进去。

5. 构建 Sumsub API 请求体 (SumsubApiService): 在 generateAccessToken 方法内部，首先会创建一个 com.example.sumsubdemo.model.AccessToken 对象实例，并用传入的 externalUserId (即 effectiveUserId) 和 levelName 初始化它。这个 AccessToken 对象将被序列化为JSON，作为发送给 Sumsub API 的POST请求体。

6. 准备发送POST请求 (SumsubApiService#sendPost): generateAccessToken 方法接着调用私有的 sendPost 方法，目标路径是 /resources/accessTokens/sdk，请求体是上一步创建的 AccessToken 对象（经过Jackson序列化和OkHttp的RequestBody.create封装）。

7. 生成请求签名 (SumsubApiService#createSignature): 在 sendPost 方法内部，发送实际HTTP请求之前，必须为该请求生成一个符合 Sumsub 安全要求的签名。这是通过调用 createSignature 方法完成的：

   • 获取当前UNIX时间戳（秒）。
   • 确定HTTP方法（对于获取访问令牌，固定为POST）。
   • 确定请求路径（/resources/accessTokens/sdk）。
   • 获取请求体的字节数组（通过 requestBodyToBytes 方法）。
   • 将时间戳、HTTP方法名、请求路径和请求体字节（如果存在）按照Sumsub规定的格式拼接起来。
   • 使用存储在 application.properties 中的 SUMSUB_SECRET_KEY 和 HmacSHA256 算法对拼接后的字符串进行加密。
   • 将加密产生的字节数组转换为十六进制字符串，得到最终的签名 X-App-Access-Sig。

8. 发送HTTP请求到 Sumsub API (SumsubApiService#sendPost 使用 OkHttp): sendPost 方法现在构造一个完整的OkHttp Request 对象。这个请求对象包含：

   • 目标URL: SUMSUB_TEST_BASE_URL + /resources/accessTokens/sdk。
   • HTTP方法: POST。
   • 请求头:
     • X-App-Token: 从 application.properties 读取的 SUMSUB_APP_TOKEN。
     • X-App-Access-Sig: 上一步生成的签名。
     • X-App-Access-Ts: 上一步使用的时间戳。
     • Content-Type: application/json; charset=utf-8。
   • 请求体: 包含 userId 和 levelName 的JSON对象。 然后，使用OkHttp客户端的 newCall(request).execute() 方法同步发送此请求到 Sumsub 服务器。

9. Sumsub API 处理请求: Sumsub的服务器接收到请求后，会首先验证 X-App-Token 的有效性，然后使用相同的 SUMSUB_SECRET_KEY（Sumsub为你账户配置的密钥）和收到的时间戳、HTTP方法、路径、请求体来重新计算签名。如果计算出的签名与请求头中的 X-App-Access-Sig 一致，则认为请求是合法的。随后，Sumsub会根据提供的 userId 和 levelName 生成一个临时的SDK访问令牌。

10. Sumsub API 返回响应: 如果一切顺利，Sumsub API会返回一个HTTP 200 OK或201 Created的响应，响应体是一个JSON对象，其中包含生成的 token (SDK访问令牌) 和 userId。例如：{"token": "generated_sdk_token_value", "userId": "effectiveUserId"}。

11. 服务层处理响应 (SumsubApiService): sendPost 方法接收到OkHttp的 Response 对象。generateAccessToken 方法接着获取响应体 (response.body().string())，并使用 com.alibaba.fastjson2.JSON.parseObject() 将其解析为一个 Map<String, Object>。

12. 控制器返回响应给前端 (SumsubController): SumsubController 的 getAccessToken 方法接收到这个包含令牌的Map。它将这个Map封装在一个 ResponseEntity.ok() 对象中，这意味着它会以HTTP 200 OK的状态码和JSON格式的响应体（即该Map序列化后的JSON）返回给前端的JavaScript调用。

13. 前端展示结果 (JavaScript - script.js): 前端的AJAX调用成功接收到来自后端的JSON响应。JavaScript代码解析这个JSON，提取出 token 字段的值。然后，它可以将这个令牌显示在 index.html 页面的某个元素中，或者用于后续的 Sumsub Web SDK 初始化操作（在更完整的集成场景中）。如果后端返回的是错误响应，JavaScript代码则会显示相应的错误信息。

这个详细的流程覆盖了从用户界面交互到与外部API安全通信，再到结果返回的完整闭环，是理解该Sumsub集成演示项目运作方式的关键。

3.4. 技术实现细节考量

在实现上述功能和流程时，项目采用了一些关键的技术和实践：

• Spring Boot 自动配置与内嵌服务器: 利用Spring Boot的特性，项目能够以最小的配置快速启动和运行。内嵌的Tomcat服务器使得部署变得简单，只需一个可执行的JAR文件。
• OkHttp 进行 HTTP 通信: 选择OkHttp作为HTTP客户端，因为它是一个成熟、高效且功能丰富的库，能够很好地处理网络请求的复杂性，如连接管理、超时设置、重试机制（尽管本项目中未显式配置高级重试）等。
• JSON 数据交换: Jackson 和 FastJSON2 的使用确保了Java对象与JSON字符串之间转换的便捷性和高效性。这对于与现代Web API（如Sumsub API）进行交互是必不可少的。
• 安全的签名机制: 严格遵循Sumsub API的HmacSHA256签名生成规则是保障通信安全的核心。将密钥等敏感信息存储在配置文件中，并通过依赖注入在服务层使用，是一种比硬编码更好的实践。
• 异常处理: 虽然项目中的异常处理相对基础（主要是在控制器层捕获并返回通用错误），但在生产级应用中，这里需要更细致的处理，包括定义具体的业务异常、提供更友好的错误信息以及完善的日志记录。
• 依赖管理 (Maven): Maven有效地管理了项目的所有第三方依赖库及其版本，确保了构建的一致性和可重复性。

这些技术细节共同支撑了项目的稳定运行和功能的实现，同时也为开发者提供了一个学习和参考如何在Java环境中集成类似Sumsub这样的第三方服务的范例。

4. 配置与部署

本章节将详细介绍如何配置 Sumsub Java Web Demo 应用程序，以及如何将其部署到运行环境中。正确的配置是确保应用程序能够成功与 Sumsub API 通信的关键，而了解部署流程则有助于将该演示项目或基于其开发的应用投入实际使用。

4.1. 应用程序配置

应用程序的主要配置信息存储在位于 src/main/resources/ 目录下的 application.properties 文件中。该文件是 Spring Boot 应用程序标准的配置文件，用于管理各种应用程序级别的参数。对于 Sumsub Java Web Demo，以下配置项至关重要：

• sumsub.app.token: 这是您的 Sumsub 应用令牌 (App Token)。您需要从您的 Sumsub 开发者后台获取此令牌。它用于标识您的应用程序发起的 API 请求。

  properties

  sumsub.app.token=YOUR_SUMSUB_APP_TOKEN
  

  请将 YOUR_SUMSUB_APP_TOKEN 替换为您实际的应用令牌。

• sumsub.secret.key: 这是您的 Sumsub 秘密密钥 (Secret Key)。同样，此密钥也需要从您的 Sumsub 开发者后台获取。该密钥用于生成 API 请求的签名，是保障通信安全的核心元素，必须严格保密。

  properties

  sumsub.secret.key=YOUR_SUMSUB_SECRET_KEY
  

  请将 YOUR_SUMSUB_SECRET_KEY 替换为您实际的秘密密钥。

• sumsub.base.url: 这是 Sumsub API 的基础 URL。通常，Sumsub 会提供一个用于测试/沙箱环境的 URL 和一个用于生产环境的 URL。在本项目中，默认配置可能指向测试环境。

  properties

  sumsub.base.url=https://api.sumsub.com
  

  请根据您的需求（测试或生产 ）以及 Sumsub 提供的最新 API 端点信息，确认并配置正确的 URL。

• server.port (可选): 您可以通过此属性配置应用程序运行时监听的 HTTP 端口。如果未指定，Spring Boot 默认使用 8080 端口。

  properties

  # server.port=8090 # Uncomment and change if you need a different port
  

配置步骤:

1. 打开 src/main/resources/application.properties 文件。
2. 找到上述提到的 sumsub.app.token 和 sumsub.secret.key 配置项。
3. 将占位符替换为您从 Sumsub 账户中获取的实际凭证。
4. 根据需要调整 sumsub.base.url 和 server.port。
5. 保存文件。

重要提示: 切勿将您的实际 sumsub.secret.key 硬编码到版本控制系统（如 Git）中公开的仓库。在生产环境中，应使用更安全的方式管理密钥，例如通过环境变量、专门的密钥管理服务（如 HashiCorp Vault, AWS Secrets Manager, Azure Key Vault）或 Spring Cloud Config Server 等。

4.2. 构建项目

在配置完成后，您需要使用 Apache Maven 来构建项目。打开命令行或终端，导航到项目的根目录（即包含 pom.xml 文件的目录），然后执行以下 Maven 命令：

bash

mvn clean package

• clean: 这个命令会清除先前构建生成的所有文件（即删除 target 目录）。
• package: 这个命令会编译代码、运行测试（如果配置了），并将项目打包成一个可执行的 JAR 文件。该 JAR 文件将包含所有必要的依赖项（“胖 JAR”），可以直接运行。

构建成功后，您会在项目的 target/ 目录下找到一个名为 sumsub-web-demo-0.0.1-SNAPSHOT.jar (版本号可能根据 pom.xml 中的定义有所不同) 的文件。

4.3. 运行应用程序

一旦项目成功构建并生成了可执行的 JAR 文件，您可以通过以下命令在本地运行该应用程序：

bash

java -jar target/sumsub-web-demo-0.0.1-SNAPSHOT.jar

替换 sumsub-web-demo-0.0.1-SNAPSHOT.jar为您实际生成的 JAR 文件名。

应用程序启动后，它会开始监听在 application.properties 中配置的端口（默认为 8080）。您可以在控制台输出中看到 Spring Boot 的启动日志，包括 Tomcat 服务器已启动并监听指定端口的信息。

此时，您可以打开 Web 浏览器并访问应用程序的前端界面，通常是 http://localhost:8080/ (如果端口是8080 )。您应该能看到 index.html 页面，并可以尝试通过它来获取 Sumsub 访问令牌。

4.4. 部署到服务器 (通用指南)

将此 Spring Boot 应用程序部署到服务器环境与部署其他标准的 Spring Boot “胖 JAR” 应用类似。以下是一些通用的步骤和考虑因素：

1. 准备服务器环境: 确保服务器上安装了 Java 运行时环境 (JRE) 或 Java 开发工具包 (JDK)，其版本与项目 pom.xml 中指定的 Java 版本（本项目为 Java 11）兼容或更高。

2. 上传 JAR 文件: 将构建好的可执行 JAR 文件（例如 sumsub-web-demo-0.0.1-SNAPSHOT.jar）上传到您的服务器上，例如上传到 /opt/apps/sumsub-demo/ 目录。

3. 外部化配置 (推荐): 为了便于管理不同环境（开发、测试、生产）的配置，并避免将敏感信息打包到 JAR 文件中，强烈建议外部化 application.properties 文件。

   • 您可以将 application.properties 文件放置在 JAR 文件旁边，Spring Boot 会自动加载它。
   • 或者，您可以使用命令行参数指定配置文件的位置：

     bash

     java -jar your-app.jar --spring.config.location=file:/path/to/your/application.properties
     

   • 更高级的方法包括使用 Spring Profiles 来管理特定环境的配置，或使用配置服务器。

4. 运行应用程序: 在服务器上，使用与本地运行类似的命令启动应用程序。如果配置已外部化，请确保命令指向正确的配置文件。

   bash

   java -jar /opt/apps/sumsub-demo/sumsub-web-demo-0.0.1-SNAPSHOT.jar
   

5. 作为服务运行 (推荐): 在生产环境中，您通常希望应用程序作为后台服务运行，并在服务器重启时自动启动。实现这一点的方法因操作系统而异：

   • Linux (Systemd): 创建一个 systemd 服务单元文件。例如，在 /etc/systemd/system/sumsub-demo.service 创建一个文件，内容类似：

     ini

     [Unit]
     Description=Sumsub Java Web Demo Application
     After=syslog.target network.target[Service]
     User=your-app-user # 推荐使用非root用户运行
     Group=your-app-group
     ExecStart=/usr/bin/java -jar /opt/apps/sumsub-demo/sumsub-web-demo-0.0.1-SNAPSHOT.jar
     SuccessExitStatus=143
     Restart=on-failure
     RestartSec=10[Install]
     WantedBy=multi-user.target
     

     然后使用 sudo systemctl daemon-reload, sudo systemctl enable sumsub-demo, sudo systemctl start sumsub-demo 等命令管理服务。
   • Linux (SysVinit): 创建 init.d 脚本。
   • Windows: 可以将应用程序注册为 Windows 服务，例如使用 NSSM (Non-Sucking Service Manager)。
   • Docker/Kubernetes: 将应用程序容器化是现代部署的常用方法。您可以创建一个 Dockerfile 来构建包含应用程序的 Docker 镜像，然后使用 Docker 或 Kubernetes 等容器编排平台来部署和管理它。这提供了更好的隔离性、可移植性和可伸缩性。

6. 配置反向代理 (可选但推荐): 通常，您会在应用程序前面设置一个反向代理服务器，如 Nginx 或 Apache HTTP Server。反向代理可以处理 SSL/TLS 终止、负载均衡、静态内容缓存、请求路由等任务。 例如，Nginx 可以配置为将来自公网的请求（如 https://yourdomain.com/sumsub-app/ ）代理到在本地运行的 Spring Boot 应用（如 http://localhost:8080/ ）。

7. 日志管理: 配置应用程序将日志输出到文件，并设置日志轮转。在服务器环境中，通常会使用集中的日志管理系统（如 ELK Stack - Elasticsearch, Logstash, Kibana 或 Grafana Loki）来收集、存储和分析应用程序日志。

8. 监控与健康检查: Spring Boot Actuator 模块（如果添加到项目中）可以提供生产就绪的端点，用于监控应用程序健康状况、指标、配置等。这些端点可以被监控系统集成。

通过遵循这些配置和部署步骤，您可以成功地运行和管理 Sumsub Java Web Demo 应用程序或基于其构建的更复杂的系统。

5. 安全注意事项

在开发和部署与敏感数据或外部 API（如 Sumsub）集成的应用程序时，安全性是至关重要的。本章节将讨论与 Sumsub Java Web Demo 项目相关的一些关键安全注意事项。

5.1. API 密钥管理

• 秘密密钥的机密性: SUMSUB_SECRET_KEY 是用于生成请求签名的核心凭证，必须严格保密。如果此密钥泄露，攻击者可能能够伪造对您 Sumsub 账户的 API 请求。
  • 禁止硬编码: 切勿将秘密密钥直接硬编码到源代码中，尤其是在提交到版本控制系统（如 Git）时。
  • 安全存储: 在生产环境中，应使用安全的方式存储和访问此密钥。推荐的方法包括：
    • 环境变量: 将密钥存储在运行应用程序的服务器的环境变量中。Spring Boot 可以轻松地从环境变量中读取配置属性。
    • 密钥管理服务: 使用专门的密钥管理服务，如 HashiCorp Vault, AWS Secrets Manager, Google Cloud Secret Manager, 或 Azure Key Vault。应用程序在启动时或运行时从这些服务安全地检索密钥。
    • 配置文件权限: 如果使用外部配置文件（如 application.properties），确保该文件的读取权限受到严格限制，只有运行应用程序的用户账户才能访问。
• 应用令牌: 虽然 SUMSUB_APP_TOKEN 不如秘密密钥那样敏感，但也应妥善管理，并避免不必要的暴露。

5.2. 请求签名

• 签名的重要性: Sumsub API 使用基于 HMAC-SHA256 的请求签名来验证请求的真实性和完整性。确保签名逻辑 (SumsubApiService#createSignature) 的正确实现至关重要。任何签名生成过程中的错误都可能导致 API 请求失败或潜在的安全漏洞。
• 时间戳 (Nonce): 签名过程中使用的时间戳 (X-App-Access-Ts) 有助于防止重放攻击。Sumsub 服务器通常会检查时间戳是否在可接受的时间窗口内。确保您的服务器时间与 NTP (Network Time Protocol) 同步，以避免因时间偏差导致签名验证失败。

5.3. 输入验证与输出编码

• 控制器输入验证: SumsubController 接收来自客户端的 userId 和 levelName 参数。虽然在当前演示中处理相对简单，但在生产应用中，应对所有外部输入进行严格验证：
  • 检查参数格式、长度、允许的字符集等。
  • 防止常见的注入攻击，如跨站脚本 (XSS)（尽管在此后端API场景下直接风险较低，但作为通用原则很重要）或路径遍历等。
• 输出编码: 当将数据显示回前端（例如，错误信息）时，确保进行了适当的输出编码，以防止 XSS 攻击。Spring MVC 默认会对 Thymeleaf 或 JSP 等视图技术中的数据进行编码，但如果是直接返回 JSON 数据，前端 JavaScript 在渲染时需要注意安全处理。

5.4. HTTPS 通信

• 与 Sumsub API 的通信: SumsubApiService 与 Sumsub API (sumsub.base.url) 的通信应始终通过 HTTPS 进行，以加密传输中的数据，防止窃听和篡改。OkHttp 默认支持 HTTPS。
• 客户端与本应用的通信: 如果此应用程序部署在公共网络上，客户端（浏览器）与本应用程序之间的通信也应强制使用 HTTPS。这通常通过在反向代理（如 Nginx）层面配置 SSL/TLS 证书来实现。

5.5. 依赖项安全

• 定期更新依赖: 项目依赖的第三方库（如 Spring Boot, OkHttp, Jackson 等）可能存在已知的安全漏洞。应定期检查并更新这些依赖到最新的安全版本。可以使用 Maven 的版本管理功能和一些安全扫描工具（如 OWASP Dependency-Check, Snyk, GitHub Dependabot）来帮助识别和管理易受攻击的依赖。

5.6. 异常处理与日志记录

• 详细的错误信息: 避免向客户端泄露过于详细的内部错误信息或堆栈跟踪，因为这可能暴露系统内部结构或潜在漏洞。应向客户端返回通用的错误消息，并将详细的错误信息记录在安全的服务器端日志中。
• 安全日志记录: 日志中可能包含敏感信息（例如，用户ID）。确保日志文件的存储和访问受到适当保护。避免在日志中记录完整的请求体或敏感凭证（如秘密密钥）。

5.7. 前端安全

虽然本项目主要关注后端，但前端 (script.js, index.html) 也有一些安全考虑：

• 处理API响应: JavaScript 在处理从后端获取的访问令牌时，应确保不会意外地将其暴露在不安全的环境中（例如，存储在不安全的本地存储中，或泄露给第三方脚本）。
• Content Security Policy (CSP): 可以通过设置 CSP HTTP头部来限制浏览器可以加载的资源类型和来源，减少XSS等攻击的风险。

5.8. 最小权限原则

• 运行用户: 应用程序应以具有完成其任务所需最小权限的用户账户运行，而不是使用 root 或管理员账户。
• API 密钥权限: 如果 Sumsub 或其他第三方服务支持细粒度的 API 密钥权限，请确保为应用程序生成的密钥仅具有其执行核心功能所必需的权限。

通过认真考虑和实施这些安全措施，可以显著提高 Sumsub Java Web Demo 应用程序及其衍生项目的整体安全性。

6. 总结与展望

Sumsub Java Web Demo 项目成功地演示了如何使用 Spring Boot、OkHttp 和相关的 Java 技术栈来集成 Sumsub 的身份验证服务，特别是专注于获取用于 Web SDK 的访问令牌。通过详细分析其项目架构、核心组件、业务流程、配置方法和安全机制，本文档为开发人员提供了一个清晰的指南，以便理解、使用和扩展此演示项目。

项目展示了构建与第三方 API 安全通信的后端服务的关键步骤，包括 API 密钥管理、请求签名生成以及 HTTP 请求的发送和响应处理。其分层架构（控制器、服务、模型）和对标准 Maven 项目布局的遵循，使其具有良好的可读性和可维护性。

主要成就与价值：

• 实践范例: 提供了一个具体的、可运行的 Java 代码示例，展示了 Sumsub API 集成的核心逻辑。
• 技术栈演示: 演示了如何在 Spring Boot 环境下结合使用 OkHttp, Jackson/FastJSON2, Apache Commons Codec 等流行库来完成实际任务。
• 安全意识: 通过对签名机制和密钥管理的强调，提升了开发者在集成第三方服务时的安全意识。
• 可扩展性基础: 项目的模块化设计为添加更多 Sumsub API 功能（如申请人创建、文档上传状态跟踪等）提供了良好的基础。

未来展望与潜在改进方向：

• 增强错误处理与日志记录: 可以引入更健壮的全局异常处理机制，并集成结构化的日志记录框架（如 SLF4J 与 Logback/Log4j2），以便更好地进行故障排查和监控。
• 异步处理: 对于可能耗时较长的 API 调用，可以考虑使用 Spring 的异步处理能力（例如 @Async 注解）或响应式编程模型（如 Project Reactor/Spring WebFlux）来提高应用的吞吐量和响应性。
• 全面的测试覆盖: 增加单元测试和集成测试的覆盖率，确保代码的质量和稳定性。
• 生产级配置管理: 引入更高级的配置管理方案，如 Spring Cloud Config，以适应复杂的部署环境和多环境配置需求。
• 容器化与云原生部署: 提供 Dockerfile 并考虑将其部署到 Kubernetes 等容器编排平台，以适应现代云原生架构。
• 扩展 Sumsub 功能集成: 可以基于现有框架，逐步集成 Sumsub 提供的其他 API 功能，例如创建申请人、上传文档、获取审核结果、处理 Webhook 通知等，从而构建一个功能更完整的 Sumsub 集成后端服务。
• 前端界面优化: 虽然当前前端仅为演示目的，但在实际应用中，可以构建一个功能更丰富、用户体验更好的前端界面。

7. 附录：参考资料

• Sumsub API 文档: https://developers.sumsub.com/api-reference/ (请以 Sumsub 官方最新文档为准)
• Spring Boot 官方文档: https://spring.io/projects/spring-boot
• OkHttp 官方网站: https://square.github.io/okhttp/
• Jackson 官方文档: https://github.com/FasterXML/jackson-docs
• Apache Commons Codec: https://commons.apache.org/proper/commons-codec/
• Maven 官方网站: https://maven.apache.org/