API 设计规范

目录

API 实现方式

通常,设计 API 规范有两个方向,Design-First(设计优先) 或 Code-First(编码优先)。

Design-First(设计优先)

即优先设计 API 规范,设计完成后再着手进行代码开发工作。推荐使用 OpenAPI-GUI v3 来设计 API 描述文件。

采用 Design-First 就意味着,将设计 API 路由、参数等工作提前,后续整个软件开发的流程都需要围绕着 API 规范为核心,当然这需要有一定的设计经验的开发人员才能胜任。

Design-First 有很多好处:

  • 提高开发效率。开发团队将根据 API 规范进行并行开发和对接工作,而无需等待接口逻辑开发完毕。
  • 降低接口开发的成本,无需修改代码逻辑即可轻松地修改 API 规范,因为 API 描述语言(如:OpenAPI)与编码语言无关。
  • 开发人员更加专注于设计 API 规范,对比 Code-First 可以描写更多 API 的细节,如:校验规则、范例数据等,同时开发人员对 API 的全局一致性、扩展性、规范性也有更好的把控。
  • 在联调开发的过程中可以提前发现和解决问题,避免问题在开发完毕后修改的成本过高。
  • 由于 API 描述更加标准化,可以方便做更多的 API 生态延伸,比如基于 API 规范生成 Mock API Server,开发 API 自动化测试代码,接入 API 网关等。

Code-First(编码优先)

即通过代码中关于 API 描述特性、注解或注释自动生成 API 描述文件的设计方式,如:JAVA 生态的 SpringFox。

适合倾向于在代码上编写 API 规范,通过自动化设施自动生成文档的团队。

Code-First 的优点:

  • 节省时间。对于 API 开发者,编码的同时可以获得一份满足基本要求的 API 文档。
  • 方便接入自动化 CI/CD 流程中。

虽然 Code-First 省去了开发者设计 API 描述文件的阶段,提高了 API 开发者的效率,但是从整个团队的角度来看,效率并不一定提升了,反而有可能降低了效率。

不同 API 开发者的经验和习惯的不同,极有可能在编码的过程中对 API 的限制条件考虑不全,又或者框架生成 API 文档的程序完善度不够,种种因素导致最终生成的 API 的描述无法达到理想标准。

而很多 API 开发者习惯开发完成后才推送代码,并生成 API 文档,也导致了团队的进程阻塞于此,拖后了整个团队的开发进程。另一方面,API 在开发完成如果没有测试,很有可能导致 API 对接者在对接的过程中遇到重重阻碍。

如果使用 Code-First 设计方向,建议:

  • 选用完善程度比较高的生成组件。
  • 对 API 的描述尽可能的细致、完整。
  • 优先设计路由、请求、响应等规则,详细的逻辑代码在 API 设计完成后再着手开发。

API 设计规范

为用户设计 API

API 并不是用来盲目的暴露一些数据或业务处理能力的,它就像我们每天使用的任何形式的接口一样(例如:微波炉的操作按钮),用来帮助用户完成他们的目标。所以,需要从用户的视角来决定一个 API 的设计是否友好,在设计 API 的时候要充分考虑 UI/UE 的操作流程。

反之,如果以开发者的视角去设计 API,那么通常的后果是开发出的 API 往往都偏重与于功能的实现过程和原理,而不是用户如何能简单平滑的使用这个 API 来达到他们的目的。

所以,一个好的 API 设计一定是面向用户的,充分隐藏底层复杂原理的。要设计出让用户容易理解和容易使用的 API。

识别 API 的目标

识别 API 的目标,最基本的需要对以下方面有深刻且精准的认识:

  • Who,谁使用这个 API?
  • What,用户拿这个 API 能做什么事?
  • How,用户如何做这件事?
  • What Need,用户想要做这件事的话还需要什么?
  • What Return,用户会得到什么?

Mock API Server

Mock API Server 基于 API 描述文件自动生成 Mock API,通过提供真实 API 响应的范例数据来模拟真实的 API 服务,并且支持路由及参数校验。

使用场景

  1. API 对接/调试:通常在公司项目中,API 使用者(如:前端、App、自动化 API 测试开发人员)的开发进度会比后端 API 开发人员提前开始开发实现。而使用基于 API 文档的 Mock API 可提供模拟真实 API 响应的沙盒环境,以便 API 使用者提前开始调试工作。另一方面 API 使用者可以及时反馈 API 设计问题,在完成 API 实现之前提早完善 API 设计,使得 API 开发工作更加高效和趋于完美。
  2. API 测试:当需要对部分 API 进行统一测试时,可以替换其他 API 为 Mock API,而无需关心其他依赖 API 是否满足测试条件。
  3. 外部 API 服务:通常外部 API 服务可能会有不可靠、收费、访问限制等情况,所以可以替换外部 API 服务为 Mock API,通过 Mock 外部 API 服务的真实数据来调试程序逻辑。

使用步骤

  1. API 规范设计:OpenAPI 规范。
  2. 生成范例数据 :Swagger Editor 可自动通过参数生成 Example。
  3. 生成 Mock API:Swagger CodeGen 可以自定生成 Mock API Server。
©️2020 CSDN 皮肤主题: 编程工作室 设计师:CSDN官方博客 返回首页
实付 49.00元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、C币套餐、付费专栏及课程。

余额充值