请选择 进入手机版 | 继续访问电脑版

3楼社区

查看: 27|回复: 4

[规范制定征求] 后端 API 接口返回值

[复制链接]

该用户从未签到

2830

主题

2830

帖子

8631

积分

版主

Rank: 7Rank: 7Rank: 7

积分
8631
发表于 2020-11-20 14:45:59 | 显示全部楼层 |阅读模式
前言

我们公司正在快速发展状态,是时候开始制定各项技术标准规范(各种技术栈的语言规范)和工作流程从开发、测试到上线等)了,否则后期越来越玩不转。

前期虽然有引进各种规范,但总是支离破碎,而且有很多地方也不太符合我们公司工程师口味,所以也没有继续执行下去。

最近我们在开始整理各种技术规范和流程,会经历以下流程:

  • 内部主要人员(主要是是几个 TL )进行初稿审定,提出问题、分析问题、指定初稿。
  • 形成初稿后不仅在公司内部公示,不涉密部分还要在网上公示(重点)
  • 接收大家的意见和建议,综合各方意见并权衡利弊,确定一种方案开始在各团队中试行。
  • 后续再开发中遇到问题后,再升级规范。


今天我们公示一下我们公司的初稿,并解释其中的原因,也广泛征求大家的意见和建议,大家的每一条建议我们都会深入思考和论证的。后续我们还会有很多类似的规范拿出来和大家一起交流,不吝赐教。
后端 API 返回值规范初稿
规范针对群体

服务端、服务端对接端(网页端、APP 端、小程序端)
规范细节

  • 正常的后端接口响应,HTTP Status Code 默认返回 200,只有在下列情况时接口才会出现非 200 的情况:


  • 当服务端鉴权失败时返回 HTTP Status Code 401
  • 中间环节三方软件返回的标准错误码,例如 Nginx 返回的 5** 错误码


  • 当接口 HTTP Status Code 为 200 时,返回的结构如下:
  1. { “resultCode“: 200, “data“: null, “errorMsg“: ““ }
复制代码


  • resultCode 表示服务端处理结果代码,用 3 位数字表示通用处理结果代码,用 4 位及以上数字表示业务处理结果代码,通用处理结果代码有:
    200 表示处理成功
    400 表示参数错误
    500 表示服务器内部错误
    503 表示当前服务不可用
    504 表示网关超时
  • data 表示返回的数据,如果没有数据时返回 null
  • errorMsg 表示错误时的返回信息,如果没有错误时返回空字符串,始终不能为 null


  • 当接口 HTTP Status Code 非 200 时,返回的结构如下:
  1. { “resultCode“: {通用处理结果代码}, “data“: null, “errorMsg“: “对应的错误消息“ }
复制代码


  • 三方软件 HTTP Status Code 非 200 时,我们对内容不可控,对接端要做好拿不到返回 body 的准备

针对初稿里面的若干问题思考,也希望大家多提意见和建议


  • 为什么我们的返回都尽量采用 HTTP Status Code 为 200 ?
    答:经过公司内部对接端同事们的意见,如果返回的是非 200 状态码,目前很多框架会在框架层直接拦截,不会进一步解析消息体,不方便拿到服务端返回的错误消息。  

  • [重点讨论] 那为什么鉴权失败时要返回 HTTP Status Code 401 呢?
    答:目前我们的 APP 中有通过 WebView 嵌套网页,网页里面又有 Ajax 的调用。  


之前我们的流程是,APP 内如果需要打开网页,则需要通过一个固定的链接进行转换,例如本身要访问 a 链接,则务必访问跳转链接并添加参数 b?targetUrl=a,同时携带 APP 的鉴权参数( APP 我们是把鉴权参数放到 header 里面的),服务端拿到 APP 的鉴权信息后会回写 cookie 到网页中,同时引导跳转到真正的目标地址 。

上述流程里面就会出现一个问题,当 APP 里面的鉴权信息( Token )没有过期,但网页中的鉴权信息过期了(例如一些不可抗拒因素导致某台服务器丢失了网页端的 session ),用户再点击网页里面的内容,则始终会报告失败,给用户一种很不好的体验。

之前我们是通过 bridge 的形式由网页端通知 APP 端发起重新跳转,如果本次跳转 APP 鉴权信息依然有效则按照前述流程正常打开网页,如果本次跳转发现 APP 的鉴权信息也失效了,则引导用户在 APP 中重新登录。 根据我们的经验,bridge 这种方式很容易出现兼容性问题,在某些机型上无法通知 APP,导致用户始终卡在网页上(用户并不知道要重启 APP,只知道找客服)

为了让用户得到更好的体验,我们打算在 APP 层面捕捉 webview 的所有请求,一旦发现 HTTP Status Code 为 401 的情况,就引导 APP 重新登录,简单粗暴,不过会忽略 APP Token 有效,网页 Token 无效这种情况。

如果把 401 放到返回 body 里面,不方便 APP 统一捕捉返回信息。

  • 针对 APP 打开网页,网页里面有网页跳转或者接口请求这种情况,大家还有更好的方案吗?
    答:我们的目的是能够更好地处理错误流程。也希望大家多多指导,不胜感激。


如果按照上述我们的方案,我们的接口需要接收 cookie 这种鉴权方式( APP 内打开的网页通过 ajax 调用),也需要接收 header 这种鉴权方式( APP 直接请求);我们的网页需要接收 header 这种鉴权方式( APP 通过跳转链接打开目的网页时),也需要接收 cookie 这种鉴权方式(正常情况下都通过 cookie 认证)。,
前言

我们公司正在快速发展状态,是时候开始制定各项技术标准规范(各种技术栈的语言规范)和工作流程从开发、测试到上线等)了,否则后期越来越玩不转。

前期虽然有引进各种规范,但总是支离破碎,而且有很多地方也不太符合我们公司工程师口味,所以也没有继续执行下去。

最近我们在开始整理各种技术规范和流程,会经历以下流程:

  • 内部主要人员(主要是是几个 TL )进行初稿审定,提出问题、分析问题、指定初稿。
  • 形成初稿后不仅在公司内部公示,不涉密部分还要在网上公示(重点)
  • 接收大家的意见和建议,综合各方意见并权衡利弊,确定一种方案开始在各团队中试行。
  • 后续再开发中遇到问题后,再升级规范。


今天我们公示一下我们公司的初稿,并解释其中的原因,也广泛征求大家的意见和建议,大家的每一条建议我们都会深入思考和论证的。后续我们还会有很多类似的规范拿出来和大家一起交流,不吝赐教。
后端 API 返回值规范初稿
规范针对群体

服务端、服务端对接端(网页端、APP 端、小程序端)
规范细节

  • 正常的后端接口响应,HTTP Status Code 默认返回 200,只有在下列情况时接口才会出现非 200 的情况:


  • 当服务端鉴权失败时返回 HTTP Status Code 401
  • 中间环节三方软件返回的标准错误码,例如 Nginx 返回的 5** 错误码


  • 当接口 HTTP Status Code 为 200 时,返回的结构如下:
  1. { “resultCode“: 200, “data“: null, “errorMsg“: ““ }
复制代码


  • resultCode 表示服务端处理结果代码,用 3 位数字表示通用处理结果代码,用 4 位及以上数字表示业务处理结果代码,通用处理结果代码有:
    200 表示处理成功
    400 表示参数错误
    500 表示服务器内部错误
    503 表示当前服务不可用
    504 表示网关超时
  • data 表示返回的数据,如果没有数据时返回 null
  • errorMsg 表示错误时的返回信息,如果没有错误时返回空字符串,始终不能为 null


  • 当接口 HTTP Status Code 非 200 时,返回的结构如下:
  1. { “resultCode“: {通用处理结果代码}, “data“: null, “errorMsg“: “对应的错误消息“ }
复制代码


  • 三方软件 HTTP Status Code 非 200 时,我们对内容不可控,对接端要做好拿不到返回 body 的准备

针对初稿里面的若干问题思考,也希望大家多提意见和建议


  • 为什么我们的返回都尽量采用 HTTP Status Code 为 200 ?
    答:经过公司内部对接端同事们的意见,如果返回的是非 200 状态码,目前很多框架会在框架层直接拦截,不会进一步解析消息体,不方便拿到服务端返回的错误消息。  

  • [重点讨论] 那为什么鉴权失败时要返回 HTTP Status Code 401 呢?
    答:目前我们的 APP 中有通过 WebView 嵌套网页,网页里面又有 Ajax 的调用。  


之前我们的流程是,APP 内如果需要打开网页,则需要通过一个固定的链接进行转换,例如本身要访问 a 链接,则务必访问跳转链接并添加参数 b?targetUrl=a,同时携带 APP 的鉴权参数( APP 我们是把鉴权参数放到 header 里面的),服务端拿到 APP 的鉴权信息后会回写 cookie 到网页中,同时引导跳转到真正的目标地址 。

上述流程里面就会出现一个问题,当 APP 里面的鉴权信息( Token )没有过期,但网页中的鉴权信息过期了(例如一些不可抗拒因素导致某台服务器丢失了网页端的 session ),用户再点击网页里面的内容,则始终会报告失败,给用户一种很不好的体验。

之前我们是通过 bridge 的形式由网页端通知 APP 端发起重新跳转,如果本次跳转 APP 鉴权信息依然有效则按照前述流程正常打开网页,如果本次跳转发现 APP 的鉴权信息也失效了,则引导用户在 APP 中重新登录。 根据我们的经验,bridge 这种方式很容易出现兼容性问题,在某些机型上无法通知 APP,导致用户始终卡在网页上(用户并不知道要重启 APP,只知道找客服)

为了让用户得到更好的体验,我们打算在 APP 层面捕捉 webview 的所有请求,一旦发现 HTTP Status Code 为 401 的情况,就引导 APP 重新登录,简单粗暴,不过会忽略 APP Token 有效,网页 Token 无效这种情况。

如果把 401 放到返回 body 里面,不方便 APP 统一捕捉返回信息。

  • 针对 APP 打开网页,网页里面有网页跳转或者接口请求这种情况,大家还有更好的方案吗?
    答:我们的目的是能够更好地处理错误流程。也希望大家多多指导,不胜感激。


如果按照上述我们的方案,我们的接口需要接收 cookie 这种鉴权方式( APP 内打开的网页通过 ajax 调用),也需要接收 header 这种鉴权方式( APP 直接请求);我们的网页需要接收 header 这种鉴权方式( APP 通过跳转链接打开目的网页时),也需要接收 cookie 这种鉴权方式(正常情况下都通过 cookie 认证)。
回复

使用道具 举报

该用户从未签到

0

主题

85

帖子

1804

积分

惊鸿侠影

Rank: 9Rank: 9Rank: 9

积分
1804
发表于 2020-12-20 22:53:21 | 显示全部楼层
神马都是浮云!很给力!
回复

使用道具 举报

该用户从未签到

0

主题

85

帖子

1880

积分

惊鸿侠影

Rank: 9Rank: 9Rank: 9

积分
1880
发表于 2020-12-21 13:32:09 | 显示全部楼层
时光如飞刀,刀刀催人老
回复

使用道具 举报

该用户从未签到

0

主题

97

帖子

2056

积分

传奇人物

Rank: 10Rank: 10Rank: 10

积分
2056
发表于 2021-1-8 08:11:53 | 显示全部楼层
无图无真相
回复

使用道具 举报

该用户从未签到

0

主题

115

帖子

1842

积分

惊鸿侠影

Rank: 9Rank: 9Rank: 9

积分
1842
发表于 11 小时前 | 显示全部楼层
顶一顶
回复

使用道具 举报

您需要登录后才可以回帖 登录 | 立即注册

本版积分规则

Archiver|手机版|小黑屋|

快速回复 返回顶部 返回列表