WIP 俺的ベストプラクティス集
自身が今まで触れてきた技術のベストプラクティスが記載されているWebページをまとめるページです。
本ページは随時、追記していきます。 :bow:
Architecture
REST API
Programming Language
Java
Kotlin
T.B.C
Python
Golang
Infrastructure as Code
Docker
docs.docker.jp cloud.google.com
Ansible
Monitoring
カバンを持たず、本だけ持って通勤してみた
弊社は1年で12万円分、好きな本やガジェットを買うことができる制度があります。
これを利用し本を買うわけですが、本を持ち歩くものの、通勤時間の中で読むことがない状況が続いていました。
モチベーションがないとか精神的な問題もあるんと思うが、仕組みとして本を読まない問題を解決できないかを考えました。
アプローチ
考えた結果、カバンを持たずに本だけ手に持って通勤すれば良いのでは？と思い立ちました。
カバンだけで通勤するにも持ち物を絞る必要があるので、まずは持ち物を整理しました。
通勤時の持ち物について
もともと通勤時の持ち物が少ないので、「本だけ持って通勤」はすぐ実践することができました。
ちなみに持ち物はこのような感じで、やめたのはカバンを持つことだけです。
やってみてどうだったか？
まず、本しか手に持ってなくて嫌でも本へと意識が向くことがわかりました。
結果として、読書する時間は以前と比べて間違いなく伸びました。
一方、むき出しの本だけを持って出勤してる人などまずいないので、なにか気恥ずかしさを感じていました。
この対策としては、ブックカバーに入れて本を持ち歩くようにしたほうが良いかもしれません。 個人的には、以下のようなフリーサイズのブックカバーがいいと思います。
おわりに
本だけ持って出勤すると、読書する機会を嫌でも増やすことができるとわかりました。
本を読むモチベーション次第ですが、私のように本を鞄に入れっぱなしで読んでない！と言う人は一度試してみると良いかもしれません。
RESTful APIのドキュメンティングツール比較
概要
いままでチームで、ConfluenceにAPI仕様書を書いてました.
今回新たに別ドメインのAPIを用意するにあたり、ナウくてイケてるAPIドキュメンティングトツールを採用したいと思い調査しました.
個人メモなので結構緩めです.
要求
ざっくりこうあってほしいということ.
- メンテナンスが簡単
- 記述フォーマットが簡単
- 一般的なフォーマットだとエディタの恩恵を受けやすい
- 仕様書を簡単に公開できる
- ローカル環境でいちいちなにかすることなく、簡単にだれでもAPI仕様を閲覧できるようにしたい
- MockAPIの立ち上げができること
- 簡単に試せるようにしたい
結論
結論からいうと、Swaggerを採用することにしました.
- OpenAPI InitiativeがRESTful API の標準化をしており、ドキュメンティングツールとしてSwaggerを採用
- 今後の標準になる見込み.
- Swagger形式が、AWSやGCPですでに使われている.
- APIモックサーバの立ち上げや検証機能など、一通りのツールが揃っている.
比較
比較する候補
JSON Schema
JSON値の形式を定義、検証するための仕様です.
JSON文書の検証、APIドキュメント生成ができます.
JSONの記載は手動なので、多少つらみはあるかもしれません.
API Blueprint
APIドキュメンティングツール.
yamlの拡張形式で、APIの形式を表現できます.
Swaggerよりも簡単に導入できそうですが、記述方式に若干の癖がありコストがかかりそうという印象.
Swagger(OpenAPI)
上記同様APIドキュメンティングツール.
OpenAPI InitiativeがRESTful API の標準化をしており、ドキュメンティングツールとしてSwaggerを採用されたようです.
したがって今後API仕様の標準となりそうです.
各要素の比較
| 観点＼項目 | JSON Schema | API Blueprint | Swagger(OpenAPI) |
|---|---|---|---|
| フォーマット | JSON | MSON(独自) | JSON, YAML |
| サーバスタブコード生成 | ☓ | ◯ | ◯ |
| クライアントライブラリ生成 | ☓ | ◯ | ◯ |
| モックサーバ立ち上げ | ☓ | ◯ | ◯ |
| HTML生成、公開 | ☓ | △ | ◯ |
| パブリッククラウド採用(AWS, GCP) | ☓ | ☓ | ◯ |
以下、比較についての補足です.
フォーマット
エディタの対応状況を考えると個人的にはYAMLがやりやすいです.
HTML生成、公開
- API Blueprintは Apiary を使ってホスティングできる(有料)
- Swaggerは redoc をつかって静的なHTMLページを簡単に作ることができる.
- Github Page 、AWS S3から無料で簡単にドキュメントを公開できる.
おわりに
次は ReDoc についてまとめようと思います。
入門監視を読みました
最近、入門監視読んで良かったので、概要とか感想まとめておきます。
本の概要
監視の知見が詰まった本。 大きく2部構成で、
- 1部では筆者が今まで見てきた、監視するときに陥りがちなアンチパターンや、逆にうまくいった知見としてのデザインパターン
- 2部では、何を監視すべきか？なぜ監視すべきか？どうやって監視するかといった監視の戦略
が書かれています。 よくある、特定のツールを用いたインストールや設定方法はなく、監視に対する考え方を学ぶことができます。
どんな人にオススメか？
- 監視ってそもそも何？どこからやればいいの？という人
- ZabbixやNagiosを入れてれば監視は完璧！と思ってる人
- 監視なんて専任の人がやることでしょ？と思ってるアプリケーションエンジニア
よかったところ
本書で一番感銘を受けたのは「ユーザ視点で監視すべき」ということです。
私の今までの監視の理解は
- 各サーバ単位で、OSメトリクス(CPU,Memory,Disk)、ポートの死活監視
- 上記に異常が発生したら即アラートをする
だと思っていました。 しかし本書では、ユーザ視点での監視をすべきと言っています。
「ユーザ視点での監視」とは？
ユーザ視点の監視とは「ユーザ影響がないかどうか」をわかるようにする監視です。 WEBシステムの一般的な構成として、以下のようにロードバランサ等を用いてアプリケーションサーバを複数用意した冗長化構成とするかと思います。
よくやりがちなのは「どこかのサーバでエラーが出た場合にアラートを上げる」ことです。
画像の例でいくとAvailability Zone AのAWS EC2サーバが1台落ちてしまった場合などです。
本書では、これはアラート疲れをを起こすため良くないと紹介しています。
では、どうすべきか？
具体的には以下のようなチェックをすべきと紹介されています。
- HTTPレスポンスコードのチェック
- 200が帰ってきていること
- 5XXが出ていないこと
- レスポンスのレイテンシが低下していないこと
これを監視することで、ユーザ影響の有無を即座に察知することができます。
また、これをもっとブラッシュアップすることで
- 「ユーザのXXX処理の失敗回数が5分間で5％以上の場合にアラートを上げる」
- 「ユーザのXXX処理のレスポンスが1秒を超えた場合にアラートを上げる」
といった、よりユーザ目線なアラートを上げるこが可能となります。
終わりに
ここで紹介したユーザ視点での監視は、正直今まで考えられてなく為になりました。
他にも陥りがちなアンチパターンと、アラートを良くするためのデザインパターン等が記載されています。
個人的には、この本は、リファレンス的に手元に持っておきたいと思いました。
ページ数もあまり多くないので、まさに入門本として読みやすいのでおすすめです。
