🧬 协议 Codec

Codec 定义了报文如何分帧（切分出单条消息）与解析（从消息中提取字段）。管理后台「TCP 代理 → 协议 Codec」页面维护命名 Codec，监听器通过 type: custom + codecName 引用。

为什么需要命名 Codec

多个监听器可能需要相同的协议定义。将协议配置提取为命名 Codec，可：

一次定义、多处复用（监听器引用同一 Codec）
后台集中管理，修改后立即生效
让配置更简洁

yaml

# Codec 表：定义命名协议
codecs:
    - name: line-cmd
      protocol:
        type: delimiter
        delimiter: "\n"
        parseFields:
            - name: cmd
              split: ' '
              index: 0

# 监听器：引用 Codec
listeners:
    - name: line-cmd-demo
      port: 19004
      protocol:
        type: custom
        codecName: line-cmd

内置 Codec

以下协议类型无需自定义即可直接使用：

类型	分帧与解析能力
`raw`	透传原始字节
`delimiter`	按分隔符切分消息
`lengthPrefix`	按长度前缀切分消息
`fixedLength`	按固定长度切分消息
`redis`	自动解析 RESP 命令与响应（`+OK`、`$5`、数组等）
`mysql`	自动解析 COM 命令 / OK / ERR / 结果集
`mqtt`	自动解析 CONNECT / PUBLISH / SUBSCRIBE / PINGREQ 等
`websocket`	HTTP Upgrade 握手 + 数据帧解析（自动去掩码）
`grpc`	前奏 + HTTP/2 帧 + HPACK 头 + gRPC 消息解析
`coap`	RFC 7252 CoAP 报文解析（UDP 监听器使用）

字段提取（parseFields）

从报文中提取字段是规则匹配与模板渲染的基础。支持多种提取方式，可组合：

yaml

parseFields:
    # 方式一：定长截取（offset + length）
    - name: type
      offset: 0
      length: 1
      encoding: hex

    # 方式二：整体 JSON 平铺（点号分隔键）
    - name: body
      json: true
      # 提取后可访问 body.user.name

    # 方式三：JSONPath 提取单个字段
    - name: userId
      jsonPath: user.id

    # 方式四：正则提取
    - name: orderNo
      regex: 'order-(\d+)'
      group: 1

    # 方式五：分隔符拆分
    - name: cmd
      split: ' '
      index: 0

提取方式总览

参数	说明
`offset` + `length`	定长截取，`length <= 0` 表示截取到末尾
`encoding`	`utf8` / `hex`，默认 `utf8`
`json`	整体 JSON 平铺为点号键
`jsonPath`	JSON 提取单个字段路径（如 `a.b.0`）
`regex` + `group`	正则提取，`group = 0` 表示整条匹配
`split` + `index`	按分隔符拆分后取第 index 段

字段的用途

提取出的字段在 TCP 规则中用于匹配（match.field），在 mock 响应中用于模板渲染（{{ .fields.xxx }}）。

管理后台操作

进入「TCP 代理 → 协议 Codec」页面
新建 Codec：填写名称，选择协议类型并配置分帧参数与字段提取
保存后，监听器的 protocol.type 选 custom 并引用该 Codec 名称
修改 Codec 后保存即生效，引用它的监听器自动使用新配置

方法	路径	说明
GET	`/api/tcp/codecs`	Codec 列表
POST	`/api/tcp/codecs`	新建 Codec
PUT	`/api/tcp/codecs/:name`	更新 Codec
DELETE	`/api/tcp/codecs/:name`	删除 Codec

🧬 协议 Codec ​

为什么需要命名 Codec ​

内置 Codec ​

字段提取（parseFields） ​

提取方式总览 ​

管理后台操作 ​