1、shell 编程规范第 1 页Shell 编程规范v1.0.0 2018-09-29 目录一、 命名规范 .21、 版本和运行参数 .22、 变量命名 .23、 函数命名 .34、 脚本(模块)命名 .35、 临时文件的命名 .3二、 代码风格 .41、 代码框架 .42、 函数 .43、 条件语句与循环 .44、 缩进 .5三、 注释规范 .51、 文件/模块说明 .52、 重要函数说明 .63、 其它 .6四、 日志规范 .6五、 接口文件规范 .7六、 配置规范 .71、 配置文件 .72、 配置项的检查 .8七、 报警规范 .8八、 其它细节 .8九、线上实例补充 .10shell 编
2、程规范第 2 页一、命名规范1、 版本和运行参数1) 脚本开始之前以注释形式说明版本号；（推荐）2) 如果调用其他工具，还需说明工具的版本号；（推荐）3) 为脚本添加必须的运行参数，类似于 C 程序的运行参数，可使用 getopt 的方式取得运行参数值，如基本的参数有：-v - 版本号；-h 帮助信息；(推荐)2、 变量命名1) 变量命名要前后统一，建议使用全部大写字母，如 APACHE_ERR_NUM;语义要清晰，能够正确表达变量的含义，过长的英文单词可采用前几个字符代替。多个单词连接使用“_”号连接, 引用时，必须以$APACHE_ERR_NUM方式引用；2) 避免无含义字符或数字: 例如
3、下面的数字 22, 并不知道其确切含义.COUNT=grep keywords fileif $COUNT ne 22 thenDo Somethingfi3) 全局变量和局部变量：i. 如需要使用全局变量，则在变量加前缀 g，如 g_WORK_DIR，在变量使用时，使用将其括起,即$VARIABLEii. 局部变量的使用：脚本在定义在一个函数(function)中的变量我们称之为局部变量，必须要以 local 方式进行声明，使之只在本函数中作用有效，以免造成在函数中的命名与程序中变量重名，造成对程序中正常变量的不正常操作。如function TestFunc()local ifor(i=0;
4、i $TMP_FILE.shell 编程规范第 4 页#endrm $TMP_FILE二、代码风格1、 代码框架1) 解释器声明最好为 #!/bin/sh（推荐） ，如果不是再加入 crontab 计划任务时要格外注意执行环境。配置文件/库函数的引用 source foo_conf.sh2) 主过程只实现程序主干，功能实现应该封装在子函数中；3) 对于能独立执行的脚本需要有 usage 和 version 函数，可以输出脚本用法和版本信息（推荐）2、 函数1) 函数定义时在函数名前加上 function 保留字2) 显示函数返回：在函数的每个分支在函数的每个分支都包含显示的 return语句，
5、并跟上返回值。即使是不关心返回值的函数，也可能在后续调用时无意的去判断它的返回值并进行一系列动作，这种不必要的麻烦我们在一开始就应该注意，显示的写 return 语句并不会带来多少负担，相反的，它能让函数逻辑更加清晰和严谨。3、 条件语句与循环1) 在使用条件语句及循环时，尽量使用统一格式，而不是使用“;”分隔；if -d abc thenDo somethingfiwhile 1 doDo somethingdonefor i in *doDo somethingshell 编程规范第 5 页Done2) 尽量使用每一行一条语句，而不是使用”;”将多个语句隔开。尽可能多的判断操作是否成功，并
6、对其进行相应处理，如 DoSth BB #! FILEIN: data/url.crawl#! 由 dedup_crawl.sh 生成 , 格式为 . #! FILEOUT: result/GOOD_GRP#! 通过检测的无问题 alias 组 #! FILEOUT: result/WRONG_GRP#! 未通过检测的有问题 alias 组 #! DEP: wget 1.10.2 #! DEP: lftp 3.0.6 #! PREV: dedup_crawl.sh #! NEXT: dedup_update.sh 注释中的路径给出的相对路径都必须是相对于该模块安装时生成的根目录。example
7、:模块 seek_url 安装在 PATH 目录下，安装后生成了新的目录 seek_url，那么所有的相对路径都是相对于 PATH/seek_url/的。推荐为脚本的配置和在处理流程中位于本脚本之前和之后的脚本写注释。以便于测试和新人熟悉模块流程。 （推荐）example:#! conf conf/config_dedup_check.sh#! dedup-check 的模块范围的配置文件#! 这里主要读取 BINPATH 和 ALIAS_FILE 设置处理流程中在本脚本之前的脚本名#! prev dedup_crawl.sh处理流程中在本脚本之后的脚本名#! next dedup_updat
8、e.sh所有脚本都要在脚本或配置文件中写明：依赖的模块、工具、脚本 （必须）example:#! dep spuser-ftool#! 简要说明#! dep read_di#! 简要说明2、 重要函数说明对于重要函数，需说明函数用途，参数，返回值，作者，版本，格式也不做强制要求，可如下：#! TODO: get hostname #! AUTHOR: somebody #! VERSION: 1.0 #! IN: $1 = ip #! IN: $2 = port #! OUT: 0 = success; 1 = failure 3、 其它脚本中一定要有十分详细的注释，包括变量的定义，函数的定义
9、，返回值的函义，每步操作的目的等，这方面尤其要加强。注释尽量使用标准的英文或是详细的shell 编程规范第 7 页中文说明。四、日志规范1. 脚本和 C 程序一样，需要有日志记录脚本的运行状态，操作过程等。推荐：每条日志要以记录的当前时间为开头，然后是记录的日志描述信息，描述信息要包括日志的级别，如 FATAL，WARNING，NOTICE 等，还要保留充分完整，无歧义的上下文信息，尤其是 FATAL 和 WARNING 日志更是如此。2. 每个脚本程序要有自己的日志文件，不要将多个脚本的日志记录到同一个日志文件中，即使这些脚本之间有依赖关系也不可以。五、接口文件规范1. 所有模块之间的接口文
10、件必须在生成的同时生成 md5 校验码，并且一个文件对应一个 md5 文件，md5 文件的命名为接口文件名后加上“ .md5”。2. 机器之间的数据拷贝推荐使用 wget，尽量减少 scp 和 ssh 的使用。但是只要是wget 获取远程数据，必须使用 md5 校验数据的完整性。3. 推荐所有接口文件都进行格式检查，对空文件和不存在的文件判断方式应该一致。4. 推荐接口文件最好有相应的 flag 文件指明生成时间，以便检查和容错。六、配置规范在多个脚本程序协同工作时，应该尽量使用公共函数库来完成近似的功能，使用配置文件统一变量及外部数据的引用，这样便于日后的功能升级及环境的变更操作。如果使用了
11、公共函数库，建议在配置文件中添加公共函数库脚本的路径，即使是在当前目录下也要进行配置，如 FILENAME_PATH=”./”，脚本中的公共函数库及配置文件使用 source $FILENAME_PATH/filename.sh 方式加载。1、 配置文件1) 所有的脚本必须把功能和配置明确分开；2) 配置文件，以 conf_脚本名.sh 来命名（推荐）；3) 原则上，配置项放在目录 conf/底下，引用时通过 source conf/conf_spdata.sh 的形式加载；4) 配置项的命名规范与变量命名规范相同，要求所有的配置项应都有值，避免内容为空的配置项出现，配置项的内容由双引号括起，
12、如：OUTPUT_FILE_PATH=”./output”shell 编程规范第 8 页5) 路径参数的配置：脚本中经常需要配置路径，本地路径或者远程机器的路径。路径的配置强烈推荐使用全局路径，全局路径的配置建议以“/”开头，末尾没有“/”，脚本中使用路径的配置项时，必须以 “/”分隔不同的配置项，变量或通配符等，不可以省略“/”。6) 易变参数的配置：易变参数中主要是指状态报告和报警的收件人，都必须写成配置。7) 机器名，端口和用户名引用：所有线上脚本都必须通过配置引用机器名、端口和用户名等信息。8) 二进制程序引用：当模块中需要调用非本模块维护的二进制程序/脚本时，都必须通过一个可配置的路
13、径来间接引用，禁止直接复制其它模块的二进制程序到自身目录使用。2、 配置项的检查1) 脚本中要检查配置项是否为空，尤其是一些重要的，影响下面脚本正常运行的配置项，必须要进行是否为空的检查，避免配置文件中有遗漏等错误，检查格式可如下：if -z $OUTPUT_FILE_PATH thenDo something, such as write logfi七、报警规范1) 报警邮件的标题（和短信报警）必须为如下格式：报警级别 服务名 机器名 模块名 报警信息 时间 Example:echo “errorimage$(hostname -s)$0 urlmerge for group $group_
14、no failed $(date +%Y-%m-%d %H:%M:%S)“2) 报警邮件的发件人必须真实，报警短信必须包括发件机器名。不容许在 A 机器上发出以 B 机器名义的报警，推荐使用 hostname 命令3) 线上模块报警邮件（或短信）的收件人必须包括模块负责人，指导人，op，禁止将模块报警（或短信）发给全组。 每个包含信息相同的报警原则上不得多于 3 条。（必须）八、其它细节shell 编程规范第 9 页1) 涉及依赖的机器，需以配置的形式出现在脚本的配置文件；禁止在脚本中随处定义机器，这样不易于维护，也容易出错； （必须）2) 必须要有基本的日志输出；（必须）3) 要关注脚本的效
15、率和系统消耗，综合、平衡的考虑；（必须）4) 函数参数传递：在调用函数时，向函数传递的参数如果是以变量的方式进行传递，必须使用双引号将变量括起，这是为了防止某个变量中含有多个以空格分隔的字段，导致函数误认为是多个参数，如报警邮件和报警短信的配置项，使用方式如下：Alert “some thing” “$LOG” “$ALERT_MAIL” “$ALERT_MOBILE”5) 避免 cat 大文件。比如 for id in cat id_file;do ;done。而是采用readline 形式读入文件。(必须)6) 所有上一级命令需用 if $? 来判断返回值，对于异常分支，需有相应的处理策略
16、：或是打印 warning 日志，或是报警退出/重试。（必须）7) Sort 超过 1G 的数据文件时，必须用-T 指定其临时文件夹，推荐在使用到sort 的时候就使用-T 指定到自身的 TMP 目录。（必须）8) 避免使用大的 while/for 循环，如果实在需要，请考虑用 awk 命令替代。（推荐）9) 需要配置 crontab 的脚本，要注意 crontab 的时间可能会有前后 1 分钟之内的波动，对于时间精度要求较严格的脚本，不建议配置在比如 00 分钟这样的时刻。10) 对于一系列有严格依赖关系的命令，建议使用 & 来处理，比如：make mydir & mv myfile myd
17、ir；并且对于有前后次序的脚本，禁止采用后台运行 & 命令。(推荐)11) 脚本运行前后，注意清除过期数据（上次运行生成的数据）（推荐）12) 脚本开始运行之前需明确当前运行路径，例如 cd /home/img/img；同时必须明确数据生成路径，例如 data/spdata_stat/splendid.list；（必须）13) 对于功能较为复杂的脚本，考虑使用一些函数对功能点进行封装。这样可以使脚本清晰易读；（推荐）14) 任何出错情况必须将出错信息打印到日志中；严重的错误必须以邮件或短信报警的形式发出。（必须）15) 对于逻辑比较复杂的脚本，可以使用 set -x 来打印命令执行情况，便于调
18、试和排错 （推荐）16) wget 之前，注意先删除本地文件；（推荐）shell 编程规范第 10 页17) 拷贝比较大的文件时，最好先将文件 cp 到一个临时文件夹，然后 mv 到目标文件夹。这样可以避免下游模块读取到了不完整的文件。（推荐）18) mv，cp 等命令，注意要使用 r f 等递归和强制命令（必须）19) 脚本中，要注意对单引号双引号“”的转义。不明确转义含义的，最好在单元自测的时候多加小心。（推荐）20) 使用 paste 命令的时候，注意分清楚，文件是使用 tab 还是空格作分隔符。21) 使用 ps axuw|grep 来获取信息时，注意 ps 打印的最大宽度。建议多打几
19、个w，例如 ps axuwwww|grep ；(推荐)22) 使用 sort，uniq，join，comm 等命令时，要注意两点：1，是否要求排序（例如 uniq，join，comm 要求输入文件是排好序的）；2，如果排序，要求以什么方式排序（例如，comm 要求输入文件是字典序的，而不是数值序）；（推荐）23) 字段匹配日志的时候，要注意特殊字符，例如 spurlstargirlsspid2534969opusr stargirlsopuid6545440，这样的日志，如果只使用 和作分隔符，就会有问题，因为 spurl 中就可能含有或等特殊字符，从而导致后面的匹配全部出错。24) 对特殊信
20、号的处理：在脚本运行时，我们有时会临时中断此脚本(ctrl+c)，如果脚本在做多个文件操作，并生成一些临时文件，那么我们在中断脚本时，就需要恢复或清除一些过程文件。在复杂脚本中，要对一些中止的信号进行特殊的处理。九、线上实例补充登陆到 build1 系列机器的/home/img/img/shell 目录下，分别查看urlmerge.sh、rebuild_linkdb.sh 和 urlfilter.sh 三个脚本，其中带日期的版本是修改前的，不带日期的是修改后的。$ vimdiff urlmerge.sh urlmerge.sh.20080819 可得出：1 调用发送邮件函数时需要注意参数的正确
21、引用，以避免程序或脚本出问题不能收到报警；$ vimdiff rebuild_linkdb.sh rebuild_linkdb.sh.20080819 可得出：1 对于脚本的运行异常和退出 应该有报警；2 脚本结束时发送邮件内容应该正确，以进行进度和问题跟踪；$ vimdiff urlfilter.sh urlfilter.sh.20080819 可得出：shell 编程规范第 11 页1 切换目录操作时应有异常处理，避免可能引发的问题；2 常用的数字和文件名字应该以配置参数的形式给出； 3 作 md5 和解校验 md5 时应有异常分支处理；登陆到 build2 系列机器的/home/img/img/shell 目录下，查看脚本 tntransfer.sh，logSH 目录下应有脚本运行日志；Tntransfer.sh 中 test_download_ok 函数可以添加检查 wget 本次下载的那些文件是否成功的功能；wget_log 日志数据不应删除，thumbnaildict.*.md5 文件也应保留。并且日志数据应放在适当的目录下，便于环境统一。tntransfer 脚本尚未修复，请 RD 给出排期。
