前后端分离，关于接口文档，后端是要先写好接口文档，再进行写代码开发，还是写完代码后再编写接口文档？

Question

你好，我想问，正常的流程 接口文档是要后端先定义接口，编写文档，给前端和测试，然后后端按着接口文档写代码，设计数据库进行开发吗？
还是先写代码，设计数据库，开发完代码后再写接口文档？

Answer 1

1、先理清业务流程
2、定义前后端开发的接口规范。比如json的格式，url的格式
3、定义接口文档，这里的接口文档一般就是对应后台的实体reqVo（调用后台接口<控制器>访问的实体）和返回给前台的respVo（前台调用接口的返回的实体）。注意一般respVo都会有在后台做一个统一的处理为ResultVo（这个规范在2中要定义好，比如：错误码，错误描述，请求的url，请求时间，以及实体T<这个实体才是真正的respVo和业务相关,这个一般都是实体>）
4、定义接口文档是在了解业务流、数据流基础之上完成的。有了这个接口文档（其实就是定义实体的过程和对应的json）前后端的开发基本按照这个文档去开发。接口文档会有版本迭代，一般放到svn上，供所有开发人员阅览
5、现在一般系统用到的数据库都不会是单纯mysql了。还有redis，mongo、es等。这些个人感觉都是在十分了解业务的情况和系统架构下去设计的。后台运用这些工具去完成接口功能的实现已经系统功能和性能的实现。这个和接口文档先后顺序还真不好说，个人觉得都可以。
6、业务流-数据流-资金流。去了解和设计系统。追问

你好，按你的意思就是先理清业务流程，定义接口规范，再数据库设计实体，编写接口文档，写好接口文档后再开发写业务代码吗？ 还是写完接口和业务代码后再编写业务代码？
还有你说的前后端的开发基本按照这个文档去开发，是指代码开发吗？开发的流程接下来的流程是怎样的，可以详细说一下吗？ 还有下面的回答返回数字0和1是什么意思？你有接口文档例子和开发流程可以让我参考看下吗？谢谢。

追答

1、系统架构的思想。业务流-数据流-资金流
2、代码编写再最后，数据库的设计和接口文档的顺序看情况。业务很清楚了，可以同时进行。业务不清楚和没有定义接口校验的人可以先建库再来定义接口文档。
3、定义好借口文档的目的是让团队中的前后端人员尽快进入开发流程，无论如何功能代码都应该放到最后，架构代码一般架构或者技术lead在技术讨论和系统基盘的时候会写一下（这个过程应该会在接口文档同时）
4、下面提问的1、0不要去理会。那都是实现细节。按照接口文档实现功能即可。在开发工程中，技术lead会对你的点质量进行校验（也就是代码质量和功能）
5、没有具体的流程。要根据团队的人数、角色和工作情况来定。

追问

你好，感谢的你回答。你说的“代码编写再最后”是指业务的功能代码是在最后编写吗？定义接口文档是由后端开发人员来编写的吗？还是技术经理或领导之类的去编写？编写好接口文档交给前端开发，后端也是按照接口文档去开发功能代码吗？

另外接口文档内容是怎样子的？你有没有例子和接口文档案例可以让我参考一下，我想学习怎么写接口文档，谢谢。

追答

1、功能代码放到最后编写

2、接口文档其实就是根据理解一个功能点后的根据后台实体编写。这个可以给模板后由初级或者是实习编写（现在也可有用swagger2来直接根据controller来完成）

3、接口文档写好后，前后端都要根据这个来实现数据的请求和后台数据的返回。这个就是前后端交流的桥梁。后面联合测试也会根据接口文档来完成。当然在开发过程中有修改及时更新接口文档并广而告之

4、网页链接这是支付宝的接口文档你可以按照它的格式来。不外乎：介绍、请求地址和请求方式、入参、出参、错误码等等。

Answer 2

两种方式都是可以的,针对不同的团队有不同的选择

一般对于需求分析,设计能力比较强,的团队,推荐使用契约优先的设计模式,也就是先编写接口文档,规定好接口的 请求类型/参数数量/参数类型/返回结果的格式然后搭建模拟服务,然后前后端分别开发,但是这种方式需要比较高的设计能力,以应对需求的变更,设计时需要考虑的方面很多,适合于成熟的团队.
如果需求不确定性较高,甚至频繁变动,上面这种方式,就会有局限性,频繁的需求变更带来的就是频繁的接口契约变更.会拖慢前后端的开发进度,这种时候可以采用,先开发后编写文档的流程,由于频繁的发生变更,这时候团队的沟通显得很重要,项目管理人员一定要十分注意前后端开发的沟通效率,不然项目进度会变得不可控

Answer 3

先设计数据库，你写接口就是访问数据库，返回 数据库的数据和自己处理的拼接而成的数据。
再根据返回的数据写接口文档。例如你少了条件就返回 0 ，成功访问数据库并处理 返回1， 其他的什么情况返回什么数字。 这些返回的数字，就写在文档里，返回什么，代表什么意思。大概这样子 。追问

你好，按你的意思就是先理清业务流程，定义接口规范，再数据库设计实体，编写接口文档，写好接口文档后再开发写业务代码吗？ 还是写完接口和业务代码后再编写业务代码？

还有你说的前后端的开发基本按照这个文档去开发，是指代码开发吗？开发的流程接下来的流程是怎样的，可以详细说一下吗？ 还有上面的回答返回数字0和1是前后端开发经常用到的吗？你有接口文档例子和开发流程可以让我参考看下吗？谢谢。

Answer 4

百度一下你就知道百度一下你就知道百度一下你就知道百度一下你就知道百度一下你就知道百度一下你就知道百度一下你就知道百度一下你就知道百度一下你就知道百度一下你就知道百度一下你就知道百度一下你就知道百度一下你就知道百度一下你就知道百度一下你就知道百度一下你就知道百度一下你就知道百度一下你就知道百度一下你就知道百度一下你就知道百度一下你就知道