Shell脚本精读 · S14-01 | 风格约定：命名、引用、函数与错误处理

模块：S14 工程化与综合实战
篇号：S14-01 / 42
预计阅读：45 分钟
主线：Bash

本篇目标

把前面各模块的零散习惯收成一套工程化风格约定：命名、引用、函数布局、错误与退出码。能按约定写出可读、可 review 的 Bash 脚本，并在读他人代码时快速识别main/die/usage、"$@"、local等模式。可移植写法见S13；本篇侧重团队内 Bash 脚本的一致风格。

30 秒速览

• 文件：#!/usr/bin/env bash+set -euo pipefail；业务放main "$@"。
• 命名：常量/环境UPPER_SNAKE；局部变量lower_snake；函数verb_noun或lower_snake。
• 引用：变量、路径、"$@"一律双引号；数组用"${arr[@]}"（S02-01）。
• 函数：上部定义工具函数；usage→exit 2、die→exit 1；函数内临时量用local（S08-02）。
• 错误：预期失败用return；致命错误die；关键步骤cmd || die或依赖-e。
• 日志：用户可见信息stdout；错误与诊断stderr。

正文

1. 风格约定解决什么问题

语法正确 ≠ 好维护。多人协作或半年后自己重读时，差异来自：

风格约定不是语法课，而是读写的共同语言——与S13 可移植性并列：S13 管「能不能在 dash 跑」，S14 管「Bash 项目里怎么写才一致」。

2. 脚本文件与头部

#!/usr/bin/env bash# deploy.sh — 发布静态资源到目标目录（一行用途说明）set-euopipefail

文件名：小写 + 连字符或下划线，见名知意：backup-db.sh、lib/common.sh。避免test.sh、run.sh等泛名。

3. 命名约定

3.1 变量

readonlyDEFAULT_PORT=8080log_level=${LOG_LEVEL:-info}main(){localsrc_dir=$1localdest_dir=$2...}

• readonly：脚本级常量，防止误改。
• local：函数内变量（S08-02），避免污染全局命名空间。

3.2 函数

读脚本：见到require_*、ensure_*、validate_*多为前置检查；do_*、run_*多为业务步骤。

3.3 退出码（团队内约定）

与S04-01一致；不要用exit 255等易与信号混淆的值。

4. 引用约定

默认规则：凡变量展开、位置参数、含空格或通配符风险的字符串 →双引号。

# 推荐cp"$src""$dest"rm-f--"$maybe_dash_name"forfin"$@";doprocess"$f"done# 数组（S03-04）files=(a.log b.log)printf'%s\n'"${files[@]}"

刻意不加引号的少数情况：算术$(( ))、[[ ... ]]右侧模式、for i in 1 2 3等已知安全列表——写的时候加注释说明为何安全。

反模式（读脚本时标红）：

rm$file# 空变量 → rm 无参；多词 → 多文件ssh$host"cmd"# host 含空格即断

5. 函数与文件布局

推荐自上而下四段（与 S01-04、S08-01 骨架一致）：

#!/usr/bin/env bashset-euopipefail# --- 1. 常量 / 默认配置 ---readonlySCRIPT_NAME=${0##*/}# --- 2. 工具函数（无业务副作用或仅通用副作用）---log(){printf'[%s] %s\n'"$(date+%H:%M:%S)""$*">&2;}die(){printf'error: %s\n'"$*">&2;exit1;}usage(){printf'usage: %s [-v] <dir>\n'"$SCRIPT_NAME">&2;exit2;}require_cmd(){command-v"$1">/dev/null2>&1||die"command not found:$1"}# --- 3. 业务函数 ---deploy_dir(){localdir=$1[[-d"$dir"]]||die"not a directory:$dir"...}# --- 4. main 入口 ---main(){localverbose=0localtargetwhilegetopts':v'opt;docase$optinv)verbose=1;;*)usage;;esacdoneshift$((OPTIND-1))(($#==1))||usagetarget=$1require_cmdrsyncdeploy_dir"$target"}main"$@"

定义顺序：函数必须在调用前定义；main "$@"在文件末尾。

6. 错误处理约定

6.1 三层模型

6.2die与usage

die(){printf'error: %s\n'"$*">&2exit1}usage(){printf'usage: %s [-f] <file>\n'"${0##*/}">&2exit2}

• usage：参数解析失败、-h以外的非法选项 →exit 2。
• die：业务/环境错误 →exit 1（或团队统一的其他非 0 码）。

6.3return与exit

# 函数内：可恢复 / 可跳过is_stale(){[[-n"${1:-}"]]||return1...}# 函数内：致命（结束整个脚本）fatal_in_main_context(){die"cannot continue"# die 内部 exit}# 库函数被 source 时：慎用 exit（S08-03）lib_fn(){printf'bad\n'>&2return1# 让调用方决定}

6.4 与set -e协作

set-euopipefail# 显式忽略（要有理由）greppatternfile||true# 显式失败信息cp"$a""$b"||die"copy failed:$a->$b"# 函数里希望「失败但不退出脚本」process_one(){convert"$1"||return1}

读脚本：混用|| true、|| die、裸命令时，先确认是否开了-e（S01-04、S08-01 §9）。

7. 标准输出与标准错误

log(){printf'[info] %s\n'"$*">&2;}result_path=$(find_upward"$start")# find_upward 只 echo 路径到 stdout

反模式：echo "debug: ..."混在会进管道的命令之间，污染下游（S09-01）。

8. 注释写什么

# GNU date only; BSD use gdate (documented in README)expire=$(date-d'+7 days'+%F)

9. 与 S13 可移植性的关系

不要shebang 写sh却用本篇 Bash 风格——这是 S13-01 红旗。

10. 风格约定速查表

读脚本检查清单

• 第一行 shebang 与文内语法是否一致（Bash vs sh）
• 是否有set -euo pipefail（或团队等价物）
• 变量、"$@"是否普遍加双引号
• 是否有main "$@"或清晰的单一入口
• usage/die/log命名与退出码是否一致
• 函数内是否用local，有无全局污染
• 错误信息是否走stderr，数据是否走stdout
• || true是否都有理由（不是掩盖真 bug）

练习

判断题

1. 脚本内配置常量推荐readonly MAX_RETRIES=3形式。
2. "$@"在传递参数时通常优于$*。
3. usage函数应惯例以退出码 2 结束脚本。
4. 所有echo都应改为写到 stdout，包括错误提示。
5. 函数内的循环变量i应用local i声明（若函数可能被递归或重入）。

1. 对。
2. 对。
3. 对（团队可自定义，但 2 是常见约定）。
4. 错（错误与日志应stderr，如>&2）。
5. 对（良好习惯，避免泄漏到全局）。

改错题

指出下面片段中风格/健壮性问题（至少 4 处）：

#!/usr/bin/env bashset-emax=3deploy(){src=$1dest=$2cp$src$dest}if[$#-lt1];thenechousage:$0direxit0fideploy$1/var/www

示例答案（不唯一）：

1. 缺-u、-o pipefail（与专栏骨架不一致）。
2. max若不变可readonly MAX=3；函数内src/dest应local。
3. cp $src $dest应cp "$src" "$dest"。
4. 用法错误却exit 0，应exit 2且输出到stderr。
5. 无main "$@""结构，参数未引号传递deploy "$1" /var/www。
6. echo usage宜改为usage函数或printf 'usage: ...\n' "$0" >&2。

实操题

按本篇约定，为下面需求写头部 + 工具函数 + main 骨架（业务体可...）：

• 脚本名sync-site.sh
• 必须恰好 1 个参数（目标目录）
• 依赖rsync不存在则die
• 支持-ndry-run（传给rsync -n）

#!/usr/bin/env bash# sync-site.sh — 同步站点目录到目标路径set-euopipefailreadonlySCRIPT_NAME=${0##*/}die(){printf'error: %s\n'"$*">&2;exit1;}usage(){printf'usage: %s [-n] <dest-dir>\n'"$SCRIPT_NAME">&2;exit2;}require_cmd(){command-v"$1">/dev/null2>&1||die"command not found:$1"}main(){localdry_run=0localdestwhilegetopts':n'opt;docase$optinn)dry_run=1;;*)usage;;esacdoneshift$((OPTIND-1))(($#==1))||usagedest=$1require_cmdrsyncif((dry_run));thenrsync-an./site/"$dest/"elsersync-a./site/"$dest/"fi}main"$@"

下一篇预告

S14-02：《脚本模板：从 20 行工具到可维护项目》— 在风格约定之上，给出可复制目录结构与多文件协作模板。