Bash中实现变量与函数访问修饰（区分source可见与内部私有）的通用约定

核心机制背景：Bash的source（等价于.内置命令）不会创建独立子Shell，而是直接在当前执行上下文运行脚本的所有代码，因此脚本顶层定义的全局变量、函数默认都会污染调用方的Shell上下文。要实现“部分内容对外可见、其余内容内部私有”的效果，需要严格遵循Bash生态的通用作用域规则，避免无意义的特殊技巧。

一、需要对外暴露的变量/函数的处理规则 #

这类内容的目标是让执行source操作的当前Shell可以直接读取、调用，必须遵守以下惯例：

• 直接在脚本无嵌套的顶层执行流中定义，不能被包裹在子Shell、函数作用域内部，否则加载完成后外部上下文无法访问
• 涉及需要传递给后续子进程的环境变量，必须添加export前缀做标记
• 所有对外暴露的标识符必须添加项目专属的命名前缀，避免和当前Shell已有的变量、函数重名冲突。比如使用MYAPP_作为变量前缀，myapp_作为函数前缀，绝对不要直接使用config、start这类通用命名
• 对外暴露的标识符不能使用local修饰——local仅在函数作用域内生效，顶层使用会直接报错

二、需要做内部私有化的变量/函数的实现规则 #

这类内容的目标是仅在脚本内部执行时可访问，执行完成后不残留到外部Shell上下文，最通用的实现方式是借助Bash的函数局部作用域自动回收机制，具体规则如下：

• 定义一个带专属前缀、命名足够特殊的私有初始化入口函数，比如__myapp_internal_bootstrap__
• 所有的临时变量、内部工具函数的定义，全部放在这个私有入口函数内部：
  • 所有临时变量必须用local关键字修饰，这类变量仅在当前函数的执行栈上存在，函数执行完成后会被Bash自动回收，不会泄露到外层上下文
  • 所有嵌套的内部工具函数，必须用local function语法声明为局部函数，避免这类函数被Bash默认注册到全局命名空间
• 私有初始化逻辑执行的过程中，将需要对外暴露的内容，手动赋值到我们预先定义好的全局命名空间（也就是之前说的带前缀的顶层变量、全局接口函数）
• 整个私有初始化函数定义完成后，在脚本顶层调用一次该函数，调用完成后立刻用unset -f删除这个初始化入口函数本身，避免它泄露到外部上下文

可直接复用的参考代码结构：

# ---- 全局对外接口的预留定义区（无嵌套顶层位置） ----
export MYAPP_VERSION="2.1.0"
export MYAPP_CONFIG_PATH="/etc/myapp/app.conf"
# 全局可调用的启动接口
function myapp_start() {
  echo "应用启动，当前版本：${MYAPP_VERSION}"
}

# ---- 私有内部逻辑区 ----
function __myapp_internal_bootstrap__() {
  # 所有内部临时变量，加local修饰，绝不泄露
  local temp_parse_result
  local temp_log_level

  # 内部工具函数，用local声明，全局完全访问不到
  local function __parse_config_file() {
    temp_log_level=$(grep -E "^log_level=" "$MYAPP_CONFIG_PATH" | cut -d= -f2)
    # 如果配置读取失败则设置默认值
    [ -z "$temp_log_level" ] && temp_log_level="info"
  }

  # 执行内部解析逻辑
  __parse_config_file
  # 将解析得到的结果赋值给对外可见的全局变量
  MYAPP_CURRENT_LOG_LEVEL="$temp_log_level"
  # 给全局接口补充内部逻辑
  function myapp_start() {
    echo "日志级别设置为：$MYAPP_CURRENT_LOG_LEVEL"
  }
}

# 执行一次初始化
__myapp_internal_bootstrap__
# 立刻删除初始化入口函数，避免泄露
unset -f __myapp_internal_bootstrap__

三、常见的反惯例操作（需要避免） #

• 不要为了实现私有化，把整个脚本内容包裹在( ... )子Shell中执行：这种方式下，所有在子Shell中设置的对外变量，根本无法传回执行source的父Shell上下文，完全违背source加载的设计初衷
• 不要靠脚本末尾手动unset所有临时变量实现私有化：如果脚本执行过程中遇到报错提前退出，未执行到unset步骤的变量会全部残留到外部Shell，可靠性远低于函数局部作用域的自动回收机制
• 不要在内部函数中定义不做local标记的嵌套函数：Bash默认会把函数内部定义的所有无修饰的函数注册为全局函数，哪怕这个函数是在其他函数里写的，会导致大量内部逻辑意外泄露

四、私有化效果的校验方法 #

脚本开发完成后，可通过以下方式确认没有意外泄露的内容：

• 加载脚本前，分别保存当前Shell的全局变量列表、全局函数列表到临时文件
• 加载完脚本后，重新生成一次全局变量、函数列表，和之前的文件做diff，所有diff中出现的、不在我们预先规划的对外暴露名单里的内容，就是意外泄露的部分
• 加载完成后，尝试手动调用内部的临时函数、查看临时变量，如果能正常读到，就说明局部作用域的保护没有生效，需要修正

内容的提问来源于stack exchange，提问作者Alesi Rowland