企业官网建设流程全解析

• 示例工程
• 教程
• 后端

本篇技术指南聚焦javav2/example_code/stepfunctions目录下的 AWS SDK for Java (v2) 示例代码，系统讲解如何运行与测试这些 AWS Step Functions 示例，覆盖状态机（State Machine）与活动（Activity）的创建、查询、执行、删除以及执行历史检索等核心操作，并深入剖析一个模拟聊天机器人交互的完整场景。读完本文，你将掌握使用SfnClient编写可运行、可测试的 Step Functions 工作流编排代码的完整方法。

AWS Step Functions 与 Java SDK v2 示例概览

AWS Step Functions 是一个可视化工作流服务，帮助开发者使用 AWS 服务构建分布式应用、自动化流程、编排微服务，以及创建数据与机器学习（ML）管道。它通过Amazon States Language (ASL)定义状态机，由 Step Functions 服务负责执行状态间的流转、重试与错误处理。

本仓库中的 Java 示例（位于 javav2/example_code/stepfunctions）使用 AWS SDK for Java v2 提供的SfnClient（全限定名software.amazon.awssdk.services.sfn.SfnClient）封装了 Step Functions 的核心 API 调用，涵盖以下文件：

• CreateStateMachine.java：根据 ASL JSON 定义创建状态机
• DeleteStateMachine.java：删除状态机
• GetExecutionHistory.java：检索指定执行的完整事件历史
• GetFailedExecutions.java：列出某个状态机下的执行记录
• ListActivities.java：列出账户中的活动
• ListStateMachines.java：列出账户中的状态机
• StartExecution.java：启动状态机执行
• scenario/StepFunctionsScenario.java：多命令组合的完整场景示例

所有示例使用的凭据提供器均为默认凭据提供器（default credentials provider），即通过环境变量、本地配置文件或 IAM 角色等链式机制自动解析 AWS 凭据，无需在代码中硬编码密钥。

⚠️ 重要提示

运行或测试这些代码可能产生 AWS 账户费用（详见 AWS 官方定价页面）。建议遵循最小权限原则（least privilege），仅授予执行任务所需的最低权限，并使用独立的测试专用资源进行实验。此外，这些代码未在所有 AWS 区域测试，请以所用区域的服务可用性为准。

代码示例清单：入门与单动作调用

入门示例（Get started）

• Hello AWS Step Functions—— 见 ListStateMachines.java，演示listStateMachines命令。

单动作示例（Single action）

以下代码摘录演示如何调用单个服务函数：

说明：原 README 中部分链接指向 route53 目录，实际上这些场景代码位于stepfunctions/scenario子包，本文统一采用仓库内实际路径。

场景示例（Scenarios）

• Get started with AWS Step Functions—— StepFunctionsScenario.java，通过多次调用同一服务内的多个函数完成一个完整业务目标。

单动作示例源码解读

列出状态机：ListStateMachines

ListStateMachines.java 是最简单的入门示例，其核心逻辑如下：

Region region = Region.US_EAST_1; SfnClient sfnClient = SfnClient.builder() .region(region) .build(); listMachines(sfnClient); sfnClient.close(); public static void listMachines(SfnClient sfnClient) { try { ListStateMachinesResponse response = sfnClient.listStateMachines(); List<StateMachineListItem> machines = response.stateMachines(); for (StateMachineListItem machine : machines) { System.out.println("The name of the state machine is: " + machine.name()); System.out.println("The ARN value is : " + machine.stateMachineArn()); } } catch (SfnException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } }

关键点：

• 客户端构建采用链式 Builder 模式，显式指定Region.US_EAST_1；示例中的区域可依据实际部署环境调整。
• listStateMachines()返回ListStateMachinesResponse，其stateMachines()返回StateMachineListItem列表，每一项包含name()与stateMachineArn()两个核心属性。
• 所有示例统一通过捕获SfnException（继承自 AWS SDK 运行时异常）读取awsErrorDetails().errorMessage()输出错误原因，并调用System.exit(1)终止进程。
• SfnClient使用完毕后需显式调用close()释放底层 HTTP 连接资源。

创建状态机：CreateStateMachine

CreateStateMachine.java 演示如何从 ASL JSON 定义文件创建状态机：

public static String createMachine(SfnClient sfnClient, String roleARN, String stateMachineName, String jsonFile) { String json = getJSONString(jsonFile); try { CreateStateMachineRequest machineRequest = CreateStateMachineRequest.builder() .definition(json) .name(stateMachineName) .roleArn(roleARN) .type(StateMachineType.STANDARD) .build(); CreateStateMachineResponse response = sfnClient.createStateMachine(machineRequest); return response.stateMachineArn(); } catch (SfnException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } return ""; }

运行参数（main方法校验args.length != 3时打印用法并退出）：

实现细节：

• 使用json-simple库的JSONParser与JSONObject读取并重新序列化 JSON 文件，得到String形式的定义。
• CreateStateMachineRequest的type()指定为StateMachineType.STANDARD（标准工作流，适用于需要长期运行、有审计事件与回调的场景；对应还有EXPRESS类型用于高吞吐、短时运行）。
• 返回的stateMachineArn是后续startExecution、describeStateMachine、deleteStateMachine等操作的唯一标识。

启动执行：StartExecution

StartExecution.java 演示启动状态机执行：

public static String startWorkflow(SfnClient sfnClient, String stateMachineArn, String jsonFile) { String json = getJSONString(jsonFile); UUID uuid = UUID.randomUUID(); String uuidValue = uuid.toString(); try { StartExecutionRequest executionRequest = StartExecutionRequest.builder() .input(json) .stateMachineArn(stateMachineArn) .name(uuidValue) .build(); StartExecutionResponse response = sfnClient.startExecution(executionRequest); return response.executionArn(); } catch (SfnException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } return ""; }

运行参数：<stateMachineArn> <jsonFile>，其中jsonFile为包含传入工作流参数值的 JSON 文件。

实现细节：

• 执行名称用UUID.randomUUID()生成，避免重复执行同名冲突（Step Functions 要求同一状态机下的执行名称唯一，默认去重窗口为 90 天）。
• 执行输入input以 JSON 字符串形式传入，状态机首状态即可通过$.参数名引用。
• 返回的executionArn可用于后续describeExecution与getExecutionHistory。

列出活动、获取执行历史与失败执行

• ListActivities.java：构造ListActivitiesRequest并设置maxResults(10)限制返回条数，遍历ActivityListItem输出activityArn()与name()。
• GetExecutionHistory.java：接收执行 ARN，构造GetExecutionHistoryRequest（同样设置maxResults(10)），遍历返回的HistoryEvent列表并打印type()事件类型（如TaskScheduled、TaskSucceeded、ExecutionSucceeded等）。
• GetFailedExecutions.java：接收状态机 ARN，通过ListExecutionsRequest.builder().stateMachineArn(...)列出该状态机的执行记录，逐一输出executionArn()。注意该示例客户端区域设置为Region.US_WEST_2，与其余示例（US_EAST_1）不同，跨区域使用时需确认状态机所在区域。
• DeleteStateMachine.java：构造DeleteStateMachineRequest，传入状态机 ARN 后调用deleteStateMachine，成功后打印确认信息。

完整场景：ChatSFN 聊天式活动编排

StepFunctionsScenario.java 是一个将上述单动作串成完整业务闭环的场景示例，模拟了一个聊天机器人（ChatSFN）工作流：状态机执行到某个Task状态时暂停，等待外部代码通过Activity拉取任务并回传结果。其执行流程共 7 步：

1. 创建活动（Create an activity）：createActivity基于CreateActivityRequest.builder().name(activityName)创建活动，返回activityArn。
2. 创建状态机（Create a state machine）：先用 IAM 创建信任策略为states.amazonaws.com的服务角色，再读取chat_sfn_state_machine.json，并通过 Jackson 将 JSON 中States.GetInput节点的Resource字段改写为刚创建的活动 ARN，最后以修改后的定义创建状态机。
3. 描述状态机（Describe the state machine）：describeStateMachine输出名称、状态、ARN 与角色 ARN，然后通过控制台交互询问用户名。
4. 启动执行并交互（Start execution and interact）：以{ "name" : "<userName>" }作为输入启动执行；随后循环调用getActivityTask拉取活动任务（返回taskToken与input），打印 ChatSFN 的回复，等待用户输入动作，再通过sendTaskSuccess将结果回传给 Step Functions。当用户输入done时结束循环。
5. 描述执行（Describe the execution）：describeExe轮询describeExecution，每 2 秒检查一次状态，直到SUCCEEDED为止。
6. 删除活动（Delete the activity）：deleteActivity释放活动资源。
7. 删除状态机（Delete the state machine）：deleteMachine调用删除后持续describeStateMachine轮询确认删除完成。

场景中的关键方法实现

创建 IAM 服务角色（信任策略允许 Step Functions 服务代入）：

String polJSON = """ { "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "states.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } """;

调用iam.createRole时传入roleName、assumeRolePolicyDocument与描述信息，返回角色 ARN。注意IamClient使用全局区域Region.AWS_GLOBAL，而SfnClient使用Region.US_EAST_1。

获取活动任务并发送成功响应（Activity 的拉取-回传模式核心）：

public static List<String> getActivityTask(SfnClient sfnClient, String actArn) { List<String> myList = new ArrayList<>(); GetActivityTaskRequest getActivityTaskRequest = GetActivityTaskRequest.builder() .activityArn(actArn) .build(); GetActivityTaskResponse response = sfnClient.getActivityTask(getActivityTaskRequest); myList.add(response.taskToken()); myList.add(response.input()); return myList; } public static void sendTaskSuccess(SfnClient sfnClient, String token, String json) { SendTaskSuccessRequest successRequest = SendTaskSuccessRequest.builder() .taskToken(token) .output(json) .build(); sfnClient.sendTaskSuccess(successRequest); }

getActivityTask返回的taskToken是回传结果的凭证，必须原样交给sendTaskSuccess；input是状态机传入该任务的数据。这种模式适合需要人工审批、外部系统介入的长时间运行任务。

轮询等待执行完成：

while (!hasSucceeded) { DescribeExecutionResponse response = sfnClient.describeExecution(executionRequest); status = response.statusAsString(); if (status.compareTo("RUNNING") == 0) { System.out.println("The state machine is still running, let's wait for it to finish."); Thread.sleep(2000); } else if (status.compareTo("SUCCEEDED") == 0) { System.out.println("The Step Function workflow has succeeded"); hasSucceeded = true; } else { System.out.println("The Status is neither running or succeeded"); } }

通过statusAsString()读取执行状态，在RUNNING时休眠 2 秒重试，直到SUCCEEDED或进入其他终态。

场景运行参数与资源文件

场景主方法校验 4 个参数：<roleName> <activityName> <stateMachineName> <jsonFile>，分别对应 IAM 角色名、活动名、状态机名以及chat_sfn_state_machine.json的路径。

该 ASL 定义文件可从仓库的resources/sample_files目录获取，名为chat_sfn_state_machine.json。场景代码通过FileInputStream读取该文件并用 JacksonObjectMapper解析为JsonNode，修改States.GetInput.Resource后再序列化为状态机定义字符串——这一步是场景得以把"聊天任务"绑定到真实 Activity 的关键。

环境准备与运行前置条件

要运行这些示例，需要先配置好 Java 开发环境（JDK 与 AWS SDK for Java v2 的依赖管理），并确保本机已完成 AWS 凭据与区域配置。项目的 pom.xml 显示：

• Java 版本：21（<java.version>21</java.version>，编译源码与目标均为 21）
• AWS SDK BOM：software.amazon.awssdk:bom:2.35.10，统一管理sfn、iam、secretsmanager、sso、ssooidc等模块版本
• JSON 处理：json-simple:1.1.1（读 ASL 定义）与jackson-databind:2.18.9（场景中动态改写 JSON）
• 测试与日志：junit-jupiter:5.11.4、log4j-bom:2.23.1、slf4j-api:2.0.13
• 构建插件：maven-compiler-plugin:3.1与maven-surefire-plugin:3.5.2

务必小心运行任何会删除或修改 AWS 资源的操作。建议在实验时创建仅用于测试的独立资源，避免影响生产环境。

测试 Step Functions Java 示例

测试方式与输出

示例代码通过 JUnit 5 测试类StepFunctionsTest进行验证，文件位于src/test/java目录，即 StepFunctionsTest.java。可以在 IDE（如 IntelliJ IDEA）中运行，也可以在命令行通过 Maven 的 surefire 插件运行。每个测试运行时会输出成功或失败信息，例如：

Test 1 passed

WARNING：运行这些 JUnit 测试会操作真实的 AWS 资源，可能产生账户费用。

从测试源码可以看到其设计：

• 测试类标注@TestInstance(TestInstance.Lifecycle.PER_METHOD)与@TestMethodOrder(MethodOrderer.OrderAnnotation.class)，按@Order注解顺序执行。
• @BeforeAll中创建SfnClient（区域US_EAST_1），并从 AWS Secrets Manager 读取test/stepfunctions密钥中的测试参数，为角色名、活动名与状态机名追加UUID.randomUUID()后缀，避免测试间资源命名冲突。
• 目前包含两个集成测试：testListActivities（调用ListActivities.listAllActivites）与TestHello（调用ListStateMachines.listMachines），均使用assertDoesNotThrow断言，通过后打印Test N passed。

Properties 文件（config.properties）

运行 JUnit 测试前，必须在resources文件夹下的config.properties文件中定义所需值；未定义全部值时测试会失败。该文件位于 config.properties，原始模板为：

jsonFile = <set jsonFile value> jsonFileSM = <set jsonFileSM value> roleARN = <set roleARN value> stateMachineName = <set stateMachineName value>

结合 README 说明，运行场景测试需要配置以下关键值：

补充说明：从 StepFunctionsTest.java 的实现看，当前测试版本已支持从 AWS Secrets Manager 密钥test/stepfunctions读取测试参数（roleNameSC、activityNameSC、stateMachineNameSC），配置属性与 Secrets Manager 是两条可选的参数供给路径。

状态机定义文件

创建状态机所需的 ASL JSON 定义文件位于仓库的resources/sample_files目录。运行场景测试时，需要将chat_sfn_state_machine.json放入项目的 resources 文件夹，否则测试无法成功。该文件定义了 ChatSFN 工作流的状态结构，其中GetInput状态的Resource字段在运行时被替换为动态创建的活动 ARN。

日志配置

项目资源目录下的 log4j2.xml 配置了 Log4j2 控制台输出：定义ConsoleAppender（%msg%n格式）与AlignedConsoleAppender（%m%n格式），根 logger 级别为info，关联到ConsoleAppender。测试中的"Test N passed"日志正是经由该日志链路打印到控制台。

构建与运行建议

以 Maven 为构建工具，在javav2/example_code/stepfunctions目录下可执行以下典型操作（具体以本机 Maven 配置为准）：

• 编译：mvn compile
• 运行测试：mvn test（将触发 StepFunctionsTest，需先完成凭据、config.properties 或 Secrets Manager 参数配置）
• 运行单个示例：编译后通过java执行对应主类并传入所需参数，例如创建状态机需提供<jsonFile> <roleARN> <stateMachineName>三个参数

由于示例均使用默认凭据提供器，运行前请确保通过环境变量、~/.aws/credentials或 IAM 角色等方式配置了具备 Step Functions（states:*）、IAM（场景中创建角色）与 Secrets Manager（测试读取密钥）权限的凭据。

小结

本指南完整覆盖了javav2/example_code/stepfunctions下 AWS Step Functions 的 Java SDK v2 示例：从单动作的createStateMachine、startExecution、listExecutions、getExecutionHistory到多命令组合的 ChatSFN 场景，并给出了环境配置、config.properties参数、JUnit 5 测试方法与 ASL 定义文件的使用要点。读者可以基于这些模式进一步扩展：例如将 Activity 模式用于人工审批流，将getExecutionHistory用于工作流审计，或将状态机定义参数化以实现多环境复用。

文中涉及的源码均位于 javav2/example_code/stepfunctions 目录，示例版权归 Amazon.com, Inc. 或其关联公司所有，代码遵循 Apache-2.0 许可（SPDX-License-Identifier: Apache-2.0）。

• 示例工程
• 教程
• 后端