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

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

  •  
  •   xianyv · 2021-12-09 09:43:01 +08:00 · 5528 次点击
    这是一个创建于 840 天前的主题,其中的信息可能已经有所发展或是发生改变。

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

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

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

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

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

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

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

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

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

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

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

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