V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
V2EX 提问指南
xianyv
V2EX  ›  问与答

请问怎么样才能愉快的前后端进行对接

  •  
  •   xianyv · 250 天前 · 4727 次点击
    这是一个创建于 250 天前的主题,其中的信息可能已经有所发展或是发生改变。

    我现在跟前端对接的时候太痛苦了, 怎么才能让前端看到接口就知道这个接口用在哪里? 还有就是怎么才能让前端记住部分通用字典(这个可能有点过分)?

    第 1 条附言  ·  249 天前
    我还有一个问题:
    如何委婉的让前端看完接口文档再提问题?
    86 条回复    2021-12-10 17:40:10 +08:00
    bojackhorseman
        1
    bojackhorseman  
       250 天前
    写好文档😏
    gauzung
        2
    gauzung  
       250 天前   ❤️ 11
    1.让前端看到接口就知道这个接口用在哪里;
    2.让前端记住部分通用字典

    我的评价是——换个后端
    cxe2v
        3
    cxe2v  
       250 天前
    写好文档[微笑]
    xianyv
        4
    xianyv  
    OP
       250 天前
    @gauzung 哈哈哈哈,确实这两个要求太过分了
    zhuangjia
        5
    zhuangjia  
       250 天前
    写好文档
    xianyv
        6
    xianyv  
    OP
       250 天前
    @bojackhorseman
    @cxe2v 怎么才能算是一个好文档? 因为业务频繁变动,有的时候实在是就把文档更新给忘记了
    zhuangjia
        7
    zhuangjia  
       250 天前
    1.让前端看到接口就知道这个接口用在哪里
    没有默契就在开发前和前端对照设计图确认开发方案,并确保后面接口文档与此一致
    2.怎么才能让前端记住部分通用字典
    通用字典放到文档里,每个需要该字典的地方都链接过去
    h1104350235
        8
    h1104350235  
       250 天前
    写好文档
    xianyv
        9
    xianyv  
    OP
       250 天前
    @zhuangjia 好的谢谢
    zhuangjia
        10
    zhuangjia  
       250 天前
    @xianyv
    > 因为业务频繁变动,有的时候实在是就把文档更新给忘记了

    前端怼我一句话:你文档没更新,我改不了
    cxe2v
        11
    cxe2v  
       250 天前
    @xianyv #6 你都能把文档给忘了,那可不就得口耳相传接口设计了
    zinete
        12
    zinete  
       250 天前
    我是前端, 有个 swagger docs 链接就成
    xianyv
        13
    xianyv  
    OP
       250 天前
    @cxe2v 这点我是需要改改的
    xianyv
        14
    xianyv  
    OP
       250 天前
    @zinete 不让用,文档手写
    iDontEatCookie
        15
    iDontEatCookie  
       250 天前
    我们后端给我的接口都是 xx 模块 /xx 页面 /xx 时候调用接口 这样写好的 字典要么是在接口参数注释里写好 要么是统一接口返回的

    文档不更新 总不能让我看你后端代码接接口吧?
    bojackhorseman
        16
    bojackhorseman  
       250 天前
    我们用的`swagger-typescript-api`根据 swagger json 文件生成 api 文档,类型提示,调用方法都有,特别方便,不用手写方法了。
    zoharSoul
        17
    zoharSoul  
       250 天前
    让前端自己写接口, 后端写到 rpc 层完事
    TangYuSen
        18
    TangYuSen  
       250 天前
    昨天上课的老师说了,软件开发中,敲代码只占了很小一部分的时间(他说最多 10%),更多时间是在写文档,开会交流,要我们牢记这点,其实我也赞同,我觉得我周围的人对文档很不重视,只顾敲代码完成功能就完事了,包括我,我自己也在学着去写文档了,但写文档来的正反馈真的没有敲代码完成一个小功能来的爽,感觉写文档,更多的是对自己工作负责吧,我想或许这是成为高级工程师的要点之一吧(我专业是软工)
    DShen
        19
    DShen  
       250 天前 via iPhone
    自己做全栈😂
    deplivesb
        20
    deplivesb  
       250 天前
    锻炼身体,当后端打不过你的时候,他自然能和你愉快的对接
    lqw3030
        21
    lqw3030  
       250 天前
    yapi,swagger 通过介质,规避语言沟通带来的负面情绪
    xianyv
        22
    xianyv  
    OP
       250 天前
    @DShen 全栈做不了,但是能全干
    xianyv
        23
    xianyv  
    OP
       250 天前
    @lqw3030 确实 主要是沟通带来的负面情绪太多了
    nc4697
        24
    nc4697  
       250 天前
    我们写接口甚至不用通知前端。进度表更新已完成他们就自己去 swagger 上面找了
    joshuacavell
        25
    joshuacavell  
       250 天前
    @gauzung 就你秀
    RealJacob
        26
    RealJacob  
       250 天前
    我还觉得我对接的后端做事儿不靠谱呢,文档不更新,有 swagger 也不用,mockapi 也不用,什么时候都觉得着急忙慌,让他改一改,规范一点,就是排期不够用,这次先赶进度。最后急匆匆的丢给我一堆数据,真是干的费劲。。。一帮老油条混子,说难听点,真的该被优化了
    c6h6benzene
        27
    c6h6benzene  
       250 天前 via iPhone
    @xianyv 你用了还能拦着你不成…最多发布的时候去掉呗。
    c6h6benzene
        28
    c6h6benzene  
       250 天前 via iPhone
    上条说的是 Swagger ,引用好像出错了。
    xianyv
        29
    xianyv  
    OP
       250 天前
    @RealJacob 直接丢数据确实有点恶心,一般都是更新文档的,就算是忘记了,沟通后也还是要更新的
    evil0harry
        30
    evil0harry  
       250 天前
    postman group
    xianyv
        31
    xianyv  
    OP
       250 天前
    @c6h6benzene 能拦着,之前我跟领导沟通过,明确的不让用,而且他还隔几天就看看代码,我要是引用进去,他能给我唠叨半天
    xianyv
        32
    xianyv  
    OP
       250 天前
    @nc4697 我们没有项目进度表,项目管理混乱
    Heimerdinger
        33
    Heimerdinger  
       250 天前
    提升自己的实力,有时候痛苦的根源是你自己表达不清楚
    guisheng
        34
    guisheng  
       250 天前 via iPhone
    总有一个人需要去叙述,要么你跟他说一次,要么画个图,要么他来问你这个地方调用哪个接口。
    Remember
        35
    Remember  
       250 天前
    正儿八经的工程,文档比代码重要的,不存在把更新文档忘了这种事,应该是文档先出,代码后提交。
    phub2020
        36
    phub2020  
       250 天前
    我是前端,我只按后端给的文档干活。do one thing ,万一要是我不按文档干活,回头楼主会不会再怨我自己发挥过头呀。加个狗头,保命
    daliusu
        37
    daliusu  
       250 天前
    1.让前端看到接口就知道这个接口用在哪里;
    2.让前端记住部分通用字典

    这俩说能解决都能解决,说不能解决也不能解决,事实上这问题大头在后端和项目的工程化能力而不是前端
    比如 [让前端看到接口就知道这个接口用在哪里] ,你觉得前提是不是得你给接口写的好?外加你们工程化做得好?接口文档清晰分类,同时你接口名称命名也够规范够清楚,这样前端按照分类自己找到对应模块,然后去模块看看名字就知道自己要哪个接口。我见过有一些接口是完全没分类的,就一串名字,这串名字还包含大量无意义的后端模块信息,根本区分不出来这是什么玩意。我给个实际例子,memberAddLog 这个是我前一阵子接口的一个系统的接口,你看名字猜猜这是啥,是不是加成员的日志信息?其实这是个成员列表接口,为啥叫这个,因为后端觉得成员都是人为添加的,添加日志就是成员列表,所以叫这个。而且文档没有任何 注释说这是个啥玩意,如果满屏幕都是这玩意你说怎么能接,问了我都怕记不住我还要自己写注释,不然隔天就忘了这是个什么。

    [怎么才能让前端记住部分通用字典] 这个问题反倒好解决,我这里是这部分字典会在接口文档里面直接体现,我找了个实际的

    // 前端接口文件
    export enum APIStatus {
    DEPLOYED = "已部署",
    DEPLOYING = "部署中",
    FAILED = "部署失败",
    }

    // 后端文档
    {
    apiName: string,
    apiStatus: APIStatus
    }

    接口文档会直接标注 apiStatus 的类型是 APIStatus ,前端去直接引用 APIStatus 这个枚举就可以了,所以我反倒工作中没碰到过词典问题,但是这个前提也得工程化支持同时规范化操作,你如果就给写个 0 1 2 ,这就没辙了,不问上哪知道去,最坑的有时候用 01 ,有时候用 12 ,有时候字符串,有时候数字。

    所以解决这俩问题我觉得基础在工程化这块要做得好,前端后端都得做得好,其次就是后端要约束自己的代码,再然后就是前端要有点灵性(这个其实很难定义,我见过不少代码写的还可以的人确实不太灵性,有些代码写的一般般但是基本看看就懂了),我现在基本做一个模块(俩星期工作量的)可能跟后端也就沟通个几十句的样子,剩下大部分都是报一些问题
    qwei
        38
    qwei  
       250 天前
    1.让前端看到接口就知道这个接口用在哪里:
    接口用在哪需要看你们项目怎么规划,是面向对象的还是面向流程的。
    面向对象的,需要完善的文档,结果应该是,看到接口知道拿到的是什么,而不是看到接口知道用在哪,比如:
    getUserInfo ,看接口应该知道是获取用户信息,那么是用在哪的不需要你考虑。
    如果是面向流程的,需要实现双方做好约定,结果应该是,看到接口就知道是用在哪,比如:
    getUserCenterInfo ,那么这个接口应该是用户中心页面的所有内容(如果你真的肯这么干的话);或者 getGoodsListForPage ,看起来应该是获取某一页的商品列表(如果你肯这么干的话)。
    2.让前端记住部分通用字典
    通用字典的关键在你们需要事前同步“通用”的含义,比如每个公司在定义接口返回状态的时候,code=0 是没问题,那么可以取 data 里的值,code!=0 ,那么 data 没有值,取 message 里的报错信息;而又有些公司,有 code 则是有问题,没有则是没问题。还有比如 end 是结束,那么开始有些会用 start ,有些会用 begin 。还有失败,有些会用 failed ,有些会用 error 。
    你的通用字典,不一定是别人的通用字典。想让对方记住,就约定。
    ColdBird
        39
    ColdBird  
       250 天前
    我工作几年得出的结论是后端不蠢,文档能出好,接口 bug 少点,就很轻松
    kiritoxf
        40
    kiritoxf  
       250 天前
    不让用 swagger 的话,可以本地搭个服务吧,跑在内网,让前端直接访问你电脑就行了。
    xianyv
        41
    xianyv  
    OP
       250 天前
    @kiritoxf 问题是前后端还不在一个内网,我们用的 Yapi
    iikebug
        42
    iikebug  
       250 天前
    全栈,自己接口自己写
    xianyv
        43
    xianyv  
    OP
       250 天前
    @daliusu 工程化这块确实做得不好,后端和前端都不好,都是放任自流的状态,能写出项目来就行的状态了
    xianyv
        44
    xianyv  
    OP
       250 天前
    @iikebug 哈哈哈哈,之前我就是这样,可惜没给我两份工资我就跑路了
    v2orz
        45
    v2orz  
       250 天前
    smart-doc , 写好自己的注释,剩下的交给它
    xianyv
        46
    xianyv  
    OP
       250 天前
    @v2orz 谢谢,我去看一下文档
    lingo
        47
    lingo  
       250 天前
    你自己都说了工程化又没做好,业务频繁变动也会忘记更新文档,前端靠猜么 = =
    xianyv
        48
    xianyv  
    OP
       250 天前
    @lingo 所以我在考虑怎么不会忘记又能让前端看懂.
    yaphets666
        49
    yaphets666  
       250 天前
    你写文档呀,不写文档就主动告诉人家或者等着问啊.字典什么的.前端不能查测试数据库吗?还是你的字段名与字典不一致?
    thtznet
        50
    thtznet  
       250 天前
    一个人写前后端,就很愉快地对接了
    uasier
        51
    uasier  
       250 天前
    一个屏幕写前端,一个屏幕写后端
    Dragonphy
        52
    Dragonphy  
       250 天前
    按照 openapi 规范写好接口文档
    cedoo22
        53
    cedoo22  
       250 天前
    现在的前端都不管业务, 只管调接口。。。不仅数据要有,连显示的格式都要和控件要求的格式一致。。。。当接口有变动还没发布出来的时候,就停工,真的把你搞到没脾气。
    leafre
        54
    leafre  
       250 天前 via Android
    swagger
    lifesimple
        55
    lifesimple  
       250 天前
    作为前端就烦你这样的后端,接口文档不写好,每次都要来口头沟通确认 「 xx 字段是对应页面 yy 内容把」,当然大部分情况都是没问题的,但也有些情况 比如一个 name 字段 按字段名来说应该是页面名称字段,但后端改了接口加了字段却不是这个字段也不说就很坑,因为没文档就算显而易见字段对应页面哪个东西,但不能确定还是得口头问,不问万一不是到时候出问题后端就说「这个字段不是对应页面 xx 咋不问一下」就他妈离谱。
    写好文档,节省两个人的时间。
    ruiyinjinqu
        56
    ruiyinjinqu  
       250 天前
    @TangYuSen 写文档就得加班,不写八点还能走
    ruiyinjinqu
        57
    ruiyinjinqu  
       250 天前
    @DShen 前后端写自己确实爽啊,哪个方便在哪边处理
    ykk
        58
    ykk  
       250 天前
    简单,自己写前端和后端😊
    ALVC666
        59
    ALVC666  
       250 天前
    文档写好真的是一劳永逸的事情。
    不然一句句口头确认太难受了
    guanhui07
        60
    guanhui07  
       250 天前
    写好文档
    LengSe9
        61
    LengSe9  
       250 天前
    推荐用 yapi 非常好用
    wiken
        62
    wiken  
       250 天前
    面向文档编程
    Aaron55
        63
    Aaron55  
       250 天前
    我们公司的话是用 Swagger ,接口注解写好相关的信息就好。
    weaponc
        64
    weaponc  
       250 天前
    处好关系,工具无所谓。
    前期为人友好处好关系及时响应,后面你字段给他汉语拼音都没事
    Aprilming
        65
    Aprilming  
       250 天前
    我就是不喜欢和同事对接, 所以自己对接。
    h1104350235
        66
    h1104350235  
       250 天前
    @weaponc 这个我插两句阿。为人友好只会让人 pua ,有事没事让你改这改那。职场老好人太难当了。
    weaponc
        67
    weaponc  
       250 天前
    @h1104350235
    你说的应该不是 pua ,是白嫖吧
    为人友好也不是说就是得当老好人吧
    xstmjh123
        68
    xstmjh123  
       250 天前
    RPC
    RudyS
        69
    RudyS  
       250 天前
    全栈是最终解
    waltcow
        70
    waltcow  
       250 天前
    openAPI generator
    1016
        71
    1016  
       250 天前   ❤️ 1
    不写文档的人 最讨厌了 别老是写好接口就直接丢给前端一个 swagger 而有的叼后端 swagger 里面也不写清楚
    DShen
        72
    DShen  
       250 天前 via iPhone
    @ruiyinjinqu #57 哈哈
    DShen
        73
    DShen  
       250 天前 via iPhone
    @xianyv #22 那就只能在接口文档上做好了,有规范,有流程就相对比较愉快
    XCFOX
        74
    XCFOX  
       250 天前   ❤️ 1
    关于写好文档,推荐一下 GraphQL ,接口即文档,一目了然
    xinge666
        75
    xinge666  
       249 天前 via iPhone   ❤️ 1
    fastapi 有个自动生成 api 文档的功能,把你的方法在这里再写一遍(不用实现)然后跑起来就行
    dayeye2006199
        76
    dayeye2006199  
       249 天前
    先写 openapi spec -> 生成接口文档 -> 生成 mock server -> 前端开始工作的同时,后端开始补实现

    接口变更也是 也从改 spec 开始,然后刷新文档,然后后端再补实现
    xuanbg
        77
    xuanbg  
       249 天前
    参数命名一目了然,且至始至终保持一致。文档严格按照规范。时间长了基本上就不需要看文档了,或者你拿旧项目文档稍微改改就是一份新项目的文档。
    openbsd
        78
    openbsd  
       249 天前
    娶了前端,从此沟通再无障碍 [狗头]
    xqk111
        79
    xqk111  
       249 天前
    写好开发文档就行,先找找自己的问题
    xianyv
        80
    xianyv  
    OP
       249 天前
    @openbsd 哈哈哈哈,这个算了,有点难
    Donquixote0917
        81
    Donquixote0917  
       249 天前   ❤️ 1
    https://gitee.com/Tencent/APIJSON 小项目可以试试
    jones2000
        82
    jones2000  
       249 天前   ❤️ 1
    给前端写一个对接好的 js 库, 所有数据都你自己对接好,前端只需要实例化对应的数据对接库, 就可以用, 不需要关心你的接口。
    listkun
        83
    listkun  
       249 天前
    swagger-ui
    buyuw
        84
    buyuw  
       249 天前
    和前端商量好大部分通用字段,然后给他一个 swagger 文档 /swagger url,尽量写清楚用途 目的 示例,(大概)就能减少很多交流问题了
    ffw5b7
        85
    ffw5b7  
       249 天前 via Android
    yapi 也可以生成,有 idea 插件,没有 swagger 那样侵入。 分析设计,定义好接口沟通确认下,同步开发。
    xianyv
        86
    xianyv  
    OP
       249 天前
    @ffw5b7 好的,谢谢
    关于   ·   帮助文档   ·   API   ·   FAQ   ·   我们的愿景   ·   广告投放   ·   感谢   ·   实用小工具   ·   2810 人在线   最高记录 5497   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 62ms · UTC 13:22 · PVG 21:22 · LAX 06:22 · JFK 09:22
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.