从某种 API 定义(如 OpenAPI)生成客户端并将其与其他代码一起交付是一种非常常见的模式,我过去曾使用并创建过此类客户端。对于您的 API 的消费者来说,这有一些明显的优势:他不必生成客户端(取决于使用的技术有时会很痛苦),他受益于提供者(和其他人)所做的维护,并使用官方与 API 交互的方式。
在这样的客户端中,有三个主要的包应该相互分离和独立:
- 生成的客户端
- 简化生成客户端使用的代码
- 其他代码(即抽象或简化常见交互的实用程序,提供客户端所需的域逻辑等)
如果这些是分开的,那么消费者很容易挑选他想要使用的部件。
主要缺点是您必须为您的 API 实现和维护多个客户端。根据 API 的大小、支持的平台和客户端使用的环境,这可能是一项非常复杂的任务。还要记住,提供一个体面的客户端库需要对目标平台和环境有很好的理解。否则您的客户端库可能不会被其他开发人员接受。
一般来说,生成的代码通常不是那么“自然”和“好”。例如,生成的标识符可能不遵循平台的约定,或者它需要使用像工厂这样的过于复杂的构造来创建一个简单的对象。通常可以调整生成器,但这会增加所需的工作量。
所有这些努力通常加起来,因此即使是大型 API 提供者也难以为许多平台提供良好的客户端库。
有两种选择:
第一种选择让消费者可以自由选择他想要使用您的 API 的方式。但是给定一个好的 API 定义(很难编写),这样做相对容易。在这种情况下,不可能向客户端提供一些额外的代码。但总的来说,您应该针对愚蠢的客户并避免客户执行业务逻辑。
如果您的目标是有限数量的平台,您希望在这些平台上为消费者提供最佳体验,那么手工制作的客户端最适合。此外,您可以实现各种其他东西。但即使对于单个平台,这也可能是一项巨大的努力。