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

一、数据包类型

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

• 请求数据包：由客户端XXC发送给消息中转XXD 服务器，再由 消息中转 XXD 服务器转发给后端处理服务器XXB；
• 响应数据包：后端处理服务器XXB处理请求数据包后会向 消息中转XXD 服务器返回响应数据包，消息中转XXD 服务器处理之后会分发给客户端XXC；
• 推送数据包：由 消息中转XXD 服务器主动推送给客户端XXC的数据包。

二、数据包组

有时后端会一次性返回一个以上数据包，这些数据包以数据包组的形式返回给 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]来表示会话消息对象数组。