[Nestia] ابزار انتقال از Swagger به NestJS و تولید SDK & Mockup Simulator

پیشگفتار

در اینجا نستیا را معرفی می کنیم dev.to در جامعه، درخواست‌های ایمیل زیادی دریافت کردم که امیدواریم نوع دیگری از مولد کتابخانه SDK برای سایر زبان‌ها و فریم‌ورک‌های Backend وجود داشته باشد.

با دریافت ایمیل‌های آن‌ها، فکر می‌کنم به جای ساخت کتابخانه‌های تکراری برای سایر زبان‌ها و فریم‌ورک‌های باطن، بهتر است از محیط‌های دیگر در سمت نستیا فعلی پشتیبانی کنیم. من فکر می کردم که این یک راه بسیار ساده تر و سریعتر برای برآورده کردن درخواست های شما خواهد بود.

بنابراین اکنون، کتابخانه جدید خود را معرفی می کنم @nestia/migrate، که می تواند کتابخانه SDK را حتی در سایر زبان ها و فریم ورک های Backend ایجاد کند.

طرح کلی

# SETUP GLOBALLY
npm install -g @nestia/migrate

# DO MIGRATE
npx @nestia/migrate swagger.json output_directory

ابزار مهاجرت از Swagger Documents به NestJS.

وقتی می دوی npx @nestia/migrate swagger.json <output> فرمان، @nestia/migrate شما را تجزیه و تحلیل خواهد کرد swagger.json فایل، و یک پروژه NestJS را در <output> فهرست اگر قصد مهاجرت پروژه باطن خود به NestJS را دارید، @nestia/migrate نقطه شروع خوبی خواهد بود.

همچنین، @nestia/sdk می تواند موارد زیر را از پروژه NestJS تولید کند.

یعنی با @nestia/migrate، می توانید کتابخانه SDK یا Mockup Simulator را از هر پروژه باطنی ایجاد کنید. اگر برنامه ای برای مهاجرت به NestJS ندارید، اما امیدوارید از مزایای آن استفاده کنید، @nestia/migrate انتخاب خوبی خواهد بود زبان‌ها و چارچوب‌ها، دیگر در توسعه باطن اهمیتی ندارند.

بیایید از دنیای جدید لذت ببریم @nestia/migrate.

کتابخانه SDK

مجموعه ای از انواع DTO و توابع واکشی.

اگر اطلاع ندارید با nestia، اصطلاح کتابخانه SDK (کیت توسعه نرم افزار) ممکن است ناآشنا به نظر برسد. کتابخانه SDK NestJS به معنای مجموعه ای از DTO انواع و fetch توابع با تعاریف نوع برای راحتی. وقتی می دوی @nestia/sdk، کدهای سرور باطن شما را تجزیه و تحلیل می کند و چنین کتابخانه SDK را ایجاد می کند.

اگر توضیح من هنوز واضح نیست، اجازه دهید یک مثال به شما نشان دهم. به تصویر گیف زیر نگاه کنید، سپس ممکن است متوجه شوید که کتابخانه SDK چیست. سمت چپ یک کد سرور NestJS است و سمت راست یک کد برنامه مشتری (frontend) است که از کتابخانه SDK استفاده می کند. همانطور که می بینید، توسعه دهنده کلاینت (frontend) می تواند به راحتی با سرور باطن شما فقط با استفاده از نکات تایپ و تکمیل خودکار TypeScript تعامل داشته باشد.

به نظر راحت و امن نیست؟ منظور من این کتابخانه SDK است.

کد سرور NestJS

import { Controller } from "@nestjs/common";
import typia from "typia";

import core from "@nestia/core";

import { IBbsArticle } from "@api/lib/structures/IBbsArticle";

@Controller("body")
export class TypedBodyController {
    @core.TypedRoute.Post()
    public async store(
        @core.TypedBody() input: IBbsArticle.IStore,
    ): Promise<IBbsArticle> {
        const output: IBbsArticle = {
            ...typia.random<IBbsArticle>(),
            ...input,
        };
        return output;
    }
}

کد کتابخانه SDK

/**
 * @packageDocumentation
 * @module api.functional.body
 * @nestia Generated by Nestia - https://github.com/samchon/nestia 
 */
//================================================================
import { Fetcher } from "@nestia/fetcher";
import type { IConnection, Primitive } from "@nestia/fetcher";

import type { IBbsArticle } from "./../../structures/IBbsArticle";

/**
 * @controller TypedBodyController.store()
 * @path POST /body
 * @nestia Generated by Nestia - https://github.com/samchon/nestia
 */
export async function store(
    connection: IConnection,
    input: store.Input,
): Promise<store.Output> {
    return Fetcher.fetch(
        connection,
        store.ENCRYPTED,
        store.METHOD,
        store.path(),
        input,
    );
}
export namespace store {
    export type Input = Primitive<IBbsArticle.IStore>;
    export type Output = Primitive<IBbsArticle>;

    export const METHOD = "POST" as const;
    export const PATH: string = "/body";
    export const ENCRYPTED: Fetcher.IEncrypted = {
        request: false,
        response: false,
    };

    export const path = (): string => {
        return `/body`;
    }
}

شبیه ساز موکاپ

شبیه ساز سرور باطن جاسازی شده در کتابخانه SDK.

مانند موارد بالا SDK (کیت توسعه نرم افزار)، اگر از nestia آگاه نباشید، کلمه “Mockup Simulator” ممکن است ناآشنا به نظر برسد. “Mockup Simulator” به معنای شبیه ساز سرور باطن جاسازی شده در کتابخانه SDK است که توسط @nestia/sdk.

اگر توسعه frontend را تجربه کرده اید، ممکن است msw – (Mockup Service Worker) را بشناسید. Mockup Simulator از nestia تقریباً مشابه آن است، اما nestia کاملاً خودکار است. علاوه بر این، msw باید رابط های API و کدهای مدل سازی را به صورت دستی بنویسد.

اگر کد واقعی Mockup Simulator را مشاهده کردید، ممکن است دقیقاً متوجه شوید که چیست. بله، Mockup Simulator، این فقط یک تابع داخلی است که داده های تصادفی را با همان نوع رابط API برمی گرداند. به عنوان مرجع، تولید داده های ماکت توسط انجام می شود typia.random<T>() تابع، که می تواند نوع TypeScript را تجزیه و تحلیل کند و کد تولید تصادفی بهینه را در سطح تطبیق ایجاد کند.

/**
 * @packageDocumentation
 * @module api.functional.body
 * @nestia Generated by Nestia - https://github.com/samchon/nestia 
 */
//================================================================
import { Fetcher } from "@nestia/fetcher";
import type { IConnection } from "@nestia/fetcher";
import typia from "typia";

import { NestiaSimulator } from "./../../utils/NestiaSimulator";
import type { IBbsArticle } from "./../../structures/IBbsArticle";

/**
 * @controller BodyController.post()
 * @path POST /body
 * @nestia Generated by Nestia - https://github.com/samchon/nestia
 */
export async function post(
    connection: IConnection,
    body: IBbsArticle.IStore,
): Promise<post.Output> {
    return !!connection.simulate
        ? post.simulate(
              connection,
              body,
          )
        : Fetcher.fetch(
              connection,
              post.ENCRYPTED,
              post.METHOD,
              post.path(),
              body,
          );
}
export namespace post {
    export type Input = IBbsArticle.IStore;
    export type Output = IBbsArticle;

    export const METHOD = "POST" as const;
    export const PATH: string = "/body";
    export const ENCRYPTED: Fetcher.IEncrypted = {
        request: false,
        response: false,
    };

    export const path = (): string => {
        return `/body`;
    }
    export const random = (g?: Partial<typia.IRandomGenerator>): Output =>
        typia.random<Output>(g);
    export const simulate = async (
        connection: IConnection,
        body: post.Input,
    ): Promise<Output> => {
        const assert = NestiaSimulator.assert({
            method: METHOD,
            host: connection.host,
            path: path()
        });
        assert.body(() => typia.assert(body));
        return random(
            typeof connection.simulate === 'object' &&
                connection.simulate !== null
                ? connection.simulate
                : undefined
        );
    }
}

ویرایشگر نستیا

کتابخانه جدید @nestia/editor در حال آمدن است

اگر قصد مهاجرت از سرور باطن خود به NestJS را دارید، فکر می کنم فعلی است @nestia/migrate ماژول کاملاً کافی است.

با این حال، اگر نمی‌خواهید به NestJS مهاجرت کنید و فقط به کتابخانه SDK و Mockup Simulator امیدوار باشید، در حال حاضر @nestia/migrate می تواند برای شما کمی ناخوشایند باشد. نصب و اجرا npx @nestia/migrate swagger.json output_directory کمی آزاردهنده به نظر می رسد، اینطور نیست؟

بنابراین، من قصد دارم یک کتابخانه جدید بسازم @nestia/editor. این یک نوع تکامل یافته است swagger-ui تعبیه ویرایشگر TypeScript، @nestia/migrate و @nestia/sdk.

با تعبیه ویرایشگر TypeScript در swagger-ui، می توانید از مزایای کامپایلر TypeScript مانند نکات تایپ و تکمیل خودکار استفاده کنید. همچنین، اگر حالت شبیه سازی را روشن کنید، @nestia/editor از شبیه ساز Mockup تعبیه شده استفاده خواهد کرد @nestia/sdk، به جای ارسال درخواست به سرور باطن واقعی.

البته همانطور که @nestia/editor شامل می شود @nestia/migrate، می توانید کتابخانه SDK و Mockup Simulator را در وب سایت بسازید و دانلود کنید.

منتظرش باش، من دنیای جدیدی را به تو نشان خواهم داد.