建立完美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。