通信协议

协议概述

cs-auther 采用基于 TCP 长连接 的 JSON 文本协议，所有数据以 UTF-8 编码传输。协议设计简洁直观，便于调试和扩展。

---

数据包格式

每条消息都是一个完整的 JSON 对象，包含三个固定字段：

{
    "action": "类名/方法名",
    "token":  "用户凭证（可选）",
    "data":   { ... }
}

字段	类型	必填	说明
action	String	是	路由地址，格式为 类名/方法名，如 User/Login、Calc/Submit
token	String	否	登录成功后服务端下发的凭证，用于身份验证
data	Object	是	业务数据，必须是对象（字典/集合/cJson.Root），空数据传 {}

---

路由命名规范

路由地址采用 PascalCase 类名 + 方法名 的命名方式：

User/Login        → 调用 bUser 类的 Login 方法
User/Info         → 调用 bUser 类的 Info 方法
Notify/Show       → 调用 bNotify 类的 Show 方法
Notify/CheckNew   → 调用 bNotify 类的 CheckNew 方法
Calc/Submit       → 调用 bCalc 类的 Submit 方法
Calc/Show         → 调用 bCalc 类的 Show 方法
Message/ShowMsgbox → 调用 cMessage 类的 ShowMsgbox 方法
Message/ShowToast  → 调用 cMessage 类的 ShowToast 方法

---

典型通信示例

1. 用户登录

客户端请求:

{
    "action": "User/Login",
    "token": "",
    "data": {
        "username": "wangli",
        "password": "哈希后的密码"
    }
}

服务端响应 (成功):

{
    "action": "User/Info",
    "token": "550e8400-e29b-41d4-a716-446655440000",
    "data": {
        "ID": 2,
        "UserName": "wangli",
        "NickName": "王丽",
        "Password": "456"
    }
}

服务端响应 (失败):

{
    "action": "Message/ShowMsgbox",
    "token": "",
    "data": {
        "Content": "用户名不存在",
        "Title": "登录失败"
    }
}

2. 公告推送（服务端广播）

服务端向所有在线客户端广播:

{
    "action": "Notify/Show",
    "token": "",
    "data": {
        "Time": "2026年04月27日 10:30:00",
        "Title": "系统维护通知",
        "Content": "系统将于今晚22:00进行维护\r\n预计耗时2小时"
    }
}

3. 参数计算演示

客户端发送 50 个参数:

{
    "action": "Calc/Submit",
    "token": "xxx",
    "data": {
        "id": 12165,
        "age": 28,
        "grade": 85,
        "isActive": true,
        "birthDate": "1996-03-15",
        "name": "Alice Zhang",
        ...
    }
}

服务端修改后回传:

{
    "action": "Calc/Show",
    "token": "",
    "data": {
        "id": 1000,
        "memo": "特殊备注：测试专用账号\r\n这是服务端追加的备注内容",
        "remark": "你可以修改更多的字段",
        ...
    }
}

---

中间件与 Token 机制

Token 生命周期

1. 生成: 用户登录成功后，服务端调用 VBMAN.ToolsStr.GetGUID() 生成唯一 Token
2. 绑定: 通过 cWinsock.BindUser 将 Token 与当前连接实例、用户数据关联
3. 携带: 客户端在后续所有请求的 token 字段中携带该值
4. 验证: 中间件 mAuth 对比请求中的 Token 与连接实例绑定的 Token
5. 失效: 连接断开或账号在别处登录时，Token 自动失效

中间件白名单

以下路由不受中间件拦截，无需 Token 即可访问：

• User/Login — 登录接口
• Message/* — 消息提示类接口（服务端主动推送的消息）

白名单可在服务端 Form1.RegRouter 中通过 MiddleWaresWhiteList.Add 动态扩展。

---

服务端主动向客户端推送

除了响应客户端请求外，服务端还可以通过以下方式主动推送消息：

单播（SendTo）

Common.SendTo Inst, "Message/ShowToast", data

向指定客户端发送消息。

广播（SendToAll）

Common.SendToAll Insts.TcpServer, "Notify/Show", data

向所有在线客户端广播消息。

踢人下线

If TcpServer.ExistsUser(UserName) Then
    Common.SendMsgbox TcpServer.GetClientByUser(UserName), "账号在另外一个地方登录", "下线通知"
    TcpServer.CloseUser UserName
End If

---

错误处理

服务端业务代码执行出错时，错误信息会通过 Message/ShowMsgbox 自动回传给客户端：

On Error GoTo EH
' ... 业务逻辑 ...
Exit Sub
EH:
    Common.SendMsgbox Client, Err.Description, "内部错误"

中间件拦截时也会发送 MsgBox：

Common.SendMsgbox Client, "凭证验证失败", "中间件拦截"