微服务手册：API接口9个生命节点，构建全生命周期管理

互联网应用架构：专注编程教学，架构，JAVA，Python，微服务，机器学习等领域，欢迎关注，一起学习。

对于API，在日常的工作中是接触最多的东西，特别是我们软件这一行，基本就是家常便饭了，在百度百科里面的解释：

API（Application Programming Interface，应用程序接口）是一些预先定义的函数，或指软件系统不同组成部分衔接的约定。 用来提供应用程序与开发人员基于某软件或硬件得以访问的一组例程，而又无需访问源码，或理解内部工作机制的细节。

在不同系统之间，不同部门之间的各种对接，API就是研发人员的一个纯粹性的沟通语言，双方定义好规范、约束等进行系统之间的交互。

生命周期

在我们软件行业的领域里面，每一个软件都是有生命周期的，从最开始的需求调研，需求设计，架构设计，软件研发，测试，上线，试运行，运行到最后业务上，技术上跟不上时代的发展，被新来的技术人员嫌弃，后面的业务部门抛弃，至此开始结束最后到下线，这个系统就算结束了他们的生命周期。

API是一种应该性接口同样具备了设计化、测试化的过程，这就显性表明API其实也作为有生命周期的存在，在现有的设计中，API生命周期分为9种

• 设计
• 构建/研发
• 管理
• 联调/测试
• 自动化
• 文档/发布
• 授权开放
• 监控
• 下线

设计--见文知意

一个API的形成，设计是最根本的存在，因为他的存在不单单是自己使用，更重要的是让多方可以使用，因此有一个规范的思想非常重要，这里有个方法论就是--见文知意。每次看到API都能知道这个API是做什么的，这是对开发者，使用者来说非常重要的一个方向，每一个API实际上对应的一个后端服务的方法，必须有限定的出参与入参，其中出参与入参必须有严格的定义。

入参：有一个重要的准则就是能快速进行参数的基础属性的校验，例如是否为空，字段长度等，目前一般采用hibernate valid或者java自带的valid来实现。

出参：出参的规范化体现在错误码上，针对错误码的定义需要非常明确，让调用者可以一眼就能看到问题的所在，目前很多API接口在进行设计的时候一般只有正确与错误两个错误码，平时用着没问题，在业务发展到一定程度后会增加运维的难度，建议错误码按照不同的类别，例如业务、技术等区分。

构建/研发--防范于未然

在进行了的第一步的规范化设计后，研发人员就要开始根据规范进行API接口的内部业务逻辑的设计，具体的业务逻辑由业务逻辑来做限定，这里需要注意的就是非法参数尽可能排除的API之外，需要在入口处进行判断并且汇集不合法的数据直接报错，不允许出现在后续的业务代码逻辑里面去判断合法性，如上面所说采用hibernate valid进行操作，这些都是一个API生成的过程。

管理--运筹帷幄

每一个API的诞生到最后的下线它都是可控可管理的。

版本管理：每一个API从最开始发布到后面不断迭代发布更新，都需要一个版本号来做限定，做到每一个版本可查可追溯。

文档管理：API里面文档是非常重要的存在，它是连接所有应用的桥梁里面的中流砥柱，一份清晰可见的文档是所有使用者的福报。在研发人员的世界中，最喜欢写代码，最痛苦写文档，但是如果把写代码变成一种写代码的方式呢，swagger可以帮你实现本地化文档也可以实现离线文档，还是直接导入到yapi进行mock测试。

质量审核：API并非写完就完事，如果只是简简单单搞定并不按照规范走，入参map加上出参map的存在，那就要扯皮来，因此需要一个人来审核这些才能允许上线。

状态码管理：由于状态码是最常见的存在，因此它是微乎其微但是又是非常重要的东西，定义业务级别的状态码，定义系统级别的状态码，这些都需要进行管控起来。

迭代管理：迭代跟上面的版本有异曲同工之妙，版本更着重于版本号的定义及生成，迭代更侧重于每一次迭代的跟进管理，等价于每一次的历史记录。

权限管理：API并非任何人都可以用的，需要进行授权。

服务管理：一个服务提供多个API，存在数据库级别的1对N关系，需要这些进行分配及管理。

变更管理：API并非一成不变的，除了版本号的变更，经常涉及到里面的内容的管理，这些内容需要做记录及对比。

联调/测试--微察秋毫

一个好的API除了规范设计清晰及业务逻辑清晰，更重要的是一定也是便于测试的，对应的业务是否能完成，对应的系统对接是否有足够集成，是否提供了足够的详细的文档，确保了API的质量是有非常高的维护性的，这些通通在测试层进行验证，本地化测试，MOCK测试，测试用例尽可能完整。

自动化--进退有度

相比于上面的人工测试，自动化测试是标准化的一种设计。按照约定设定好一定的标准阈值对接口进行测试，检验接口是否满足我们最基础的性能等要求，但是自动化测试并不是万能的，何时介入，怎么介入，什么样的项目适合自动化测试，这些都需要我们进行思考。

何时介入：在项目的刚开始的时候不适合自动测试的介入，业务稳定性，需求变更快导致接口随时随地都在变化，代码变动率非常高，维护成本非常高；到了后期后项目稳定了项目进入维护阶段，此时自动化开始介入并为回归测试做好准备。

怎么介入：从自动化程度及自动化率来做切入点，虽然前期的项目并不适合做自动化测试，但是可以选用一些稳定的，公用的进行测试。

适合项目：有意做回归测试，并且需要长期做支持维护的项目；压力测试的项目；覆盖率测试的项目。

文档/发布--十年磨一剑

这里用十年磨一剑有点夸张了，但是相对于开发者来说，每一个接口的诞生都是我都认为那是一项伟大的存在。在经历了前面的各种更改，测试，压力考验后可以正式发布了。每一个接口在发布后就直接跟网关对接，网关帮我们实现统一的鉴权，过滤，熔断，限流等操作来保护我们每一个接口的安全。

授权开放--首肯心折

不是所有人都可以访问API接口的，不是每个接口都是免费的，在必要的时刻需要我们对特定的接口做授权管理，规定哪些人可以访问，哪些接口需要收费。

监控--运筹帷幄

在API运行期间，最重要的也是最重点的工作就是对接口进行监控，包括性能监控、可用率监控、调用量监控等，并生成监控报告。这些监控都可以帮助我们从技术层面，业务层面进行分析接口的详情情况及指标，确保每一个接口都尽可能实现价值，实现接口的性能达标跟可用率达标。

下线--功成名就

到了这里，接口基本上就是已经功成名就完成它的使命，我们需要结束它的生命周期，有种莫名的伤感，夕阳西下，断肠人在天涯，下线吧。

--END--

作者：@互联网应用架构

原创作品，抄袭必究

如需要源码或请转发，关注后私信我

部分图片或代码来源网络，如侵权请联系删除，谢谢！