API說(shuō)明

名詞約定

client：喧喧客戶端xxd：GO 聊天服務(wù)器xxb：后臺(tái)然之服務(wù)器

1.API數(shù)據(jù)格式

常見的請(qǐng)求對(duì)象格式

{
  userID, // 用戶id，xxd → xxb 非登錄時(shí)必須
  module, // 模塊名稱,必須
  method, // 方法名稱,必須
  test,   // 可選參數(shù)，bool,默認(rèn)為false。
  params, // 參數(shù)對(duì)象,可選
  data    // 請(qǐng)求數(shù)據(jù),可選,與params配合使用,通常data傳輸是對(duì)象
}

常見的響應(yīng)數(shù)據(jù)格式

{
  module,  // 模塊名稱,必須
  method,  // 方法名稱,必須
  users[], // 該數(shù)據(jù)響應(yīng)給哪些用戶，users為空表示所有在線用戶
  params,  // 參數(shù)對(duì)象,可選
  result:, // 響應(yīng)狀態(tài),可為"success"（成功）, "fail"(失敗), "denied"(拒絕,需要登錄),
  message:,// 消息,可選,當(dāng)result不為success時(shí),使用此字段來(lái)解釋原因
  data     // 數(shù)據(jù) 
}

2.xxd啟動(dòng)

xxd啟動(dòng)時(shí)會(huì)向xxb發(fā)送一條請(qǐng)求，xxb收到請(qǐng)求將所有用戶狀態(tài)重置為offline。

請(qǐng)求

方向：xxd → xxb

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

響應(yīng)

方向：xxb -→ xxd

HTTP Status Code

登錄

請(qǐng)求

方向：client → xxd

{
  module: "chat",
  method: "login",
  params: 
  [
    serverName,// 多然之時(shí)客戶端登錄的服務(wù)器名稱
    account,   // 用戶名
    password,  // 加密后的密碼
    status     // 登錄后設(shè)置的狀態(tài),包括online,away,busy
  ]
 }

方向：xxd → xxb

xxd服務(wù)器根據(jù)module、method和serverName把請(qǐng)求發(fā)送給指定的xxb

響應(yīng)

方向：xxb → xxd

{
  module: "chat",
  method: "login",
  result,
  users[]，
  data: 
  {          // 當(dāng)前登錄的用戶數(shù)據(jù)
    id,      // ID
    account, // 用戶名
    realname,// 真實(shí)姓名
    avatar,  // 頭像URL
    role,    // 角色
    dept,    // 部門ID
    status,  // 當(dāng)前狀態(tài)
    admin,   // 是否超級(jí)管理員，super 超級(jí)管理員 | no 普通用戶
    gender,  // 性別，u 未知 | f 女 | m 男
    email,   // 郵箱
    mobile,  // 手機(jī)
    site,    // 網(wǎng)站
    phone,   // 電話
    ranzhiUrl// 當(dāng)前用戶所在的然之站點(diǎn)地址（可選，1.3新增）
  }
}

登錄成功以后xxd主動(dòng)從xxb服務(wù)器獲取用戶列表、用戶所參與的會(huì)話信息和用戶的離線消息發(fā)送給當(dāng)前客戶端。最后把xxb服務(wù)器響應(yīng)給xxd服務(wù)器的登錄信息去掉users字段后，發(fā)送給此會(huì)話包含的所有在線用戶。

登出

請(qǐng)求

方向：client → xxd

{
  userID, //登出用戶的id號(hào)
  module: "chat",
  method: "logout",
}

方向：xxd → xxb

xxd把client發(fā)送的數(shù)據(jù)轉(zhuǎn)發(fā)給xxb。

響應(yīng)

方向 xxb → xxd

{
  module: "chat",
  method: "logout",
  result,
  users[],
  data:
  {          // 當(dāng)前登錄的用戶數(shù)據(jù)
    id,      // ID
    account, // 用戶名
    realname,// 真實(shí)姓名
    avatar,  // 頭像URL
    role,    // 角色
    dept,    // 部門ID
    status,  // 當(dāng)前狀態(tài)
    admin,   // 是否超級(jí)管理員，super 超級(jí)管理員 | no 普通用戶
    gender,  // 性別，u 未知 | f 女 | m 男
    email,   // 郵箱
    mobile,  // 手機(jī)
    site,    // 網(wǎng)站
    phone    // 電話
  }
}

方向：xxd → client

把xxb服務(wù)器響應(yīng)給xxd服務(wù)器的登出信息去掉users字段后，發(fā)送給此會(huì)話包含的所有在線用戶。

3.重復(fù)登錄

當(dāng)同一用戶重復(fù)登錄時(shí),系統(tǒng)會(huì)向前一個(gè)登錄的用戶推送一條特殊的消息,客戶端接收到該消息后應(yīng)該將用戶登出，并關(guān)閉相關(guān)的網(wǎng)絡(luò)連接。該消息不需要響應(yīng)或返回結(jié)果。

方向：xxd → client

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

4.獲取所有用戶列表

請(qǐng)求

方向： client → xxd

{
  userID, //用戶的id號(hào)
  module: "chat",
  method: "userGetlist",
  params:
  [
    idList, // 要獲取的用戶信息id編號(hào)數(shù)組，可選，如果留空則獲取所有用戶（1.3新增）
  ]
}

方向： xxd → xxb

xxd把client發(fā)送的數(shù)據(jù)轉(zhuǎn)發(fā)給xxb。

響應(yīng)

方向：xxb → xxd

{
  module: "chat",
  method: "userGetlist",
  result,
  users[],
  data:
  [         // 所有用戶狀態(tài)數(shù)組
    {       // 其中一個(gè)用戶數(shù)據(jù)
      id,     // ID
      account,  // 用戶名
      realname, // 真實(shí)姓名
      avatar,   // 頭像URL
      role,   // 角色
      dept,   // 部門ID
      status,   // 當(dāng)前狀態(tài)
      admin,  // 是否超級(jí)管理員，super 超級(jí)管理員 | no 普通用戶
      gender,   // 性別，u 未知 | f 女 | m 男
      email,  // 郵箱
      mobile,   // 手機(jī)
      site,   // 網(wǎng)站
      phone   // 電話
    },
    // 更多用戶數(shù)據(jù)...
  ],
  roles: {
    "dev": "開發(fā)者",
    "productManager": "產(chǎn)品經(jīng)理"   
    // 更多角色表數(shù)據(jù)，格式為鍵名為角色代號(hào)，鍵值為角色顯示名稱
  },
  depts: [
    {id: 2343, name: "研發(fā)部", parent: 0},
    {id: 2344, name: "項(xiàng)目部", parent: 2343},
    // 更多部門表數(shù)據(jù)，每個(gè)對(duì)象表示一個(gè)部門信息，parent 為上級(jí)部門id，如果沒(méi)有上級(jí)部門parent值為0
  ]
}

方向：xxd → client

把xxb服務(wù)器響應(yīng)給xxd服務(wù)器的信息去掉users字段后，發(fā)送給此會(huì)話包含的所有在線用戶。

5.獲取當(dāng)前登錄用戶所有會(huì)話數(shù)據(jù)

請(qǐng)求

方向：client → xxd

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

方向： xxd → xxb

xxd把client發(fā)送的數(shù)據(jù)轉(zhuǎn)發(fā)給xxb。

響應(yīng)

方向：xxb → xxd

{
  module: "chat",
  method: "getList",
  result,
  users[],
  data:
  [             // 所有會(huì)話信息數(shù)組
    {           // 其中一個(gè)會(huì)話信息
      id,       // 會(huì)話在服務(wù)器數(shù)據(jù)保存的id
      gid,      // 會(huì)話的全局id,
      name,       // 會(huì)話的名稱
      type,       // 會(huì)話的類型
      admins,     // 會(huì)話允許發(fā)言的用戶列表
      subject,    // 主題會(huì)話的關(guān)聯(lián)主題ID
      public,     // 是否公共會(huì)話
      createdBy,    // 創(chuàng)建者用戶名
      createdDate,  // 創(chuàng)建時(shí)間
      editedBy,     // 編輯者用戶名
      editedDate,   // 編輯時(shí)間
      lastActiveTime, // 會(huì)話最后一次發(fā)送消息的時(shí)間
      star,       // 當(dāng)前登錄用戶是否收藏此會(huì)話
      hide,       // 當(dāng)前登錄用戶是否隱藏此會(huì)話
      members: 
      [         // 當(dāng)前會(huì)話中包含的所有用戶信息,只需要包含id即可
        {
          id,   //用戶id
        },
        // 更多用戶...
      ],
    },
    // 更多會(huì)話數(shù)據(jù)...
  ]
}

方向：xxd → client

把xxb服務(wù)器響應(yīng)給xxd服務(wù)器的信息去掉users字段后，發(fā)送給此會(huì)話包含的所有在線用戶。

6.獲取當(dāng)前登錄用戶所有離線消息

請(qǐng)求

方向： xxd → xxb

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

響應(yīng)

方向：xxb → xxd

{
  module: "chat",
  method: "message",
  result,
  users[],
  data:  // 一個(gè)包含一條或多條離線消息的數(shù)組
  [
    {        // 其中一條離線消息
      id,      // 消息在服務(wù)器保存的id
      gid,     // 此消息的gid
      cgid,    // 此消息關(guān)聯(lián)的會(huì)話的gid
      user,    // 消息發(fā)送的用戶名
      date,    // 消息發(fā)送的時(shí)間
      type,    // 消息的類型
      contentType, // 消息內(nèi)容的類型
      content,   // 消息內(nèi)容
    },
    // 更多離線消息
  ]
}

方向：xxd → client

把xxb服務(wù)器響應(yīng)給xxd服務(wù)器的信息去掉users字段后，發(fā)送給當(dāng)前登錄用戶。

7.更改當(dāng)前登錄用戶的信息

請(qǐng)求

方向：client → xxd

{
  userID,
  module: "chat",
  method: "userChange",
  params:
  [         // 更改后的用戶    
    user:     // 一個(gè)用戶對(duì)象
    {
      id,     // ID
      account,  // 用戶名
      realname, // 真實(shí)姓名
      avatar,   // 頭像URL
      role,   // 角色
      dept,   // 部門ID
      status,   // 要設(shè)置的新狀態(tài),包括online, away, busy
      admin,  // 是否超級(jí)管理員，super 超級(jí)管理員 | no 普通用戶
      gender,   // 性別，u 未知 | f 女 | m 男
      email,  // 郵箱
      mobile,   // 手機(jī)
      site,   // 網(wǎng)站
      phone   // 電話
    }
  ]
}

方向： xxd → xxb

xxd把client發(fā)送的數(shù)據(jù)轉(zhuǎn)發(fā)給xxb。

響應(yīng)

方向：xxb → xxd

{
  module: "chat",
  method: "userChange",
  result,
  users[],
  data: 
  {       //當(dāng)前登錄用戶數(shù)據(jù)   
    id,     // ID
    account,  // 用戶名
    realname, // 真實(shí)姓名
    avatar,   // 頭像URL
    role,   // 角色
    dept,   // 部門ID
    status,   // 狀態(tài)
    admin,  // 是否超級(jí)管理員，super 超級(jí)管理員 | no 普通用戶
    gender,   // 性別，u 未知 | f 女 | m 男
    email,  // 郵箱
    mobile,   // 手機(jī)
    site,   // 網(wǎng)站
    phone   // 電話
  }
}

方向：xxd → client

把xxb服務(wù)器響應(yīng)給xxd服務(wù)器的信息去掉users字段后，發(fā)送給此會(huì)話包含的所有在線用戶。

8.創(chuàng)建聊天會(huì)話

請(qǐng)求

方向：client → xxd

{
  userID,
  module: "chat",
  method: "create",
  params:
  [
    gid,   // 會(huì)話的全局id,
    name,  // 會(huì)話的名稱
    type,  // 會(huì)話的類型
    members: [{id}, {id}...] // 會(huì)話的成員列表 
    subject, //可選,主題會(huì)話的關(guān)聯(lián)主題ID,默認(rèn)為0
    pulic  //可選,是否公共會(huì)話,默認(rèn)為false
  ]
}

方向： xxd → xxb

xxd把client發(fā)送的數(shù)據(jù)轉(zhuǎn)發(fā)給xxb。

響應(yīng)

服務(wù)器在創(chuàng)建會(huì)話時(shí)應(yīng)該先檢查gid是否已經(jīng)存在，如果存在則直接為當(dāng)前登錄用戶返回已存在的會(huì)話信息。

方向：xxb → xxd

{
  module: "chat",
  method: "create",
  result,
  users[],
  data:         
  {           // 新創(chuàng)建的會(huì)話完整信息
    id,       // 會(huì)話在服務(wù)器數(shù)據(jù)保存的id
    gid,      // 會(huì)話的全局id,
    name,       // 會(huì)話的名稱
    type,       // 會(huì)話的類型
    admins,     // 會(huì)話允許發(fā)言的用戶列表
    subject,    // 主題會(huì)話的關(guān)聯(lián)主題ID
    public,     // 是否公共會(huì)話
    createdBy,    // 創(chuàng)建者用戶名
    createdDate,  // 創(chuàng)建時(shí)間
    editedBy,     // 編輯者用戶名
    editedDate,   // 編輯時(shí)間
    lastActiveTime, // 會(huì)話最后一次發(fā)送消息的時(shí)間
    members: [{id}, {id}...] // 會(huì)話的成員列表 
  }
}

方向：xxd → client

把xxb服務(wù)器響應(yīng)給xxd服務(wù)器的信息去掉users字段后，發(fā)送給此會(huì)話包含的所有在線用戶。

9.加入或退出聊天會(huì)話

用戶可以加入類型為group并且公共的會(huì)話；用戶可以退出類型為group的會(huì)話。

請(qǐng)求

方向：client → xxd

{
  userID,
  module: "chat",
  method: "joinchat",
  params: 
  [
    gid, // 要加入或退出的會(huì)話id
    join // 可選, true加入會(huì)話, false退出會(huì)話, 默認(rèn)為true
  ]
}

方向： xxd → xxb

xxd把client發(fā)送的數(shù)據(jù)轉(zhuǎn)發(fā)給xxb。

響應(yīng)

方向：xxb → xxd

{
  module: "chat",
  method: "joinchat",
  result,
  users[],
  data:
  {           // 會(huì)話的完整信息
    id,       // 會(huì)話在服務(wù)器數(shù)據(jù)保存的id
    gid,      // 會(huì)話的全局id,
    name,       // 會(huì)話的名稱
    type,       // 會(huì)話的類型
    admins,     // 會(huì)話允許發(fā)言的用戶列表
    subject,    // 主題會(huì)話的關(guān)聯(lián)主題ID
    public,     // 是否公共會(huì)話
    createdBy,    // 創(chuàng)建者用戶名
    createdDate,  // 創(chuàng)建時(shí)間
    editedBy,     // 編輯者用戶名
    editedDate,   // 編輯時(shí)間
    lastActiveTime, // 會(huì)話最后一次發(fā)送消息的時(shí)間
    members: [{id}, {id}...] // 會(huì)話的成員列表 
  }
}

方向：xxd → client

把xxb服務(wù)器響應(yīng)給xxd服務(wù)器的信息去掉users字段后，發(fā)送給此會(huì)話包含的所有在線用戶（包括退出會(huì)話的當(dāng)前用戶）。

10.更改會(huì)話名稱

用戶可以更改類型為group的會(huì)話的名稱。

請(qǐng)求

方向：client → xxd

{
  userID,
  module: "chat",
  method: "changeName",
  params:
  [
    gid, // 要更改的會(huì)話id
    name // 新的名稱
  ]
}

方向： xxd → xxb

xxd把client發(fā)送的數(shù)據(jù)轉(zhuǎn)發(fā)給xxb。

響應(yīng)

方向：xxb → xxd

{
  module: "chat",