但也要注意一点,如果可以,尽量不要让你 SDK 中的类名(函数名)和别人的完全一致,否则可能给用户带来困扰:这么多同名的函数,我该用哪个呢?哪个是你开发的 SDK 呢?
可理解性有时,用户可能不满足于简单地使用你的 SDK,而是希望阅读你的 SDK 源码来进一步了解,用的才更放心。
因此,除了易用外,还要让你的 SDK 便于理解,不能金玉其外败絮其中。
这个就和编码习惯有很大的关系了,无论是写 SDK 也好,还是做项目也罢,都要做到以下几点:
结构清晰把代码按照功能或类别进行整理,放到指定的目录下。常见的做法有分包、分层等,让人一眼就知道每个目录下的文件的作用。
比如下面这个经典的 Java 项目结构,service 目录是编写业务逻辑的、constant 是存放常量的、utils 是存放工具类的等等,都很清晰:
统一风格统一风格的目标很简单:让项目看起来是同一个人写出来的。
比如代码缩进都用 4 个空格、命名都用驼峰式等。尤其是功能相似的代码,一定要保持命名和用法的统一!比如解析文本的函数,不要一会叫 "parseXXX"、一会儿又叫 "jiexiXXX",给用户都整乐了~
但实际上,团队开发中,很难做到这点。因此才需要有一套通用的代码规范,大家都去遵守规范,才能让项目更好理解、更便于维护。
编写注释最好给 SDK 中的每个类和函数的 开头 都加上注释,这样用户在使用 SDK 时,甚至都不需要看文档,直接看代码注释就能知道它是干嘛的、怎么用。
随便打开 Java SDK 或者网上知名 SDK 中的一个函数,一般都能看到这些注释,包括对函数功能的描述、参数含义、返回值含义等:
说明文档除了注释外,还要编写一个说明文档(用户手册),包括如何引入 SDK 、有哪些功能、应该怎么使用等等,甚至还可以补充一些关键的实现细节、以及常见的问题列表。
这点也会极大地影响用户的选择。就我个人而言,没有文档的 SDK 我一般是不会选用的,万一出了事我找谁呢?
可扩展性编写 SDK 的一大难点是:不仅要考虑到大部分通用的使用场景,还要满足小部分用户定制化的需求。
因此,SDK 的可扩展性是很重要的,但怎么提升呢?
轻量依赖一方面,我们可以尽量减少 SDK 本身对其他类库的依赖。
举个例子,假如你要做一个很轻小的工具类,可能只有几十 KB,那就没有必要再引入一个几百 KB 的依赖库了,得不偿失!别人也不乐意用啊!
轻量依赖不仅可以减少 SDK 的体积,更关键的是可以减少依赖冲突的可能性。我自己也曾经遇到过很多次这样的尴尬局面:引入一个工具类后,整个项目就跑不起来了!
自定义实现为了提高 SDK 的通用性和灵活性,在设计 SDK 时,除了提供默认实现外,建议提供一个通用接口或抽象类,让用户来继承,编写自己的实现方式。
举个例子,假设我们要编写一个日期解析类,默认的解析规则是按照短横分割字符串:
// 按照 \'-\' 切分 date = DateUtils.parse(\'2021-01-18\')如果只能做到这点,那这个 SDK 就很死板。因为用户可能想按照冒号或其他规则来解析。
怎么实现呢?
我们可以允许用户自己传入分割字符:
// 按照 \'-\' 切分 parseRule = \':\' date = DateUtils.parse(\'2021-01-18\', parseRule)还可以让用户自己来控制解析的方式:
// 自定义解析器 interface MyParser extends Parser { // 需要用户自己实现 void doParse(); } // 指定解析器 date = DateUtils.parse(\'2021-01-18\', MyParser.class);这两种方式在 SDK 的设计中屡见不鲜,此外还可以让用户自行编写或指定配置文件,也能提高灵活性。
高效稳定其实,开发 SDK,尤其是在大厂开发 SDK,是个很 “坑” 的工作,我相信做过的朋友会感同身受。