最小化的安全bash脚本模板

August 22, 2022

原文：https://betterdev.blog/minimal-safe-bash-script-template
仅意译，文章推荐使用此仓库：https://github.com/ralish/bash-script-template
Bash 脚本参考：https://wangdoc.com/bash/

Bash 脚本几乎是每个人都迟早该会一点的。大抵没人会说自己喜欢写 Bash 脚本，可能正因此大部分人都没怎么关注它。

本文不是为了精通 Bash 脚本，而是展示一个最小化的模板，可以让脚本更安全。

为何使用 Bash 脚本？

与 “就像骑自行车一样” 相反的是： “通过 Bash 编程”。 (比喻：像骑自行车一样，学过就忘不了)
这句话的意思是，无论你做了多少次，你每次还是要重新学习。

— Jake Wharton (@JakeWharton) December 2, 2020

不过 Bash 脚本就像其它广受喜爱的编程语言一样，比如说 JavaScript，不会轻易消失。
尽管我们希望 Bash 脚本不会变成所有事物的主要语言，但它总是无处不在。

Bash 脚本继承了 shell 的宝座，在 Linux 系统和 Docker 镜像中随处可见，这也是大多数后端运行的环境。所以如果你需要为服务器程序的启动、CI/CD 步骤或集成测试的运行编写脚本，Bash 总在这里。

要把几个命令连在一起，把输出从一个传到另一个，或者是运行一些可执行程序，Bash 是最简单和最本源的解决方案。
虽然用其他语言编写更强大、更复杂的脚本是很好的，但你不能指望到处都有 Python、Ruby、fish 或其它你觉得好的解释器。
而且在你将其它的解释器添加到某些生产服务器、Docker 镜像或 CI 环境之前，你可能要三思而后行。

Bash 尚不完美，语法繁杂，很难做错误处理。编写的过程中容易踩坑，但我们必须解决它。

Bash 脚本模板

直接上代码

bash

#!/usr/bin/env bash

set -Eeuo pipefail
trap cleanup SIGINT SIGTERM ERR EXIT

script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" &>/dev/null && pwd -P)

usage() {
  cat << EOF # remove the space between << and EOF, this is due to web plugin issue
Usage: $(basename "${BASH_SOURCE[0]}") [-h] [-v] [-f] -p param_value arg1 [arg2...]

Script description here.

Available options:

-h, --help      Print this help and exit
-v, --verbose   Print script debug info
-f, --flag      Some flag description
-p, --param     Some param description
EOF
  exit
}

cleanup() {
  trap - SIGINT SIGTERM ERR EXIT
  # script cleanup here
}

setup_colors() {
  if [[ -t 2 ]] && [[ -z "${NO_COLOR-}" ]] && [[ "${TERM-}" != "dumb" ]]; then
    NOFORMAT='\033[0m' RED='\033[0;31m' GREEN='\033[0;32m' ORANGE='\033[0;33m' BLUE='\033[0;34m' PURPLE='\033[0;35m' CYAN='\033[0;36m' YELLOW='\033[1;33m'
  else
    NOFORMAT='' RED='' GREEN='' ORANGE='' BLUE='' PURPLE='' CYAN='' YELLOW=''
  fi
}

msg() {
  echo >&2 -e "${1-}"
}

die() {
  local msg=$1
  local code=${2-1} # default exit status 1
  msg "$msg"
  exit "$code"
}

parse_params() {
  # default values of variables set from params
  flag=0
  param=''

  while :; do
    case "${1-}" in
    -h | --help) usage ;;
    -v | --verbose) set -x ;;
    --no-color) NO_COLOR=1 ;;
    -f | --flag) flag=1 ;; # example flag
    -p | --param) # example named parameter
      param="${2-}"
      shift
      ;;
    -?*) die "Unknown option: $1" ;;
    *) break ;;
    esac
    shift
  done

  args=("$@")

  # check required params and arguments
  [[ -z "${param-}" ]] && die "Missing required parameter: param"
  [[ ${#args[@]} -eq 0 ]] && die "Missing script arguments"

  return 0
}

parse_params "$@"
setup_colors

# script logic here

msg "${RED}Read parameters:${NOFORMAT}"
msg "- flag: ${flag}"
msg "- param: ${param}"
msg "- arguments: ${args[*]-}"

我的想法是不要让代码太长了，但又能为具体的脚本提供基础。
实现起来不容易，因为 Bash 是没有依赖管理的。

一个想法是用一个基础的脚本去启动一个实现实际逻辑的脚本，不过这样就要两个脚本，不算是最小化。
所以我们尽量减小模板代码，保持精简。

下面具体分析代码。

shebang 行，选择 bash

bash

#!/usr/bin/env bash

选 /usr/bin/env 而不是直接 /bin/bash

失败时立刻停止运行

bash

set -Eeuo pipefail

set 命令改变了脚本的运行模式。
比如说，通常 Bash 就算命令运行失败了（非零返回），都会直接继续执行下一行。
考虑如下脚本：

bash

#!/usr/bin/env bash
cp important_file ./backups/
rm important_file

上面的脚本中，如果 backups 文件夹不存在，控制台会输出报错信息，但是下一行移除文件夹的代码还是会运行。

关于set -Eeuo pipefail选项的具体内容，参见这篇文章

尽管你应该知道，有一些论点反对设置这些选项。

获取运行目录

bash

script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" &>/dev/null && pwd -P)

这行代码尽可能地获取当前运行目录~~，然后cd进这个目录，为何？~~

一般来说我们的脚本在相对与脚本文件所在目录下工作（复制文件、执行命令），也就是说脚本所在目录即为当前工作目录。
这也是我们在脚本所在目录执行脚本将得到的结果。

但是如果我们在命令行通过以下方式执行脚本：

bash

/opt/ci/project/script.sh

则脚本的工作目录不是脚本所在目录，而是完全未知的一个任意工作目录。
虽然说可以通过预先进入脚本所在目录，然后再运行脚本来解决此问题：

bash

cd /opt/ci/project && ./script.sh

但是如果我们能在脚本内部解决此问题就更好了。
所以如果我们的脚本需要在相对于脚本所在路径读取文件或者执行命令，可以通过以下方式：

bash

cat "$script_dir/my_file"

同时，该脚本不会更改工作目录。如果脚本是在其他目录执行的，并且用户提供了某个文件的相对路径，我们仍然能够读取它。

执行清理工作

（译注：关于 trap 命令，参见：https://tldr.ostera.io/trap，下面 trap 将使程序接收指定信号时执行 cleanup 函数）

bash

trap cleanup SIGINT SIGTERM ERR EXIT

cleanup() {
  trap - SIGINT SIGTERM ERR EXIT
  # script cleanup here
}

可以把 trap 视作脚本的 finally 块。在脚本结束时——正常情况下，由错误或外部信号引起——将执行 cleanup() 函数。例如，可以在这里删除脚本创建的所有临时文件。

只需注意 cleanup() 函数不仅可以在最后调用，还可以让脚本完成任何部分的工作。不一定所有你试图清理的资源都会存在。

显示帮助

bash

usage() {
  cat << EOF # remove the space between << and EOF, this is due to web plugin issue
Usage: $(basename "${BASH_SOURCE[0]}") [-h] [-v] [-f] -p param_value arg1 [arg2...]

Script description here.

...
EOF
  exit
}

让 usage() 相对靠近脚本的顶部，有两个作用:

向那些不了解所有选项和不想翻阅整个脚本的人展示帮助信息
给修改此脚本的人作为一个简洁的文档（比如说，两个星期后你可能自己忘记写了这个脚本）

我不主张在这里给每一个函数都写文档。但是一个简短的、好的脚本使用方法（usage message）的文档是最起码的要求。

输出彩色文本

bash

setup_colors() {
  if [[ -t 2 ]] && [[ -z "${NO_COLOR-}" ]] && [[ "${TERM-}" != "dumb" ]]; then
    NOFORMAT='\033[0m' RED='\033[0;31m' GREEN='\033[0;32m' ORANGE='\033[0;33m' BLUE='\033[0;34m' PURPLE='\033[0;35m' CYAN='\033[0;36m' YELLOW='\033[1;33m'
  else
    NOFORMAT='' RED='' GREEN='' ORANGE='' BLUE='' PURPLE='' CYAN='' YELLOW=''
  fi
}

msg() {
  echo >&2 -e "${1-}"
}

首先，如果你不需要输出彩色文本，删除 setup_colors() 函数即可。
我保留它是因为我知道如果我不需要每次都去查颜色的代码，我将更频繁地使用彩色文本。

其次，指定的颜色仅在 msg() 函数内有效，其它的 echo 命令是无效的。

msg() 意在用于打印所有非脚本输出。这包括所有日志（logs）和消息（messages），而不仅仅是错误（errors）。

引用自 12 Factor CLI Apps article：

简而言之：stdout 用来输出（output），stderr 用来打印消息（messaging）

Jeff Dickey, who knows a little about building CLI apps

所以说在大多数情况下你不应该在 stdout 中使用彩色文本。

通过 msg() 函数打印的消息将发送至 stderr，并支持特殊序列，如颜色。如果 stderr 输出不是一个交互式终端或者传递了一个标准参数，则颜色将被禁用。

用法：

bash

msg "This is a ${RED}very important${NOFORMAT} message, but not a script output value!"

要检查它在当 stderr 不是交互式终端时的行为，可以像上面这样在脚本中添加一行（使用 msg 函数的语句），
然后执行它，将 stderr 重定向到 stdout，并通过管道将其发送到 cat。
管道操作使得输出不再直接发送到终端，而是发送到下一个命令，因此现在颜色应该会被禁用。

$ ./test.sh 2>&1 | cat
This is a very important message, but not a script output value!

解析参数

bash

parse_params() {
  # default values of variables set from params
  flag=0
  param=''

  while :; do
    case "${1-}" in
    -h | --help) usage ;;
    -v | --verbose) set -x ;;
    --no-color) NO_COLOR=1 ;;
    -f | --flag) flag=1 ;; # example flag
    -p | --param) # example named parameter
      param="${2-}"
      shift
      ;;
    -?*) die "Unknown option: $1" ;;
    *) break ;;
    esac
    shift
  done

  args=("$@")

  # check required params and arguments
  [[ -z "${param-}" ]] && die "Missing required parameter: param"
  [[ ${#args[@]} -eq 0 ]] && die "Missing script arguments"

  return 0
}

如果脚本需要传入参数的话，我会一般这样做，就算脚本仅在这一处使用。复制和重用它很容易，这也是迟早要做的。
此外，即使有些东西需要硬编码，通常在比 Bash 脚本更高的层次上也有更好的地方。

命令行参数主要有三种类型：标志（flags）、命名参数（named parameters）和位置参数（positional arguments）。parse_params() 函数支持提到的所有参数。

这里唯一没有处理的一种常见参数模式是串联多个单字母标志。为了能够传递两个标志作为-ab，而不是-a -b，需要一些额外的代码。

while 循环是一种手动解析参数的方式。在其他语言中，您应该使用内置的解析器或其它可用库，但是，这是 Bash。

模板中有一个示例标志 (-f) 和命名参数 (-p)。只需更改或复制它们来添加其他参数。之后不要忘记更新 usage() 函数。

这里重要的一点是，当你用谷歌搜索出来的第一个结果来解析 Bash 参数，通常会忽略的一点是，在未知选项上抛出一个错误。
脚本接收了一个未知选项就意味着用户想做一些脚本无法实现的事情。所以用户期望和脚本行为可能会大不相同。
最好在坏事发生之前就完全阻止程序的执行。

在 Bash 中，解析参数有两种方法，即 getopt 和 getopts。赞成和反对使用它们的意见都有。
我认为这些工具并不是最好的，因为默认情况下，macOS 上的 getopt 行为完全不同，而且 getopts 不支持长参数(例如 --help)。

使用模板

复制粘贴即可，就像抄网上其它代码一样。

嗯，实际上，这是个诚恳的建议。毕竟 Bash 没有像 npm 一样的包管理器可以执行 install。

复制之后只需改变四处：

usage() 处文本改为脚本说明
cleanup() 中的内容
parse_params() 中的参数。保留 --help 和 --no-color，替换掉实例参数：-f 和 -p
脚本的实际逻辑

可移植性

我在 MacOS（默认 archaic Bash 3.2）和几个 docker 镜像：Debian, Ubuntu, CentOS, Amazon Linux, Fedora 下测试此模板。能够正常工作。

当然，它不能在缺少 Bash 的环境中工作，比如 Alpine Linux。Alpine 作为一个极简主义系统，使用了轻量级的 shell ash (Almquist shell)。

你可能会问，使用几乎在任何地方都适用的 Bourne Shell 兼容脚本不是更好吗？至少对我来说，答案是否定的。Bash 更安全、更强大(但仍然不容易使用)，所以我可以接受对一些我很少处理的 Linux 发行版缺乏支持。

扩展阅读

在 Bash 或其它更好的编程语言中创建 CLI 脚本时，有一些通用规则。这些资源将指导你如何让你的小型脚本和大型 CLI 应用程序变得可靠:

结束语

我不是第一个也不是最后一个创建 Bash 脚本模板的人。一个很好的选择是这个项目，虽然对我的日常需求来说有点太大了。毕竟，我试图让 Bash 脚本尽可能的小(和少)。

编写 Bash 脚本时，使用支持 ShellCheck linter 的 IDE，比如 JetBrains IDEs。它会阻止你做一堆事与愿违的事情。

我的 Bash 脚本模板也可以通过 GitHub Gist 获得(在 MIT 许可下):

script-template.sh

如果你发现模板有任何问题，或者你认为缺少了什么重要的东西，请在评论中告诉我。

评论见原文评论区：https://betterdev.blog/minimal-safe-bash-script-template

←Back to home