Clever Geek Handbook

100番目のAPIを作成したとき、...

先週、 Perfect Solutionsで、100番目のAPIスコアを書きました。 この間ずっと、レーキ、松葉杖、自転車、およびリファクタリングの費用がかかりましたが、「APIを作成して痛みや苦痛を抑える方法」という優れた戦略を開発したことに気付きました。



この投稿は、APIのバージョン管理、サポート、バグ修正、およびライフサイクル全体に関するものです。



交通量の多い写真はありません。銀の弾丸はありません。注意を引くための写真すらありません。私たちの経験の便利な絞り込みです。 カットの下で、実際の開発経験、詰まったコーン、壊れたレーキで開発された方法論。



製品アプローチ



APIは、「すべての人のための機能のセット」ではなく、「問題を解決するためのセット」でも、「作り忘れ」でもありません。



APIは製品であり、開発者が使用する製品です。 悪いAPIを「売る」ことはできず、良いAPIを偽装します。 すべての質問は時間までに回答されます。



製品APIアプローチとは何ですか？ これは、APIが機能とバグで構成されることを意味します。 機能はシンプルかつアトミックでなければなりません。1つのAPIメソッドは1つの機能として認識されます。 APIを介してユーザーを登録することは可能ですか？ はい、機能です！ プッシュ通知を送信する機能ですか？ 機能！



そして、これは、すべてのAPIメソッドを考え、記述、開発、およびテストする必要があることを意味します-完全な開発サイクルを実行するため。 APIに対する開発者の態度の面で最大の不幸は、思考不足です。



原子操作



APIが1つのメソッドで1つのDBMSに3つのINSERTを行う場合、トランザクションが必要です。 存在しない場合、それは問題の原因であるだけでなく、見つからず、インターフェースから再現できない問題の原因にもなります 。



そして、アタルマリティの概念における別の重要なポイント。 この機能はアトミックです。 APIから新しいユーザーを登録するときに、（権利システムからの）ロールを彼に示す必要がある場合、ユーザーを登録するAPIメソッドは1つのリクエストで両方のことを行う必要があります。







たとえば、yii2の場合のメソッドは次のとおりです。 

public function actionRegister($username, $password, array $roleNames) { ... }




すべての着信パラメータとプロトコルのコンプライアンスを確認します



ユーザーから受け取ったデータと同様に、APIに来るものはすべて検証に合格する必要があります。 APIは開発者によって使用されますが、APIは同じユーザーであり、人々です。



現実に対応する標準のhttp-answersは、サポートとデバッグを簡素化するための重要なポイントです。 無効なリクエスト、検証なし-「400 Bad Request」、内部エラー-「500 Internal Server Error」。 これは、ロギング（nginxログ）および将来のすべてのバグの修正に非常に重要です。 APIのステータスが常に200である場合、ログでエラーの原因を見つけることは非常に困難です。



バグを修正します



APIを破棄せず、「後で新しいバージョンを作成する」こともありません。 このバージョンのAPI、このコード、および明日のバグを修正します。



これは、他の製品と同様に、APIはデバッグ、テスト、および保守が必要なものであるという事実に基づいています。 そのため、最も一般的なルールセットがあります。





APIをバージョン管理する方法を考案したとは思わない





APIバージョン管理は、古いメソッドを破棄せずに古いバージョンのままにして、新しいメソッドの下位互換性を失うのに役立ちます。 インターネットには、APIをバージョン管理するためのさまざまな方法が用意されています。 さまざまなフレームワーク、アプローチ、その他すべての方法はありませんが、特効薬はありません。 そのためには、ほぼすべての弾丸が簡単に届く店舗-nginxの場所です。 

  location /api/v1/ { ... } location /api/v2/ { ... }


このアプローチにより、古いAPIを適切なタイミングで破棄できるだけでなく、新しいAPIを別のアプリケーションの別のサーバーに移動することもできますが、通常はどこにでも移動できます。 これは「すべての問題の解決策」ではなく、多くの決定をまとめることができる箱であり、時間とともに変化します。



ドキュメントドライブ開発



多くの場合、APIドキュメントは苦痛です。 ドキュメントはほとんど常に最新であり、swaggerなどのツールは引き続きサポートが必要です。 この問題は、食品のアプローチに従えば簡単に解決できます-ドキュメントから始めます。 jira / redmineでタスクを開始するのはそうです-APIに必要なものすべてをそこに記述します。 ドキュメント形式で。



バトルサーバーに新しいメソッドを配置します。タスクからドキュメントリポジトリにドキュメントをコピーするだけです。 そして出来上がり-あなたのドキュメントは常に最新です。



類推としてのFP



簡単なAPIメソッドを作成します。 Erlangで関数を書くことを想像してください。 問題のまともな部分は、「すべてのロシアの方法」、「すべてのための方法」、またはロジックでオーバーロードされた方法です。



APIメソッドはアトミックである必要がありますが、十分です。 また、ブレークが小さすぎると、反対側が問題につながります。



頑張って



APIの開発における主観的な経験を簡単に説明しましたが、意味のあるコードは提供しませんでした-あなたはまだコードを持っています。



しかし、これらはすべて論文の形式では短くなっています。



More articles:


All Articles