エンジニアの知識

シェルスクリプトの設計書とは?必要な項目や書き方等を解説!

2020年5月16日

一般的にシェルスクリプトの大半は、運用ツールとしての処理が主な用途となります。大抵の処理は「起動・停止・状態表示」や「リソースチェック」「夜間バッチ処理」等の単発処理となるため、設計書と言う観点ではかなり軽視されがちです。

シェルスクリプトはOSの組み込みコマンドを駆使することで、非常に有用なツールとなります。一言で表すならば「かゆいところに手が届く」ため、運用上欠かすことは出来ません。

ところが、私の経験的に7割近くのプロジェクトが、「運用ツール(シェルスクリプト)」設計書のメンテナンスが出来ていません。出来ていないどころか、シェルスクリプトの一番上にコメントで用途を記述して終わらせている場合が実に多い・・

極めつけが、シェルスクリプト名に「db0001.sh」など、番号で付与されている場合、ファイルを開いて中身を確認する以外に用途が全く推測できず、障害対応以前にシェルスクリプトの解析から入ることになってしまいます。

この記事では、シェルスクリプトの設計書について、必要な項目や書き方等を解説します。

シェルスクリプト設計書とは

シェルスクリプト設計書は、主に2つの役割があります。

シェルスクリプト設計書の役割

  • 運用設計を行う上で、必要なルールを決定する
  • システム運用に必要な機能を実現するための方法を定義する

なお、シェルスクリプト設計書に、統一された書式や形式はありません。

シェルの設計に必要な項目

シェル設計書に記載する内容例

  • 標準規約類
    • ディレクトリ構成
    • スクリプト命名規約
    • コーディング規約
  • 機能概要
  • 属性仕様
  • 処理詳細
  • 個別仕様

標準規約

ディレクトリ構成」や「スクリプト命名規約」「コーディング規約」等、複数のエンジニアが参画するプロジェクトにおいて、一定の品質を担保するために定める標準規約を作成します。標準規約は、スクリプト毎に作成するものではなく、プロジェクト単位で作成されます。

ディレクトリ構成

ディレクトリ構成とは、運用ツール開発において、予め用途ごとにファイルシステム内に作成するディレクトリを決定することを指します。

ディレクトリ構成例(Beエンジニア)

  • BASE_DIR
    • scripts
      • bin(実行スクリプト格納場所)
      • com(共通スクリプト格納場所)
      • etc(設定ファイル等の格納場所)
      • log(スクリプト実行ログの格納場所)
      • rep(出力レポート等の格納場所)
      • tmp(テンポラリ領域)

ディレクトリ構成は、一旦プロジェクトへリリースしてしまうと、おいそれとは変更できません。後々になって変更すると、ソース内部のパス等がズレてしまうため、システム自体が正常に動作しなくなってしまう可能性があります。予めきっちりと構成を決定しておくことが重要です。

スクリプト命名規約

命名規約とは、プログラミングを行う際にソースコード上の識別子の名称となる文字列や、ソースファイル自体の名前を決定するためのルールを定めたものを指します。

スクリプト名及び、関数に関する命名規約(例

先頭ワードは、目的を表す単語から始まり、後に対象や用途をキャメルケースにて記述する。

目的を表す単語の例

 ワード 意味 記述例
is 有効・無効を表わすもの isProcAlive、isPortAlive
get 情報やモノ取得を表すもの getName、getTarget
exec 実行を表すもの execBackup、execSnap
mk 作成を表すもの mkDir
rm 除去を表すもの rmDir

コーディングフェーズ前までにワードをすべて出し切るかは、プロジェクトによりマチマチです。多くのプロジェクトでは、それまでに蓄積された既存資産があるはずなので、流用することが一般的です。

変数に関する命名規約(例

すべての変数は、スネークケースを使用する。

  • 定数及びグローバル変数
    定数及び、グローバル変数はすべて大文字にて記述する。
    例)SCRIPT_NAME、BASE_DIR
  • ローカル変数
    例)proc_cnt、file_name

コーディング規約

コーディング規約とは、ソフトウエア開発において、プログラムコーディングにおける統一的なガイドラインを指します。「可読性」や「保守性」を高めるメリットがあります。

コーディングエリア(例

ソースコードは、下記の指定された領域へ、それぞれ用途ごとに正しく記述すること。

  • シェバン
  • プログラム概要
    • バージョン、作成日、仕様方法、説明、設計書の所在
  • 変数の宣言領域
  • 関数を記述する領域
  • 事前処理ロジックを記述する領域
  • メイン処理ロジックを記述する領域
  • 事後処理ロジックを記述する領域

#!/bin/sh
#_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
#
# ver.1.0.0 yyyy.mm.dd
#
# Usage:
#     仕様方法を記述
#
# Description:
#   スクリプトの説明を記述
#
# 設計書
#   設計書の所在を記述
#
#_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/

# ----------------------------------------------------------
# 変数の宣言領域
# ----------------------------------------------------------
# ----------------------------------------------------------
# 関数を記述する領域
# ----------------------------------------------------------
# ----------------------------------------------------------
# 事前処理ロジックを記述する領域
# ----------------------------------------------------------
# ----------------------------------------------------------
# メイン処理ロジックを記述する領域
# ----------------------------------------------------------
# ----------------------------------------------------------
# 事後処理ロジックを記述する領域
# ----------------------------------------------------------

制御文「if」(例

制御文で使用する「test」コマンドについては、可読性の観点から下記の記述法を使用する。

正)

if [ 条件文 ]; then
  コマンド1
else
  コマンド2
fi

誤)

[ 条件文 ] && コマンド1 || コマンド2

上記は、あくまでも1例にすぎません。上記で挙げた以外にも、「case」の使いどころや、引数の判定は「getOpts」を使用する、ログ出力シスログ出力ループの作法など、細かく決定していきます。

機能概要

概要設計は、実装するべき機能の目的及び、概要を解り易く簡潔に記述します。ここでズラズラと役所チックに文章を記述すると、だれも見ない設計書になってしまいます。ましてや、シェルスクリプト設計書を必要とする場合は、きわめて緊急性を要する場合が多い為、一目で把握できるレベルで記述することが大事です。

機能概要の記述例

例)ダンプバックアップの場合
外部ファイルで指定されたファイルシステム単位にダンプを取得し、引数で指定されたディレクトリへ退避する。

属性仕様

プロジェクトごとに呼び方は変わると思いますが、この属性設計では、スクリプトファイル名や記述言語等、作成するシェルスクリプトの属性に関わる情報を記述します。

記述する項目としては下記の詳細になります。

属性設計への記述項目

  • 記述言語
    • sh (sh,bash,ksh)
    • ps1
  • 実行ユーザー
    • 特権ユーザー
    • 一般ユーザー
  • 種別
    • リソースファイル(関数/変数/定義)
    • 実行スクリプト
    • サブスクリプト
    • ラッパースクリプト
  • 言語環境
  • 起動方式
  • 多重起動制御
  • ログ出力方式
  • シグナル制御
  • 異常検知方式
  • 終了方式
  • 終了コード
  • リラン可否
  • 個別設定有無
  • etc・・

この「属性仕様」セクションは非常に重要です。障害発生時に一番初めに知りたい情報がここにちりばめられています。

例えば「種別」なら、このシェルスクリプトは単独実行するのか、他のスクリプトから呼び出されるサブスクリプトなのか・・等で対応範囲が即座に判断できます。

また「リラン可否」の項目では、障害復旧時の現状回復に取る処置は、「単純リラン」で良いのか、エンジニアの判断が必要なのか・・等、俯瞰的に見て取ることが可能となります。

処理詳細

処理詳細には、作成するシェルスクリプトの処理内容を下記の観点毎に文章で記述します。

処理詳細の記述観点

  • 初期処理
    • リソースファイルの読み込み等を記載
    • ログ出力有無やレベル等を記載
  • 事前処理
    • 定数・変数宣言等を記載
    • 関数などを記載
    • ログ出力有無やレベル等を記載
  • 主処理
    • ビジネスロジック内容を記載
    • ログ出力有無やレベル等を記載
  • 事後処理
    • 一時ファイルの削除等、事後処理内容等を記載
    • ログ出力有無やレベル等を記載

処理詳細の記載レベルは、プロジェクトによって異なります。最近は少なくなりましたが、行数やインデントなどをすべてを作成するスクリプトと一致させて記述することを求められることもあります。

個別仕様

個別仕様では、そのシェルスクリプトが他のスクリプトと異なる仕様を記述します。例えば、引数の内容や参照する外部ファイル等、作成するシェルスクリプト固有の情報を記述します。

個別仕様記述項目例

  • 引数情報
    引数 パラメータ 必須/任意 設定値
    -s 取得元パス 必須 対象ファイルシステム
    -d 退避先パス 必須 出力ダンプ退避先パス
  • 参照ファイル情報
    ファイル名(物理) ファイル名(論理) 概要説明
    com_func.sh 共通関数定義ファイル 各スクリプトで使用する関数が定義されたファイル
    dump_fs.target ダンプ取得対象リスト ダンプバックアップの対象FSが定義されたファイル
  • 設定ファイル記載書式
    #デバイス名,ファイルシステム名,スナップサイズ  値の間は半角スペース
    /dev/root_vg/lv_jboss /opt/jboss 10GB
    /dev/root_vg/lv_data /oracle/data 30GB

  • 出力イメージ
    ∟<hostname>_jboss.tar.gz
    ∟<hostname>_data.tar.gz
    ∟<hostname>_df.txt
    ∟<hostname>_fdisk.txt
    ∟<hostname>_lv.txt
    ∟<hostname>_pv.txt
    ∟<hostname>_vg.txt

  • チェック項目
    • 引数チェック
    • ダンプ取得対象リスト存在チェック
    • 退避先パス存在チェック

実際のプロジェクトでは、現場毎でノウハウが蓄積されています。実際のスクリプト設計書は、プロジェクトの方針に従って作成してください。

よく読まれている記事

1

目次1 Shellとは?1.1 代表的なシェルの種類2 シェルスクリプトの違いとは? Shellとは? Shellとは、人間の理解できる言葉を機会へ伝えるプログラムです。 Linux環境でコマンドプロ ...

2

Linuxは主にサーバー用として利用されるOSです。大規模な基幹システムの開発者、ロボットや家電開発等の組み込み系エンジニア、ネットワーク機器やデータベースに携わるインフラエンジニアは触れることが多い ...

3

プログラミング言語を習得しようと思った時、必ずと言っていいほど候補として挙げられるのが「Java」というプログラミング言語です。 「Java」は、現在日本で最も使われている言語であり、非常に人気のある ...

4

この記事は、Linuxについて勉強している初心者の方向けに「Shellスクリプト」について解説します。最後まで読んで頂けましたら、Shellスクリプトはどのような役割を担っているのか?を理解出来るよう ...

-エンジニアの知識

Copyright© Beエンジニア , 2020 All Rights Reserved.