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

[xianyv]

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

我还有一个问题:
如何委婉的让前端看完接口文档再提问题?

[bojackhorseman]

写好文档😏

[gauzung]

1.让前端看到接口就知道这个接口用在哪里；
2.让前端记住部分通用字典

我的评价是——换个后端

[cxe2v]

写好文档[微笑]

[xianyv]

@gauzung 哈哈哈哈,确实这两个要求太过分了

[zhuangjia]

写好文档

[xianyv]

@bojackhorseman
@cxe2v 怎么才能算是一个好文档? 因为业务频繁变动,有的时候实在是就把文档更新给忘记了

[zhuangjia]

1.让前端看到接口就知道这个接口用在哪里
没有默契就在开发前和前端对照设计图确认开发方案，并确保后面接口文档与此一致
2.怎么才能让前端记住部分通用字典
通用字典放到文档里，每个需要该字典的地方都链接过去

[h1104350235]

写好文档

[xianyv]

@zhuangjia 好的谢谢

[zhuangjia]

@xianyv
> 因为业务频繁变动,有的时候实在是就把文档更新给忘记了

前端怼我一句话：你文档没更新，我改不了

[cxe2v]

@xianyv #6 你都能把文档给忘了，那可不就得口耳相传接口设计了

[zinete]

我是前端， 有个 swagger docs 链接就成

[xianyv]

@cxe2v 这点我是需要改改的

[xianyv]

@zinete 不让用,文档手写

[iDontEatCookie]

我们后端给我的接口都是 xx 模块 /xx 页面 /xx 时候调用接口 这样写好的 字典要么是在接口参数注释里写好 要么是统一接口返回的

文档不更新 总不能让我看你后端代码接接口吧？

[bojackhorseman]

我们用的`swagger-typescript-api`根据 swagger json 文件生成 api 文档，类型提示，调用方法都有，特别方便，不用手写方法了。

[zoharSoul]

让前端自己写接口, 后端写到 rpc 层完事

[TangYuSen]

昨天上课的老师说了，软件开发中，敲代码只占了很小一部分的时间（他说最多 10%），更多时间是在写文档，开会交流，要我们牢记这点，其实我也赞同，我觉得我周围的人对文档很不重视，只顾敲代码完成功能就完事了，包括我，我自己也在学着去写文档了，但写文档来的正反馈真的没有敲代码完成一个小功能来的爽，感觉写文档，更多的是对自己工作负责吧，我想或许这是成为高级工程师的要点之一吧（我专业是软工）

[DShen]

自己做全栈😂

[deplivesb]

锻炼身体，当后端打不过你的时候，他自然能和你愉快的对接

[lqw3030]

yapi,swagger 通过介质，规避语言沟通带来的负面情绪

[xianyv]

@DShen 全栈做不了,但是能全干

[xianyv]

@lqw3030 确实 主要是沟通带来的负面情绪太多了

[nc4697]

我们写接口甚至不用通知前端。进度表更新已完成他们就自己去 swagger 上面找了

[joshuacavell]

@gauzung 就你秀

[RealJacob]

我还觉得我对接的后端做事儿不靠谱呢，文档不更新，有 swagger 也不用，mockapi 也不用，什么时候都觉得着急忙慌，让他改一改，规范一点，就是排期不够用，这次先赶进度。最后急匆匆的丢给我一堆数据，真是干的费劲。。。一帮老油条混子，说难听点，真的该被优化了

[c6h6benzene]

@xianyv 你用了还能拦着你不成…最多发布的时候去掉呗。

[c6h6benzene]

上条说的是 Swagger ，引用好像出错了。

[xianyv]

@RealJacob 直接丢数据确实有点恶心,一般都是更新文档的,就算是忘记了,沟通后也还是要更新的

[evil0harry]

postman group

[xianyv]

@c6h6benzene 能拦着,之前我跟领导沟通过,明确的不让用,而且他还隔几天就看看代码,我要是引用进去,他能给我唠叨半天

[xianyv]

@nc4697 我们没有项目进度表,项目管理混乱

[Heimerdinger]

提升自己的实力，有时候痛苦的根源是你自己表达不清楚

[guisheng]

总有一个人需要去叙述，要么你跟他说一次，要么画个图，要么他来问你这个地方调用哪个接口。

[Remember]

正儿八经的工程，文档比代码重要的，不存在把更新文档忘了这种事，应该是文档先出，代码后提交。

[phub2020]

我是前端，我只按后端给的文档干活。do one thing ，万一要是我不按文档干活，回头楼主会不会再怨我自己发挥过头呀。加个狗头，保命

[daliusu]

1.让前端看到接口就知道这个接口用在哪里；
2.让前端记住部分通用字典

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

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

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

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

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

所以解决这俩问题我觉得基础在工程化这块要做得好，前端后端都得做得好，其次就是后端要约束自己的代码，再然后就是前端要有点灵性（这个其实很难定义，我见过不少代码写的还可以的人确实不太灵性，有些代码写的一般般但是基本看看就懂了），我现在基本做一个模块（俩星期工作量的）可能跟后端也就沟通个几十句的样子，剩下大部分都是报一些问题

[qwei]

1.让前端看到接口就知道这个接口用在哪里：
接口用在哪需要看你们项目怎么规划，是面向对象的还是面向流程的。
面向对象的，需要完善的文档，结果应该是，看到接口知道拿到的是什么，而不是看到接口知道用在哪，比如：
getUserInfo ，看接口应该知道是获取用户信息，那么是用在哪的不需要你考虑。
如果是面向流程的，需要实现双方做好约定，结果应该是，看到接口就知道是用在哪，比如：
getUserCenterInfo ，那么这个接口应该是用户中心页面的所有内容（如果你真的肯这么干的话）；或者 getGoodsListForPage ，看起来应该是获取某一页的商品列表（如果你肯这么干的话）。
2.让前端记住部分通用字典
通用字典的关键在你们需要事前同步“通用”的含义，比如每个公司在定义接口返回状态的时候，code=0 是没问题，那么可以取 data 里的值，code!=0 ，那么 data 没有值，取 message 里的报错信息；而又有些公司，有 code 则是有问题，没有则是没问题。还有比如 end 是结束，那么开始有些会用 start ，有些会用 begin 。还有失败，有些会用 failed ，有些会用 error 。
你的通用字典，不一定是别人的通用字典。想让对方记住，就约定。

[ColdBird]

我工作几年得出的结论是后端不蠢，文档能出好，接口 bug 少点，就很轻松

[kiritoxf]

不让用 swagger 的话，可以本地搭个服务吧，跑在内网，让前端直接访问你电脑就行了。

[xianyv]

@kiritoxf 问题是前后端还不在一个内网,我们用的 Yapi

[iikebug]

全栈，自己接口自己写

[xianyv]

@daliusu 工程化这块确实做得不好,后端和前端都不好,都是放任自流的状态,能写出项目来就行的状态了

[xianyv]

@iikebug 哈哈哈哈,之前我就是这样,可惜没给我两份工资我就跑路了

[v2orz]

smart-doc , 写好自己的注释，剩下的交给它

[xianyv]

@v2orz 谢谢,我去看一下文档

[lingo]

你自己都说了工程化又没做好，业务频繁变动也会忘记更新文档，前端靠猜么 = =

[xianyv]

@lingo 所以我在考虑怎么不会忘记又能让前端看懂.

[yaphets666]

你写文档呀,不写文档就主动告诉人家或者等着问啊.字典什么的.前端不能查测试数据库吗?还是你的字段名与字典不一致?

[thtznet]

一个人写前后端，就很愉快地对接了

[uasier]

一个屏幕写前端，一个屏幕写后端

[Dragonphy]

按照 openapi 规范写好接口文档

[cedoo22]

现在的前端都不管业务， 只管调接口。。。不仅数据要有，连显示的格式都要和控件要求的格式一致。。。。当接口有变动还没发布出来的时候，就停工，真的把你搞到没脾气。

[leafre]

swagger

[lifesimple]

作为前端就烦你这样的后端，接口文档不写好，每次都要来口头沟通确认 「 xx 字段是对应页面 yy 内容把」，当然大部分情况都是没问题的，但也有些情况 比如一个 name 字段 按字段名来说应该是页面名称字段，但后端改了接口加了字段却不是这个字段也不说就很坑，因为没文档就算显而易见字段对应页面哪个东西，但不能确定还是得口头问，不问万一不是到时候出问题后端就说「这个字段不是对应页面 xx 咋不问一下」就他妈离谱。
写好文档，节省两个人的时间。

[ruiyinjinqu]

@TangYuSen 写文档就得加班，不写八点还能走

[ruiyinjinqu]

@DShen 前后端写自己确实爽啊，哪个方便在哪边处理

[ykk]

简单，自己写前端和后端😊

[ALVC666]

文档写好真的是一劳永逸的事情。
不然一句句口头确认太难受了

[guanhui07]

写好文档

[LengSe9]

推荐用 yapi 非常好用

[wiken]

面向文档编程

[Aaron55]

我们公司的话是用 Swagger ，接口注解写好相关的信息就好。

[weaponc]

处好关系，工具无所谓。
前期为人友好处好关系及时响应，后面你字段给他汉语拼音都没事

[Aprilming]

我就是不喜欢和同事对接， 所以自己对接。

[h1104350235]

@weaponc 这个我插两句阿。为人友好只会让人 pua ，有事没事让你改这改那。职场老好人太难当了。

[weaponc]

@h1104350235
你说的应该不是 pua ，是白嫖吧
为人友好也不是说就是得当老好人吧

[xstmjh123]

RPC

[RudyS]

全栈是最终解

[waltcow]

openAPI generator

[1016]

不写文档的人 最讨厌了 别老是写好接口就直接丢给前端一个 swagger 而有的叼后端 swagger 里面也不写清楚

[DShen]

@ruiyinjinqu #57 哈哈

[DShen]

@xianyv #22 那就只能在接口文档上做好了，有规范，有流程就相对比较愉快

[XCFOX]

关于写好文档，推荐一下 GraphQL ，接口即文档，一目了然

[xinge666]

fastapi 有个自动生成 api 文档的功能，把你的方法在这里再写一遍（不用实现）然后跑起来就行

[dayeye2006199]

先写 openapi spec -> 生成接口文档 -> 生成 mock server -> 前端开始工作的同时，后端开始补实现

接口变更也是 也从改 spec 开始，然后刷新文档，然后后端再补实现

[xuanbg]

参数命名一目了然，且至始至终保持一致。文档严格按照规范。时间长了基本上就不需要看文档了，或者你拿旧项目文档稍微改改就是一份新项目的文档。

[openbsd]

娶了前端，从此沟通再无障碍 [狗头]

[xqk111]

写好开发文档就行，先找找自己的问题

[xianyv]

@openbsd 哈哈哈哈,这个算了,有点难

[Donquixote0917]

https://gitee.com/Tencent/APIJSON 小项目可以试试

[jones2000]

给前端写一个对接好的 js 库， 所有数据都你自己对接好，前端只需要实例化对应的数据对接库， 就可以用， 不需要关心你的接口。

[listkun]

swagger-ui

[buyuw]

和前端商量好大部分通用字段,然后给他一个 swagger 文档 /swagger url,尽量写清楚用途 目的 示例,(大概)就能减少很多交流问题了

[ffw5b7]

yapi 也可以生成，有 idea 插件，没有 swagger 那样侵入。 分析设计，定义好接口沟通确认下，同步开发。

[xianyv]

@ffw5b7 好的,谢谢