由于交付周期的缘故原由，接入了一个第三方的库，碰着了这么一些问题：文档老旧，并且不足全面。这个问题比较于没有文档来说，愈加的恐怖。我们须要的接口不在文档上，文档上的接口不存在库里，又或者是少了一行关键的代码。
对付一个库来说，文档是多种多样的：一份 demo、一个入门指南、一个 API 列表，还有一个测试。如果一个 API 有测试，那么它也相称于有一份大略的文档了——如果我们可以看到测试代码的话。而当一个库没有文档的时候，它也不会有测试。
在前后端分离的项目里，API 也是这样一个烦人的存在。我们就常常碰着各种各样的问题：
API 的字段更新了
API 的路由更新了
API 返回了未预期的值
API 返回由于某种缘故原由被删除了
。。。
API 的掩护是一件烦人的事，以是最好能一次设计好 API。可是这是不可能的，API 在其的生命周期里，该当是要不断地演进的。它与精益创业的思想是相似的，当一个 API 不得当现有场景时，该当对这个 API 进行更新，以知足需求。也因此，API 本身是面向变革的，问题是这种变革是双向的、单向的、联动的？还是静默的？
API 设计是一个非常大的话题，这里我们只谈论：演进、设计及掩护。
前后端分离 API 的演进史
刚毕业的时候，事情的紧张内容是用 Java 写网站后台，业余写写自己喜好的前端代码。逐步的，随着各个公司的 Mobile First 计策的履行，项目上的紧张措辞变成了 JavaScript。项目开始履行了前后端分离，团队也变成了全功能团队，前端、后台、DevOps 变成了每个人须要提高的技能。于是如我们所见，当我们完成一个任务卡的时候，我们须要自己完成后台 API，还要编写相应的前端代码。
只管当时的手机浏览器性能，已经有相称大的改进，但是仍旧会存在明显的卡顿。因此，我们在设计的时候，尽可能地便将逻辑移到了后台，以减少对付前端带来的压力。可性能问题在本日看来，差异已经没有那么明显了。
犹如我在《RePractise：前端演进史》中所说，前端领域及 Mobile First 的变革，引起了后台及 API 架构的一系列演进。
最初的时候，我们只有一个网站，没有 REST API。后台直接供应 Model 数据给前端模板，模板处理完后就展示了干系的数据。
当我们开始须要 API 的时候，我们就会采取最大略、直接的办法，直接在原有的系统里开一个 API 接口出来。
为了不毁坏现有系统的架构，同时为了更快的上线，直接开出一个接口来得最为直接。我们一贯在这样的模式下事情，直到有一天我们就会创造，我们碰着了一些问题：
API 消费者：一个接口无法同时知足不同场景的业务。如移动运用，可能与桌面、手机 Web 的需求不一样，导致接口存在差异。
API 生产者：对接多个不同的 API 需求，产生了各种各样的问题。
于是，这时候就须要 BFF（backend for frontend）这种架构。后台可以供应所有的 MODEL 给这一层接口，而 API 消费者则可以按自己的须要去封装。
API 消费者可以连续利用 JavaScript 去编写 API 适配器。后台则逐步的由于须要，拆解成一系列的微做事。
系统由内部的类调用，拆解为基于 RESTful API 的调用。后台 API 生产者与前端 API 消费者，已经区分不出谁才是真正的开拓者。
瀑布式开拓的 API 设计
说实话，API 开拓这种活就和传统的瀑布开拓差不多：未知的前期设计，痛楚的后期集成。好在，每次这种设计的周期都比较短。
新的业务需求来临时，前端、后台是一起开始事情的。而不是后台在前，又或者前端先完成。他们开始与业务职员沟通，须要在页面上显示哪些内容，须要做哪一些转换及分外处理。
然后便合营着去设计相应的 API：要求的 API 路径是哪一个、要求里要有哪些参数、是否须要鉴权处理等等。对付返回结果来说，仍旧也须要一系列的定义：返回哪些相应的字段、额外的显示参数、分外的 header 返回等等。除此，还须要谈论一些非常情形，如用户授权失落败，做事端没有返回结果。
整理出一个相应的文档约定，前端与后台便去编写相应的实当代码。
末了，再经历痛楚的集成，便算是能完成了事情。
可是，API 在这个过程中是不断变革的，因此在这个过程中须要的是协作能力。它也能从侧面地反响中，团队的协作水平。
API 的协作设计
API 设计该当由前端开拓者来驱动的。后台只供应前端想要的数据，而不是反过来的。后台供应数据，前端从中选择须要的内容。
我们常报怨后台 API 设计得不合理，紧张便是由于后台不知道前端须要什么内容。这就彷佛我们接到了一个需求，而 UX 或者美工给老板见过设计图，但是并没有给我们看。我们能设计出符合需求的界面吗？答案，不用想也知道。
因此，当我们把 API 的设计交给后台的时候，也就意味着这个 API 将更符合后台的需求。那么它的设计就趋向于对后台更大略的结果，比如后台返回给前端一个 Unix 韶光，而前端须要的是一个标准韶光。又或者是反过来的，前端须要的是一个 Unix 韶光，而后台返回给你的是当地的韶光。
与此同时，按前端职员的假设，我们也会做类似的、『禁绝确』的 API 设计。
因此，API 设计这种活动便像是一个博弈。
利用文档规范 API
不论是异地，或者是坐一起协作开拓，利用 API 文档来确保对接成功，是一个“低本钱”、较为通用的选择。在这一点上，利用接口及函数调用，与利用 REST API 来进行通讯，并没有太大的差异。
先写一个 API 文档，双方一起来掩护，文档放在一个公共的地方，方便修正，方便沟通。逐步的再随着这个过程中的一些变革，如无法供应事先定好的接口、不须要某个值等等，再去修正接口及文档。
可这个时候由于没有一个可用的 API，因此前端开拓职员便须要自己去 Mock 数据，或者搭建一个 Mock Server 来完成后续的事情。
因此，这个时候就涌现了两个问题：
掩护 API 文档很痛楚
须要一个同步的 Mock Server
而在早期，开拓职员有同样的问题，于是他们有了 JavaDoc、JSDoc 这样的工具。它可以一个根据代码文件中中注释信息，天生运用程序或库、模块的API文档的工具。
同样的对付 API 来说，也可以采纳类似的步骤，如 Swagger。它是基于 YAML语法定义 RESTful API，如：
Swagger代码
swagger:\"大众2.0\"大众
info:
version:1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
- https
host: simple.api
basePath: /openapi101
paths: {}
它会自动天生一篇排版幽美的API文档，与此同时还能天生一个供前端职员利用的 Mock Server。同时，它还能支持根据 Swagger API Spec 天生客户端和做事真个代码。
然而，它并不能办理没有人掩护文档的问题，并且无法及时地关照其余一方。当前端开拓职员修正左券时，后台开拓职员无法及时地知道，反之亦然。但是持续集成与自动化测试则可以做到这一点。
左券测试：基于持续集成与自动化测试
当我们定好了这个 API 的规范时，这个 API 就可以称为是前后端之间的左券，这种设计办法也可以称为『左券式设计』。（定义来自维基百科）
引用
这种方法哀求软件设计者为软件组件定义正式的，精确的并且可验证的接口，这样，为传统的抽象数据类型又增加了先验条件、后验条件和不变式。这种方法的名字里用到的“左券”或者说“左券”是一种比喻，由于它和商业左券的情形有点类似。
按传统的『瀑布开拓模型』来看，这个左券该当由前端职员来创建。由于当后台没有供应 API 的时候，前端职员须要自己去搭建 Mock Server 的。可是，这个 Mock API 的准确性则是由后台来担保的，因此它须要共同去掩护。
与其用文档来规范，不如考试测验用持续集成与测试来掩护 API，担保协作方都可以及时知道。
在 2011 年，Martin Folwer 就写了一篇干系的文章：集成左券测试，先容了相应的测试办法：
其步骤如下：
编写左券（即 API）。即规定好 API 要求的 URL、要求内容、返回结果、鉴权办法等等。
根据左券编写 Mock Server。可以彩 Moco
编写集成测试将要求发给这个 Mock Server，并验证
如下是我们项目利用的Moco天生的左券，再通过Moscow来进行 API 测试。
Api测试代码
[
{
\"大众description\"大众:\公众should_response_text_foo\"大众,
\"大众request\公众: {
\"大众method\公众:\"大众GET\"大众,
\"大众uri\"大众:\"大众/property\"大众
},
\"大众response\公众: {
\"大众status\公众:401,
\"大众json\"大众: {
\"大众message\公众:\公众Full authentication is required to access this resource\公众
}
}
}
]
只须要在相应的测试代码里要求资源，并验证返回结果即可。
而对付前端来说，则是依赖于 UI 自动化测试。在测试的时候，启动这个 Mock Server，并借助于 Selenium 来访问浏览器相应的地址，仿照用户的行为进行操作，并验证相应的数据是否精确。
当左券发生发动的时候，持续集成便失落败了。因此相应的后台测试数据也须要做相应的修正，相应的前端集成测试也须要做相应的修正。因此，这一改动就可以即时地关照各方了。
前端测试与 API 适配器
由于前端存在跨域要求的问题，我们就须要利用代理来办理这个问题，如 node-http-proxy，并写上不同环境的配置：
这个代理就像一个适配器一样，为我们匹配不同的环境。
在前后端分离的运用中，对付表单是要经由前端和后台的双重处理的。同样的，对付前端获取到的数据来说，也该当要常常这样的双重处理。因此，我们就可以大略地在数据处理端做一层适配。
写前真个代码，我们常常须要写下各种各样的：
前端代码
if(response && response.data && response.data.length >0){}
纵然后台向前端担保，一定不会返回 null 的，但是我总想加一个判断。刚开始写 React 组件的时候，创造它自带了一个名为 PropTypes 的类型检测工具，它会对传入的数据进行验证。而诸如 TypeScript 这种强类型的措辞也有其类似的机制。
我们须要处理同的非常数据，不同情形下的返回值等等。因此，我之前考试测验开拓 DDM 来办理这样的问题，只是轮子没有造完。诸如 Redux 可以管理状态，还该当有个相应的类型检测及 Adapter 工具。
除此，还有一种情形是利用第三方 API，也须要这样的适配层。很多时候，我们须要的第三方 API 以公告的形式来关照各方，可每每我们不会及时地根据这些变革。
一样平常来说这种事情是后台去做代码的，不得已由前端来实现时，也须要加一层相应的适配层。
小结
总之，API 利用的第一原则：不要『相信』前端供应的数据，不要『相信』后台返回的数据。
作者：熵谈电商
链接：https://www.jianshu.com/p/f5fefa0b60f5
来源：简书
简书著作权归作者所有，任何形式的转载都请联系作者得到授权并注明出处。
