库作者指南简介

本指南总结了在设计库时应考虑的最佳实践和理念。

为了有效，一个库必须实现某些基本目标。具体而言，它应做到：

定义其问题域，并实现一组相关的、能解决其定义问题的功能需求。例如，一个 HTTP 客户端可能旨在支持所有 HTTP 请求类型，并理解各种标头、内容类型和状态码。
满足与问题域相符的非功能性标准。这些通常包括性能、可靠性、安全性及可用性。这些标准的相对重要性差异很大。例如，一个为批处理设计的库可能不需要与旨在日内交易的库相同水平的性能。
识别和定义功能性与非功能性需求的过程是一个复杂主题，已在软件工程中被广泛研究。本指南不深入涵盖这些主题，因为它们超出了其作用域。

本指南的主要关注点是探讨一个库为保持其相关性并受用户欢迎所必须具备的特点。这些特点包括：

最大限度降低心智复杂性： 所有开发者都必须考虑其代码的可读性和可维护性。降低他人阅读、理解和使用你的 API 所需的心智负担至关重要。实现这一点需要创建清晰、一致、可预测且易于调试的库。
向后兼容性： 发布 API 新版本时，确保现有 API 仍可运行。清晰地传达并提前文档化任何破坏性变更。为用户提供直接、清晰、渐进的途径，以便他们采用新的 API 或设计变更。
信息丰富的文档： 随库附带的文档不仅仅需要重复函数和类型声明。它应该全面且专门定制以适应库的目标受众。它应准确反映各种用户角色的需求和场景，确保在不过于简单或复杂的情况下提供必要信息。始终包含清晰的示例，平衡解释性文本与实际代码示例。

此外，构建具有多平台支持的 Kotlin 库可以拓宽其在面向各种环境的项目中的适用性。设计 API 以使其在共享代码和平台特有的代码中都能可靠工作，可以提高库在所有支持的目标平台中的多功能性和可用性。

以下章节将深入探讨这些特点，并提供实用建议，帮助你为库的用户提供最佳体验。

接下来