运维必知必会：Bash Shell 脚本的实践指南

FYIRH · 发表于 2021-12-26 23:22:48

本帖最后由 FYIRH 于 2021-12-26 23:47 编辑

前言

与其它的编码规范一样，这里所讨论的不仅仅是编码格式美不美观的问题，同时也讨论一些约定及编码标准。这份文档主要侧重于我们所普遍遵循的规则，对于那些不是明确强制要求的，我们尽量避免提供意见。

为什么要有编码规范

编码规范对于程序员而言尤为重要，有以下几个原因：

一个软件的生命周期中，80%的花费在于维护
几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护
编码规范可以改善软件的可读性，可以让程序员尽快而彻底地理解新的代码
如果你将源码作为产品发布，就需要确任它是否被很好的打包并且清晰无误，一如你已构建的其它任何产品
编码规范原则1 N- y# v4 }$ Z. \
+ a; a6 G+ w3 B* l6 _' ?* u( v

本文档中的准则致力于最大限度达到以下原则：

正确性
可读性
可维护性
可调试性
一致性
美观
- }' z3 x0 u. j; ^: S% B5 R; p% O3 Q2 ^4 I

尽管本文档涵盖了许多基础知识，但应注意的是，没有编码规范可以为我们回答所有问题，开发人员始终需要再编写完代码后，对上述原则做出正确的判断。

代码规范等级定义

可选（Optional）：用户可参考，自行决定是否采用；
推荐（Preferable）：用户理应采用，但如有特殊情况，可以不采用；
必须（Mandatory）：用户必须采用（除非是少数非常特殊的情况，才能不采用）；

7 A0 E, x4 ^% U, D

注：

未明确指明的则默认为必须（Mandatory）

主要参考如下文档:

Google Shell Style Guide
Bash Hackers Wiki

: ?. m, E/ o0 ^' m' o+ t* h

源文件

基础

使用场景

仅建议Shell用作相对简单的实用工具或者包装脚本。因此单个shell脚本内容不宜太过复杂。

在选择何时使用shell脚本时时应遵循以下原则：

如主要用于调用其他工具且需处理的数据量较少，则shell是一个选择
如对性能十分敏感，则更推荐选择其他语言，而非shell
如需处理相对复杂的数据结构，则更推荐选择其他语言，而非shell
如脚本内容逐渐增长且有可能出现继续增长的趋势，请尽早使用其他语言重写
$ d, S& a/ t$ h3 K

0 v0 O# l# [; u2 J1 L文件名

可执行文件不建议有扩展名，库文件必须使用.sh作为扩展名，且应是不可执行的。

执行一个程序时，无需知道其编写语言，且shell脚本并不要求具有扩展名，所以更倾向可执行文件没有扩展名。

而库文件知道其编写语言十分重要，使用.sh作为特定语言后缀的扩展名，可以和其他语言编写的库文件加以区分。

文件名要求全部小写, 可以包含下划线_或连字符-, 建议可执行文件使用连字符，库文件使用下划线。

正例:

反例：

3 i/ U, a7 K) _; r l2 \5 O
文件编码

源文件编码格式为UTF-8。避免不同操作系统对文件换行处理的方式不同，一律使用LF。

单行长度

每行最多不超过120个字符。每行代码最大长度限制的根本原因是过长的行会导致阅读障碍，使得缩进失效。

除了以下两种情况例外：

导入模块语句
注释中包含的URL% m9 }2 v9 f, t% M

如出现长度必须超过120个字符的字符串，应尽量使用here document或者嵌入的换行符等合适的方法使其变短。

示例：

空白字符

除了在行结束使用换行符，空格是源文件中唯一允许出现的空白字符。

字符串中的非空格空白字符，使用转义字符
不允许行前使用tab缩进，如果使用tab缩进，必须设置1个tab为4个空格
不应在行尾出现没有意义的空白字符
. `2 N% c$ g& K2 E, ?1 }& C

垃圾清理(推荐)

对从来没有用到的或者被注释的方法、变量等要坚决从代码中清理出去，避免过多垃圾造成干扰。

结构

使用bash

Bash 是唯一被允许使用的可执行脚本shell。

可执行文件必须以 #!/bin/bash开始。请使用set来设置shell的选项，使得用bash <script_name>调用你的脚本时不会破坏其功能。

限制所有的可执行shell脚本为bash使得我们安装在所有计算机中的shell语言保持一致性。正例：

反例：

许可证或版权信息(推荐)

许可证与版权信息需放在源文件的起始位置。例如：

缩进

块缩进

每当开始一个新的块，缩进增加4个空格（不能使用\t字符来缩进）。当块结束时，缩进返回先前的缩进级别。缩进级别适用于代码和注释。

管道

如果一行容不下整个管道操作，那么请将整个管道操作分割成每行一个管段。

如果一行容得下整个管道操作，那么请将整个管道操作写在同一行，管道左右应有空格。

否则，应该将整个管道操作分割成每行一段，管道操作的下一部分应该将管道符放在新行并且缩进4个空格。

这适用于管道符 | 以及逻辑运算 || 和 &&。正例：

反例：

循环

请将 ; do , ; then 和 while , for , if 放在同一行。

shell中的循环略有不同，但是我们遵循跟声明函数时的大括号相同的原则。即：; do , ; then 应该和 while/for/if 放在同一行。else 应该单独一行。结束语句应该单独一行且跟开始语句缩进对齐。

正例：

反例：

case语句

通过4个空格缩进可选项。可选项中的多个命令应该被拆分成多行，模式表达式、操作和结束符 ;; 在不同的行。

匹配表达式比 case 和 esac 缩进一级。多行操作要再缩进一级。模式表达式前面不应该出现左括号。避免使用 ;& 和 ;;& 符号。示例：

只要整个表达式可读，简单的单行命令可以跟模式和 ;; 写在同一行。当单行容不下操作时，请使用多行的写法。单行示例：

函数位置

将文件中所有的函数统一放在常量下面。不要在函数之间隐藏可执行代码。

如果你有函数，请将他们统一放在文件头部。只有includes， set 声明和常量设置可能在函数声明之前完成。不要在函数之间隐藏可执行代码。如果那样做，会使得代码在调试时难以跟踪并出现意想不到的结果。

主函数main

对于包含至少了一个其他函数的足够长的脚本，建议定义一个名为 main 的函数。对于功能简单的短脚本， main函数是没有必要的。

为了方便查找程序的入口位置，将主程序放入一个名为 main 的函数中，作为最底部的函数。这使其和代码库的其余部分保持一致性，同时允许你定义更多变量为局部变量（如果主代码不是一个函数就不支持这种做法）。文件中最后的非注释行应该是对 main 函数的调用：

注释

代码注释的基本原则：

注释应能使代码更加明确
避免注释部分的过度修饰
保持注释部分简单、明确
在编码以前就应开始写注释
注释应说明设计思路而不是描述代码的行为
注释与其周围的代码在同一缩进级别，#号与注释文本间需保持一个空格以和注释代码进行区分。) N9 p+ C- _2 g

8 K* `7 z8 Q g. f$ Y/ ~
文件头

每个文件的开头是其文件内容的描述。除版权声明外，每个文件必须包含一个顶层注释，对其功能进行简要概述。

例如：

功能注释

主体脚本中除简洁明了的函数外都必须带有注释。库文件中所有函数无论其长短和复杂性都必须带有注释。

这使得其他人通过阅读注释即可学会如何使用你的程序或库函数，而不需要阅读代码。

所有的函数注释应该包含：

函数的描述
全局变量的使用和修改
使用的参数说明
返回值，而不是上一条命令运行后默认的退出状态
0 ~! B( R6 m) U, c2 I
9 R) n$ p" P! n3 U

例如：

TODO注释

对那些临时的, 短期的解决方案, 或已经够好但仍不完美的代码使用 TODO 注释.

TODO 注释要使用全大写的字符串 TODO, 在随后的圆括号里写上你的名字,邮件地址, bug ID, 或其它身份标识和与这一 TODO 相关的 issue。

主要目的是让添加注释的人 (也是可以请求提供更多细节的人) 可根据规范的TODO 格式进行查找。添加 TODO 注释并不意味着你要自己来修正,因此当你加上带有姓名的 TODO 时, 一般都是写上自己的名字。这与C++ Style Guide中的约定相一致。

例如：

命名

函数名

使用小写字母，并用下划线分隔单词。使用双冒号::分隔包名。函数名之后必须有圆括号。如果你正在写单个函数，请用小写字母来命名，并用下划线分隔单词。

如果你正在写一个包，使用双冒号 :: 来分隔包名。函数名和圆括号之间没有空格，大括号必须和函数名位于同一行。当函数名后存在 () 时，关键词 function 是多余的，建议不带 function 的写法，但至少做到同一项目内风格保持一致。正例：

反例：

变量名

规则同函数名一致。

循环中的变量名应该和正在被循环的变量名保持相似的名称。示例：

常量和环境变量名

全部大写，用下划线分隔，声明在文件的顶部。

常量和任何导出到环境中的变量都应该大写。示例：

有些情况下首次初始化及常量（例如，通过getopts），因此，在getopts中或基于条件来设定常量是可以的，但之后应该立即设置其为只读。值得注意的是，在函数中使用 declare 对全局变量无效，所以推荐使用 readonly 和 export 来代替。示例：

只读变量

使用 readonly 或者 declare -r 来确保变量只读。

因为全局变量在shell中广泛使用，所以在使用它们的过程中捕获错误是很重要的。当你声明了一个变量，希望其只读，那么请明确指出。示例：

局部变量

每次只声明一个变量,不要使用组合声明，比如a=1 b=2;

使用 local 声明特定功能的变量。声明和赋值应该在不同行。

必须使用 local 来声明局部变量，以确保其只在函数内部和子函数中可见。这样可以避免污染全局名称空间以及避免无意中设置可能在函数外部具有重要意义的变量。

当使用命令替换进行赋值时，变量声明和赋值必须分开。因为内建的 local 不会从命令替换中传递退出码。正例：