概述
在项目开发中，web项目的前后端分离开发，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。
一、为什么要写接口文档？
- 正规的团队合作或者是项目对接，接口文档是非常重要的，一般接口文档都是通过开发人员写的。一个工整的文档显得是非重要。
- 项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发，项目维护中或者项目人员更迭，方便后期人员查看、维护
二、接口规范是什么？
首先接口分为四部分：方法、uri、请求参数、返回参数
-
方法:新增(post) 修改(put) 删除(delete) 获取(get)
-
接口详情 地址 www.baidu.com 方式 GET -
uri：以/a开头，如果需要登录才能调用的接口(如新增、修改；前台的用户个人信息，资金信息等)后面需要加/u，即：/a/u；
中间一般放表名或者能表达这个接口的单词；get方法，如果是后台通过搜索查询列表，那么以/search结尾，如果是前台的查询列表，以/list结尾；url参数就不说了中间一般放表名或者能表达这个接口的单词；get方法，如果是后台通过搜索查询列表，那么以/search结尾，如果是前台的查询列表，以/list结尾；url参数就不说了 -
请求参数和返回参数，都分为5列：字段、说明、类型、备注、是否必填
字段是类的属性；说明是中文释义；类型是属性类型，只有String、Number、Object、Array四种类型；
备注是一些解释，或者可以写一下例子，比如负责json结构的情况，最好写上例子，好让前端能更好理解；是否必填是字段的是否必填。 -
返回参数结构有几种情况：
-
返回接口调用成功还是失败（如新增、删除、修改等），如下图：
返回结果 格式 JSON 状态码 200 success(成功) 状态码 500 error(失败) 状态码 501 param error(参数错误) … … … -
如果要返回某些参数，则有两个结构体：1是code/mesage/data，2是data里写返回的参数,data是object类型；
-
如果要返回列表，那么有三个结构体，1是code/mesage/data,data是object，里面放置page/size/total/totalPage/list 5个参数，其中list是Arrary类型，list里放object，object里是具体的参数。
注意：uri地址里不允许出现大写字母，如果是两个单词拼接，用/分开
-
三.如何合理设计接口？
一、 设计原理
- 深入了解需求:从“客户端-接口-数据库”的层次上看，接口明显扮演着承上启下的角色，一方面要明白接口要什么数据，另一方面要考虑如何从数据库获取、组织数据。所以如果不了解需求，你就无法正确抽象对象来组织数据给客户端，也无法验证数据库的数据结构能否满足需求。
- 了解数据库结构:既然接口要明白如何从数据库获取、组织数据，就当然要了解数据库结构啦。
- 了解客户端原型:了解原型，其实更多是为了帮助你设计接口时需要提供的数据和结构。
二、设计原则
- 充分理由:不是随便一个功能就要有个接口，也不是随便一个需求就要加个接口。每新建一个接口，就要有充分的理由和考虑，无意义的接口不仅增加了维护的难度，更重要是对于程序的可控性的大大降低，接口也会十分臃肿。
- 职责明确:一个接口只负责一个业务功能，比如查询会员，但不要在查询会员的同时还有修改权限等类似的其他业务功能，应该分成两个接口做。
- 高内聚低耦合:一个接口要包含完整的业务功能，而不同接口之间的业务关联要尽可能的小。
- 分析角度明确:设计接口分析的角度要统一明确。否则会造成接口结构的混乱。
- 入参格式统一:所有接口的参数格式要求及风格要统一，不要一个接口参数是逗号分隔，另一个就是数组;不要一个接口日期参数是x年x月x日风格，另一个就是x-x-x。
- 状态及消息:提供必要的接口调用状态信息。调用是否成功?如果失败，那么失败的原因是什么。这些必要的信息必须要告诉给客户端。
- 控制数据量:一个接口返回不应该包含过多的数据量，过多的数据量不仅处理复杂，对数据传输的压力也非常大，会导致客户端反应缓慢。过多的数据量很多时候都是接口划分不明确。
最后
以上就是细心耳机为你收集整理的什么是接口文档，如何写接口，有什么规范？的全部内容，希望文章能够帮你解决什么是接口文档，如何写接口，有什么规范？所遇到的程序开发问题。
如果觉得靠谱客网站的内容还不错，欢迎将靠谱客网站推荐给程序员好友。
发表评论 取消回复