后端开发完接口才给接口定义, 是常规操作吗?

[Chingim]

最近加入了一个 1000 多人的中型公司, 在做项目的过程中, 后端不愿意先协商接口定义, 坚持等他开发完后才给接口文档, 理由是先给接口文档, 实现的过程中难免有变动, 改动起来很麻烦.

而作为前端, 我的理由是, 产品需求文档以及设计稿已经具备的情况下, 先约定接口定义, 前后端可以并行开发, 提高效率.

几番交涉之后还是没有达成一致, 现在是他开发一个接口, 给一个接口的文档.

之前就职的小公司是开发前给接口定义, 所有人评审接口之后再开发的. 我觉得效率很高, 定义好的接口, 开发过程中的改动也只是简单的增减, 不会有很大的变化.

是公司规模造成的开发流程差异吗? 请朋友们说说

我不是求认同, 也不需要 v 友站队.

我想要的是: 充分了解其他公司的协作流程, 充分了解其他后端同事对出具接口协议的看法，心智负担在何处。以及探讨怎么样才是合理的可实行的协作方案。

如果你没有探讨的想法，你可以保持沉默.

no war, make love

[lihongjie0209]

@reus
对于用户端的接口来说， 需求就是 doX 并发送短信

对于后台管理端的接口来说， 需求就是 doX


要理清楚需求，哪怕现在用户端和管理端的接口需求一样， 也必须分开， 因为这些都是可以预期的二者会往不同的方向发展

[hrx999]

有变动是必然的，没必要不理解。。。大概率是后端怕有变动后，你直接甩锅给他，结果变动也不是他的原因，平白无故背锅，所以干脆接口写完再给文档。

[lihongjie0209]

@reus
只有非常简单接口可以这么做

如果这个接口有前置接口依赖，那我是不会提前定义的， 我会和前端实时沟通并更新接口

[reus]

@lihongjie0209 那就塞进去啊，有什么问题？不想写到一起，就用钩子、埋点。可以异步的，就起异步任务。依赖关系复杂，就用依赖注入自动解决。对外的接口哪来什么“单一职责”？你发个短信，运营商做了再多事情，对你来讲，就是“发短信”这个职责。前端也一样，他知道你这个接口会 doX，会发通知，就行了。我没看出你说的这些，用一个接口实现有什么问题。

[reus]

@lihongjie0209 你拆开也可以，合并也可以，你的设计选择你负责就行。现在问题不是接口粒度或者接口怎么设计的问题，是接口应不应该先设计出来，前后端达成共识再开发的问题。

有前置的你就先把前置的设计了啊。你也知道前置的没做，就不提前做。现在楼主的情况是，他把“接口定义”看作是前置任务，结果后端说不给，那楼主只能在前置条件还没达成的时候，就上手做。他只能猜测前置会是怎样的，不能确定，那后面会怎样，你能理解了吧？如果前置的实现有偏差，你说是不是会多了无谓的工作量？

[lihongjie0209]

@reus
1. 依赖注入不能帮你解决依赖过多的问题
2. 前端不止需要知道接口会 doX， 他还需要知道有那些额外的参数来触发额外的钩子，埋点
3. 代码职责太多的表现就是在参数中有许多 flag

[lihongjie0209]

@reus
这个东西不是我定义好前端就能实现， 产品就能满意的， 一个复杂的流程必须要和前端还有产品沟通，做演示，提意见，一系列操作之后，你原来定义好的接口可能就面目全非了

所有人，包括产品经理都是在项目进行中不断学习，不断深入理解需求的，你提前把接口都定义的前置条件就是：

1. 所有人都对需求有 100%的理解
2. 后端定义的接口前端一定可以使用而不需要考虑前端使用的复杂度

但是上述的条件都是不成立的
第一点我已经说过了
第二点后端要考虑前端人员的技术水平以及项目进度。有时候前端觉得这个接口不符合他的使用习惯或者是难以使用， 后端应该尽可能的提供帮助来解决问题。


按照你的说法， 需求不变的情况下，前端因为其他问题需要后端改接口是不能的。因为后端接口只依赖于需求，不依赖于前端。
但现实情况是：
1. js 很垃圾， 后端可以简单实现的功能 js 要写一堆，依赖一大堆
2. 开发人员水平参差不齐，有些后端认为很简单的实现对于和你对接前端来说很困难

我们要做的就是接受这种现实，不是说吐槽后端不行或者是前端不行，而是说大家作为一个团队要及时沟通和相互帮助来完成我们的项目。

[atonku]

反正前端就是三句话，我不管，弄不了，找后端

[Chingim]

@atonku 你说的这些对讨论主题有帮助吗?

[Sczlog]

可以先写一层处理数据的接口，对于后台所有传过来的数据都用自己的接口转一下，前端用另一套自己的 model 类，这样后台修改你只需要改这个接口就行了，页面上的就没有必要修改了。

[tiedan]

后端定接口文档->前后端一起评审文档，修改接口定义

[reus]

@lihongjie0209 产品需求不能相对稳定，那当然是没法做。产品需求本身也是接口文档的前置条件。但题主的情况是“产品需求文档以及设计稿已经具备”，这就和你说的折腾需求不是一回事。

我从来没有表达过“需求不变的情况下，前端因为其他问题需要后端改接口是不能的”这种意思。前端如果有需要，后端可以提供协助，可以加接口，可以加字段。我是说先出接口定义，哪有说过不能改动？

其实吧，如果前后端全程参与产品讨论，定个接口也就几分钟的事情，你需求变化再快，几分钟都拿不出么……

[lihongjie0209]

@reus 需求就没有稳定这一说，只能说有个大方向， 具体细节还是要在开发者不断改的

[TommyLemon]

这是互联网开发中普遍存在的问题，以上各种回答都是治标不治本，有的还容易引发同事间的矛盾。

建议使用 APIJSON 轻松且彻底解决前后端关于接口的各种恼人的问题。


# 对于前端
* 不用再向后端催接口、求文档
* 数据和结构完全定制，要啥有啥
* 看请求知结果，所求即所得
* 可一次获取任何数据、任何结构
* 能去除重复数据，节省流量提高速度

# 对于后端
* 提供通用接口，大部分 API 不用再写
* 自动生成文档，不用再编写和维护
* 自动校验权限、自动管理版本、自动防 SQL 注入
* 开放 API 无需划分版本，始终保持兼容
* 支持增删改查、模糊搜索、正则匹配、远程函数等

# 在线解析
* 自动生成接口文档，清晰可读永远最新
* 自动生成请求代码，支持 Android 和 iOS
* 自动生成 JavaBean 文件，一键下载
* 自动管理与测试接口用例，一键共享
* 自动校验与格式化 JSON，支持高亮和收展



码云最有价值开源项目：后端接口和文档自动化，前端(客户端) 定制返回 JSON 的数据和结构！
GitHub 右上角点 Star (5.6K) 支持下吧 ^_^
https://github.com/TommyLemon/APIJSON

[TommyLemon]

@bangq
@zjp
@kevinlm
@also24
@changdy
@kidtest
@hyyou2010
@AngryMagikarp
@rizon
@metrxqin
@Sanko
@Sparetire
@dajj
@scnace
@ackfin01
@johnhsm2333
@hantsy
@justfindu
@wweir
@a0000
@owt5008137
@ala2008
@Gea
@siteshen
@aa1072551507
@rockagen
@kulove
@hrx999
@Sczlog
看上面回答，用 APIJSON，
后端不用写接口、也不用写文档就能提供"接口"和"文档"，
前端(客户端)不用看"文档"就能调用"接口"。

后端：零用时开发接口、零沟通零被打扰。
前端(客户端)：内容可任意组合、结构可任意嵌套、零沟通零打扰零等待。

不需要 Mock，也不需要约定，直接调用完全自动化的 API 实现需求。

[atonku]

@Chingim 所以你想要的结果是什么，必须站一方？那你准备是找领导提意见，还是跳槽到按照你的套路来的下一家公司。这样的问题，无非是让网友说一句“没有这样的，赶紧跳”或者“都是这样的，老实呆着”？至于解决方案，说真的，不是领导的话，真的实施不起来，而且领导也没有那么容易推动一件事情。

[TimLang]

@TommyLemon 我们在用 apizza.net ，国内版的 postman,直接能调用接口其实可以降低很多沟通成本，并且文档也直接写上面很方便。

[viator42]

可以，但必须把前端开发的时间单独拿出来算，从他提供接口之后开始算时间
不然的话要求一周之内上线他摸鱼到周五下午才给你接口你怎么办

[ksssdh123]

@TommyLemon 只要查找 接口 这个关键词 哪都有你 快成牛皮鲜了 哈哈
话说 你对于 graphql 怎么看？

[huijiewei]

后端想偷懒呗

约定接口定义需要动脑子和充分的交流

[idamien]

通常是因为后端都不知道自己需要啥，也在摸索。。。

当然流程方面很不正规 这估计也是某些公司的通病

[TommyLemon]

@TimLang
APIJSON 并不是一个接口工具哦，它是一个自动化接口和文档的 ORM 库，
后端不用写接口、也不用写文档就能提供"接口"和"文档"，
前端(客户端)不用看"文档"就能调用"接口"。

第二张是 APIJSON 生态内 自动化接口管理工具 APIJSONAuto 的截屏，
APIJSONAuto 才是类似 Postman 的接口工具，但整体要更强大易用很多。

自动化接口管理工具，自动生成代码、自动静态检查、自动化回归测试、自动生成文档与注释等。
可以点 Star 支持下哦 ^_^
https://github.com/TommyLemon/APIJSONAuto/

[TommyLemon]

@ksssdh123 有对比
https://github.com/TommyLemon/APIJSON/issues/2

[haohappy]

@TommyLemon APIJSON 是直接操作数据库并返回结果吗？那后端还需要做什么？

[TommyLemon]

@haohappy
可以直接操作，也可以中间加数据库中间件等。
前端传请求 JSON，后端自动转换为 SQL 语句连接数据库并执行 CRUD，
然后返回对应结构和内容的 JSON，
期间自动校验角色及对应的操作权限、自动防 SQL 注入。

CRUD 可以自动化，但特定的业务逻辑还是需要后端写 远程函数 来实现的

[TommyLemon]

@huijiewei 想偷懒可以用 APIJSON，不用写代码也能提供“接口”和“文档”，具体见 #144 楼回答

[haohappy]

@TommyLemon 牛逼 以后 1 个后端可以对接 10 个前端了

[TommyLemon]

@haohappy 哈哈

[ruandao]

需求有了， 为什么你会需要后端给接口？

直接一个静态 web 服务器， 然后 放 json 文件， 想要怎么返回不是很容易的事情吗？

你不知道有什么字段吗？ 为什么需要后端提供？

[smilepig]

个人认为 后端先定义好接口，然后再开发比较好，
方便前端接入，前端也能更早的发现接口是否满足需求，出现问题可以早点发现，修改；

但是有时候后端不可避免的在实现过程中因为种种需求变更或者考虑不周，修改接口定义，前端如果乐意修改比较好，就怕有些前端会嚷嚷：你怎么老是改接口，我刚接好你又改了。。。

[Chingim]

@atonku 我想要的是: 充分了解其他后端同事对出具接口协议的看法，心智负担在何处。以及探讨怎么样才是合理的可实行的协作方案。

如果你没有探讨的想法，你可以保持沉默，而不是阴阳怪气

[Chingim]

@ruandao 这么说前后端不需要协作了？

[silenM]

先给接口定义没问题 我们公司也这样 在写的过程中如有调整 知会下前端 修改下文档就好了 这更多是一个沟通问题我觉得

[TommyLemon]

@smilepig
@silenM
用 APIJSON 这些问题就解决了，具体见 #144 楼回答

[ruandao]

画完界面，回头后端完成后，再适配下

[summersnow521]

不是常规操作

[skadi]

看情况...如果业务简单,或者不大可能会改的就提前定好接口.

如果是业务确实复杂,或者很有可能会改的.那么给个大致的接口,比如主要数据,具体细节看情况.

[dabaibai]

全栈路过

[MonoLogueChi]

我是客户端，后端的接口形式都是我来定的

[darkbill]

@reus 我不是写 Web 的，我是写 MCU 的，但我也非常赞成你的做法。

拼数据这种根据不同项目 /前端（ Web/App 等）有不同项目的做法，当然是放到项目 /前端层面来做。他们都应该懂得根据业务的需求，选择合适的流程（同步 /异步 /实时 /时间不敏感）去获取相应的数据，并拼接展示。
后端也好，设备也好，根据业务需求，在写完之后就都尽量固化了，即使升级，也是需要考虑不少向前兼容的问题。一般来说，只会增，不会减。
初期来说，后端一般只需要提供合适的 CRUD 接口就可以了；随着业务的发展，后端可根据前端提出的合理需求（ eg. 跨表查询 /实时任务），再增加相应的功能。

[dioxide]

觉得接口定义应该以前端定义为主, 但随后要一起评审.

[loveCoding]

必须先给出接口文档

[guanhui07]

可以先出接口文档，后面也有可能修改