最新公告
  • 新注册用户请前往个人中心绑定邮箱以便接收相关凭证邮件!!!点击前往个人中心
  • 公司前端和后端因为接口扯起了皮,还列了 5 宗罪

    • 罪状一:没有文档
    • 罪状二:文档不全
    • 罪状三:接口参数没校验
    • 罪状四:没保证接口原子性
    • 罪状五:接口问题不断

    今天一位前端开发人员扯起了后端接口的皮,那个兄弟对后端人员提供的接口很大的意见(我是司空见惯),不过他说的也确实有道理,所以结合我的见解,希望提供接口的人员能多加注意。

    罪状一:没有文档

    例如新的前端人员到了一个新的公司,使用接口时,问这个这个不知道,问那个那个不知道,要文档没文档,这绝对是前端人员最抓狂的事,心里肯定是一千只草泥马奔腾而过。
    1.为什么要文档?
    1. 文档是当前开发者甚至后面的接盘侠(后面开发者)能够清晰往下做的指引。
    2. 即便是简单的东西,但如果不写文档,以后口口相传消耗的工作量会比写文档更多。
    3. 好记性不如烂笔头,一段时候后,可能连开发者都忘记接口的用途。
    2.文档怎么写?
    1. 在线文档。
    在线文档易于更新和他人查看,例如可以使用Swagger编写接口文档。
    PS:Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。
    1. 本地文档。
    本地文档一般用Word文档,但是比较不易传播,但能离线查看。
    Final~
    文档是及其关键的,无论是在线文档还是本地文档,有是关键。虽然写文档是麻烦的事,但对后端人员来说,是利人利己。

    罪状二:文档不全

    额,就是有了文档,文档里面对接口的描述也可能不全,可能缺每个参数详尽描述(取值范围、类型)、请求方式(GET、POST、PUT、DELETE)、返回数据的所有状态等等。这里面可能最缺就是返回数据的状态!
    一般的返回数据结构~
    公司的数据接口返回结构是
    {
    s : 01//表示此操作的处理状态( status ),一般简单的成功 /不成功,使用 1/0 表示。
    m : ‘xxxx’//表示此操作的提示信息( message ),一般只用来显示操作失败时提示信息。
    r : [], //表示此操作的返回值( result )
    count : x //返回的数据条数

    }

    这种数据结构看起来没问题,确实也没大问题,问题就是出在s这个字段。有许多的接口不仅仅只有两种状态,成功状态只有一种倒是没问题,问题就出在失败状态,失败可能有很多情况,一个简单的s:0不能说明失败的原因(即便是有m提示信息,但用这个来区分很不靠谱,因为提示可能会变化),我们不总是仅拿m做显示用。
    升级返回数据结构~
    那位同事建议以下方式应答
    {
    s : 0123// 0代表正常,1是参数有误,2是用户不存在,3是用户没权限等等
    m : ‘xxxx’//表示此操作的提示信息( message ),一般只用来显示操作失败时提示信息。
    r : [], //表示此操作的返回值( result )
    count : x //返回的数据条数
    }
    m、r、count 可以保持不变,但是s里面必须包含所有返回状态,代表这个接口所有业务的情况,前端开发人员也就能针对每种情况进行处理。
    Final~
    文档最重要的部分是返回值的状态,我也建议上面的升级返回数据结构,这样就不存在任何不明朗情况。既然写了文档,就把文档写好,写明朗,这也是利人利己地方。

    罪状三:接口参数没校验

    这个前端人员倒不是很关注,因为本身调接口之前都会先做校验,后端做参数校验只是双重保证。我之前也做过一段时间后端,也犯过没校验参数的错,额,因为后来没有做后端,也就没有去修正。不过还是提醒后端人员,做好参数校验是第一步,不要偷懒了。
    Final~
    统一处理好接口校验,后端好好考虑下。

    罪状四:没保证接口原子性

    接口的原子性很重要,有时一个接口可能会干几件事,但不一定都能正常完成,这就导致可能存在原子性问题,接口不能准确被调用。
    PS:原子性。一个原子事务要么完整执行,要么干脆不执行。这意味着,工作单元中的每项任务都必须正确执行。如果有任一任务执行失败,则整个工作单元或事务就会被终止。即此前对数据所作的任何修改都将被撤销。如果所有任务都被成功执行,事务就会被提交,即对数据所作的修改将会是永久性的。
    Final~
    原子性一定要保证,保证,保证!

    罪状五:接口问题不断

    前端开发人员调接口时候,可能会存在各自各样的问题,有问题可以理解,程序哪会没有bug,但不能太离谱啊,后端兄弟们。所以我觉得在给出接口之前自己明确几件事:
    1. 是否校验参数。
    2. 是否所有的情况都测试过了,如果可以请写单元测试。
    3. 是否返回数据准确明朗,响应状态码是否正常。
    4. 文档是否已经完备。

    总结

    后端人员多体谅前端人员,在出现问题时,先检查自身,别一上来就跟前端干起来,要是自己的问题就尴尬了。
    本站所有文章均由网友分享,仅用于参考学习用,请勿直接转载,如有侵权,请联系网站客服删除相关文章。若由于商用引起版权纠纷,一切责任均由使用者承担
    极客文库 » 公司前端和后端因为接口扯起了皮,还列了 5 宗罪

    常见问题FAQ

    如果资源链接失效了怎么办?
    本站用户分享的所有资源都有自动备份机制,如果资源链接失效,请联系本站客服QQ:2580505920更新资源地址。
    如果用户分享的资源与描述不符怎么办?
    可以联系客服QQ:2580505920,如果要求合理可以安排退款或者退赞助积分。
    如何分享个人资源获取赞助积分或其他奖励?
    本站用户可以分享自己的资源,但是必须保证资源没有侵权行为。点击个人中心,根据操作填写并上传即可。资源所获收益完全归属上传者,每周可申请提现一次。
    如果您发现了本资源有侵权行为怎么办?
    及时联系客服QQ:2580505920,核实予以删除。

    参与讨论

    • 169会员总数(位)
    • 3735资源总数(个)
    • 1本周发布(个)
    • 0 今日发布(个)
    • 443稳定运行(天)

    欢迎加入「极客文库」,成为原创作者从这里开始!

    立即加入 了解更多
    成为赞助用户享有更多特权立即升级