feat: 代码标准化和文件重命名
## 新增功能 - 创建统一的公共函数库 (common/logging.sh, common/error_handler.sh) - 添加功能演示脚本 (common/demo_usage.sh) - 完善的使用文档 (common/README.md) ## 代码重构 - 重构所有脚本使用统一的公共库 - 为所有函数添加完整的文档注释 - 统一代码格式（4空格缩进、严格模式） - 标准化错误处理和日志输出 ## 文件重命名 - gcp/create_ai_project.sh → gcp/create_ai_projects.sh (单复数统一) - gcp/delete_all_project.sh → gcp/delete_all_projects.sh (单复数统一) - linux/install_ohmyzsh.sh → linux/install_oh_my_zsh.sh (专有名词规范) - linux/create_raid0_with_ext4.sh → linux/create_raid0_array.sh (简化命名) - common/example.sh → common/demo_usage.sh (更具描述性) ## 技术改进 - 使用 readonly 声明常量 - 启用 set -euo pipefail 严格模式 - 统一的 ANSI 颜色日志输出 - 完善的命令重试机制 - 栈追踪支持
This commit is contained in:
245
common/README.md
Normal file
245
common/README.md
Normal file
@@ -0,0 +1,245 @@
|
||||
# 公共函数库
|
||||
|
||||
本目录包含可复用的 Bash 函数库，用于标准化所有脚本的日志输出和错误处理。
|
||||
|
||||
## 📦 包含的库
|
||||
|
||||
### 1. logging.sh - 日志输出库
|
||||
|
||||
提供统一的日志输出函数，支持多个日志级别和彩色输出。
|
||||
|
||||
**功能特性:**
|
||||
- 5个日志级别：DEBUG, INFO, WARNING, ERROR, SUCCESS
|
||||
- 彩色控制台输出
|
||||
- 可选的时间戳
|
||||
- 支持输出到文件
|
||||
- 灵活的日志级别控制
|
||||
|
||||
**使用示例:**
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
source common/logging.sh
|
||||
|
||||
# 基本使用
|
||||
log_info "程序启动"
|
||||
log_success "操作完成"
|
||||
log_warning "磁盘空间不足"
|
||||
log_error "连接失败"
|
||||
log_debug "调试信息"
|
||||
|
||||
# 设置日志级别
|
||||
log_set_level "DEBUG" # 显示所有日志
|
||||
|
||||
# 输出到文件
|
||||
log_set_file "/var/log/myapp.log"
|
||||
|
||||
# 禁用时间戳
|
||||
log_disable_timestamp
|
||||
```
|
||||
|
||||
### 2. error_handler.sh - 错误处理库
|
||||
|
||||
提供统一的错误处理和检查机制。
|
||||
|
||||
**功能特性:**
|
||||
- 命令存在性检查
|
||||
- 文件/目录检查
|
||||
- 变量非空检查
|
||||
- Root 权限检查
|
||||
- 命令返回值检查
|
||||
- 带重试的命令执行
|
||||
- 调用栈跟踪
|
||||
|
||||
**使用示例:**
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
source common/error_handler.sh
|
||||
|
||||
# 启用严格错误处理
|
||||
enable_exit_on_error
|
||||
|
||||
# 检查命令是否存在
|
||||
check_command "git" || error_exit "git 未安装"
|
||||
|
||||
# 检查文件
|
||||
check_file "/etc/config" || error_exit "配置文件不存在"
|
||||
|
||||
# 检查 root 权限
|
||||
check_root || error_exit "需要 root 权限"
|
||||
|
||||
# 执行命令并检查结果
|
||||
run_command "安装失败" apt-get install -y package
|
||||
|
||||
# 带重试的命令执行
|
||||
retry_command 3 5 "下载失败" curl -O https://example.com/file
|
||||
|
||||
# 检查变量非空
|
||||
check_not_empty "$PROJECT_ID" "PROJECT_ID" || error_exit "项目ID不能为空"
|
||||
```
|
||||
|
||||
## 🚀 完整示例脚本
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# ============================================================================
|
||||
# 示例脚本：展示如何使用公共函数库
|
||||
# ============================================================================
|
||||
|
||||
# 获取脚本目录
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
|
||||
# 加载公共库
|
||||
source "${SCRIPT_DIR}/../common/logging.sh"
|
||||
source "${SCRIPT_DIR}/../common/error_handler.sh"
|
||||
|
||||
# 配置日志
|
||||
log_set_level "INFO"
|
||||
log_set_file "/tmp/example.log"
|
||||
|
||||
# 启用错误处理
|
||||
enable_exit_on_error
|
||||
|
||||
#
|
||||
# 主函数
|
||||
#
|
||||
main() {
|
||||
log_info "脚本开始执行"
|
||||
|
||||
# 检查必要的命令
|
||||
check_command "git" || error_exit "请先安装 git"
|
||||
|
||||
# 检查参数
|
||||
local project_name="$1"
|
||||
check_not_empty "$project_name" "project_name" || {
|
||||
log_error "用法: $0 <project_name>"
|
||||
exit 1
|
||||
}
|
||||
|
||||
# 执行操作
|
||||
log_info "正在处理项目: $project_name"
|
||||
|
||||
# 带重试的网络操作
|
||||
retry_command 3 2 "网络请求失败" curl -f "https://example.com/api"
|
||||
|
||||
log_success "脚本执行完成"
|
||||
}
|
||||
|
||||
# 执行主函数
|
||||
main "$@"
|
||||
```
|
||||
|
||||
## 📖 最佳实践
|
||||
|
||||
### 1. 脚本模板
|
||||
|
||||
每个脚本都应遵循以下模板结构：
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -euo pipefail # 启用严格模式
|
||||
|
||||
# 脚本信息
|
||||
# ============================================================================
|
||||
# 文件名: script_name.sh
|
||||
# 描述: 脚本功能描述
|
||||
# 作者: 作者名
|
||||
# 版本: 1.0.0
|
||||
# ============================================================================
|
||||
|
||||
# 常量定义
|
||||
readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
readonly SCRIPT_NAME="$(basename "$0")"
|
||||
|
||||
# 加载公共库
|
||||
source "${SCRIPT_DIR}/../common/logging.sh"
|
||||
source "${SCRIPT_DIR}/../common/error_handler.sh"
|
||||
|
||||
# 全局变量
|
||||
GLOBAL_VAR=""
|
||||
|
||||
#
|
||||
# 显示使用帮助
|
||||
#
|
||||
show_usage() {
|
||||
cat << EOF
|
||||
使用方法: $SCRIPT_NAME [选项]
|
||||
|
||||
选项:
|
||||
-h, --help 显示此帮助信息
|
||||
-v, --verbose 启用详细输出
|
||||
|
||||
示例:
|
||||
$SCRIPT_NAME --verbose
|
||||
EOF
|
||||
}
|
||||
|
||||
#
|
||||
# 主函数
|
||||
#
|
||||
main() {
|
||||
log_info "脚本开始执行"
|
||||
|
||||
# 你的代码逻辑
|
||||
|
||||
log_success "脚本执行完成"
|
||||
}
|
||||
|
||||
# 执行主函数
|
||||
main "$@"
|
||||
```
|
||||
|
||||
### 2. 错误处理建议
|
||||
|
||||
- 总是检查命令返回值
|
||||
- 使用 `check_*` 函数进行前置条件检查
|
||||
- 对网络操作使用 `retry_command`
|
||||
- 提供有意义的错误消息
|
||||
|
||||
### 3. 日志使用建议
|
||||
|
||||
- INFO: 正常流程信息
|
||||
- SUCCESS: 操作成功完成
|
||||
- WARNING: 需要注意但不影响执行的情况
|
||||
- ERROR: 错误但可以继续的情况
|
||||
- DEBUG: 调试信息（默认不显示）
|
||||
|
||||
## 🔧 环境变量配置
|
||||
|
||||
### logging.sh 环境变量
|
||||
|
||||
```bash
|
||||
# 设置日志级别 (DEBUG=0, INFO=1, WARNING=2, ERROR=3, SUCCESS=4)
|
||||
export LOG_CURRENT_LEVEL=1
|
||||
|
||||
# 设置日志文件路径
|
||||
export LOG_FILE_PATH="/var/log/myapp.log"
|
||||
|
||||
# 启用/禁用时间戳
|
||||
export LOG_ENABLE_TIMESTAMP=true
|
||||
```
|
||||
|
||||
### error_handler.sh 环境变量
|
||||
|
||||
```bash
|
||||
# 错误时是否退出 (true/false)
|
||||
export ERROR_EXIT_ON_FAIL=true
|
||||
|
||||
# 是否显示调用栈 (true/false)
|
||||
export ERROR_STACK_TRACE=false
|
||||
```
|
||||
|
||||
## 📝 维护说明
|
||||
|
||||
- 版本: 1.0.0
|
||||
- 最后更新: 2025-12-26
|
||||
- 维护者: Cloud Tools Project
|
||||
|
||||
## 🤝 贡献
|
||||
|
||||
如需添加新功能或修复 bug，请：
|
||||
1. 保持向后兼容性
|
||||
2. 添加完整的函数文档注释
|
||||
3. 提供使用示例
|
||||
4. 更新此 README
|
||||
Reference in New Issue
Block a user