Android 项目代码质量保证实践

针对 EmpytActivity 这里需要定义的文件有：
< >globals.xml.ftl：定义当前模板的一些全局变量recipe.xml.ftl：定义模板拷贝的逻辑等template.xml：定义模板对话框的样式template_blank_activity.png：定义模板的图标root/src/app_package/SimpleActivity.java.ftl：具体的模板文件

图片来自：http://www.slideshare.net/murphonic/custom-android-code-templates-15537501

• 自定义模板
  而针对我们需要自定义的模板，可以在模板定义路径下新建文件夹和文件即可，细节内容可查看 Tutorial How To Create Custom Android Code Templates
  项目的模板文件内容：
  
   

  

  image17
  设置完模板文件之后，重启 Android Studio，可以生效模板文件，使用模板文件如下：
  
   

  

  image18

4 编码后期 - 静态代码检查

由上，我们定义了编码规范，定义了 Live Template 和 Android Studio Template 方便程序猿更好的准守我们的项目编码规范。然后编码规范毕竟只是软规范，而提供编码模板更多的解决大量 util 的使用问题和便利小伙伴完成机械编码，并不能完全保证程序猿严格按照全部的规范来编码。
为此，我们需要一套静态代码检查机制能检查已有的代码是否遵守规范。总结已有的规范，可以将规范类型归纳为普通 Java 规范、普通 Android 规范、具体项目规范等。而这些检查点，可以配合不同的检查工具进行检查。

4.1 检查 java 代码风格 - CheckStyle

对于 java 规范，checkstyle 帮助开发者实现常用的检查。这里 CheckStyle 能检查的内容有：

1. Javadoc 注释
2. 命名约定
3. 标题
4. Import 语句
5. 体积大小
6. 空白
7. 修饰符
8. 块
9. 代码问题
10. 类设计
11. 混合检查（包活一些有用的比如非必须的System.out和printstackTrace）

检查内容很多，而检查项需要和具体的项目规范做结合。如，每行代码字符数控制在 80，单页代码行数控制在 800 等。因此需要结合配置文件，来检查项目中的 java 代码。在 Android Studio 上配置 CheckStyle 流程如下：

1. 在 Android Studio 中添加 gradle Plugin
   

   apply plugin: 'checkstyle' 

2. 设置 CheckStyle 版本
   

   checkstyle { toolVersion '6.1.1' showViolations true } 

3. 配置 CheckStyle 检查项
   

   task checkstyle(type: Checkstyle) { configFile file("$configDir/checkstyle/checkstyle.xml") configProperties.checkstyleSuppressionsPath = file("$configDir/checkstyle/suppressions.xml").absolutePath source 'src' include '**/*.java' // 检查 java 代码 exclude '**/gen/**' // 排除生成的代码 classpath = files() ignoreFailures true // 忽略检查失败的情况，避免gradle命令执行中止 } 

4. 配置自定义的检查项：
   checkstyle.xml：
   

   <!--单个文件方法数上限最多为 30--> <module name="MethodCount"> <property name="maxTotal" value="30"/> </module> <!--方法名的首字母是小写--> <module name="MethodName"> <property name="format" value="^[a-z][a-zA-Z0-9]*$"/> </module> <!--静态变量名的首字符是 s--> <module name="StaticVariableName"> <property name="format" value="^[a-z][a-zA-Z0-9]*$"/> <property name="applyToPublic" value="true"/> <property name="applyToProtected" value="true"/> <property name="applyToPackage" value="true"/> <property name="applyToPrivate" value="true"/> </module> <!--只有私有构造函数的类需要定义成 final 类型--> <module name="FinalClass"/> ... 

   具体其他的检查项配置可以查看 检查配置链接
5. 执行 checkstyle 检查
   

   ./gradlew checkstyle 

6. 查看检查结果
   命令执行结束，查看检查结果文件：${project}/app/build/reports/checkstyle/checkstyle.html
   
    

   

   image

4.2 检查 java 代码质量 - FindBugs

与 CheckStyle 工具不同的是，FindBugs 不注重样式或者格式，而是试图寻找出真正的缺陷或者现在的性能问题。FindBugs 检查类和 Jar 文件，不是通过分析类文件的形式或结构来分析程序，而是使用 Visitor 模式，将字节码与一组缺陷模式进行对比以发现可能的问题。而这些问题比如如下：

1. 忽略返回值
   
    

   

   image
   上述代码执行结束之后，并没有什么意义，变量 a 的值也不会变成 dddbbbccc。因此，上述代码很可能是程序猿的 bug。为此 FindBugs 能找出这种问题
2. 空指针示例
   
    

   

   image
   上述最后一行代码，很明显在执行的时候会发生空指针异常，这里因为 FindBugs 无法知道变量 strMaps 是否确实有 aaa 这个 key，为此这里会检查出错误。
3. 未初始化的成员变量使用
   
    

   

   image
   这里由于类成员变量 actions 并未初始化，因此当 actions.add("TEST") 被执行的时候会发生异常。

Android Studio 上 FindBugs 的集成如下：

1. 在 gradle 中引入插件
   

   apply plugin: 'findbugs' 

2. 在 gradle 中配置 findbugs task
   

   task findbugs(type: FindBugs, dependsOn: "assembleDebug") { ignoreFailures = false effort = "max" reportLevel = "high" excludeFilter = new File("$configDir/findbugs/findbugs-filter.xml") classes = files("${project.rootDir}/app/build/intermediates/classes") source 'src' include '**/*.java' exclude '**/gen/**' reports { xml.enabled = false html.enabled = true xml { destination "$reportsDir/findbugs/findbugs.xml" } html { destination "$reportsDir/findbugs/findbugs.html" } } classpath = files() ignoreFailures true // 避免检查失败 gradle 执行中止 } 

3. 执行 findbugs 检查
   

   ./gradlew findbugs 

4. 查看检查结果
   查看检查结果文件：${project}/app/build/reports/findbugs/findbugs.html
   
    

   

   image

4.3 检查 Android 代码质量 - Lint

4.3.1 基本介绍

前面 FindBugs 的检查实例(忽略返回值, 未初始化的成员变量使用)，可以发现在 Android Studio IDE 上，已经出现了标黄提示，我们把光标放上去，就能看到具体的提示了：
按 cmd + F1 可以看到具体的错误提示：
这就原生 Lint 给我们提供的错误提示功能。除了和 FindBugs 重复的纯 java 代码检查之外，Lint 能检查很多其他工具无法检查的内容，也更贴合 Android：

在 Activity 内定义非静态内部类 Handler 的报警

在 AndroidManifest.xml 中定义 export 为 true 的广播接受器，但没有定义权限，Lint 检查认为是不安全的

build.gradle 文件中引用的 support 包的版本低的提示

Android Lint 是一个静态代码检查工具，能够对潜在的 bug，可能的安全性、性能、可用性、可访问性、国际化等优化内容做出监测：

来自官方文档 Improve Your Code with Lint

1. App Source Files：工程中的源文件，包括 java 代码、资源 xml 代码、gradle 文件，图片资源文件以及 progroud 等文件
2. lint.xml：配置文件，配置哪些 lint 检查可以排除，自定义问题的严重级别
3. lint Tool：静态代码检查工具，可以是命令行或者集成在 Android Studio 上
4. lint Output：代码检查结果，可以直接显示在 Console 上，也可以是 lint-result.html

4.3.2 原生 Lint 检查

在 Android SDK Tools 16 及更高的版本中，Lint 工具会自动安装。原生 Lint 的检查项已经有 200 多项 (包括前面示例的 5 项内容)，因此使用原生的功能点，就能检查开发中的大部分通用问题。

1. Android Studio IDE 上配置 Lint 检查偏好设置
   (Mac 下) Preferences → Editor → Inspections 进入 Android Studio 的 Lint 配置界面
   
    

   

   image
   • A：配置 Profile，方便不同项目或者不同情况下使用不同的 Profile 进行检查
   • B：Lint 检查点 Group
   • C：Lint 检查点具体描述
   • D：Lint 检查点警告级别设置
   • E：Lint 检查点开关
2. lint.xml 上配置 Lint
   除了可以通过 IDE 配置 Lint，还可以通过直接 lint.xml 为单个项目配置检查规则
   

   <?xml version="1.0" encoding="UTF-8"?> <lint> <!-- Disable the given check in this project --> <issue id="IconMissingDensityFolder" severity="ignore" /> <!-- Ignore the ObsoleteLayoutParam issue in the specified files --> <issue id="ObsoleteLayoutParam"> <ignore path="res/layout/activation.xml" /> <ignore path="res/layout-xlarge/activation.xml" /> </issue> <!-- Ignore the UselessLeaf issue in the specified file --> <issue id="UselessLeaf"> <ignore path="res/layout/main.xml" /> </issue> <!-- Change the severity of hardcoded strings to "error" --> <issue id="HardcodedText" severity="error" /> </lint> 

   来源 Android Develop 文档 Improve Your Code with Lint

3. gradle 中配置 Lint task
   

   android { lintOptions { abortOnError false // 配置 lint 过程中出错，不中止 gradle 任务 xmlReport false htmlReport true lintConfig file("$configDir/lint/lint.xml") // 配置 lint 检查规则 htmlOutput file("$reportsDir/lint/lint-result.html") // 配置 lint 输出文件 xmlOutput file("$reportsDir/lint/lint-result.xml") // 配置 lint 输出文件 } } 

4. 执行检查
   在工程根目录执行以下命令 (Mac)，以执行检查任务
   

   ./gradlew lint 

5. 检查结果
   生成的检查结果在 ${项目工程}/app/build/reports/lint/lint-result.html
   
    

   

   image

4.3.3 自定义 Lint 检查

虽然原生的 Lint 检查已经很强大了，检查项也已经很多，然而还是无法满足项目中的特有需求：

1. log 统一使用 LogUtil
2. 对应 Activity 的 layout 命名为 activity_XXX
3. 对应 Fragment 的 layout 命名为 fragment_XXX
4. Activity 必须派生自 BaseBlankActivity 或 BaseActionBarActivity

对于以上这些需求，原生 Lint 检查（包括 CheckStyle，FindBugs）就已经无能为力了，我们必须编码支持自定义检查。以项目中集成的 Lint 检查为例，讲述流程：

4.3.3.1 配置 Gradle，引入 lint 库

dependencies { ... compile 'com.android.tools.lint:lint-api:24.5.0' compile 'com.android.tools.lint:lint-checks:24.5.0' } 

• lint-api: 官方给出的API，API并不是最终版，官方提醒随时有可能会更改API接口。
• lint-checks：已有的检查。

4.3.3.2 定义 IssueRegistry 类

新建一个 MyIssueRegistry 类，继承自 IssueRegistry。用来注册我们自定义的全部 issue

public class MyIssueRegistry extends IssueRegistry { @Override public List<Issue> getIssues() { System.out.println("********YXLint rules works!!!********"); return Arrays.asList( LogUsageDetector.ISSUE, ToastUsageDetector.ISSUE, ActivitySuperClassDetector.ACTIVITY_SUPER_CLASS_ISSUE, ... BuildGradleVersionDetector.ISSUE); } } 

其中：

• LogUsageDetector.ISSUE：用于检查不允许直接使用 Log.* 方式输出本地日志的代码
• ToastUsageDetector.ISSUE：用于检查直接用 Toast 方式显示 toast 的代码
• ActivitySuperClassDetector.ACTIVITY_SUPER_CLASS_ISSUE：用于检查 Activity 的基类
• BuildGradleVersionDetector.ISSUE：用于检查 gradle 文件中不允许直接写数字版本号的代码

4.3.3.3 gradle 清单项中注册前面定义的 IssueRegistry 类

jar { manifest { attributes('Lint-Registry': 'com.netease.htlint.lintrules.MyIssueRegistry') } } 

4.3.3.4 定义 Detector

MyIssueRegistry 类中声明注册了各个 Detector 的 Issue。Issue 由 Detector 发现并报告，是 Android 程序代码可能存在的风险。而这里就需要真正实现这些 Detector，以检查 Activity 的基类为例。
ACTIVITY_SUPER_CLASS_ISSUE 这个 Issue 的定义需要使用 Issue.create(...) 方式实现，同时需要传入 6 个参数分别如下：

• A：一个固定的唯一的 id 代表这个 Issue
• B：对于问题的简短总结，描述问题而不是修复措施
• C：完整的问题解释和修复建议
• D：问题类别，现在已有的问题类别有如下
  • Lint
  • Correctness (incl. Messages)
  • Security
  • Performance
  • Usability (incl. Icons, Typography)
  • Accessibility
  • Internationalization
  • Bi-directional text
• E：优先级，必须在1到10之间，10为最重要/最严重。
• F：严重级别，可选值有 Fatal, Error, Warning, Informational, Ignore
• G：为 Issue 和 Detector 提供映射关系，Detector 就是当前类。声明扫描检测的范围 Scope，描述 Detector 需要分析时需要考虑的文件集，包括：Resource 文件或目录、Java 文件、Class 文件

ActivitySuperClassDetector 继承自 Detector，并实现 Detector.JavaScaner。这里主要自定义实现的方法如上图 H，I

• H：检查类的基类是 "android.support.v4.app.Activity" 或 "android.app.Activity"
• I：具体检查类的方法，这里需要排除非 yanxuan 包名下的代码，判断当前类的基类是否是 BaseBlankActivity 或 BaseActionBarActivity？如果都不是的话，则报告错误
• J：报出问题的方法：该方法中指定参数有：
  • 需要报错的 Issue
  • 发生问题的代码在语法树上的节点
  • 发生问题的代码位置
  • 警告的信息

4.3.3.5 生成 jar 包

完成上述步骤，可以在控制台中通过命令 ../../gradlew assemble 来执行编译任务，就可以输出我们需要的 jar 文件 (htlintrules_jar-0.0.1.jar) 了

4.3.3.6 jar 的使用

按照 Google 方法，可以将 htlintrules_jar-0.0.1.jar 拷贝到 ~/.android/lint 中，但缺点是针对会影响一台机器其他的工程。很明显，我们的自定义 Lint 检查有很多是项目中特有的一些编码规范。
为此，我们采用 LinkedIn 方案：将 jar 放到一个 aar 中。这样我们就可以针对工程进行自定义 Lint，lint.jar 只对当前工程有效。
在现有的 htlintrules_jar 工程的 build.gradle 中添加代码，整体看起来如下：

apply plugin: 'java' apply plugin: 'maven' dependencies { compile 'com.android.tools.lint:lint-api:24.5.0' compile 'com.android.tools.lint:lint-checks:24.5.0' } jar { manifest { attributes('Lint-Registry': 'com.netease.htlint.lintrules.MyIssueRegistry') } } configurations { lintJarOutput } dependencies { lintJarOutput files(jar) } defaultTasks 'assemble' 

同时新建另一个工程 htlint，在其 build.gradle 文件中添加如下代码：

/* * rules for including "lint.jar" in aar */ configurations { lintJarImport } dependencies { lintJarImport project(path: ':htlintrules_jar', configuration: "lintJarOutput") } task copyLintJar(type: Copy) { from (configurations.lintJarImport) { rename { String fileName -> 'lint.jar' } } into 'build/intermediates/lint/' } project.afterEvaluate { def compileLintTask = project.tasks.find { it.name == 'compileLint' } compileLintTask.dependsOn(copyLintJar) } 

最后在 app 工程的 build.gradle 中添加 htlint 引用，配置完成

dependencies { compile project(':htlint') // lint 检查库 ... } 

4.3.3.7 自定义 Lint 检查执行及结果检查

在 ${项目工程}/app/ 目录下执行 ../gradlew lint：
根据提示查看 lint-result.html 文件，可以查看到前面编写的 ActivitySuperClassDetector.ACTIVITY_SUPER_CLASS_ISSUE 已经生效，并且检查出了相关的非规范代码。

4.3.3.8 排除错误的检查结果

前面很好的给出了检查结果了，然而我们会发现，FullScreenVideoActivity 确实是需要的错误检查结果，而 WXEntryActivity 却不是，这个类是有集成微信分享时需要的，并且按照微信开放平台的文档来编写，因此并不需要按照项目规范，继承 BaseBlankActivity 或 BaseActionBarActivity。为此，我们期望 WXEntryActivity 不应该被检查出 WrongActivitySuperClass 错误
为此，我们可以在 WXEntryActivity 类名签名添加 SuppressLint 注解：

@SuppressLint("WrongActivitySuperClass") public class WXEntryActivity extends Activity implements IWXAPIEventHandler{ ... } 

1. 排除 java 类或者方法的 Lint 检查
   若需要抑制某个 Issue 检查，可以在类定义签名或者方法定义签名，添加注解 @SuppressLint(${IssueId})。这里设置的就是具体某个 Issue 的 id 值
   若需要抑制全部的 Issue 检查，可以使用 all 关键字，比如：@SuppressLint("all")
2. 排除 xml 资源的 Lint 检查
   如项目中引入微博分享 sdk，按照官方文档，需要在 AndroidManifest 中声明 com.sina.weibo.sdk.net.DownloadService 这个 Service，而这个 Service 会被 Lint 检查为未定义，为此需要 xml 文件中也过滤部分代码的 Lint 的检查：
   

   <manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools" package="com.netease.yanxuan"> ... <service android:name="com.sina.weibo.sdk.net.DownloadService" android:exported="false" tools:ignore="MissingRegistered" /> </manifest> 

   这里对于单个 Issue 过滤的规则为：tools:ignore=${IssueId}
   如果需要过滤全部的 Issue，可以使用 all 关键字：tools:ignore="all"

4.4 其他代码检查工具

4.4.1 360 火线

360 火线 是 360 公司和信息安全部门深度合作，定制的适用于 360 公司产品的安卓 APP 安全检查规则。总共覆盖 61 项代码检查。使用也非常方便，细节看 使用文档，可以直接使用 jar 包并执行命令或集成 Android Studio Plugin 执行检查

4.4.2 pmd

pmd 代码检查工具，包含 16 个规则集，涵盖了 Java 的各种常见问题。其中规则集包含 基本（rulesets/basic.xml），终结函数（finalizer），未使用的代码（rulesets/unusedcode.xml），设计（rulesets/design.xml） 等。
相比 FindBugs，pmd 的一些规则更具争议，但 pmd 支持我们构建自己的规则集

<?xml version="1.0"?> <ruleset name="customruleset"> <description> Sample ruleset for developerWorks article </description> <rule ref="rulesets/design.xml"/> <rule ref="rulesets/naming.xml"/> <rule ref="rulesets/basic.xml"/> </ruleset> 

4.5 代码检查工具整合及集成 jenkins

为整合这些检查工具，在 gradle 中自定义 check 命名，并依赖其他的 task。在执行检查的时候，可以通过 ./gradlew check 来执行全部的检查命令。

check.dependsOn 'checkstyle', 'findbugs', 'pmd', 'lint' 

另一方面，这种代码检查，如果等到开发完成的时候再去执行，很可能问题积累了很多，甚至导致产品上线前，开发并不能来得及修正全部的问题。为此，可以将代码检查的命令集成 jenkins，保证开发每天都能看到当前的代码的缺陷，能及时的修改

5 总结

我们从编码前的编码规范，编码进行中的编码模板，编码结束后的代码静态检查，保障了程序小伙伴们的代码。除此之外，还有很多不完善的地方需要我们做进一步处理：

1. 和特定项目相关的自定义 Lint 检查项，仅支持了一部分的编码规范，自定义 Lint 检查项需要后续完成
2. 虽然检查工具很多，检查的结果内容也很多，而很明显，这些检查工具相互之间是有重复的情况（主要是纯 java 代码部分的检查），因此如果整理检查结果，并过滤出我们真正关心的问题，也是后续需要完成的内容

原文转自：https://www.jianshu.com/p/6a38e9dcc0d9