SDK开发技术规范总结

SDK是Software Development Kit的缩写,译为“软件开发工具包”,通常是为辅助开发某类软件而编写的特定软件包,框架集合等,SDK一般包含相关文档,范例和工具。
SDK可以分为系统SDK和应用SDK.所谓的系统SDK是为特定的软件包,软件框架,硬件平台,操作系统等应用时所使用的开发工具集合.而应用SDK则是基于系统SDK开发的独立于具体业务而具有特定功能的集合.

1.设计原则

优秀设计

• SDK 必须要遵从原生、简短、执行迅速、代码干净、易读、可测试的原则。

• 一个接口尽量只做一件事

• SDK所包含的接口数量越少越好，接口参数越少越好，调用流程越少越好 向后兼容。

• SDK产品往往是迭代的，向后兼容非常重要。

兼容性

• 一般出现接口兼容性的问题主要是由于最初需求考虑不完善，导致后面进行方案优化时引起接口的变更，使之前的接口成为历史的老大难问题，最终造成删除难度大。

• 在确定开发方案时，就需要考虑到一部分接入方使用了该功能，需要保证该功能正常读取。一部分接入方没有使用到该功能，要确保无异常出现。一般这种兼容性问题会决定开发方案的技术实现。

参数设计

• 一些固定的参数可以通过config配置参数在SDK初始化的时候设置

• 接口参数尽量少

• 参数过多，可合并成一个对象

• 能同步尽量同步调用，返回结果能不用回调就别用回调

• 多线程能自己处理就自己处理

性能高效

• 良好的性能带来良好的用户体验，性能优化也是Android 开发者基本素质。
• 内存占用，内存抖动
• 多线程控制，
• 避免主线程阻塞
• 电量消耗

回调设计

• 减少全局回调；必须全局回调的，
• 分模块回调 回调中接口尽可能的少
• 异常情况回调
• 错误回调采用errorCode+errorMsg组合

日志设计

• 核心处理log log日志可配置，
• 可控制打印log级别

注释

• 代码注释要规范和清楚
• 接口注释要特别完善
• 注释形式统一
• 注释内容准确简洁

输出

• androidstudio平台相关包：demo工程+aar仓库
• 可直接安装运行的demo.apk包
• 示例代码，维护一份准确的示例代码是一劳永逸的事情，可避免很多不必要的打扰。

2.代码规范

代码规范可以参考的规范很多，如阿里巴巴java开发规范、android开发规范、和github上有开发总结的规范。
命名规范

• 代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。正确的英文拼写和语法可以让阅读者易于理解，避免歧义。

包规范

• 包名全部小写，连续的单词只是简单地连接起来，不使用下划线，采用反域名命名规则，全部使用小写字母。
• 类、方法、变量的范围尽可能缩小（能用 private 不用 public，能用局部变量就不用全局变量）
• package 内高内聚，package 间低耦合。关于包名的划分，推荐采用 PBF（按功能分包 Package By Feature），区别于通常的PBL（按层分包 Package By Layer） PBL 降低了代码耦合，但带来了 package耦合，要添新功能，需要改 model、dbHelper、view、service 等等，需要改动好几个package下的代码，改动的地方越多，越容易产生新问题，不是吗li>
• PBF 的话 featureA 相关的所有东西都在 featureA 包，feature 内高内聚、高度模块化，不同 feature之间低耦合，相关的东西都放在一起，还好找。 哪块要添新功能，只改某一个 package 下的东西。 package有私有作用域（package-private scope）
• 你负责开发这块功能，这个目录下所有东西都是你的。 很容易删除功能
  统计发现新功能没人用，这个版本那块功能得去掉。
• 如果是 PBL，得从功能入口到整个业务流程把受到牵连的所有能删的代码和 class 都揪出来删掉，一不小心就完蛋。如果是 PBF，好说，先删掉对应包，再删掉功能入口（删掉包后入口肯定 错了），完事。

类名

• 类名都以 UpperCamelCase 风格编写。
• 类名通常是名词或名词短语，接口名称有时可能是形容词或形容词短语。现在还没有特定的规则或行之有效的约定来命名注解类型。

方法名

• 方法名都以 lowerCamelCase 风格编写。
• 方法名通常是动词或动词短语。

常量名

• 常量名命名模式为 CONSTANT_CASE，全部字母大写，用下划线分隔单词。

资源规范

• 资源命名使用下划线分隔的小写字母
• 所有资源需要有前缀区分，避免引入应用后出现资源名冲突
• 应用图标放在 mipmap 下，普通资源放在drawable
• 尽量用.9.png
• 尽量使用内置的资源，如@android:color/white,

3. 文档规范

• 内容准确完整，一个优秀的SDK开发人员在编写文档前会做充分的接口场景调用验证，已保证内容的准确和完整。

• 易读易用，SDK开发人员作为文档的第一个读者和使用者，在使用文档过程中应该有意识的降低自己的姿态，时常假想一个很low的开发者在阅读自己文档时候的样子，通过积极阅读和不断改进确保一个不是很擅长编程的开发者也能使用我们的SDK。

• 精简文档，一个优秀的SDK开发人员会通过减少重复、避免冗余、整洁代码等措施来精简文档的内容，同时这也减少了文档的维护成本。

• 更新日志文档
  描述清楚相对上个版本的所有变更（优化项酌情考虑是否添加），如：

v2.23.2
修复xxx崩溃的偶发性bug
调整xxx列表页面ui
增加xxx的接口，详情看接口文档

如果api变动较大，需提供变更对照文档

• 接口文档/集成指南

一般文档结构如下：

产品简介

功能说明 适配版本 开发包内容

接入准备

相关key的申请等

相关配置

manifest配置 混淆配置 依赖配置 …

接口调用

接口详情

示例代码

FAQ

依赖冲突 …

• 测试 告

在实际的接入过程中，有很多接入方需要提供相关的性能测试说明，这部分的内容需要及早准备。测试 告的工作可以研发和测试一起协助进行输出，最终方便后续的支持工作，降低维护成本。

4.第三方库依赖处理原则

原则：

• 能用系统的API解决的，就不要使用第三方，减少对其他库的依赖；
• 最小可用性原则，即用最少的代码，如无必要勿增实体；
• 最少依赖性原则，即用最低限度的外部依赖，如无必要勿增依赖

SDK开发中，需要尽量避免依赖第三方库，使用通用的Android SDK自带的官方库能满足需求即可，以免引起不必要的冲突或者三方库不要放到lib包下，默认打包进去封装过程中的aar二次打包问题；

比如，不要为了一个简单的JSON数据转换就引入Fastjson 、Gson之类的第三方json解析转换库。

如果确实因为项目需要，要引入一些开源库，可以通过源码集成的形式引入，再更改一下包名，避免集成冲突。

第三方依赖处理

打包aar只是单纯的引用library项目中的class和资源，对于需要的第三方依赖是没有引入到aar中的，一种简单的方法就是在你的项目gradle中重新引入依赖，这样是可以运行的，但这本身就是一个问题，所以不推荐使用这种简单粗暴的方法

多个jar打包到一起

由于gradle版本的差别，实际library编译输出的目录是不同的，需要根据gradle版本进行适配更改。但是第三方jar打包到一起需慎用，因为第三方依赖会有升级，会和使用方的版本会有冲突，只可做临时测试。

maven方式

如果有私服的话也可以把生成的文件放入到私服中，编译完成后，你会发现我们想要的aar文件和pom文件，简单介绍一下pom文件，这个文件就是我们的第三方引用文件。打开pom文件进行查看你会发现你引用的三方的文件名称版本 等。别人使用你的SDK的时候他也可以通过implements的方式来引用你的SDK了。

5.版本管理规范

版本 规则

使用三位版本 ，每位版本 最高三位数字：（1_999）.（0999）如：1.0.12

版本 递增原则：

• 第三位：bug修复，极小的变更
• 第二位：一般的功能迭代
• 第一位：项目重构，功能变更较大，需团队共同确定

命名规则

遵循以下命名规则可避免不同sdk命名冲突

• 所有资源命名前缀：mEft_xxx_ 工程命名：eft-sdk-xxx-android
• demo 项目命名：demo，包名：cn.eft.sdk.xxx.demo sdk
• 项目命名：mEftXxxSDK，包名：cn.etf.sdk.xxx

打包原则

打包必须符合以下原则和规范

• 对外提供的包不能包含任何编译生成的文件和目录，如安卓的build目录
• 使用脚本一键打包，提升打包效率，降低手动打包带来的出错率
• 打包脚本需与项目其他脚本分离，尽量职责单一 包中尽量提供示例工程， 示例工程必须让开发者以最低的成本运行起来
• 打包指令根据实际情况调整，打完的包需亲测有效才可对外发布

参考文献：

1. https://www.haohaohu.com/sdkkai-fa-ji-ben-gui-fan/
2. https://github.com/Blankj/AndroidStandardDevelop#6-%E7%89%88%E6%9C%AC%E7%BB%9F%E4%B8%80%E8%A7%84%E8%8C%83
3. https://zhuanlan.zhihu.com/p/172443606
4. https://juejin.cn/post/6844904100077764622