:::wonder
権限管理をすることになったけど、どうすればいいの？ なにからはじめればいいのかわからない。
:::

という悩みについて、記事でお答えしていきます。

この記事を読むことで、権限管理とはなにか、その際に押さえておくべきRBACとABACについて、また権限管理を設計するやり方の一例がわかるようになります。

私はエンジニアとして、主に立ち上げのフェーズで20以上のサービスを開発してきました。権限管理は、どのサービスにも必ず入ってくるプロセスでした。ここでの経験や、調べたことをもとにこの記事を書いています。

:::note
### 想定している読者の方

この記事が想定している読者の方としては、エンジニアとしてシステムを設計または実装する立場にある、実務経験が1〜3年目の方を想定して記事を書いています。
:::

## 権限管理とは
この記事でいう権限管理とは、ユーザー認証を行った相手に対して、『**誰がどの機能に対してなにをしていいのか、あるいはしてはいけないのかを管理すること**』をいいます。

たとえばTwitterにおける権限管理について考えてみると、次のようになります：

* すべてのユーザーは投稿できる
* すべてのユーザーは自分の投稿を削除できる
* ツイートはすべてのユーザーが閲覧できる
* 非公開ツイートはフォロワーのみが閲覧できる
* ブロックされたユーザーはツイートを閲覧できない

こういった、**サービス内の行動に対する権限を設計する**のが権限管理ですね。この権限管理について、この記事で書いていきます。

:::note
### この記事の権限管理の前提

権限管理は、**システムの種類によって大きく変わってきます**。このため、この記事の内容はすべてのシステムに適用できるやり方というわけではありません。参考資料のひとつとしてお読みいただければと思っています。
:::

## どう権限管理を設計するか
:::trouble
権限管理がなにかはわかったよ。じゃあ具体的にどう設計すればいいの？
:::

Googleで『権限管理 設計』で検索してもらってもわかることですが、権限管理にはいろんなやり方があって、**ベストプラクティスはない**と思っています。この前提で、私はシートで管理するやり方をとっています。

たとえば次のような感じですね。これは架空のドキュメント共有サービスを例に作ってみています：

![権限管理の例](//images.ctfassets.net/pppgbgujcovf/319j6VkMVXG6mdQJhx65Tk/95133f1312b3bf4296e41c3f848d6410/__________________.png)

### 権限管理のシートに書く内容

このシートには、次のようなことを書いていきます：

| 項目 | 内容 | 例 |
| - | - | - |
| **機能** | どの機能に対する権限か | 投稿閲覧 |
| **役割** | どの役割に対する権限か | 一般ユーザー / 管理者 |
| **属性** | どんな属性をもったユーザーに対する権限か | 同じグループに属していること |
| **対象となるデータ** | 処理するデータはどれか | グループのメンバーの投稿 |
| **処理の可否** | 処理をできるのかどうか | できる / できない |
| **説明** | その権限の概要 | 同じグループのユーザーの投稿を閲覧できる |

開発が進むにつれて、機能が追加・削除されて、権限もどんどん変わっていくことになります。その度に、このシートを更新していきます。

すべての権限管理が一枚のシートに集約されている状態がベストですね。

## 権限管理におけるRBACとABACという考え方
上の表で、権限管理には『役割』と『属性』があると書きました。これについて、権限管理を設計する上で**RBAC**と**ABAC**という考え方が大切なので、それぞれについて書いていきます。

### RBAC: Role-Based Access Control

RBACは『**ユーザーの役割によって権限のチェックを行う**』やり方です。役割とは、たとえば一般ユーザーや管理者などがありますね。

権限を変更するだけで処理の可否を変更できるという利点がありますが、権限がふえると管理や実装が大変になってきます。

『管理者』のような役割以外にも、WritableやReadableのような複数のパーミッションを持たせるようなやり方もあります。

### ABAC: Attribute-Based Access Control

ABACは『**ユーザーの属性によって権限のチェックを行う**』やり方です。たとえばツイートの投稿者かどうか、あるいは同じグループに所属しているかどうか、ですね。

ABACは柔軟な権限管理ができる一方で実装が大変だったり、ものによってはデータベースへのアクセスがふえてパフォーマンスが悪くなったりします。

:::wonder
RBACとABAC、どっちのやり方がいいの？
:::

RBACとABACは、システムの種類によって使い分けるとよいですね。ひとつのシステム内で両方を使うことももちろんあります。

## 権限管理を設計するフロー
権限管理の設計はシートでやるといい、と書きました。その手順としては、次の3つでやるとスムーズに設計できます。

1. 機能を洗い出す
2. 機能に対する権限を洗い出す
3. 重複した権限の優先度を考える

まずシステムの機能を洗い出して、それぞれの機能に対する権限をシートにまとめていきます。このとき、重複した権限が出てきます。たとえば：

* 管理者はすべての投稿を表示できる
* ブロックされたユーザーは、相手の投稿を表示できない

という二つの権限があったときに、『ブロックされている管理者』は投稿を閲覧できるのかどうかを考える必要が出てきます。

こういった重複について、ひとつひとつどうするかを決めていきます。

## 権限はどこでチェックするか
:::smile
権限を設計するやり方はなんとなくわかった。あとは実装していくだけだね。
:::

次はコード面での設計についてです。権限は、データベースなどの**データとのやりとりが発生するところ**でチェックするといいですね。

たとえばフロントエンドにJavaScriptを用いていて、データとのやりとりにAPIサーバーがある、という構成について考えてみます。

フロントエンド側で権限管理をする/しないについては選択の余地がありますが、**API側での権限管理は必須**ですね。なぜなら不正なリクエストなどで、意図しないやりとりが行われる可能性があるからです。

もちろんトークンの照合などでリクエスト自体の正当性は検証しつつも、API側で権限をチェックする必要があるといえます。

## 権限はどこで実装するか
次は、チェックではなく権限自体をどこで実装するかについて考えてみます。

権限管理とは：

> 誰がどの機能に対してなにをしていいのか、あるいはしてはいけないのかを管理すること

であると書きました。つまり**権限はビジネスロジックである**といえます。権限はそれ単体でひとつの責務をもつので、権限管理をする責務として切り出して実装していくとよさそうです。

:::note
### 例：Rubyの場合

Rubyには[Pundit](https://github.com/varvet/pundit)というGemがあります。これはモデル層に属する純粋なRubyオブジェクトで、リソースに対する権限を実装するときに有用なライブラリです。
:::

## 権限管理を設計するときの指針
権限管理を設計するときは、次の二つのことを実践していきます：

1. **役割をできるだけ減らす**
2. **テストコードを書く**

それぞれについて簡単に書きます。

### 役割をできるだけ減らす

権限管理の役割がふえると、その分だけ**権限管理シートやソースコードが複雑**になってしまいます。

ビジネスを表現するために必要であれば役割をふやすことも仕方がないですが、「とりあえず問題を解決するために役割をふやそう」という発想は避けるべきだといえますね。

### テストコードを書く

前述のとおり、権限管理はビジネスロジックに属します。権限の実装にミスがあると、**意図しないデータの流出などにつながるおそれ**があります。

権限に対するユニットテストはもちろん、データとのやりとりが発生するコントローラ層へのユニットテスト、またE2Eテストなどを書くことで、信頼性の担保につながります。

## まとめ
この記事では権限管理を設計するときの考え方、やり方について書いてきました。

権限管理はシステムの種類によって変わってきます。この記事の内容を参考にしつつ、システムに適したやり方を見つけられればと思います。

この記事を読むことで、権限管理とはなにか、その際に押さえておくべきRBACとABACについて、また権限管理を設計するやり方の一例がわかるようになります。

権限管理のイメージ

システムの権限管理を設計するときの考え方

:::wonder
ユーザー認証を実装することになったんだけど、どう設計すればいいの？ 認証にはいろんなやり方があると思うんだけど、なにから考えればいいのか分からない。
:::

といった悩みに、記事でお答えしていきます。

この記事では、Webアプリケーションやネイティブアプリでのユーザー認証の仕組みや方法を説明した上で、どの方法がいいのかをケースごとに見ていきます。

私はBtoB、BtoCのWebアプリケーションやモバイルアプリをいくつか作ってきました。その度に、ソフトウェアの種類に応じたユーザー認証について考え、設計・実装してきました。その経験をもとにこの記事を書いています。

:::note
### この記事の対象となる読者の方

この記事はプログラミングを学習中の方、エンジニアとしての実務経験が1〜3年目の方を対象として書いています。わかりやすさを優先して、用語の使い方が厳密でないところがあります。その際は注釈として補足しています。
:::

## ユーザー認証とは
:::trouble
そもそもユーザー認証とはなに？
:::

この記事でいうユーザー認証とは、Webアプリケーションやネイティブアプリにおいて**リクエストした相手がユーザーであることを確認すること**をいいます。たとえば現実世界でいう運転免許証での本人確認ですね。

ユーザーにだけなんらかの機能を提供したいときに、ユーザー認証を行います。

## ユーザー認証のフロー
ユーザー認証は、基本的に次のようなフローで行われます：

1. クライアントからサーバーに認証情報を送る
2. サーバー上で認証情報を検証する
3. 認証情報が正しければ、クライアントにアクセストークンを送る（+必要に応じてセッションに記録する）

たとえばフォームにメールアドレスとパスワードを入力・送信し、入力内容が正しければサーバーからアクセストークンが渡される、というイメージですね。

## ユーザー認証を設計する上で決めるべきこと
:::anger
それで、結局ユーザー認証を設計するときなにをすればいいの？
:::

このユーザー認証ですが、設計する上で次の4つについて決める必要があります：

| 順番 | 項目 | 選択肢 |
| :-: | - | - |
| 1 | **認証方法をどうするか** | パスワード認証、OpenID Connect |
| 2 | **アクセストークンをどう管理するか** | JWT |
| 3 | **アクセストークンをどう引き回すか** | Authorizationヘッダー、Cookieヘッダー |
| 4 | **アクセストークンをどう保持するか** | OS標準のストア、メモリ、Cookie、localStorage |

今はまだそれぞれがなにかを理解する必要はありません。これからひとつずつ見ていきましょう。

## 1. ユーザー認証の方法
まず、ユーザー認証の方法には、大きく次の二つがあります：

| 番号 | 認証方法 | 概要 |
| :-: | - | - |
| 1 | **パスワード認証** | IDとパスワードをサーバーに送る |
| 2 | **OpenID Connect** | 外部のプロバイダ上で認証し、アクセストークンをサーバーに送る |

OpenID Connectは、OAuth認証と聞くとなじみがあると思います。たとえばGoogleやTwitterなどのアカウントによる認証ですね。ただ、『OAuth認証』という言葉には語弊があります。これは後述しますね。

この二つの認証方法についてひとつずつ見ていきます。

## 認証方法(1): パスワード認証
パスワード認証にも、大きく二つの認証方法があります：

1. Basic認証やDigest認証など
2. 独自の認証機構

独自の認証機構とは、たとえばフォームからIDとパスワードをサーバーに送って、ユーザー基盤をもとに認証を行う一般的なやり方ですね。広く使われている**フルスタックのWebフレームワークならだいたい認証機構をもっている**と思います。

この認証方法はパスワードを平文で送ることになります。仮にSSLで通信を暗号化していたとしても、ログに書かれて流出につながったりします。

## 認証方法(2): OpenID Connect
次にOpenID Connectについて説明します。これはGoogleやTwitterなどのアカウントで認証する方法ですね。

まず、前提知識として、OAuthという『**アクセストークンを発行する仕組み**』があります。アクセストークンは、アプリケーションをAPI経由で操作するときなんかに使われますね。たとえばTwitterクライアントを自作するときにアクセストークンを使ったりします。

このOAuthは前述のとおりアクセストークンを発行する仕組みであって、**認証については定められていません**。認証に必要な、ユーザー情報などの取得については決まっていないんですね。

このOAuthを拡張し、ユーザー情報の取得についてなどを標準化したのがOpenID Connectというわけです。これについては『[OpenID Connectユースケース、OAuth 2.0の違い・共通点まとめ](https://www.buildinsider.net/enterprise/openid/connect)』の説明がわかりやすいです：

> OpenID Connectは、『OAuth 2.0を使ってID連携をする際に、OAuth 2.0では標準化されていない機能で、かつID連携には共通して必要となる機能を標準化した』OAuth 2.0の拡張仕様の一つである。

### OpenID Connectによる認証のフロー

このOpenID Connectは広く使われている認証方法なので、フローを押さえておきます。まず、IDトークンという『**ユーザー情報が含まれたアクセストークン**』があり、これを次のフローでやりとりします。プロバイダというのはGoogleなどの認証を行うサービスを想定しています：

| 順番 | リクエスト元 | 相手 | 内容 |
| :-: | - | - | - |
| **1** | **クライアント** | **プロバイダ** | **IDトークンを要求する** |
| 2 | プロバイダ | ユーザー | IDトークンの発行可否を聞く。あわせて認証を行う |
| 3 | ユーザー | プロバイダ | 発行可否と、発行する場合に認証情報を送る |
| **4** | **プロバイダ** | **クライアント** | **IDトークンを発行する** |

この1と4のやりとりを標準化したのがOpenID Connectです。OAuthが『アクセストークンを発行する仕組み』なのに対して、OpenID Connectはこれを拡張して『IDトークンを発行する仕組み』と考えるとわかりやすいかもしれません。

詳しいことはさておき、『Googleなどのアカウント認証を使う』=『OpenID Connectを使う』という認識がもてればいいのかな、と思います。

:::note
### Googleの認証方法はOpenID Connectではない

OpenID Connectについて書きましたが、実際のところGoogleやTwitterの認証はOpenID Connectではありません。GoogleはOpenID Connectの仕様に準拠しつつ、OAuth 2.0を採用しています。TwitterはOAuth 1.0aという仕様で、OpenID Connectには準拠していません。

いずれにしてもOAuthをベースにした認証を行なっていますが、ここではわかりやすさのためにOpenID Connectという用語に統一して説明しています。
:::

## 2. JWTでトークンを管理する
OpenID ConnectはIDトークンをやり取りする、と書きました。これはJWTというトークンの形式になっています。JWTはユーザー認証において大切な概念なので、簡単に説明しておきますね。

### JWTとは

JWTは『**二者間で情報のやりとりを目的とした、JSONベースの形式について規定した標準仕様**』です。『ジョット』と読みます。たとえばJWTは次のような値になります：

```
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
```

わかりづらいですが、三つの文字列がピリオドで連結されています。わかりやすく書くと：

```
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
```

となります。それぞれBase64でエンコードされた文字列となっています。上から順番に、次のような名前と役割があります：

| 順番 | 名前 | 役割 |
| :-: | - | - |
| 1 | **ヘッダー** | 署名の検証に必要な情報 |
| 2 | **ペイロード** | やり取りに必要な情報。ユーザー情報など |
| 3 | **署名** | 検証する内容 |

署名には秘密鍵を使うため、これを用いて検証を行うことができます。署名はヘッダーやペイロードをもとに行うので、内容の改ざんができない、という仕組みです。

クライアントからトークンを受け取ると、サーバー側でトークンが正しいかどうかをその場で検証できます。JWTを用いることで、**パスワードなどの認証情報をデータベースに保存する必要がない**、というメリットがあります。

:::note
### 正しくはJWS

上の説明ではJWTという用語を出しました。これは広く使われているのでこうしましたが、正しくはJWSという仕様です。JWSはJSON Web Signatureで、署名つきのJWTの場合にとりわけてこう呼びます。
:::

### JWTは使うな？

:::anger
いろいろ調べてみると「JWTは使うな」っていう人が多いんだけど、大丈夫なの？
:::

JWTは危険だという議論があります。確かにJWTの署名を検証する方法によっては脆弱性を作り出してしまうという問題があります。たとえば**ヘッダーの情報を改ざんするやり方**です。これについては『[JSON Web Token（JWT）の紹介とYahoo! JAPANにおけるJWTの活用](https://techblog.yahoo.co.jp/advent-calendar-2017/jwt/)』に詳しいです。

ただ、これは実装によって対応できる問題であり、ほとんどのライブラリ側で対応されています。JWTは使うメリットが大きいので、脆弱性への対応がされていることを確認した上で、積極的に使うべきだと思っています。

## 3. アクセストークンをどう引き回すか
上で、ユーザー認証の方法としてパスワードとOpenID Connectについて書きました。この認証結果として、アクセストークンが返されることになります。以降は、このアクセストークンを用いて認証することになります。

では、このアクセストークンはどう引き回せばいいでしょうか。つまり、どうやってクライアントからサーバーにリクエストを送ればいいのでしょうか。これには次の二つがありますが、結論からいうと『**特定の条件を除いてAuthorizationヘッダーで行えばよい**』と思っています。

### 方法1: Authorizationヘッダー

このやり方は、認証を行うために定義されているAuthorizationヘッダーにアクセストークンを入れるやり方です。たとえば次のような形式になります：

```
Authorization: Bearer <アクセストークン>
```

このAuthorizationヘッダーは、Basic認証やDigest認証で使われていました。その後[RFC6750](https://tools.ietf.org/html/rfc6750)でBearerというスキームが策定されました。これは**単一の文字列を認証情報として送信するのに適しています**。

特徴をまとめると：

* ステートレス。サーバー側にセッションストアがいらない
* ネイティブプラットフォームで扱いやすい
* Cookieが使用できない環境でも問題ない

Authorizationヘッダーを用いるやり方は、OpenID Connect、パスワードのどちらの認証方法にも適しています。

### 方法2: Cookieヘッダー

このやり方は、CookieヘッダーにセッションIDを入れつつ、サーバー上でも保存しておくやり方です。ユーザー認証を一度行ったら、以降は**Cookieヘッダーに含まれるセッションIDとサーバー側のセッションIDを照合**してユーザーを識別します。

次のような形でサーバー側からクライアントにCookieのセットをリクエストして：

```
Set-Cookie: SID=<セッションID>
```

次のような形でクライアントからサーバーにリクエストを行います：

```
Cookie: SID=<セッションID>
```

特徴をまとめると：

* ステートフル。データベースなど外部のストレージからセッションを取得する必要がある
* サーバーにリクエストするたびに自動でCookieが送信される
* CSRF脆弱性への対策をする必要がある
* 異なるドメインに対して制約がつく（=CORS）

APIは一般的にステートレスで行うため、Cookieヘッダーによる引き回しは実用的ではないといえます。このやり方はパスワード認証かつ、ネイティブアプリやSPAでない従来のWebアプリケーションに適していると思います。

## 4. アクセストークンをどう保持するか
長くなりましたが、最後のテーマです。前述のとおり、パスワードやOpenID Connectでユーザー認証を行うと、アクセストークンが発行されます。これをヘッダーに乗せて認証します。つまり、**クライアント側でアクセストークンを保持**しておかなければなりません。

アクセストークンはどう保存すればいいのでしょうか。大きく次の4つがありますが、結論からいうと可能な限り『**OS標準のストレージ**』か『**メモリ**』に保持します：

| 番号 | 場所 | 概要 |
| :-: | - | - |
| 4.1 | **OS標準のストレージ** | iOSのKeyChain、AndroidのKeyStore |
| 4.2 | **メモリ** | JavaScriptの変数など |
| 4.3 | **Cookie** | WebブラウザのCookie |
| 4.4 | **localStorage** | Web Storage APIのlocalStorage |

ひとつずつ見ていきます。

### 4.1 OS標準のストレージ

iOSのKeyChainやAndroidのKeyStoreなど、OSが標準で提供しているストレージを利用するやり方です。[Auth0によるアクセストークンの保持についての記事](https://auth0.com/docs/tokens/token-storage#regular-web-apps)でも、次のメモリとあわせて推奨されているやり方です。

### 4.2 メモリ

JavaScriptの変数などに格納し、CookieやlocalStorageには保存しないやり方です。スコープに気をつける必要はありますが、永続化しないため安全といえます。

ただ、ページから離脱するとアクセストークンが消えてしまうので、**ソフトウェアが要件を満たせる場合のみ採用できるやり方**になります。

### 4.3 Cookie

これはWebブラウザのCookieを使うやり方ですね。Cookieを使うやり方にはいくつか問題があります。たとえばXSS脆弱性やCSRF脆弱性などです。

CookieにSecure属性やHttpOnly属性をつければ安全性はいくらか高まります。ただ、Authorizationヘッダーを用いる場合JavaScriptを用いることになるのでHttpOnly属性をつけられません。つまりXSS脆弱性が残ってしまいます。

### 4.4 localStorage

[Web Storage API](https://developer.mozilla.org/ja/docs/Web/API/Web_Storage_API)のlocalStorageを使うやり方です。これもCookieと同じくJavaScriptから操作可能なので、XSS脆弱性が残ります。また、localStorageには『[HTML5のLocal Storageを使ってはいけない](https://techracho.bpsinc.jp/hachi8833/2019_10_09/80851)』で書かれているようないくつかの問題点もあります。

以上、いずれの場合もクライアントとサーバーのやり取りに**HTTPSで通信する**のは必須ですね。HTTPだと通信が見えてしまうので、アクセストークンが盗まれる可能性があります。

また、CookieやlocalStorageを使う場合は**有効期限を短くしてリスクを下げる**などの対策が必要だと思います。

## ユーザー認証の設計例
:::trouble
ユーザー認証についてだいたい分かったけど、長くて頭が混乱してきた。一度整理してほしいな。
:::

記事のはじめにも書きましたが、ユーザー認証を設計する上で決めるべきこととして、次の4つがあります：

| 順番 | 項目 | 選択肢 |
| :-: | - | - |
| 1 | **認証方法をどうするか** | パスワード認証、OpenID Connect |
| 2 | **アクセストークンをどう管理するか** | JWT |
| 3 | **アクセストークンをどう引き回すか** | Authorizationヘッダー、Cookieヘッダー|
| 4 | **アクセストークンをどう保持するか** | OS標準のストア、メモリ、Cookie、localStorage |

この4つについて、どう選択すればいいのでしょうか。これはソフトウェアの種類や事業のステージなどによって異なりますが、いくつかの例をとおして見てみます。

### ケースに応じたユーザー認証の設計例

たとえばフルスタックなWebフレームワークを用いて、APIを使わないWebアプリケーションを構築するケース。この場合は**パスワードで認証**し、**Cookieヘッダー**でリクエストします。**JWTは使わず**、アクセストークンはクライアントの**Cookieに保持**します。

SPAでサーバーはAPIとしてのみ利用する場合は、**OpenID Connectで認証**し、**Authorizationヘッダー**でやり取りします。アクセストークンは**メモリ上**に保持します。

ネイティブアプリかつユーザー基盤を自前で構築する場合は、**パスワード認証**をしつつ**JWT**でやり取りします。リクエストは**Authorizationヘッダー**を用い、KeyChainやKeyStoreといった**OS標準のストレージ**を利用します。

## まとめ
長くなってしまいましたが、ユーザー認証を設計するための基本的な知識はだいたい書けたかと思います。

OpenID ConnectやJWTなど、実際に開発する上でもっと深く掘り下げなければならない知識はあると思いますが、この記事がユーザー認証を実装するときの参考になればうれしいです。

この記事では、Webアプリケーションやネイティブアプリでのユーザー認証の仕組みや方法を説明した上で、どの方法がいいのかをケースごとに見ていきます。

ユーザー認証のイメージ

ユーザー認証とは。Web、APIでの認証の仕組みと認証方法

:::wonder
バッチ処理を設計することになったけど、やり方がわからない。そもそもバッチ処理とは？
:::

といった悩みにお答えします。

この記事を読むことで、バッチ処理とはなにか、どう設計すればいいか、そのやり方がわかるようになります。バッチ処理を設計する上で押さえるべきポイントをまとめているので、参考になればと思います。

私は上場企業やスタートアップなどでいくつものWebサービスやアプリを開発してきて、もちろんバッチ処理も設計・実装してきました。その経験をもとに記事を書いています。

:::note
### この記事の対象となる読者の方

この記事はエンジニアとしての実務経験が1〜3年目くらいの方を想定して書いています。また、ソフトウェアの種類としてはWebアプリケーションやモバイルアプリを想定しています。
:::

## バッチ処理とは

![バッチ処理とは](//images.ctfassets.net/pppgbgujcovf/6eUcA9vLljkbwlCXlhwrpi/6b0129d679076d95d16b84eda778e2b5/about-batch-processing.png)

まず、この記事におけるバッチ処理の定義について示しますね。バッチ処理とは『**入力があり、その入力を加工し出力するプログラム**』をいいます。たとえばデータベースから処理対象となるデータを取得し、データを変更した上で更新するプログラムがバッチ処理にあたります。

この処理はなんらかのトリガーによって起動します。たとえば時間がトリガーとなって起動します。

バッチ処理はプログラムの実行方式のひとつで、まとまった処理を一度に行います。時間がかかる処理や定時処理などに有用で、ビジネス側の要件を満たすために重要な役割をもちます。

## バッチ処理が満たすべき要件

:::smile
バッチ処理とはなんなのかはわかったよ。じゃあ、具体的にどうバッチ処理を設計すればいいの？
:::

次にバッチ処理を設計する上で満たすべき要件を定めます。この記事で示す各ポイントは、次の要件を満たすことを目的とします。

* ビジネス側の要件を満たすこと
* 問題をできるだけ起こさないこと
* 処理の状況を把握できること
* 異常時にリカバリできること
* リソースの消費を抑えること

## バッチ処理を設計するやり方

上記の要件を満たすために、バッチ処理を設計する上で抑えるべきポイントは次のとおりです。各ポイントごとに書いていきます。

| 順番 | 項目 |
| :-: | - |
| 1 | **ビジネス側の要件を明確にする** |
| 2 | **Dry Runできるようにする** |
| 3 | **APIを叩く処理はリトライする** |
| 4 | **外的要因に依存しないようにする** |
| 5 | **テストコードを書く** |
| 6 | **ログを出力する** |
| 7 | **コミュニケーションツールに通知する** |
| 8 | **冪等性をもたせる** |
| 9 | **処理対象を引数で指定できるようにする** |
| 10 | **リソースの消費を減らす** |

### 1. ビジネス側の要件を明確にする

バッチ処理にはビジネス側の要件があります。いつはじまっていつ終わるのか、どの処理の後にはじめるのか。処理対象はなにか。どういう処理をし、どう出力するのか。こういった要件を明確にした上で設計に入ります。

### 2. Dry Runできるようにする

バッチ処理を実行する際のオペレーションミスを防ぐため、Dry Runの仕組みをとりいれます。

バッチ処理はビジネス上重要な処理であることが多いです。処理対象を間違えるとリカバリをする必要があります。場合によってはメンテナンスモードに入ることになります。これはユーザのUXを低下させてしまいます。

このような問題を防ぐため、処理を実行する前にふるまいをチェックする仕組みをつくります。正しい処理対象に正しい処理が行えるか。これを標準出力をとおして確認できるようにします。

より安全な運用をするために、バッチ処理のデフォルトのふるまいをDry Runにすることも検討します。

### 3. APIを叩く処理はリトライする

APIの利用制限にひっかかるとバッチ処理全体が失敗してしまいます。これを防ぐため、APIを叩く処理はリトライするようにします。

APIによってはRate Limitなどのリクエストに関する制限があります。あるいはAPIが一時的にダウンしているかもしれません。リトライを行うことでことで、処理全体が成功する可能性を高めることができます。

リトライの時間間隔はExponential Backoffという手法が有用です。

### 4. 外的要因に依存しないようにする

処理が外的要因に依存すると、それが利用不能になった場合にバッチ処理全体が失敗してしまいます。可能な限り依存しないようにします。

たとえばバッチ処理内で運用者にSlackで通知したとします。この通知を同期的に行うと、エラーハンドリングしない限りバッチ処理全体が失敗します。通知の失敗が許容できるケースでは失敗してもいいようにします。具体的には非同期での実行などの方法をとります。

### 5. テストコードを書く

バッチ処理も、アプリケーションのコードと同じくテストコードを書きます。このことが問題の防止につながります。

テストコードは処理のふるまいを定義し、テストによって正しくふるまっているかを検証します。これを継続的にテストすることで、バッチ処理の品質を保つことができます。

### 6. ログを出力する

バッチ処理に問題が発生したとき、その調査やリカバリにログを利用します。このためログはバッチ処理において重要な役割を果たします。

ログを設計する際は5W1Hを意識すると効果的です。バッチ処理をいつ開始したか、いつ終了したか。処理対象はなにか。どういう処理を行ったか、行わなかったか。なぜその対象なのか。どの処理か──これは一意の処理IDをログに付与すると、ログ監視ツールで調査しやすくなります。

また、エラーが発生したときはスタックトレースをログに記録します。

### 7. コミュニケーションツールに通知する

バッチ処理の状況を把握するために、処理内の主要なポイントでSlackなどのコミュニケーションツールに通知します。これによりバッチ処理が正しく動作していることを確認できます。問題が発生したときにはすぐ気づくことができ、リカバリ作業に移行できます。

この通知はエンジニア以外のメンバーにもわかりやすい形で通知します。こうすることで、ユーザへのフォローまで含めたリカバリを行うことができます。

### 8. 冪等性をもたせる

バッチ処理は、何度実行しても一度処理した対象を二重に処理しないようにします。「何度実行しても同じ結果が得られる性質」を冪等性といいます。冪等性をもたせることで、処理が失敗したときに再度処理すれば未処理のもののみ処理にかけることができます。

### 9. 処理対象を引数で指定できるようにする

未処理のデータを指定して処理にかけられるよう、処理対象を引数で指定できるようにします。バッチ処理が失敗したとき、処理されたものと未処理のものが出てきます。未処理のもののみ再実行できるとリカバリしやすくなります。

これは冪等性をもたせることが難しいバッチ処理に対して特に効果的です。

また、Dry Runと組み合わせることも有用です。今後実施予定のバッチ処理を、処理対象を指定した上で事前に確認できるようになります。

### 10. リソースの消費を減らす

バッチ処理は、その性質上コンピューティングリソースを消費しやすいです。できるだけ消費を減らせるよう、実装上の工夫をします。

たとえばデータベースにある大量のレコードを扱うとき、全件をメモリ上に展開すると多くのリソースを消費してしまいます。この場合、分割して処理することを検討します。

またトランザクションも有用ですが、大量のデータに対するトランザクションはデータベースリソースの消費につながります。適切な粒度で行う必要があります。

## おわりに

![バッチ処理を設計する上で抑えるべきポイント](//images.ctfassets.net/pppgbgujcovf/6UENtMZ6qz8aN11xADtVnU/4c50c03629cb43f89c0c9ba8f972570e/points-on-designing-batch-processing.png)

以上のポイントを意識してバッチ処理を設計することで、ビジネス側の要件を満たしつつ、問題が起きづらいバッチ処理を運用することができます。問題が起きたときにも対処しやすいため、可能な限りポイントを押さえるようにしたいですね。

この記事を読むことで、バッチ処理とはなにか、どう設計すればいいか、そのやり方がわかるようになります。バッチ処理を設計する上で押さえるべきポイントをまとめているので、参考になればと思います。

バッチ処理のイメージ

バッチ処理の設計。バッチ処理とはなにか、やり方は？

:::trouble
システムに障害が起きちゃった！ どうすればいいの？
:::

:::smile
障害が起きたときのために、どう障害対応をすればいいか学んでおきたいな。
:::

といった悩みに記事でお答えしていきます。

この記事を読むことで、**障害が起きたときの業務フロー**を学ぶことができます。実際に障害が起きたときに見ながら対応することで、復旧につながっていきます。また、障害が起こらないための準備についてもまとめています。

私は上場企業やスタートアップなどでBtoBやBtoCのシステムを開発・運用してきました。ここで経験した障害対応得た知見をもとに、記事としてまとめています。

:::note
### この記事の前提

この記事では、Webサービスやモバイルアプリの障害対応を想定して書いています。他の領域における障害対応でも参考になるかもしれませんが、当てはまらないこともあることをご承知おきください。

また、想定している読者の方としては、エンジニアとしての実務経験が1〜3年目の方としています。
:::

## 障害対応とは
:::wonder
そもそも障害対応ってなに？
:::

障害対応とは、『**システムに障害が起きたときに、正常な状態に戻すための対応のこと**』をいいます。ここでいう障害とは、なんらかの問題が起きたときに『今すぐ対応すべき』と判断したものを障害としています。

## 障害対応の業務フロー
障害対応の業務フローは、次の7つのプロセスからなります：

| 順番 | 項目 |
| :-: | - |
| 1 | **関係者への周知** |
| 2 | **体制構築** |
| 3 | **ユーザへのフォロー** |
| 4 | **復旧** |
| 5 | **復旧の共有** |
| 6 | **再発防止** |
| 7 | **関係者への共有** |

上のプロセスのうち、復旧までにかかる時間をできるだけ短くすることが大切だといえます。障害の大きさによらず、3の『ユーザへのフォロー』までは**努力次第で確実に早くできる**ので、そのための準備をしておくといいですね。

私もそうでしたが、運用の経験がない方にとっては障害対応=4の『復旧』だと思いがちだと思います。ただ、復旧は障害対応の一部に過ぎません。上の7つのプロセスをしっかりと押さえておきましょう。

:::info
### システムの復旧は障害対応の一部に過ぎない

障害対応において、システムの復旧はもちろん重要な要素です。ただ、その前に関係者への周知や障害対応の体制構築、ユーザへのフォローなど、確実に行っておきたいプロセスがあります。まずはプロセス全体を把握しておきましょう。
:::

## 1. 関係者への周知
それでは障害対応についてひとつずつ見ていきます。まずは関係者への周知についてですね。このプロセスでは、**システムに関わるメンバーに障害について周知**します。とくに、2の『体制構築』に関わるメンバーには確実に共有できるようにします。

周知の方法については、社内で使っているチャットツールなど、全体に通知できる方法を用います。書く内容としては、次のような項目がいいでしょう：

* 障害の内容
* いつ発生したか
* 原因はなにか
* 影響範囲
* 障害対応にあたるメンバーおよびリーダー
* 対応内容
* 完了目処

周知の段階で、わからないことは一旦未定でいいと思います。障害対応に進捗があったとき、必要に応じて随時周知を行います。

## 2. 体制構築
障害対応を行うための体制を構築します。たとえば次のようなメンバーで構成します：

* ユーザとのフロントに立つセールスやカスタマーサクセスなどのメンバー
* 技術的な復旧対応にあたるエンジニア
* その他、影響範囲を確認したり、状況を関係者に報告する、ドメイン知識が豊富なプロダクトマネージャなど

障害対応における体制構築において大切なことは、**ひとりで解決しようとしないこと**です。複数人で行えば、後述する復旧対応を複数の視点から行えます。一方で復旧を間違えると二次、三次の障害が発生し、被害が拡大してしまいます。

なにより、障害対応はやることがたくさんあります。個人開発などひとりでしか行えないケースを除いて、複数人であたるようにします。たとえば『[インシデント指揮官トレーニングの手引き](https://yakst.com/ja/posts/5588)』では『インシデント指揮官』をはじめとする4つの役割で障害対応にあたるとしています。

## 3. ユーザへのフォロー
障害対応にあたる体制を構築したら、まずは**ユーザにフォローを入れます**。フォローを入れる方法としては、障害の種類や影響範囲、プロダクトの種類に応じて次の中から使い分けます：

* システム上にメッセージを掲載する
* メールで通知する
* 電話などで個別に連絡する

## 4. 復旧
復旧は、システムを問題なく使用できるようにすることを目的とします。復旧は次のようなプロセスになります：

1. 復旧のゴールを決める
2. 情報を収集する
3. 調査する
4. ソースコード等の変更を行う
5. 変更を適用する

障害対応における復旧の最終的なゴールは、障害が起こる前の状態に戻すことです。ただ、復旧には時間を要する場合もあります。このときは、**暫定的なゴールとしてひとまず問題なく使える状態**にします。

次に情報を収集します。発生した障害を体験したユーザにコンタクトが取れる場合は、情報をヒアリングします。このときユーザのアカウント情報を得ることで、後述する調査のときにログ等と照らし合わせることができます。

### 障害を調査する

情報収集と合わせて調査を行います。障害対応の起点となるのはエラー監視ツールによる通知の場合が多いと思いますが、まずはエラー監視ツールを見て、問題を切り分けます。

切り分けた対象を元にリソース監視ツールやプロセス監視ツールを確認し、障害の要素を見つけます。また、関連するログも見ます。アプリケーションやサーバ、それぞれのアクセスログやエラーログなどを見ていきます。

このとき、**障害が発生した時間やユーザのアカウント情報と照らし合わせて確認する**ことで、原因を突き止めやすくなると思います。

調査して原因がわかったら、ソースコード等を変更し適用します。このとき、データの変更などで本番環境に負荷がかかる場合があります。必要に応じてメンテナンスモードへの移行やバックアップ、リストア手順の確認などを行います。

## 5. 復旧の共有
システムの障害が復旧したら、あるいは復旧のメドが立ったが時間を要する場合にも、ユーザに共有します。これも3の『ユーザへのフォロー』と同じ考え方で行います。

## 6. 再発防止
システムが障害から復旧できたら障害対応は終わり、ではありません。**なぜ障害が起こったのか、再発しないためになにをするか**を決めていきます。たとえばインスタンスのサイズを上げたり、レビューのプロセスを改善する具体的な方法を決めたりします。

障害対応のプロセス自体に問題があったときも、再発防止策として改善したいですね。

## 7. 関係者への共有
**再発防止の内容を元に、今回の障害について関係者に共有**します。同じ障害が起きない安心感を与えたり、似た障害が起きたときに再度報告してもらうことにつながります。

また、障害対応のプロセスに問題があったときに、第三者の目から見て客観的に問題を指摘してもらい、次につなげることができます。

:::convinced
障害対応って、調査と解決以外にもやることがたくさんあるんだね。実際に障害が起きたら、焦らずまわりに協力してもらいつつ、ひとつずつやっていこうl
:::

## システムに障害を起こさないために
この記事では障害対応の業務フローについて書いてきましたが、そもそも障害を起こさない方がいいですよね。そのために重要なのが：

* コードレビューを行う
* 自動テストを導入する
* 運用監視ツールを導入する

などです。変更しようとするソースコードに問題があったとき、ソースコードレビューや自動テストの実行で検出することができます。また、運用監視ツールでは急激なアクセスの増加などで問題が起こりそうなときに、前もって検出することができます。

この3つについては次の記事でも説明しています。あわせてご覧くださいね：

:link{slug=how-to-do-source-code-review}

:link{slug=how-to-create-test-cases}

:link{slug=what-is-server-operation-monitoring}

## まとめ
障害が起きたときの業務フローについて書きました。システムに障害が起きたら、ひとりで焦って対応せずに、関係者への共有からひとつずつやっていきましょう。また、運用監視ツールの導入など、障害が起きないための準備もしておきたいですね。

この記事を読むことで、障害が起きたときの業務フローを学ぶことができます。実際に障害が起きたときに見ながら対応することで、復旧につながっていきます。また、障害が起こらないための準備についてもまとめています。

障害対応のイメージ

障害対応の業務フロー。システム開発における障害対応の手順、体制

:::wonder
管理画面を開発することになったけど、どう作ればいいの？ デザインの記事は見つかるんだけど。どう設計すればいい？ 必要な機能ってなに？
:::

という悩みについてお答えしてきます。

この記事では、**管理画面を設計する上でなにを考えればいいか**、指針をまとめていきます。また、プロダクトのフェーズにおける管理画面の考え方についても整理します。

この記事を読むことで、管理画面の作り方がよくわからない状態から、どう作りはじめればいいかがわかるようになると思います。

私は上場企業やスタートアップなどで20以上のプロダクトを作ってきました。そのすべてに管理画面をもっていました。たくさんの管理画面を設計・開発した経験をもとに、この記事を書いています。

## 管理画面とは
:::trouble
そもそも管理画面ってなんなの？ なにをする画面なんだろう。
:::

管理画面は、『**プロダクトの運用を目的としてデータを管理するための画面**』のことをいいます。基本的には運用者のみがアクセスや操作を許されていますね。

管理画面を作る上で、まず『利用者』と『目的』のふたつを押さえておくことが大切です。

### 管理画面の利用者

管理画面の利用者には、大きく分けると：

* 運用者
* ユーザ

のふたつの役割がいます。ユーザとは、たとえばブログサービスにおける投稿画面のようなイメージですね。この記事では、前者の『運用者』が使う管理画面について書いていきます。

### 管理画面の目的

また、管理画面の目的には、大きく分けると：

* オペレーションのため
* データ分析のため

のふたつがあります。この記事ではどちらもふまえますが、どちらかというと前者のオペレーションを目的とした管理画面について書いていきます。

:::info
### まとめ：管理画面とは

管理画面は『プロダクトの運用を目的としてデータを管理するための画面』です。管理画面を設計する前に、まず利用者と目的を明確にしておきましょう。
:::

## 管理画面の設計指針
:::smile
管理画面についてはなんとなくわかったよ。じゃあ次にどう設計すればいいのかについて教えてね。
:::

では、管理画面をどう作ればいいのか、なにを考えて作ればいいのかについて書いていきますね。これはプロダクトの種類について変わってくるので、ここでは共通する普遍的なことについてまとめます。

まず表にまとめて、それからひとつずつ見ていきます。

| 番号 | 設計項目 |
| :-: | - |
| 1 | **認証をどうするか決める** |
| 2 | **認可する対象を決める** |
| 3 | **テストを書く** |
| 4 | **監査用のログを記録する** |
| 5 | **自動でバックアップを取る** |
| 6 | **機能を決める** |
| 7 | **体験を決める** |
| 8 | **デザインを決める** |
| 9 | **外部サービスの利用を検討する** |

### 1. 認証をどうするか決める

まず認証をどうするか決めます。GoogleやSlackなどのアカウント連携がよさそうですね。どのアカウントを使うかは、**組織が利用しているプラットフォームに応じて**決めればいいです。

あとは、IPアドレスによる制限をかけるなど、他の手段とあわせて認証するとセキュリティが強化されます。

実装がラクだからといって、プロダクト本体のユーザ基盤を利用してしまうと、セキュリティの担保が難しくなったり、管理画面がプロダクト本体と密結合になってしまうので、基本的には避けた方がいいと思っています。

### 2. 認可する対象を決める

次に**認証した運用者の役割によって許可する操作を分けていきます**。たとえばアルバイトや業務委託の方など、アクセスしていいデータが変わってくることがあるので、これを分けます。

やり方としては、まず管理画面上の操作の一覧をスプレッドシートなどに書き出し、許可する役割をセットで書いておくことで、実装しやすくなります。テストも書きやすくなりますね。

### 3. テストを書く

管理画面は大切なデータを扱う画面です。不具合があってデータに不整合が起こってしまうと大変なので、当然ですがテストを書きましょう。テストを自動で実行し、不具合を検出できる環境も作っておきます。

### 4. 監査用のログを記録する

誰がいつどんな操作をしたのかを記録します。組織によっては必要になるので、**事前に確認しておきましょう**。

### 5. 自動でバックアップを取る

システムのバグや操作ミスなどでデータが意図しない形になってしまったときに、もとに戻すためにバックアップが必要になってきます。管理画面がなくても必要ですが、念のために項目として書いておきます。

### 6. 機能を決める

管理画面にどんな機能を作るかを決めていきます。管理画面といっても、通常のプロダクト開発と同じやり方で作ります。つまり、基本的には『それがないと成り立たない機能のみ』を作ります。

作るだけではなく、使わなくなった機能はどんどん消していきましょう。これについては『[プロダクトに機能を追加するかどうかを判断する方法](https://product-development.io/posts/how-to-determine-whether-to-add-feature-to-product)』で詳しく説明しています。

:link{slug=how-to-determine-whether-to-add-feature-to-product}

### 7. 体験を決める

体験とは操作をしたときのメッセージ表示やアラートの出し方などですね。運用者もユーザと同じで、**マニュアルに書いたところで操作ミスなどは必ず起こります**。このミスができるだけ起きないよう、メッセージの出し方やアラートを出す基準を決めましょう。

### 8. デザインを決める

どんなデザインにするかを決めます。管理画面のデザインにはコストをかけられないかもしれませんが、見た目がよくないと運用のモチベーションに影響してきます。これって結構大切だったりします。

CSSフレームワークなどを使って、最低限の見た目は整えるようにしたいですね。

### 9. 外部サービスの利用を検討する

機能を作ることは負債であるという認識をもつことが大切です。たとえば分析は[Redash](https://redash.io/)を用いるなど、できるだけ外部サービスを利用するようにしましょう。

## プロダクトのフェーズに応じた管理画面
上で管理画面の設計指針についてまとめました。ただ、**管理画面の作り方はプロダクトのフェーズによっても変わってきます**。とくに、Product/Market Fitの前後で変わります。

### PMFをめざしているとき

PMFをめざしている段階では、日々変化するプロダクトに対応できるよう、オペレーションをまわしていく必要があります。このための**開発スピードがなにより大切**になってきます。

開発スピードを優先するために、管理画面を作るためのフレームワークなどを用いることを検討します。

### PMF達成後

PMFを達成したということは、ある程度オペレーションが固まったことを意味します。この段階では長期的な運用を見据えて、**自前で管理画面を作る**ことを検討します。

PMFをめざす過程では機能の追加・削除が繰り返されると思います。汚くなった機能やソースコードを一度整理するのもこのタイミングがよさそうですね。

## 管理画面に対する基本的な考え方
管理画面は、基本的にはプロダクトと同じです。**ユーザ=運用者が抱える課題を解決するため**に、管理画面を作ります。

このため、誰が運用者なのか、運用者はなにを解決したいのか、どう解決するのかを、ひとつひとつ検証しながら作っていくべきです。つまりリーンスタートアップの考えに基づいて作っていきます。もちろん、一度作って終わりではなく、継続的に開発していく必要がありますね。

:::convinced
管理画面はプロダクトのフェーズに応じて作り方を変えることが大切なんだね。プロダクトと同じように作る、というのも分かったよ。
:::

## まとめ
管理画面は主にオペレーションのために運用者が使う画面です。運用者をユーザととらえ、リーンスタートアップの考え方に基づいて作っていくことで、よりよい管理画面になっていきます。

管理画面を作るときはプロダクトのフェーズに応じた作り方をすることで、小さいコストで作っていけます。

この記事では、管理画面を設計する上でなにを考えればいいか、指針をまとめていきます。また、プロダクトのフェーズにおける管理画面の考え方についても整理します。

管理画面のイメージ

管理画面を開発するときの設計指針。ゼロからわかる作り方

:::wonder
Contentfulで、あるEntryへのLinkの数はどうやって取得すればいいの？ いくつかのContent Modelから参照している合計の数を取得したいな。
:::

という悩みに回答していきます。

[Content Delivery API](https://www.contentful.com/developers/docs/references/content-delivery-api/)には、Entriesを取得するための検索パラメータとして[links_to_entry](https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters/links-to-entry)というパラメータがあります。これを使っていきます。

本サイト『[Product Development IO](https://product-development.io/)』はNext.js+Contentfulで作っていて、記事や単語、本といったコンテンツからタグを参照しています。このタグに紐づいたEntryの数を取得するのに `links_to_entry` を使っています。

本サイトの実装を例に説明していきますね。

## 動作環境
この記事の内容は、次の各バージョンで動いています。本サイトはTypeScriptで書いているので、コードの例もTypeScriptとなっています。

| ライブラリ | バージョン |
| - | - |
| [typescript](https://github.com/microsoft/TypeScript) | 4.1.5 |
| [contentful.js](https://github.com/contentful/contentful.js) | 8.1.7 |

## links_to_entryとは
:::trouble
`links_to_entry` を使えばいいことはわかったけど、そもそも `links_to_entry` ってなんだろう？
:::

まず `links_to_entry` についてまとめますね。これはContent Delivery APIでEntriesに対する検索パラメータのひとつです。

ドキュメントには次のように書かれています：

> あるエントリにリンクするフィールドをもつエントリを検索するには、links_to_entry という検索パラメータを用います。値にはエントリのIDを設定します。

ドキュメントのコード例そのままですが、JavaScriptの場合は次のようにして取得します：

```javascript
client
  .getEntries({
    links_to_entry: '<entry_id>',
  })
  .then((response) => console.log(response.items))
  .catch(console.error)
```

:::notice
### パフォーマンス上の注意

今回の例のように、複数のContent Modelから参照しているエントリについては `links_to_entry` は有用です。

ただ、特定のContent Modelから参照しているエントリを取得するときは、 `links_to_entry` を使わずContent Typeを指定して取得する方が、パフォーマンスが高くなります。
:::

## links_to_entryの実装例
では実装例の方を見ていきますね。本サイトのようにタグがあり、タグを参照する記事、単語、本という3つのContent Modelがあるアプリケーションを想定します。

### Content Model

それぞれ、次のような構造であると仮定します。単語と本は記事とだいたい同じ構造なので省略します：

| Content Model | Field Name | Field Type |
| - | - | - |
| Tag | Name | Short Text |
| | Slug | Short Text |

| Content Model | Field Name | Field Type |
| - | - | - |
| Post | Title | Short Text |
| | Slug | Short Text |
| | Content | Long Text |
| | Tag | Reference |

このときの型定義は次のようになります。タグには自身を参照しているエントリの数を格納する `count` も定義しています：

```typescript
export type Tag = {
  name: string
  slug: string
  count: number
}

export type Post = {
  title: string
  slug: string
  content: string
  tag: Entry<Tag>
}
```

### タグの一覧を取得する

まず、タグの一覧を取得します。パラメータの型は `any` にしていますが、実際は許容する検索パラメータの型を指定します：

```typescript
export async function getTags(params?: any): Promise<Entry<Tag>[]> {
  const entries = await client.getEntries<Tag>({
    content_type: 'tag',
    ...params,
  })
  return entries.items
}
```

### タグへの参照数を取得する

次に、取得したそれぞれのタグへの参照数を取得していきます：

```typescript
export async function withLinksCountToTag(
  tags: Entry<Tag>[]
): Promise<Entry<Tag>[]> {
  await Promise.all(
    tags.map(async (tag) => {
      const entries = await client.getEntries({
        links_to_entry: tag.sys.id,
      })
      tag.fields.count = entries.total
      return tag
    })
  )
  return tags
}
```

参照数はJSONオブジェクトの `total` プロパティに格納されているので、これを使います。また、このコード例のように `getTags` をラップするようにして使うことで、参照数が必要ないときに `getTags` のみを使えるようになります。

:::notice
### 参照数を取得するときの注意

上記のコード例は、タグの数が多いとパフォーマンス上の問題やAPIのRate Limitによる制限が起きる可能性があります。

本サイトはタグが数個かつNext.jsのStatic Site Generationを用いているので問題ありませんが、アプリケーションの種類によって対策を取る必要があると思います。
:::

### 使い方

この二つの関数を使うと、次のようにしてタグの一覧と、それぞれのタグへの参照数を取得できます：

```typescript
const tags = await withTagEntriesCount(await getTags())
```

## まとめ
あるエントリを参照する複数のContent Modelがあるとき、参照されるエントリの参照数を取得するのに `links_to_entry` を使うといいです。

特定のContent Modelを対象に参照数を取得するときは、 `links_to_entry` ではなくContent Typeを指定する方がよいパフォーマンスを期待できます。

Content Delivery APIのlinks_to_entryという検索パラメータを用いて、エントリへの参照数を取得する方法について説明します。

Contentfulのイメージ

ContentfulでEntryへのLinkの数を取得する方法

機密情報管理サービスとは、ひとことでいうと機密情報のためのキーバリューストアです。
代表的なものとして[AWS Secrets Manager](https://aws.amazon.com/jp/secrets-manager)や[Systems Managerパラメータストア](https://docs.aws.amazon.com/ja_jp/systems-manager/latest/userguide/systems-manager-parameter-store.html)、[Hashicorp Vault](https://www.vaultproject.io)があります。
TerraformやAnsibleなどでインフラを構築するときに、機密情報管理サービスを用いることで安全性を高めることができます。

この記事では上記3つのサービスについて、Infrastructure as Codeの文脈で比較します。
またプロダクトにあった選び方について述べます。

## 用語の定義

まず、この記事における用語の定義について示します。

### 機密情報とは

機密情報とは「意図しない第三者に知られると悪用されるおそれのある情報」をいいます。
パスワードやAPIキーなどがあてはまります。
機密情報が漏洩すると、たとえばサーバに不正にアクセスされ、個人情報を取得されるおそれがあります。
あるいは、クラウドリソースを消費され、巨額の費用を請求されるかもしれません。

機密情報をソースコード内に直接記述すると、バージョン管理システムをとおして意図しない人に公開される可能性があります。
機密情報管理サービスを用いることで、このような問題を防ぐことにつながります。

### 機密情報管理サービスとは

機密情報管理サービスとは「機密情報を暗号化し、安全に保管した上で、権限をもったユーザにAPIをとおして提供する機能をもつキーバリューストア」です。
パスベースのものが広く使われており、たとえば次のようにパスをキーとして値を格納します。

| キー | 値 |
| -: | :- |
| `/example-com/production/google-api-key` | `abcde…` |

値はAES-256などのアルゴリズムで暗号化されます。
AWSなどの信頼できるマネージドサービスを用いることで、暗号化された値を安全に保管できます。
また、値へのアクセス権限をポリシーにより管理する仕組みがあります。

## 機密情報管理サービスの要件

機密情報管理サービスには代表時なものにSecrets Managerとパラメータストア、Vaultがあると述べました。
これらサービスがIaCという文脈で満たすべき要件として、次のことがあります。

1. 暗号化されること
2. 安全に保管されること
3. アクセス権限を管理できること
4. APIにより情報を取得できること

この4つの項目を上記サービスはすべて満たしています。
たとえば暗号化について、Secrets ManagerとパラメータストアはAWS Key Management Service (KMS)、VaultはAES-256を用いて暗号化します。

機密情報が保管されるストレージバックエンドについては、Secrets Managerとパラメータストアはマネージドになります。
VaultはS3やAzure、PostgreSQLなどクラウドやリージョン、ストレージを自由に選択できます。

権限管理について、Secrets ManagerとパラメータストアはAWS Identity and Access Management (IAM)によりポリシーベースでアクセス権限を管理できます。
Vaultもポリシーを[HCL](https://github.com/hashicorp/hcl)で定義できます。

## 比較項目

次にプロダクトにあったサービスを選ぶ基準として、コスト、シークレットローテーション、パスワード生成という3つの項目で上記サービスを比較します。

| 項目 | Secrets Manager | パラメータストア | Vault |
| -: | :-: | :-: | :-: |
| コスト | 有料 | 基本的に無料 | 無料/有料 |
| シークレットローテーション | ◯ | - | ◯ |
| パスワード生成 | ◯ | - | ◯ |

まずコストについて、Secrets Managerは機密情報1つにつき$0.4/月、また10,000回のAPIコールあたり$0.05かかります。
パラメータストアは標準パラメータは無料、アドバンストパラメータは機密情報1つにつき$0.05/月かかります。
機密情報の基本的なユースケースにおいては標準パラメータの利用で問題ありません。
パラメータの種類については「[パラメータ層の管理](https://docs.aws.amazon.com/ja_jp/systems-manager/latest/userguide/parameter-store-advanced-parameters.html)」をお読みください。

VaultはOSSを利用する場合はサーバ代やメンテナンスコストがかかります。
SaaS版は問い合わせによる料金開示となります。

シークレットローテーションとは、機密情報を定期的に自動で変更する機能で、安全性の向上に役立ちます。
Secrets ManagerとVaultが対応しています。
パスワードを生成する機能もSecrets ManagerとVaultのみが対応しています。

## サービスごとの特徴

上記比較項目以外にも、サービスごとの特徴があります。
機密情報管理サービスを選ぶ上での重要なポイントになります。
以下に特徴を示します。

### Secrets Manager

Secrets ManagerのシークレットローテーションはAmazon RedshiftといったAWS各サービスと統合しやすいという特徴をもっています。
また、Amazon VPCエンドポイントをサポートしているため、機密情報がパブリックインターネットに送信されることを防げます。

そのほか、AWS CloudTrailを用いてログ監査ができます。
CloudWatchやIAMとの統合もしやすいです。
また、Secrets ManagerにはSLA99.9%が設定されています。

### パラメータストア

Secrets Managerと同じくVPCエンドポイントをサポートしていたり、CloudTrailやIAMなどと統合することができます。
SLAは標準パラメータには設定されていませんが、アドバンストパラメータにはSecrets Managerと同じレベルが設定されています。

スロットルについて、パラメータストアは1秒間に最大1,000リクエストがサポートされています。
インフラ構築という文脈では十分な数値といえます。

### Vault

Vaultのアーキテクチャはバックエンドストレージを信頼しておらず、Vaultサーバをとおるすべてのデータはセキュリティバリアという機構により自動的に暗号化されます。
セキュリティバリアからデータが読みとられると改ざんが検出されるなど、安全性を高める仕組みがあります。

またVaultサーバへのアクセスキーはShamir's Secret Sharingというアルゴリズムで分割されます。
これを複数の端末に配置することで、安全性を向上させることができます。

VaultにはDynamic Secrets: 有効期限つきの認証情報を動的に生成して安全性を高める機能があります。
たとえば有効期限つきのIAMユーザを作成できます。

## 選び方

パラメータストアはInfrastructure as Codeに必要な最低限の機能をもっています。
無料で使用できるため、パラメータストアをベースに考えます。

シークレットローテーションやパスワード生成の機能が必要で、AWSのその他サービスを利用しており、かつ有償サービスも採用可能な場合はSecrets Managerが候補になります。

Vaultはもっとも高機能ですが、その分学習コストがかかります。
OSS版の場合は運用コストも考慮しなければなりません。
セキュリティに対する要件が高かったり、Dynamic SecretsなどVaultでしか対応が難しい機能がある場合にはVaultの採用を検討するとよいでしょう。

Terraformなどでインフラを構築するときに安全性を高めるための機密情報管理サービスについて、AWS Secrets Manager、Systems Managerパラメータストア、Hashicorp Vaultの3つを比較します。

IaCにおける機密情報管理サービス比較: Secrets Manager, パラメータストア, Vault

Terraformはコードをどう配置するかというルールがありません。
だからといって自由にコードを書いてしまうと、コードを管理しづらくなったり、メンバーがコードの変更をキャッチアップしづらくなってしまいます。

Terraformのコードを扱うときは、どう管理するかというルールを定めることが大切です。
この記事では、Terraformにおけるディレクトリ構成の例を示します。

## この記事の目的

この記事の読者の対象はTerraformの基礎を理解している方で、Terraformのコードをどう設計または改善するかについて考えている方です。
ディレクトリの構成例にふれることで、プロダクトにあった構造をみつける参考になればと思います。

## 背景

Terraformはインフラをコードで定義し構築の自動化を行うソフトウェアです。
公式なプロバイダでAWSやGCPのリソース定義をできるのはもちろん、コミュニティプロバイダを使うことでSentryやStripeといったサービスの定義も行えます。
Terraformを使うことで、インフラを宣言的に管理できます。
バージョン管理を行えば差分がわかりやすくなり、コードを共有するメンバーもキャッチアップしやすくなります。

一方でTerraformを使うサービスや環境、プロバイダやリソースがふえたときに、基準となる指針がないと、コードがちらばりわかりづらくなってしまいます。
再利用できそうな、同じ責務をもつモジュールの存在に気づけないかもしれません。
こういった問題を起こさないような、チームにあった指針を決めることが大切になります。

## Terraformにおけるディレクトリ構成とは

この記事でいうディレクトリ構成とは「Terraformのコードをどう配置するか」をいいます。
`main.tf`や`variables.tf`、`outputs.tf`などのtfファイルやモジュールの構成をどうするか。
サービスや環境の種類をどう定義するか。
この課題をディレクトリ構成といいます。

### ディレクトリ構成の要件

この記事では、次の要件を満たすディレクトリ構成について示しています。

* メンバーがルールを把握しやすいこと
* コードを変更しやすいこと
* 複数のサービスに対応できること
* 複数の環境に対応できること
* 再利用性があること

## この記事の前提

この記事の前提として「Terraformのコードをひとつのチームで管理していること」を想定しています。
ひとつのチームで管理しきれない規模になるようであれば、リポジトリを分割するなどの戦略が必要になると思います。

また、Terraformには[Workspaces](https://www.terraform.io/docs/state/workspaces.html)というしくみがあります。
ただ、この記事ではWorkspacesには言及しません。
Workspacesは差分を吸収するためのコードが必要になり、わかりづらくなると考えているためです。

次章でディレクトリ構成を示していますが、これは例にすぎません。
最適なディレクトリ構成はサービスの種類やチームの状況によって異なり、ただひとつの正解はないと考えています。
重要なのはチーム内で指針をもつことです。
チームにあった指針を決めるときの参考になればと思います。

## ディレクトリ構成のベストプラクティス

ここではa.example.comとb.example.comという2つのサービスがあり、それぞれステージングと本番環境をもっていると想定します。
このときのディレクトリ構成を示します。

### 動作環境

この記事にあるコードは、次のバージョンで動作を確認しています。

| 名前 | バージョン |
| - | - |
| Terraform | 0.12.29 |

### ディレクトリ構成

まずディレクトリ構成を示し、次節でこの構成をもとにした設計指針を示します。
モジュールはAWS S3やHerokuなど、エントリポイントから参照されるものをいくつか示しています。

```
▼ modules
  ▼ aws-s3-bucket
      main.tf
      outputs.tf
      variables.tf
  ▶ heroku
  ▶ sentry
  ▶ stripe
▼ services
  ▼ a.example.com
    ▼ staging
        main.tf
    ▼ production
        main.tf
  ▶ b.example.com
```

### ディレクトリ構成の設計指針

上記ディレクトリ構成をもとに、設計指針の例を示します。

**最小限のモジュールをひとつの単位としてmodules下に配置する**。
たとえば「S3のバケットをつくる」「HerokuのWeb Dynoを起動する」など。
このときバケット名などは変数として定義します。
こうすることで再利用性が高まり、各サービスから参照しやすくなります。

**サービスをservices下に、各環境をサービスの下に配置する**。
たとえば`services/a.example.com/staging`。
サービス×環境のエントリポイントがすぐわかります。

**モジュールは3つのtfファイルのみをもつ**。
`main.tf`と`outputs.tf`、`variables.tf`の3つ。
これは[公式ドキュメント](https://www.terraform.io/docs/modules)にある最小限の構成で、名前の決め方やファイルのもつ役割がわかりやすくなります。

**エントリポイントにはバックエンドやプロバイダ、モジュール定義のみを行う**。
できるだけモジュールとして定義し、エントリポイントから使用することで、定義場所のゆらぎがなくなり、再利用性をもたせることができます。

## 備考

上記のディレクトリ構成例において、a.example.comとb.example.comを管理するメンバーが大きく異なる場合はリポジトリをわけた方がよいと思います。
またa.example.comとb.example.comで技術スタックが大きく異なる場合もわけた方がよいかもしれません。
ステートの規模も分割の基準になると思います。

## まとめ

モジュールをわけ、サービス×環境ごとにエントリポイントをもたせるディレクトリ構成例を示しました。
この構成にすることでサービスや環境、モジュールがふえても柔軟に対応することができます。

チーム内でディレクトリ構成の設計指針をもつことで、コードを変更するときの指針になり、またキャッチアップしやすくなります。
チームにあった構成をみつける参考になればと思います。

Terraformはコードをどう配置するかというルールがありません。だからといって自由にコードを書いてしまうと、コードを管理しづらくなったり、メンバーがコードの変更をキャッチアップしづらくなってしまいます。Terraformのコードを扱うときは、どう管理するかというルールを定めることが大切です。この記事では、Terraformにおけるディレクトリ構成の例を示します。

Terraformにおけるディレクトリ構成のベストプラクティス

ソフトウェアが運用段階に入ると、重要になってくるのが運用監視ですよね。ソフトウェアが動作するサーバを監視することで、ソフトウェアを正常に動作させ、また問題が起きそうなときにも、あらかじめ対策をとることができます。

私もよくサーバの運用監視を行うのですが、あらためて考え方を整理するために、運用監視の目的や種類、ツールなどについてまとめてみました。

## 想定している読者の方
この記事はエンジニアの方、とくに運用監視に携わる方、これから携わろうとしている方を対象としています。私はWebエンジニアなので、Web上のソフトウェアという文脈で書いていきます。

## サーバの運用監視とは
サーバの運用監視とは『**サーバが正常に動作しているか、また問題が起きそうでないかを継続的にチェックすること**』をいいます。

ここでいうサーバにはいろんな種類があります。Webサーバやデータベースサーバ、メールサーバなどがあります。こういったサーバの運用監視について次にまとめていきます。

## なぜサーバを運用監視するのか
サーバを運用監視する目的としては、大きく次の3つがあると思っています。

1. **サーバが正常に動作しているかをチェックするため**
2. **サーバに問題が起きそうなときに、あらかじめ対策をとるため**
3. **サーバに問題が起きたときに、すぐ復旧するため**

サーバを運用していると、いろんな問題が起きます。なんらかの問題でアプリケーションが応答しなくなったり、プロセスが止まったりします。CPUの使用率が高くなったり、メモリが枯渇して動作が遅くなることもありますね。

こういった問題の原因もいろいろあって、たとえば直近のリリースに不具合があったり、あるいはDDoSのような攻撃を受けて負荷が高まったことが理由になるかもしれません。

いずれにせよ、サーバに問題が起きてしまうと、ユーザの体験を損ねてしまいます。ビジネスの種類によっては**大きなトラブルに発展する**かもしれません。

問題が起きる前に対策をとり、問題が起きないようにする必要があります。また、問題が起きたときもすぐ復旧したいですよね。サーバの運用監視は、こういった目的のために行います。

:::note
**正常監視と異常監視**

サーバが正常に動作しているかどうかを確認することを正常監視、なんらかの異常が起きたときに運用者に通知することを異常監視といったりします。
:::

## サーバの運用監視の種類
ひとことで運用監視といっても、いろんな種類の監視があります。次に、一般的な監視の種類をまとめます。

1. **死活監視**
2. **リソース監視**
3. **サービス監視**
4. **プロセス監視**
5. **ログ監視**

### 1. 死活監視

外部から一定時間おきにPINGを送信して、正常なリクエストが返ってくるかどうかを監視します。サーバが正常に稼働しているかどうかをチェックできます。

### 2. リソース監視

サーバのCPUやメモリ、ディスクといったリソースを監視します。これらの値はサーバの応答速度の低下などの原因になります。しきい値を設定して運用者に通知することで、問題の予防につながります。

### 3. サービス監視

外部からインターネット経由でポートにリクエストを送り、HTTPやHTTPS、DNS、FTPといった基本的なサービスが正常に動作しているかどうかを監視します。

### 4. プロセス監視

データベースや他のアプリケーションのプロセスが正常に動作しているかどうかを監視します。

### 5. ログ監視

サーバで行った処理やイベントなどを記録したデータを監視します。サーバに問題が起きたときの調査に役立ちます。

## プッシュ型とプル型
サーバの運用監視の種類を上で示しました。次にこれを行うツールを示していきますが、その前提となるプッシュ型とプル型という概念について整理しておきます。これらはインストールの方法や特徴が異なります。

### プッシュ型

プッシュ型のツールは、監視対象となるサーバにソフトウェアをインストールすることで監視を行います。サーバを監視して、その結果を中央サーバに送信します。プッシュ型はサーバの詳細な情報を収集できるという特徴があります。ファイアウォールで外部からのアクセスが制限されていても問題なく監視できます。

### プル型

外部のサーバから監視対象となるサーバにリクエストを行うことで監視します。監視対象となるサーバが増減したら、設定を変更する必要があります。サーバに問題が起きたときにすばやく察知できるという特徴があります。

## サーバを運用監視するためのツール
それでは運用監視のためのツールをまとめます。実際に導入するときは、どの監視ができるのか、プッシュ型かプル型か、コストや操作性といった判断基準をもとに選択することになると思います。

ツールの機能やコスト、操作性などは今後変わる可能性があるので、詳細は比較はせず、ここではツールの一覧を示すにとどめます。

### プッシュ型

* [Sensu](https://sensu.io/)
* [Datadog](https://www.datadoghq.com/ja/)
* [Mackerel](https://mackerel.io/ja/)
* [New Relic](https://newrelic.com/jp)

### プル型

* [Zabbix](https://www.zabbix.com/jp)
* [Nagios](https://www.nagios.org/)
* [Prometheus](https://prometheus.io/)

:::notice
プル型のツールでも、プッシュ型として監視するための手段があるものがあります。
:::

## 問題発生時の通知方法
上でも書いたのですが、サーバの運用監視の目的は**予防**と**原因特定**です。問題が起きそうなとき、あるいは実際に起きたときに、メールやチャットツール、電話などで通知することで対応を行うことになります。

ただ、すべての問題を同じ方法で通知してしまうと、運用担当者の負担がふえてしまいます。通知する相手も設定できると、負担の軽減につながります。こういった、問題のレベルに応じた適切な通知をとる手段があるといいですね。

このことを実現する方法として、[PagerDuty](https://ja.pagerduty.com/)のような**インシデント管理ツール**があります。これは運用監視ツールのアラートを一箇所に集約して、問題のレベルに応じて通知対象や通知方法を柔軟に設定することができます。

問題が発生したときの対応に課題が出てきたら、導入を検討してみるといいかもしれません。

## まとめ
サーバの運用監視は、サーバを正常に動作させたり、問題の予防や問題が発生したときにすぐ対応するために重要な役割を果たします。運用監視には死活監視やリソース監視など、いくつかの種類があります。

運用監視のツールを選ぶときは、どの監視ができるか、動作方法はプッシュ型かプル型かなどをもとに選ぶことになります。

### 参考文献

* [第17回 サーバ運用監視のノウハウ（その1）](https://gihyo.jp/design/serial/01/hosting_department/0017)
* [サーバの死活監視から性能監視は具体的にどの範囲まで必要なのか](https://cybersecurity-jp.com/security-measures/8152)

ソフトウェアが運用段階に入ると、重要になってくるのが運用監視です。ソフトウェアが動作するサーバを監視することで、ソフトウェアを正常に動作させ、また問題が起きそうなときにも、あらかじめ対策をとることができます。この記事ではサーバの運用監視の目的や種類、ツールなどについてまとめてみました。

サーバの運用監視の種類とツール。死活監視、ログ監視など

ソフトウェアを開発する上で、テストに携わることがあると思います。アジャイル開発においても、Product/Market Fitを達成した後はソフトウェアの品質がより重要になってきます。

今回は私がチームでテストの書き方について共有するために、テストケースとはなにか、作り方や観点、書き方などについての基本的な内容をまとめてみました。テストを行う際の参考になればうれしいです。

:::note
**この記事の対象となる読者の方**

この記事は、ソフトウェアのテストに関わる方、とくにテストの経験が長くない方を対象としています。また、筆者はWebエンジニアなので、その文脈でまとめています。
:::

## テストケースとは
テストケースとは、『**ソフトウェアのテストをどう実施するかが書かれた手順書**』のことをいいます。テストケースをもとに、手動でテストを行ったり、自動テストを書いたりします。

まずはじめに、この記事の前提知識として**テストの種類**と**テストケースの種類**についてまとめます。

### テストの種類

ソフトウェアのテストにはいろんな種類があります。たとえば、代表的なものの中に次の3つがあります。

| 種類 | 説明 |
| - | - |
| **ユニットテスト** | モジュールのメソッド単体に対するテスト |
| **インテグレーションテスト** | モジュール間の連携に対するテスト |
| **システムテスト** | ユーザ視点でのインタフェースをとおしたテスト |

### テストケースの種類

また、ソフトウェアのテスト方法を示すテストケースには、正常系と異常系というふたつの種類があります。

| 種類 | 説明 |
| - | - |
| **正常系** | 想定している入力に対して期待どおりの出力を行うか |
| **異常系** | 想定していない入力に対して問題なく対処できるか |

いろんな種類のテストについて、正常系と異常系をもとにテストの手順を書いていくのがテストケース、ということになります。また、テストケースは手順書なので、つまり読み手がいることになります。読み手がわかるような文章を心がけて書くとよいですね。

:::info
ユニットテストなどいろんな種類のテストについて、正常系と異常系をもとにテストの手順を書くのがテストケースです。
:::

## なぜテストケースを作るのか
そもそもなぜテストケースを作る必要があるのでしょうか。テストケースは『それをもとにテストを行う』というのはもちろんそうですが、品質という意味でも次の3つの目的があります。

1. **必要なテストを漏れなく実施するため**
2. **不要なテストを削除するため**
3. **誰が行っても同じテストにするため**

### 1. 必要なテストを漏れなく実施するため

テストケースは、ソフトウェアのあるべき姿を記述したものといえます。必要なテストがないと、提供したい機能がバグなどの理由で提供できなくなるかもしれません。**とくに、異常系のテストケースは足りなくなりがち**です。

こういったテストの漏れは、テストケースを書くことで解消できます。テストケースがあることでレビューができるため、**レビューをとおして漏れを防ぐ**ことができます。

テストケースを作るとき、作成者がシステムやビジネスに完全に通じているとは限りません。作成者のみでテストケースの作成を完結すると、漏れが出るかもしれません。システムやビジネスに詳しいメンバーからのレビューを行うことで、不足したテストケースを追加することができます。

システムのすべてのバグを防ぐことは難しいですが、限りなく減らすことはできます。リリース後の不具合によるコストはテストのコストより大きくなってしまうので、その意味でもテストケースをしっかり作る必要があります。

### 2. 不要なテストを削除するため

必要なテストが漏れるのはよくありませんが、一方で網羅製を担保しようとして**テストケースを無駄にふやしがち**になるという問題もあります。

テストケースは多すぎてもよくありません。テストを行うことはコストになりますし、テストケースを維持するのにもコストがかかります。そもそも同じ目的のテストケースはいくつあっても品質の向上にはつながりません。

テストに詳しいメンバーからのレビューをとおして不要なテストケースを削除することで、コスト削減などのメリットにつながります。

### 3. 誰が行っても同じテストにするため

テストを手動で行う場合、テストを行う人のテストスキルによってシステムの品質に差が出てしまってはいけません。自動テストにおいても、同じく実装者によって差が出てしまわないようにしなければなりません。

テストケースを作ってレビューすることで、テストの品質を高い水準に保つことができるようになります。

## テストケースの作り方
それでは、実際にテストケースの作り方についてまとめていきます。テストにはユニットテストやシステムテストなどいろいろな種類があると書きましたが、基本的な作り方は次のような形になると思います。

| 順番 | 項目 | 内容 |
| :-: | - | - |
| 1 | **前提条件** | テスト対象の前提となる値や状態はなにか |
| 2 | **手順** | どのようにテストするか |
| 3 | **入力値** | どのような値を入力するか |
| 4 | **期待する結果** | どのような結果を期待しているか |

### テストケースの例

たとえば、分かりやすい例として『一桁の自然数同士のかけ算をする計算機能』のテストケースについて考えてみます。一桁の自然数とはつまり1〜9の値を取りうるのですが、次のようなテストケースができます。

| 項目 | 内容 |
| - | - |
| 前提条件 | 5が入力されている |
| 手順 | かけるボタンを押す |
| | 入力値を押す |
| | 計算ボタンを押す |
| 入力値 | 6 |
| 期待する結果 | 30が表示されている |

## テストケースの入力値
前で書いたテストケースの例は、必要なテストケースのひとつでしかありません。一桁の自然数同士のかけ算、つまり1〜9同士の掛け算になるので、全部で81通りの組み合わせがあります。

また、入力可能性という意味では無限にあり得ます。不正な入力として0や-1が入力される可能性も考慮しなければなりません。

この組み合わせについて、すべてのケースをテストするのは大変で、コストもかかります。このようにテストケースが多いときに、**品質をある程度保ちつつケースを減らす方法**として、次の4つがあります。

1. **同値分割**
2. **境界値分析**
3. **ペアワイズ法**
4. **エラー推測**

### 1. 同値分割
同値分割は**入力をグループ化して、有効なものと無効なものに分けるやり方**です。たとえば『一桁の自然数』が入力だとすると、

* 1より小さい
* 1〜9
* 9より大きい

の3つのグループに分けることができます。つまり、入力値としてたとえば0、5、10の3つにすればよい、ということになります。

### 2. 境界値分析

同値分割において、経験則的に**同値グループ間の境界にバグが発生しやすい**ということが分かっています。上の例でいうと、0と1、9と10などですね。このような境界値では等号や不等号のミスなどでバグが起きやすくなっていて、これを境界値分析で検出することができます。

### 3. ペアワイズ法

『ほとんどの不具合は1つまたは2つの要因によるものである』という経験則をもとにした方法で、たくさんある要因のうち**2つの要因の組み合わせだけは網羅する**、という観点で値を選ぶのがペアワイズ法です。

上の計算機能の例では要因は2つですが、テストの対象によってはもっと多くなるパターンも出てくると思います。ペアワイズ法を用いることで、組み合わせの数が多いときにテストケースを大きく削ることができます。

一方で、ペアワイズ法では本来検出できたはずのバグを取りこぼす可能性もあります。ペアワイズ法だけでテストせずに、組み合わせを選ぶときの参考にする程度でよいのかな、と思っています。

:::info
ペアワイズ法により組み合わせを選ぶやり方として、マイクロソフト社製の[PICT](https://github.com/microsoft/pict)というツールがあります。
:::

### 4. エラー推測

これは上の3つの方法論とはちょっと変わっているのですが、**テストケースを作る人の経験に基づいてエラーが起きそうな値を決めるやり方**です。たとえば『一桁の自然数』という入力値に対して、負の数やヌル文字、空白、全角文字や小数などを用いてテストします。

## テストケースの観点
ここまででテストケースの作り方と、入力値の選び方について書いてきました。最後に、テストケースを作るときの観点をざっとあげてみます。テストケースを作る対象のシステムによって違うと思いますが、参考になればと思います。

### 全般

* 入力に対する結果は正しいか
* 想定していない入力に対処できるか
* 入力の型や文字コードの種類は想定されているか
* 不適切な入力は想定されているか
* リクエストに対するレスポンスは正しいか

### データ

* レコードは正しく更新されているか
* トランザクションは考慮されているか

### セキュリティ

* 脆弱性は考えられないか
* 認証、認可のロジックは問題ないか
* 認証、認可失敗時の動作は問題ないか

### エラー

* エラー処理はされているか
* 例外処理はされているか

### 画面

* データがないときの処理・表示は問題ないか
* 文言は正しいか
* 画面の遷移先は正しいか

### アクセス

* 多重実行は考慮されているか
* 遅いネットワーク環境での利用は考慮されているか
* 処理がキャンセルされた場合は考慮されているか
* 同時アクセスは考慮されているか
* 同一ユーザの複数端末からの利用は想定されているか
* 利用環境の差異（OSやブラウザなど）は想定されているか
* 利用者の役割（ゲスト、管理者など）は考慮されているか

### 環境

* 実行環境の差異（開発環境、本番環境など）は想定されているか
* 時間やタイムゾーンの問題はないか

### 通信

* APIなどの通信先は正しいか
* APIなど通信先のステータスは考慮されているか
* 非同期処理のタイミングによるデータの有無は考慮されているか
* 非同期処理は必要なところでされているか
* メールやチャットなどへの通知は行われているか、送り先は正しいか

## いつテストケースを作るか
たとえばアジャイル開発においては、継続的にソフトウェアを変更するので、最初からすべてのテストケースを作ることはないと思います。変更を行うときに、変更とセットでテストケースを作ることになると思います。

たとえば、GitHubのプルリクエストをとおして変更を適用している場合は、プルリクエストの本文にテストケースを書き、テストコードとあわせてレビューすればよいのかな、と思います。

## まとめ
この記事では、テストケースとはなにか、目的や作り方についてまとめました。システムの種類やビジネス形態によって書くべきテストも変わってくるので、目的にあわせてテストケースを作れるようになりたいですね。

### 参考文献

* [テストケース作成で気をつけるべき3つのポイント！ソフトウェアテストを効率よく行う方法](https://goworkship.com/magazine/test-case/)
* [テスト観点レビュー時のチェックポイント](https://medium.com/wingarc/%E3%83%86%E3%82%B9%E3%83%88%E8%A6%B3%E7%82%B9%E3%83%AC%E3%83%93%E3%83%A5%E3%83%BC%E6%99%82%E3%81%AE%E3%83%81%E3%82%A7%E3%83%83%E3%82%AF%E3%83%9D%E3%82%A4%E3%83%B3%E3%83%88-932adf70111d)

この記事では、私がチームでテストの書き方について共有するために、テストケースとはなにか、作り方や観点、書き方などについての基本的な内容をまとめてみました。テストを行う際の参考になればうれしいです。

テストケースの作り方。目的や観点、書き方の例

チームで開発をするとき、技術選定をすることがあります。どの技術を使うべきか、説明責任もともなうので、よく悩みます。自分の中で判断基準を明確にもっておくために、技術選定のポイントについてまとめてみました。

この記事では技術選定とはなにか、なぜ技術選定をするのか、技術選定のポイントを書いていきます。技術選定をするときの参考材料になればうれしいです。

## 想定している読者の方
この記事は、エンジニアの方、とくに開発をリードされている立場の方を想定して書いています。また、個人で開発している方にも参考になるかと思います。

## 技術選定とは
この記事でいう技術選定とは、その名のとおり『**どんな技術を使うかを選ぶこと**』です。領域はインフラやサーバサイド、フロントエンド、また種類としては言語やフレームワーク、ミドルウェアなどが対象になります。

この記事ではライブラリの選定基準については書いていません。これについては次の記事で詳しく書いていますので、あわせてご覧ください。

:link{slug=criteria-for-selecting-libraries}

## なぜ技術選定をするのか
技術選定の目的は『**事業価値を最大化するため**』だと考えています。技術選定というと、ついシステム要件を満たすために決めてしまいがちです。もちろんこれも必要ですが、選定のポイントという意味では一部でしかありません。

企業において、開発は事業を運営するために行います。OSSの場合は『事業』を『ソフトウェア』に置き換えられると思いますが、使う技術は事業に大きく影響します。たとえば、技術を使える人の採用コストだったり、運用コストなどが分かりやすい例ですね。

どの技術を使うかは自由度がとても高い一方で、選択を間違えると長期的にみて事業に大きな損失を与えることもあります。そのため、技術選定をする上では基準を設けるべきといえます。

:::info
技術選定は事業価値を最大化するために行います。使う技術によって採用コストや運用コストが大きく変わるので、基準を設けた上で検討した方がよいといえます。
:::

## 技術選定のポイント
それでは、技術選定のポイントを次に書いていきます。ポイントを『機能』『人』『信頼性』『経済性』の4つに分類しています。お互い重複する要素もありますが、検討しやすいようにしています。

### 1. 機能

技術の機能面については大きく次の3つがあります。そもそもの前提条件となるポイントが多いですね。

| 番号 | ポイント | 備考 |
| :-: | - | - |
| 1 | **要件を満たせるか** | 要件を満たす上で必要な機能をもっているか |
| 2 | **ユーザ体験** | 基準以上のユーザ体験を提供できるか |
| 3 | **パフォーマンス** | 基準以上のパフォーマンスであるか |

### 2. 人

技術を使う人に焦点をあてたポイントです。個人的にはほかの評価軸を満たしつつ、いかにメンバーのモチベーションが高い技術を選択できるか、が大切だと思っています。

| 番号 | ポイント | 備考 |
| :-: | - | - |
| 1 | **人材流動性** | 技術を使える人が転職市場にどれくらいいるか |
| 2 | **学習コスト** | 技術を使えるようになるのにどれくらい学習の必要があるか |
| 3 | **開発規模** | 開発者の人数に適しているか |
| 4 | **習熟度** | メンバーはその技術にどれくらい習熟しているか |
| 5 | **モチベーション** | メンバーはその技術を使うモチベーションが高いか |

### 3. 信頼性

技術の信頼性についてのポイントです。コストがかかるものほど信頼性についての説明責任が問われてくると思うので、しっかり判断したいところです。

| 番号 | ポイント | 備考 |
| :-: | - | - |
| 1 | **信頼性** | 機能は安定して提供されるか |
| 2 | **セキュリティ** | セキュリティ要件を満たせるか |
| 3 | **メンテナンス** | 機能は継続的なメンテナンスを期待できるか |
| 4 | **利用実績** | 機能は十分な利用実績や事例があるか |

### 4. 経済性

コストなどの経済性についてのポイントです。スイッチングコストについてはデータベースなど低いレイヤーに行くほど乗り換えづらいので、慎重に評価したいところです。

| 番号 | ポイント | 備考 |
| :-: | - | - |
| 1 | **利用コスト** | 利用するのにどれくらい費用がかかるか |
| 2 | **スイッチングコスト** | 機能を乗り換えるのにどれくらい費用がかかるか |
| 3 | **開発生産性** | 開発効率はどれくらいか |

## 事業のフェーズによる技術選定
技術選定をするときは、**事業のフェーズによって評価軸を変える**ことが重要になってきます。

事業を立ち上げて、最初にめざすのはProduct/Market Fitです。つまり、市場に求められるプロダクトにすることです。このPMF達成までは、なによりも開発スピードが求められます。

PMFを達成したら、プロダクトの価値がユーザに受け入れられたということになります。経済的にも持続可能であることが評価できました。このタイミングでは、開発スピードから安定性などに評価軸を移していきます。

開発スピードがはやいといわれる技術にRuby on Railsがあります。たとえば、PMFまではRailsでWebアプリケーションとしてつくります。PMF達成後にパフォーマンスが重要なポイントが見えてきて、かつネイティブアプリ化のニーズが出てきたときに、APIとしてGo、フロントエンドにTypeScript+Reactを選びます。

こういったように、事業のフェーズによって技術選定をする上での評価するポイントを柔軟に変えていくといいと思います。

:::note
**事例: Twitter**

TwitterはもともとRuby on Railsで書かれていましたが、JavaやScalaといったJavaVMに移行しました。この理由として、ユーザからのリクエストがふえた結果、非同期処理やVMの性能などがより重要になってきたため、としています。

事業のフェーズによって解決すべき課題が出てきたときに、これまでの評価軸とは視点を変えて技術を選定する必要があることがわかる事例ですね。

参考：[Twitterが、Ruby on RailsからJavaVMへ移行する理由](https://www.publickey1.jp/blog/11/twitterruby_on_railsjavavm.html)
:::

## まとめ
技術選定は、事業価値を最大化するために行います。技術選定をする際は、なぜそれを使うかという理由をもっておく必要があります。これは、機能、人、信頼性、経済性を基準に行うやり方があります。

技術選定は事業のフェーズによって評価軸を変えることで、事業価値の最大化につながっていきます。

### 参考文献

1. [技術選定と、組織のかたちと、セキュリティ](https://diary.shift-js.info/tech-and-org-and-security/)
2. [理想の技術選定](https://note.com/timakin/n/n2d9eaa02e633)
3. [Kibela開発における技術選択の指針を全部教える。必要十分に新しい技術を維持するための考え方](https://eh-career.com/engineerhub/entry/2019/04/05/103000)

チームで開発をするとき、技術選定をすることがあります。どの技術を使うべきか、説明責任もともなうので、よく悩みます。自分の中で判断基準を明確にもっておくために、技術選定のポイントについてまとめてみました。

エンジニアのための技術選定のポイントとやり方

ソフトウェアを開発する上でしっかりと対応しておきたいのがログの出力ですよね。私は以前、運用しているWebアプリケーションのログ出力が不十分だったため、問題が起きたときに原因の調査ができなかったという経験があります。そのときから、ログの出力について気をつけるようにしています。

この記事ではログの出力を設計する指針について、書き方やフォーマットの例をもとに整理します。ログを設計するときの参考になればうれしいです。

:::note
### この記事で対象としている読者の方

この記事はソフトウェア開発に携わるエンジニアの方を対象としています。私はWebエンジニアなので、Webアプリケーションという文脈でログ出力の設計について書いています。
:::

## ログ出力の設計指針とは
まず、ログとは**アプリケーションやサーバ、ソフトウェアなどが出力する、時系列に記録されたデータ**のことをいいます。アプリケーションが出力するログやデバッグログ、Webサーバのアクセスログやエラーログなどですね。

ログの種類によって、出力の設計指針は変わってくると思います。この記事では、いろんなログに共通する汎用的な内容として、アプリケーションログの出力を例に設計指針について書いていきます。

ログ出力の設計指針は、開発するソフトウェアによっても変わってきます。大切なことは、チームで指針をもってログ出力を行い、しっかりと運用していくことだと思います。

:::info
### ログ出力の設計指針とは

ログ出力の設計指針とは、アプリケーションなどのログの出力をどう設計するかという指針のことをいいます。
:::

## なぜログを出力するのか
これからログ出力の設計指針について書いていくのですが、そもそもなぜログを出力する必要があるのでしょうか。これは、大きく次の4つがあると思っています。

1. **問題が発生したときに調査するため**
2. **問題の発生を防ぐため**
3. **データ分析をとおしてソフトウェアを改善するため**
4. **監査ログとして利用するため**

ひとつずつ見ていきます。

### 1. 問題が発生したときに調査するため

Webアプリケーションを運用していると、サーバがダウンしてしまったり、レスポンスが遅くなったりすることがあります。こういった問題が発生したときに、**発生した時間のログを見る**ことで、原因が分かったりします。

また、ユーザに問題が起きたときにも役立ちます。ユーザから問い合わせがあったときに、ユーザのアカウント情報と突き合わせて調べることで、ユーザに起きた問題の原因が分かることがあります。

### 2. 問題の発生を防ぐため

問題が起きていなくても、**問題が起きる予兆**があったりします。たとえば同一のIPアドレスから連続してアクセスを受けることがあります。このときにIPアドレスに対する制限を行うなどすることで、問題の発生を防げることがあります。

### 3. データ分析をとおしてソフトウェアを改善するため

ログは、ソフトウェアを改善するためにも役立ちます。ユーザの行動を分析して学習し、機能や施策につなげることでユーザ体験を向上することができます。

### 4. 監査ログとして利用するため

たとえば[PCI DSSというセキュリティ基準](http://www.intellilink.co.jp/article/pcidss/02.html)では、監査ログを最低3ヶ月間は保管しなければならないとしています。ソフトウェアによっては、こうした基準を満たすためにログを出力する必要があったりします。

## ログ出力の設計指針
それでは、具体的にどうログ出力を設計すればよいのでしょうか。まず前提として、**ログには読み手がいる**ということを意識します。どういうケースで、どういう読み方を想定しながらログ出力を設計することが大切といえます。

ログ出力は、5W1Hにもとづいて設計するとよいといわれています。たとえば、次のような項目をログに出力するようにします。

| 項目 | 内容 | 備考 |
| - | - | - |
| **時間** | ログを記録した時間 | 年月日時分秒ミリ秒 |
| **ID** | イベントのID | 一連のイベントを関連づけるために必要 |
| **ログレベル** | ログのレベル | INFOやWARNなど |
| **ユーザ情報** | リクエストしたユーザの情報 | ユーザIDやIPアドレスなど |
| **リクエスト対象** | どこにリクエストしたか | URLなど |
| **処理内容** | どんな処理を行なったか | 参照や更新、削除など |
| **処理対象** | なにを処理したか | リソースのIDなど |
| **処理結果** | 処理した結果どうなったか | 成功または失敗、処理件数など |
| **メッセージ** | その他出力したいこと | - |

ログ出力のメッセージは、できるだけシンプルに書くことで読み手に伝わりやすくなります。また、エラーが発生したときはスタックトレースを出力することで調査しやすくなります。

### ログレベル

上で書いた項目の中にログレベルというものがあります。これはINFOやWARNなど、そのログのレベルを表します。

ログ出力にはログレベルを書くケースがほとんどだと思います。ログレベルは、**読み手がほしい情報を適切に伝えるため**に役立ちます。ログレベルには、次のような種類があります。

| レベル | 概要 | 説明 |
| - | - | - |
| **FATAL** | 致命的なエラー | アプリケーション全体が提供できない |
| **ERROR** | エラー | ユーザのリクエストが処理できない |
| **WARN** | 警告 | アプリケーションは提供できるが対応が望まれる |
| **INFO** | 情報 | 記録しておくべき情報 |
| **DEBUG** | デバッグ情報 | 動作に関する情報 |
| **TRACE** | トレース情報 | 動作に関する詳細な情報 |

たとえば、状況を確認するのに必要な情報をDEBUGレベルにしてしまうと、INFO以上を表示するときに表示されなくなってしまいます。INFOを見るときはどういう状況か、DEBUGを見るときはどういう状況かなど、読み手を想定して適切にログレベルを設定すべきだといえますね。

### なにを記録するか

ログ出力のフォーマットについては上で書きましたが、具体的にどのようなイベントを記録すればよいのでしょうか。たとえば、次のようなイベントについてログに出力します。

* ユーザが画面上で行うイベント全般
* 認証やサインアウト
* アカウント管理、パスワード変更
* 重要な情報へのアクセス
* エラーが発生したとき

### なにを記録しないか

上で記録すべき情報について書きましたが、逆に**記録すべきでない情報**もあります。主にセキュリティの観点になるのですが、たとえば次のような情報は記録すべきでありません。あるいはマスク処理を行う必要があります。

* パスワード
* OAuthなどの認証情報
* 個人情報

## ログ出力を設計するときに注意すること
ログは問題が発生したときの調査や問題の予防などに役立ちますが、一方で**サーバに負荷がかかる行為**でもあります。ログを出力することでサーバにパフォーマンス上の問題が起きたときは、出力の設計指針を見直す必要がありそうです。

## まとめ
アプリケーションのログを出力することで、問題が起きたときの調査に役立ったり、問題の予防につなげることができます。

ログ出力を設計するときは、読み手がほしい情報を想定して、適切な情報をふくめるとよいですね。ログ出力はサーバのパフォーマンスに影響するので、サーバの監視もあわせて行うべきといえます。

### 参考文献

* [Webアプリケーションのログ出力について指針を考えてみた](https://blog.mmmcorp.co.jp/blog/2018/05/25/web_application_logging/)
* [6W2Hでログ設計の考慮事項を考えてみた](https://www.dfour.net/logs-6w2h/)
* [ウェブサービスのログ設計についてメモ](http://gan.hatenablog.jp/entry/2013/09/08/012437)

ソフトウェアを開発する上でしっかりと対応しておきたいのがログの出力です。この記事ではログの出力を設計する指針について、書き方やフォーマットの例をもとに整理します。ログを設計するときの参考になればうれしいです。

ログ出力のイメージ

ログ出力の設計指針。書き方、フォーマットの例

今回は、ローカルに開発環境を構築するときに、どの方法で作ればいいか？について書きたいと思います。手動でやるか、あるいはVagrantやDockerなどの仮想化技術を用いるか、などですね。

開発環境の構築は、新しくメンバーが入ったときなどにまずやる事になると思います。ここがしっかりできていると、オンボーディングの体験がよくなりますね。逆になかなか開発環境の構築ができないと、不安にさせてしまうかもしれません。

開発環境の構築は、地味だけどしっかりと整えておきたいところです。この記事では私がチームで開発したときにつまずいた経験などを元に整理してみます。開発環境を構築するときの参考になればうれしいです。

:::note
### この記事の対象となる読者の方

この記事は、開発環境を準備しようとしているエンジニアの方を対象としています。新しいメンバーを迎え入れる予定の方など、ですね。ソフトウェアの種類は、WebアプリケーションをGitで管理しているような構成を想定していますが、そうでなくても参考になるかと思います。
:::

## ローカルの開発環境とは
この記事でいうローカルの開発環境とは、『**ソフトウェアの開発をローカルの端末で行うための環境**』のことをいいます。開発環境の構築の流れはプロジェクトによって違うと思いますが、基本的には次のような形になると思います。

1. ソースコードをダウンロードする
2. 依存ライブラリをインストールする
3. ミドルウェアをダウンロード、インストールする
4. 環境変数を設定する
5. ミドルウェアを立ち上げる
6. 開発用のデータを挿入する
7. アプリケーションを起動する

他にも、ソフトウェアの種類によってはホストの設定などが必要になったりしますね。こうした手順をとおして開発のための準備を行うのが、ローカルの開発環境構築になります。

:::info
### まとめ：ローカルの開発環境とは
『ソフトウェアの開発をローカルの端末で行うための環境』をローカルの開発環境としています。
:::

## いつローカルに開発環境を構築するか
ローカルに開発環境を構築するときは、どんなときがあるでしょうか。たとえば次のようなときに開発環境を構築すると思います。

* **端末が新しくなったとき**。端末が故障した、買い替えたときなど
* **新しくメンバーが入ったとき**
* **開発環境が動かなくなったとき**。ミドルウェアの実験などで起こったりする

実際にソフトウェアを開発していると、開発環境を構築するタイミングは思ったよりあると思います。開発に携わるメンバーがふえるほど、その機会もふえていくことになりますね。

## なぜローカルに開発環境を構築するのか
ローカルの開発環境を構築する目的は、**ソフトウェアの開発などの作業をローカルで行えるようにするため**です。

『開発など』としたのは、開発環境を構築するのはエンジニアだけではないからです。デザインの検証をするためにデザイナーの方が行うかもしれませんし、データ分析のためにビジネスサイドのメンバーが行うこともあると思います。

このため、ローカルでの開発環境の構築は『手元で動作させたいと思った人が構築できる』くらいハードルが低い方がいいといえますね。

## ローカルの開発環境の構築方法を決めるときの指標
ローカルに開発環境を構築する方法はいくつかあります。それらを見る前に、開発環境を構築するときに考慮するべき指標を次にまとめてみます。

| 番号 | 指標 | 備考 |
| :-: | - | - |
| 1 | **自動化のコストが低いこと** | - |
| 2 | **構築が簡単であること** | 少ない手数で構築できるか |
| 3 | **起動が簡単であること** | 少ない手数で起動できるか |
| 4 | **起動が早いこと** | - |
| 5 | **端末によらないこと** | WinやMac、Linuxで使えるか |
| 6 | **開発体験がいいこと** | デバッグやテストはしやすいか |
| 7 | **消費メモリが少ないこと** | - |
| 8 | **再現性があること** | どの端末の環境で行っても同じ結果になるか |
| 9 | **インフラの知識がいらないこと** | 起動に知識は必要ないか |
| 10 | **本番環境と差がないこと** | - |
| 11 | **構成を把握しやすいこと** | コードを見て構成が分かるか |
| 12 | **環境が汚れないこと** | 端末にインストールや設定をしないか |

これらの指標を押さえつつ、ではローカルに開発環境を構築するときにどの方法を選択していけばいいかを次に書いていきます。

## ローカルに開発環境を構築する方法の比較
前の章で書いた指標をふまえた上で、ではどのような方法が考えられるのかについて書いていきます。

まず、ローカルに開発環境を構築するには、大きく『**手動でやるか**』『**自動化するか**』に分けられます。また、自動化についても、仮想化の手法が『**ホスト型**』か『**コンテナ型**』かに分けられます。

この上で、ローカルに開発環境を構築する方法として次の3つについて考えます。

1. **手動で端末上に構築する**
2. **ホスト型の仮想化ソフトウェア上に構築する**
3. **コンテナ型の仮想化ソフトウェアを用いて構築する**

### 1. 手動で端末上に構築する

まずひとつめは、その名のとおりソースコードのダウンロードやライブラリのインストール、ミドルウェアの準備などを手動で、ローカルの端末に対して行う方法です。

ソフトウェアの種類によりますが、起動が早く、またデバッグがしやすい、テストの実行が早いといったメリットがあります。**開発環境の構築を自動化するコストをかける必要がない**という最大のメリットがあります。

この方法は、チームメンバーがひとりまたは数人で、かつソフトウェアがProduct/Market Fitを達成しておらず、開発スピードがなにより重要なタイミングで積極的にとりたい方法といえます。

### 2. ホスト型の仮想化ソフトウェア上に構築する

VagrantやVirtualBoxを用いてローカルの端末に仮想的なOSを立ち上げて、Ansibleなどのプロビジョニングツールを用いて開発環境を構築する方法です。

OSを自由に使えるので、開発するソフトウェアがカーネルパラメータを設定するなど**OSと関わりが強いものであれば、この方法が適している**といえます。また、ローカルの端末のOSがWindowsでもMacでも差が出ません。

本番環境でコンテナを使っていない場合、ローカルの開発環境と本番環境で差をなくすことができます。プロビジョニングツールで構成をコードとして記述するので、どんなミドルウェアが使われているかも把握しやすいです。仮想的なOSを使うので、端末の環境も汚れませんね。

一方で、この方法は**プロビジョニングに時間がかかる**というデメリットがあります。OSから立ち上げるので、起動も遅く、消費メモリも大きくなりがちです。

仮想化ソフトウェアのバージョンによって起動できないなどのトラブルがなにかと起きたりします。インフラの知識がないと対応できないことが出てきます。

### 3. コンテナ型の仮想化ソフトウェアを用いて構築する

ローカルの端末のOSやカーネル部分を使って、ミドルウェアなどのコンテナを立ち上げることで開発環境を構築する方法です。たとえばDocker Composeを用いれば、コマンドひとつで開発環境が立ち上がります。**起動も早い**です。

ファイルに定義した内容で開発環境が立ち上がるので、使っているミドルウェアなどの構成が把握しやすく、依存関係も定義できるので再現性もあります。

起動する人はインフラの知識がほとんど入らないので、**デザイナーなど非エンジニアの方でも環境を作りやすい**ですね。本番環境でコンテナを使っているなら環境に差も出ませんし、開発端末の環境も汚れません。

ただ、Macで遅いという問題があります。いくらか早くするためのチューニングの方法はありますが、自動化のコストがかかるといえます。

## ローカルに開発環境を構築する方法
以上のことをふまえて、ソフトウェアの種類やチームの状況に応じた選択について案を書いてみます。

まず大前提として、どの方法を使うかは**本番環境の構成に大きく依存する**と思っています。本番環境がコンテナを利用していれば上記の3、そうでなければ2か3がとり得るかなと思います。

『1. 手動で端末上に構築する』は、開発メンバーが1〜3人くらいで、ソフトウェアがProduct/Market Fitを達成しておらず、開発スピードがなにより重要なときにとり得る方法といえます。**ギリギリまでこの方法でがんばりたい**ですね。

『2. ホスト型の仮想化ソフトウェア上に構築する』は、本番環境にコンテナを利用しておらず、Ansibleなどのプロビジョニングツールで構築している場合に適しています。**ソフトウェアがカーネルと深く関わっている**ときはこの方法が開発しやすいですね。

この方法は開発環境を構築するのがほとんどエンジニアの場合のみに採用するのがよさそうです。開発メンバーが使っているOSがWindows/Macなどいろいろある場合はこの方法が差が出にくいのでいいかもしれません。

『3. コンテナ型の仮想化ソフトウェアを用いて構築する』は、**本番環境にコンテナを使用している場合**に積極的にとりたい方法です。非エンジニアの方でも環境構築しやすくしたい場合にも有用ですね。

個人的には、ギリギリまで手動で構築しつつ、必要なタイミングでDocker Composeを用いて自動化する、というやり方がいいと思っています。これはソフトウェアの種類やチームの状況によって変わるので、参考程度にしていただければと思います。

:::info
### まとめ：ローカルに開発環境を構築する方法

自動化が必要になるギリギリのタイミングまで手動でがんばりつつ、必要になったらコンテナ型の仮想化による自動化を優先的に考え、必要に応じてホスト型の仮想化で自動化を選択すればよさそうです。
:::

## 開発環境の自動化において大切なこと
ローカルへの開発環境の構築を自動化するときに大切なことは、**自動化したコードをメンテナンスすること**だと思います。

開発環境の構築を自動化したはいいものの、メンテナンスされておらず、新しく構築する人がすんなりと構築できないケースをよく見ます。たとえば、新しく構築を試して、できなかったら修正し、自動化のコードを変更するルールを導入するなど、**仕組みもセットで決めるべき**かな、と思っています。

## まとめ
ローカルに開発環境をスムーズに構築できると、新しいメンバーのオンボーディングもふくめてチームの生産性が大きく向上すると思います。メンバーやチームの状況に応じて適切な方法で構築できる仕組みがあるといいですね。

### 参考文献

* [ピクスタ開発部でローカル開発環境構築自動化コンペを開催しました](https://texta.pixta.jp/entry/2017/01/10/184141)
* [webサービス開発における良い開発環境](https://qiita.com/reireias/items/2597871afb76086a6d21)
* [チーム開発の開発環境として Docker + Vagrant を選択し続ける理由](https://toris.io/2016/12/the-reason-why-we-continue-to-choose-docker-and-vagrant-as-our-dev-stack/)

ローカルに開発環境を構築するときに、手動でやるか、あるいはVagrantやDockerなどの仮想化技術を用いるか。どの方法で作ればいいか？について、私がチームで開発したときにつまずいた経験などを元に書いています。

ローカルに開発環境を構築するイメージ

ローカルの開発環境の構築におすすめの方法。手動やVagrant、Dockerによる自動化

プログラミングで分かりづらいテーマの一つが例外処理ですよね。例外処理は正しく設計しないと問題が起きたときにアプリケーションの障害につながってしまいます。一方で例外処理を学習だけで理解するのは難しく、実務での経験をとおして身につける必要があると思っています。

私も実務で例外処理を経験するまでは『なんとなく知っている』レベルでした。実務でレビューを受けたりしながら例外処理について学びました。この経験をもとに、この記事では例外処理とはなにか、目的や考え方について書いていきます。

:::note
### この記事で想定している読者の方

この記事は、プログラミングを学習中の方、実務経験が浅いエンジニアの方を主な読者対象としています。私がメインで使っているプログラミング言語はRubyですが、言語を問わない汎用的な内容になっていると思います。
:::

## 例外処理とは
まず例外について整理しておきます。例外とは、『**想定していないことが起きたときに、問題の解決=回復を期待して呼び出し元にそれを伝えること**』をいいます。この例外を処理することが例外処理になります。

呼び出し元に例外を投げて、そこで解決されない場合は次々と上位の呼び出し元に伝搬します。例外処理の全体をとおしても問題が解決されないとき、アプリケーションに障害が起こります。

### どんなときに例外が起こるか

そもそも、どんなときに例外は起こるのでしょうか。たとえば、次のようなケースで起こったりします。

* API連携など、結合している外部のアプリケーションに問題があるとき
* ゼロでの除算など、許されない演算を行ったとき
* ユーザの入力にミスがあったとき
* ライブラリにバグがあったり、アップデートにより互換性が失われたとき
* ハードウェアが故障したとき

### 例外が起こる例

上で例外が起こるケースをいくつか見ましたが、具体的な例を見てみます。たとえば、アプリケーションで処理をしようとしているファイルがないときに例外処理が起こります。

C++やJava、JavaScriptやRubyなど、言語によっては例外処理をする機能を組み込みで提供しています。たとえばJavaは、文法上のミスがないなど、コンパイルさえできれば実行できます。ただ、**コンパイル時に想定していなかったことが、実行段階で起こったりします**。つまり例外が起こります。

ファイルの処理において、コンパイルの段階ではファイルの存在確認をしないので、実行時に例外が起きることがあります。このケースでは、ファイルがないときの例外処理をしないと、アプリケーションに障害が起きてしまいます。

この障害を防ぐ方法としては、たとえば**画面上でユーザにファイルの存在確認を促すような例外処理**を行うことで、例外から回復することができますね。

:::info
### まとめ：例外処理とは

例外処理とは、呼び出し先に想定していないことが起きたときに、問題の解決=回復を行うことをいいます。
:::

## なぜ例外処理をするのか
例外処理は、**例外に対応してアプリケーションを回復するため**に行います。

例外処理を行わないと、アプリケーションに障害が起こってしまいます。これはユーザ体験の悪化につながります。ビジネスの種類によっては、ユーザに実質的な損害を与えることになります。データの破損も起こりうるでしょう。受託開発においては、内容によっては瑕疵に相当するかもしれません。

例外が起きたときにアプリケーションを回復するのが例外処理の役割です。とても重要だといえますね。

## 例外処理における用語の定義
例外処理の考え方に入る前に、次の用語について押さえておくことが大切なので、まず説明しておきます。

### エラーと例外の違い

例外という文脈で似ている言葉として『**エラー**』があります。中には混用しているケースも見られます。両者の明確な定義はありませんが、次のように分類する場合があります。分かりやすいので、私はこの分類でいいと思っています。

| 用語 | 説明 |
| - | - |
| **エラー** | アプリケーションのユーザが解決できる問題 |
| **例外** | アプリケーションの開発者が解決する必要のある問題 |

### チェック例外と非チェック例外

また、Javaなど言語によっては呼び出し元に例外処理を強要する機能をもつものがあります。これについて、『**チェック例外**』と『**非チェック例外**』という考え方があります。

| 用語 | 説明 | 例 |
| - | - | - |
| **チェック例外** | 例外処理が必要な例外 | ファイル読み込みなど |
| **非チェック例外** | 例外処理を行う必要がない例外 | メモリの枯渇など |

## 例外処理の考え方、設計指針
それでは、実際にどうやって例外処理を行えばいいのでしょうか。基本的な考え方は、『**例外処理は回復するか投げっぱなしにするかのどちらか**』で対応するとよいです。

ここでは例外処理をすべきところ、逆にすべきでないところの例を書いていきます。

### どこで例外処理をすべきか

まず例外処理をすべきところについて書きます。例外処理は、**呼び出し先で起こりうる例外を回復できるところ**で行います。たとえば次のようなところです。

* APIにリクエストを送っているところ
* ファイルの読み込みを行なっているところ
* ユーザからの入力を処理しているところ

このとき、**回復可能な例外をできるだけ狭い範囲でキャッチ**します。たとえばExceptionではなくIOExceptionのような下位の例外を処理します。また、例外処理をしたときは**クリーンナップ処理**も行います。たとえばファイルのクローズ処理などですね。

ほかにも、フレームワークの例外処理機構を使用することを検討します。たとえばRuby on Railsには[rescue_from](https://railsguides.jp/action_controller_overview.html#rescue-from)というメソッドがあります。これはコントローラのトップレベルで例外処理を定義できます。

:::info
### まとめ：例外処理をすべきところ

例外処理は、呼び出し先で起こりうる例外を回復できるところで行います。
:::

### どこで例外処理をすべきでないか

上で例外処理をすべきところについて書きましたが、今度は逆に例外処理をすべきではないところについて整理します。これについて、**呼び出し先で起こりうる例外を回復できないところでは例外処理をすべきではありません**。

例外が起こりうる呼び出し先があるからといって、直近の呼び出し元で例外処理を必ずしなければならないという訳ではありません。上位の呼び出し元に任せることも、大切な考え方のひとつといえます。

たとえば、次のようなケースでは例外処理をすべきではありません。

* **例外をなかったことにする**こと。『**例外を握りつぶす**』といったりします。これをすると上位の呼び出し元が例外を検知できず、適切な回復処理を行えなくなります
* **ログに書いて例外を再送出する**こと。上位の呼び出し元でも、同じ例外を元にしたログが書かれているはずなので、ログが二重になります。これは調査のときに混乱の元になってしまいます

:::notice
### まとめ：例外処理をすべきでないところ

例外処理は、呼び出し先で起こりうる例外を回復できないところでは行うべきではありません。
:::

## どこで例外を投げるべきか
以上で、例外処理について書きました。では、例外を投げる側については、どういったときに投げればいいのでしょうか。

この基本的な考え方としては、『**呼び出しもとは呼び出す条件を満たしたけど、求められる処理を達成できなかったとき**』に投げればよいです。このとき、次の二つのことを考慮します。

* **呼び出し元に例外処理を強要しない**こと
* **例外クラスを定義するということは、呼び出し元で回復処理を期待する**ことを意味する。そうでなければ標準例外クラスを使い、クラス定義はしない

## まとめ
例外処理は、アプリケーションの障害を防ぐために重要な処理のひとつです。例外処理はただ行えばいいものではありません。ログだけ書いて握りつぶすような処理は、逆に問題を引き起こすことにつながります。

例外処理では可能な限り回復し、できなければ投げっぱなしにして上位の呼び出し元に任せる、といった設計指針でよいのかな、と思います。

### 参考文献

* [Web開発のためのJava入門 9章：例外処理](https://www.fujitsu.com/jp/group/fap/services/java-education-kc/course/technology/java-cobol/09-exception/index.html)
* [段階的に理解する Java 例外処理](https://qiita.com/ts7i/items/d7f6c1cd5a14e55943d4)
* [例外設計の話](https://gist.github.com/sunaot/6138546)

プログラミングで分かりづらいテーマの一つが例外処理です。私は実務でレビューを受けたりしながら例外処理について学びました。この経験をもとに、この記事では例外処理とはなにか、目的や考え方について書いていきます。

例外のイメージ

プログラミングにおける例外処理の考え方、設計指針

チームでソフトウェアを開発するとき、ソースコードレビューをすることがあると思います。私もレビューをよくするのですが、やる度にレビューの観点が変わってしまっているような気がしていて、一度整理しようと思い立ちました。

この記事では、ソースコードレビューとはなにか、目的ややり方、観点のチェックリストについて書いています。レビューをするときの参考になればと思います。

## 対象としている読者
この記事の対象は、ソフトウェア開発に携わるエンジニアの方です。私はWebアプリケーションのフロントエンドやバックエンドに関わることが多いので、それ以外の領域については視点が欠けているかもしれません。

## ソースコードレビューとは
ソースコードレビューとは、**ソースコードの差分を見て、コメントなどの手段をとおしてソースコードの品質向上を促すこと**です。

役割としてはふたつあって、レビューを依頼する**レビューイ**と、レビューする**レビュアー**がいます。レビュアーは複数人の場合もありますね。

ソフトウェアの品質を担保するために、レビュアーの許可がないと変更を適用できない、といったルールで運用されるところもあると思います。GitHubのプルリクエストや同様の機能をとおして行なったり、対面やオンラインで集まって行うこともあります。

### この記事で書かないこと

この記事では、『プルリクエストをどう書くか』といった内容は書きません。これについては別の記事で書いていますので、あわせてご覧ください。

:link{slug=how-to-write-git-pull-request}

## ソースコードレビューの目的
ソースコードレビューには、大きく分けて次の4つの目的があると思っています。

1. ソフトウェアの品質を高めるため
2. バグなどの問題の混入を防ぐため
3. 影響範囲を確認するため
4. メンバーの教育のため

1と2はレビューの目的として、なんとなく想像がつくと思います。3の影響範囲については、その変更がソフトウェアの別のところ、ソフトウェア以外にもユーザやオペレーションなどに影響を及ぼさないか？などを確認します。とても重要な目的といえます。

また、ソースコードレビューは教育の効果も大きいです。レビューイはもちろん、レビュアーにとっても学ぶことがあったりします。

## ソースコードレビューのやり方
まず、ソースコードレビューのやり方について、次の7つの項目でまとめます。

1. コメントの種類を押さえる
2. コメントの仕方に気をつける
3. よいところもコメントする
4. 根拠を示す
5. 進捗に応じて見るポイントを変える
6. レビュー後でも直せるかどうかを意識する
7. 口頭でのコミュニケーションも併用する

### 1. コメントの種類を押さえる

ソースコードレビューのコメントは、レビューイがなにをすべきかが自明であるように書きます。レビュアーの考えを深読みしなくていいようにします。このやり方として、次の3つを使う方法があります。

| 項目 | 意味 |
| - | - |
| **MUST** | 対応すべきこと |
| **IMO** | 自分の意見（In my opinion） |
| **nits** | 細かい指摘 |

他にもSHOULDを使う例をよく見かけますが、対応すべきかどうかが曖昧なのでMUSTかIMOに寄せるべきだと私は考えています。

### 2. コメントの仕方に気をつける

ソースコードレビューのコメントはコミュニケーションでもあるので、コミュニケーションが円滑になるよう絵文字などを交えて投稿した方がいいと思います。

### 3. よいところもコメントする

2と同じ理由ですが、ソースコードレビューはコミュニケーションであるので、相手をほめることも意識した方がいいと思います。また、よいところをコメントすることはメンバーの学びにもつながります。

### 4. 根拠を示す

コメントが「こうすべき」だけだと、レビュイーは「なぜ？」と思ってしまいます。その根拠として、参考文献などをリンクで示すと親切ですね。

### 5. 進捗に応じて見るポイントを変える

作業中のソースコードをWIPとして先にプルリクエストを出すやり方もあります。WIPのときは変更の前提となるところ、例えば『そもそもこの変更は必要なのか』や『設計や実装の大まかな方針に問題はないか』を見ます。

このとき、細かいスタイルについては指摘する必要はありません。実装完了後に、具体的な実装方法や書き方についてレビューしていきます。

### 6. マージ後でも直せるかどうかを意識する

たとえばビューの修正はマージ後でも低コストでできますが、データベースの変更は修正コストが大きくなります。データベースのように、変更しづらいところを特に意識してレビューした方がよいといえます。

### 7. 口頭でのコミュニケーションも併用する

コメント上だけでのコミュニケーションが難しい場合は、口頭でのコミュニケーションも併用した方がいいことがあります。ただこの場合でも、指摘内容はコメントしておいた方が、どういう議論をしたかが分かりますし、他のメンバーの学びにもつながります。

## ソースコードレビューの観点のチェックリスト
それでは次にソースコードレビューをどのような観点で行うか、チェックリストを示していきます。これはチームによって変わってくると思うので、参考程度にしつつ、**チームごとのチェックリストをつくれれば**と思っています。

### 前提

* ソースコードを変更する目的に問題はないか
* ソースコードの変更項目に問題はないか
* コミットの粒度は問題ないか
* コミットメッセージは問題ないか

### ソフトウェアの動作

* 画面の表示に問題はないか
* 文言に問題はないか
* 満たすべき環境すべてで問題なく動作するか

### 設計方法

* 変更項目と実装内容に齟齬はないか
* ロジックは合っているか
* よりよい設計はないか
* オブジェクト指向設計の原則は守られているか

### 実装方法

* 不要になったソースコードはないか
* DRYに書けているか
* 将来必要になるかもしれないものを実装していないか
* 導入したライブラリに問題はないか
* 使えそうなライブラリはないか
* 標準のAPIにある機能を再発明していないか
* 使用できる既存のモジュールはないか
* APIのリクエストやレスポンスに問題はないか
* リトライ処理は行えているか。問題ないか
* データの型は適切か
* データの不整合は起こらないか。トランザクションは張れているか
* ログは適切に記録されているか
* デバッグ用のコードは残っていないか
* よりよい書き方はないか
* 命名に問題ないか
* 名前から副作用の有無は想定できるか
* 名前と実装は合っているか
* 可読性に問題はないか
* ガード節を用いているか
* アクセス修飾子は適切か
* スコープは適切か
* スタイルに問題はないか
* ひとつのメソッドの処理は多すぎないか
* ネストは深くないか

### 運用

* ユーザに影響はないか、対応はとれているか
* メンバーに影響はないか、対応はとれているか
* システムに影響はないか、対応はとれているか
* ドキュメントの更新は十分か
* 法的、あるいは利用規約上の問題はないか

### テスト

* テストケースに問題はないか
* テストの実装方法に問題はないか
* テストはパスしているか
* セキュリティ上の問題はないか

### パフォーマンス

* パフォーマンス上の問題はないか
* N+1問題は発生しないか
* 計算量は問題ないか、あるいは減らせないか
* クエリは最適化できないか

## よりよいソースコードレビューのために
ソースコードレビューをよりよくするためには、まず**レビューの観点をチームで共有しておく**べきだと思っています。

レビューで、私もたまにあるのですが、コメントを受けてモヤモヤすることがあると思います。それはチームとしてのレビューの観点が決まっていないから、というのが理由のひとつにあると思っています。

レビューの観点を共有しておけば、レビュアーはその観点に基づいたコメントであるという担保ができますし、レビューイもコメントではなく観点自体についての建設的な議論を提案できます。チームで実践しているふりかえりなどのプラクティスで話せるとよさそうですね。

また、**自動化できるところは自動化すべき**といえます。たとえば細かいスタイルについての指摘は、する側も受ける側もあまりいい気持ちになれないと思います。

こういったところはフォーマッタやソースコードレビューサービスなどを利用して自動化するといいと思います。

## まとめ
ソースコードレビューは、ソフトウェアの品質向上のための重要な取り組みのひとつです。やり方や観点を抑えておくことで、効果的なレビューを行えるようになります。この記事がレビューをするときの参考になればうれしいです。

### 参考文献

1. [コードレビューのやり方、基礎の基礎](https://eh-career.com/engineerhub/entry/2020/03/12/103000)
2. [コードレビューをより効果的にする方法](https://www.infoq.com/jp/articles/effective-code-reviews/)
3. [ソースコードレビューのポイント](https://gist.github.com/s-yoshiki/9e446d69cf388703a4711f7e69cba173)

チームでプロダクトを開発するとき、ソースコードレビューをすることがあると思います。私もレビューをよくするのですが、やる度にレビューの観点が変わるような気がしていて、一度整理したいと思いました。この記事では、ソースコードレビューとはなにか、目的ややり方、観点のチェックリストについて書いています。

ソースコードレビューのやり方、目的や観点のチェックリスト

私はふだんの開発でプルリクエストを出すとき、なんとなくフォーマット化したものを使っていました。プルリクエストについて整理するために、この記事でプルリクエストとはなんなのか、誰が読むのか、目的はなにか、書くべきことなどをまとめてみました。

記事の後半にはプルリクエストのテンプレートもありますので、よりよいプルリクエストにするための参考になればうれしいです。

## プルリクエストの書き方とは
ここでいうプルリクエストの書き方とは、プルリクエストの本文についての書き方のことです。プルリクエストの本文は、ひとことで言うと『**ファイルの変更について表した文章**』といえます。

プルリクエストの本文には、一般的には変更の概要や変更点、再現手順などが書かれます。自由に書けますが、気をつけるべきポイントもあります。人それぞれ、チームそれぞれで書き方はあると思いますが、よりよくしたいときにこの記事が参考になればと思います。

:::notice
この記事では、プルリクエストのコードについては言及していません。たとえば『変更の目的はひとつであるべき』や『差分を小さくすべき』といったことについては書いていません。
:::

## この記事で想定している読者
この記事は、Gitを用いて開発するエンジニアの方を想定して書いています。とくにチームで開発している方にとって有用だと思います。

プルリクエストと聞くとGitHubですが、Bitbucketなど他のプラットフォームを利用している方にとっても参考になると思います。

## プルリクエストの書き方を気をつけるべき理由
プルリクエストの本文を書く上で気をつけるべき理由として、大きく次の3つがあると思っています。

1. 読むコストを下げるため
2. いいフィードバックをもらうため
3. プルリクエストはドキュメントでもあるため

### 1. 読むコストを下げるため

プルリクエストのレビューは時間がかかりますし、頭も使います。レビュワーの方が内容をできるだけ早く、ラクに把握できると、プロダクトの価値向上など他のことに時間を使えるようになります。

コミュニケーションコストも減るので、早いレビューにもつながります。なかなかレビューされないと、コンフリクトが起きて自分がつらい目にあってしまうかもしれませんよね。

### 2. いいフィードバックをもらうため

プルリクエストの変更の内容が分かりやすかったり、とくに見てほしいポイントが明確だと、よりよいフィードバックにつながるかもしれません。

### 3. プルリクエストはドキュメントでもあるため

開発や運用のためのドキュメントと同じく、**プルリクエストもドキュメントの一部**です。

将来のメンバーがあるコードに関わるときに、関連するプルリクエストを見ることもあります。今プロダクトに関わっている人だけではなく、あとから読む人のことも想定した内容であるべきといえます。

## プルリクエストは誰のために書くのか
プルリクエストの本文は、次の方を読者として想定しながら書くと、よいプルリクエストにつながります。

* レビュワーのため
* 自分のため
* 将来のメンバーのため

レビュワーのために書く、というのは分かりやすい理由だと思います。自分のために書くと、プルリクエストに問題がないかを確認することができます。

また、前述したように将来のメンバーのためにも書きます。これはプルリクエストに前提知識がいらないように書く、などの気をつけるポイントにつながります。

## プルリクエストの書き方
それでは、プルリクエストの本文になにを書くかについてまとめます。プルリクエストの本文には、次のような項目を書いていくといいと思っています。

| 順番 | 見出し | 備考 |
| :-: | - | - |
| 1 | **変更の概要** | 概要、関連するIssueやプルリクエスト |
| 2 | **なぜこの変更をするのか** | - |
| 3 | **やったこと** | チェックボックスで進捗を表す |
| 4 | **変更内容** | UIのスクリーンショット、APIのリクエスト/レスポンスなど |
| 5 | **やらないこと** | プルリクエストのスコープ外とすること |
| 6 | **影響範囲** | ユーザやメンバー、システムに影響すること |
| 7 | **どうやるのか** | 変更したものの使い方や再現手順 |
| 8 | **課題** | 悩んでいるところ、とくにレビューしてほしいところ |
| 9 | **備考** | - |

プルリクエストを出すときは、本文だけでなくタイトルづけも大切です。**タイトルには、変更した内容が分かるように書きます**。

また、プルリクエストの本文は長ければいいというものでもありません。長い文章は読むコストを高めてしまうかもしれません。プルリクエストの前提が変わったときの保守コストもあります。シンプルにすることを心がけた方がいいと思います。

また、今ではなくあとから読むメンバーのためにも、プルリクエストの文章だけで前提知識が分かるようにすることも大切です。

## プルリクエストのテンプレート
前述したプルリクエストの書き方をもとに、テンプレートをつくりました。人やチームによって書き方は変わってくると思いますが、なにかの参考になればうれしいです。

```markdown
## 変更の概要

* 変更の概要
* 関連するIssueやプルリクエスト

## なぜこの変更をするのか

* 変更をする理由
* 前提知識がなくても分かるようにする

## やったこと

* [x] やったこと
* [ ] やっていること

## 変更内容

* UIの変更ならスクリーンショット
* APIの変更ならリクエストとレスポンス

## 影響範囲

* ユーザに影響すること
* メンバーに影響すること
* システムに影響すること

## どうやるのか

* 使い方
* 再現手順

## 課題

* 悩んでいること
* とくにレビューしてほしいところ

## 備考

* その他に伝えたいこと
```

## まとめ
プルリクエストの本文は、プルリクエストの変更について把握するための文章です。読み手や、読み手の目的を想定した文章をつくるべきといえます。

プルリクエストの本文を書くときは、テンプレートを利用することで、プルリクエストの作成コストを下げることができます。

### 参考文献

1. [レビューしてもらいやすいPRの書き方](https://hydrakecat.hatenablog.jp/entry/2018/06/30/%E3%83%AC%E3%83%93%E3%83%A5%E3%83%BC%E3%81%97%E3%81%A6%E3%82%82%E3%82%89%E3%81%84%E3%82%84%E3%81%99%E3%81%84PR%E3%81%AE%E6%9B%B8%E3%81%8D%E6%96%B9)
2. [Pull Requestのフォーマットを決めるとレビューの効率が3倍よくなる](https://engineering.crocos.jp/post/98455177675/pull-request-%E3%81%AE%E3%83%95%E3%82%A9%E3%83%BC%E3%83%9E%E3%83%83%E3%83%88%E3%82%92%E6%B1%BA%E3%82%81%E3%82%8B%E3%81%A8%E3%83%AC%E3%83%93%E3%83%A5%E3%83%BC%E3%81%AE%E5%8A%B9%E7%8E%87%E3%81%8C3%E5%80%8D%E3%82%88%E3%81%8F%E3%81%AA%E3%82%8B)

この記事でプルリクエストとはなんなのか、誰が読むのか、目的はなにか、書くべきことなどをまとめてみました。記事の後半にはプルリクエストのテンプレートもあります。

Gitのプルリクエストの書き方とテンプレート

私は以前チームで開発していたとき、よくドキュメントを書いていました。ドキュメントを書くと「仕事をした！」という気持ちになれました。ただふりかえってみると、そのドキュメントは誰にも読まれなかったし、本業であるソフトウェア開発の進捗がわるくなっていた、ということがありました。

あらためて、ソフトウェア開発におけるドキュメントとはなにか、なにを書くべきか、あるいは書くべきでないかなどについて整理してみました。ドキュメントを書くときの参考になればうれしいです。

## 対象となる読者の方
この記事は個人やチームによらずソフトウェア開発に携わっているエンジニアの方にとって参考になると思います。まず全体をざっと読んで概要を把握しつつ、実際にドキュメントを書くときに見る、というような読まれ方を想定しています。

## ソフトウェア開発におけるドキュメントとは
この記事ではドキュメントの書き方について書いていくのですが、ここでいうドキュメントの定義についてまず整理しておきます。先に結論をいうと、この記事ではアジャイル開発における『**開発や運用に必要なドキュメント**』について書きます。

プロダクト開発の方法としてはアジャイル開発が主流となっていますが、『アジャイルソフトウェア開発宣言[^1]』ではドキュメントについて次のように書かれています：

> 包括的なドキュメントよりも動くソフトウェアを

このこともあってか、アジャイル開発の現場によってはドキュメントをあまり書かない方針のところもあるようですが、この宣言はドキュメントに価値がないといっている訳ではないんですね。

この宣言でいう『包括的なドキュメント』とは、角谷信太郎氏の『第4回 ドキュメントを大切にする[^2]』によると：

> 要求定義→設計→実装→テストといったいわゆる『開発工程』の区切りに作成されるドキュメントのことです。仕様書や外部設計書、詳細設計書、テスト仕様書、テスト実施報告書などがその代表例です

つまりウォーターフォール型の開発手法に見られるようなドキュメントは減らすべきだけど、それ以外のドキュメントは依然として価値があるよ、といっています。

### ソフトウェア開発におけるドキュメントの種類

ここでいう価値のあるドキュメントは、たとえば次のような種類のものがあります。

1. ソースコードやテストコードなどの『動くドキュメント』
2. GitのコミットやPull Request
3. ユーザ向けのドキュメント
4. **開発や運用に必要なドキュメント**

これらのドキュメントを継続的につくっていくことが、ソフトウェア開発には重要になってきます。この記事では、とくに『4. 開発や運用に必要なドキュメント』について書き方を書いていきます。

:::info
この記事では、アジャイル開発における『開発や運用に必要なドキュメント』について書きます。
:::

また、この記事では文章技術のようなテクニックの話は書きません。これについては次の記事で書いているので、参考になればと思います。

:link{slug=points-when-writing-technical-article}

## なぜドキュメントを書くのか、あるいは書かないのか
ドキュメントにはいろんな種類のものがありますが、基本的な目的は**ソフトウェアの価値を高めるため**に書くと思います。ソフトウェアの価値を高めるドキュメントとは、つまり：

* それが必要なときに
* 必要なタイミングで
* 必要最小限のもの

であるべきといえますです。

必要なときにドキュメントがないと、必要な情報を得られず、開発に支障が出てしまいます。たとえば環境構築のときなどですね。逆に必要としている人がいないドキュメントを書くことも、**ソフトウェアの価値を高める時間を減らした**という意味でよくありません。

またタイミングについては、遅すぎるのはもちろん早すぎてもよくありません。ドキュメントを書くのが早すぎると、変化の早いアジャイル開発では必要なときに**前提が変わっている**かもしれません。

ドキュメントは充実していればいいかというと、しすぎるのはよくありません。必要以上の情報は読むコストがかかりますし、変更の多いアジャイル開発においてはドキュメント自体の保守コストがかかってしまいます。

ドキュメントは開発に必要なツールではありますが、ソフトウェアの価値を高めるという目的と、そのためにどうドキュメントを書くかは抑えておく必要があると思っています。

:::notice
ドキュメントはただ書けばいいという訳ではありません。必要なときに、必要なタイミングで、必要最小限で書くべきといえます。
:::

## ソフトウェア開発におけるドキュメントの書き方
では、どのようにドキュメントを書けばいいのでしょうか。開発や運用に必要なドキュメントには、たとえば環境構築やアーキテクチャ設計の意図についてなど、いろんな種類があります。ここでは基本的な書き方について整理します。

ドキュメントを書くときは、次の4W1Hを意識して整理するとよいドキュメントにつながります。

| 順番 | 項目 | 説明 |
| :-: | - | - |
| 1 | **What** | このドキュメントはなにを示すのか。あるいはなにを示さないのか |
| 2 | **Who** | 誰のためのドキュメントか。読み手がいなければ書く必要はない |
| 3 | **When** | いつ必要になるドキュメントか。あるいはいつ更新すべきか |
| 4 | **How** | 本文。どのようにするのか。動作環境や手順、図など |
| 5 | **Why** | なぜHowのような内容になったのか |

補足として、1については情報が必要な人が、必要であると分かる文章にします。2についてはチームの構成によって変わってきます。たとえばプロフェッショナルだけで構成されるチームには初歩的なドキュメントは必要ないでしょう。

また、基本的に客観的な情報のみを書き、書き手の主観を入れるときはそれが分かるように注意書きをすべきだと思います。ドキュメントの内容を検討するときに議論しやすくするためです。

## いつドキュメントを書くか
ドキュメントを書くタイミングは早すぎず遅すぎず、それが必要になったときに書いてある状態にしておくのが望ましいです。

アジャイル開発は頻繁に変更があるので、ドキュメントにも頻繁な変更が入ります。最初から完全なドキュメントをつくってしまうと時間がかかるし、修正コストも大きくなります。小さくはじめて育てていく意識があるといいと思います。

## どこでドキュメントを書くか
ドキュメントを書く場所に必要な要素としては、アクセスしやすく、更新しやすいことが大切だと思います。たとえばesa[^3]は『情報を育てる』ためのドキュメント共有サービスなので、書く場所として適していると思います。

## まとめ
ドキュメントは、書くタイミングや内容の要点を抑えた上で書くことで、ソフトウェアの価値を高めることにつなげられます。ドキュメントを書くときは4W1Hを意識して、必要最小限の内容にするとよいと思います。

[^1]: [アジャイルソフトウェア開発宣言](http://agilemanifesto.org/iso/ja/manifesto.html)
[^2]: [第4回 ドキュメントを大切にする: アジャイル開発者の習慣](https://gihyo.jp/dev/serial/01/agile/0004)
[^3]: [esa](https://esa.io/)

この記事ではソフトウェア開発におけるドキュメントとはなにか、なにを書くべきか、あるいは書くべきでないかなどについて整理してみました。個人やチームによらずソフトウェア開発に携わっているエンジニアの方にとって参考になると思います。まず全体をざっと読んで概要を把握しつつ、実際にドキュメントを書くときに見る、というような読まれ方を想定しています。

ソフトウェア開発におけるドキュメントの種類と書き方

プログラミングをするとき、ライブラリを使うことがあると思います。ライブラリを使うときに、なにかしらの条件をもとに『そのライブラリを使っていいかどうか』を考えたりします。

自分の中で、このライブラリの選定基準をうまく言語化できてなかったので、自分なりにまとめてみました。

この記事では、プログラミングにおけるライブラリの選定基準とはなにか、選定基準をつくるべき理由と選定基準について書いていきます。

## プログラミングにおけるライブラリの選定基準とは
この記事でいうライブラリの選定基準とは、ライブラリを使おうとするときに**そのライブラリを使っていいかどうかを判断するための基準**のことをいいます。たとえば『メンテナンスされているか』などが基準としてあります。

## なぜライブラリの選定基準をつくるのか
ライブラリの選定基準をつくる一番の理由は、**プログラムのメンテナンス性を保つため**です。導入すべきでないライブラリを選んでしまうと、破壊的な変更が多くて追従が大変だったり、バグが放置されてモンキーパッチをあてることになったりしてしまいます。

個人・チームに関わらず、プログラミングをするときに基準をもっておくべきだと思っています。

選定基準をつくる理由については、メンテナンスの問題以外にも、パフォーマンスへの影響や法的リスクの検証といったものもあります。

:::info
ライブラリの選定基準をつくる主な理由は『プログラムのメンテナンス性を保つため』です。
:::

## ライブラリの選定基準一覧
まずライブラリの選定基準を表でまとめつつ、次の章でそれぞれについて書いていきます。基本的にはどれも満たすべき項目だと思っています。逆に満たしていない、満たせない項目については、**そこがリスクになることを把握**しておいた方がよさそうです。

| 番号 | 項目 |
| :-: | - |
| 1 | メンテナンスされているか |
| 2 | 破壊的な変更は多くないか |
| 3 | 使われているか |
| 4 | リリースされてから十分な時間が経過しているか |
| 5 | 安定版か |
| 6 | 依存関係は問題ないか |
| 7 | アプリケーションと疎結合にできるか |
| 8 | テストは十分か |
| 9 | 守備範囲が広すぎないか |
| 10 | 学習コストは高くないか |
| 11 | ドキュメントは充実しているか |
| 12 | 遅くないか |
| 13 | ブラックボックスなところはないか |
| 14 | 使えなくなったときの代替案はあるか |
| 15 | ライセンス上の問題はないか |

## ライブラリの選定基準
ひとつひとつ見ていきます。

### 1. メンテナンスされているか

コミットログの頻度や、Issues/Pull Requestsの対応状況を見てみます。コミットの頻度が少なかったりバグが放置されていたりすると、モンキーパッチなどで対応することになるかもしれません。

GitHubなら、開発者の方の草の生え具合を見てみるのもいいかもしれません。

### 2. 破壊的な変更は多くないか

CHANGELOGを見てみます。破壊的な変更が多いと、追随するためのコストが高くなるリスクがあります。

### 3. 使われているか

ライブラリが使われているかどうかで、開発者の方のそのライブラリに対するモチベーションを推測することができます。GitHubならスター数などが参考になると思います。

### 4. リリースされてから十分な時間が経過しているか

リリースして間もないライブラリだと、将来の変更が見えづらいという問題があります。

### 5. 安定版か

ライブラリが安定版でないと、破壊的な変更が入ったり、既知のバグがあったりします。バージョンが1.0以上であればいいかというとそういうわけではなく、ライブラリによってバージョニングの方針が異なるので、READMEなどを確認してみます。

### 6. 依存関係は問題ないか

依存関係が多いと、ライブラリのバージョン管理が難しくなります。ライブラリ自体が依存しているライブラリのメンテナンス状況なども同様に見ておく方がよさそうです。

### 7. アプリケーションと疎結合にできるか

ライブラリがアプリケーションと密になってしまうと、そのライブラリの変更に対する影響を大きく受けてしまうことになります。また、ライブラリの使用をやめる
ときのコストも高くなってしまいます。

### 8. テストは十分か

必要なテストが書かれているか、また自動化されたテストをパスしているかを確認します。

### 9. 守備範囲は広すぎないか

『[ライブラリの守備範囲は狭い方がいい](https://konifar.hatenablog.com/entry/2015/05/14/184237)』という記事にもありますが、守備範囲が広いとアプリケーションのサイズが大きくなったり、代替が効きづらいという問題につながってしまいます。

### 10. 学習コストは高くないか

独自DSLなど、ライブラリを使うための学習にかかる時間が多いと、チーム開発でパフォーマンスが下がるかもしれません。汎用性のない知識の習得は、人によってはたのしくないと思うかもしれません。

### 11. ドキュメントは十分か

インストールや使用方法、APIなどの情報が最低限まとまっているか、古い情報が残ったままになっていないかなどを見てみます。

### 12. 遅くないか

用途としては問題ないけど遅い、というライブラリがあったりします。パフォーマンスが重要なところに導入するライブラリではとくに注意した方がよさそうです。

### 13. ブラックボックスなところはないか

ベンダー製のライブラリでは、本質的なロジックをAPI経由で処理したりします。仕方のないことではありますが、リスクとして把握しておいた方がよさそうです。

### 14. 使えなくなったときの代替案はあるか

ライブラリがメンテナンスされなくなったり、思想が変わってしまうことがあったりします。そのときの代替案を想定しておくことは重要な観点だと思います。

### 15. ライセンス上の問題はないか

ライブラリのライセンスが導入するプログラムにとって問題がないかを確認します。『[Facebookの特許条項付きBSDライセンスが炎上している件について](https://note.com/konpyu/n/nc0d2f49676ba)』にあるような、ライセンス上の問題に発展するリスクがあります。

## まとめ
ライブラリに選定基準をつくっておくことで、継続的にメンテナンス性を保つことにつながります。ライブラリを使うときは、基準にそって判断し、基準を満たさないものはリスクとして把握しておくとよさそうです。

### 参考文献

* [「GitHubのスター数が多いから良い」と盲目的にライブラリ選定をしていないか胸に手をあてて考える](https://note.com/serima/n/n1a83526c5d5e)
* [ソフトウェア開発時にどのような基準でOSSライブラリを選定するのがよいのか](https://yoshinorin.net/2019/08/31/how-to-choose-oss-library/)

ライブラリを使うときに、なにかしらの条件をもとに『そのライブラリを使っていいかどうか』を考えたりします。自分の中で、このライブラリの選定基準をうまく言語化できてなかったので、自分なりにまとめてみました。

プログラミングにおけるライブラリの選定基準

Web APIのための規格。
APIリクエストのためのクエリ言語と、APIの仕様を記述するためのスキーマ言語からなる。
必要なリソースのみをクエリに記述するため、結果が予測可能となる。
またひとつのリクエストで多くのリソースを取得できるため、ネットワーク接続が遅い環境下に対応しやすい。

GraphQL

Webページの情報を提供するための標準化されたデータ形式。
Googleがページをクロールする際、より正確に情報を収集できるようになる。
また検索結果に画像などのコンテンツを表示できるようになる。

構造化データ

アプリケーションの実行モデルのひとつで、サーバの運用が不要なモデルのこと。
イベント駆動により、実行に必要なサーバが立ち上がる。
従量課金制によるコスト削減や、サーバのアップデート・スケーリングといった管理が不要になるなどのメリットがある。
これにより開発者がプロダクトの価値向上にリソースを使うことができるようになる。

Serverless

「上位のモジュールは下位のモジュールに依存してはならない」という原則。
下位のモジュールに依存すると、モジュールが変更されたときに影響を受けてしまう。
各モジュールの間に抽象クラスを導入し、各モジュールはこの抽象クラスに依存することで、モジュールを疎結合に保てる。

依存性逆転の原則

「クライアントにとって不要なインタフェースに依存することを強制してはならない」という原則。
依存するインタフェースがふえると、インタフェースの変更による影響を受けやすくなる。
責務に応じてインタフェースを分けるよう設計する。

インタフェース分離の原則

「サブクラスはスーパークラスに置き換え可能であるべき」という原則。
置き換えられないということは、つまりサブクラスへの知識をもつということ。
これは密結合の原因となってしまう。
スーパークラスの知識のみをもち、サブクラスは置き換え可能であるように設計することで、クラスを疎結合に保てる。

リスコフの置換原則

「クラスは拡張に対して開いていて、修正に対して閉じているべき」という原則。
コードの変更は、既存のクラスを修正するのではなく、新しくコードを追加することによって行うよう設計する。
これにより既存のクラスが影響を受けなくなる。

オープン・クローズドの原則

「クラスのもつ責務はひとつであるべき」という原則。
責務が複数あると、その責務の数だけクラスを変更する理由が生じる。
このとき、ある責務に対する変更が、関係ない別の責務に影響を与えてしまう。
複数の責務をもつクラスは最小限にし、クラスには単一の責務だけをもたせるよう設計する。