创建完美SDK的10个技巧

阅读更多

【编者按】本文作者为 Gal Lavinsky，文中将列出10个零基础小技巧，帮你创建完美的Java SDK。文章系国内 ITOM 管理平台 OneAPM 编译呈现。以下为正文。

本文起源于笔者朋友的一次问询。他认为，关于如何写好一个简单易用的SDK，没有足够的参考文件。

在过去的十年里，SDK的使用在开发生命周期中已经成为了重要的一部分。事实上，它的使用和在产品中的集成已经如此常见，可以说，相比于深度学习算法来自行实施，开发者们更需要学习大量框架以融会贯通。

本文主要面向想要学习书写最佳SDK，并为之提供参考文档的读者。SDK的出发点是它的参考文档应当是重点明确且清晰的。如果你觉得文档有多个重点，请考虑拆分为多个文档。

以下是笔者希望能帮助你更好地构建SDK并书写其参考文档的清单：

 

1. 了解墙外的世界

试着去关注你的竞争对手或者与你相似领域的公司都做了什么。这可能会给你一些参考的角度。采纳你喜欢的地方，改善你不喜欢的地方。

 

2. 简洁

代码简洁——简洁的代码意味着你的客户用起来得心应手。这可能包括尽可能减少与代码交互的方式，比如只公开一个接口类；或是简短的方法签名，比如少量的输入参数，等等。

除了初始化阶段（只发生一次且可能要求进行配置），请让SDK方法使用起来尽可能简单。

同样地，请尽量减少方法签名中的参数。

你可以通过提供默认配置以及允许高级用户进行覆盖的默认实现类来达到这一目的。

隐藏用户不需要使用的类和方法，比如，只将用户必须使用的类/方法设定为公有的，否则就将它们的使用范围设定为局部或者私有。一个 IDEs 提供了代码检查与清除功能，可以帮你自动实现这一点。

参考文档简洁——让你的文档尽可能简单易懂。这意味着有时候你得多写注释，有时候又得尽量少写。内联样本代码通常很有帮助，因为大多数人都是通过例子来学习的。

 

3. 提供简单的开始步骤

这是指一个人可以在五分钟内上手使用你的代码。这一点非常重要，因为客户往往希望尽可能不费力地进行集成。除此之外，有时候客户想要评估你的产品，但如果无法进行简单的测试，他们就很可能选择跳过你的产品。

 

4. 短小精悍

保持简短主要是文档的责任，但是同样与用户和SDK代码的交互方式有关；为了保持文档的简短，可以提供代码样例、一目了然的方法名或使用默认数据来实现。

 

5. 集成

请谨记客户开发环境的多样性。

比如说，如果你在写一个安卓库，它的集成方式在客户使用Android Studio加gradle 框架和使用Eclipse集成开发环境时就非常不同。前者需要aar工件并发布到远程存储库中，而后者需要你提供jar文件，以及关于如何为SDK更改AndroidManifext.xml文件和独立eclipse项目的指导。

这可能会影响你的构建机制及其工件。然而，不要试图取悦所有客户，请先满足你的第一位客户，或者预期中的大多数客户的需求。

 

6. 项目示例

在GitHub上创建一个最基本的项目，模拟使用SDK包的用户。

这可以向客户展示你的产品如何满足他们的需求，以及如何集成你的产品。如果你想展示高级用法，那就在另一个项目里进行展示。通常，客户会将项目示例作为主要的参考文档，因此，请提供行内评论，并尽量用一目了然的方式书写代码。

 

7. 概述

在参考文档的开头，或是GitHub项目的README.md文件中，请用直白的语言对你的解决方案进行概述。在此部分，笔者通常会提供一个使用样例来解释SDK的典型用法。如果有可能，请提供一个简单的表格或是图表，这样一来，不喜欢阅读操作指南的用户也可以快速了解该SDK的优势。

 

8. 初始化

使用在SDK域内可接受的惯例。

这些惯例可能是可重载的构造函数，某种构建模式等。初始化应当巧妙地使用默认值来简化流程。

 

9. 默认值

默认值对于保持代码的简洁性和减少配置过程（见简洁性部分）是非常重要的。你所提供的默认值（不管是在配置还是实施过程）应该代表在你眼中大多数SDK用户会进行的操作。

你可以提供几个方法重载，使最简单的签名都可以用默认值调用更高级的方法。

 

10. 发布

• 离线使用不可编辑模式——PDF。优势是文档创建简单，可以本地存储在Dropbox中。并且对于每次发布，版本可以自动更新。
• 在线——你的企业网站。这是更推荐的方式。然而，在更新时可能会导致一些额外的IT开销。

希望这些指南对你有所帮助。也欢迎进行反馈。

OneAPM 能为您提供端到端的 Java 应用性能解决方案，我们支持所有常见的 Java 框架及应用服务器，助您快速发现系统瓶颈，定位异常根本原因。分钟级部署，即刻体验，Java 监控从来没有如此简单。想阅读更多技术文章，请访问 OneAPM 官方技术博客。

本文转自 OneAPM 官方博客

原文地址：http://blog.mobitech.io/2016/02/sdk-writing-guidelines.html。