如何设计 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
新亮笔记
技术的深度和广度只能靠自己努力去发掘,谁也不能替你学习,在这里希望你能有所收获。
推荐阅读
关于项目中 Repository 层的思考
维护这一层的开发者,可以称为 仓库管理员 ,当使用者需要查询数据的时候,需要告诉仓库管理员,由仓库管理员拿给他,至于仓库管理员从哪拿的数据,使用者无需关系。
新亮赞 2阅读 1.8k评论 1
一个HTTP请求的曲折经历
作为程序员的我们每天都在和网络请求打交道,而前端程序员接触的最多的就是HTTP请求。平时工作中,处理网络请求之类的操作是最多的了。但是一个请求从客户端发出到被服务端处理、再回送响应,再被客户端接收这一...
nero赞 24阅读 5.1k评论 1
Nginx 一网打尽:动静分离、压缩、缓存、黑白名单、跨域、高可用、性能优化...
早期的业务都是基于单体节点部署,由于前期访问流量不大,因此单体结构也可满足需求,但随着业务增长,流量也越来越大,那么最终单台服务器受到的访问压力也会逐步增高。时间一长,单台服务器性能无法跟上业务增...
民工哥赞 23阅读 1.1k
Golang 中 []byte 与 string 转换
string 类型和 []byte 类型是我们编程时最常使用到的数据结构。本文将探讨两者之间的转换方式,通过分析它们之间的内在联系来拨开迷雾。
机器铃砍菜刀赞 24阅读 58.4k评论 2
年度最佳【golang】map详解
这篇文章主要讲 map 的赋值、删除、查询、扩容的具体执行过程,仍然是从底层的角度展开。结合源码,看完本文一定会彻底明白 map 底层原理。
去去1002赞 16阅读 11.6k评论 2
年度最佳【golang】GMP调度详解
Golang最大的特色可以说是协程(goroutine)了, 协程让本来很复杂的异步编程变得简单, 让程序员不再需要面对回调地狱, 虽然现在引入了协程的语言越来越多, 但go中的协程仍然是实现的是最彻底的. 这篇文章将通过分析...
去去1002赞 15阅读 12k评论 4
最好用的 python 库合集
🎈 分词 - jieba优秀的中文分词库,依靠中文词库,利用词库确定汉子之间关联的概率,形成分词结果 {代码...} 🎈 词云库 - wordcloud对数据中出现频率较高的 关键词 生成的一幅图像,予以视觉上的突出 {代码...} 🎈 ...
tiny极客赞 11阅读 2.9k评论 2
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用
。你还可以使用@
来通知其他用户。