库开发者指南简介

这篇指南包含设计库时的一些最佳实践, 以及需要考虑的问题.

为了有效运作, 一个库必须达到某些基本目标. 具体来说, 它应该:

• 定义清楚它的问题域, 并实现一组相关的功能需求, 解决它定义的那些问题. 例如, 一个 HTTP Client 的目标可能是支持所有的 HTTP 请求类型, 并了解各种 Header, 内容类型, 以及状态码.

• 满足适合于问题域的非功能性标准. 这些标准通常涉及性能, 可靠性, 安全性, 以及可用性. 这些标准的相对重要性差别很大. 例如, 为批处理设计的库, 它的性能可能不需要达到日常交易的库相同的程度.

这篇指南的重点是探索一个库必须具备哪些特性, 才能紧贴用户, 并受到用户欢迎. 这些特性包括:

• 减少认知复杂度 (Mental Complexity): 所有的开发者必须考虑他们代码的可读性和可维护性. 减少其他人阅读, 理解, 以及使用你的 API 时所需要的脑力劳动, 这是非常重要的. 要实现这个目标, 需要创建清晰, 一致, 可预测, 以及易于调试的库.

• 向后兼容性(Backward Compatibility): 在发布一个 API 的新版本时, 要确保既有的 API 能够继续工作. 要提前沟通清楚, 并为所有的破坏性变更(Breaking Change)编写文档. 要为用户提供直接, 清楚, 并且循序渐进的途径, 来采用新的 API 或设计变更.

• 信息丰富的文档: 随库一起发布的文档不能仅仅是重复库的函数和类型声明. 文档应该包含全面的信息, 并专门针对库的使用者. 它应该准确反映各种用户角色的需求和使用场景, 确保提供必要的信息, 不能过分简单, 也不能过分复杂. 应该始终包含清晰的示例, 解释性文字和实际代码示例要保持平衡.

后续章节会更加深入的研究这 3 个特性, 并对如何为你的库使用者提供最佳体验, 给出一些实用的建议.