这是一个创建于 1081 天前的主题，其中的信息可能已经有所发展或是发生改变。
我现在跟前端对接的时候太痛苦了, 怎么才能让前端看到接口就知道这个接口用在哪里? 还有就是怎么才能让前端记住部分通用字典(这个可能有点过分)?
第 1 条附言 · 2021-12-10 12:34:50 +08:00
我还有一个问题:
如何委婉的让前端看完接口文档再提问题?
如何委婉的让前端看完接口文档再提问题?
 |
1
bojackhorseman 2021-12-09 09:53:46 +08:00
写好文档😏
|
 |
2
gauzung 2021-12-09 09:59:45 +08:00  11
1.让前端看到接口就知道这个接口用在哪里；
2.让前端记住部分通用字典 我的评价是——换个后端 |
 |
3
cxe2v 2021-12-09 10:03:13 +08:00
写好文档[微笑]
|
 |
5
zhuangjia 2021-12-09 10:13:43 +08:00
写好文档
|
 |
6
xianyv OP |
|
7
zhuangjia 2021-12-09 10:17:27 +08:00
1.让前端看到接口就知道这个接口用在哪里
没有默契就在开发前和前端对照设计图确认开发方案，并确保后面接口文档与此一致 2.怎么才能让前端记住部分通用字典 通用字典放到文档里，每个需要该字典的地方都链接过去 |
 |
8
h1104350235 2021-12-09 10:17:52 +08:00
写好文档
|
 |
12
zinete 2021-12-09 10:21:52 +08:00
我是前端， 有个 swagger docs 链接就成
|
 |
15
iDontEatCookie 2021-12-09 10:25:32 +08:00
我们后端给我的接口都是 xx 模块 /xx 页面 /xx 时候调用接口 这样写好的 字典要么是在接口参数注释里写好 要么是统一接口返回的
文档不更新 总不能让我看你后端代码接接口吧？ |
|
16
bojackhorseman 2021-12-09 10:33:28 +08:00
我们用的`swagger-typescript-api`根据 swagger json 文件生成 api 文档，类型提示，调用方法都有，特别方便，不用手写方法了。
|
 |
17
zoharSoul 2021-12-09 10:34:37 +08:00
让前端自己写接口, 后端写到 rpc 层完事
|
 |
18
TangYuSen 2021-12-09 11:01:08 +08:00
昨天上课的老师说了，软件开发中，敲代码只占了很小一部分的时间（他说最多 10%），更多时间是在写文档，开会交流，要我们牢记这点，其实我也赞同，我觉得我周围的人对文档很不重视，只顾敲代码完成功能就完事了，包括我，我自己也在学着去写文档了，但写文档来的正反馈真的没有敲代码完成一个小功能来的爽，感觉写文档，更多的是对自己工作负责吧，我想或许这是成为高级工程师的要点之一吧（我专业是软工）
|
 |
19
DShen 2021-12-09 11:06:47 +08:00 via iPhone
自己做全栈😂
|
 |
20
deplivesb 2021-12-09 11:08:34 +08:00
锻炼身体，当后端打不过你的时候，他自然能和你愉快的对接
|
 |
21
lqw3030 2021-12-09 11:16:40 +08:00
yapi,swagger 通过介质，规避语言沟通带来的负面情绪
|
 |
24
nc4697 2021-12-09 11:26:53 +08:00
我们写接口甚至不用通知前端。进度表更新已完成他们就自己去 swagger 上面找了
|
 |
25
joshuacavell 2021-12-09 11:27:40 +08:00
@gauzung 就你秀
|
 |
26
RealJacob 2021-12-09 11:29:14 +08:00
我还觉得我对接的后端做事儿不靠谱呢，文档不更新，有 swagger 也不用，mockapi 也不用，什么时候都觉得着急忙慌，让他改一改，规范一点，就是排期不够用，这次先赶进度。最后急匆匆的丢给我一堆数据，真是干的费劲。。。一帮老油条混子，说难听点，真的该被优化了
|
 |
27
c6h6benzene 2021-12-09 11:29:58 +08:00 via iPhone
@xianyv 你用了还能拦着你不成…最多发布的时候去掉呗。
|
|
28
c6h6benzene 2021-12-09 11:30:47 +08:00 via iPhone
上条说的是 Swagger ，引用好像出错了。
|
 |
30
evil0harry 2021-12-09 11:34:13 +08:00
postman group
|
|
31
xianyv OP @c6h6benzene 能拦着,之前我跟领导沟通过,明确的不让用,而且他还隔几天就看看代码,我要是引用进去,他能给我唠叨半天
|
 |
33
Heimerdinger 2021-12-09 12:01:01 +08:00
提升自己的实力，有时候痛苦的根源是你自己表达不清楚
|
 |
34
guisheng 2021-12-09 12:03:43 +08:00 via iPhone
总有一个人需要去叙述，要么你跟他说一次，要么画个图，要么他来问你这个地方调用哪个接口。
|
 |
35
Remember 2021-12-09 12:04:49 +08:00
正儿八经的工程，文档比代码重要的，不存在把更新文档忘了这种事，应该是文档先出，代码后提交。
|
 |
36
phub2020 2021-12-09 12:13:59 +08:00
我是前端，我只按后端给的文档干活。do one thing ，万一要是我不按文档干活，回头楼主会不会再怨我自己发挥过头呀。加个狗头，保命
|
 |
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 ，有时候字符串，有时候数字。 所以解决这俩问题我觉得基础在工程化这块要做得好，前端后端都得做得好，其次就是后端要约束自己的代码，再然后就是前端要有点灵性（这个其实很难定义，我见过不少代码写的还可以的人确实不太灵性，有些代码写的一般般但是基本看看就懂了），我现在基本做一个模块（俩星期工作量的）可能跟后端也就沟通个几十句的样子，剩下大部分都是报一些问题 |
 |
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 。 你的通用字典，不一定是别人的通用字典。想让对方记住，就约定。 |
 |
39
ColdBird 2021-12-09 13:15:57 +08:00
我工作几年得出的结论是后端不蠢，文档能出好，接口 bug 少点，就很轻松
|
 |
40
kiritoxf 2021-12-09 13:40:04 +08:00
不让用 swagger 的话，可以本地搭个服务吧，跑在内网，让前端直接访问你电脑就行了。
|
 |
42
iikebug 2021-12-09 13:48:47 +08:00
全栈，自己接口自己写
|
 |
45
v2orz 2021-12-09 13:51:35 +08:00
smart-doc , 写好自己的注释，剩下的交给它
|
 |
47
lingo 2021-12-09 14:03:57 +08:00
你自己都说了工程化又没做好，业务频繁变动也会忘记更新文档，前端靠猜么 = =
|
 |
49
yaphets666 2021-12-09 14:47:53 +08:00
你写文档呀,不写文档就主动告诉人家或者等着问啊.字典什么的.前端不能查测试数据库吗?还是你的字段名与字典不一致?
|
 |
50
thtznet 2021-12-09 15:07:46 +08:00
一个人写前后端，就很愉快地对接了
|
 |
51
uasier 2021-12-09 15:16:32 +08:00
一个屏幕写前端，一个屏幕写后端
|
 |
52
Dragonphy 2021-12-09 15:27:49 +08:00
按照 openapi 规范写好接口文档
|
 |
53
cedoo22 2021-12-09 15:38:01 +08:00
现在的前端都不管业务， 只管调接口。。。不仅数据要有，连显示的格式都要和控件要求的格式一致。。。。当接口有变动还没发布出来的时候，就停工，真的把你搞到没脾气。
|
 |
54
leafre 2021-12-09 15:45:26 +08:00 via Android
swagger
|
 |
55
lifesimple 2021-12-09 15:55:31 +08:00
作为前端就烦你这样的后端，接口文档不写好，每次都要来口头沟通确认 「 xx 字段是对应页面 yy 内容把」，当然大部分情况都是没问题的，但也有些情况 比如一个 name 字段 按字段名来说应该是页面名称字段，但后端改了接口加了字段却不是这个字段也不说就很坑，因为没文档就算显而易见字段对应页面哪个东西，但不能确定还是得口头问，不问万一不是到时候出问题后端就说「这个字段不是对应页面 xx 咋不问一下」就他妈离谱。
写好文档，节省两个人的时间。 |
 |
56
ruiyinjinqu 2021-12-09 16:01:17 +08:00
@TangYuSen 写文档就得加班，不写八点还能走
|
|
57
ruiyinjinqu 2021-12-09 16:02:16 +08:00
@DShen 前后端写自己确实爽啊，哪个方便在哪边处理
|
 |
58
ykk 2021-12-09 16:15:28 +08:00
简单，自己写前端和后端😊
|
 |
59
ALVC666 2021-12-09 16:19:52 +08:00
文档写好真的是一劳永逸的事情。
不然一句句口头确认太难受了 |
 |
60
guanhui07 2021-12-09 16:30:36 +08:00
写好文档
|
 |
61
LengSe9 2021-12-09 16:38:26 +08:00
推荐用 yapi 非常好用
|
 |
62
wiken 2021-12-09 16:43:58 +08:00
面向文档编程
|
 |
63
Aaron55 2021-12-09 16:49:07 +08:00
我们公司的话是用 Swagger ，接口注解写好相关的信息就好。
|
 |
64
weaponc 2021-12-09 17:08:45 +08:00
处好关系，工具无所谓。
前期为人友好处好关系及时响应，后面你字段给他汉语拼音都没事 |
 |
65
Aprilming 2021-12-09 17:33:47 +08:00
我就是不喜欢和同事对接， 所以自己对接。
|
|
66
h1104350235 2021-12-09 17:34:54 +08:00
@weaponc 这个我插两句阿。为人友好只会让人 pua ，有事没事让你改这改那。职场老好人太难当了。
|
|
67
weaponc 2021-12-09 17:40:22 +08:00
|
 |
68
xstmjh123 2021-12-09 17:41:02 +08:00
RPC
|
 |
69
RudyS 2021-12-09 17:42:25 +08:00
全栈是最终解
|
 |
70
waltcow 2021-12-09 18:01:29 +08:00
openAPI generator
|
 |
71
1016 2021-12-09 18:03:33 +08:00 1
不写文档的人 最讨厌了 别老是写好接口就直接丢给前端一个 swagger 而有的叼后端 swagger 里面也不写清楚
|
|
72
DShen 2021-12-09 20:14:35 +08:00 via iPhone
@ruiyinjinqu #57 哈哈
|
 |
74
XCFOX 2021-12-09 20:16:18 +08:00 1
关于写好文档，推荐一下 GraphQL ，接口即文档，一目了然
|
 |
75
xinge666 2021-12-10 00:08:07 +08:00 via iPhone 1
fastapi 有个自动生成 api 文档的功能，把你的方法在这里再写一遍（不用实现）然后跑起来就行
|
 |
76
dayeye2006199 2021-12-10 06:21:10 +08:00
先写 openapi spec -> 生成接口文档 -> 生成 mock server -> 前端开始工作的同时，后端开始补实现
接口变更也是 也从改 spec 开始，然后刷新文档，然后后端再补实现 |
 |
77
xuanbg 2021-12-10 06:57:44 +08:00
参数命名一目了然，且至始至终保持一致。文档严格按照规范。时间长了基本上就不需要看文档了，或者你拿旧项目文档稍微改改就是一份新项目的文档。
|
 |
78
openbsd 2021-12-10 08:33:13 +08:00
娶了前端，从此沟通再无障碍 [狗头]
|
 |
79
xqk111 2021-12-10 09:04:56 +08:00
写好开发文档就行，先找找自己的问题
|
 |
81
Donquixote0917 2021-12-10 10:14:58 +08:00 1
|
 |
82
jones2000 2021-12-10 11:11:54 +08:00 1
给前端写一个对接好的 js 库， 所有数据都你自己对接好，前端只需要实例化对应的数据对接库， 就可以用， 不需要关心你的接口。
|
 |
83
listkun 2021-12-10 15:54:44 +08:00
swagger-ui
|
 |
84
buyuw 2021-12-10 16:40:09 +08:00
和前端商量好大部分通用字段,然后给他一个 swagger 文档 /swagger url,尽量写清楚用途 目的 示例,(大概)就能减少很多交流问题了
|
 |
85
ffw5b7 2021-12-10 16:40:24 +08:00 via Android
yapi 也可以生成，有 idea 插件，没有 swagger 那样侵入。 分析设计，定义好接口沟通确认下，同步开发。
|
Select Language