3.接口文档

接口文档

  1. HTTP部分
  2. Socket自定义协议

Http部分

（一般都是这样）

全局规范

  • URL

    URL的组成：基本的网络地址 ＋ 分支节点

    http://127.0.0.1:8080/chat 为 基本的网络地址

    /login 为 分支节点

    http://127.0.0.1:8080/chat/login 组成完整的 URL

    当前统一的基本网络地址为 http://127.0.0.1:8080/ChatServer

  • 请求方式

    POST

    GET

    PUT

  • 请求消息头

    键值对(key value形式)

  • 请求参数

    键值对(key value形式)

  • 响应的状态码

    统一的返回码为: 200 (注:只要访问服务器成功，一律返回200)

  • 响应的格式

    Json

  • 响应的JSON规范

    • 成功

      {flag:true, data:...}

      成功的标记为 flag 为 true

      根据具体的请求，如果需要返回值 data节点 包含的是 返回结果

      不需要需要返回值 ，则没有data节点

    • 失败

      {flag:false, errorCode:1, errorString:"错误原因"} 失败的标记为 flag 为 false

      flag 为 false时，必然返回 errorCode和errorString 节点

      errorCode说明了错误编码

      errorString说明错误原因

Login(登录接口)

  • 分支节点 : /login

  • 请求方式 : POST

  • 请求参数 :

    key | 类型 | 说明 ------------ | -------- | ------------ account | String | 用户的账号 password | String | 用户的密码

  • 响应结果 :

    • 成功

      {
    "flag": true,
    "data": {
        "account": "zhangsan",
        "name": "张三",
        "sex": 1,
        "icon": "/a/b/zhangsan.png",
        "sign": "我的个性签名",
        "area": "深圳",
        "token": "5904c7ae-3e75-48c8-bbee-ad094533a422"
    }
}

    • 失败

      errorCode | errorString ---------- | -------------- 100 | 用户密码错误 101 | 用户不存在

Regisger(注册接口)

  • 分支节点 : /register

  • 请求方式 : POST

  • 请求参数 :

    key | 类型 | 说明 ------------ | -------- | ------------ account | String | 用户注册的账号 password | String | 用户注册的密码

  • 响应结果 :

    • 成功

      {
    "flag": true,
    "data": {
        "account": "zhangsan",
        "name": "张三",
        "sex": 1,
        "icon": "/a/b/zhangsan.png",
        "sign": "我的个性签名",
        "area": "深圳",
        "token": "5904c7ae-3e75-48c8-bbee-ad094533a422"
    }
}

    • 失败

      errorCode | errorString ---------- | -------------- 150 | 用户已经存在

搜索用户接口

  • 分支节点 : /user/search

  • 请求方式 : POST

  • 请求消息头 :

    key      | 类型      | 说明

    ------------ | -------- | ------------ account | String | 用户的账号 token | String | 用户的唯一标识

  • 请求参数 :

    key      | 类型      | 说明

    ------------ | -------- | ------------ search | String | 搜索的账号

  • 响应结果 :

    • 成功

      {
    "flag": true,
    "data": {
        "account": "zhangsan",
        "name": "张三",
        "icon": "/a/b/zhangsan.png",
        "sign": "我的个性签名",
        "area": "深圳"
    }
}

    • 失败

      errorCode | errorString ---------- | -------------- 200 | 用户不存在

接受用户用户邀请

  • 分支节点 : /friend/accept

  • 请求方式 : POST

  • 请求消息头 :

    key      | 类型      | 说明

    ------------ | -------- | ------------ account | String | 用户的账号 token | String | 用户的唯一标识

  • 请求参数 :

    key | 类型 | 说明 ------------ | -------- | ------------ invitor | String | 邀请者的账号 acceptor | String | 接受者的账号

  • 响应结果 :

    • 成功

      {
    "flag": true
}

    • 失败

      {
    "flag": false
}

获取朋友列表

  • 分支节点 : /friend/list

  • 请求方式 : POST

  • 请求消息头 :

    key      | 类型      | 说明

    ------------ | -------- | ------------ account | String | 用户的账号 token | String | 用户的唯一标识

  • 请求参数 : 无

  • 响应结果 :

    • 成功

      {
    "flag": true
}

    • 失败

      {
    "flag": false
}

用户名称修改接口

  • 分支节点 : /user/nameChange

  • 请求方式 : POST

  • 请求消息头 :

    key      | 类型      | 说明

    ------------ | -------- | ------------ account | String | 用户的账号 token | String | 用户的唯一标识

  • 请求参数 :

    key      | 类型      | 说明

    ------------ | -------- | ------------ name | String | 修改后的用户名

  • 响应结果 :

    • 成功

      {
    "flag": true
}

    • 失败

      {
    "flag": false
}

Sokect自定义协议

全局规范

  • 协议的定义

    1. 传输格式为json
    2. 协议分为 请求 和 响应

    3. 传输方向:

      client --> server : 发送消息

      server --> client : 推送消息

    4. 发送消息

      发送过程包含的两个过程：

      请求 : client 发送消息到 server

      响应 : server 响应 client 的这次消息请求

      两个过程 都完成 才算 当前消息发送成功

    5. 推送消息

      推送过程包含的两个过程：

      请求 : server 发送消息到 client

      响应 : client 响应 server 的这次消息请求

      两个过程 都完成 才算 当前消息发送成功

    6. 消息必备格式

      请求部分:

      {
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "request",
    "action": "text"
}

      响应部分:

      {
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "response",
    "flag": "true"
}

      sequece : 标记 请求 和 响应，用来表明 响应 是 针对 哪次 请求的

      type : 用来标记 是 请求 还是 响应

      action : 请求发送方 的 发送类型，由具体请求 决定取值。

Client 部分

Auth认证

  • Action : auth

  • 请求的 key-Value

    key | 类型 | 说明 --------|-----------|------------- type | String |请求：request sequence| String |请求的序列号 action | String |请求的行为:auth sender | String |发送者账号 token | String |发送者token标志

  • 请求的json 格式:

    {
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "request",
    "action": "auth",
    "sender":"xxxx",
    "token":"xxxx"
}

    {"sequence":"1","type":"request","action":"auth","sender":"iphone1","token":"0dce6f76ac1a29d276c0c6dabe60519c"}

  • 响应的json 格式:

    成功 :

    {
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "response",
    "flag": "true",
}

    失败 :

    {
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "response",
    "flag": "false",
    "errorCode":"",
    "errorString":""
}

发送邀请

  • Action : invitation

  • 请求的 key-Value

    key | 类型 | 说明 --------|-----------|------------- type | String |请求：request sequence| String |请求的序列号 action | String |请求的行为:invitation sender | String |发送者账号 token | String |发送者token标志 receiver| String |接收者的账号 content | String |邀请的文本内容

  • 请求的json 格式:

    {
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "request",
    "action": "invitation",
    "token":"xxxx",
    "sender":"xxxx",
    "receiver":"xxxx",    
    "content":"xxxxxx"
}

  • 响应的json 格式:

    成功 :

    {
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "response",
    "flag": "true",
}

    失败 :

    {
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "response",
    "flag": "false",
    "errorCode":"",
    "errorString":""
}

发送文本消息

  • Action : text

  • 请求的 key-Value

    key | 类型 | 说明 --------|-----------|------------- type | String |请求：request sequence| String |请求的序列号 action | String |请求的行为:invitation sender | String |发送者账号 token | String |发送者token标志 receiver| String |接收者的账号 content | String |邀请的文本内容

  • 请求的json 格式:

    {
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "request",
    "action": "text",
    "token":"xxxx",
    "sender":"xxxx",
    "receiver":"xxxx",    
    "content":"xxxxxx"
}

  • 响应的json 格式:

    成功 :

    {
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "response",
    "flag": "true",
}

    失败 :

    {
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "response",
    "flag": "false",
    "errorCode":"",
    "errorString":""
}

Server 部分

推送用户邀请

  • action : invitation

  • 请求的 key-Value

    key | 类型 | 说明 --------|-----------|------------- type | String |请求：request sequence| String |请求的序列号 action | String |请求的行为:invitation sender | String |发送者账号 receiver| String |接收者的账号 invitorname|String |邀请者的名字 invitoricon|String |邀请者的头像 content | String |邀请的文本内容

  • 请求的json 格式:

    {
    "sequence":"3",
    "type":"request",
    "action":"invitation",
    "sender":"iphone1",
    "receiver":"iphone2",
    "invitor_name":"iphone2",
    "invitor_icon":"/icon/iphone2.png",
    "content":"hehe"
}

  • 响应的json 格式:

    成功 :

    {
    "sequence": "3",
    "type": "response",
    "flag": "true",
}

    失败 :

    {
    "sequence": "3",
    "type": "response",
    "flag": "false",
    "errorCode":"",
    "errorString":""
}

推送用户接受邀请

  • action : reinvitation

  • 请求的 key-Value

    key | 类型 | 说明 --------|-----------|------------- type | String |请求：request sequence| String |请求的序列号 action | String |请求的行为:reinvitation sender | String |发送者账号 receiver| String |接收者的账号 name | String |接受邀请者的名字 icon | String |接受邀请者的头像 content | String |邀请的文本内容

  • 请求的json 格式:

    {
    "sequence":"3",
    "type":"request",
    "action":"text",
    "sender":"iphone1",
    "receiver":"iphone2",
    "name":"iphone1",
    "icon","/icon/iphone1.png",
    "content":"hehe"
}

  • 响应的json 格式:

    成功 :

    {
    "sequence": "3",
    "type": "response",
    "flag": "true",
}

    失败 :

    {
    "sequence": "3",
    "type": "response",
    "flag": "false",
    "errorCode":"",
    "errorString":""
}

推送文本消息

  • action : text

  • 请求的 key-Value

    key | 类型 | 说明 --------|-----------|------------- type | String |请求：request sequence| String |请求的序列号 action | String |请求的行为:text sender | String |发送者账号 receiver| String |接收者的账号 content | String |邀请的文本内容

  • 请求的json 格式:

    {
    "sequence":"3",
    "type":"request",
    "action":"text",
    "sender":"iphone1",
    "receiver":"iphone2",
    "content":"hehe"
}

  • 响应的json 格式:

    成功 :

    {
    "sequence": "3",
    "type": "response",
    "flag": "true",
}

    失败 :

    {
    "sequence": "3",
    "type": "response",
    "flag": "false",
    "errorCode":"",
    "errorString":""
}

推送用户名变更

  • action : nameChange

  • 请求的 key-Value

    key | 类型 | 说明 --------|-----------|------------- type | String |请求：request sequence| String |请求的序列号 action | String |请求的行为:nameChange sender | String |发送者账号 receiver| String |接收者的账号 name | String |发送者变更后的名字

  • 请求的json 格式:

    {
    "sequence":"3",
    "type":"request",
    "action":"text",
    "sender":"iphone1",
    "receiver":"iphone2",
    "content":"hehe"
}

  • 响应的json 格式:

    成功 :

    {
    "sequence": "3",
    "type": "response",
    "flag": "true",
}

    失败 :

    {
    "sequence": "3",
    "type": "response",
    "flag": "false",
    "errorCode":"",
    "errorString":""
}

附件列表

    【推广】 免费学中医，健康全家人
    原文地址：https://www.cnblogs.com/sixrain/p/5188134.html