微服务 API 设计实践与思考

《微服务 API 设计实践与思考》由会员分享，可在线阅读，更多相关《微服务 API 设计实践与思考（3页珍藏版）》请在金锄头文库上搜索。

1、微效劳 API 设计实践与思考随着微效劳的越来越流行，越来的越多的公司开头实行微效劳架构，相对于单一应用架构，微效劳将简单性拆分 并且打散到一个个粒度更加细分的应用中，极大了削减了开发中单个效劳的简单性，开发人员只需要面对专注单 一业务场景编程，从技术开发角度，单一效劳代码量上削减很多，从业务角度上，业务简单性的降低降低了需求 的沟通本钱。然而，整体业务简单性照旧存在，当我们需要接入或者依靠其他效劳时，通常作为接入方来说，我们不需要深化 了解效劳供给方的业务，此时API 成为了开发人员间的沟通语言。良好的 API 设计，能极大的削减沟通本钱，甚至有时候可以代替文档，尤其是对于根底性效劳来说，效

2、劳的可扩展性有时候表达在API 的可扩展性，我曾经参与过一个根底业务微效劳的业务升级，由于旧版本的API 划分不够清楚，局部 API 存在重复性，后面不得不对大局部API 进展重构替换为新版本的API，仅仅在效劳消费方升级这个阶段就持续 1-2 个月之久，在这个过程中也不断对 API 设计中存在的一些问题以及应当遵循哪些原那么进展了一些思考。API 先行在灵敏开发的大浪潮下，产品上通常要求快速迭代，面对一个新的需求，假设需要开发新的接口，通常在表构造 完成设计后，开发人员就需要完成API 设计并交付消费方即效劳的调用方或者依靠方，文中其余局部均表示此含义，在技术联调前，消费方可以 Mock 接

3、口来完成调试。所以通常来说，API 先与效劳交付，之后再完成编码， 测试，调试等工作。固然，由于可能在需求细节，技术实现方面可能在实现过程中觉察需求需要调整，或者 API 接口的调整，最初版本的API 可能是不成熟的，导致我们经常在API 调整或者演化过程中在API 维护方面存在很多遗漏，所以API 最初交付后的维护是持续性的工作。API 设计常见问题在我们设计API 过程中由于存在阅历的缺失，或者由于屡次交接，或者由于经受屡次需求的变更，导致效劳的 API 渐渐腐化，带来以下常见的问题。 被遗忘的注释，注释通常描述了API 的功能以及参数说明，以及如何接入，甚至给出简洁例如，过于具体的注释会

4、带来肯定的反作用，例如由于新需求带来了内部规律的调整，但是由于未准时对API 的注释进展更新，会给新接入的调用方带来潜在的风险。所以不仅仅需要为API 供给完整清楚的注释，当内部规律变更时，作为开发人员通常也需要评估API 层面的变更，包括注释。 接口数量持续膨胀，有很多缘由带来接口数量的膨胀，可能是接口升级，但是旧接口无法直接下线，所以会供给一个功能类似的新接口；可能是新接收一个效劳由于对业务不了解，面对新需求直接开发新接口；可能是接口分 类划分不合理，或者数据模型混乱导致API 划分混乱，消灭API 功能重复，最终导致一个场景多个API 接口都可以满足，这样很明显是应当避开的。解决这些问题

5、都需要建立在对业务充分理解的根底上，下文的设计原那么会针 对这类问题给出解决方案。 缺乏有效测试，很多开发人员往往无视对于接口的测试，无论是内部规律细节的单元测试，还是接口层面的测试，都是效劳强健性的一个有效保证，假设无法对接口进展有效测试，不仅是不负责任的提现，而且还会经常被线上bug 困扰。API 设计的原那么简洁且专注 简洁：在面对对象设计原那么中，第一条是单一职责原那么，同样适用于 API 设计，我们的主体对象就是业务模型， API 就是封装内部规律后对外界开放的功能。保证API 的简洁和职责单一，能够避开解决上文中提到的接口数量膨胀问题。那如何才能实现API 职责单一，需要我们在定义

6、接口时能够准确识别出接口之间的关联性和边界，对于 API 如何划分可以通过以下角度： 依据业务主体划分，不一样的业务主体承受不一样的接口类 查询类和修改类的接口分别；通常来说我们对于数据的查询场景远大于修改的场景，而且查询有多种多样的业务 场景，对于数据的修改恳求通常来源于业务后台人员对数据进展修改，此时的业务规律也通常会更加特别例如 有很多额外数据校验，所以建议修改类和查询类API 尽量分别，甚至可以将业务配置后台类查询和一般业务查询分别以至于能够适应各自的业务变更。 专注：一个单一接口的场景是基于业务抽象后专注于某一个场景并且相互不重合的，这样才能保证接口的粒度足 够小，尤其是对于根底类效

7、劳，接口粒度的划分能保证接口是纯粹的且相互独立的，这样才不至于在需求变化是 涉及过多接口的变动除非是对业务模型有较大的调整，另外要说明的是，内部规律的业务数据模型 POJO 类和 API 数据模型DTO有时候消灭差异，否那么可能需要消费者理解效劳的业务模型才能正确的使用接口， 这就要求在API 设计中开发人员需要明确应当供给哪些数据模型给消费者，在此前提下更加有助于我们保证单一接口的专注。良好的注释 注释应当包含哪些；接口的使用场景，参数的说明，在接口类说明中可以给出接口文档链接地址，便利调用方查 看 参数的说明；包含参数代表的含义，参数的类型依据Javadoc link 标准，参数是否为空，

8、特别值说明 过期说明；假设接口已经过期，需要给出过期说明，对于 Java 来时就是Deprecated 注解，并给出切换接口说明，假设条件允许可以推动调用方进展接口迁移，后续对旧接口下线扩展性唯一不变的是变化，接口也会始终演化，我们不提倡过度提前设计，但是在演化过程中要始终保持接口的可扩展 性。 多参数构造与单一参数类构造 通常来说，假设一个接口的参数小于三个，那么建议使用多参数接口，这样做到直观简洁 假设一个接口的参数较多而且后续可能经常消灭变动，为了便于扩展和兼容，会将参数封装到一个类构造中，记得同样对每个字段给出完整的注释说明。 类复用噩梦 在单一参数类构造下，我经常看到多个存在明显功能

9、差异的接口频繁复用一个构造体，甚至接口参数和返回值都复用一个DTO，为了保证兼容，又不得不在同一个 DTO 内不断加字段，久而久之维护本钱持续增高， 这是一种不合理的类设计，假设遵守专注原那么，这个问题很多时候可以避开。兼容性 接口规律或者参数变更时，需要对旧的接口保持兼容，这个是API 变更时肯定要遵守的原那么之一，而且要通过接口测试来验证兼容性。 是否要新增接口，当面对一个新的需求时，为了避开对旧接口直接修改，有的开发人员会统一供给新的接口，如果并非规律上发生较大的变更，这样做会提高API 的维护本钱，后续假设不对API 进展重构，新增加的维护本钱将远大于最开头节约的开发本钱，例如需要对某

10、个参数增加有效校验，那么我们需要对两个接口的API 实现都做修改，而且是重复性的代码，而且我们的影响范围已经成了两个接口，这样影响范围的扩大也带来了更多的潜在风险。固然在某些场景例如接口规律消灭大的调整，API 重构等状况下，更好的方法是供给新的接口，并推动效劳消费者使用新的API，最终渐渐下线旧的API，这样才能遵循简洁和专注的原那么。完善的测试 单元测试，完善的单元测试能保证代码的强健性，提前在编码阶段觉察并解决潜在的 bug，单元测试是一个开发人员的必备力量。 接口和场景测试，接口测试包含内部规律验证，特别输入，并发等场景下对单一接口的验证，假设要对API 进展完整的规律验证，需要开发人

11、员构造完整的测试数据通常包含scheme.sql 和 data.sql 文件，尤其是对于根底效劳，需要对某些简单业务场景下联合多个接口完成某个场景的测试，并对中间的数据和输出进展 Assert 确认，这样也会代码肯定的测试代码维护本钱，需要开发人员进展利弊权衡。重视文档良好的注释和文档能削减大局部和效劳消费者的沟通工作，也避开了一些错误的接口调用。没有人期望每次都需 要在 IM 工具上铺张大量口水或者需要当面询问才知道如何正确使用API，也没有开发者情愿每天重复答复如何调用供给的接口。对于接口文档，可以是承受 Javadoc 这样简洁的方式，也可以是通过 wiki 来集中治理，可以是markdown 文档，也有很多的开源系系统例如Swagger，yapi，eolinker 等；微效劳的架构极大的加强了沟通的本钱，这也是微效劳架构的一个弊端，但是合理的利用 工具 可以削减不必要的沟通。总结作为微效劳之间的桥梁，API 设计和维护是微效劳架构中很重要的一个环节，每个开发人员不仅仅需要良好的代码标准，也需要建立并遵守 API 设计标准。API 设计力量在微效劳架构中作为软实力的一个局部，需要开发人员有肯定的设计阅历的积存，同时，只有不断的思考和总结才能更加深化的理解。