脚本工程化与规范

#!/usr/bin/env bash
# ------------------------------------------------------------------
# deploy.sh - 发布脚本
# 用法: ./deploy.sh [-e env] <app>
# 作者: devops@example.com
# ------------------------------------------------------------------

set -euo pipefail

# ---------- 配置区 ----------
readonly APP_DIR="/opt/apps"
readonly LOG_FILE="/var/log/deploy.log"

# ---------- 函数区 ----------
log() { printf '%s %s\n' "$(date '+%F %T')" "$*"; }
die() { log "[ERROR] $*" >&2; exit 1; }

# ---------- 主逻辑 ----------
main() {
  local env="${1:?用法: $0 <env>}"
  log "开始部署 $env"
  # ...
}
main "$@"

# 三个开关逐项拆解
set -e            # 任何命令失败立即退出（rc 非 0）
set -u            # 引用未定义变量立即报错
set -o pipefail   # 管道中任一段失败，整体失败

# 一行全开（推荐写法）
set -euo pipefail

# 需要"容忍失败"的场合显式豁免
rm -rf "$tmp" || true
grep -q "ok" file || echo "未找到 ok"

# 判断类命令不能因 -e 退出
if grep -q "x" file; then
  echo "有 x"
fi

# 管道里明确不检查失败的段
set +o pipefail
echo "end" | cat
set -o pipefail

# lib/log.sh - 日志函数库
#!/usr/bin/env bash
log_info()  { printf '[INFO ] %s\n' "$*"; }
log_warn()  { printf '[WARN ] %s\n' "$*" >&2; }
log_error() { printf '[ERROR] %s\n' "$*" >&2; }

# 主脚本引用
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# shellcheck source=lib/log.sh
source "$SCRIPT_DIR/lib/log.sh"

log_info "加载配置"

# 纯函数 + 返回值传递
parse_version() {
  local input="$1"
  [[ "$input" =~ ([0-9]+)\.([0-9]+) ]] || return 1
  echo "${BASH_REMATCH[1]} ${BASH_REMATCH[2]}"
}
read -r major minor < <(parse_version "v1.24" || echo "0 0")
echo "major=$major minor=$minor"

# 安装（macOS）
brew install shellcheck
# 运行
shellcheck myscript.sh

# 只看错误级别
shellcheck -S error myscript.sh
# 忽略某条规则
shellcheck -e SC2086 myscript.sh
# 指定 shell 方言
shellcheck -s bash myscript.sh

# 常见修复示例
# 坏：cd /tmp && rm -f x
cd /tmp || die "无法进入 /tmp"     # SC2164
# 坏：local x=$(cmd)
local x
x=$(cmd)                            # SC2155

# 统一日志函数（带等级与时间）
LOG_LEVEL=${LOG_LEVEL:-INFO}
log() {
  local level="$1"; shift
  printf '[%s] %s %s\n' "$level" "$(date '+%F %T')" "$*"
}
log_info()  { log INFO  "$*"; }
log_warn()  { log WARN  "$*" >&2; }
log_error() { log ERROR "$*" >&2; }

# 数据走 stdout，日志走 stderr
log_info "查询开始"
result=$(db_query)
printf '%s\n' "$result"          # stdout 只有结果
log_info "查询结束"

# 重定向到文件（含 stderr）
exec >> /var/log/app.log 2>&1

# 用 bats 写单元测试
# test/parse_test.bats
#!/usr/bin/env bats
load '../lib/parse.sh'

@test "parse_version 返回主次版本" {
  result="$(parse_version 'v1.24')"
  [ "$result" = "1 24" ]
}

@test "parse_version 非法输入返回非零" {
  run parse_version "abc"
  [ "$status" -ne 0 ]
}

# .github/workflows/shell.yml
name: shell-check
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: shellcheck -S error lib/*.sh *.sh
      - run: |
          for f in tests/*.bats; do bats "$f"; done

# 本地快速自查
bash -n deploy.sh && echo "语法 OK"
shellcheck -S error deploy.sh

# 脚本自带版本
readonly VERSION="1.4.0"
[[ "$1" == "--version" ]] && { echo "deploy.sh $VERSION"; exit 0; }
[[ "$1" == "--help" ]] && { usage; exit 0; }

# 发布流程要点
# 1. tag 对应版本：git tag v1.4.0
# 2. CHANGELOG 记录破坏性变更
# 3. 配置文件与代码分离，不放仓库里