【YQN】前后端对接接口API规范-企业开发项目流程

// http://xxx/api/xxx/xxx
// http://xxx/api/xxx/xxx?key1=value1&key2=value2&key3=value3

// http://xxx/api/xxx/xxx
// 通用请求体
{
    key1: 200,
    key2: '响应消息',
    key3: {
        xxx: '',
        yyy: {},
        zzz: []
    },
    key4: [
        {
            xxx: 1,
            yyy: '',
            zzz: {}
        },
        {
            xxx: 2,
            yyy: '',
            zzz: {}
        }
    ]
}

// 通用列表请求体
{
    // 列表业务用参数
    key1: 200,
    key2: '响应消息',
    // 列表格式用参数
    page: 1,                      // 请求页码（require）
    size: 20,                     // 请求每页展示数（require）
    sort: [
        {                         // 列表排序方式
            property: 'id',       // 排序属性的key
            direction: 'ASC'      // 排序方式    ASC[升序] | DESC[降序]
        }
    ]
}

// 通用对象返回
{
    code: 200,                       // 响应状态码（require）
    msg: '响应消息',                  // 响应消息体（require）
    data: {                          // 响应数据体（require）
        xxx: '',
        yyy: {},
        zzz: []
    }
}

// 通用数组返回
{
    code: 200,                       // 响应状态码（require）
    msg: '响应消息',                  // 响应消息体（require）
    data: [                          // 响应数据体（require）
        {
            xxx: '',
            yyy: {},
            zzz: []
        }
    ]
}

// 通用列表返回（带分页查询）
{
    code: 200,                        // 响应状态码（require）
    msg: '响应消息',                   // 响应消息体（require）
    data: {
        content: [                    // 列表数据体（require）
            {
                xxx: '',
                yyy: {},
                zzz: []
            }
        ],
        sort: [
            {                         // 列表排序方式
                property: 'id',       // 排序属性的key
                direction: 'ASC'      // 排序方式    ASC[升序] | DESC[降序]
            }
        ],
        page: 1,                      // 当前页码（require）
        size: 20,                     // 每页展示数（require）
        total: 200,                   // 列表总数（require）
        totalPage: 10,                // 列表总页数（require）
        isLast: 0                     // loadmore用，是否最后一页（require）
    }
}

// 无数据返回格式需要按照数据体类型返回对应空数据体
{
    code: 200,                       // 响应状态码（require）
    msg: '响应消息',                  // 响应消息体（require）
    data: {}                         // 无数据（require）
}

{
    code: 200,                       // 响应状态码（require）
    msg: '响应消息',                  // 响应消息体（require）
    data: []                         // 无数据（require）
}

{
    code: 200,                        // 响应状态码（require）
    msg: '响应消息',                   // 响应消息体（require）
    data: {
        content: [],                  // 无数据（require）
        sort: [{}],
        page: 1,                      // 当前页码（require）
        size: 0,                      // 每页展示数（require）
        total: 0,                     // 列表总数（require）
        totalPage: 0                  // 列表总页数（require）
        isLast: 1                     // loadmore用，是否最后一页（require）
    }
}

// 请求失败（网络不通，环境不对导致）
{
    code: 500,                        // 错误状态码（require）
    msg: '响应消息',                   // 错误消息体（require）
    data: {}                          // （require）
}

// 请求失败（业务错误）
{
    code: XXXXX,                      // 建议4-5位数错误码，用来和系统级别，通用错误码区分开来（require）
    msg: '响应消息',                   // 错误消息体（require）
    data: {}                          // （require）
}