库作者指南简介

本指南总结了在设计库时应考虑的最佳做法和思路。

为了行之有效，库必须实现某些基本目标。具体而言，它应当：

• 定义其问题域，并实现一组相关的、用于解决其定义问题的核心功能需求。 例如，HTTP 客户端可能旨在支持所有 HTTP 请求类型，并理解各种标头、内容类型和状态码。
• 满足适用于该问题域的非功能性标准。这些通常涉及性能、可靠性、安全性和可用性。 这些标准的相对重要性差异很大。例如，为批处理设计的库可能不需要与用于日间交易的库相同的性能水平。

识别和定义功能与非功能性需求的过程是一个复杂的主题，在软件工程中已经得到了广泛研究。 本指南不深入探讨这些主题，因为它们超出了本指南的范围。

本指南的主要侧重点是探讨库必须具备的特征，以保持其与用户的相关性和受欢迎程度。这些特征包括：

• 最小化心智复杂度： 所有开发者都必须考虑其代码的可读性和可维护性。降低他人阅读、理解和使用 API 所需的心智负担至关重要。实现这一目标涉及创建清晰、一致、可预测且易于调试的库。
• 向后兼容性： 发布 API 的新版本时，确保现有 API 保持正常运行。提前清楚地沟通并记录任何重大变更。为用户采用新 API 或设计变更提供简单、清晰且渐进的途径。
• 信息丰富的文档： 随库附带的文档不仅仅是重复函数和类型声明。它应当是全面的，并且专门针对库的受众量身定制。它应当准确反映各种用户角色的需求和场景，确保提供基本信息，而不会过于简单或复杂。务必包含清晰的示例，平衡解释性文字与实际的代码示例。

此外，为您的 Kotlin 库构建多平台支持可以扩大其在针对各种环境的项目中的适用性。 设计能在共享代码和特定于平台的代码中可靠工作的 API，可以提高库在所有支持的目标上的通用性和可用性。

以下章节将深入探讨这些特征，并提供有关如何为库用户提供最佳体验的实用建议。

后续步骤

• 在最小化心智复杂度中探索最小化心智复杂度的策略。
• 在向后兼容性中了解维护向后兼容性的相关信息。
• 有关有效文档实践的详尽概述，请参阅信息丰富的文档。
• 在为多平台构建 Kotlin 库中探索构建多平台库的最佳做法。