Google Shell 脚本风格指南解析与实践

Google Shell 脚本风格指南解析与实践

styleguide 项目地址: https://gitcode.com/gh_mirrors/st/styleguide

前言：Shell脚本在现代开发中的定位

Shell脚本作为一种轻量级的自动化工具，在系统管理、持续集成和日常任务自动化中扮演着重要角色。Google的Shell脚本风格指南为我们提供了一套经过大规模实践验证的最佳实践方案，帮助开发者编写出更安全、更易维护的脚本程序。

一、Shell脚本的适用场景

1.1 选择合适的Shell解释器

在Google规范中，Bash是唯一被允许用于可执行脚本的Shell。主要原因包括：

• Bash在所有现代Linux系统中默认安装
• 提供了比传统sh更丰富的功能集
• 避免了不同Shell实现之间的兼容性问题

规范要求所有可执行脚本必须以#!/bin/bash开头，并设置最小的启动参数。例如：

#!/bin/bash
set -euo pipefail  # 启用严格模式

1.2 Shell脚本的适用边界

Shell脚本最适合的场景包括：

• 简单的工具链封装
• 轻量级系统管理任务
• 其他程序的启动/控制脚本

不适合使用Shell的情况：

• 需要复杂数据处理
• 性能敏感型任务
• 超过100行的逻辑复杂脚本
• 需要长期维护的核心业务逻辑

二、脚本文件组织规范

2.1 文件扩展名策略

• 可执行脚本：.sh扩展名或无扩展名
  • 有构建系统参与时使用.sh
  • 直接放入PATH的可执行文件建议无扩展名
• 库文件：必须使用.sh且不可执行

2.2 安全限制

严格禁止SUID/SGID权限的Shell脚本，因为：

1. Shell脚本存在注入风险
2. 环境变量可能被篡改
3. 依赖的外部命令可能被劫持

替代方案是使用sudo机制进行权限提升。

三、代码结构与注释规范

3.1 文件头注释

每个文件顶部必须包含功能描述：

#!/bin/bash
#
# Oracle数据库热备份工具
# 支持增量备份和全量备份模式

3.2 函数注释标准

任何非显而易见的函数都需要完整注释：

#######################################
# 清理备份目录中的过期文件
# 按照保留策略删除超过指定天数的备份
# Globals:
#   BACKUP_DIR - 备份根目录
#   RETENTION_DAYS - 保留天数
# Arguments:
#   $1 - 要清理的数据库SID
# Returns:
#   0表示成功，非0表示失败
#######################################
cleanup_backup() {
  ...
}

3.3 实现注释技巧

• 在复杂算法处添加解释
• 非常规处理需要说明原因
• 使用TODO标记待完善代码

# TODO(zhangsan): 需要处理GBK编码的异常情况

四、代码格式化准则

4.1 基础格式要求

• 缩进：2个空格，禁止制表符
• 行宽：不超过80字符
• 长字符串：使用heredoc或多行写法

# 多行字符串示例
long_message="这是一个非常长的提示信息，\
它被分成多行以提高可读性，\
同时保持逻辑完整性。"

4.2 控制结构格式

• ; then/; do与if/for同行
• else单独一行
• 结束标记(fi/done)与开始标记垂直对齐

for file in "${files[@]}"; do
  if [[ -f "${file}" ]]; then
    process_file "${file}"
  else
    warn "文件不存在: ${file}"
  fi
done

4.3 Case语句规范

• 每个模式缩进2空格
• 简单语句可与;;同行
• 复杂逻辑应分多行

case "${OS_TYPE}" in
  linux)
    install_linux_packages
    ;;
  darwin)
    install_mac_tools
    ;;
  *)
    die "不支持的OS类型: ${OS_TYPE}"
    ;;
esac

五、变量处理最佳实践

5.1 变量引用规范

• 始终使用${var}形式
• 特殊参数($1, $@等)可省略花括号
• 数字位置参数必须使用${10}形式

echo "用户: ${USER}, 目录: ${HOME}"
echo "第一个参数: $1"
echo "第十个参数: ${10}"

5.2 引号使用原则

• 必须加引号的情况：

  • 包含空格/特殊字符的字符串
  • 命令替换$(...)
  • 变量扩展${var}

• 可省略引号的情况：

  • 纯数字变量
  • 明确不需要分词的情况

# 正确示例
greet="Hello, World!"
count=42

六、高级特性使用建议

6.1 数组应用

使用数组安全处理参数列表：

flags=(
  "--verbose"
  "--output=/dev/null"
  "--user=${USER}"
)
run_command "${flags[@]}"

6.2 命令替换

优先使用$(...)而非反引号：

# 推荐
current_branch=$(git rev-parse --abbrev-ref HEAD)

# 不推荐
current_branch=`git rev-parse --abbrev-ref HEAD`

6.3 测试表达式

[[ ]]比[ ]更安全且功能更丰富：

if [[ -n "${VAR}" && -f "${FILE}" ]]; then
  ...
fi

七、命名与组织规范

7.1 命名约定

• 函数名：小写+下划线，动词开头
• 变量名：大写表示常量，小写表示普通变量
• 局部变量：必须声明为local

readonly MAX_RETRIES=3

process_data() {
  local temp_file
  temp_file="$(mktemp)"
  ...
}

7.2 代码组织

• 主函数命名为main
• 函数定义集中放在文件开头或结尾
• 相关功能分组组织

#!/bin/bash

# 函数定义
helper1() { ... }
helper2() { ... }

# 主逻辑
main() {
  helper1
  helper2
}

main "$@"

八、错误处理规范

8.1 错误输出

所有错误信息必须输出到STDERR：

err() {
  echo "[$(date)] ERROR: $*" >&2
}

err "配置文件不存在"

8.2 返回值检查

必须检查关键命令的返回值：

if ! do_critical_operation; then
  err "关键操作失败"
  exit 1
fi

结语：一致性优先原则

当遇到规范未明确覆盖的情况时，保持与现有代码风格一致是最重要的原则。良好的Shell脚本应该像文档一样易于阅读和理解，这也是Google制定这套风格指南的核心目标。

通过遵循这些经过大规模实践验证的规范，我们可以编写出更健壮、更易维护的Shell脚本，有效降低系统维护成本，提高团队协作效率。

styleguide 项目地址: https://gitcode.com/gh_mirrors/st/styleguide