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

前后端接口交互

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


新亮笔记
技术的深度和广度只能靠自己努力去发掘,谁也不能替你学习,在这里希望你能有所收获。

日拱一卒

2.9k 声望
1.2k 粉丝
0 条评论
推荐阅读
关于项目中 Repository 层的思考
维护这一层的开发者,可以称为 仓库管理员 ,当使用者需要查询数据的时候,需要告诉仓库管理员,由仓库管理员拿给他,至于仓库管理员从哪拿的数据,使用者无需关系。

新亮2阅读 1.8k评论 1

一个HTTP请求的曲折经历
作为程序员的我们每天都在和网络请求打交道,而前端程序员接触的最多的就是HTTP请求。平时工作中,处理网络请求之类的操作是最多的了。但是一个请求从客户端发出到被服务端处理、再回送响应,再被客户端接收这一...

nero24阅读 5.1k评论 1

Nginx 一网打尽:动静分离、压缩、缓存、黑白名单、跨域、高可用、性能优化...
早期的业务都是基于单体节点部署,由于前期访问流量不大,因此单体结构也可满足需求,但随着业务增长,流量也越来越大,那么最终单台服务器受到的访问压力也会逐步增高。时间一长,单台服务器性能无法跟上业务增...

民工哥23阅读 1.1k

封面图
Golang 中 []byte 与 string 转换
string 类型和 []byte 类型是我们编程时最常使用到的数据结构。本文将探讨两者之间的转换方式,通过分析它们之间的内在联系来拨开迷雾。

机器铃砍菜刀24阅读 58.4k评论 2

年度最佳【golang】map详解
这篇文章主要讲 map 的赋值、删除、查询、扩容的具体执行过程,仍然是从底层的角度展开。结合源码,看完本文一定会彻底明白 map 底层原理。

去去100216阅读 11.6k评论 2

年度最佳【golang】GMP调度详解
Golang最大的特色可以说是协程(goroutine)了, 协程让本来很复杂的异步编程变得简单, 让程序员不再需要面对回调地狱, 虽然现在引入了协程的语言越来越多, 但go中的协程仍然是实现的是最彻底的. 这篇文章将通过分析...

去去100215阅读 12k评论 4

最好用的 python 库合集
🎈 分词 - jieba优秀的中文分词库,依靠中文词库,利用词库确定汉子之间关联的概率,形成分词结果 {代码...} 🎈 词云库 - wordcloud对数据中出现频率较高的 关键词 生成的一幅图像,予以视觉上的突出 {代码...} 🎈 ...

tiny极客11阅读 2.9k评论 2

封面图

日拱一卒

2.9k 声望
1.2k 粉丝
宣传栏