前の10件 | -
API仕様ファースト開発 [プログラマー現役続行]
「API仕様ファースト開発」という用語は、私自身が雑誌「WEB+DB PRESS Vol.134」の特集1「実践API設計」を執筆する際に考えた造語です。
全く新規にサービスを開発する場合の開発順序は次のようになります（記事の題3章の図1）。
これは、私自身が初めてメルペイで担当して、一からマイクロサービスを開発したときの開発順序です。そして、その後、チーム移動により別のマイクロサービスの開発へ移動したり、カウシェへ転職したりした際に、最初に導入したのはE2Eテストフレームワーク（記事の第4章「E2Eテストフレームワークの構築」）でした。
そして、API仕様の技術的負債（エンドポイントの仕様が書かれていなくて、それをテストするE2Eテストもない状態）を返済するために、次の開発順序（記事の第5章の図1）を自分自身も行い、他の開発者達にも行ってもらうようになりました。
新たなエンドポイントの追加の場合は、次の開発順序（記事の第5章の図2）となります。
この開発プロセスが定着すると、バックエンドサービスの既存のエンドポイントの修正や新規のエンドポイントの追加の際に、最初に行われるのは次のようになります。
この開発プロセスが定着すると、次のようなことが利点として発生します。
さらに、このような開発手順が定着して日々行われている開発組織に、同じ経験がない開発者が新たに加わった場合でも、次のようになるはずです。
結果として、API仕様ファースト開発経験がない開発者が開発組織に加わっても、かなり早い段階で、API仕様ファースト開発を行うようになり、API仕様の技術的負債を積み上げることはなくなります。つまり、開発者の増加に対して、スケールアップする組織となっていきます。
逆の状況では、API仕様の記述がなく、API仕様に基づくE2Eテストがないまま開発していると、API仕様の技術的負債を積み上げていくだけです。そして、新たな開発者が加わっても、API仕様ファースト開発経験がない開発者なら、技術的負債を返済することなく積み上げるだけとなってしまいます。
全く新規にサービスを開発する場合の開発順序は次のようになります（記事の題3章の図1）。
図1 API仕様ファースト開発での開発順序
これは、私自身が初めてメルペイで担当して、一からマイクロサービスを開発したときの開発順序です。そして、その後、チーム移動により別のマイクロサービスの開発へ移動したり、カウシェへ転職したりした際に、最初に導入したのはE2Eテストフレームワーク（記事の第4章「E2Eテストフレームワークの構築」）でした。
そして、API仕様の技術的負債（エンドポイントの仕様が書かれていなくて、それをテストするE2Eテストもない状態）を返済するために、次の開発順序（記事の第5章の図1）を自分自身も行い、他の開発者達にも行ってもらうようになりました。
図1 既存のエンドポイントの修正順序
新たなエンドポイントの追加の場合は、次の開発順序（記事の第5章の図2）となります。
図2 新たなエンドポイントの追加順序
この開発プロセスが定着すると、バックエンドサービスの既存のエンドポイントの修正や新規のエンドポイントの追加の際に、最初に行われるのは次のようになります。
- 仕様の修正のPR（Pull Request）の作成（新規の場合、新規の仕様のPR）
- 主にフロントエンド開発者による仕様PRのレビューとフィードバック（そして、承認）
- バックエンド開発（E2Eテスト修正・作成およ実装）
- バックエンド開発者によるテストコードと実装のPRのレビュー、フィードバック、承認
この開発プロセスが定着すると、次のようなことが利点として発生します。
- フロントエンド開発者は、バックエンドのAPI仕様がきちんと記述されていることを期待し、不明点や不足点は仕様に反映される。つまり、ミーティングで口頭で聞いたり、Slackで問い合わせただけの状態にならないようになります。
- バックエンド開発者も、たとえ自分で過去に担当して開発してエンドポイントであっても、その詳細を忘れることはよく発生します。その場合、実装を読み直すことなく、API仕様を確認できる。結果として、問い合わせがあった時に、実装を読み直す必要がなくなります。
- 新たにチームに加わったしたフロントエンドおよびバックエンドの開発者は、個々のエンドポイントの仕様を、他のバックエンド開発者に問い合わせることなく理解できます。
さらに、このような開発手順が定着して日々行われている開発組織に、同じ経験がない開発者が新たに加わった場合でも、次のようになるはずです。
- API仕様を記述しないで仕様のPRを出しても却下される。たとえば、gRPCであれば、.protoファイルにメッセージ定義しかなく、何も説明が書かれていなかったり、記述されていなかったりする。GraphQLでは、Mutationの新たなエンドポイントのtype定義はあるが、何も仕様が記述されていないとか。
- 実装のPRに、エンドポイントの仕様に基づくE2Eテストが書かれていない場合、却下される。
結果として、API仕様ファースト開発経験がない開発者が開発組織に加わっても、かなり早い段階で、API仕様ファースト開発を行うようになり、API仕様の技術的負債を積み上げることはなくなります。つまり、開発者の増加に対して、スケールアップする組織となっていきます。
逆の状況では、API仕様の記述がなく、API仕様に基づくE2Eテストがないまま開発していると、API仕様の技術的負債を積み上げていくだけです。そして、新たな開発者が加わっても、API仕様ファースト開発経験がない開発者なら、技術的負債を返済することなく積み上げるだけとなってしまいます。
- 出版社/メーカー: 技術評論社
- 発売日: 2023/04/22
- メディア: Kindle版
2023-12-07 06:17
コメント(0)
株式会社令和トラベルで働きます [転職]
一か月前に「株式会社カウシェを退職します」を書きました。その時点で12月からの勤務先は決まっていませんでしたが、12月1日より株式会社令和トラベルで、嘱託社員契約でバックエンドエンジニアとして働きます。
オフィスは渋谷（カウシェの新たなオフィスの近く）ですが、基本的に自宅からフルリモートで働きます。実は、1年2か月在籍したカウシェには、入社前にオフィスへ行ったことはあるのですが、在籍期間中は一度も出社しませんでした。
私の世代は定年まで1つの会社で働き続けるのが普通でした。実際、富士ゼロックスでの同期や後輩の多くは60歳の定年まで勤めています。私自身は、「定年退職」を経験したことはなく、どの会社も定年退職前に退職したことになります。
これまでのバックエンドの開発経験を活かし、私にとっては初めての旅行という領域でサービスを開発しながら、これから大きくなっていく開発組織をいかにスケールアップできる組織にしていくのかという点についても貢献できればと思っています。
勤務形態
週4日（月曜日〜木曜日）勤務です。週4日勤務は、2017年9月から続けている勤務形態です。オフィスは渋谷（カウシェの新たなオフィスの近く）ですが、基本的に自宅からフルリモートで働きます。実は、1年2か月在籍したカウシェには、入社前にオフィスへ行ったことはあるのですが、在籍期間中は一度も出社しませんでした。
9社目
11月で64歳になり、令和トラベルで社会人になって9社目となります。私の世代は定年まで1つの会社で働き続けるのが普通でした。実際、富士ゼロックスでの同期や後輩の多くは60歳の定年まで勤めています。私自身は、「定年退職」を経験したことはなく、どの会社も定年退職前に退職したことになります。
バックエンド開発
ウェブサービスのバックエンドとしてのキャリアはソラミツからなので、すでに6年を超えたことになります。ただ、今まではGo言語での開発でしたが、令和トラベルではTypeScriptなので、一から学習しながらということになります。これまでのバックエンドの開発経験を活かし、私にとっては初めての旅行という領域でサービスを開発しながら、これから大きくなっていく開発組織をいかにスケールアップできる組織にしていくのかという点についても貢献できればと思っています。
2023-12-01 06:00
コメント(0)
腰部脊柱管狭窄症の再発 [脊柱管狭窄症]
2週間ほど前から腰部脊柱管狭窄症が再発した感じとなりました。急性心筋梗塞後は、ずっとエアロバイク中心の運動をしていたのですが、今年の6月からは天気がよい日はウォーキングをして、雨の日に自宅でエアロバイクをしていました。
脊柱管狭窄症が再発したので、今はエアロバイクだけです（エアロバイクは、初めて脊柱管狭窄症を発症した頃に運動不足を解消するために購入したものですが、その後は、心臓リハビリテーションとしての目的でも使っています）。
初めて発症した2018年6月から2019年4月頃までは、かなり辛かった時期もあったのですが、薬だけで改善しました。今回も、今は薬で様子見となっています。
前回は六本木まで通勤している頃で、通勤がかなり辛かったという記憶があります（「通勤電車の書斎化（2）」）。幸い、今はフルリモートで在宅勤務なので、通勤しなくてよいのが助かります。12月から新たに働く会社もフルリモートで働きます。
脊柱管狭窄症が再発したので、今はエアロバイクだけです（エアロバイクは、初めて脊柱管狭窄症を発症した頃に運動不足を解消するために購入したものですが、その後は、心臓リハビリテーションとしての目的でも使っています）。
初めて発症した2018年6月から2019年4月頃までは、かなり辛かった時期もあったのですが、薬だけで改善しました。今回も、今は薬で様子見となっています。
前回は六本木まで通勤している頃で、通勤がかなり辛かったという記憶があります（「通勤電車の書斎化（2）」）。幸い、今はフルリモートで在宅勤務なので、通勤しなくてよいのが助かります。12月から新たに働く会社もフルリモートで働きます。
2023-11-29 05:48
コメント(0)
E2Eテスト vs E2Eテスト [プログラマー現役続行]
私が「WEB+DB PRESS, Vol.134」の特集1「実践API設計」の中で使っている用語「E2Eテスト」は、一般的な書籍で述べられているE2Eテストとは若干異なります。
どのように違うのかをウェブサービスのバックエンドのサービスで説明します。新たに図を起こすのが面倒なので、すでにある記事「マイクロサービスの開発とテストファースト／テスト駆動開発」からそのまま引用します。
この図では、「加盟店管理用APIマイクロサービス」が複数のマイクロサービスに依存しています。
テストピラミッドの例
このテストピラミッドでは、「統合テスト」は、依存しているサービスへの呼び出し部分をモックで置き換えてサービス単体でテストすることを指すことが多いです。したがって、依存しているサービスへの呼び出しを、テスト時だけモックで置き換えられるような仕組みを埋め込む必要があります。つまり、本番環境で動作するコードの動作を確認しているわけではありません。
たとえば、実際に本番環境（もしくは開発用環境）で依存するサービスを呼び出したら、呼び出しコードに間違いがあり、モックとは異なる動作をしたり、正しく動作しなかったりする可能性があります。
そのため、統合テストの次の上の段階で行いたいのは、テスト対象のサービスの実行ファイル（本番環境にデプロイするバイナリ形式）で実際に実行して、そのAPIのエンドポイントを外部から呼び出すテストを行うことになります。
この時に、依存するサービスをどうするのかという問題に直面することになります。その結果、一般的な書籍で述べられている「E2Eテスト」ということになります。しかし、それは他の依存するサービスも動作させないといけないし、それらのサービスが動作するためのデータベースの設定が必要かもしれなく、設定が非常に面倒になります。
その結果、一般的な書籍では、E2Eテストは構築が難しいくテスト時間も要するので、単体テストや統合テストを強く勧めています。
当時は、ほぼすべてのマイクロサービスが同時に開発されており、私が担当するマイクロサービスが依存するマイクロサービスも開発中という状態でした。それで考え出したE2Eテストです。
考え出した背景は、次の通りです。
2019年12月14日に開催されたGDG DevFest Tokyo 2019で最初の発表を行っています。
どのように違うのかをウェブサービスのバックエンドのサービスで説明します。新たに図を起こすのが面倒なので、すでにある記事「マイクロサービスの開発とテストファースト／テスト駆動開発」からそのまま引用します。
この図では、「加盟店管理用APIマイクロサービス」が複数のマイクロサービスに依存しています。
一般的なE2Eテストとは
一般的な書籍では、テストピラミッドにおける頂点にあるE2E（End-To-End）テストは、「加盟店管理用APIマイクロサービス」およびそれが依存するすべてのマイクロサービスを何らかの環境（たとえば、Docker、あるいは開発用のクラウド環境）にデプロイして「加盟店管理用APIマイクロサービス」をテストすることを指すものが多いです。テストピラミッドの例
このテストピラミッドでは、「統合テスト」は、依存しているサービスへの呼び出し部分をモックで置き換えてサービス単体でテストすることを指すことが多いです。したがって、依存しているサービスへの呼び出しを、テスト時だけモックで置き換えられるような仕組みを埋め込む必要があります。つまり、本番環境で動作するコードの動作を確認しているわけではありません。
たとえば、実際に本番環境（もしくは開発用環境）で依存するサービスを呼び出したら、呼び出しコードに間違いがあり、モックとは異なる動作をしたり、正しく動作しなかったりする可能性があります。
そのため、統合テストの次の上の段階で行いたいのは、テスト対象のサービスの実行ファイル（本番環境にデプロイするバイナリ形式）で実際に実行して、そのAPIのエンドポイントを外部から呼び出すテストを行うことになります。
この時に、依存するサービスをどうするのかという問題に直面することになります。その結果、一般的な書籍で述べられている「E2Eテスト」ということになります。しかし、それは他の依存するサービスも動作させないといけないし、それらのサービスが動作するためのデータベースの設定が必要かもしれなく、設定が非常に面倒になります。
その結果、一般的な書籍では、E2Eテストは構築が難しいくテスト時間も要するので、単体テストや統合テストを強く勧めています。
私が定義しているE2Eテストとは
私がマイクロサービスの開発とテストファースト／テスト駆動開発」や「WEB+DB PRESS, Vol.134」の特集1「実践API設計」で述べているE2Eテストは、テスト対象のサービスの実行ファイル（本番環境にデプロイするバイナリ形式）で実際に実行して、そのAPIのエンドポイントを外部から呼び出すテストを行うのですが、以下の点が異なります。- 本物の依存するサービスは使わない
- 開発者の開発PC（たとえば、MacBook Pro）上でローカルにテストが実行できる
必要に迫られて開発した方法
2018年6月にメルペイに入社して、本格的にウェブサービスのバックエンドサービスの開発に従事するようになって担当したのが、上の図にある「加盟店管理用APIマイクロサービス」です。当時は、ほぼすべてのマイクロサービスが同時に開発されており、私が担当するマイクロサービスが依存するマイクロサービスも開発中という状態でした。それで考え出したE2Eテストです。
考え出した背景は、次の通りです。
- 自分が開発を担当するマイクロサービスの開発・テストが終わったと責任を持って言えるようにするにはどうすればよいか
- マイクロサービスが定義しているAPIの仕様に書かれている動作をすべて自動テストで確認してから、フロントエンドの担当者に、マイクロサービスの開発が終わっているので使ってくださいと言いたい
2019年12月14日に開催されたGDG DevFest Tokyo 2019で最初の発表を行っています。
〓GDG DevFest Tokyo 2019 ご登壇者紹介〓
— GDG Tokyo (@gdgtokyo) November 16, 2019
Main Sessionにて柴田 芳樹さんにご講演いただきます。『マイクロサービスの開発とテストファースト/テスト駆動開発』と題して、merpayのバックエンドエンジニアとしてどのような手順で開発し工夫をしているのかなど紹介いただきます。 #DevFest19 #gdgtokyo pic.twitter.com/IZG1rglNCT
2023-11-08 17:12
コメント(0)
株式会社カウシェを退職します [転職]
2022年10月1日から働き始めた株式会社カウシェを11月30日付けで退職します。1984年4月1日に社会人として富士ゼロックス（現在は、富士フイルムビジネスイノベーション）で働き始めてから8社目の会社でした。12月からの予定は、未定です。
メルペイとカウシェの2社で私自身が推進してきた開発手法を特集1「実践API設計」で解説しています。一年前にカウシェに入社した時点では、gRPCに基づくバックエンドサービスのAPI仕様は全く記述されていませんでした。現在は、この一年間で新規に追加されたエンドポイントでAPI仕様が記述されているだけでなく、過去の技術的負債もかなり返済され、E2Eテストも整備されている状態になっています。
雑誌の記事としては、16年振りの執筆でした。その前は「Systems Engineer Vol.1」（技術評論社、2007年4月）で書いた3本の記事が最後でした。
私にとっては21冊目となる技術書の翻訳本です。Go言語で開発するエンジニアは、「プログラミング言語Go」に加えて、必ず読んでもらいたい本です。
Developer eXperience Day 2023
「45年の歴史から振り返る、ソフトウェア開発とキャリアの変遷」と題して、私自身のソフトウェア開発とキャリアの変遷を話しました。この講演の内容は、logmiTechで紹介されています。
https://logmi.jp/tech/articles/329156
https://logmi.jp/tech/articles/329157
https://logmi.jp/tech/articles/329158
12月から新たな会社で働くのか、あるいは、働かないで過ごすのかはまだ未定です。一方で、私にとって6冊目となる書籍を執筆しているので、しばらくは、その執筆に専念するかもしれません。
雑誌記事・翻訳・講演・技術教育
この一年間の成果は次の通りです。- 出版社/メーカー: 技術評論社
- 発売日: 2023/04/22
- メディア: Kindle版
メルペイとカウシェの2社で私自身が推進してきた開発手法を特集1「実践API設計」で解説しています。一年前にカウシェに入社した時点では、gRPCに基づくバックエンドサービスのAPI仕様は全く記述されていませんでした。現在は、この一年間で新規に追加されたエンドポイントでAPI仕様が記述されているだけでなく、過去の技術的負債もかなり返済され、E2Eテストも整備されている状態になっています。
雑誌の記事としては、16年振りの執筆でした。その前は「Systems Engineer Vol.1」（技術評論社、2007年4月）で書いた3本の記事が最後でした。
Go言語 100Tips ありがちなミスを把握し、実装を最適化する impress top gearシリーズ
- 出版社/メーカー: インプレス
- 発売日: 2023/08/18
- メディア: Kindle版
私にとっては21冊目となる技術書の翻訳本です。Go言語で開発するエンジニアは、「プログラミング言語Go」に加えて、必ず読んでもらいたい本です。
Developer eXperience Day 2023
「45年の歴史から振り返る、ソフトウェア開発とキャリアの変遷」と題して、私自身のソフトウェア開発とキャリアの変遷を話しました。この講演の内容は、logmiTechで紹介されています。
技術教育
この一年間で個人として行った技術教育は、リクルート社向けの『Effective Java 第3版』研修だけでした。今後
今月で64歳になります。2020年6月20日に急性心筋梗塞で昭和大学藤が丘病院の救命救急センターへ搬送され、緊急手術を受けました。幸い、心筋の壊死の範囲も狭く、現在も元気に生活できています。12月から新たな会社で働くのか、あるいは、働かないで過ごすのかはまだ未定です。一方で、私にとって6冊目となる書籍を執筆しているので、しばらくは、その執筆に専念するかもしれません。
2023-11-01 06:10
コメント(0)
再び聴けるKOIT [KOIT]
KOITの公式ページには、次のように米国以外では聴けないことになっています。
Streaming outside the United States:しかし、過去、日本で聴けたり、聴けなかったりを繰り返しており、最近再び聴けるようになっています。
The 96.5 KOIT App and online streaming allow you to stream in the United States. All other countries are blocked. Thank you for understanding.
過去の記事から抜粋してKOITを紹介すると次のとおりです。
- 米国シリコンバレーにあるPalo Alto, CAに住んでいた頃（1991年5月から1993年4月までの2年間）、カーラジオでよく聞いていたFM放送局がKOITでした。当時は、車には、カーラジオかカセットテープのプレイヤーだけしかない頃でした。KOITを聞いていると、シリコンバレーの青空や、当時はそれほど混んでいなかったフリーウェイ260を思い出します。
- 現地の放送がそのまま流れてきますので、コマーシャルもそのまま現地の話です。
今は日本でも聴けますが、しばらくしたらまた聴けなくなるかもしれません。
2023-10-28 15:31
コメント(0)
伸ばすのが難しい能力（４） [プログラマー現役続行]
2003年以降のデジタル複合機のコントローラソフトウェア、2017年9月からのウェブサービスのバックエンド開発をテストファースト開発によるソフトウェアの自動テストを長年行ってきて、バックエンド開発については「WEB+DB PRESS Vol.134」の特集1「実践API設計」としてまとめました。デジタル複合機のコントローラソフトウェア開発については、過去にカンファレンスなどで話しています。
これらの長年の開発で気付いていなくて、最近気付いたことは、次の2つの活動は強く関連していることです。
API仕様をきちんと書かずに開発している場合、フロントエンドの開発者は、適当に仕様を推測して試してみたり、バックエンドの開発者に（Slackなどで）問い合わせたりしながら開発を続けていることが多いでしょう。
このような開発であると、バックエンド開発者にはAPI仕様を書くというモチベーションはありません。仮に書いたとしても、長期的にきちんと保守するというモチベーションもありません。
仮に、バックエンド開発者が書いた自動テストコードがあるとしても、それがすべての機能を網羅しているのか、あるいは足りないテストがあるのかは、その開発者以外は分かりません。ひょっとしたら、その開発者も分かっていないかもしれません。
さらに、このような開発サイクルが回っている開発組織へ新たな開発者が参加しても、この開発サイクルを逸脱した開発を行うことはできません。なぜなら、API仕様や実装のPRが承認されないからです。その結果、その新たな開発者は、参加する以前の開発経験に関係なく、API仕様を書いてE2Eテストを開発することを経験することになります。
しかし、多くのソフトウェア開発組織は、そのようなE2Eテストフレームワークがないため、「自動テストがない」で述べたような状況で開発が進められてしまうことが多いと推測されます。そして、そのような開発組織でしか働いたことがない開発者は、API仕様を書くという習慣を身に付けないままとなります。
これらの長年の開発で気付いていなくて、最近気付いたことは、次の2つの活動は強く関連していることです。
- API仕様をきちんと書く
- そのAPI仕様に基づく、自動テストコードを作成する
自動テストがない
API仕様に基づいて、そのエンドポイントを直接呼びだして行うE2Eテストコードがない場合、API仕様をどれだけきちんと書いて、修正や追加の際に更新することのモチベーションはあるでしょうか？API仕様をきちんと書かずに開発している場合、フロントエンドの開発者は、適当に仕様を推測して試してみたり、バックエンドの開発者に（Slackなどで）問い合わせたりしながら開発を続けていることが多いでしょう。
このような開発であると、バックエンド開発者にはAPI仕様を書くというモチベーションはありません。仮に書いたとしても、長期的にきちんと保守するというモチベーションもありません。
仮に、バックエンド開発者が書いた自動テストコードがあるとしても、それがすべての機能を網羅しているのか、あるいは足りないテストがあるのかは、その開発者以外は分かりません。ひょっとしたら、その開発者も分かっていないかもしれません。
あるべき開発サイクル
記事「実践API設計」で明示的には述べていませんでしたが、バックエンドでAPIの新たなエンドポイントを追加する場合、あるべき開発サイクルは次のようになります。- 新たなエンドポイントを定義して、その仕様（正常な動作だけでなく、エラーも含めて）を記述して、PR（Pull Request）のレビューをフロントエンド開発者に依頼する。フロンドエンド開発者は仕様から不明な点があれば、不明な点を明確にした内容を仕様に反映してもらうようにフィードバックする。
- API仕様のPRの内容をフロントエンド開発者がレビューして問題がなければ、承認する。
- バックエンド開発者は、API仕様に基づいて、そのエンドポイントを呼びだしてテストするE2Eテストを作成しながら、実装を行う。
- テストコードの作成と実装が終われば、PRを他のバックエンド開発へレビュー依頼する。
- レビューを依頼されたバックエンド開発者は、API仕様を確認して、E2Eテストで仕様が網羅されているか、漏れはないかを確認した後、実装をレビューして確認します。もしE2Eテストに、仕様に書かれていない動作がテストされてる場合、API仕様の更新を要求することになります。
さらに、このような開発サイクルが回っている開発組織へ新たな開発者が参加しても、この開発サイクルを逸脱した開発を行うことはできません。なぜなら、API仕様や実装のPRが承認されないからです。その結果、その新たな開発者は、参加する以前の開発経験に関係なく、API仕様を書いてE2Eテストを開発することを経験することになります。
しかし、多くのソフトウェア開発組織は、そのようなE2Eテストフレームワークがないため、「自動テストがない」で述べたような状況で開発が進められてしまうことが多いと推測されます。そして、そのような開発組織でしか働いたことがない開発者は、API仕様を書くという習慣を身に付けないままとなります。
2023-10-28 07:05
コメント(0)
伸ばすのが難しい能力（３） [プログラマー現役続行]
「伸ばすのが難しい能力（２）」の状況から、技術負債を返却して、API仕様ファースト開発への手順については、「実践API設計」で述べています。
記事では書いていませんが、「第5章 API仕様の技術的負債の返済」で述べている返済を実行する上での課題は、多くのソフトウェアエンジニアは、経験したことがないことなので、そのメリットを十分に理解できないことです。そのため、実際に行ってみる強い動機を持って、実践できる開発者はとても少ないと思います。
このような状況を改善にするには、私の経験からは、「やってみせるしかない」ということです。私自身がウェブサービスに本格的に従事し始めたのは、2018年6月にメルペイ社へ入社して、加盟店様向けのマイクロサービスを一から開発することを担当したときです。
「第3章 API仕様ファースト開発」で説明している手順で開発しました。その大枠の手順は、次の図（第3章の図１）で示されています（詳しいくは記事を参照してださい）。
初めてのウェブサービス開発ではありましたが、この手順が私にとっては素直な手順であり、これを実施して最初のマイクロサービスを開発しました。
その後、メルペイ内では、チームを移動していくつかのマイクロサービスの開発に従事したのですが、その多くが以下の状態でした（「第5章 API仕様の技術的負債の返済」参照）。
そのため、新たなチームへ移動するごとに「第5章 API仕様の技術的負債の返済」で述べている内容を繰り返し、一緒に開発している他の開発者にも実践してもらうように働きかけてきました。
ただし、E2Eテストフレームワークの構築は、私自身で行いました。そうやって作成したE2Eテストフレームワークは、どのマイクロサービスからも使えるように独立したライブラリとして退職前には構築しました。
このような活動の結果として、最後にいたチームでは、既存機能の修正や新規機能の追加に際しては、かならずきちんとしたAPI仕様を記述し、そのエンドポイントを呼び出すE2Eテストを作成するということを普通に行ってもらえるようになりました。
ここでの重要な点は、残念ながら「API仕様ファースト開発」はやってみせないと広がらないということです。カウシェで働き始めてから一年近くなりますが、カウシェでも今では定着しています。
- 出版社/メーカー: 技術評論社
- 発売日: 2023/04/22
- メディア: Kindle版
記事では書いていませんが、「第5章 API仕様の技術的負債の返済」で述べている返済を実行する上での課題は、多くのソフトウェアエンジニアは、経験したことがないことなので、そのメリットを十分に理解できないことです。そのため、実際に行ってみる強い動機を持って、実践できる開発者はとても少ないと思います。
このような状況を改善にするには、私の経験からは、「やってみせるしかない」ということです。私自身がウェブサービスに本格的に従事し始めたのは、2018年6月にメルペイ社へ入社して、加盟店様向けのマイクロサービスを一から開発することを担当したときです。
「第3章 API仕様ファースト開発」で説明している手順で開発しました。その大枠の手順は、次の図（第3章の図１）で示されています（詳しいくは記事を参照してださい）。
図1 API仕様ファーストでの開発順序
初めてのウェブサービス開発ではありましたが、この手順が私にとっては素直な手順であり、これを実施して最初のマイクロサービスを開発しました。
その後、メルペイ内では、チームを移動していくつかのマイクロサービスの開発に従事したのですが、その多くが以下の状態でした（「第5章 API仕様の技術的負債の返済」参照）。
- サービスのAPIに対する仕様が記述されていない
- サービスのAPIをテストする自動テストが存在しない
そのため、新たなチームへ移動するごとに「第5章 API仕様の技術的負債の返済」で述べている内容を繰り返し、一緒に開発している他の開発者にも実践してもらうように働きかけてきました。
ただし、E2Eテストフレームワークの構築は、私自身で行いました。そうやって作成したE2Eテストフレームワークは、どのマイクロサービスからも使えるように独立したライブラリとして退職前には構築しました。
このような活動の結果として、最後にいたチームでは、既存機能の修正や新規機能の追加に際しては、かならずきちんとしたAPI仕様を記述し、そのエンドポイントを呼び出すE2Eテストを作成するということを普通に行ってもらえるようになりました。
ここでの重要な点は、残念ながら「API仕様ファースト開発」はやってみせないと広がらないということです。カウシェで働き始めてから一年近くなりますが、カウシェでも今では定着しています。
2023-09-03 07:28
コメント(0)
伸ばすのが難しい能力（２） [プログラマー現役続行]
ウェブサービスは、フロントエンド（iOS、Android、ウェブブラウザ）とバックエンドから構成されます。バックエンドが提供する機能は、APIとして定義され、フロントエンドから呼び出されます。
この場合、「APIを定義する」行為にはいくつかのレベルが存在します。話を単純にするために、バックエンドのAPIがgRPCで定義されているとします。その場合、フロントエンドが呼び出すAPIは、protobufとして
次は、最低限の定義のみの例です。呼び出すrpcやmessage定義が定義されているだけです。
実は、このレベルの定義だけで開発されているウェブサービスは多いと思います。その理由として以下のものが考えられます。
サービスを短期間で開発し、顧客に価値を提供し、サービスの価値を検証するためには、この程度の仕様で十分と考えて開発が進むと、結果的に、将来のサービスの成長を大きく阻害する技術的負債を積み上げていきます。
そもそもの原因は、「APIを定義するという行為は、この程度でよいという認識のエンジニアによって作成される」からなのです。
つまり、「伸ばすのが難しい能力」で述べた経験を積んでいないエンジニアが開発することにより、この状況は発生しているとも言えます。
（続き）
この場合、「APIを定義する」行為にはいくつかのレベルが存在します。話を単純にするために、バックエンドのAPIがgRPCで定義されているとします。その場合、フロントエンドが呼び出すAPIは、protobufとして
.protoファイルに定義されます。その.protoファイルに定義されるAPIにいくつかのレベルが存在します。次は、最低限の定義のみの例です。呼び出すrpcやmessage定義が定義されているだけです。
service Greeter {
rpc SayHello (SayHelloRequest) returns (SayHelloResponse) {}
}
message SayHelloRequest {
string name = 1;
}
message SayHelloResponse {
string message = 1;
}
実は、このレベルの定義だけで開発されているウェブサービスは多いと思います。その理由として以下のものが考えられます。
- フロントエンドとバックエンドを同一のエンジニアが開発しているので、この程度で分かるから問題ないと考えてしまう。
- フロントエンドのエンジニアからの問い合わせには、都度、Slackで回答しているから問題ない。
サービスを短期間で開発し、顧客に価値を提供し、サービスの価値を検証するためには、この程度の仕様で十分と考えて開発が進むと、結果的に、将来のサービスの成長を大きく阻害する技術的負債を積み上げていきます。
そもそもの原因は、「APIを定義するという行為は、この程度でよいという認識のエンジニアによって作成される」からなのです。
つまり、「伸ばすのが難しい能力」で述べた経験を積んでいないエンジニアが開発することにより、この状況は発生しているとも言えます。
（続き）
2023-09-02 12:10
コメント(0)
実践API設計：目次 [API仕様を書く]
- 出版社/メーカー: 技術評論社
- 発売日: 2023/04/22
- メディア: Kindle版
特集1「実践API設計」の構成が分かるように目次を作成してみました。
第1章 優れたAPI仕様とは何か
特集のはじめに
APIとは
フレームワークや標準ライブラリのAPI仕様
企業内でのAPI仕様
優れたAPI仕様とは
理解が容易
変更が容易
テストが容易
API仕様でよくある問題点
API仕様が書かれていない
エラーの記述がない
自動テストが存在しない
API仕様に書くべきこと
サービスの概要の説明
個々のエンドポイントの説明
エラーの説明
パラメータの不正値
誤った順序での呼び出し
認証と認可のエラー
そのほかのエラー
まとめ
第2章 gRPCにおけるAPI仕様の書き方
gRPCとは
API仕様をどこに書くか
サービスの概要の記述
個々のエンドポイント（RPC）の説明
エラーの説明
パラメータの不正
InvalidArgument ── 不正なパラメータ値
NotFound ── リソースが見つからない
OutOfRange ── 指定された範囲のデータがない
誤った順序での呼び出し
FailedPrecondition ── 事前条件が成立していない
認証や認可のエラー
Unauthenticated ── 認証できない
PermissionDenied ── 認可できない
サービスの概要に書くべきそのほかのエラー
Canceled ── キャンセルされた
DeadlineExceeded ── 処理がタイムアウトした
Unknown ── 不明なエラー
Internal ── 内部エラーが発生した
個々のエンドポイントに書くべきそのほかのエラー
AlreadyExists ── リソースがすでに存在する
ResourceExhaused ── サービス側のリソースの枯渇
Aborted ── 処理が中断された
書く必要がないエラー
Unavailable ── サービスが動作していない
DataLoss ── データが失われた
Unimplemented ── まだ実装されていない
リストオプションの説明
まとめ
第3章 API仕様ファースト開発
開発順序
API仕様の記述
E2Eテストフレームワークの検討と実装
テストコードの作成と機能の実装
リファクタリングとカバレッジの確認
Pull Requestのレビュー
不具合の修正順序
再現テストの作成と実装の修正
リファクタリングとカバレッジの確認
既存のエンドポイントの修正と新たなエンドポイントの追加
まとめ
第4章 E2Eテストフレームワークの構築
テストフレームワークの基本的な考え方
マイクロサービス構成でのテストフレームワーク
書きたいテスト
レスポンスの確認
依存サービスを正しく呼び出しているかの確認
E2Eテストフレームワークのプロセス
E2Eテストのプロセス間シーケンス
依存サービスが外部サービスの場合の解決方法
エラーのテストは簡単
DeadlineExceededとCanceled
Aborted
非マイクロサービス構成でのテストフレームワーク
E2Eテストフレームワークの骨格
Test Suiteプロセスの骨格
テスト対象マイクロサービスの骨格
フェイクマイクロサービスの骨格
テストコードの骨格
そのほかの考慮項目
まとめ
第5章 API仕様の技術的負債の返済
技術的負債とは
API仕様の負債の返済
既存のエンドポイントを修正するケース
ステップ1：既存のAPI仕様の更新（見なおし）
ステップ2：既存のAPI仕様のテストコード作成と実行
ステップ3：新たな修正のためのAPI仕様の再修正
ステップ4：新たな修正に対するテストコードの作成
ステップ5：新たな修正の実装
ステップ6：リファクタリングとカバレッジの確認
新たなエンドポイントを追加するケース
既存のエンドポイントの不具合を修正するケース
返済順序のまとめ
E2Eテストのもう一つの利点：リファクタリング
特集のまとめ
2023-08-21 05:47
コメント(0)
前の10件 | -
著書（PDF）
翻訳本（Kindle版）
翻訳本（PDF）
