还能不能好好的写 API 了?规范争议大讨论,欢迎大家来拍砖!

刚组建的团队在一个新的项目上对于接口这块的处理规范上产生了分歧。
希望大家也能发表下意见对于接口这块有什么好的建议。

A,B后端希望遵循RESTful API中使用HTTP状态码来表示请求状态。

C前端希望统一返都返回 200 , 响应体中 data ,code,msg . code 用来做校验字段 ,msg 做提示信息

关于争论的三个帖子
https://www.zhihu.com/question/58686782
https://www.v2ex.com/t/321419
https://www.v2ex.com/t/321243?p=1

---大飞
本帖已被设为精华帖!
本帖由 Summer 于 6年前 加精
《L01 基础入门》
我们将带你从零开发一个项目并部署到线上,本课程教授 Web 开发中专业、实用的技能,如 Git 工作流、Laravel Mix 前端工作流等。
《G01 Go 实战入门》
从零开始带你一步步开发一个 Go 博客项目,让你在最短的时间内学会使用 Go 进行编码。项目结构很大程度上参考了 Laravel。
讨论数量: 9

@hooklife 首先要强调下我没说 RESTful 没用,我是说两者都可以,甚至可以参照 BAT 这些国内大厂的狗屎接口来定义自己的规范,不管啥标准啥规范都有优点和不足(坑),选用适合自己团队的就好。项目、团队可以是全新的,但开发人员都是有经验和技术包袱的,如果项目组10个程序员只有一两个精通 RESTful 其他人对 {code,msg} 都很老练,那么用 RESTful 必须有充分的理由而不是人云亦云。
网络情况很复杂, https 不是万能的,Google 全站 https 我还是访问不了,为啥绝大多数公开的 API 已经 https 了还有接口签名机制,某些二三级运营商有自己的缓存服务器,误伤你的接口很正常。每天都有人问搜索引擎为啥网络连接正常但只有 QQ 微信能上,腾讯做自己的协议不光是为了加密。
排除经验等因素,我不建议 RESTful 首先是觉得 API 只是数据接口,为啥要依赖 HTTP 这个传输层, Web 的世界里全是 HTTP,但是 API 规范可能还用于别的世界,比如我提到的 TCP/UDP Socket ,客户端自己的 route 等。大多数前端程序员只是写 UI 的,他只关心如何把数据呈现在界面上,至于数据是坐飞机来的还是骑摩拜来的他不管,那是架构师的事,而且前端程序员操作数据和界面的姿势五花八门,除了正常的网络数据请求和响应,他还要处理别的。当然,为了不影响前端的数据操作方式,可以在 HttpClient 里统一把 HTTP response 转换成 json 格式,这样的话对于前端来说使用 RESTful 貌似没啥意义了。
总之,没有更好的,只有更合适的。

你说的最后一点,是的,除了特殊照顾的接口,比如 HEAD 检查缓存、手动 Cookie 等,其他接口除了基本的 HTTP 头外没别的头,数据全在 body 里,状态 2xx 则请求成功然后解析 json 成前端语言相应的数组、字典、model、文件等。另外,从安全性角度讲,对于非开源的 API 来说,状态码和message/error都应该是非可见字段。

6年前 评论

消除 “个人喜欢”,制定团队规范,制定规范参考大厂玩法,就没啥大问题了

6年前 评论
Ryan

直接参考github的restful api

6年前 评论

同意 @overtrue ,老大定个规范,ABCDEF 端全按这个来,别瞎 BB,不爽可以离职...
我前后端都做,就我个人来说,我是不遵从 RESTful 的。管你 HTTP 状态码是200还是201,我解析 response 后得到 code 才认为这个响应确实是我服务端返回的。这种数据格式不依赖网络传输层的协议和质量,比如不用操心 HTTP 状态码或 header 被运营商或路由器篡改,除了处理 HTTP 响应还可以处理 socket 数据、前端自己的路由等。
我觉得后端倾向 RESTful 可能是因为觉得逼格高,所谓的公认规范,大厂经验。但是现实是很多公司设计的 RESTful API 不完全符合规范,或者是某些地方觉得不方便就用自己的定义的格式了,我见过的很多都是半洋不土。
前端喜欢自定义的 code, msg 主要是因为他们觉得这样更可控,在 HttpClient 里方便统一处理服务端异常、业务错误、解密解析响应、自动生成 model 对象等,而不是在具体的功能模块用 if-else 判断 HTTP 状态码。还有一点原因是前端新手程序员不太了解 HTTP ,可能是畏惧吧,我就见过几个写了三年 iOS/Android 客户端但是不知道 200 301 状态码是啥意思。
最后,如果公司以前用的协议没啥问题,就别轻易折腾了,搞项目重要的是上线,不是用啥语言用啥规范。

6年前 评论

@ElfSundae 感谢,这是个新团队,全新的项目,我对技术不是太了解~谢谢您的建议

6年前 评论
巴啦啦

开发项目要快

6年前 评论

@ElfSundae 首先你说的第一个问题,篡改的问题基本不需要考虑,现在随便拿出一个新项目应该都要上https吧?
第二个,我虽然没写过安卓/ios的开发,但是我觉得应该就是个在哪判断的问题,if else都是以一个一个判断吧?
http的状态码已经定了这么多基础的,你的http的库,浏览器都会对这些状态/头部信息进行处理?
如果你说这些东西都没用,都可以写到code什么里的话,那么写这种接口的http上是不是应该都是没有头的? 都是json返回回去的?

6年前 评论

@hooklife 首先要强调下我没说 RESTful 没用,我是说两者都可以,甚至可以参照 BAT 这些国内大厂的狗屎接口来定义自己的规范,不管啥标准啥规范都有优点和不足(坑),选用适合自己团队的就好。项目、团队可以是全新的,但开发人员都是有经验和技术包袱的,如果项目组10个程序员只有一两个精通 RESTful 其他人对 {code,msg} 都很老练,那么用 RESTful 必须有充分的理由而不是人云亦云。
网络情况很复杂, https 不是万能的,Google 全站 https 我还是访问不了,为啥绝大多数公开的 API 已经 https 了还有接口签名机制,某些二三级运营商有自己的缓存服务器,误伤你的接口很正常。每天都有人问搜索引擎为啥网络连接正常但只有 QQ 微信能上,腾讯做自己的协议不光是为了加密。
排除经验等因素,我不建议 RESTful 首先是觉得 API 只是数据接口,为啥要依赖 HTTP 这个传输层, Web 的世界里全是 HTTP,但是 API 规范可能还用于别的世界,比如我提到的 TCP/UDP Socket ,客户端自己的 route 等。大多数前端程序员只是写 UI 的,他只关心如何把数据呈现在界面上,至于数据是坐飞机来的还是骑摩拜来的他不管,那是架构师的事,而且前端程序员操作数据和界面的姿势五花八门,除了正常的网络数据请求和响应,他还要处理别的。当然,为了不影响前端的数据操作方式,可以在 HttpClient 里统一把 HTTP response 转换成 json 格式,这样的话对于前端来说使用 RESTful 貌似没啥意义了。
总之,没有更好的,只有更合适的。

你说的最后一点,是的,除了特殊照顾的接口,比如 HEAD 检查缓存、手动 Cookie 等,其他接口除了基本的 HTTP 头外没别的头,数据全在 body 里,状态 2xx 则请求成功然后解析 json 成前端语言相应的数组、字典、model、文件等。另外,从安全性角度讲,对于非开源的 API 来说,状态码和message/error都应该是非可见字段。

6年前 评论
xuding

我的5毛看法:

  1. 使用常用的几个HTTP Status Code(平衡前端与后端的学习量)
    • 200 - OK
    • 400 - Bad Request (Client Error)
    • 401 - Unauthorized
    • 500
  2. RESTful API是协议,HTTP是其实现方法之一。不用太纠结,项目能上线才是最重要。

P.S 有人用GraphQL吗?目前项目在用,值得一试。

6年前 评论

我开发的app接口都是用code,data,msg,没有用Restful风格……顺便吐槽一下,对于所谓的code,因为定义正确是1,其他是负数,我们的前端只是对code做了是否等于1的处理,根本就没有把控的那么细腻,因为前端也想省事啊

6年前 评论

讨论应以学习和精进为目的。请勿发布不友善或者负能量的内容,与人为善,比聪明更重要!