API 計画ガイド: コードファースト VS デザインファーストのアプローチ-Python チュートリアル-php.cn

A Guide to Planning Your API: Code-First VS Design-First Approach

あなたは何もない野原に立っている建築家であると想像してください。設計図がなければレンガを積み始めることはできませんよね？同じ原則が API 開発にも当てはまります。私はデザインファーストのアプローチを学ぶまで、コードファーストのアプローチを使用し、最初にコードを書き、後でドキュメントを作成していました。設計優先のアプローチでは、コードを記述する前に詳細な API 定義を作成します。

このガイドの概要

本題に入る前に、目標を計画しましょう。これを API 計画ロードマップとして考えてください:

API 計画の基礎を学びます
2 つの異なる方法を検討してください
賢明な選択をしましょう
API プランを作成します

学習内容:

API 計画には何が含まれます
コードファーストアプローチ
デザインファーストアプローチ
コードファーストとデザインファーストの比較
適切な方法を選択する方法
API 計画の実践的な手順

API 計画には何が含まれます

優れた API の基盤

API の計画は技術仕様だけではなく、他の人が使いたくなる製品を構築することも重要です。それは、すべての部屋に目的があり、他の部屋と論理的に接続されている家を設計するようなものです。

答えるべき重要な質問:

消費者とは誰ですか? (フロントエンド開発者、サードパーティパートナーなど)
どのような操作をサポートしていますか? (CRUD操作、統合など)
その安全性を確保するにはどうすればよいですか? (認証、レート制限など)

計画の芸術

API 計画と傑作の描画を比較します:

コードファーストは、下書きせずに絵を描くようなものです
デザインを最初に行うことは、構成を最初に計画することに似ています

コードファーストアプローチ

コードファーストのアプローチとは、API の構造ドキュメントや設計を作成する前に、コーディングと機能の作成に直接取り組むことです。 API の構築を始めたとき、私はコードファーストの支持者でした。私が学んだことは次のとおりです:

<code>// 第一天：“这看起来很简单！”
app.get('/users', getUsers);

// 第二周：“哦，等等，我需要过滤……”
app.get('/users', authenticateUser, validateQuery, getUsers);

// 第三周：“也许我应该更好地规划一下……”</code>

ログイン後にコピー

クイックヒント ✨: コードファーストはプロトタイプには機能しますが、作成する際に決定事項を文書化してください。

仕組み

バックエンドの開発とモックアップから始めます。
データベース構造に基づいて API エンドポイントを構築します。
実装後に API ドキュメントを作成します。

メリット

プロトタイピングの高速化: 小規模チームや個人プロジェクトに最適です。
簡単な実装: 事前の計画を立てずに機能の構築に重点を置きます。

チャレンジ

一貫性のない設計: 複数の開発者が関与している場合、API に一貫性が欠けている可能性があります。
反復は困難です。開発後に大幅な変更を加えるとコストがかかる可能性があります。

デザインファーストアプローチ

デザインファーストのアプローチでは、コードを記述する前に API の構造を計画して定義することに重点を置きます。全員が同じ認識を保つことができます。 API 定義が合意されると、テスターやテクニカルライターなどの関係者は開発者と並行して作業できるようになります。

仕組み

Swagger/OpenAPI などのツールを使用して API パターンを設計します。
エンドポイント、リクエスト/レスポンスの形式、検証を定義します。
デザインを関係者と共有してフィードバックを受け取ります。
デザインが決定した後に開発が開始されます。

メリット

コラボレーション: 関係者からの早期フィードバックを促進します。
一貫性: エンドポイントの一貫性を確保します。
モック API: フロントエンドチームがモック応答を使用して統合を早期に開始できるようにします。

チャレンジ

事前の取り組み: 初期設計には時間がかかります。
必要な専門知識: 開発者は、設計ツールとベストプラクティスに精通している必要があります。

コードファーストとデザインファースト: 比較

コードファースト

速度: 単純なプロジェクトの場合は高速です。
コラボレーション: 初期段階では限定的です。
一貫性: これはエンドポイントによって異なる場合があります。
柔軟性: 単独での開発が簡単です。
スケーラビリティ: これを拡張するのは難しいかもしれません。

まずデザインします

速度: 初期の計画のため遅いです。
コラボレーション: 早期のチームコラボレーションを奨励します。
一貫性: 標準化された設計を確保します。
柔軟性: チームまたはパブリック API に最適です。
スケーラビリティ: スケーラビリティを念頭に置いて設計されています。

適切な方法を選択する方法

次の場合にコードファーストを選択します:

あなたは、簡単な概念実証または内部 API を構築しています。
API コンシューマーは 1 つの小さなチームです。
あなたはデザインよりもスピードを優先します。

次の条件が満たされる場合は、デザイン優先度を選択してください:

API は外部の消費者または複数のチームに公開されます。
コラボレーションと一貫性が最優先事項です。
あなたはパブリック API または長期的な API を構築しています。

API 計画の実践的な手順

ステップ 1: API の目的を定義する

エンドポイントとメソッドについて詳しく説明する前に、次の基本的な質問に答えてください:

あなたの API はどのような問題を解決しますか?
あなたのターゲットユーザーは誰ですか?
どのようなコア機能を提供する必要がありますか?
機能以外の要件は何ですか?

目的のステートメントの例:

<code>// 第一天：“这看起来很简单！”
app.get('/users', getUsers);

// 第二周：“哦，等等，我需要过滤……”
app.get('/users', authenticateUser, validateQuery, getUsers);

// 第三周：“也许我应该更好地规划一下……”</code>

ログイン後にコピー

ステップ 2: コアリソースを特定する

リソースは API の名詞と考えてください。 e コマースの例:

主なリソース:

製品
在庫
倉庫
在庫の変更

リソース関係:

<code>// 第一天：“这看起来很简单！”
app.get('/users', getUsers);

// 第二周：“哦，等等，我需要过滤……”
app.get('/users', authenticateUser, validateQuery, getUsers);

// 第三周：“也许我应该更好地规划一下……”</code>

ログイン後にコピー

ステップ 3: 操作を定義する

次に、ユーザーがこれらのリソースに対してどのようなアクション (動詞) を実行する必要があるかを検討します。

<code>此API使电子商务平台能够实时管理多个仓库的库存，确保准确的库存水平并防止超卖。</code>

ログイン後にコピー

ステップ 4: データモデルを計画する

明確で一貫したデータ構造を定義します:

<code>产品
  └── 库存
       └── 仓库
            └── 库存变动</code>

ログイン後にコピー

ステップ 5: 認証とセキュリティを計画する

最初からセキュリティについて考えてみましょう:

認証方法
認証レベル
レート制限
データ暗号化
入力確認

ステップ 6: API ドキュメントを作成する

包括的なドキュメントを作成します:

API 概要

目的と範囲
スタートガイド
認証の詳細

エンドポイントのドキュメント

リソースの説明
リクエスト/レスポンスのフォーマット
呼び出しの例
エラー処理

使用例

一般的なシナリオ
統合例
ベストプラクティス

結論

API 開発ではコードファーストとデザインファーストの両方のアプローチが重要です。重要なのは、プロジェクトのニーズ、チームの規模、長期目標に合ったアプローチを選択することです。最終的には、コードファーストのアプローチを選択するか、デザインファーストのアプローチを選択するかに関係なく、目標は開発者が使いやすい API を作成することです。旅は目的地ほど重要ではない場合もありますが、適切な地図があれば旅が楽になります。