“ 高质量的规范文档是一个优秀设计系统的代表物”
“你这接口文档，谁能看懂啊，写的都是啥，能调通才怪呢！浪费我时间”
“你到底会不会看文档啊，调用方式，参数都给你写的很清楚了，年轻人，还需继续努力啊！”
"你..."
"我怎么..."
前端:后端,我要分手
气氛很不好，大家都看到了吧，现在项目都是前后端分离，相互之间沟通需要一个容易理解的接口文档。更糟的情况可能是想个相爱的程序员say goodbay。
01
—
如何理解接口？
当我们说到接口时，首先要分前端和后端，前端有Android、IOS、Js，后端定义返回值、参数、请求方式、协议等。系统A调用系统B，系统B调用系统C，像是把多个系统连接起来的一座桥梁，各自遵守相同的约定，但他本身是一种协议。它规范了传入的对象所必须具备的某些特征，从而保证在调用时既不会发生错误又不需要提前检查。
现实生活中的案例，比如插板上面有三个头的两个头的，手机充电器有usb的，typec的。那么在现实生活中的这些接口其实就是一种契约，连接两个物件，只要你按照接口的要求来做，就能和另外一个按照这个接口对应的物件相互连接。比如所有三头的插头都可以插入三个眼的插板，充电器也一样。
02
—
接口规范是什么？
接口五要素
1、接口数据格式(返回值)
返回值一般包括code状态码，message返回消息，data承载数据
为什么是返回这三个字段？
1、分层更明确
2、前端处理方便
除了这种方式，还有哪些方法可以实现返回值信息？
1、使用http status来标识
这样可以减少代码复杂度
2、接口参数
接口参数一般有字段名称、字段类型、是否必填、备注说明等字段
1、字段命名有什么要求？
首先推荐意义明确的单个单词
用驼峰式
用小写+下划线
后续接口改版，确保字段意思不丢失
2、为什么大部分类型定义都是string和int呢？
这其实是跟后端语言有关系，有的用java如果我不标明是什么类型，后端接收强转换可能会出错，这在代码中跟业务逻辑不相关的校验逻辑，这些事情其实是框架帮我们做的。
你们可以想一下为什么我们在接口文档中写了string我在后端java接收就是字符串了，前端会分这种类型吗？你看看url参数里面有区分这种是字符串还是数字吗？不会吧只不过我们在这种约定好之后，在写java代码时，约定这就是整型意思就是我拿整型parseInt这种方式，去接收这个参数，基本不会报错，如果报错，那就前端传错了。
这种方式叫做：约定大于配置，是Maven中非常重要的一个理念。如果我想减少这种错误，我任务双方都得遵守这种约定，你要传数字，肯定是12345678910这种数字。不会是张三李四这种字符串，这是一种约定。应该传数字的时候，你非要传字符串，那程序肯定会报错。这就是双方没有遵守这个约定。
什么叫做配置呢？在name中学号XX_XXX这种自解析可以理解为是一种配置加个type区分什么类型，我在写代码时候，大家都遵守这个约定走接口文档只有一份，其实开发中，可能会对接多个平台Android、IOS、前端都是遵循同一个接口文档去做事情。
3、为什么要有必须项？
后端接口设计到数据库字段，有些字段不能为空，如果不传程序机会出现错误。
4、备注和说明应该怎么写？
1、给人看的
2、如字段是枚举类型 A代表什么，B代表什么写清楚就行了。、
5、参数到底放url在后，还是放一个body里面
1、如果是按ID查询或者其他单个字段查询，建议放在url后面
2、表单提交查询，简单放body里面
6、为什么使用JSON作为返回值
常用有XML和JSON两种方式，那有没有比JSON更简洁的格式呢？
我们经常使用的Spring配置YML就是比JSON更简洁的文件。选择JSON其实设计方案一种均衡，比XML简洁，而且我们暂时不需要更简洁。
3、需要什么数据(具体请求的URL)
如：GET https//baidu.com/api/{模块名}/{?菜单名}/{接口名}/:param
具体数据是从域名后面开始，明确要取哪些数据。
一般协议+地址+端口号，文档里面不需要写死，可能会部署在多个域名下面，地址会变，一般提供后面方法即可。
4、HTTP方法：GET，POST、PUT、DELETE
定义接口请求方式，常用的有以下四种
5、协议(http、https)
大致分http接口、api接口、RPC接口、RMI、webservice、Restful等
03
—
什么时候写接口文档？
1、方案评审之前？方案评审之后？
这里分两个方面：
1、对业务和系统比较熟悉的，需求出来之后，方案不用想，就知道接口怎么写了
2、没有经验的，方案评审之前前端和后台要把需要过一遍，确认接口信息(发起人，最好是前端)
3、方案评审后，有小的调整，可以直接修改。
2、接口到底怎么定，是否前后端一起定义？
1、客户端提接口需求(包括风格建议)
2、服务端出接口细节
