一份完整的接口文档

不表于情

已于 2024-02-29 15:16:07 修改

阅读量6.7k

点赞数 2

文章标签：软件测试

于 2019-11-22 10:51:41 首次发布

本文链接：https://blog.csdn.net/weixin_42575367/article/details/103196913

版权

一、什么是接口文档？

在项目开发中，web项目的前后端分离开发，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。

来自

API（Application Programming Interface）即应用程序接口。可以认为 API 是一个软件组件或是一个 Web 服务与外界进行的交互的接口。目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。从另一个角度来说，API 是一套协议，规定了我们与外界的沟通方式：如何发送请求和接收响应。

接口分为四部分：方法、uri、请求参数、返回参数

1、方法:新增(post) 修改(put) 删除(delete) 获取(get)

2、uri：以/a开头，如果需要登录才能调用的接口(如新增、修改；前台的用户个人信息，资金信息等)后面需要加/u，即：/a/u；中间一般放表名或者能表达这个接口的单词；get方法，如果是后台通过搜索查询列表，那么以/search结尾，如果是前台的查询列表，以/list结尾。

3、请求参数和返回参数，都分为5列：字段、说明、类型、备注、是否必填

字段是类的属性；说明是中文释义；类型是属性类型，只有String、Number、Object、Array四种类型；备注是一些解释，或者可以写一下例子，比如负责json结构的情况，最好写上例子，好让前端能更好理解；是否必填是字段的是否必填。

4、返回参数结构有几种情况：1、如果只返回接口调用成功还是失败（如新增、删除、修改等），则只有一个结构体：code和message两个参数；2、如果要返回某些参数，则有两个结构体：1是code/mesage/data，2是data里写返回的参数,data是object类型；3、如果要返回列表，那么有三个结构体，1是code/mesage/data,data是object，里面放置page/size/total/totalPage/list 5个参数，其中list是Arrary类型，list里放object，object里是具体的参数。

槽糕的API接口各种各样，但是好的API接口对于用户来说必须满足以下几个点：

• 易学习：有完善的文档及提供尽可能多的示例和可copy－paste的代码，像其他设计工作一样，你应该应用最小惊讶原则。

最小惊讶原则(Principle of least astonishment)

最小惊讶原则通常是在用户界面方面引用，但同样适用于编写的代码。代码应该尽可能减少让读者惊喜。也就是说，你编写的代码只需按照项目的要求来编写。其他华丽的功能就不必了，以免弄巧成拙。

• 易使用：没有复杂的程序、复杂的细节，易于学习；灵活的API允许按字段排序、可自定义分页、排序和筛选等。一个完整的API意味着被期望的功能都包含在内。

• 难误用：对详细的错误提示，有些经验的用户可以直接使用API而不需要阅读文档。

而对于开发人员来说，要求又是不一样的：

• 易阅读：代码的编写只需要一次一次，但是当调试或者修改的时候都需要对代码进行阅读。

• 易开发：个最小化的接口是使用尽可能少的类以及尽可能少的类成员。这样使得理解、记忆、调试以及改变API更容易。

一、设计原理

1. 深入了解需求

除了设计数据库的人最了解需求外，其次就是设计接口的人了，甚至有时接口开发人员还要参与到数据库设计中。从“客户端-接口-数据库”的层次上看，接口明显扮演着承上启下的角色，一方面要明白接口要什么数据，另一方面要考虑如何从数据库获取、组织数据。所以如果不了解需求，你就无法正确抽象对象来组织数据给客户端，也无法验证数据库的数据结构能否满足需求。数据库设计者要了解需求中的数据结构，而接口则更多的要了解需求中的逻辑结构以及由此衍生出的逻辑数据结构。

2. 了解数据库结构

既然接口要明白如何从数据库获取、组织数据，就当然要了解数据库结构啦。

3. 了解客户端原型

了解原型，其实更多是为了帮助你设计接口时需要提供的数据和结构。但有时当你设计时并没有原型，所以此条并不是必须要求的。但假如设计完接口后原型出来了，我们也可以拿原型还验证接口设计是否正确、合理。

二、设计原则

1. 充分理由

不是随便一个功能就要有个接口，也不是随便一个需求就要加个接口。每新建一个接口，就要有充分的理由和考虑，即这个接口的存在是十分有意义额价值的，无意义的接口不仅增加了维护的难度，更重要是对于程序的可控性的大大降低，接口也会十分臃肿。因此我放在了第一条。

2. 职责明确

一个接口只负责一个业务功能，它与设计模式里的职责单一原则类似但却不同，因为一个业务功能里可能会包含多个操作，比如查询会员，可能除了查询会员表外还要获取该会员的其他必要信息，但不要在查询会员的同时还有修改权限等类似的其他业务功能，应该分成两个接口还做。

3. 高内聚低耦合

一个接口要包含完整的业务功能，而不同接口之间的业务关联要尽可能的小。还是查询会员的例子，有时查询会员的同时，可能该会员的相关信息要随之发生变化(如状态)，如果这时一条完整的业务流水线，那么就应该在一个接口里完成，而不应再单独设立接口去操作完成。就是说一个接口不应该随着另一个变化而变化或以某几个接口为前提而存在。

4. 分析角度明确

设计接口分析的角度要统一明确。否则会造成接口结构的混乱。例如，不要一会以角色的角度设计，一会儿就要以功能的角度设计。

5. 入参格式统一

所有接口的参数格式要求及风格要统一，不要一个接口参数是逗号分隔，另一个就是数组;不要一个接口日期参数是x年x月x日风格，另一个就是x-x-x。

6. 状态及消息

提供必要的接口调用状态信息。调用是否成功?如果失败，那么失败的原因是什么。这些必要的信息必须要告诉给客户端。

7. 控制数据量

一个接口返回不应该包含过多的数据量，过多的数据量不仅处理复杂，对数据传输的压力也非常大，会导致客户端反应缓慢。过多的数据量很多时候都是接口划分不明确。

8. 禁止随意拓展参数

与第1条类似，只不过是针对参数而言了。日后拓展接口可能是难以避免的，但是不要随意就加参数，加参数一定是必要且有意义的，需求改变前首先应考虑现有接口内部维护是否能满足需求，而不要通过加个参数来方便自己实现需求的难度，因为参数的更变会直接导致客户端调用的变化，易产生版本兼容性问容题。

三、设计方法

1. 抽象业务