写给产品的技术科普——API 接口

自从做了研发类产品，老有童鞋找我问什么是接口什么是前端后端，回答次数多了，想着所幸写一篇出来，希望对更多人有所帮助

接口的缘起

很久以前，页面没有现在这么花狸狐哨，以静态为主，最原始的开发模式，应该是不分什么前后端的，可能只有 “xx开发工程师”，Java 程序员一个人从底层存储到逻辑到前端交互全写了，所谓全栈、全能啊。

但是万物发展规律都是——事态越来越复杂，各自分工做专长的事情最为高效，因此前后端分离了。

『后端』 即 服务端，负责做数据的存储，业务功能逻辑的实现，常和数据库、服务器、环境打交道；

『前端』广义来讲，包括 Web 前端、iOS 及 Android 等客户端、RN 及 Flutter 等跨端开发，负责页面的实现，包括页面的框架结构、UI 样式，以及用户行为的交互逻辑反馈，所以更着重处理用户体验相关的事情。

那后端开发好这些功能，怎么给用户用呢？不能让用户输入代码吧，铛铛铛，这就是『接口』上场的时候啦！！

接口工作的原理

API，Application Programming Interface，直译就是应用程序接口嘛，还是听不懂对不对？其实可以这么理解，用户和界面交互的过程 就是 前端通过某个东西（比如ajax）调用后端写好的接口（比如 restful API） 进行 数据交互 的过程。所以说，接口即服务、接口即能力。

什么是接口文档

一般产品需求评审之后，各端同学开始真正开发之前，会先规定好怎么传输数据，传什么样的数据，这个规定就是『接口文档』。
不规定这个东西会肿么样？相信我，前后端会打架的。前端埋怨后端：“我要是的xx，你这返回的是啥？” 后端也会气死：“不是说好的xxx吗？怎么xxx？！” 真实工作中，即便是有这份接口规定，测试阶段也会有一堆 bug 是和接口定义沟通有关。

言归正传，接口文档一般包含：接口基本信息、请求头、请求体（入参）、返回值（出参）、示例等几部分。

（1）基本信息：包括接口名称、URL、请求方式、描述

• URL可理解为接口的地址 ID，规定了前端去哪儿请求数据。如：api/queryOrder

• 请求方式类似指 提交数据（POST）、读数据（GET）、更新数据（PUT）、删数据（DELETE）什么的，不用了解太细，常用的一般就是POST和GET，数据一般不会轻易删除，所以 DELETE 用得较少。

（2）请求头 Header

• 负责一些比较全局的规定，比如用 Accept 指定客户端能够接收的内容类型，对于产品来说其实不用太了解。

（3）入参/请求内容/请求体 Body

• 请求体就是前端请求这个接口时需要给的字段规则；
• 包括：入参字段名 Value、含义、字段类型、是否必填、格式、长度规则等等。

（4）出参/返回值/响应体 Response

• 返回值就是服务端同学根据请求内容传回具体的信息，一般包括请求结果、状态码以及返回值等。
• 请求结果是指是否成功，success 为 true 还是 false；
• 状态码 code 和状态消息 msg 是一一对应的，一般会统一管理；
• 返回值一般是封在一个 data 的数组或者对象里，包括字段名、描述、字段类型等。
• 入参和返回值是最和产品需求相关的部分，如果产品同学懂数据结构，和研发交流起来就会更 easy～

举个栗子

比如你买火车票时，输入乘车时间、出发站、到达站、车次等条件后，就会得到一个火车票列表。此时就是用到了查询火车票列表接口。那么这份接口文档一般如下：

• 基本信息：
  URL：xxxxx/trains
  类型：GET
  接口描述：火车票列表查询接口，根据始发站等条件获取火车票列表数据

• 入参：
  参数名 | 必填 | 类型 | 说明
  --|--|--|--
  from_stationID | Long | Y | 出发站ID
  to_station | Long | Y | 到达站ID
  train_date | Date | Y | 乘车日期，格式：yyyy-MM-dd
  train_code | String | N | 车次号
  purpose_code | String | Y | 车票类型，枚举，成人票ADULT，学生票STUDENT

（你会发现，其实是否必填就对应了你点击 搜索 按钮是否会弹窗提醒“请输入xx”）

• 出参：
  参数名|类型|说明
  --|--|--
  map|object|出发到达信息
  result|array|车次查询结果

最后

这些接口，都是HTTP协议的REST风格才这样，不走这个协议 风格就不一样了。不过不太常见，不用管。原理都是一样的。

现在大型公司，业务复杂，这个部门需要调用那个部门的能力的时候，走的微服务，我感觉本质都是一样的。封装好后开放出来，使用者按规则按需就可以调用。

有什么问题欢迎留言，有错误欢迎指正，有别的问题也欢迎来问～