4. 接口协议建模方法

接口协议建模的目标，是把一份“能读懂但难以执行”的协议文本，转化为仿真环境可以直接加载、联调人员可以逐条核对、测试用例可以自动生成的形式化描述。它要回答四个问题：报文长什么样、设备在什么条件下切换状态、信号之间必须满足哪些时间关系、出错时双方如何反应。这四类信息分别对应报文结构、状态机、时序约束和异常行为，缺一不可。

一、报文结构：从字节布局到可校验的字段模型

报文结构建模不是把协议手册的表格抄一遍，而是把每个字段的偏移、长度、字节序、取值域、默认值和校验方式显式化。以一条典型的设备控制报文为例，假设采用小端字节序，帧格式为：帧头 0xAA55（2 字节）、长度 LEN（1 字节，表示载荷长度）、命令字 CMD（1 字节）、载荷 PAYLOAD（LEN 字节）、校验 CRC16（2 字节，覆盖 LEN 到 PAYLOAD）。

帧结构（小端）：
偏移 0..1 : HEADER = 0xAA55
偏移 2    : LEN    = 载荷字节数，取值 0..64
偏移 3    : CMD    = 0x01 启动 / 0x02 停止 / 0x03 查询状态
偏移 4..   : PAYLOAD
末尾 2 字节: CRC16，覆盖 LEN、CMD、PAYLOAD

建模时建议为每个字段定义五元组：名称、偏移、长度、类型、约束。例如 CMD 字段的约束是“枚举 {0x01,0x02,0x03}，其他值视为非法命令”。这样，仿真器在发送前可以做一次本地校验，接收端也可以按同一模型解析，避免“发送方认为合法、接收方认为越界”的争议。对于变长载荷，必须明确 LEN 与 PAYLOAD 的对应关系，并规定 LEN 超出上限时的处理策略——是截断、拒绝还是回错误帧，这属于异常行为建模的一部分。

二、状态机：把“什么时候能发什么”变成可执行规则

状态机描述的是接口在生命周期内的合法状态与迁移条件。以设备控制接口为例，可抽象为四个状态：空闲（IDLE）、就绪（READY）、运行（RUN）、故障（FAULT）。迁移条件由收到的命令和内部条件共同决定：IDLE 收到启动命令且自检通过进入 READY；READY 收到启动命令进入 RUN；RUN 收到停止命令回到 READY；任一状态检测到硬件故障进入 FAULT；FAULT 收到复位命令且故障消除回到 IDLE。

形式化描述时，每个迁移应写成“源状态 + 触发事件 + 守卫条件 + 动作 + 目标状态”。例如：READY --[CMD_START, 温度<85℃] / 启动电机 --> RUN。守卫条件不可省略，否则状态机无法区分“命令合法但条件不满足”和“命令非法”这两种情况，而它们在异常处理中往往需要不同的响应。

三、时序约束：把“先后”和“多久”写成可判定的条件

时序约束建模要区分三类关系：顺序关系、超时关系和并发关系。顺序关系如“收到启动命令后，必须在 50 ms 内返回应答帧”；超时关系如“发送请求后 200 ms 未收到应答，判定为超时并重发，最多重发 3 次”；并发关系如“状态查询与命令下发可以并行，但同一时刻只允许一条控制命令在途”。

这些约束应写成带参数的判定式，而不是自然语言描述。例如：t_reply ≤ 50 ms、t_timeout = 200 ms、retry_max = 3、t_retry_interval = 100 ms。仿真器据此可以自动检查：如果应答在 50 ms 后到达，标记为“迟应答”；如果 200 ms 内无应答，触发重发；如果重发 3 次仍失败，进入 FAULT 并记录错误码。这样，时序约束就从“文档里的说明”变成了“仿真中的断言”。

四、异常行为：定义错误码、恢复路径与边界条件

异常行为建模最容易被忽略，却直接决定联调效率。建议至少覆盖四类：帧级异常（帧头错误、长度越界、CRC 校验失败）、命令级异常（非法 CMD、参数越界）、状态级异常（在 IDLE 收到停止命令、在 FAULT 收到启动命令）、时序级异常（应答超时、重发耗尽）。每类异常应明确：检测条件、响应动作、错误码、是否改变状态、是否记录日志。

例如，CRC 校验失败时，接收端丢弃该帧、不改变状态、回送错误码 0xE1，并累计错误计数；连续 5 次 CRC 错误则进入 FAULT。非法 CMD 时，回送错误码 0xE2，状态保持不变。在 FAULT 状态下收到 CMD_START，回送 0xE3 并保持 FAULT，直到收到 CMD_RESET 且故障条件消除。把这些规则写成表格或结构化描述，仿真器就能自动生成对应的异常测试用例。

五、文档化：让模型成为可交付、可追溯的资产

形式化描述最终要落到文档上，但文档不应是散落的文字说明。推荐采用“模型文件 + 说明文档”的双层结构：模型文件用结构化格式（如 JSON、YAML 或自定义 DSL）描述报文、状态、迁移、时序参数和异常规则，供仿真器加载；说明文档则解释设计意图、取值依据和典型场景，供人阅读。两者通过字段名和错误码一一对应，保证可追溯。

一个可参考的模型片段如下：

{
  "frame": {
    "header": "0xAA55",
    "fields": [
      {"name": "LEN", "offset": 2, "len": 1, "range": [0, 64]},
      {"name": "CMD", "offset": 3, "len": 1, "enum": [1, 2, 3]},
      {"name": "PAYLOAD", "offset": 4, "len": "LEN"},
      {"name": "CRC16", "offset": "4+LEN", "len": 2}
    ]
  },
  "timing": {"t_reply_max_ms": 50, "t_timeout_ms": 200, "retry_max": 3},
  "errors": {
    "0xE1": "CRC_FAIL",
    "0xE2": "INVALID_CMD",
    "0xE3": "ILLEGAL_STATE"
  }
}

文档化时还要注意版本管理：协议一旦变更，模型文件、说明文档和测试用例必须同步更新，并在变更记录中注明影响的字段、状态或时序参数。只有这样，接口协议建模才不是一次性的纸面工作，而是可持续支撑仿真与联调的工程资产。