Springを使ったWebアプリ開発
フロント開発未経験でも詳細設計書を書きながら学んだこと【1年間の学び】
この記事では、
・設計書の各項目の役割
・どこに何を書けばいいのか
・初心者でも迷わなくなる整理方法
を、実体験ベースで解説します。
初めてのフロント開発で、先輩に聞くにしても何からどう聞いたらいいのか分からず、1つ1つネットや書籍を調べながら業務を進めていましたが、応用力がなく、とても苦労しました。
同じように悩んでいる方や、先輩に質問しづらい方の助けになればと思い、私の学びを整理してブログにまとめました。
専門的には誤解がある部分もあるかもしれませんが、あくまで 業務を遂行するために私が学んだ理解 としてまとめています。
■私の業務について
現在の現場では、詳細設計書の作成からPTまで担当しています。
今回は、詳細設計書の新規作成をする際に「どういう順番」で「何を書くのか」についてお話します。
詳細設計書の新規作成で最初にぶつかった疑問は次の2つです。
各単語の役割は何か
どこに何を記載すればいいのか
正直に言うと、
最初は設計書が怖かったです。
何を書いても「これで合ってるのかな」と不安で、
単語を見ても意味がつながらない。
でも、
「これは画面の役目」
「これは受付の役目」
「これは処理の役目」
と分けて考えた瞬間、
バラバラだったものが、急につながりました。
設計書は“単語の集まり”ではなく、
役割の分担表だったんだと気づきました。
■詳細設計書の記載事項
以下の12項目を例に説明します。 （Webアプリ開発の設計書で一般的に使われていると思われる項目名を使用しています）
画面構成図
サービス構成図
画面遷移定義
画面パラメータ定義
JavaScript
RestController
Controller
Service
SQL定義
Form項目定義
DTO項目定義
画面用データ項目定義
初心者にとっては、「これって何？」「どこに何を書くの？」が大きな壁でした
■５つの役目に分類
上記の項目には以下の５つのグループに役割が分類されます。
私はこれを意識することで「どこに何を記載するのか」・「この項目にはどんなことを記載するのか」を判断しやすくなりました。
| 役割 | 項目名 |
|---|---|
| 画面の役割 | ・画面遷移定義 ・画面遷移パラメータ定義 ・JavaScript ・Form項目定義 |
| 受付の役割 | ・RestController ・Controller |
| 処理の役割 | ・Service |
| データの出し入れ（保管）の役割 | ・SQL定義 |
| データの入れ物の役割 | ・DTO ・DataBean |
①画面の役割
このグループに分類される項目には「画面に表示されるもの・画面上のものを操作する」ための役割があります。
つまり、「入力する」・「ボタンを押す」・「結果を見る」ことに関する処理を記載します。
上記のことを踏まえると「画面の役割」グループに属する項目は以下のことを記載すれば良いということが分かります。
| 項目名 | 記載内容 | 画面の役割になる理由 |
|---|---|---|
| 画面遷移定義 | ・遷移先の画面の項目名 ・遷移先のURL etc. | 人が操作した結果、どの画面が表示されるかを記載する役割のため ⇒画面上のものを操作する役割にあたる |
| 画面遷移パラメータ定義 | ・画面遷移する際に渡すパラメーター ・画面遷移する条件 etc. | 人がした操作きっかけで何をどこへ渡すかを示す役割があるため ⇒画面上のものを操作する役割にあたる |
| JavaScript | ボタンが押されたときの動き ・入力内容のチェック ・ボタンの表示・非表示の制御 ・ボタンを押せる・押せないの制御 ・受付係（Controller・RestController）への依頼 etc. | 画面を動かす役割があるため ⇒画面上のものを操作する役割にあたる |
| Form項目 | 検索条件になるような以下の項目を記載する。 ・テキストボックスへの入力項目 ・ラジオボタン項目 ・チェックボックス項目 ・hidden項目 ・プルダウン項目 etc. | 入力に関する項目について記載するため ⇒画面上のものを操作する役割にあたる |
②受付の役割
このグループに属する項目には、「画面からのお願いを受け取る」ための役割があります。
つまり、「自分では処理しない」・「次の担当に回す」ための処理を記載します。
上記のことを踏まえると「受付の役割」グループに属する項目は以下のことを記載すれば良いということが分かります。
| 項目名 | 記載内容 | 受付の役割になる理由 |
|---|---|---|
| RestController | ・DataBean → DTO への詰め替え ・Serviceの呼び出し ・Service呼び出しパラメータ ・DTO → DataBean への詰め替え ・JavaScriptへの値の返却 | 画面からの依頼を受け取り、処理へつなぐ役割を持つため ⇒受付の責務にあたる |
| Controller | ・画面項目（検索ワードetc.）をDTOに設定する ・遷移元画面から受け取ったパラメータを DTOに設定する ・Serviceの呼び出し ・DTOを画面（HTMLまたはJavaScript）に返却する | 画面が表示されるときに最初に呼び出され、必要な情報を処理担当へ依頼し、画面に表示する値を準備する役割があるため ⇒受付の役割にあたる |
※RestControllerはJavaScriptに、ContortはHTMLに代わってServiceとやり取りを行うのが
メインですが場合によっては、Serviceから受け取った値を確認してJavaScriptに
返却する値を決めるといったような分岐処理を記載する場合もあります。 ※パラメータ：Serviceがテーブルから値を取得するための検索キーワードのようなもの
③処理の役割
このグループに属する項目には、「受け取った内容をもとに実際の処理を行う」役割があります。
もう少し詳細に言い換えると「計算する」・「条件を判断する」・「データを取得・更新する」ための処理を記載します。
上記のことを踏まえると「処理の役割」グループに属する項目は以下のことを記載すれば良いということが分かります。
| 項目名 | 記載内容 | 処理の役割になる理由 |
|---|---|---|
| Service | ・ControllerやRestControllerから受け取った値をもとに処理を行う ・必要に応じてデータベースからデータを取得する ・取得した結果を整理・加工してDTOに設定する ・データの登録・更新・削除などの処理を行う ・処理結果をControllerやRestControllerへ返却する | どのように処理するかを決め、必要なデータをどこから取得・更新するかを判断する役割があるため ⇒処理の役割にあたる |
④データの出し入れ（保管）の役割
このグループに属する項目には、「必要なデータを出し入れする」ための役割があります。
つまり「どのテーブルを使用するかを決める」・「どの項目を取得・登録・更新するかを定める」ための内容を記載します。
上記のことを踏まえると「データの出し入れ（保管）の役割」グループに属する項目は以下のことを記載すれば良いということが分かります。
| 項目名 | 記載内容 | データの出し入れ（保管）の役割になる理由 |
|---|---|---|
| SQL定義 | ・DAOクラス名 ・DAOメソッド名 ・利用するテーブル名 ・テーブル結合内容 ・抽出条件 ・取得・登録・更新する項目名 ・並び順（必要な場合） | どのテーブルから取得・登録・更新するかを決める役割があるため ⇒データの保管の役割にあたる |
※DAOとは、データベースからデータを取得・登録・更新するためのクラスです。
⑤データの入れ物の役割
このグループに属する項目には、「データを入れて受け渡す」ための役割があります。
「画面から受け取った値を保持する」・「処理結果を次の担当へ渡す」 ための内容を記載します。
上記のことを踏まえると「データを入れて受け渡す」グループに属する項目は以下のことを記載すれば良いということが分かります。
| 項目名 | 記載内容 | データの入れ物の役割になる理由 |
|---|---|---|
| DTO | ・DTOクラス名 ・項目名 ・項目ID ・項目の型etc. | 処理は行わず、データを保持して次の担当へ渡すための箱であるため ⇒データの入れ物の役割にあたる |
| DataBean | ・DataBeanクラス名 ・項目名 ・項目ID ・項目の型etc. | 画面と受付の間でデータを受け渡すための箱であり、自分では処理を行わないため ⇒データの入れ物の役割にあたる |
【補足】
■DTOにはどんな項目を入れるのか
⇒データベースから取得したい項目、JavaScriptに返却したい項目、データベースに登録・更新したい項目、データベースから削除したい項目etc.
■DTOとDataBeanの違い
DTOとDataBeanの２つは、最初は「DTOとDataBeanって何が違うの？」と混乱しました。
でも、“箱はどこで使うのか” を考えたら整理できました。
どちらも基本的にはデータを運ぶための箱です。
ただし、使うタイミング（場所）が違います。
DataBean
⇒JavaScriptとRestControllerの間でデータをやり取りする際に使います
DTO
⇒ControllerまたはRestControllerがServiceとやり取りするデータを入れるために使います。 RestControllerでは、JavaScriptからDataBeanに入れて送られてきたデータを
DTOに詰め替えてServiceに送ります。また、ServiceからDTOに入れられて送られてきた
データをDataBeanに詰め替えてJavaScriptにデータを送ります。
⑥その他
役割は５つと説明しましたが、「画面遷移定義」・「サービス構成図」の２つに関しては
上記の５つの役割とは別物となります。
なぜなら、この２つは処理の中身を書く場所ではなく「誰がどの順番で動くか」を整理する役目を持つからです。
では、何を記載するのかとういうと以下のような内容を記載します。
どの受付が呼ばれるか
どの処理担当が動くか
どのデータ取得担当を使うか
どのデータの箱を使うか
といった、処理の“つながり”をまとめる設計図です。
■まとめ
以上が、私が詳細設計書を作成する時に、学び気づいたことになります。
設計書は、ただの資料ではありません。
「誰が何を担当するのか」を決める設計図です。
もし今、 「何を書けばいいのか分からない」と悩んでいる人がいるなら、
まずはこう問いかけてみてください。
これは 画面の役目？ 受付の役目？ 処理の役目？ データの役目？ 入れ物の役目？
役割で分けて考えると、 不思議と霧が晴れていきます。
私も、そこからやっと “設計書を書く側”になれた気がしました。
