如何让你的开源项目更加正式

本文将以 weixin-sdk 为例，介绍如何让你的开源项目看起来更加正式。

一个好的开源项目，通常会有以下的特性：

• 详细且格式良好的 README 文件（软件使用文档），这个可以参考：中文技术文档的写作规范
• 开源协议的选择，常见的有 Apache-2.0 MIT 等
• 良好的编码风格
• 完善的单元测试

本文将详细介绍后面两点。

良好的编码风格

一个良好的项目，通常需要有统一的风格，因为一个项目通常会有很多人一起合作，如果每个人都有自己的编码风格，那整个项目到最后看起来就会非常乱，所以最好在一开始就定义统一的风格，为此我们可以通过插件的帮助来约束代码风格（如前端的 eslint 及后端 Java 的 check-style 等）。这里提供两个项目，供大家参考：

• 阿里巴巴Java开发手册
• Google styleguide

因为 weixin-sdk 是 Java 项目，所以我将使用 check-style 插件，具体的 check-style 规则则是使用的 Google styleguide 的 check-style 文件，大家也可以针对自己的编码风格自行编写 check-style。
要使用 check-style 检查代码，首先要添加 maven-checkstyle-plugin，并配置 check-style 规则文件的位置：

      
        org.apache.maven.plugins
        maven-checkstyle-plugin
        3.1.0
        
          check-style-roles.xml
          UTF-8
          true
          true
          false
          warning
        
        
          
            validate
            validate
            
              check
            
          
        
      

添加了 check-style 插件后，在使用 maven 构建项目时，它首先就会根据我们配置的规则对代码进行静态检查，如果静态检查失败，则构建直接就会失败。如：

image.png

但是，目前项目只能在本地进行代码检查，我们更希望的是当有人给项目提交 PR 时，GitHub 能自动执行 check-style 检查，为了实现此功能，我们还需借助 travis-ci 这个工具。

image.png

我们可以直接通过 GitHub 登录 travis-ci，它会自动读取我们的项目，我们只需要打开需要执行自动构建的项目的开关，并进行简单的设置即可。当我们打开了开关后，它会自动在我们的 GitHub Repo 中注册一个 Webhook，用于触发自动构建：

image.png

但是它怎么能知道我们的项目依赖什么环境以及怎么执行构建命令呢？这就需要我们在项目根目录中添加 travis-ci 的配置文件 .travis.yml，如：

language: java

jdk:
- openjdk8

install:
- mvn install -Dmaven.test.skip=true

script:
- mvn test -DactiveProfile=test
after_success:
- mvn clean test -DactiveProfile=test jacoco:report coveralls:report
notifications:
  email:
  - [email protected]

在上面的配置文件中，我们指定了项目的语言，依赖的环境以及需要执行的脚本和结果通知的地址。
当我们的操作触发了 GitHub 的事件后（如提交了 PR），GitHub 会通过注册的 WebHook 将事件发送给 travis-ci,travis-ci 收到事件后，就会拉取代码，读取我们项目中的 .travis.yml，根据配置执行构建，在构建完成之后又通过 GitHub 的 API 将结果发送给 GitHub。这样就能实现我们之前的需求了。

image.png

点击 Details 链接进去后，我们就可以看到详细的日志：

image.png

完善的单元测试

一个好的开源项目，单元测试也是必不可少的，这里介绍一个 GitHub 的插件 coveralls，主要用于检测代码的单元测试覆盖率，集成方式非常简单，同样可以通过 GitHub 账号登录，登录后你将得到一个 repo_token，我们需要将这个值配置到 travis-ci 的环境变量中：

image.png

同时，我们还需要添加 coveralls maven 插件：

      
        org.eluder.coveralls
        coveralls-maven-plugin
        4.3.0
      

      
        org.jacoco
        jacoco-maven-plugin
        0.7.6.201602180812
        
          
            prepare-agent
            
              prepare-agent
            
          
        
      

这里我使用了 jacoco 作为代码覆盖率检测工具，如果你想用其它工具，可以参考：coveralls-maven-plugin

到此所有的配置都完成了，当我们提交 PR 后，首先会触发 travis-ci，它会进行代码静态检查以及跑单元测试，当 travis-ci 成功后，就会继续触发 coveralls 进行代码覆盖率检查，并将检查结果告知 GitHub。

image.png

可以看到，目前项目的测试覆盖率仅为 6%。

优化 README

为了更方便的查看构建结果及代码覆盖率，我们还可以将 travis-ci 以及 coveralls 提供的标签贴到我们项目的 README 文件中，最后的效果如下：

image.png

设置保护分支

当构建工具配置完成后，我们还需要将 master 分支设置为保护分支，使 PR 只有在构建成功以及进行 Code Review 后才能合入 master。

image.png

其它

• 目录
• 上一篇
• 源码