OpenShift中的持续交付

持续交付

如果要打造一个持续交付的流水线,首先要考虑多环境的问题。一般一个应用程序会有多个环境,比如开发环境、集成测试环境、系统测试环境、用户验收测试环境、类生产环境、生产环境。如何在OpenShift中隔离并建立对这些环境的部署流程有多种方案可以选择。

  1. 同一个project中使用label和唯一名称来区分不同的环境;
  2. 集群中的不同project来隔离环境;
  3. 跨集群来隔离环境。

我们以第二种方式为例,演示下多环境管理问题。

在上图中,我们有一个build project。build project包含了一组相互依赖性比较强的应用,每个应用对应一个build config,产生的Image Stream存放在image register中。而每个环境各对应一个project,其中包含了该应用的deployment config,其镜像输入是build config产生的Image Stream。之所以这样做,有以下几点考虑:

  1. 不同的环境分布在不同的project中,可以很好的借助project的特性进行环境隔离。比如sys project的容器只能部署在label为sys的node上,prod project的容器只能部署在label为prod的node上。
  2. 不同的project可以分别定义权限访问和控制。比如只有QA才能操作sys project中的资源,运维工程师才能操作prod project中的资源。
  3. 不同的环境共用一个Image Stream,保证了应用程序镜像在不同环境中的是完全一致的,防止由于测试环境和生产环境不一致而引入缺陷。

那么大家共用同一个Image Stream,如何实现应用的promotion呢?解决方案就是使用tag。

如上图所示,一个image stream里面有多个版本的镜像,而OpenShift可以为版本添加自定义tag。在不同的project里面,我们配置image的来源为”ImageStreamTag”,名称为”applicationName:environmentName”。比如sys project的镜像名为”App1:sys”,prod project的镜像为”App1:prod”。如果想将version 3的镜像推送到sys环境,只需要简单的给version 3的镜像打上sys的tag,这样部署sys环境时就会自动使用version 3的镜像。

oc tag App1:latest App1:sys

如果在Deployment Config里面配置了自动监听tag的变动的操作,那么一旦你修改了ImageStream的tag,就会自动触发对应环境的部署。

由于应用程序镜像在不同的环境中是一致的,那么变动的部分都被抽取到了外部配置中。如何根据不同的环境来加载对应的外部配置呢?实现方式有很多种,这里介绍了使用Spring Cloud Config的方案。

首先我们将针对不同环境的配置放置在一个git仓中,然后通过Spring Cloud Config Server将其转换为http服务。而我们在应用中嵌入Spring Cloud Config Client,其会接收一个环境变量来拉取指定环境的配置。而该环境变量可以通过Deployment Config来进行注入。

oc env dc/sys PROFILE=sys

使用Spring Cloud Config给予了我们更多的灵活性。我们可以选择在应用程序第一次启动的时候拉取配置,也可以设置每隔一段时间自动更新配置,从而实现热更新。

OpenShift虽然提供了构建和部署的能力,我们有时也需要使用Jenkins之类的工具来可视化以及编排整个流水线。

既然OpenShift是个容器化的管理平台,那么我们完全也可以将Jenkins作为一个应用纳入到OpenShift中来托管,这样Jenkins的Master和Slave都是容器化的。OpenShift官方提供了一个Jenkins2.0的镜像,其预装了OpenShift pipeline插件,可以很方便地进行构建、部署等操作。

生产环境的部署

OpenShift在产品环境的部署默认是rolling的方式。

每次部署时,它会启动一个新的Replica Controller,部署一个pod,然后削减旧的Replica Controller的pod,如此往复,直到旧的Replica Controller中的所有pod都被销毁,新的Replica Controller的所有pod都在线。整个过程保证了服务不宕机以及流量平滑切换,对用户是无感知的。

而有的时候部署场景要负责些,比如我们想在产品环境对新版本做了充分的PVT(product version testing)才切换到新版本。那么就可以使用蓝绿部署的方式。

蓝绿部署方案的关键点在于一个Router对应两个Service。而Route作为向外界暴露的服务端口是不变的,两个Service分别对应我们的生产蓝环境和生产绿环境。同时只有一个Service能接入Router对外服务,另一个Service用来进行PVT测试。切换可以简单的修改Router的配置即可。

port:
  targetPort: app-blue-http
to:
  kind: Service
  name: app-blue

结语

OpenShift在应用的构建以及部署方面为我们提供了大量开箱即用的功能和解决方案,所以实现持续交付不再那么艰难。我们可以将更多的精力花费在提升应用程序质量以及架构方面,交付更好的产品。


更多精彩洞见,请关注微信公众号:思特沃克

Share

对于持续集成实践的常见问题的解答

我之前总结了一下自己在做咨询时辅导团队时遇到的问题,并且给出了相应解答。

Q1:什么是持续集成?

集成,就是一些孤立的事物或元素通过某种方式集中在一起,产生联系,从而构成一个有机整体的过程。知识经济的社会,集成已经成了很重要的一个名词。各行各业基本都会用到集成。比如汽车行业,那么复杂的一台跑车愣是通过一大堆零件组装起来。对于这些传统行业,它们在研发成功以后,可以通过流水线的方法批量生产进行集成。而在软件行业中,集成并不是一个简单的“搬箱子”的过程。因为软件工业是一个知识生产活动,其内在逻辑非常复杂,需求又很难一次性确定,完成的产品与最初的设计往往相差很远。敏捷宣言中就有一条是说响应变化重于遵循计划。而且由于软件行业的迅猛发展,软件变的越来越复杂,单靠个人是根本无法完成。大型软件为了重用及解耦,往往还需要分成好几个模块,这样集成就成了软件开发中不可或缺的一部分。

持续集成这个词语最早是由大名鼎鼎的Martin Fowler。他在早期进行软件行业实习的时候就发现一个问题,即集成是项目中的一个大难题。当他在英国一家软件公司实习时,项目经理亲口告诉他一个项目已经开发了好几年了,现在正在做集成,集成已经进行了好几个月了,每个人都很疲惫,并不知道集成什么时候才能结束。其中一个很重要的原因就是项目集成发生的频率太低,导致大家对项目很没有信心。

在《持续集成》一书中,对持续集成的定义如下:持续集成是一种软件开发实践。在持续集成中,团队成员频繁集成他们的工作成果,一般每人每天至少集成一次,也可以多次。每次集成会经过自动构建(包括自动测试)的检验,以尽快发现集成错误。自从在团队中引入这样的实践之后,Martin Fowler发现这种方法可以显著减少集成引起的问题,并可以加快团队合作软件开发的速度。

Q2:持续集成能给团队带来什么好处?

如果想要谈持续集成的好处,那么我们应该先谈谈没有采纳持续集成,项目会出现什么问题。总体来说,没有采用持续集成的项目一般会面临下面四个问题:

  1. 没有一致的可部署的软件。只有在完成集成测试、系统测试后,才能得到可用的软件,整个过程中只有最后时刻才能拿到可运行软件。集成活动不一定在一个标准的构建机器上生成,而是在某个开发人员的机器上构建的,那么可能存在在其他机器上无法运行的问题。
  2. 很晚才发现缺陷,并且难以修复。实践证明,缺陷发现的越晚,需要修复的时间和精力也就越大。从上一个可工作的软件到发现缺陷之间可能存在很多次提交,而要从这些提交中找出问题并修复的成本会很大,因为开发人员需要回忆每个提交的上下文来评估影响点。
  3. 低品质的软件。 由于集成时每次包含的代码很多,所以大家的关注点主要都是如何保证编译通过、自动化测试通过,而往往很容易忽略代码是否遵守了编码规范、是否包含有重复代码、是否有重构的空间等问题。而这些问题又反过来会影响今后的开发和集成,久而久之集成变得越来越困难,软件的质量可想而知。
  4. 项目缺少可见性

而通过持续集成的活动,我们可以实现以下价值:

  1. 减少风险。缺陷的检测和修复变得更快。软件的健康程度可以测量。
  2. 减少重复过程。让人们有时间做更多的需要动脑筋的、更高价值的工作。通过对重要过程自动化,克服项目中某些成员对实现改进的抵制。
  3. 在任何时间、任何地点生成可部署的软件。对客户来说,可以部署的软件是最实际的资产。
  4. 增强项目的可见性。集成就像我们项目的一面镜子,通过这面镜子能够快速的了解项目目前的状况、存在的问题。
  5. 对开发团队的软件产品建立起更强大的信心。它能够帮我们有效的决策,注意到项目进展的趋势。

Q3:持续集成都包括哪些要素?

一个最小化的持续集成系统需要包含以下几个要素:

  1. 版本管理系统:项目的源代码需要托管到适合的版本管理系统中,一般我们使用git作为版本控制库,版本管理软件可以使用github、gitlab、stash等。
  2. 构建脚本:每个项目都需要有构建脚本来实现对整个项目的自动化构建。比如Java的项目就可以使用gradle作为构建工具。通过构建工具实现对编译、静态扫描、运行测试、样式检查、打包、发布等活动串起来,可以通过命令行自动执行。
  3. CI服务器:CI服务器可以检测项目中的代码变动,并及时的通过构建机器运行构建脚本,并将集成结果通过某种方式反馈给团队成员。

Q4:持续集成的全景图是什么样子的?

以下是持续集成的一个全景图。从中可以看到我们需要版本管理系统、构建脚本、CI服务器、CI构建机器、反馈机制。

Q5:持续集成一般都包含哪些任务?

持续集成并不是说只要代码能编译通过就是集成成功,我们已经把每次集成都看做一次完整的测试。任何迁入到代码库中的代码都应该是可以部署到产品环境的。拿一个Java项目为例,持续集成一般执行的任务有:

  1. 代码静态扫描:通过静态扫描确定代码的一些潜在bug,比如未被使用的变量等。
  2. 代码样式检查:团队一致定义出需要遵循的编码规范,并通过一些插件对迁入的代码进行样式合规性检查,防止不守规范的代码进入版本库。比如方法名首字母小写、类的大字母大写、if关键字后面需要加空格等问题都可以纳入到样式检查中。
  3. 单元测试、集成测试、系统测试:通过运行自动化的单元测试、集成测试、系统测试可以有效的保证迁入代码的质量。一旦有测试失败,开发人员就需要快速反应进行修复。
  4. 测试覆盖率检查:一般项目会设置一个测试覆盖率指标(比如80%),如果代码达不到这样的测试覆盖率,就不会允许代码迁入。这样可以保证开发人员在新增功能时也要为新加入的功能编写自动化测试。
  5. 编译打包:确保没有任何语法错误,生成构建产出物。
  6. 发布: 将通过完整构建的产出物放置到产出物仓库,以便进行后续部署。

这些任务都必须是能通过命令行自动完成的,不同类型的项目任务略有不同。

Q6:持续集成这些任务应该遵循什么顺序?

其中有一个重要的原则就是fail fast,即快速失败。一般会把运行时间短的、价值大的任务放在前面,而运行时间长的任务放置到后面。因为构建成功的标准是所有的验证都能够通过,那么执行时间短的任务放在前面能更快的得到反馈。

Q7:为什么我们组搭建了持续集成服务器,并且还派专人看守CI,但是感觉项目并没有明显的改善?

并不是说搭建了持续集成服务器就说明团队能成功运行持续集成了。持续集成是一个实践,所以大家要遵循一些原则。

大家可以先思考一下问题:

  1. 在CI服务器上多久会看到一次集成?
  2. CI服务器的集成结果是绿色居多(指构建成功)还是红色居多(指构建失败)?
  3. 当构建失败后,团队成员有没有第一时间修复构建,有没有在构建失败的情况下依然在提交代码,在提交代码之前有没有进行本地的私有构建?

从这些问题可以引申出持续集成中需要遵循的一些原则:

  1. 经常提交代码
  2. 不要提交无法构建的代码
  3. 立即修复无法集成的构建
  4. 编写自动化的开发者测试
  5. 必须通过所有测试和审查
  6. 执行私有构建
  7. 避免迁出无法构建的代码

Q8: 本地提交代码应该经过哪些步骤?

本地提交可以采用经典的七步提交法


更多精彩内容,请关注微信公众号:软件乌托邦

Share

HashiCorp Vault

HashiCorp Vault是一款企业级私密信息管理工具。说起Vault,不得不提它的创造者HashiCorp公司。HashiCorp是一家专注于DevOps工具链的公司,其旗下明星级产品包括Vagrant、Packer、Terraform、Consul、Nomad等,再加上Vault,这些工具贯穿了持续交付的整个流程。


HashiCorp Vault在2016年四月进入了ThoughtWorks技术雷达,位于Tools分类,处于ACESS级别。在2017年3月份期技术雷达中,HashiCorp Vault已经处于TRIAL级别。

为什么要使用HashiCorp Vault?

在企业级应用开发过程中,团队每时每刻都需要管理各种各样的私密信息,从个人的登陆密码、到生产环境的SSH Key以及数据库登录信息、API认证信息等。通常的做法是将这些秘密信息保存在某个文件中,并且放置到git之类的源代码管理工具中。个人和应用可以通过拉取仓库来访问这些信息。但这种方式弊端很多,比如跨团队分享存在安全隐患、文件格式难以维护、私密信息难以回收等。

尤其是在微服务如此风靡的今天,如何让开发者添加私密信息、应用程序能轻松的获取私密信息、采用不同策略更新私密信息、适时回收私密信息等变得越来越关键。所以企业需要一套统一的接口来处理私密信息的方方面面,而HashiCorp Vault就是这样的一款工具。

HashiCorp Vault的特性

HashiCorp Vault作为集中化的私密信息管理工具,具有以下特点:

  • 存储私密信息。 不仅可以存放现有的私密信息,还可以动态生成用于管理第三方资源的私密信息。所有存放的数据都是加密的,任何动态生成的私密信息都有租期,并且到期会自动回收。
  • 滚动更新秘钥。用户可以随时更新存放的私密信息。Vault提供了加密即服务(encryption-as-a-service)的功能,可以随时将密钥滚动到新的密钥版本,同时保留对使用过去密钥版本加密的值进行解密的能力。 对于动态生成的秘密,可配置的最大租赁寿命确保密钥滚动易于实施。
  • 审计日志。 保管库存储所有经过身份验证的客户端交互的详细审核日志:身份验证,令牌创建,私密信息访问,私密信息撤销等。 可以将审核日志发送到多个后端以确保冗余副本。

另外,HaishiCorp Vault提供了多种方式来管理私密信息。用户可以通过命令行、HTTP API等集成到应用中来获取私密信息。HashiCorp Vault也能与Ansible、Chef、Consul等DevOps工具链无缝结合使用。

HashiCorp 架构

HashiCorp对私密信息的管理进行了合理的抽象,通过优良的架构实现了很好的扩展性和高可用。

  • Storage backend: 存储后端,可以为内存、磁盘、AWS等地方。
  • Barrier:隔离受信区域和非授信区域,保证内部数据的安全性。
  • HTTP API:通过HTTP API向外暴露服务,Vault也提供了CLI,其是基于HTTP API实现的。

Vault提供了各种Backend来实现对各种私密信息的集成和管理。比如Authentication Backend提供鉴权,Secret Backend用于存储和生成私密信息等。

总结

HashiCorp Vault作为私密信息管理工具,比传统的1password等方式功能更强大,更适合企业级的应用场景。在安全问题越来越严峻的今天,值得尝试HashiCorp Vault。


更多精彩洞见,请关注微信公众号:思特沃克

Share

解读基础设施即代码

现代软件开发对基础设施的管理提出了更苛刻的要求:产品要适应瞬息万变的市场,要求基础设施有更快的响应速度。持续交付和DevOps的推行要求产品团队对部署和运维要有更高的自主性。技术的快速进步和演化,也使得基础设施的配置不得不频繁变化。在这种快速变化的过程中,要求基础设施既要灵活,也要安全、可靠。

而传统的基础设施运维管理具有以下几个问题:

  • 被动响应。产品团队获取服务器资源采用的是申请制,中间存在若干审批过程,以及需要等待运维团队实施,响应不及时。
  • 自动化缺乏串联。虽然有一定的自动化,但不能做到无人值守,需要执行一些临时命令介入。由于环境释放和重建的成本高,因而倾向于不释放,导致资源利用率低。
  • 和产品团队脱节。很难根据需求随时动态增加环境。需要额外的文档来描述环境,可能更新不及时。

产品团队在实施持续交付的过程中,必须考虑将基础设施的维护纳入进来,作为支持产品运行的一部分。以下是产品团队的持续交付流水线全景图。

从上图可以看出,产品团队除了管理项目本身代码外,还要管理环境定义脚本。环境定义脚本可以由基础设施自动化工具执行,动态创建、销毁和更新产品运行所需的环境(包括服务器、负载均衡器、防火墙配置、第三方依赖等)。

如果实现了这一点,就实现了基础设施即代码的雏形。Kief在《Infarftruce As Code》一书中对基础设施即代码定义如下:

“基础设施即代码是一种使用新的技术来构建和管理动态基础设施的方式。它把基础设施、工具和服务以及对基础设施的管理本身作为一个软件系统,采纳软件工程实践以结构化的安全的方式来管理对系统的变更。”

基础设施即代码有四项关键原则:

  • 再生性。环境中的任何元素可以轻松复制。
  • 一致性。无论何时,创建的环境各个元素的配置是完全相同的。
  • 快速反馈。能够频繁、容易地进行变更,并快速知道变更是否正确。
  • 可见性。所有对环境的变更应该容易理解、可审计、受版本控制。

基础设施即代码的目标是:

标准化。 以代码来定义环境,实现开发环境、测试环境、生产环境的标准化。

自动化。 以自动化工具来驱动代码准备环境。包括创建环境、更新环境以及销毁环境。

可视化。 以监控来可视化环境信息。环境当前状态可视、环境变更历史可视、可追溯。

基础设施即代码实践会产生高成熟度的持续交付和DevOps。

在实施基础设施即代码时,要遵守以下实践:

使用DSL描述环境

Ansible、Chef、SaltStack、Terraform等基础设施自动化工具都有各自的描述性语言来实现对基础设施的定义。使用DSL更容易通过描述性的语言定义基础设施,也有助于代码重用。团队成员能建立起共同理解,从而维护脚本。

以下是Ansible的一个playbook示例。

---
- hosts: local
  tasks:
   - name: Install Nginx
     apt: pkg=nginx state=installed update_cache=true
     notify:
      - Start Nginx

  handlers:
   - name: Start Nginx
     service: name=nginx state=started

自测试系统

在编写环境代码的配置时,也要编写对环境的测试。确保所有服务器都进行了正确的配置,遵守了所有的安全规则,也对网络连通性等进行了验证。我们一般提倡将测试代码和配置代码放在一起维护。这样配置代码更新时,能保证测试代码也被及时更新。

一些典型的基础设施自动化测试工具有ServerSpec、Testinfra等。以下是一个ServerSpec的示例。

    require 'spec_helper'

    describe package('httpd'), :if => os[:family] == 'redhat' do
      it { should be_installed }
    end

    describe package('apache2'), :if => os[:family] == 'ubuntu' do
      it { should be_installed }
    end

    describe service('httpd'), :if => os[:family] == 'redhat' do
      it { should be_enabled }
      it { should be_running }
    end

    describe service('apache2'), :if => os[:family] == 'ubuntu' do
      it { should be_enabled }
      it { should be_running }
    end

    describe service('org.apache.httpd'), :if => os[:family] == 'darwin' do
      it { should be_enabled }
      it { should be_running }
    end

    describe port(80) do
      it { should be_listening }
    end

一切进行版本化

一旦采用了环境定义脚本实现对环境的控制后,需要将环境定义脚本纳入到版本管理中。并且之后所有的环境变更都应该先修改环境定义脚本,由环境定义脚本触发对环境的变更。登录到服务器执行一些临时性命令是被坚决禁止的。因为这极有可能会破坏环境的一致性。重建服务器时,也不能保证能应用所有需要的变更。

下图是基础设施即代码的一个典型使用场景。

除此之外,如果想要在生产环境中创建可伸缩性的服务,也需要借助“基础设施即代码”这一实践。在高峰时期,系统可以根据定义的环境自动创建并加入新的节点来实现动态扩容,并在低峰时将其销毁。当监控发现某节点失败,系统可以根据定义的环境自动创建新的节点来替换失败节点,实现自动灾难恢复。

最后是我们在某团队实施基础设施即代码的案例解析。这张图是某团队的基础设施架构图。

该团队使用AWS作为基础设施平台。我们选用ansible作为基础设施自动化工具,并结合AWS提供的cloudformation服务实现快速创建和销毁资源。所有网元都有清晰的角色划分,配套对应的配置脚本。从网络配置到网元配置以及应用配置都实现了全自动化。所有的配置脚本都和源代码一起托管在GitHub。团队所有成员都可以查看并修改。


更多精彩洞见,请关注微信公众号:思特沃克

Share

阿里巴巴Java开发手册评述

注:本文基于阿里巴巴技术手册的1.0.2版本编写

2016年底,阿里巴巴公开了其在内部使用的Java编程规范。随后进行了几次版本修订,笔者当时看到的版本为v1.0.2版。下载地址可以在其官方社区——云栖社区找到。

笔者作为一名有数年工作经验的Java程序员,仔细研读了这份手册,觉得是一份不可多得的好材料。正如阿里巴巴在发布时所说,“阿里巴巴集团推出的《阿里巴巴Java开发手册(正式版)》是公司近万名开发同学集体智慧的结晶,以开发视角为中心,详细列举了如何开发更加高效、更加容错、更加有协作性,力求知其然,更知其不然。结合正反例,让Java开发者能够提升协作效率、提高代码质量。” 同时,阿里巴巴也期望这套Java统一规范标准将有助于提高行业编码规范化水平,帮助行业人员提高开发质量和效率、大大降低代码维护成本。

(图片来自:http://t.cn/R63jrWi)

其实早在多年前,Google就已经把公司内部采用的所有语言的编码规范(其称为Style Guide)都开源在Github上。这份清单中包括了C++Objective-CJavaPythonRShellHTML/CSSJavaScriptAngularJSCommon LispVimscript等语言的编程规范。并且Google还发布了一个用于检查样式合规性的工具cpplint以及在Emacs中使用Google编程样式的配置文件google-c-style.el。看来Google中Emacs粉比Vim粉要强势的多。

Google为什么要发布这样的Style Guide呢?因为它认为几乎所有的开源项目都需要有一组约定来规范如何编写代码。如果项目中的代码都能保持一致的风格,那么即使代码再多也会很容易的被人理解。

Google的这份编程规范包含了很多方面,从”对变量使用camelCase命名法”到”绝不要使用全局变量”到”绝不允许例外“等。其Java编程规范包含7大部分,分别为介绍、源文件基本要求、源文件结构、格式化、命名、编程实践和Javadoc。每一部分又细分为很多子条目。如果采取条规范的原因不是很容易理解,都会配有相应的示例或者引用文章。

由于Google的这份编程规范目前只有英文版本,所以在中国的程序员中只有少部分人知道它的存在。并且只有更少的团队在真正的应用它,其中就包括我的团队。我们团队根据Google的Java style guide也演化出了自己的团队版本,放置在团队共享wiki上供大家随时查阅。我们根据自身的项目特点丰富了”编程实践”里的内容,并且新加入一个章节来描述编写Java代码的一些原则,比如简洁代码、组合优于继承、stream优于for循环等。

我想阿里巴巴发布的Java开发手册之所以叫做”开发手册”,而不是像Google那样叫做“Style Guide(样式风格)”,是因为它不仅仅局限于style guide这一方面,而是以Java开发者为中心视角,划分为编程规约、异常日志规约、MYSQL规约、工程规约、安全规约五大块,再根据内容特征,细分成若干二级子目录。根据约束力强弱和故障敏感性,规约依次分为强制、推荐、参考三大类。

该开发手册中的每一条都值得了解。限于篇幅原因,这里只列出”编程规约“中有感受的几条来评述一下。

15. 【参考】各层命名规约:

A) Service/DAO 层方法命名规约

1) 获取单个对象的方法用 get 做前缀。

2) 获取多个对象的方法用 list 做前缀。

3) 获取统计值的方法用 count 做前缀。

4) 插入的方法用 save(推荐)或 insert 做前缀。

5) 删除的方法用 remove(推荐)或 delete 做前缀。

6) 修改的方法用 update 做前缀。

B) 领域模型命名规约

1) 数据对象:xxxDO,xxx 即为数据表名。

2) 数据传输对象:xxxDTO,xxx 为业务领域相关的名称。

3) 展示对象:xxxVO,xxx 一般为网页名称。

4) POJO 是 DO/DTO/BO/VO 的统称,禁止命名成 xxxPOJO。

命名规约的第15条描述了在Service/DAO层对于资源的操作的命名规范。这一条的参考价值极大,因为我所有待过的团队对于这一点都没有明显的约束,每个团队都有五花八门的实现。如果能遵守这一点,那么我们在操作资源时就会减少一些困扰。

2. 【强制】long 或者 Long 初始赋值时,必须使用大写的 L,不能是小写的 l,小写容易跟数字1混淆,造成误解。

说明:Long a = 2l; 写的是数字的 21,还是 Long 型的 2?

这是常量定义的第2条。从这一点可以看出阿里巴巴对代码可读性的细节扣的很严格。我也很赞同这一点。代码只需编写一次,而会被查看无数次,所以要力争在第一次编写的时候尽可能少的引入歧义。

1. 【强制】大括号的使用约定。如果是大括号内为空,则简洁地写成{}即可,不需要换行;如果是非空代码块则:

1) 左大括号前不换行。

2) 左大括号后换行。

3) 右大括号前换行。

4) 右大括号后还有 else 等代码则不换行;表示终止右大括号后必须换行。

格式规约的第1条终于终结了括号之争。这一条需要强制遵守,那么左大括号换行一派则被彻底排除在阿里巴巴之外。有人说不推荐左大括号换行,可以减少行数,增加单个屏幕可以显示的代码行数。而有的人反驳说现在屏幕已经足够大,不换行则破坏了对称之美。其实对于我来说两种格式都有各自的好处,我都可以接受,只要团队能够坚持使用其中之一即可。

5. 【强制】缩进采用 4 个空格,禁止使用 tab 字符。

说明:如果使用 tab 缩进,必须设置 1 个 tab 为 4 个空格。IDEA 设置 tab 为 4 个空格时,请勿勾选 Use tab character;而在 eclipse 中,必须勾选 insert spaces for tabs。

正例: (涉及 1-5 点)

public static void main(String[] args) {
    // 缩进 4 个空格
    String say = "hello";
    // 运算符的左右必须有一个空格
    int flag = 0;
    // 关键词 if 与括号之间必须有一个空格,括号内的 f 与左括号,0 与右括号不需要空格
    if (flag == 0) {
        System.out.println(say);
    }
    // 左大括号前加空格且不换行;左大括号后换行
    if (flag == 1) {
        System.out.println("world");
        // 右大括号前换行,右大括号后有 else,不用换行
    } else {
        System.out.println("ok");
        // 在右大括号后直接结束,则必须换行
    }
}

使用空格代替tab字符进行缩进已经成为了编程界的共识。其主要原因是不同的平台甚至不同的编辑器下tab字符的长短是不一样的。不过Google在其《java style guide》中规定缩进为2个空格,而阿里巴巴约定为4个空格。由于4个空格的缩进比2个空格的缩进长一倍,所以如果在代码嵌套过深的情况下可能会很快超过单行最多字符数(阿里巴巴规定为120个)的限制。不过这个问题可以从另一个方面进行思考,如果由于缩进的原因导致单行字符数超标,这很可能是代码设计上有坏味道而导致嵌套过深。所以最好从调整代码结构的方面下手。

6. 【强制】单行字符数限制不超过 120 个,超出需要换行,换行时遵循如下原则:

1) 第二行相对第一行缩进 4 个空格,从第三行开始,不再继续缩进,参考示例。

2) 运算符与下文一起换行。

3) 方法调用的点符号与下文一起换行。

4) 在多个参数超长,逗号后进行换行。

5) 在括号前不要换行,见反例。

正例:

    StringBuffer sb = new StringBuffer();
    //超过 120 个字符的情况下,换行缩进 4 个空格,并且方法前的点符号一起换行
    sb.append("zi").append("xin")...
        .append("huang")...
        .append("huang")...
        .append("huang");

反例:

StringBuffer sb = new StringBuffer();
//超过 120 个字符的情况下,不要在括号前换行
sb.append("zi").append("xin")...append
("huang");
//参数很多的方法调用可能超过 120 个字符,不要在逗号前换行
method(args1, args2, args3, ...
, argsX); 

关于换行,Google并没有给出明确的要求,而阿里巴巴则给出了强制性的要求。Google特别提示可以通过一些重构手法来减少单行字符长度从而避免换行,这一点我颇为认同。关于参数,很多方法调用超过120个字符需要换行,这暴露除了过长参数列的代码坏味道,解决方式之一就是使用重构手法的Replace Parameter With Method的方式把一次方法调用化为多次方法调用,或者使用Introduce Parameter Object手法创造出参数对象并进行传递。

17. 【推荐】循环体内,字符串的联接方式,使用 StringBuilder 的 append 方法进行扩展。 反例:

    String str = "start";
    for (int i = 0; i < 100; i++) {
        str = str + "hello";
    }

说明:反编译出的字节码文件显示每次循环都会 new 出一个 StringBuilder 对象,然后进行append 操作,最后通过 toString 方法返回 String 对象,造成内存资源浪费。

这是《Effective Java》以及其他文章中经常提及的优化方式,而且面试初级Java工程师时几乎是一个必考点。其实不仅是在循环体内,所有需要进行多次字符串拼接的地方都应该使用StringBuilder对象。

20. 【推荐】类成员与方法访问控制从严:

1) 如果不允许外部直接通过 new 来创建对象,那么构造方法必须是 private。

2) 工具类不允许有 public 或 default 构造方法。

3) 类非 static 成员变量并且与子类共享,必须是 protected。

4) 类非 static 成员变量并且仅在本类使用,必须是 private。

5) 类 static 成员变量如果仅在本类使用,必须是 private。

6) 若是 static 成员变量,必须考虑是否为 final。

7) 类成员方法只供类内部调用,必须是 private。

8) 类成员方法只对继承类公开,那么限制为 protected。

说明:要严控类、方法、参数、变量的访问范围。过宽泛的访问范围不利于模块解耦。思 考:如果是一个 private 的方法,想删除就删除,可是一个 public 的 Service 方法,或者一个 public 的成员变量,删除一下,不得手心冒点汗吗?变量像自己的小孩,尽量在自己的视线内,变量作用域太大,会无限制的到处跑,那么你会担心的。

这其实就是经典的原则‘Principle of least privilege’ 的体现。我们必须遵循这一原则,但不知为何阿里巴巴将其级别列为“推荐”。

7. 【参考】方法中需要进行参数校验的场景:

1) 调用频次低的方法。

2) 执行时间开销很大的方法,参数校验时间几乎可以忽略不计,但如果因为参数错误导致 中间执行回退,或者错误,那得不偿失。

3) 需要极高稳定性和可用性的方法。

4) 对外提供的开放接口,不管是 RPC/API/HTTP 接口。

5) 敏感权限入口。

8. 【参考】方法中不需要参数校验的场景:

1) 极有可能被循环调用的方法,不建议对参数进行校验。但在方法说明里必须注明外部参 数检查。

2) 底层的方法调用频度都比较高,一般不校验。毕竟是像纯净水过滤的最后一道,参数错 误不太可能到底层才会暴露问题。一般 DAO 层与 Service 层都在同一个应用中,部署在同一台服务器中,所以 DAO 的参数校验,可以省略。

3) 被声明成 private 只会被自己代码所调用的方法,如果能够确定调用方法的代码传入参数已经做过检查或者肯定不会有问题,此时可以不校验参数。

编写代码时,对参数进行校验是不可避免的。详细说又扯到“防御式编程”和“契约式编程”的话题上。这两项之所以列为参考,并没有强迫大家遵守。

6. 【推荐】与其“半吊子”英文来注释,不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。

反例:“TCP 连接超时”解释成“传输控制协议连接超时”,理解反而费脑筋。

看到这一条我已经笑出来了。这一条说的很好,注释是用来阐述问题的,如果看了注释还一头雾水,那么这样的注释不要也罢。使用中文没什么可丢人的,解决问题才是王道。

7. 【推荐】代码修改的同时,注释也要进行相应的修改,尤其是参数、返回值、异常、核心逻辑等的修改。

说明:代码与注释更新不同步,就像路网与导航软件更新不同步一样,如果导航软件严重滞后, 就失去了导航的意义。

阿里巴巴对该条的说明非常到位。其实我们团队在编写代码时默认是没有任何注释的,因为我们追求的是self-explanatory methods。即代码本身已经就能说明它的用途。只有在很少的情况下需要添加注释。


编程规约的第九部分都是很好的tips,值得去了解和学习。

除了编程规约之外,日志规约、MySQL规约、工程规约和安全规约也都有极高的参考价值,这也是比Google的Java Style Guide出色的地方。这里就不再评述了。


阿里巴巴公布这个Java开发手册绝对是值得赞赏的事情。最后我也想给其提几点建议:

  1. 建议使用公开wiki的方式发布该手册,而不是采用pdf的方式。因为如果像google那样是公开wiki方式的话,可以方便大家参与修正和改进,并且可以看到版本历史。
  2. 该手册并没有明确的版权许可,只是在页脚处加入了“禁止用于商业用途,违者必究”的字样。Google的style guide的版权为CC-By 3.0 License,建议阿里巴巴能够指明其版权。
  3. 手册中的部分示例代码并没有遵守其列出的编程规约,有点打脸之嫌。比如以下示例代码:
     Iterator<String> it = a.iterator();
     while(it.hasNext()){
         String temp = it.next();
         if(删除元素的条件){
             it.remove();
         }
     }
    

    其while和if关键字与小括号之间并没有空格,违反了该手册中3. 【强制】if/for/while/switch/do 等保留字与左右括号之间都必须加空格。这一规则。

  4. 集合处理中可以多推荐一些Java8的集合操作方法。
  5. 有些名词没有过多解释,比如很多人可能都不知道什么叫一方库、二方库。
  6. 希望除了这份开发手册以外,阿里巴巴也可以推出对应的checkstyle配置文件以及Intellij、Eclipse的配置文件。毕竟格式化这些事都可以交由IDE来解决,通过在构建时使用checkstyle插件也可以防止不合规的代码迁入到仓库,从源头上保证代码样式的一致性。

最后,希望这份Java开发手册可以持续改进,吸纳百家之长,成为每个入门程序员必看的手册。


更多精彩洞见,请关注微信公众号:思特沃克

Share