【分享】微服务API设计的实践与思考总结
API先行
在敏捷开发的大浪潮下，产品上通常要求快速迭代，面对一个新的需求，如果需要开发新的接口，通常在表结构完成设计后，开发人员就需要完成API设计并交付消费方（即服务的调用方或者依赖方，文中其余部分均表示此含义），在技术联调前，消费方可以Mock接口来完成调试。所以通常来说，API先与服务交付，之后再完成编码，测试，调试等工作。当然，由于可能在需求细节，技术实现方面可能在实现过程中发现需求需要调整，或者API接口的调整，最初版本的API可能是不成熟的，导致我们经常在API调整或者演化过程中在API维护方面存在很多遗漏，所以API最初交付后的维护是持续性的工作。
API设计常见问题
在我们设计API过程中由于存在经验的缺失，或者由于多次交接，或者由于经历多次需求的变更，导致服务的API慢慢腐化，带来以下常见的问题。
• 被遗忘的注释，注释通常描述了API的功能以及参数说明，以及如何接入，甚至给出简单示例，过于详细的注释会带来一定的反作用，例如因为新需求带来了内部逻辑的调整，但是由于未及时对API的注释进行更新，会给新接入的调用方带来潜在的风险。所以不仅仅需要为API提供完整清晰的注释，当内部逻辑变更时，作为开发人员通常也需要评估API层面的变更，包括注释。
• 接口数量持续膨胀，有很多原因带来接口数量的膨胀，可能是接口升级，但是旧接口无法直接下线，所以会提供一个功能类似的新接口；可能是新接管一个服务由于对业务不了解，面对新需求直接开发新接口；可能是接口分类划分不合理，或者数据模型混乱导致API划分混乱，出现API功能重复，最后导致一个场景多个API接口都可以满足，这样很明显是应该避免的。解决这些问题都需要建立在对业务充分理解的基础上，下文的设计原则会针对这类问题给出解决方案。
• 缺乏有效测试，很多开发人员往往忽略对于接口的测试，无论是内部逻辑细节的单元测试，还是接口层面的测试，都是服务健壮性的一个有效保证，如果无法对接口进行有效测试，不仅是不负责任的提现，而且还会经常被线上bug困扰。
API设计的原则
良好的注释
• 注释应该包含哪些；接口的使用场景，参数的说明，在接口类说明中可以给出接口文档链接地址，方便调用方查看
• 参数的说明；包含参数代表的含义，参数的类型按照Javadoc link规范，参数是否为空，特殊值说明
• 过期说明；如果接口已经过期，需要给出过期说明，对于 Java 来时就是@Deprecated注解，并给出切换接口说明，如果条件允许可以推动调用方进行接口迁移，后续对旧接口下线
扩展性
唯一不变的是变化，接口也会一直演化，我们不提倡过度提前设计，但是在演化过程中要始终保持接口的可扩展性。
• 多参数结构与单一参数类结构 通常来说，如果一个接口的参数小于三个，那么建议使用多参数接口，这样做到直观简洁 如果一个接口的参数较多而且后续可能经常出现变动，为了便于扩展和兼容，会将参数封装到一个类结构中，记得同样对每个字段给出完整的注释说明。
• 类复用噩梦 在单一参数类结构下，我经常看到多个存在明显功能差异的接口频繁复用一个结构体，甚至接口参数和返回值都复用一个DTO，为了保证兼容，又不得不在同一个DTO内不断加字段，久而久之维护成本持续增高，这是一种不合理的类设计，如果遵守专注原则，这个问题很多时候可以避免。
兼容性
• 接口逻辑或者参数变更时，需要对旧的接口保持兼容，这个是API变更时一定要遵守的原则之一，而且要通过接口测试来验证兼容性。
• 是否要新增接口，当面对一个新的需求时，为了避免对旧接口直接修改，有的开发人员会统一提供新的接口，如果并非逻辑上发生较大的变更，这样做会提高API的维护成本，后续如果不对API进行重构，新增加的维护成本将远大于最开始节省的开发成本，例如需要对某个参数增加有效校验，那么我们需要对两个接口的API实现都做修改，而且是重复性的代码，而且我们的影响范围已经成了两个接口，这样影响范围的扩大也带来了更多的潜在风险。当然在某些场景例如接口逻辑出现大的调整，API重构等情况下，更好的方法是提供新的接口，并推动服务消费者使用新的API，最后慢慢下线旧的API，这样才能遵循简单和专注的原则。
完善的测试
• 单元测试，完善的单元测试能保证代码的健壮性，提前在编码阶段发现并解决潜在的bug，单元测试是一个开发人员的必备能力。
• 接口和场景测试，接口测试包含内部逻辑验证，异常输入，并发等场景下对单一接口的验证，如果要对API进行完整的逻辑验证，需要开发人员构造完整的测试数据（通常包含scheme.sql和data.sql文件），尤其是对于基础服务，需要对某些复杂业务场景下联合多个接口完成某个场景的测试，并对中间的数据和输出进行Assert确认，这样也会代码一定的测试代码维护成本，需要开发人员进行利弊权衡。
重视文档
良好的注释和文档能减少大部分和服务消费者的沟通工作，也避免了一些错误的接口调用。没有人希望每次都需要在IM工具上浪费大量口水或者需要当面询问才知道如何正确使用API，也没有开发者愿意每天重复回答如何调用提供的接口。对于接口文档，可以是采用Javadoc这样简单的方式，也可以是通过wiki来集中管理，可以是markdown文档，也有很多的开源系系统例如Swagger，yapi，eolinker等；微服务的架构极大的加强了沟通的成本，这也是微服务架构的一个弊端，但是合理的利用 工具 可以减少不必要的沟通。
善用工具
理论肯定是基本功，但是合理使用API工具能提高工作效率相信大多数人都不会反对，国外的Postman，Swagger，国内的Eolinker，都是现在蛮多同行在用的API工具。
总结
作为微服务之间的桥梁，API设计和维护是微服务架构中很重要的一个环节，每个开发人员不仅仅需要良好的代码规范，也需要建立并遵守API设计规范。API设计能力在微服务架构中作为软实力的一个部分，需要开发人员有一定的设计经验的积累，同时，只有不断的思考和总结才能更加深入的理解。
来源：www.eolinker.com
