API设计：如何确保手持传感器API命令按特定顺序调用

当然可以通过API本身实现命令调用顺序的强制管控，核心是在传感器端维护流程状态，每次请求时校验当前状态是否允许执行目标命令，直接拒绝不符合流程的调用。以下是几种落地性强的方案：

1. 会话ID+状态机机制 #

这是最通用的方案，适合需要保留细粒度步骤控制的场景：

• 客户启动流程时，API返回唯一的sessionId，传感器端为该会话维护状态（比如initial、step1_done、step2_in_progress、cancelled等）
• 后续所有命令请求必须携带sessionId，API先校验会话当前状态：
  • 状态匹配则正常处理并更新状态
  • 状态不匹配（比如未完成step1就调用step2），直接返回错误响应拒绝执行
• 响应里明确返回当前会话状态和允许的下一批命令，让集成方清晰知道可操作范围

请求示例（携带会话ID） #

{
    "sessionId": "sensor-sess-001",
    "command": "do_step_two"
}

错误响应（状态不匹配时） #

{
    "respondingToCommand": "do_step_two",
    "sessionId": "sensor-sess-001",
    "date": "2023-04-03T19:25:10.000000",
    "message": "无法执行step2：当前会话处于initial状态，请先完成step1",
    "currentSessionState": "initial",
    "status": "invalid_request"
}

成功完成step1的响应 #

{
    "respondingToCommand": "do_step_one",
    "sessionId": "sensor-sess-001",
    "date": "2023-04-03T19:23:23.000000",
    "message": "step1执行成功",
    "currentSessionState": "step1_done",
    "nextAllowedCommands": ["do_step_two", "cancel_sequential_process"],
    "status": "done"
}

2. 一次性命令令牌机制 #

如果需要更强的安全性，防止重复调用或非法跳步，可用令牌替代状态校验：

• 完成每一步后，API返回对应下一步的唯一一次性令牌（比如step2-token-xyz）
• 调用下一步命令时必须携带该令牌，API验证令牌的有效性（是否属于当前流程、是否未被使用）
• 令牌使用后立即失效，重复提交会被拒绝

完成step1的响应示例 #

{
    "respondingToCommand": "do_step_one",
    "date": "2023-04-03T19:23:23.000000",
    "message": "step1执行成功",
    "nextSteps": [
        {
            "name": "继续执行step2",
            "command": "do_step_two",
            "requiredToken": "step2-token-xyz123"
        },
        {
            "name": "取消流程",
            "command": "cancel_sequential_process",
            "requiredToken": "cancel-token-abc456"
        }
    ],
    "status": "done"
}

step2请求示例（携带令牌） #

{
    "command": "do_step_two",
    "token": "step2-token-xyz123"
}

3. 原子化流程API（简化集成） #

如果客户不需要干预中间步骤，只关心最终结果，可封装整个流程为一个原子API：

• 提供start_full_process命令，传感器内部自动按顺序执行所有步骤
• 集成方通过get_process_status查询进度，或等待异步回调通知结果
• 这种方式完全规避顺序问题，但牺牲了中间步骤的可控性

以上方案都能从API层面强制管控命令顺序，替代仅靠文档约束的方式，其中会话状态机方案平衡了可控性和集成复杂度，是最常用的选择。

内容的提问来源于stack exchange，提问作者hugo