记一次符合 Google Coding Style 的 Bash 脚本重构

[Cloudpods]

最近我在思考这样一个问题，顺便看一下 gpt 对这个问题的解释。搜索发现：

团队写代码，为什么要遵循 coding guideline ？

1. 一致性：编码准则确保整个团队的代码风格和格式是一致的，这使得团队成员之间更易于交流和协作。这也使得代码更容易维护和更新，因为其他人可以更轻松地理解代码。

2. 可读性：编码准则有助于提高代码的可读性。通过对代码进行格式化和注释，代码会更易于阅读和理解，从而减少错误和缺陷，并提高代码的质量。

3. 可维护性：编码准则有助于提高代码的可维护性。通过使用一致的格式和风格，团队成员可以更轻松地理解代码，并进行更快速的故障排除和修复。

4. 代码质量：编码准则有助于提高代码的质量。通过要求团队成员编写可读性高、可维护性强的代码，编码准则可以确保代码更加健壮、可靠和安全。这也有助于减少代码缺陷和错误，提高代码的可靠性和可用性。

5. 代码重用：编码准则有助于提高代码的重用性。通过编写符合标准的代码，团队成员可以更容易地将代码重用在其他项目中，从而提高生产力和效率。

继续搜索：

对于一个使用 bash 为主要语言的项目，业界推荐的 coding guideline ？

1. 使用有意义的变量名：变量名应该具有描述性，以便其他人可以轻松地理解代码。

2. 缩进：使用 4 个空格作为缩进，而不是制表符。

3. 注释：对代码进行注释，以解释代码的目的和功能。注释应该清晰、简洁，并且易于阅读。

4. 函数：编写短小精悍的函数，每个函数都应该具有一个特定的目的。函数应该使用有意义的名称，并且应该清晰地描述其目的和功能。

5. 错误处理：在代码中包含错误处理，以确保代码在遇到错误时不会崩溃或产生不可预测的结果。

6. 使用双引号：在引用变量时，使用双引号而不是单引号，以确保变量扩展能够正常工作。

7. 使用全局变量：尽量避免使用全局变量，因为它们很难调试和维护。

8. 使用命令替换：使用$()语法而不是反引号 ``来执行命令替换。

9. 使用数组：使用数组来管理相关变量，而不是使用多个单独的变量。

10. 使用“set -u”：使用“set -u”来检查未定义的变量，以避免在引用未定义的变量时产生错误。

这些规范有助于提高 Bash 代码的可读性、可维护性和可靠性。

然后我搜索 "bash script style guideline"，最上面的结果是：

即：代码规范： https://google.github.io/styleguide/shellguide.html

我仔细阅读了这份风格指南，对其中的“局部变量”的章节很感兴趣。

文中说：「最好把局部变量的定义与赋值，换行实现，不要写到同一行上」，以免掩盖报错状态码。

原文

Declare function-specific variables with local. Declaration and assignment should be on different lines.

Ensure that local variables are only seen inside a function and its children by using local when declaring them. This avoids polluting the global name space and inadvertently setting variables that may have significance outside the function.

Declaration and assignment must be separate statements when the assignment value is provided by a command substitution; as the local builtin does not propagate the exit code from the command substitution.

我动手验证这个细节，发现果然如此：

然后我开始自查当前的项目，寻找类似于如下风格的代码：

local my_var="$(my_func)"

优化后的预期结果：

local my_var
my_var="$(my_func)"

在 https://regex101.com/ 测试代码的运行。给出范例

regex:  
  local fn=$(echo $name_ver| tr ':' '-').tar.xz
test string
  local fn=$(echo $name_ver| tr ':' '-').tar.xz		#普通
    local fn=$(echo $name_ver| tr ':' '-').tar.xz	# 模拟多个空格
	local fn=$(echo $name_ver| tr ':' '-').tar.xz		# 模拟 tab 缩进
	local fn="$(echo $name_ver| tr ':' '-').tar.xz" # 模拟带引号的变量声明

测似乎生成的代码

$1local $2\n$1$2=$3

生成的代码

$re = '/^(\s*)local\s+(\w+)=("?\$\(.*)/m';
$str = '  local fn=$(echo $name_ver| tr \':\' \'-\').tar.xzt
    local fn=$(echo $name_ver| tr \':\' \'-\').tar.xzt
	local fn=$(echo $name_ver| tr \':\' \'-\').tar.xz
	local fn="$(echo $name_ver| tr \':\' \'-\').tar.xz"';
$subst = "$1local $2\n$1$2=$3";

$result = preg_replace($re, $subst, $str);

echo "The result of the substitution is ".$result;

精简为 perl_oneliner:

perl -pe 's/^(\s*)local\s+(\w+)=("?\$\(.*)/$1local $2\n$1$2=$3/g' -i file.txt

测试的场景：

搜索代码

pcregrep -lr '^(\s*)local\s+(\w+)=("?\$\(.*)' *

批量修正：

perl -pi -e 's#^(\s*)local\s+(\w+)=("?\$\(.*)#$1local $2\n$1$2=$3#' $(pcregrep -l -r '^(\s*)local\s+(\w+)=("?\$\(.*)' * )

修正之后，仔细阅读diff，检验效果，发现符合预期。

后续：增加 git hook 检测代码

为了让以后新增的代码，也都符合上述规范，我增加了这样一个 pre-commit脚本。这样，每次提交之前，它都会帮我确保代码合规。

同时，我在编辑器里，设置了 shfmt 、shellcheck 之类的规范，并设置为format on save，即，保存时自动格式化，来自动处理格式问题。

# test code 
if ! grep -wq 'Code violates rules' .git/hooks/pre-commit; then
cat >> .git/hooks/pre-commit <<'GIT_PRE_COMMIT_EOF'                                                                                                                                        
#!/usr/bin/env bash
if find . -name '*.sh'| xargs pcregrep '^\s+local\s+\w+="?(`|\$\()'; then
  echo "Error: Code violates rules"
  echo 'use: local var'
  echo 'var="$(...")'
  echo 'instead of local var=``'
  echo 'or local var="$(...)"'
  echo 'as of explained in https://google.github.io/styleguide/shellguide.html'
  exit 1
fi
GIT_PRE_COMMIT_EOF
chmod +x .git/hooks/pre-commit
fi

总结：

• 寻找业界规范
• 遵循规范
• 修改过去不合规范的代码
• 新增代码确保合规
• 将代码的规范检查，加入到日常的流程里。（ goimport check)
• 越早做，历史包袱越少。越晚做，历史包袱越沉重。

links

• Checks · koalaman/shellcheck Wiki
• ShellCheck - A shell script static analysis tool
• styleguide | Style guides for Google-originated open-source projects*
• regex101: build, test, and debug regex

原文地址： https://www.yunion.cn/article/index.html

[aloxaf]

1. 文中提到的问题，shellcheck 就能检查，为啥要自造一串正则表达式来处理……
2. 自定义 lint rule ，推荐轻量易用的 semgrep： https://semgrep.dev/playground/s/E2Jo

rules:
- id: declaration-assignment
patterns:
- pattern: local $A=$B
- pattern-not: local $A="..."
message: Declaration and assignment should be on different lines.
languages: [bash]
severity: WARNING
fix: |
$A
$A=$B

（不过 semgrep 的 autofix 一直有点问题，比如上面的规则不能正确处理第二行的缩进

[james122333]

这东西可以 但功效比 hack 语法更小 纯用 bash hack

我已经这样写

#!/bin/bash

source init_file module_path

ns test #namespace

import {
core/str #default namespace in file
rand2 core/rand #namespace rand2
}

import core/ini
import num2 core/num

fn run a b=1 @c @d=^Rabc @e:key::node f...
bgn
err $0: error
echo ok
end

rec abc a
bgn
return a=1 b=2 c=3
end

const {
var1=a
var2=b
}

const var3=c

a 没指定 b 如果带入为空则为 1 c 为 pass by reference 的参数 d 同 c 但有预设值 e 为一结构体结构类型为 key f 剩余参数
函数内 err 后 返回错误 echo ok 不执行
rec 是定义结构 回传阵列 参数方法与 fn 同
const 指定常数

当然不开源 XD

[james122333]

为何 fn 不用 block({})呢

因为可以
if [ ${abc} -eq 1 ] ; then
fn abc a=1
else
fn abc b=1
fi
bgn
....
end

猫熊万岁 XD

[mohumohu]

local 甚至不符合 POSIX sh 标准

[james122333]

@mohumohu

然而如果你只用 posix sh 会很难维护大型 shell 专案
效能也差

[james122333]

一堆项目内的 configure 脚本很烂就是这样
autotools 完全是悲剧

[mohumohu]

@james122333 用 shell 的初衷就是为了跨平台跨系统兼容，真要大型效能就用 python 去了

[james122333]

@mohumohu

现在哪个发行版还在 posix sh 所以兼容没问题
python 太臃肿 shell 单执行档就好了 光论效能 shell 是垫底的 但 posix sh 是最底的 但很多任务效能需求不高 用 shell 写可以 但 posix sh 就会明显卡顿 技术原理问题

[james122333]

差点忘了 csh 也是效能最差的 语法最神奇的 会出神秘现象

[mohumohu]

@james122333 很多嵌入式设备只有 busybox ，没有 bash ，而且都跑 shell 了，我不觉得需要有什么效能的差别，shell 核心都是调用别的程序完成任务，像 grep ，sed ，能效跟 shell 本身关系不大。

[nuk]

用数组限制太大了，至今都没什么机会用上，sh 主要就是写一些安装脚本，复杂一点我会用 lua ，table 基本上可以解决一切需要存储的地方，string.match 能解决大概 90%的正则需求，关键是非常可靠而且安全。大概十年前见过一个台湾生产的路由器，进去看才发现里面所有的页面都是用 shell 实现的 cgi ，当时震惊到我了。

[mohumohu]

@james122333 你真要这么说，一堆 docker 常用的发行版就是没 bash 的，比如 alpine

[nuk]

用 shell 实现太容易出现注入漏洞了，几年前的 360 路由器第一代，我逆向固件后，发现其中一个一百行不到的 shell 实现的 cgi 都有注入漏洞，可以直接远程执行命令，而这仅仅是因为 escape 字符串不到位而已，还有 ruckus 路由器也有注入漏洞，我拿来解除国家码限制。这都还是会考虑到安全因素的路由器，所以用 shell 写东西不难，难的是要全面的考虑到安全。

[james122333]

@mohumohu

即便你嵌入式 bash 还是比 python 小 至于 bash 与 posix sh 当然有效能差异 例如你说的 local 没有不是得多加判别不然就是写的很小心 还有简单数值计算 你用 expr 每次都得启动程序一次怎么无关效能 读档案每次调用 cat? 当然有差 grep sed 命令堆叠是最伤效能的 configure 就是一例 没有这些 啪 一下就出来的 这些命令一次处理大量内容才会有效能优势

[james122333]

@mohumohu

因为这些发行版以最简化为准则 跑的也是其它语言写的大型程序 当然 shell 什么的不重要 但其实这些东西很强大的

[swulling]

为啥不用 shell 的 lint 工具，比如 shellcheck 。

难道别的语言的 lint 工具都自己写么……

[james122333]

@nuk

bash 有关联数组 其实还好 也有正则 但其实不怎么用正则 通常有更好实现 我都是自己研究自己搞 没看过别人用 cgi
注入漏洞我这写好的函数没有 当然我自己用

[mohumohu]

@james122333 就是因为要保证兼容嵌入式设备才更要考虑 POSIX sh 标准

[mohumohu]

@james122333 很多 docker 的 init 就是用 shell 写的

[james122333]

@mohumohu

能运行不就是兼容 有哪个专属硬件不能跑？
docker init 用 shell 写的 然后呢？ 大部分都有 bash 可用
apline 类的装一下也不花多少时间

[mohumohu]

@james122333 不能跑：比如光猫上跑 ddns 脚本
我能用 sh 实现的为啥要多装一个软件增大容器镜像体积

[james122333]

@mohumohu
整个工具很小的 再嫌大拿直接二近制单档放入
sh 与 bash 都是几百 k 你不能跑的理由不是真的不能跑

[nuk]

@james122333 configure 慢不是因为 shell 去 fork 进程慢，而是它为了检测一堆没用到的 api 去不断的去测试 compile ，如果没有 compile 的话应该也是很快的。个人感觉 bash 最缺的就是两个，一个数值系统和一个正则系统，这个 expr 稍微让它多干点都不行，只能动用 bc 或者 dc 。正则的 capture 得挖空心思来弄，用 substitution 吧它只能匹配简单的，其他完全就是各种花式杂耍，什么扩展 grep ，sed 匹配整行替换，awk 调用 match ，perl 还简单点就是宿主机得先装个 perl 。

[james122333]

@nuk

compile 测试是可一定得要的 但没有这阶段还是慢
就是很多 很多套件 configure 都很久
bash 有减单数值计算和 left shift right shift
perl 本来就是另外的大怪物 以前觉得不错 但现在不觉得 大部分用 oneliner 的不会正确用这些指令
oneliner 不适合写脚本 只适合临时操作

[james122333]

bash 还有数值进制转换和位元运算 bitwise
只差没有浮点数

[james122333]

还有没 int64 只能简单运算

[iyeatse]

试过用 ChatGPT 优化吗，效果咋样

[beixiao]

@iyeatse rss