Shell 脚本工程化：从"能跑"到"能用"¶

#!/usr/bin/env bash
# 用 env bash 而不是 /bin/bash，因为不同系统 bash 路径可能不同
# env 会在 PATH 中找到 bash 的实际位置

set -euo pipefail
# -e：命令失败立即退出（Exit on error）
# -u：使用未定义变量报错（Undefined variable = error）
# -o pipefail：管道中任一命令失败，整个管道失败
#   比如 cat missing_file | sort 默认只看 sort 的退出码(0)
#   加了 pipefail 会捕获到 cat 的错误

# ==============================================================================
# 脚本名称：run_metagenome_qc.sh
# 功    能：宏基因组原始数据质控（fastp + host removal）
# 作    者：[用户] <pengwq@example.com>
# 创建日期：2026-05-01
# 修改日期：2026-05-03
# 版    本：v1.2.0
# 依    赖：fastp>=1.0, bowtie2>=2.4, samtools>=1.15
# 用    法：bash run_metagenome_qc.sh -i raw_dir -o clean_dir -t 8
# ==============================================================================

# --- 默认值 ---
INPUT_DIR=""           # 输入目录（必填）
OUTPUT_DIR="./clean"   # 输出目录（默认 ./clean）
THREADS=4              # 线程数（默认 4）
HOST_REF=""            # 宿主参考基因组（可选）

# --- 用法说明函数 ---
usage() {
    cat <<EOF
用法: $(basename "$0") -i <input_dir> -o <output_dir> [-t threads] [-r host_ref]

必填参数:
  -i  输入目录（含 *_R1.fastq.gz 和 *_R2.fastq.gz）
  -o  输出目录

可选参数:
  -t  线程数（默认: 4）
  -r  宿主参考基因组（bowtie2 索引前缀）
  -h  显示帮助信息
EOF
    exit 1
}

# --- 解析参数 ---
while getopts ":i:o:t:r:h" opt; do  # 冒号表示该选项需要参数
    case ${opt} in
        i) INPUT_DIR="${OPTARG}" ;;   # OPTARG 是选项的参数值
        o) OUTPUT_DIR="${OPTARG}" ;;
        t) THREADS="${OPTARG}" ;;
        r) HOST_REF="${OPTARG}" ;;
        h) usage ;;
        \?) echo "错误: 无效选项 -${OPTARG}" >&2; usage ;;  # 未知选项
        :)  echo "错误: 选项 -${OPTARG} 需要参数" >&2; usage ;;  # 缺少参数
    esac
done

# --- 必填参数检查 ---
if [[ -z "${INPUT_DIR}" ]]; then
    echo "错误: 必须指定输入目录 (-i)" >&2
    usage
fi

# --- 日志函数 ---
log_info()  { echo "[$(date '+%Y-%m-%d %H:%M:%S')] [INFO]  $*"; }
log_warn()  { echo "[$(date '+%Y-%m-%d %H:%M:%S')] [WARN]  $*" >&2; }
log_error() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] [ERROR] $*" >&2; }

# 使用示例
log_info "开始质控，输入目录: ${INPUT_DIR}"
log_warn "宿主基因组未指定，跳过去宿主步骤"
log_error "fastp 运行失败，退出码: $?"

# --- 临时目录与清理 ---
TMPDIR=$(mktemp -d "${TMPDIR:-/tmp}/metagenome_qc.XXXXXX")
# mktemp -d 创建唯一临时目录，XXXXXX 会被替换为随机字符

# trap 语法：trap '命令' 信号
# EXIT：脚本退出时执行（不管正常还是异常）
# ERR：命令出错时执行
# INT：用户按 Ctrl+C 时执行
cleanup() {
    local exit_code=$?
    log_info "清理临时文件: ${TMPDIR}"
    rm -rf "${TMPDIR}"
    if [[ ${exit_code} -ne 0 ]]; then
        log_error "脚本异常退出，退出码: ${exit_code}"
    fi
    exit ${exit_code}
}
trap cleanup EXIT   # 注册清理函数，脚本退出时自动执行

# --- 检查依赖工具是否安装 ---
check_dependency() {
    local cmd="$1"                          # 要检查的命令名
    if ! command -v "${cmd}" &>/dev/null; then  # command -v 检查命令是否存在
        log_error "依赖工具 '${cmd}' 未安装或不在 PATH 中"
        exit 127  # 127 = command not found（标准退出码）
    fi
}

check_dependency fastp
check_dependency bowtie2
check_dependency samtools
log_info "所有依赖检查通过"

# 标准退出码：
# 0   - 成功
# 1   - 一般错误
# 2   - 参数错误
# 126 - 权限不足
# 127 - 命令未找到
# 自定义退出码（用 10 以上）：
# 10  - 输入文件不存在
# 11  - 输出目录创建失败
# 12  - 上游工具运行失败

#!/usr/bin/env bash
# ==============================================================================
# 脚本名称：run_fastp_qc.sh
# 功    能：对宏基因组双端测序数据进行质控（fastp）
# 作    者：pengwq
# 版    本：v1.0.0
# 用    法：bash run_fastp_qc.sh -i raw/ -o clean/ -t 8
# ==============================================================================
set -euo pipefail

# ---------- 日志函数 ----------
log_info()  { echo "[$(date '+%Y-%m-%d %H:%M:%S')] [INFO]  $*"; }
log_error() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] [ERROR] $*" >&2; }

# ---------- 参数默认值 ----------
INPUT_DIR=""
OUTPUT_DIR="./clean"
THREADS=4

# ---------- 用法 ----------
usage() { echo "用法: $0 -i <input> -o <output> [-t threads]"; exit 2; }
while getopts ":i:o:t:h" opt; do
    case ${opt} in
        i) INPUT_DIR="${OPTARG}" ;;
        o) OUTPUT_DIR="${OPTARG}" ;;
        t) THREADS="${OPTARG}" ;;
        h) usage ;;
        *) usage ;;
    esac
done
[[ -z "${INPUT_DIR}" ]] && { log_error "缺少 -i 参数"; usage; }

# ---------- 依赖检查 ----------
command -v fastp &>/dev/null || { log_error "fastp 未安装"; exit 127; }

# ---------- 临时文件清理 ----------
TMPDIR=$(mktemp -d)
trap 'rm -rf "${TMPDIR}"; log_info "清理完成"' EXIT

# ---------- 创建输出目录 ----------
mkdir -p "${OUTPUT_DIR}" || { log_error "无法创建 ${OUTPUT_DIR}"; exit 11; }

# ---------- 核心逻辑 ----------
log_info "开始质控: ${INPUT_DIR} -> ${OUTPUT_DIR}"

for r1 in "${INPUT_DIR}"/*_R1.fastq.gz; do
    sample=$(basename "${r1}" _R1.fastq.gz)  # 从文件名提取样本名
    r2="${INPUT_DIR}/${sample}_R2.fastq.gz"   # 推导 R2 文件名

    [[ -f "${r2}" ]] || { log_error "${r2} 不存在，跳过 ${sample}"; continue; }

    log_info "处理样本: ${sample}"
    fastp \
        --in1 "${r1}" --in2 "${r2}" \
        --out1 "${OUTPUT_DIR}/${sample}_R1.clean.fq.gz" \
        --out2 "${OUTPUT_DIR}/${sample}_R2.clean.fq.gz" \
        --json "${OUTPUT_DIR}/${sample}.fastp.json" \
        --html "${OUTPUT_DIR}/${sample}.fastp.html" \
        --thread "${THREADS}" \
        --qualified_quality_phred 20 \
        --length_required 50 \
        2>"${OUTPUT_DIR}/${sample}.fastp.log"

    log_info "完成: ${sample}"
done

log_info "全部质控完成，结果在 ${OUTPUT_DIR}"
exit 0

# Ubuntu/Debian 安装
sudo apt install shellcheck            # 系统包管理器安装

# conda 安装（推荐，不需要 sudo）
conda install -c conda-forge shellcheck

# 基本使用
shellcheck my_script.sh               # 检查脚本
shellcheck -s bash my_script.sh       # 指定 shell 为 bash
shellcheck -x my_script.sh            # 跟踪 source 的文件一起检查

# 输出格式
shellcheck -f json my_script.sh       # JSON 格式（可集成到 CI）
shellcheck -f gcc  my_script.sh       # GCC 风格（编辑器友好）

# SC2086: 变量没有引号（可能导致分词问题）
# 错误写法：
cp $file /backup/           # 如果 file="my file.txt" 就会出错
# 正确写法：
cp "$file" /backup/         # 加引号保护空格

# SC2034: 变量赋值但未使用
UNUSED_VAR="hello"          # ShellCheck 会提醒你这个没用到

# SC2155: declare/local 和赋值同行会掩盖退出码
# 错误写法：
local output=$(command)     # 如果 command 失败，local 的返回值是 0
# 正确写法：
local output
output=$(command)           # 分开写，$? 才能捕获 command 的退出码

# 忽略特定规则（在该行上方加注释）
# shellcheck disable=SC2086
cp $file /backup/           # 这行不再报 SC2086

# 通过 npm 安装（最简单）
npm install -g bats

# 或者从源码安装
git clone https://github.com/bats-core/bats-core.git
cd bats-core && sudo ./install.sh /usr/local

#!/usr/bin/env bats
# 文件名：test_utils.bats

# setup() 在每个测试前运行（类似 pytest 的 fixture）
setup() {
    source ./utils.sh          # 加载被测试的函数
    TEST_DIR=$(mktemp -d)      # 创建临时目录
}

# teardown() 在每个测试后运行（清理）
teardown() {
    rm -rf "$TEST_DIR"
}

# @test 定义一个测试用例
@test "log_info 输出包含 INFO 标记" {
    result=$(log_info "test message")  # 执行函数
    [[ "$result" == *"[INFO]"* ]]      # 断言输出包含 [INFO]
}

@test "check_dependency 对存在的命令返回0" {
    run check_dependency bash          # run 会捕获输出和退出码
    [ "$status" -eq 0 ]               # $status 是退出码
}

@test "check_dependency 对不存在的命令返回127" {
    run check_dependency nonexistent_tool_xyz
    [ "$status" -eq 127 ]
}

bats test_utils.bats           # 运行单个测试文件
bats tests/                    # 运行目录下所有 .bats 文件
bats --tap tests/              # TAP 格式输出（CI 友好）

# =========================================================
# Makefile: 宏基因组分析流程
# 用法: make all -j 4（4 个任务并行）
# =========================================================

# --- 配置 ---
SAMPLES   := sample1 sample2 sample3
RAW_DIR   := data/raw
CLEAN_DIR := data/clean
THREADS   := 8

# --- 目标文件列表（Make 靠文件是否存在/更新来决定是否重跑） ---
CLEAN_R1  := $(patsubst %,$(CLEAN_DIR)/%_R1.clean.fq.gz,$(SAMPLES))
# patsubst 批量替换：把每个样本名变成对应的输出文件路径

# --- 默认目标 ---
.PHONY: all clean help
all: $(CLEAN_R1)     # make all 会生成所有 clean 文件

# --- 规则：从原始数据生成质控数据 ---
# $* 是 stem（匹配 % 的部分，即样本名）
# $@ 是目标文件
# $< 是第一个依赖文件
$(CLEAN_DIR)/%_R1.clean.fq.gz: $(RAW_DIR)/%_R1.fastq.gz $(RAW_DIR)/%_R2.fastq.gz
    @mkdir -p $(CLEAN_DIR)
    fastp --in1 $(RAW_DIR)/$*_R1.fastq.gz \
          --in2 $(RAW_DIR)/$*_R2.fastq.gz \
          --out1 $@ \
          --out2 $(CLEAN_DIR)/$*_R2.clean.fq.gz \
          --thread $(THREADS)

# --- 清理 ---
clean:
    rm -rf $(CLEAN_DIR)

help:
    @echo "make all    - 运行全部质控"
    @echo "make clean  - 删除质控结果"

# --- 方法1: for 循环 ---
for fq in data/raw/*_R1.fastq.gz; do
    sample=$(basename "$fq" _R1.fastq.gz)
    echo "处理 ${sample}"
    # ... 分析命令
done

# --- 方法2: while read（从文件读取样本列表） ---
while IFS=$'\t' read -r sample group; do    # IFS 指定分隔符为 Tab
    echo "处理 ${sample}，分组: ${group}"
done < sample_list.tsv

# parallel 让你用一行命令并行处理多个样本
# -j 4：同时跑 4 个任务
# {}：占位符，被输入替换
# {/.}：去掉路径和后缀的文件名

cat sample_list.txt | parallel -j 4 \
    'fastp --in1 raw/{}_R1.fq.gz --in2 raw/{}_R2.fq.gz \
           --out1 clean/{}_R1.fq.gz --out2 clean/{}_R2.fq.gz'

# 带进度条
parallel --bar -j 4 'process_sample {}' ::: sample1 sample2 sample3 sample4

LOCKFILE="/tmp/pipeline_$(basename "$0").lock"

if [[ -f "${LOCKFILE}" ]]; then
    log_error "另一个实例正在运行（锁文件: ${LOCKFILE}）"
    exit 1
fi
trap 'rm -f "${LOCKFILE}"' EXIT     # 退出时删除锁文件
echo $$ > "${LOCKFILE}"             # $$ 是当前进程 PID

# 检查某步骤的输出是否已存在，已存在则跳过
run_step() {
    local step_name="$1"       # 步骤名称
    local output_file="$2"    # 该步骤的输出文件
    shift 2                    # 移除前两个参数，剩下的是实际命令

    if [[ -f "${output_file}" ]]; then
        log_info "[跳过] ${step_name}: 输出已存在 ${output_file}"
        return 0
    fi

    log_info "[运行] ${step_name}"
    "$@"                       # 执行剩余参数作为命令
    log_info "[完成] ${step_name}"
}

# 使用：只有输出不存在时才运行
run_step "fastp质控" "clean/sample1_R1.fq.gz" \
    fastp --in1 raw/sample1_R1.fq.gz --out1 clean/sample1_R1.fq.gz

# --- config.ini 格式 ---
# RAW_DIR=/data/raw
# OUTPUT_DIR=/data/results
# THREADS=16

# 读取配置文件（跳过注释和空行）
if [[ -f config.ini ]]; then
    while IFS='=' read -r key value; do
        # 跳过注释行和空行
        [[ "${key}" =~ ^#.*$ || -z "${key}" ]] && continue
        # 去掉首尾空格
        key=$(echo "${key}" | xargs)
        value=$(echo "${value}" | xargs)
        # 导出为环境变量
        export "${key}=${value}"
    done < config.ini
    log_info "已加载配置文件 config.ini"
fi

#!/usr/bin/env bash
set -euo pipefail
# 脚本名 | 功能 | 作者 | 日期 | 版本 | 依赖 | 用法