第二章 通信协议规范

2.1 消息格式

SXDB采用固定长度头的二进制协议。每个消息由两部分组成：4字节大端序列长度头 + JSON消息体。长度头表示后续JSON消息的字节数。

字段

长度

说明

示例

Length

4字节

大端序列，表示JSON体长度

0x00 0x00 0x00 0x5A (90字节)

Payload

可变

UTF-8编码的JSON字符串

{"action":"QUERY",...}

2.2 请求响应格式

请求和响应均采用相同的消息格式。响应JSON固定包含三个字段：code（状态码，0表示成功）、msg（描述文本）、data（业务数据）。

2.3 Action动作列表

Action

功能

必需参数

返回数据

AUTH

用户认证

username, password

token

OPEN_DB

打开数据库

token, db

-

CLOSE_DB

关闭数据库

token, db

-

EXECUTE

执行SQL(DDL/DML)

token, db, sql, params

affected

QUERY

查询SQL(SELECT)

token, db, sql, params

columns, rows

BATCH

批量执行SQL

token, db, statements

各条结果

PING

心跳检测

-

-

2.4 认证流程

连接建立后，客户端需先发送AUTH请求获取token。后续所有数据操作请求均需携带该token。典型流程为：连接 → AUTH → OPEN_DB → QUERY/EXECUTE → CLOSE_DB → 断开。