如何设计 API 接口，实现统一格式返回？

文章目录：

目录

• controller 层如何用？
• • controller

前后端接口交互

我们都知道，前端通常会通过后台提供的接口来获取数据来完成前端页面的渲染，前端可以为 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。