API说明

名词约定

client：喧喧客户端xxd：GO 聊天服务器xxb：后台然之服务器

1.API数据格式

常见的请求对象格式

{
  userID, // 用户id，xxd → xxb 非登录时必须
  module, // 模块名称,必须
  method, // 方法名称,必须
  test,   // 可选参数，bool,默认为false。
  params, // 参数对象,可选
  data    // 请求数据,可选,与params配合使用,通常data传输是对象
}

常见的响应数据格式

{
  module,  // 模块名称,必须
  method,  // 方法名称,必须
  users[], // 该数据响应给哪些用户，users为空表示所有在线用户
  params,  // 参数对象,可选
  result:, // 响应状态,可为"success"（成功）, "fail"(失败), "denied"(拒绝,需要登录),
  message:,// 消息,可选,当result不为success时,使用此字段来解释原因
  data     // 数据 
}

2.xxd启动

xxd启动时会向xxb发送一条请求，xxb收到请求将所有用户状态重置为offline。

请求

方向：xxd → xxb

{
  module: "chat",
  method: "serverStart"
}

响应

方向：xxb -→ xxd

HTTP Status Code

登录

请求

方向：client → xxd

{
  module: "chat",
  method: "login",
  params: 
  [
    serverName,// 多然之时客户端登录的服务器名称
    account,   // 用户名
    password,  // 加密后的密码
    status     // 登录后设置的状态,包括online,away,busy
  ]
 }

方向：xxd → xxb

xxd服务器根据module、method和serverName把请求发送给指定的xxb

响应

方向：xxb → xxd

{
  module: "chat",
  method: "login",
  result,
  users[]，
  data: 
  {          // 当前登录的用户数据
    id,      // ID
    account, // 用户名
    realname,// 真实姓名
    avatar,  // 头像URL
    role,    // 角色
    dept,    // 部门ID
    status,  // 当前状态
    admin,   // 是否超级管理员，super 超级管理员 | no 普通用户
    gender,  // 性别，u 未知 | f 女 | m 男
    email,   // 邮箱
    mobile,  // 手机
    site,    // 网站
    phone,   // 电话
    ranzhiUrl// 当前用户所在的然之站点地址（可选，1.3新增）
  }
}

登录成功以后xxd主动从xxb服务器获取用户列表、用户所参与的会话信息和用户的离线消息发送给当前客户端。最后把xxb服务器响应给xxd服务器的登录信息去掉users字段后，发送给此会话包含的所有在线用户。

登出

请求

方向：client → xxd

{
  userID, //登出用户的id号
  module: "chat",
  method: "logout",
}

方向：xxd → xxb

xxd把client发送的数据转发给xxb。

响应

方向 xxb → xxd

{
  module: "chat",
  method: "logout",
  result,
  users[],
  data:
  {          // 当前登录的用户数据
    id,      // ID
    account, // 用户名
    realname,// 真实姓名
    avatar,  // 头像URL
    role,    // 角色
    dept,    // 部门ID
    status,  // 当前状态
    admin,   // 是否超级管理员，super 超级管理员 | no 普通用户
    gender,  // 性别，u 未知 | f 女 | m 男
    email,   // 邮箱
    mobile,  // 手机
    site,    // 网站
    phone    // 电话
  }
}

方向：xxd → client

把xxb服务器响应给xxd服务器的登出信息去掉users字段后，发送给此会话包含的所有在线用户。

3.重复登录

当同一用户重复登录时,系统会向前一个登录的用户推送一条特殊的消息,客户端接收到该消息后应该将用户登出，并关闭相关的网络连接。该消息不需要响应或返回结果。

方向：xxd → client

{
  module:  "chat",
  method:  "kickoff",
  message: "This account logined in another place."
}

4.获取所有用户列表

请求

方向： client → xxd

{
  userID, //用户的id号
  module: "chat",
  method: "userGetlist",
  params:
  [
    idList, // 要获取的用户信息id编号数组，可选，如果留空则获取所有用户（1.3新增）
  ]
}

方向： xxd → xxb

xxd把client发送的数据转发给xxb。

响应

方向：xxb → xxd

{
  module: "chat",
  method: "userGetlist",
  result,
  users[],
  data:
  [         // 所有用户状态数组
    {       // 其中一个用户数据
      id,     // ID
      account,  // 用户名
      realname, // 真实姓名
      avatar,   // 头像URL
      role,   // 角色
      dept,   // 部门ID
      status,   // 当前状态
      admin,  // 是否超级管理员，super 超级管理员 | no 普通用户
      gender,   // 性别，u 未知 | f 女 | m 男
      email,  // 邮箱
      mobile,   // 手机
      site,   // 网站
      phone   // 电话
    },
    // 更多用户数据...
  ],
  roles: {
    "dev": "开发者",
    "productManager": "产品经理"   
    // 更多角色表数据，格式为键名为角色代号，键值为角色显示名称
  },
  depts: [
    {id: 2343, name: "研发部", parent: 0},
    {id: 2344, name: "项目部", parent: 2343},
    // 更多部门表数据，每个对象表示一个部门信息，parent 为上级部门id，如果没有上级部门parent值为0
  ]
}

方向：xxd → client

把xxb服务器响应给xxd服务器的信息去掉users字段后，发送给此会话包含的所有在线用户。

5.获取当前登录用户所有会话数据

请求

方向：client → xxd

{
  userID,
  module: "chat",
  method: "getList",
}

方向： xxd → xxb

xxd把client发送的数据转发给xxb。

响应

方向：xxb → xxd

{
  module: "chat",
  method: "getList",
  result,
  users[],
  data:
  [             // 所有会话信息数组
    {           // 其中一个会话信息
      id,       // 会话在服务器数据保存的id
      gid,      // 会话的全局id,
      name,       // 会话的名称
      type,       // 会话的类型
      admins,     // 会话允许发言的用户列表
      subject,    // 主题会话的关联主题ID
      public,     // 是否公共会话
      createdBy,    // 创建者用户名
      createdDate,  // 创建时间
      editedBy,     // 编辑者用户名
      editedDate,   // 编辑时间
      lastActiveTime, // 会话最后一次发送消息的时间
      star,       // 当前登录用户是否收藏此会话
      hide,       // 当前登录用户是否隐藏此会话
      members: 
      [         // 当前会话中包含的所有用户信息,只需要包含id即可
        {
          id,   //用户id
        },
        // 更多用户...
      ],
    },
    // 更多会话数据...
  ]
}

方向：xxd → client

把xxb服务器响应给xxd服务器的信息去掉users字段后，发送给此会话包含的所有在线用户。

6.获取当前登录用户所有离线消息

请求

方向： xxd → xxb

{
  userID,
  module: "chat",
  method: "getOfflineMessages",
}

响应

方向：xxb → xxd

{
  module: "chat",
  method: "message",
  result,
  users[],
  data:  // 一个包含一条或多条离线消息的数组
  [
    {        // 其中一条离线消息
      id,      // 消息在服务器保存的id
      gid,     // 此消息的gid
      cgid,    // 此消息关联的会话的gid
      user,    // 消息发送的用户名
      date,    // 消息发送的时间
      type,    // 消息的类型
      contentType, // 消息内容的类型
      content,   // 消息内容
    },
    // 更多离线消息
  ]
}

方向：xxd → client

把xxb服务器响应给xxd服务器的信息去掉users字段后，发送给当前登录用户。

7.更改当前登录用户的信息

请求

方向：client → xxd

{
  userID,
  module: "chat",
  method: "userChange",
  params:
  [         // 更改后的用户    
    user:     // 一个用户对象
    {
      id,     // ID
      account,  // 用户名
      realname, // 真实姓名
      avatar,   // 头像URL
      role,   // 角色
      dept,   // 部门ID
      status,   // 要设置的新状态,包括online, away, busy
      admin,  // 是否超级管理员，super 超级管理员 | no 普通用户
      gender,   // 性别，u 未知 | f 女 | m 男
      email,  // 邮箱
      mobile,   // 手机
      site,   // 网站
      phone   // 电话
    }
  ]
}

方向： xxd → xxb

xxd把client发送的数据转发给xxb。

响应

方向：xxb → xxd

{
  module: "chat",
  method: "userChange",
  result,
  users[],
  data: 
  {       //当前登录用户数据   
    id,     // ID
    account,  // 用户名
    realname, // 真实姓名
    avatar,   // 头像URL
    role,   // 角色
    dept,   // 部门ID
    status,   // 状态
    admin,  // 是否超级管理员，super 超级管理员 | no 普通用户
    gender,   // 性别，u 未知 | f 女 | m 男
    email,  // 邮箱
    mobile,   // 手机
    site,   // 网站
    phone   // 电话
  }
}

方向：xxd → client

把xxb服务器响应给xxd服务器的信息去掉users字段后，发送给此会话包含的所有在线用户。

8.创建聊天会话

请求

方向：client → xxd

{
  userID,
  module: "chat",
  method: "create",
  params:
  [
    gid,   // 会话的全局id,
    name,  // 会话的名称
    type,  // 会话的类型
    members: [{id}, {id}...] // 会话的成员列表 
    subject, //可选,主题会话的关联主题ID,默认为0
    pulic  //可选,是否公共会话,默认为false
  ]
}

方向： xxd → xxb

xxd把client发送的数据转发给xxb。

响应

服务器在创建会话时应该先检查gid是否已经存在，如果存在则直接为当前登录用户返回已存在的会话信息。

方向：xxb → xxd

{
  module: "chat",
  method: "create",
  result,
  users[],
  data:         
  {           // 新创建的会话完整信息
    id,       // 会话在服务器数据保存的id
    gid,      // 会话的全局id,
    name,       // 会话的名称
    type,       // 会话的类型
    admins,     // 会话允许发言的用户列表
    subject,    // 主题会话的关联主题ID
    public,     // 是否公共会话
    createdBy,    // 创建者用户名
    createdDate,  // 创建时间
    editedBy,     // 编辑者用户名
    editedDate,   // 编辑时间
    lastActiveTime, // 会话最后一次发送消息的时间
    members: [{id}, {id}...] // 会话的成员列表 
  }
}

方向：xxd → client

把xxb服务器响应给xxd服务器的信息去掉users字段后，发送给此会话包含的所有在线用户。

9.加入或退出聊天会话

用户可以加入类型为group并且公共的会话；用户可以退出类型为group的会话。

请求

方向：client → xxd

{
  userID,
  module: "chat",
  method: "joinchat",
  params: 
  [
    gid, // 要加入或退出的会话id
    join // 可选, true加入会话, false退出会话, 默认为true
  ]
}

方向： xxd → xxb

xxd把client发送的数据转发给xxb。

响应

方向：xxb → xxd

{
  module: "chat",
  method: "joinchat",
  result,
  users[],
  data:
  {           // 会话的完整信息
    id,       // 会话在服务器数据保存的id
    gid,      // 会话的全局id,
    name,       // 会话的名称
    type,       // 会话的类型
    admins,     // 会话允许发言的用户列表
    subject,    // 主题会话的关联主题ID
    public,     // 是否公共会话
    createdBy,    // 创建者用户名
    createdDate,  // 创建时间
    editedBy,     // 编辑者用户名
    editedDate,   // 编辑时间
    lastActiveTime, // 会话最后一次发送消息的时间
    members: [{id}, {id}...] // 会话的成员列表 
  }
}

方向：xxd → client

把xxb服务器响应给xxd服务器的信息去掉users字段后，发送给此会话包含的所有在线用户（包括退出会话的当前用户）。

10.更改会话名称

用户可以更改类型为group的会话的名称。

请求

方向：client → xxd

{
  userID,
  module: "chat",
  method: "changeName",
  params:
  [
    gid, // 要更改的会话id
    name // 新的名称
  ]
}

方向： xxd → xxb

xxd把client发送的数据转发给xxb。

响应

方向：xxb → xxd

{
  module: "chat",