乘风原创程序

  • 如何设计 API 接口,实现统一格式返回?
  • 2021/7/2 15:45:47
  • 文章目录:

    前后端接口交互

    我们都知道,前端通常会通过后台提供的接口来获取数据来完成前端页面的渲染,前端可以为 pc 端、m 端、小程序、app 等。

    在这废话就不多说了,这不是重点。

    接口返回值约定

    返回值规范

    • 设置返回的 http 响应状态码;
    • 发生错误时,需设置 response body 的错误码和描述信息;

    正确返回

    http 响应状态码,设置成 200,response body 结构为返回的数据结构。

    错误返回

    http 响应状态码,不要设置成 200!需遵循 rfc 标准。

    // failure 错误时返回结构
    type failure struct {
    	code    int    `json:"code"`    // 业务码
    	message string `json:"message"` // 描述信息
    }
    

    统一定义错误码

    错误码规范

    • 统一在一个文件中定义错误码;
    • 错误码长度为 5 位;

    第 1 位表示错误是哪种级别?例如:1 为系统级错误,2 为业务模块错误,可标记 9 种错误级别。

    第 2 位和第 3 位表示错误是哪个模块?例如:01 为用户模块,02 为订单模块,可标记 99 个模块。

    第 4 位和第 5 为表示具体是什么错误?例如:01 为手机号不合法,02 为验证码输入错误,可标记 99 个错误。

    controller 层如何用?

    正确返回

    res := new(createresponse)
    res.id = 1
    ctx.payload(res)
    

    错误返回

    c.abortwitherror(errno.newerror(
    	http.statusbadrequest,
    	code.admincreateerror,
    	code.text(code.admincreateerror)).witherr(err),
    )
    
    return 
    

    详细代码实现

    错误码

    • 错误码封装:
    • 定义错误码:

    controller

    总结

    以上代码供大家参考,还有优化的空间,欢迎大家使用并提出宝贵意见。

    问题思考

    • 1、提供对外接口时,如何进行安全的签名验证?
    • 2、接口的幂等性如何设计?
    • 3、如何统一对返回数据进行敏感数据脱敏?
    • 4、如何设计接口日志,便于接口联调时快速进行错误定位?
    • 5、关于接口文档,如何进行自动生成?听说过 swagger 还不知道如何使用?

    如果你对以上问题又疑惑或拿捏不准,快来我的星球交流讨论吧,https://t.zsxq.com/iiuvvna