この記事は LITALICO Engineers Advent Calendar 2024 カレンダー1の14日目の記事です
はじめに
こんにちは！
最近街歩き系謎解きにどハマりしている @kotsume_373 です！
今年は新卒3年目になり、ありがたいことに今までよりも複雑な案件を担当させていただく機会が増えました。
特に、これまで自社サービスにおける機能追加や改修が中心だった私にとって、外部サービスとの連携には新しい発見がたくさんありました。
中でも「仕様の不確実さ」と向き合う場面が多く、試行錯誤しながら学んだことがたくさんあったので、
この記事では、新人エンジニアの多くが直面するであろう同じような課題に対処するためのヒントをお届けしたいと思います！
前提
筆者について
- 新卒3年目のエンジニア
- 入社以来、toC向け・障害福祉領域の転職サービス「LITALICOキャリア」の運用・保守に携わっています
- 今まで担当してきたのは、LITALICOキャリア内における新規機能追加・グロース・改修など
担当した開発について
普段から運用・保守しているLITALICOキャリアで、SNSアカウント連携機能を利用できるようにするプロジェクトでした。
具体的な機能は次の通りです。
- LITALICOキャリアへの会員登録時に、SNSアカウントを使った登録ができる機能
- SNSアカウント連携済みのユーザーが、LITALICOキャリア内の通知をSNS内のメッセージ機能でも受け取ることができる機能
また、LITALICOキャリアにおけるSNS連携機能の本格的な導入は今回が初めてでした。
一部の機能は以前にも実装されていたことはあったのですが、
4年ほど前に一時的な試験運用を行っていたのみで、現在のチーム内には知見はあまりありませんでした。
「公式ドキュメントをしっかり読み込んで、いつも通り設計して、実装すればいいんじゃないの？」
これは、プロジェクト開始時に私が思っていたことです。
自社サービス内での機能追加との差分は、「使う技術（外部サービス側が備えている機能）の詳細をまだ知らないこと」だと考えていました。
これまで、未経験だったプログラミング言語・ライブラリなど新しい技術を習得してきた経験上、公式情報をしっかりと読み込めば怖いものはないと思っていたので、
情報さえしっかりとキャッチアップできれば、いつもの自社サービス内での機能追加・改修と同じように進められるだろう。何も怖くない！
と意気込み、公式ドキュメントを読み始めました。
直面した問題
公式ドキュメントを読み終え、基本的なAPIを何種類かローカル環境で動作確認し、情報のキャッチアップはバッチリです。
あとは今までの開発プロジェクト同様、設計して作るだけ！と、意気揚々と設計を始めた矢先、いくつかの解消できない疑問に直面してしまいました。
「ドキュメントには、APIのエラー例にA、Bの二つの場合が書かれており、それぞれ別のエラーコードが割り当てられているが、AとBの両方を満たす場合はどちらのエラーコードが返ってくるのだろうか？」
「〇〇な状態で△△のAPIを叩いたらどんな実行結果になるのだろうか？」
私は、「公式ドキュメントを読めば外部サービスの仕様が完全に理解できる」と誤解してしまっていたのです。
なぜ我々は、外部サービス連携で「不確実な仕様」に直面してしまうのか
当たり前ではありますが、外部サービス自体も、なんらかのソースコードによって動いているシステムです。
ライブラリやプログラミング言語など、OSSでソースコードが公開されているものはソースコードを追えば詳細な仕様が把握できますが、
一般的な外部サービスで公開されているような公式ドキュメントは、ソースコードを日本語に翻訳しなおしたものなので、翻訳する際に情報が欠落してしまいます。
私はこのポイントを見逃していました…。
自社サービスに組み込んだときに発生しうるユースケースの挙動が、網羅的に公式ドキュメントに書かれているとは限らないのです。
「不確実な仕様に立ち向かう」 試行錯誤の道程とポイント
アプローチは大きく分けて2つあり、これらを組み合わせてうまく対処していくことが大切だと学びました。
- 仕様を知るために模索する
- 仕様がわからないことを許容して、柔軟に対応する
準備：「どの情報が足りていないか？」を早めに把握する
実装を始めて、プルリクエストのレビュー段階になってから「こういうときってどんな挙動になるのだろう？」という疑問に直面すると対応が後手にまわって大変です。（体験談）
早い段階で不確実性に気づいておくことで打ち手の幅が広がるので、
発生しうるユースケースの情報がドキュメント上に足りているか？、は早めに確認しておけるとよいと思います。
1. 仕様を知るために模索する
1-1. 実験してみる
知りたい仕様が実際に再現できるようなものであれば、実験してみるのが手っ取り早いかつ、確実に正確な情報を得られます。
実験に時間や手間・特殊なツールが必要な場合もあるので、早めに準備しておくのがよいと思います。
具体的には、「◯◯トークンの有効期限が切れたときのAPIの挙動を確認したい」などの場合、準備に時間がかかるので早めに仕込んでおけるとよいです。
※ 実験は良識の範囲内で行いましょう
1-2. 先人たちの知恵を借りる
自分で試すことが難しくても、同じような疑問に直面した先人たちの知恵を借りられる場合があります。
社内や知り合いのエンジニアなど、身近に同じような開発事例がある場合は情報提供をお願いする、
先人エンジニアが情報発信してくれている可能性があるため検索してみる、などの手段が取れると思います。
1-3. 問い合わせてみる
外部サービスに直接問い合わせてみるのも手です。
問い合わせにはリードタイムがかかることもあるので、考慮した上で計画を立てるようにしましょう。
外部サービスによっては問い合わせ窓口が用意されていないことがあったり、必ずしも情報を開示してもらえるとは限らなかったりするので、
欲しい情報が得られなかった場合のプランも同時進行で考えておくのがおすすめです。
2. 仕様がわからないことを許容して、柔軟に対応する
実際のサービス運用におけるユースケースは無限に存在するため、詳細な仕様を完全に解明することは、現実的には困難です。
そのため、設計・実装における心構えとして
- 不確実な仕様をある程度許容できるようにしておく
- 新しい仕様がわかったら、適切な処理をソースコードに反映することを前提にしておく
ことが大切だと学びました。
具体的には、想定外のレスポンスが返ってきた場合、アラートが飛んですぐに気づけるようにしておくなどが挙げられます。
私自身もまだまだ慣れておらず手札が少ない状態ですが、少しずつ経験を積んでいきたいです！
(番外編) 予測してみる
経験値の多い先輩と仕事をしていて気づいたことですが、
一般論や似たような経験と関連づけたり、外部サービスのコンセプトを深く理解したりすると、「多分こうなってそう」という予測を立てることも可能なようです。（！）
予測を過信して設計をするわけにはいかないですが、全く対処方法の見当がつかない場合は経験豊富な先輩に勘所を教えていただくのも一つの手札だと思います。
おわりに
この記事で共有した内容が、同じような課題に直面しているエンジニアの方々にとって、少しでも役に立てば幸いです！
何はともあれ、多様なチャレンジを重ねていくことが一番の学びに繋がります。
一緒に、どんどん前に転んで起き上がっていきましょう！
LITALICO Engineers Advent Calendar 2024 では、明日以降も毎日素敵な記事が公開されます！ぜひチェックしてみてください。
それでは、素敵な年末をお過ごしください