序文
サービス・タイピング
共通ベースプログラム
規範と基本タイプ
まず、フロントエンドとバックエンドのインタラクションの基本的なインターフェイス仕様を明確にする必要があります。例えば、インターフェイスが返すデータフォーマットはすべて従うべきです：
interface AjaxResult<R extends any> {
/** エラーコード*/
code?: number | null;
/** 説明*/
message?: string | null;
/** データサブジェクト*/
result: R
}
それに応じて、すべてのインターフェース呼び出し関数は、そのようなインターフェース定義に従うべきです：
interface AjaxFunction {
(...args: any[]): Promise<AjaxResult<any>>
}
ビジネス・ロジックで明確にする必要があるのは、インターフェイス定義の入力データと応答データのサブジェクトのタイプだけです。
代表例
ユーザーに関する情報を取得するインターフェースの例としては、swagger、yapi、あるいはwikiなど、バックエンドが提供するあらゆる形式のドキュメントがあります：
- url /api/user/info
- 取得パラメータ id を数値で渡します。
- 返されるデータの本体は、数値idと文字列nameを含むオブジェクトです。
TypeScriptの呼び出しコードとして手書きされています：
/** バックエンドデータ*/
interface UserResult {
/** id */
id: number;
/** スワッガーコードジェン*/
name: string;
}
/** インターフェース呼び出しコード*/
const getUserInfo = (id: number): AjaxResult<UserResult> => axios.get('/api/user/info', { id })
sm2tsserviceプログラムは@tefe/serviceとなります。
前の例から、サービスタイピングの本当の痛みのポイントは、既存のswaggerまたはyapiドキュメントの書式データは、マンパワーの無駄の繰り返しに等しい場合、インターフェイスドキュメントの手書きのTypeScriptコードに基づいていることがわかります技術的なソリューションの自動生成のセットを見つけるために、大幅に研究開発の効率を向上させます。
スワッガー・コデーゲン
Swaggerは、Javaコードアノテーションに基づくドキュメントを抽出するためのSwaggerシステム、Swagger-Codegen内で、Javaアノテーションの完全なセット、アノテーションパース、ドキュメントUI、さまざまな言語でのコードコールを生成するための技術ツールソリューションを提供します。
このプログラムは、TypeScriptの型、インターフェースの呼び出しコード、コアデータの変換、生成ルールの生成をサポートしています：
以上のルールから、このプログラムには次のような落とし穴があることが容易にわかります：
- タグのアノテーションが NULL ではない場合はアノテーションを変更し、 アノテーションが NULL の場合はコントローラ名を変更します；
- APIアノテーションがNULLでない、アノテーションが重複している、またはアノテーションがNULLでメソッド名が重複している場合、重複しているメソッド名の順番が変わるとoperationIdの値が変わります；
- メソッドのパラメータの順番が変わると、対応するインターフェイス呼び出しコードのパラメータも変わります。
このような落とし穴があると、特定の条件が満たされたときに生成されたコードが制御不能に変化し、非常に深刻な結果をもたらすロジックのミスマッチにつながる可能性があります。
sm2tsservice
sm2tsserviceはswagger-codegenを適応させ、その上に構築し、ビジネス利用におけるペインポイントに対処することを目的としています：
- yapi to swaggerドキュメンテーション・モジュールの実装、yapiインターフェイス呼び出しコードの自動生成のサポート。
- フロントエンドとバックエンドのコラボレーションを効率化するためのswaggerドキュメント仕様の開発。
- 生成コードの安定性を確保するためのswaggerドキュメント仕様検証、ルール修正モジュールの実装
- swaggerドキュメントのインクリメンタルアップデートモジュールを実装し、コード生成をより柔軟に制御します。
- パラメータ、データリターン検証モジュールへのインタフェースの実装、swaggerドキュメントのデータ検証の使用
yapi swaggerルールの変更
yapiドキュメントをswaggerドキュメントに変換し、カーブサポートyapi自動生成サービスコードを生成します：
スワッガー文書仕様
人為的な不確実性を排除するために設計されたインターフェイス仕様には、中核となる項目が含まれています：
スワッガー校正、補正モジュール
swaggerドキュメントが仕様に準拠しているかどうかをチェックし、operationIdの生成方法を修正するためのコアルールは以下のとおりです：
swagger-codegenコードをカスタマイズして、呼び出される関数の形式を変更します：
インクリメンタルアップデート
インターフェイスのドキュメントは、ローカルバージョンとリモートバージョンに分かれています。 ローカルバージョンは、メンテナンスのためにvcsに従います。コードが生成されるたびに、リモートバージョンがダウンロードされ、ローカルバージョンと差分されます。差分は、任意の差分と増分更新のためのWebインターフェイスの形で表示されます：
双方向キャリブレーション
デバッグ段階で、インターフェイスの入力とバックエンドのリターンを対応するswaggerドキュメントの規約と照合し、規約に準拠していないインターフェイスエラーをデフォルトで出力するプロキシプラグインを提供します。
More
- インクリメンタルアップデート技術ソリューション
- コード生成ソリューション
