码迷,mamicode.com
首页 > Windows程序 > 详细

如何设计 API 接口,实现统一格式返回?

时间:2021-06-02 20:38:53      阅读:0      评论:0      收藏:0      [点我收藏+]

标签:描述   取数据   目录   模块   mes   not   表示   规范   min   

文章目录:

前后端接口交互

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

如何设计 API 接口,实现统一格式返回?

标签:描述   取数据   目录   模块   mes   not   表示   规范   min   

原文地址:https://www.cnblogs.com/xinliangcoder/p/14839285.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!