LoginSignup
32
10

More than 1 year has passed since last update.

WanoグループAdvent Calendar 2022Day 7wano-inc
@shibe_inWano株式会社

機能設計のコミュニケーションには図を使おう！エディタで作れるよ！

Last updated at Posted at 2022-12-06

昨日の@wanomaedaさんの福利厚生編に引き続きまして、Wano Group Advent Calendar 2022の7日目の記事となります。
（子持ちではないのですが自分も弊社制度に助けられてます！子育てだけでなくただ生きることに対しても非常に有効です◯）

更新履歴

  • 2022.12.07 初稿
  • 2022.12.09 更新履歴を追加
  • 2022.12.26 各図面の説明を追加

ネタバレ

以下の図面は大変便利な上にテキストエディタがあればつくれるよ！
図面を書いてレッツコミュニケーション！

:bar_chart: 特に役に立った図面

  • シーケンス図：クライアント・サーバ・DBの通信の流れを書くのに便利！
  • ER図：DBのテーブル構成を書くのに便利！

:pencil: 使えるエディタ（ほかにもあるよ！）

  • Visual Studio Code
  • Notion

はじめに

こんにちは！@shibe_ です。TuneCore Japanでバックエンドエンジニアをしています。
今年の3月にTuneCore Japanに入り（採用に至るまでの経緯などはこちら）、わちゃわちゃと実装してきた中で役立ったツールを紹介します。

:wrench: 今年実装した機能

Tunecore Japanの以下の機能について実装しました（ひとりで実装しきったわけではないです）。

:bell: お知らせ通知改善

ユーザへのお知らせはWebサービスと切っても切れない関係にあり、例にもれずTuneCore Japanでも通知をユーザにたびたび送っています。
そんな通知ですが、これまでは通知の詳細を開かないと「通知バッヂ」が消えない状態でした。
image.png
↑ Webサービスあるある 「通知バッヂカンスト」

しかし、「通知バッヂ」の寿命を「通知の詳細を開くまで」から 「通知の一覧を開くまで」 に変更しました。
これによって新着の通知がわかりやすくなり、通知の見逃しを回避することができます（回避してください）。

:tada: TuneCoreアーティストマイルストーン

楽曲ごと、アーティストごとに各ストアごとの再生数を集計し、集計値に応じてお祝いのページ 「TuneCoreアーティストマイルストーンページ」 を作成する機能です。
これによってアーティストとファンの接点を増やしたい想いがあります。
一例を示します（ワタシのバンドです。ありがとう！）。たくさんお祝いしましょう！

:chart_with_upwards_trend: 役に立った図たち

上記の機能を実装するにあたって以下の図が役に立ちました。
文章で説明するよりも伝わりやすいのです。「伝わりやすい」というのは他の人に対してもなんですが、何より自分自身にもよく伝わるので 「あれ？何がやりたかったんだっけ？」みたいな迷子が減ります。
「こんなもん知っとるわい！」という方は『マークダウンの記述』まですっ飛ばしていただいて大丈夫です。

:floppy_disk: ER図

ER図は「データベースにおける、各テーブルのレコードとレコードの関連をあらわした図面」のことです。

（非エンジニアのみなさまへ ここから）
「データベース」とはアプリケーションで取り扱う情報（たとえば、「ユーザー名」と「パスワード」など）を保存する倉庫みたいなものです。Webアプリケーションを取り扱うにあたって、「データベースにどう情報を保存するか」については多くの人々が苦戦し、その中で様々な手法を編み出してきました。
（ここまで）

「ER」とは「Entity Relationship（実体の関連）」の略です。ここで「実態」とは何ぞやという疑問が生じるわけですが、自分は「各データベースのレコード一行分のデータ」くらいの理解でいます。
データベースの設計を実施する際は必ずといっていい頻度で触ることでしょう。

凡例

テーブルとテーブルをつなげる線の両端にご注目ください。

具体例

「商品（item）が一部対象になるキャンペーン（campaign）を行うよ！」
-> campaign テーブルを作って item テーブルとつなげてみました。
ひとつの商品が複数のキャンペーンの対象になる可能性もあるので関係は一対多にしています。

:dash: シーケンス図

ひとつのプロセスについて、各登場人物がどのようなやり取りをするのかについて、時系列にそって記述するUMLのことです。
アプリケーションでのひとつの動作についてどのようなAPIやクエリが必要なのか洗い出すときに非常に便利です。

（非エンジニアのみなさまへ ここから）
登場人物ってだれがいるの？って話をざっくりとします。「クライアントサーバモデルに基づいています」

  • ユーザー：アプリケーションを取り扱う人間です。
  • クライアント：アプリケーションの中でもユーザーの持つ端末で動作するプログラムのことです。
    • 例えば： お手元のスマホやPCで動作するYoutubeアプリ、通販サイト、スマホゲームなど……
  • サーバ：アプリケーションの中でもユーザーの端末以外のコンピューターで動作するプログラムのことです。
    • 例えば： たとえるのが難しいですが……スマホアプリなどで「サーバとの通信に失敗しました」って言われたら、「成功したときにはこのスマホから他のパソコンに通信を取ってるんだな」と思ってください……
  • データベース
    • 先述の「ER図」で説明したのでここでは割愛します。
      （ここまで）

※UMLとは？
UMLとは「統一モデリング言語」のことで、システムの動きや構造を特定の観点に基づいて図式化することに優れています。
要は「この動きってどういう流れなの？」とか「この機能ってどんなデータが必要で、その関係はどうなってんの？」みたいなコミュニケーションが実に取りやすくなります。ホントホント。

凡例

具体例

上記キャンペーンにのっとり、「商品名を保存したらキャンペーン名が末尾につくバグ」 の動作の流れを書いてみました。

:dolphin: マークダウンでの記述

上部で示した図は、実はテキストで記述しています。
mermaid というツールの登場により、マークダウン形式の文章をプレビューすると図面が勝手に差し込まれるようになりました。ありがとう！

:notepad_spiral: 準備

Notion

Notionをインストールし、適当なページを開きましょう。あなたに必要な準備はそれだけです。

Visual Studio Code

あなたに必要な準備はこれだけです。

  1. Visual Studio Codeをインストールします。
  2. Markdown Preview Mermaid Supportをインストールします。
  3. 適当な .md ファイルを開き、インストールしたプレビュー機能を実行します。

:pencil2: 実際に記述してみよう

それでは張り切って書いていきましょう。
いずれも、mermaidのコードブロック（```mermaid ではじまり ``` で終わるブロック）で記述します。

:floppy_disk: ER図

コードブロックの冒頭に erDiagram と記述するとER図として認識されます。

凡例

# テーブルの記述
テーブル名{
    型 カラム名
}

# テーブル同士の関係の記述
# 一対一の関係
テーブルA ||--|| テーブルB # テーブルAとテーブルBは完全に一対一
テーブルA ||--o| テーブルB # テーブルBのレコードがない場合もある

# 一対多の関係
テーブルA ||--|{ テーブルB # テーブルAのレコード一つに対して関連するテーブルBのレコードが一つ以上
テーブルA ||--o{ テーブルB # テーブルBのレコードがない場合もある

具体例

↑に載せたER図はテキストで表示すると以下になります。

    ```mermaid
    erDiagram
    item{
        int id
        string name
        int price
    }

    campaign_item{
        int id 
        int campaign_id 
        int item_id 
    }

    campaign{
        int id 
        string name
    }
    campaign||--o{campaign_item:""
    campaign_item}o--||item:""
    ```

:dash: シーケンス図

コードブロックの冒頭に sequenceDiagram と記述するとシーケンス図として認識されます。

凡例

# 定義
participant 短い名前 as 長い名前（人間以外）
actor 短い名前 as 長い名前（人間）


# やりとりの記述
動作主 ->> 受け手 : リクエストを送信する（実線矢印）
動作主 -->> 受け手: レスポンスを送信する（点線矢印）
動作主 ->> 動作主 : 動作主の内部動作（実線矢印、自分自身に向ける）

具体例

前半に載せたシーケンス図はテキストで表示すると以下になります。

    ```mermaid
    sequenceDiagram

        actor U as ユーザ
        participant C as ブラウザ
        participant S as サーバ
        participant DB as DB

        U ->> C: 商品情報保存ボタンクリック
        C ->> S: 商品情報保存POST
        S ->> DB: 商品IDからキャンペーン情報取得
        DB -->> S: 
        S ->> S: 商品名の末尾にキャンペーン名を付与
        S ->> DB: 商品情報保存
        DB -->> S: 
        S -->> C: 商品情報保存完了レスポンス
        C -->> U: キャンペーン名が末尾についた商品名を表示
        U ->> U: どうしてこうなった
    ```

まとめ

ね？簡単でしょ？
これまでテキストで図面を作成していなかったので泣きながらパワポ作成したりペイントツールを使ったりしていましたが、
mermaidの存在に救われました。
この記事で、より多くの魂が救われることをここで祈り続けています。

TuneCore Japan では 一緒に働くメンバーを募集しています。
エンジニアだけでなく、Director等の各種ポジションをオープンしているので興味がわいた方はぜひご覧ください！

32
10
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
32
10