江苏龙网

  1. 主页 > 生活百科 > >

大厂的 SDK 写法，偷学到了( 二 )

SDK 写法


大厂的 SDK 写法，偷学到了

文章插图
 
好坏命名
因此 ， 想要写出好的 SDK ， 首先要多用、多参考别人的 SDK ， 养成习惯后你就会发现 ， 大家起名儿都差不多 。
但也要注意一点 ， 如果可以 ， 尽量不要让你 SDK 中的类名（函数名）和别人的完全一致 ， 否则可能给用户带来困扰：这么多同名的函数 ， 我该用哪个呢？哪个是你开发的 SDK 呢？
可理解性有时 ， 用户可能不满足于简单地使用你的 SDK ， 而是希望阅读你的 SDK 源码来进一步了解 ， 用的才更放心 。
因此 ， 除了易用外 ， 还要让你的 SDK 便于理解 ， 不能金玉其外败絮其中 。
这个就和编码习惯有很大的关系了 ， 无论是写 SDK 也好 ， 还是做项目也罢 ， 都要做到以下几点：
结构清晰把代码按照功能或类别进行整理 ， 放到指定的目录下 。常见的做法有分包、分层等 ， 让人一眼就知道每个目录下的文件的作用 。
比如下面这个经典的 Java 项目结构 ， service 目录是编写业务逻辑的、constant 是存放常量的、utils 是存放工具类的等等 ， 都很清晰：
大厂的 SDK 写法，偷学到了

文章插图
【大厂的 SDK 写法，偷学到了】 
Java MVC 项目结构
统一风格统一风格的目标很简单：让项目看起来是同一个人写出来的 。
比如代码缩进都用 4 个空格、命名都用驼峰式等 。尤其是功能相似的代码 ， 一定要保持命名和用法的统一！比如解析文本的函数 ， 不要一会叫 "parseXXX"、一会儿又叫 "jiexiXXX" ， 给用户都整乐了~
但实际上 ， 团队开发中 ， 很难做到这点 。因此才需要有一套通用的代码规范 ， 大家都去遵守规范 ， 才能让项目更好理解、更便于维护 。
编写注释最好给 SDK 中的每个类和函数的 开头 都加上注释 ， 这样用户在使用 SDK 时 ， 甚至都不需要看文档 ， 直接看代码注释就能知道它是干嘛的、怎么用 。
随便打开 Java SDK 或者网上知名 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)


推荐阅读


上一篇：nginx简易实现权限登录

下一篇：什么是B+树，这下懂了... | 干货分享