Skip to main content
Version: 2.x

接口规范

一、 请求接口格式​

1. 请求方法规范(PATH 等其它方式建议不使用）)​

  • GET 请求 获取记录
  • PUT 请求 增加记录
  • POST 请求 修改记录
  • DELETE 请求 删除记录

2. 请求参数传输规范​

  • GET 请求的参数会拼凑在 url 尾部
  • 非 GET 请求的参数会放在 Request 对象的 body 参数里（重点）
  • restful 风格的 api 请求例如 /api/v2/users/1 (1 代表用户 id)

二、 接口请求格式​

1. 请求参数为对象​

{
    a: "1",
    ...
}

2. 请求参数为数组​

{
    list: [...]
}

务必注意，不能直接将数组作为参数请求，必须将数组包装到一个对象里面，例如如下格式是不合规范的

[...]

3. 分页请求​

{
  "page": 1,
  "pageSize": 20
}

三、 返回接口格式​

1. 通用接口返回格式​

    {
        code: 200/500, // Number 接口状态码, 200表示成功，500表示失败
        data: { // Object 接口返回数据
                ...
        },
        msg: "" // String 接口反馈信息，包括成功信息、错误信息等
        msgDetail: "" // String 异常详情，例如可以将发生异常的堆栈放在这里
    }

2. 返回数据为对象​

    {
        code: 200/500,
        data: {
                ... // Object 信息字段
        },
        msg: ""
    }

3. 返回数据为数组​

    {
        code: 200/500, //
        data: {
                list: []  // Array 返回列表信息
                ... // 其它信息字段
        },
        msg: ""
    }

请务必注意，不能直接将数组作为返回数据，必须将数组包装到一个对象里面，例如如下格式是不合规范的

    {
        code: 200,
        data: [...] // data必须是一个对象，不能是其它格式
        msg: ""
    }

4. 返回数据为分页数组​

    {
        code: 200/500, // Number  接口状态码
        data: {
                list: [], // Array 返回当前页列表信息
                totalRecord: 0, // Number 总条数
            },
        msg: "" // String 接口反馈信息，包括成功信息、错误信息等
    }

5. 返回 Select 下拉列表数据（字典数据）​

{
  "code": 200 / 500,
  "data": {
    "list": [
      {
        "id": 1, // Number value值
        "name": "显示" // String 显示字段
      }
    ] // Array 返回列表信息
  },
  "msg": ""
}

四、 返回码介绍​

除了 200、500 这两个常用的返回码，还有如下其它返回码

  1. 200（SUCCESS） 正常返回数据
  2. 304（NOT_MODIFIED） 数据没有发生变化(一般用于更新操作时，没有发生变化)
  3. 400（BAD_REQUEST） 客户端它发送了一个错误的请求(一般是参数不合法，可以在校验异常中使用)
  4. 401（UNAUTHORIZED） 没有认证(一般是没有登录)
  5. 403（FORBIDDEN）请求被服务器拒绝了(一般是认证通过了,但是没有权限访问该资源)
  6. 404（NOT_FOUND） 服务器无法找到所请求的 URL(一般在 Controller 中使用)
  7. 405（METHOD_NOT_ALLOWED） 发起的请求中带有所请求的 URL 不支持的方法时(如果该方法仅支持 POST 请求，用 GET 请求则报错)
  8. 408 （REQUEST_TIMEOUT）请求超时(客户端完成请求所花的时间太长)
  9. 500（ERROR） 服务器异常(一般数处理逻辑出现异常,可以在 service 中使用)