Socket自定义协议示例

- 请求报文与响应报文格式

请求报文与响应报文格式一致，均由6字节的报头和荷载组成；其中报头第一个字节为协议版本号，第二个字节为序列号，接下来的4个字节为荷载的长度。

- 协议格式

字节	5	4	3	2	1	0
说明	协议版本号	序列号	荷载长度	荷载长度	荷载长度	荷载长度

- 协议版本号说明：

当前可用版本号：0x02

- 序列号说明：

序列号用于保证数据包的顺序，由客户端生成，服务端返回响应数据包时将其返回给客户端；可用的取值范围 0~255，其中0用作服务器推送数据专用的序列号，客户端实际可用的范围为 1~255。

- 荷载格式说明：

荷载为JSON字符串的 byte 数组，其中有两个固定的字段 buzcmd 和 identity（如下代码）：

{
    "buzcmd": "业务指令（必填，区分不同业务可使用“/”做区分，如：sys/user）",
    "identity": "唯一标识（可选，可用此字段来对数据包做唯一标识）"
}

- 客户端请求：

1. heartcheck（心跳检测）

请求格式

{
    "buzcmd": "heartcheck",
    "identity": "唯一标识（可选，可用此字段来对数据包做唯一标识）"
}

响应格式

{
    "buzcmd": "heartcheck",
    "identity": "唯一标识（可选，可用此字段来对数据包做唯一标识）",
    "code": "操作代码（0-成功 1-警告 2-失败）"
}

2. login（登录）

这里的登录，并不是严格来说的登录，只是用来关联业务与Socket连接的。

请求格式

{
    "buzcmd": "login",
    "identity": "唯一标识（可选，可用此字段来对数据包做唯一标识）",
    "username": "用户名",
    "password": "密码"
}

响应格式

{
    "buzcmd": "login",
    "identity": "唯一标识（可选，可用此字段来对数据包做唯一标识）",
    "code": "操作代码（0-成功 1-警告 2-失败）",
    "data": "响应数据信息",
    "message": "操作响应提示信息"
}

3. logout（登出）

请求格式

{
    "buzcmd": "logout",
    "identity": "唯一标识（可选，可用此字段来对数据包做唯一标识）"
}

响应格式

{
    "buzcmd": "logout",
    "identity": "唯一标识（可选，可用此字段来对数据包做唯一标识）",
    "code": "操作代码（0-成功 1-警告 2-失败）",
    "data": "响应数据信息",
    "message": "操作响应提示信息"
}

4. attend/identityrec（识别记录上传）

请求格式

{
    "buzcmd": "attend/identityrec",
    "identity": "唯一标识（可选，可用此字段来对数据包做唯一标识）",
    "uid": "用户唯一标识（如果该字段为空，那么卡号字段不能为空）",
    "cardnumber": "卡号",
    "rectime": "识别时间",
    "direction": "进出方向（1-进 2-出）",
    "recimage": "识别图片（base64）",
    "devid": "设备唯一标识",
    "areaid": "区域唯一标识",
    "schoolid": "学校唯一标识"
}

响应格式

{
    "buzcmd": "attend/identityrec",
    "identity": "唯一标识（可选，可用此字段来对数据包做唯一标识）",
    "code": "操作代码（0-成功 1-警告 2-失败）",
    "data": "响应数据信息",
    "message": "操作响应提示信息"
}

- 服务端推送

1. push/user（推送用户信息）

推送格式

{
    "buzcmd": "push/user",
    "identity": "数据包唯一标识",
    "uid": "用户唯一标识",
    "username": "用户姓名",
    "usertype": "用户类型（S-学生，T-教师）",
    "classname": "班级名称（教师用户为空）",
    "cardnumber": "卡号（可为空）",
    "idimage": "底库图片，图片地址"
}

回执格式

{
    "buzcmd": "logout",
    "identity": "唯一标识（可选，可用此字段来对数据包做唯一标识）",
    "code": "操作代码（0-成功 1-警告 2-失败）",
    "data": "响应数据信息",
    "message": "操作响应提示信息"
}

2. push/area（推送区域信息，暂未实现）

推送格式

{
    "buzcmd": "push/area",
    "identity": "数据包唯一标识"
}

回执格式

{
    "buzcmd": "push/area",
    "identity": "唯一标识（可选，可用此字段来对数据包做唯一标识）",
    "code": "操作代码（0-成功 1-警告 2-失败）",
    "data": "响应数据信息",
    "message": "操作响应提示信息"
}

3. push/device（推送设备信息，暂未实现）

推送格式

{
    "buzcmd": "push/device",
    "identity": "数据包唯一标识"
}

回执格式

{
    "buzcmd": "push/device",
    "identity": "唯一标识（可选，可用此字段来对数据包做唯一标识）",
    "code": "操作代码（0-成功 1-警告 2-失败）",
    "data": "响应数据信息",
    "message": "操作响应提示信息"
}

- 代码示例（心跳检测）

请求示例

String body = "{\"buzcmd\":\"heartcheck\"}";
ByteBuf buf = Unpooled.buffer(1 + 1 + 4 + body.length());
buf.writeByte(0x02);
buf.writeByte(0x01);
buf.writeInt(body.length());
buf.writeBytes(body.getBytes());

心跳响应

ByteBuf buf = Unpooled.buffer(1 + 1 + 4 + body.length()); // 服务端响应，这里新增
byte version = buf.readByte();
byte sequence = buf.readByte();
int length = buf.readInt();
byte[] content = new byte[length];
buf.readBytes(content);

- 响应荷载

字段	类型	说明
code	byte	处理标识（0-成功 1-警告 2-失败）
data	Object	响应数据
message	String	响应消息