API先行

API设计常见成绩

API设计的准绳

复杂且专注

良好的注释

扩展性

兼容性

完善的测试

注重文档

总结

随着微效劳的越来越盛行，越来的越多的公司末尾实行微效劳架构，相关于单一运用架构，微效劳将复杂性拆分并且打散到一个个粒度愈加细分的运用中，极大了增加了开发中单个效劳的复杂性，开发人员只需求面向专注单一业务场景编程，从技术开发角度，单一效劳代码量上增加很多，从业务角度上，业务复杂性的降低降低了需求的沟通成本，但是，全体业务复杂性依然存在，当我们需求接入或许依赖其他效劳时，通常作为接入方来说，我们不需求深化了解效劳提供方的业务，此时API成为了开发人员间的沟通言语。

良好的API设计，能极大的增加沟通成本，甚至有时分可以替代文档，尤其是关于基础性效劳来说，效劳的可扩展性有时分体如今API的可扩展性，我曾经参与过一个基础业务微效劳的业务晋级，由于旧版本的API划分不够明晰，部分API存在重复性，前面不得不对大部分API停止重构（交流为新版本的API），仅仅在效劳消费方晋级这个阶段就继续1-2个月之久，在这个进程中也不断对API设计中存在的一些成绩以及应该遵照哪些准绳停止了一些思索。

API先行

在矫捷开发的大浪潮下，产品上通常要求快速迭代，面对一个新的需求，假设需求开发新的接口，通常在表结构完成设计后，开发人员就需求完成API设计并交付消费方（即效劳的调用方或许依赖方，文中其他部分均表示此含义），在技术联调前，消费方可以Mock接口来完成调试。所以通常来说，API先与效劳交付，之后再完成编码，测试，调试等任务。

当然，由于能够在需求细节，技术完成方面能够在完成进程中发现需求需求调整，或许API接口的调整，最后版本的API能够是不成熟的，招致我们常常在API调整或许演化进程中在API维护方面存在很多遗漏，所以API最后交付后的维护是继续性的任务。

API设计常见成绩

在我们设计API进程中由于存在阅历的缺失，或许由于屡次交接，或许由于阅历屡次需求的变更，招致效劳的API渐渐蜕化，带来以下常见的成绩。

被遗忘的注释，注释通常描画了API的功用以及参数阐明，以及如何接入，甚至给出复杂示例，过于详细的注释会带来一定的反作用，例如由于新需求带来了外部逻辑的调整，但是由于未及时对API的注释停止更新，会给新接入的调用方带来潜在的风险。所以不只仅需求为API提供残缺明晰的注释，当外部逻辑变更时，作为开发人员通常也需求评价API层面的变更，包括注释。

接口数量继续收缩，有很多缘由带来接口数量的收缩，能够是接口晋级，但是旧接口无法直接下线，所以会提供一个功用相似的新接口；能够是新接收一个效劳由于对业务不了解，面对新需求直接开发新接口；能够是接口分类划分不合理，或许数据模型混乱招致API划分混乱，出现API功用重复，最后招致一个场景多个API接口都可以满足，这样很清楚是应该避免的。处置这些成绩都需求树立在对业务充沛了解的基础上，下文的设计准绳会针对这类成绩给出处置方案。

缺乏有效测试，很多开发人员往往疏忽关于接口的测试，无论是外部逻辑细节的单元测试，还是接口层面的测试，都是效劳强健性的一个有效保证，假设无法对接口停止有效测试，不只是不担任任的提现，而且还会常常被线上bug困扰。

API设计的准绳 复杂且专注

复杂：在面向对象设计准绳中，第一条是单一职责准绳，异样适用于API设计，我们的主体对象就是业务模型，API就是封装外部逻辑后对外界开放的功用。保证API的复杂和职责单一，可以避免处置上文中提到的接口数量收缩成绩。那如何才能完成API职责单一，需求我们在定义接口时可以准确辨认出接口之间的关联性和边界，关于API如何划分可以经过以下角度：

按照业务主体划分，不一样的业务主体采用不一样的接口类

查询类和修正类的接口别离；通常来说我们关于数据的查询场景远大于修正的场景，而且查询有多种多样的业务场景，关于数据的修正央求通常来源于业务后台人员对数据停止修正，此时的业务逻辑也通常会愈加特殊（例如有很多额外数据校验），所以建议修正类和查询类API尽量别离，甚至可以将业务配置后台类查询和普通业务查询别离以致于可以顺应各自的业务变更。

专注：一个单一接口的场景是基于业务笼统后专注于某一个场景并且相互不重合的，这样才能保证接口的粒度足够小，尤其是关于基础类效劳，接口粒度的划分能保证接口是地道的且相互独立的，这样才不至于在需求变化是触及过多接口的变动（除非是对业务模型有较大的调整），另外要阐明的是，外部逻辑的业务数据模型（POJO类）和API数据模型（DTO）有时分出现差异，否则能够需求消费者了解效劳的业务模型才能正确的运用接口，这就要求在API设计中开发人员需求明白应该提供哪些数据模型给消费者，在此前提下愈加有助于我们保证单一接口的专注。

良好的注释

注释应该包含哪些；接口的运用场景，参数的阐明，在接口类阐明中可以给出接口文档链接地址，方便调用方查看

参数的阐明；包含参数代表的含义，参数的类型按照Javadoc link标准，参数能否为空，特殊值阐明

过时阐明；假设接口曾经过时，需求给出过时阐明，关于 Java 来时就是@Deprecated注解，并给出切换接口阐明，假设条件允容许以推进调用方停止接口迁移，后续对旧接口下线

扩展性

独一不变的是变化，接口也会不断演化，我们不倡导过度提早设计，但是在演化进程中要一直保持接口的可扩展性。

多参数结构与单一参数类结构 通常来说，假设一个接口的参数小于三个，那么建议运用多参数接口，这样做到直观繁复 假设一个接口的参数较多而且后续能够常常出现变动，为了便于扩展和兼容，会将参数封装到一个类结构中，记得异样对每个字段给出残缺的注释阐明。

(责任编辑：admin)