数据包的基本信息

2019-11-04 16:15:23
先知
92
最后编辑:先知 于 2019-11-22 09:35:57

本文档主要向大家介绍喧喧里数据包的类型、数据包组、定义对象属性、数据包实例、数据包简写、传输类型简写、定义对象属性、定义对象变量。

数据包类型

在喧喧系统中共存在三种数据包:

  • 请求数据包:由客户端发送给 XXD 服务器,再由 XXD 服务器转发给后端服务器;
  • 响应数据包:后端服务器处理请求数据包后会向 XXD 服务器返回响应数据包,XXD 服务器处理之后会分发给客户端;
  • 推送数据包:由 XXD 服务器主动推送给客户端的数据包。

数据包组

有时后端会一次性返回一个以上数据包,这些数据包以数据包组的形式返回给 XXD 服务器,XXD 服务器分别处理后再转发给客户端。数据包组以 JSON 对象数组的形式存储,例如:

[
    {
        method: 'userLogin',
        data : userData,
        v: '2.4.0'
    }, {
        method: 'userGetlist',
        data: userDataList
    },
    // ... 其他数据包
]

数据包定义对象属性

数据包定义对象为类 JavaScript 纯对象,在传输的过程中会系列化为 JSON 字符串。通常一个数据包定义对象包含如下属性:

属性名称 类型 说明
method 字符串 必须项,操作方法名称,例如user_login表示登录方法
params 数组 可选项,调用操作方法时的参数列表,例如['xuanxuan', 'user', 'password', 'online']
v 字符串 可选项,表示发送该数据包方的版本号
lang 字符串 可选项,表示客户端发送到服务器端时所使用的语言,例如'zh-cn'、'zh-tw'或'en'
d 字符串 可选项,表示客户端类型,可选值包括'desktop'(桌面端,默认)和'mobile'(移动端)
userID 字符串或数字 只有当不是登录验证数据包时为可选项,其他情况为必须项,表示该数据包对应的用户 ID
rid 字符串 请求 ID,通常在发起请求时为数据包生成一个全局唯一的字符串,用于标识并跟踪此数据包,后端服务器处理一个请求数据包时如果发现有此属性应该在响应数据包中也返回此属性和对应的值

在响应数据包和推送数据包对象中还可能包含如下属性:

属性名称 类型 说明
result 字符串 通常当值为'success'时表示操作成功,值为'fail'时表示操作失败
message 字符串 通常当result属性值为'fail'时使用该属性返回操作失败的消息文本
data 任意类型 返回响应数据或推送数据
users 数组 由用户 ID 组成的数组,表示该数据包应该推送给哪些用户
pager 对象 表示当前数据列表的分页信息

注意:所有由后端服务器返回给 XXD 服务器的响应数据包中都必须包含此字段,否则 XXD 服务器会将响应数据包发送系统中所有在线客户端。当 XXD 服务器转发给客户端时会从响应数据包对象中去掉users属性。在后文中并不会单独注明此属性。

数据包实例

下面为用户登录验证时由 XXD 服务器发送给后端服务器的请求数据包:

{
    "method": "userLogin",
    "params": [
        "",
        "admin",
        "fcea920f7412b5da7be0cf42b8c93759",
        ""
    ],
    "v":"2.0.0"
}

当后端服务器处理完登录验证操作后会随 HTTP 请求向 XXD 服务器返回如下响应数据包:

{
    "method": "userLogin",
    "result": "success",
    "users": [1],
    "data": {
        "id": 1,
        "account": "admin",
        "realname": "admin",
        "avatar": "http://rz.io/data/upload/201704/f_4dedbfc726a12556306452adeb6e4a24.png",
        "role": "dev",
        "dept": 52,
        "status": "online",
        "admin": "super",
        "gender": "m",
        "email": "user@example.com",
        "mobile": "13311303627",
        "phone": "7353099",
        "site": "",
        "qq": "443221877",
        "signed": 1538958512
    },
    "v":"2.0.0"
}

数据包简写

为了简便描述指定方法的数据包对象,会在后文中简写为方法名(参数列表)形式,其中参数列表有时也会省略不写,例如登录请求数据包可以写为:

userLogin('', 'admin', 'fcea920f7412b5da7be0cf42b8c93759', '')

或者简写为:

userLogin

传输类型简写

为了简便描述数据包发送方和接收方会使用如下简写形式:

  • xxd → xxb:由 XXD 服务器向后端服务器发送请求数据包;
  • xxc → xxd → xxb:由客户端向 XXD 服务器发送请求数据包,XXD 会将请求数据包转发给后端服务器;
  • xxb → xxd → xxc:由后端服务器向 XXD 服务器发送响应数据包,XXD 服务器会将响应数据包转发给客户端;
  • xxd → xxc:由 XXD 服务器向客户端发送推送数据包;
  • xxc → xxd:由客户端向 XXD 服务器发送请求数据包。

数据包定义对象格式

数据包定义对象为类 JavaScript 纯对象,在后文中会直接使用 JavaScript 对象来定义数据包。例如一个请求数据包的属性和结构可以表示为:

{
    method: 'chatGetList'
}

数据包定义对象变量

在使用数据包定义对象中会用到一些变量来代表实际使用过程中的数据。下面为一些常用变量名称对应的含义:

userData

变量userData表示一个用户数据对象,该对象包含如下属性:

属性名称 类型 可选性 说明
id 数字或字符串 必须 用户数据在数据库中存档的 ID,通常为数据包主键字段
account 字符串 必须 用户名
realname 字符串 可选 用户真实姓名
dept 数字 可选 用户部门编号
role 字符串 可选 角色名称
admin 字符串 可选 当前用户如果是系统管理员,则记录管理员类型,默认使用特殊值'super'表示超级管理员,其他值表示普通用户
avatar 字符串 可选 用户头像图片地址
gender 字符串 可选 存储用户性别信息,可选值包括'f'(女性)、'm'(男性)和'u'(未知)
email 字符串 可选 存储用户电子邮件地址
mobile 字符串 可选 存储用户移动电话号码
phone 字符串 可选 存储用户固定电话号码
status 字符串 可选 存储用户当前状态,可选值包括'online'(在线)、'away'(离开)、'busy'(忙碌)和'offline'(离线)
deleted 数字 可选 当值为1或true时标记当前用户已经被从系统标记为已删除

下面为一个用户对象示例:

{
    id: '12',
    account: 'admin',
    realname: '张三',
    dept: 34,
    role: 'manager',
    admin: 'no',
    avatar: 'http://example.com/user/avatar/admin.png',
    gender: 'f',
    email: 'admin@example.com',
    mobile: '+8612209098888',
    phone: '',
    status: 'online',
    deleted: 0
}

chatData

变量chatData表示一个系统中的会话数据对象,该对象包含如下属性:

属性名称 类型 可选性 说明
id 数字或字符串 必须 作为表主键,数据库存储 ID,通常为必须为大于 0 的整数,在数据表插入字段时自动生成递增的值
gid 字符串 必须 用于识别该会话全局唯一字符串,通常会在客户端创建此字段并提交到服务器保存
name 字符串 可选 会话显示名称,如果是一对一会话则无需提供名称
type 字符串 可选 会话类型,可选值包括:'system'(系统会话),'one2one'(一对一会话),'group'(多人讨论组),以及系统自定义的类型,例如'project'(禅道项目),'product'(禅道产品)等
admins 字符串 可选 会话管理员用户名列表,使用用户名,多个管理员用户名使用英文逗号分隔
committers 字符串 可选 会话允许用户发言(在会话中发布消息)的用户 ID 列表,多个用户 ID 使用英文逗号分隔,其中特殊值'$ADMINS'表示仅允许管理员发言,如果留空或者使用特殊值'$ALL'则表示允许会话中所有人发言
subject 数字 可选 主题会话关联的主题 ID,仅当会话类型(type)为自定义类型时可用(例如'project'(禅道项目),'product'(禅道产品)等)
public 布尔值 可选 是否为公开讨论组
createdBy 字符串 必须 创建此会话用户账号,存储在用户表(sys_user)中对应条目的account字段的值
createdDate 时间戳 必须 创建此会话时服务器上的时间(可以精确到秒或毫秒)
editedBy 字符串 可选 上次编辑此会话的用户账号
editedDate 时间戳 可选 上次编辑此会话时服务器的时间
lastActiveTime 时间戳 可选 会话最后一次发送消息时服务器的时间(可以精确到秒或毫秒)
dismissDate 时间戳 可选 会话被管理员解散时服务器的时间(可以精确到秒或毫秒)
members 数字数组 必须 使用数组包含此会话所有成员 ID
star 布尔值 可选 如果为true,表示此用户已经将会话设置为已收藏
hide bool 可选 用户是否将该会话标记为已存档(隐藏)
mute bool 可选 用户是否将该会话标记设置为通知免打扰
frozen bool 可选 用户是否将该会话暂时从最近会话列表移除

下面为一个会话对象数据:

{
    id: 34,
    gid: '60&74',
    name: '',
    type: 'one2one',
    admins: '',
    committers: '',
    subject: 0,
    public: 0,
    createdBy: 'sunhao',
    createdDate: 1453689245,
    editedBy: '',
    editedDate: 0,
    lastActiveTime: 1516612779,
    dismissDate: 0,
    star: 0,
    hide: 0,
    mute: 0,
    frozen: 0,
    category: '',
    members: [60,74]
}

sendMessage

变量sendMessage表示一个等待发送到服务器的会话消息对象,该对象包含如下属性:

属性名称 类型 可选性 说明
gid 字符串 必须 用于识别该会话消息全局唯一字符串,通常会在客户端创建此字段并提交到服务器保存
cgid 字符串 必须 此消息所属于的会话,存储在会话表(im_chat)中对应条目的gid字段的值,会话根据此值来查询会话中包含的消息
user 数字 可选 此消息发送用户的 ID,广播类(type字段为'broadcast')的消息没有此值
type 字符串 可选 消息的类型,可选值包括:'normal'(默认),'broadcast'(广播)
content 字符串 必须 消息的内容,如果消息内容类型不是纯文本,则此值通常为 JSON 对象字符串
contentType 字符串 必须 消息内容的类型,可选值包括:'text'(默认,支持 Markdown 的文本内容),'plain'(纯文本),'emoticon'(表情),'image'(图片),'file'(文件),也可用为自己自定义的类型名称
data 字符串 可选 消息的额外数据信息,例如点赞的用户信息,此值通常为 JSON 对象字符串

下面为一个纯文本消息对象示例:

{
    cgid: '11&7',
    content: '纯文本消息内容。',
    contentType: 'plain',
    gid: 'f62b4a20-5ae2-4c42-a5ae-b4fe7959721e',
    type: 'normal',
    user: 11
}

提示:客户端在向服务器通过此数据包发送消息时,确保为新的消息对象生成了全局唯一字符串(RFC4122)作为gid属性。如果你使用 JavaScript 可以使用 uuid 模块来实现。

messageData

变量messageData表示一个会话消息对象(已确定发送成功并且经存储到服务器),该对象包含如下属性:

属性名称 类型 可选性 说明
id 数字或字符串 必须 消息数据在服务器上存储的 ID,通常为数据库主键,会在数据库存储时自动创建
date 时间戳 必须 消息发送的时间戳(以首次在服务器上存储的时间为准,时间戳支持精确到毫秒或秒)
gid 字符串 必须 用于识别该会话消息全局唯一字符串,通常会在客户端创建此字段并提交到服务器保存
cgid 字符串 必须 此消息所属于的会话,存储在会话表(im_chat)中对应条目的gid字段的值,会话根据此值来查询会话中包含的消息
user 数字 可选 此消息发送用户的 ID,广播类(type字段为'broadcast')的消息没有此值
type 字符串 可选 消息的类型,可选值包括:'normal'(默认),'broadcast'(广播)
content 字符串 必须 消息的内容,如果消息内容类型不是纯文本,则此值通常为 JSON 对象字符串
contentType 字符串 必须 消息内容的类型,可选值包括:'text'(默认,支持 Markdown 的文本内容),'plain'(纯文本),'emoticon'(表情),'image'(图片),'file'(文件),也可用为自己自定义的类型名称
data 字符串 可选 消息的额外数据信息,例如点赞的用户信息,此值通常为 JSON 对象字符串

下面为一个纯文本消息对象示例:

{
    id: '1121',
    date: 1543481423,
    cgid: '11&7',
    content: '纯文本消息内容。',
    contentType: 'plain',
    gid: 'f62b4a20-5ae2-4c42-a5ae-b4fe7959721e',
    type: 'normal',
    user: 11
}

pagerData

变量pagerData表示一个分页信息对象,该对象拥有如下属性:

属性名称 类型 说明
recPerPage 整数 表示每页最多记录数目
pageID 整数 表示当前记录所属页码
recTotal 整数 系统中记录总数目
continued 布尔值 如果为true表示客户端是否是接上次请求持续获取其他页面的消息记录数目

notifitionData

变量notifitionData表示一个通知消息对象,该对象拥有如下属性:

属性名称 类型 可选性 说明
gid 字符串 必须 用于识别该通知消息全局唯一字符串
title 字符串 必须 通知消息的标题
subtitle 字符串 可选 通知消息的副标题
content 字符串 可选 通知消息的内容文本
contentType 字符串 必须 可选值包括:'plain'表示纯文本,'text'表示 Markdown 格式的文本
url 字符串 可选 该通知消息所指向的网页链接
actions 对象数组 可选 使用 操作对象数组表示该通知支持的操作
sender 对象 可选 通知的 发送方信息对象

通知的操作对象包含如下属性:

属性名称 类型 可选性 说明
label 字符串 必须 操作按钮上显示的文本
icon 字符串 可选 操作按钮上显示的图标
url 字符串 必须 点击此操作按钮时要打开的页面链接
type 字符串 可选 操作按钮类型,影响操作按钮外观,可选值包括'primary'、'success'、'danger'、'warning'、'info'、'important'、'special'

发送方信息对象包容如下属性:

属性名称 类型 可选性 说明
id 字符串或数字 必须 标识发送方唯一身份的字符串或数字
name 字符串 可选 发送方在界面上显示的名称
avatar 字符串 必须 发送方头像图片链接地址

变量数组

使用如下格式来表示一个变量数组:

[变量名称]
例如[messageData]来表示会话消息对象数组。
发表评论
评论通过审核后显示。