シェルスクリプトの関数名の衝突を防ぐ設計｜プレフィックス命名とdeclare -Fで既存の外部コマンド上書きを避ける

この記事のポイント

・bash は「関数 → 組み込み → 外部コマンド」の順で名前を解決するため、関数名が既存名と同じだと外部コマンドが呼ばれなくなる
・declare -F で定義済みの全関数を一覧し、type -t で衝突リスクを事前に確認できる
・プロジェクト識別子をプレフィックスに使う命名規約（例: bk_log）が衝突を根本から防ぐ
・readonly -f で公開済みの関数をロックし、source 読み込み時の意図しない上書きをブロックできる

# bash の名前解決優先順位（上が高い）
# 1. エイリアス   (alias)
# 2. シェル関数   (function)  ← 自分で定義した関数
# 3. シェル組み込み (builtin) ← cd, echo, printf, read など
# 4. 外部コマンド  (PATH 上のファイル) ← /bin/ls, /usr/bin/date など

# 【事故例1】ls という名前で「常に -la を付けたい」と思って関数を定義
ls() {
    ls -la --color=auto "$@"   # ← ls が ls を呼ぶ無限再帰になる
}
# 実行すると bash がスタックオーバーフローで強制終了する

# 【事故例2】ライブラリスクリプト lib_a.sh に date という名前の関数を定義
date() {
    echo "$(command date '+%Y%m%d')"   # 引数なしで日付文字列だけ返す
}

# main.sh で source して呼び出す
source ./lib_a.sh

BACKUP_FILE="/backup/data_$(date '+%Y-%m-%d').tar.gz"
# ↑ date 関数が呼ばれるため、'+%Y-%m-%d' は単なる引数として無視され
#   "data_20260908.tar.gz" ではなく "data_20260908.tar.gz" という
#   フォーマット崩れが起きる（または意図しない挙動になる）

# lib_a.sh: 汎用名を使ったライブラリ
log() { echo "[INFO] $*"; }

# lib_b.sh: 別の開発者が書いた別ライブラリ（同名で定義）
log() { echo "[DEBUG] $*"; }

# main.sh
source ./lib_a.sh
source ./lib_b.sh

log "バックアップ完了"
# → "[DEBUG] バックアップ完了" と出力される
# lib_b.sh の log が lib_a.sh の log を上書きした

# 定義済みのシェル関数名を一覧する
declare -F

# 関数名だけを抽出する場合
declare -F | awk '{print $3}'

$ source ./lib/bk_core.sh
$ declare -F
declare -f _bk_build_tar_cmd
declare -f _bk_rotate_old
declare -f _bk_validate_args
declare -f bk_cleanup
declare -f bk_full
declare -f bk_incremental
declare -f bk_log
declare -f bk_status

$ declare -f bk_log
bk_log ()
{
    local level="$1"
    local msg="$2"
    echo "[$level] $(date '+%Y-%m-%d %T') $msg"
}

# 関数が定義されているか確認する（0=定義済み、1=未定義）
declare -F bk_log >&/dev/null && echo "定義済み" || echo "未定義"

# type -t は名前の種別を alias/builtin/function/file のいずれかで返す
# 何も見つからなければ何も出力せず終了コード 1 を返す

$ type -t ls
alias

$ type -t cd
builtin

$ type -t date
file

$ type date
date is /usr/bin/date

$ type -t bk_log
function

$ type -t nonexistent_name
（何も出力されない・exit 1）

# _lib_assert_safe_name: 指定した名前が既存の builtin/file と衝突しないか確認する
# 引数: 関数名
# 戻り値: 0=安全、1=衝突あり（エラーを stderr に出力）
_lib_assert_safe_name() {
    local name="$1"
    local kind
    kind=$(type -t "$name" 2>/dev/null)
    case "$kind" in
        builtin|file|alias)
            printf "ERROR: '%s' は既に '%s' として存在します。関数名を変更してください。\n" \
                   "$name" "$kind" >&2
            return 1 ;;
        *)
            return 0 ;;  # 未定義または既存の function: 呼び出し元で判断
    esac
}

# ライブラリの先頭でチェックしてから定義する
_lib_assert_safe_name "bk_log"    || exit 1
bk_log() {
    local level="$1"
    local msg="$2"
    echo "[$level] $(date '+%Y-%m-%d %T') $msg"
}

# 【悪い例】汎用的な名前は衝突しやすい
log()     { echo "[INFO] $*"; }
backup()  { tar czf "/backup/$(date +%Y%m%d).tar.gz" "$@"; }
check()   { df -h; }
cleanup() { rm -f /tmp/work.*; }

# 【良い例】プロジェクト識別子（2～4文字）をプレフィックスに使う
# bk = backup project の略称
bk_log()     { echo "[INFO] $*"; }
bk_backup()  { tar czf "/backup/$(date +%Y%m%d).tar.gz" "$@"; }
bk_check()   { df -h; }
bk_cleanup() { rm -f /tmp/work.*; }

# 公開関数: プレフィックス付き（外部スクリプトから呼び出してよい）
bk_run_full()        { _bk_validate_dir "$1" && _bk_do_tar "$1"; }
bk_run_incremental() { _bk_validate_dir "$1" && _bk_do_rsync "$1"; }
bk_get_status()      { _bk_read_last_log; }

# 内部ヘルパー: _ 始まり（同一ライブラリファイル内だけで使う）
_bk_validate_dir()   { [[ -d "$1" ]] || { echo "ERROR: $1 が存在しません" >&2; return 1; }; }
_bk_do_tar()         { tar czf "/backup/$(date +%Y%m%d_%H%M%S).tar.gz" "$1"; }
_bk_do_rsync()       { rsync -a --link-dest=/backup/latest "$1" "/backup/$(date +%Y%m%d)/"; }
_bk_read_last_log()  { tail -1 /var/log/bk_backup.log 2>/dev/null; }

bk_log() {
    local level="$1"
    local msg="$2"
    echo "[$level] $(date '+%Y-%m-%d %T') $msg"
}

# 関数を定義した直後に readonly -f でロックする
readonly -f bk_log

# これ以降、bk_log を再定義しようとするとエラーになる
bk_log() { echo "上書き"; }

$ source ./lib/bk_core.sh
$ bk_log() { echo "上書き"; }
bash: bk_log: readonly function

# bk_core.sh の末尾に追加する
# bk_ で始まる全公開関数を readonly -f でロック
while IFS= read -r fn_name; do
    readonly -f "$fn_name"
done < <(declare -F | awk '$3 ~ /^bk_/ {print $3}')

# readonly -f が適用されているかを確認する
# readonly な関数には "-fr" フラグが付く（f=function, r=readonly）
$ declare -p -f bk_log
declare -fr bk_log

lib/
├── bk_log.sh       # ログ関数（bk_log, bk_log_error）
├── bk_backup.sh    # バックアップ本体（bk_full, bk_incremental）
└── bk_notify.sh    # 通知関数（bk_notify_slack, bk_notify_mail）

#!/bin/bash
set -euo pipefail

LIB_DIR="$(cd "$(dirname "$0")/lib" && pwd)"

# ライブラリをまとめて読み込む
for lib_file in "${LIB_DIR}"/bk_*.sh; do
    if [[ ! -f "$lib_file" ]]; then
        echo "ERROR: ライブラリが見つかりません: $lib_file" >&2
        exit 1
    fi
    # shellcheck source=/dev/null
    source "$lib_file"
done

# 読み込み後に定義済み関数を確認（デバッグ時に有用）
# declare -F | awk '$3 ~ /^bk_/ {print $3}'

# エントリポイント
bk_log "INFO" "バックアップ開始"
bk_full "/var/data" || { bk_log "ERROR" "バックアップ失敗"; exit 1; }
bk_notify_slack "バックアップ完了: $(date '+%Y-%m-%d %T')"
bk_log "INFO" "バックアップ完了"

# 衝突チェックスクリプト（CI で実行する）
DANGER_NAMES=(
    ls cp mv rm mkdir find grep sed awk date printf echo
    read test true false cat head tail sort uniq wc cut
    log backup check cleanup run exec init
)

for name in "${DANGER_NAMES[@]}"; do
    if declare -F "$name" >&/dev/null; then
        echo "WARN: 危険な関数名が定義されています: $name" >&2
    fi
done

# エラー例
$ source ./lib_b.sh
bash: bk_log: readonly function

# 対処: どこで bk_log が再定義されているかを確認する
grep -rn "bk_log\s*()" ./lib_b.sh
# または、lib_b.sh を source する前に readonly フラグを確認する
declare -p -f bk_log 2>/dev/null
# "declare -fr bk_log" と表示されれば readonly が有効

# 関数の定義を削除する
unset -f ls        # 関数として定義された ls を削除
unset -f date      # 関数として定義された date を削除

# 削除後に確認する
type -t ls         # alias （元のエイリアスに戻る）
type -t date       # file  （外部コマンドが使えるようになる）

# readonly が適用された関数は unset -f できない
$ unset -f bk_log
bash: unset: bk_log: cannot unset: readonly function
# → サブシェル（bash -c や スクリプト実行）で処理するしかない

# bk_ プレフィックスの関数だけを一覧する
declare -F | awk '$3 ~ /^bk_/ {print $3}'

# _ 始まりの内部関数を除いた公開関数だけを一覧する
declare -F | awk '$3 ~ /^bk_[^_]/ {print $3}'