نحوه استفاده از TypeSpec برای مستند سازی و مدل‌ سازی API‌ ها

احتمالا شما هم با محدودیت‌های بسیاری از ابزارها برای مستند‌سازی و مدل‌سازی API ها رو به رو شده‌اید و در این شرایط نیاز خواهید داشت که کد‌های خود را شفاف سازی کنید. ابزار‌هایی مانند Swagge , JSON بسیار قدرمند هستند، اما امکان دارد که طولانی باشد و یا برای استفاده مجدد مناسب نباشد.

در این محتوا لیارا قصد دارد نحوه‌ی استفاده از TypeSpec را برای ایجاد APIهای REST جدید، مستند و قابل نگهداری آموزش دهد.

“برای راه‌اندازی سریع و بدون دردسر برنامه‌های Typesense، از مستندات لیارا استفاده کنید.”

همین الان، بدون کمترین پیچیدگی، سرور مجازی خودتون رو در کمتر از ۳۰ ثانیه، راه‌اندازی کنید.
✅ عملکرد پایدار ✅ ترافیک نامحدود ✅ هزینه به‌صرفه
خرید سرور مجازی ابری

آنچه در ادامه خواهید خواند:

• الزامات اولیه
• TypeSpec چیست؟
• خروجی‌ های TypeSpec
• مزایای استفاده از TypeSpec
• اهداف طراحی TypeSpec در مدیریت API های مقیاس‌ پذیر
• نحوه نصب و پیکربندی TypeSpec
• نحوه ساخت یک پروژه در TypeSpec
• نحو پایه در TypeSpec
• مفاهیم پایه در TypeSpec
• سازماندهی و وارد کردن کد با استفاده از Namespace
• مقایسه با ابزارهای دیگر OpenAPI و Swagger
• نمونه کامل سرویس REST در TypeSpec
• نحوه ساخت الگوی REST API
• سرویس REST برای مدیریت کتاب ها
• بررسی پیاده سازی دستی با ExpressJS
• بررسی پیاده سازی با ASP.NET Core
• مقایسه ExpressJS و ASP.NET Core با TypeSpec
• نحوه ساختار دهی پروژه در TypeSpes
• پیشنهاد لیارا برای ساختار دهی پروژه های TypeSpec
• سوالات متداول
• جمع بندی

اسکریپت‌نویسی شل، کلید خودکارسازی کارها در لینوکس
اسکریپت‌نویسی شل

الزامات اولیه

پیش از آنکه از TypeSpec برای مستند‌سازی و مدل‌سازی API ها آن استفاده کنید. لازم است که با آن‌ها آشنا شوید و ابزارهای زیر را در اختیار داشته باشید.

• Node.js: نسخه جدید (ترجیحا بالاتر از 18 باشد).
• npm: برای مدیریت وابستگی‌ها.
• Visual Studio Code: برای تجربه بهتر و آسان‌تر مراحل ساخت پروژه از Visual Studio Code استفاده کنید.
• TypeSpec در VS Code: (می‌توانید افزونه را از طریق Visual Studio Marketplace نصب کنید).
• آشنایی با نحوه استفاده و ایجاد API ها

TypeSpec چیست؟

یک زبان اعلامی منبع باز که توسط مایکروسافت توسعه پیدا کرده است و برای توصیف API ها به صورت مفهومی‌تر، قابل استفاده مجدد، مقیاس‌پذیر و مبتنی بر استاندار‌های خاصی طراحی شده است. این زبان برای مدل سازی API های REST gRPC , GraphQL و انواع دیگر API ها طراحی شده و نجوه عملکرد آن شبیه به TypeScript است.

خروجی‌ های TypeSpec

TypeSpec می‌تواند به‌صورت خودکار موارد زیر را تولید کند:

• مشخصات OpenAPI , Schema یا Protobuf
• کد سمت سرور و کلاینت
• مستندات API
• سایر خروجی‌های مرتبط با رابط‌ها (interface)

مزایای استفاده از TypeSpec

قبل از آنکه وارد کد شویم، بیایید یک لحظه وقت بگذاریم و فلسفه TypeSpec را درک کنیم. مایکروسافت با استفاده از TypeSpec، سرویس‌های API با کیفیتی را به میلیون‌ها کاربر از طریق هزاران نقطه ارائه می‌دهد و در عین حال مطمئن می‌شود که کدهایی که به کاربران ارائه می‌دهد کیفیت بالایی داشته باشند و به راحتی قابل توسعه باشند.

در ادامه به صورت خلاصه تر این مزایا را برای شما مثال خواهیم زد.

• بهبود کیفیت کد و افزایش قابلیت نگهداری
• پشتیبانی از مقیاس پذیری در پروژه‌های بزرگ
• امکان تولید خودکار مستندات و کد
• سازگاری با ابزارهای جدید مانند Visual Studio Code
• استفاده مجدد از کد و ساده سازی طراحی‌های API ها

Kibana چیست؟ ابزار قدرتمند تجزیه و تحلیل و بصری‌سازی داده‌ها
Kibana

اهداف طراحی TypeSpec در مدیریت API های مقیاس‌ پذیر

TypeSpec برای پاسخگویی به چالش‌های اصلی طراحی و مدیریت API ها در مقیاس بزرگ طراحی شده است.

• ساده سازی: TypeSpec با استفاده از سینتکس (syntax) بسیار ساده، واضح و کوتاه کمک می‌کند که به جای اینکه با جزئیات فنی بسیار پیچیده درگیر شوید، بیشتر بر روی منطق اصلی تان تمرکز داشته باشید.
• قابلیت استفاده مجدد: در TypeSpec می‌توان انواع داده‌ها، مدل‌های درخواست و پاسخ و حتی تنظیمات مختلف را به‌صورت ماژول‌های جداگانه تعریف کرد.
• افزایش بهره وری: به‌جای اینکه مجبور باشید برای هر بخش از API جداگانه مستندات یا کدهای مختلفی را تولید کنید، در TypeSpec کافی‌ است یک‌بار تعریف اصلی خود را بنویسید، به عنوان مثال (مستندات و کد) به‌صورت خودکار از همان تعریف تولید می‌شود.
• یکپارچه سازی: با استفاده از کتابخانه‌های مشترکی که در TypeSpec وجود دارد، می‌توان اطمینان پیدا کرد که تمام API ها از قوانین و استاندارد‌های مشخصی پیروی می‌کنند و در نتیجه کیفیت و هماهنگی بین تمامی سرویس‌ها حفظ می‌شود.
• قابلیت تعامل: TypeSpec به راحتی با سیستم OpenAPI کار می‌کند و می‌تواند خروجی‌های مختلفی را مانند JSON Schema و JSON Schema یا حتی Protobuf بتوانید تولید کنید.
• قابلیت های مقیاس پذیری: TypeSpec برای استفاده در پروژه‌های بزرگ طراحی و ساخته شده است. TypeSpec این قابلیت را دارد که مدیریت هزاران نقطه پایانی (endpoint) را انجام دهد، درست مانند چیزی که در سرویس‌های ابری مایکروسافت (Azure) از آن استفاده می‌شود.

نحوه نصب و پیکربندی TypeSpec

برای شروع به نوشتن اولین API با استفاده از TypeSpec، ابتدا باید محیط توسعه را آماده کنید. در ادامه مراحل نصب و راه اندازی TypeSpec بر روی سیستم را به صورت کامل برای شما عزیزان شرح داده‌ایم.

نصب TypeSpec CLI به‌ صورت سراسری (Global)

npm install -g @typespec/compiler

نحوه ساخت یک پروژه در TypeSpec

برای اینکه بتوانید به ساده ترین شکل ممکن پروژه خود را بسازید، می‌توانید از Visual Studio Code و افزونه TypeSpec استفاده کنید، به خصوص اگر برایتان کار با خط فرمان CMD راحت نیست می‌توانید از این قابلیت استفاده کنید.

1. یک پوشه برای پروژه بسازید و آن را با Visual Studio Code باز کنید.
2. از نوار بالا وارد منوی View شوید و سپس گزینه Command Palette را انتخاب کنید.
3. در نوار جستجو عبارت TypeSpec: Create TypeSpec Project را وارد کنید.
4. مسیر پوشه‌ای را که برای پروژه در نظر گرفته‌اید انتخاب کنید.
5. در مرحله بعد، تمپلیت (Template) پروژه را انتخاب کنید. برای این راهنما، گزینه Generic REST API را انتخاب کرده و نام پروژه را وارد کنید.
6. گزینه پیش‌فرض emitter یعنی OpenAPI 3.1 document را بدون آنکه در آن تغییری را اعمال کنید به سراغ دیگر المان‌ها بروید. این گزینه از پکیج‌های @typespec/http و @typespec/openapi3 استفاده می‌کند.
7. منتظر بمانید تا پیکربندی پروژه انجام شود.

بعد از ساخت پروژه، ساختار اولیه‌ای مشابه زیر را دریافت خواهید کرد.

• node_modules/: پوشه‌ای است که وابستگی‌های پروژه توسط npm در آن نصب می‌شود.
• main.tsp: فایل اصلی پروژه و نقطه ورود TypeSpec است . تعریف مدل‌ها، سرویس‌ها و عملیات معمولا در این فایل انجام می‌شود.
• tspconfig.yaml: فایل پیکربندی کامپایلر TypeSpec که شامل گزینه‌ها و پارامترهای لازم برای فرآیند تولید خروجی است را نشان می‌دهد.

برای کامپایل کردن پروژه می‌توانید دستور زیر را وارد کنید.

tsp compile .

اما به شما پیشنهاد می‌کنیم که از حالت watch استفاده کنید تا با انجام هر بار فرآیند ذخیره‌سازی، پروژه به صورت خودکار کامپایل (Compile) شود.

tsp compile . --watch

بعد از آنکه توانستید کامپایل (Compile) را انجام دهید، پوشه‌هایی مانند tsp-output و schema ساخته می‌شوند و فایل openapi.yaml هم به آن اضافه خواهد شد.

• tsp-output/: محل تولید فایل‌های خروجی توسط کامپایلر (Compiler) TypeSpec
• openapi.yaml: فایل مشخصات OpenAPI که شامل endpoint ها، قالب‌ها و عملیات API است. محتوای این فایل به تنظیمات موجود در tspconfig.yaml بستگی دارد و با توجه به آن می‌تواند متفاونت باشد.

emit:
  - "@typespec/openapi3"
options:
  "@typespec/openapi3":
    emitter-output-dir: "{output-dir}/schema"
    openapi-versions:
      - 3.1.0

یکی از ویژگی هی بارز TypeSpec این است که می‌تواند به صورت خودکار مشخصات OpenAPI را از کدی بسازد که ساختار آن واضح، تایپ شده و غیر تکراری است. به این معنی است که می‌توانید API های خود را مشابه به TypeScript یا یک DSL ساختاریافته بنویسید و خروجی‌ در قالب فایل YAML دریافت کنید که با ابزارهایی مانند Swagger UI , Postman Redoc و دیگر اجزای OpenAPI سازگار است.

نحوه ایمن سازی Apache با Let’s Encrypt در Ubuntu 
ایمن سازی Apache

نحو پایه در TypeSpec

دیگر با مفهوم TypeSpec و مزایای آن در طراحی API تا حد زیادی آشنا شده‌اید، در این قسمت دیگر وقت آن رسیده است که به سراغ بخش اصلی آن برویم. TypeSpec از TypeScript الهام گرفته شده است و این قابلیت را به کاربران خود می‌دهد که منابع، مسیر‌ها، ساختار‌ها داده‌ها و رفتار‌های API را به صورت صریح، خوانا و غیر تکراری مدل سازی کند.

اصول اولیه زبان

در ادامه نمونه از یک مدل TypeSpec را نشان داده‌ایم به آن دقت کنید.

model Book {
  id: string;
  title: string;
  author: string;
}

در این بلوک، منبع به نام Book را با سه فیلد تایپ‌شده تعریف می‌کند. کلید واژه model برای توصیف اشیای JSON به‌کار می‌رود که API با آن‌ها کار می‌کند. این مفهوم معادل با schema در JSON Schema یا type definitions در OpenAPI است.

تعریف عملیات HTTP

TypeSpec امکان دارد که اتصال عملیات به مدل‌ها را با استفاده از کلید واژه @route فراهم کند. در ادامه یک مثال نسبی از تعریف یک endpoint را نشان شما خواهیم داد.

@route("/books")
op listBooks(): Book[];

در این قطعه کد یک عملیات REST را تعریف می‌کند که فهرستی از کتاب‌ها را به آن‌ها باز می‌گرداند. @route مسیر URL را مشخص می‌کند، op برای معرفی عملیات استفاده می‌شود و Book[] نوع داده بازگشتی را نشان می‌دهد. برای اینکه بتوانید پارامترهای مسیر (path)، کوئری (query)، یا بادی (body) را به‌سادگی تعریف کنید از قطعه کد زیر استفاده کنید.

@route("/books/{id}")
op getBook(@path id: string): Book;

در این مثال، مشخص شده است که id به‌عنوان پارامتر مسیر (path parameter) استفاده می‌شود.

۴ اشتباه رایج در هنگام استفاده از useState در ری اکت React
useState در ری اکت React

مفاهیم پایه در TypeSpec

در ادامه با مفاهیم پایه TypeSpec به صورت کامل آشنا خواهیم شد.

model: تعریف ساختار داده‌ ها

مدل‌ها نشان دهنده موجودیت‌های API ها هستند، مانند یک شی JSON. مدل‌ها بر اساس تبادل اطلاعات در API ها کار خود را انجام می‌دهند. در ادامه قطعه کد زیر را مشاهده کنید.

model User {
  id: string;
  email: string;
  age?: int32;
}

interface: گروه‌بندی عملیات

رابطه‌های مجموعه‌ای از عملیات مرتبط را گروه‌بندی می‌کند. این موضوع به ساختاردهی بهتر API های بزرگ، کمک می‌کند.

service: نقطه ورود API

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

@service({ title: "Book API", version: "1.0.0" })
namespace BookApi {
  interface BookOperations;
}

سازماندهی و وارد کردن کد با استفاده از Namespace

TypeSpec از namespace ها برای سازماندهی بهتر و واضح تر کد ها از آن استفاده می‌شود. کد مشابه ماژول‌ها یا پکیج‌ها در سایر زبان‌ها هستند.

namespace CommonModels {
  model Error {
    message: string;
  }
}

بعد از آن می‌توانید در فایل دیگری آن را به صورت زیر وارد کنید.

import CommonModels from "./common.tsp";

نمونه کامل سرویس REST در TypeSpec

در ادامه یک مثال کامل را برای یک سرویس REST با استفاده از TypeSpec را برای شما عزیزان بررسی کنیم.

@service({ title: "Book Service", version: "1.0.0" })

@route("/books")

namespace BookService {

  model Book {
    id: string;
    title: string;
    author: string;
    publishedYear?: int32;
  }

  @get()
  op listBooks(): Book[];

  @post()
  op createBook(@body book: Book): Book;

  @get("/{id}")
  op getBook(@path id: string): Book;

  @put("/{id}")
  op updateBook(@path id: string, @body book: Book): Book;

  @delete("/{id}")
  op deleteBook(@path id: string): void;
}

توضیح ساختار قطعه کد بالا:

• @service({ title, version }): متادیتای (Metadata) سرویس شامل نام و نسخه را مشخص می‌کند. این اطلاعات در مستندات تولیدشده مانند Swagger UI کاربرد دارد.
• @route("/books"): مسیر پایه برای تمام عملیات‌های این سرویس را مشخص می‌کند.
• namespace BookService { ... }: تمام مدل‌ها و عملیات‌های مرتبط با این سرویس را زیر یک فضای نام منطقی قرار می‌دهد.

عملیات‌های تعریف‌شده:

• @get() op listBooks(): یک endpoint از نوع GET برای مسیر /books که فهرستی از کتاب‌ها را بازمی‌گرداند.
• @post() op createBook(): یک endpoint از نوع POST برای مسیر /books که یک شی Book را در بدنه درخواست دریافت کرده و کتاب ایجادشده را بازمی‌گرداند.
• @get("/{id}"): یک endpoint از نوع GET برای مسیر /books/{id} که یک کتاب را بر اساس شناسه دریافت می‌کند.
• @put("/{id}"): یک endpoint از نوع PUT برای مسیر /books/{id} که اطلاعات یک کتاب را به‌روزرسانی می‌کند.
• @delete("/{id}"): یک endpoint از نوع DELETE برای حذف یک کتاب بر اساس شناسه است. نوع void به این معناست که پاسخی بازگردانده نمی‌شود.

تنها با چند خط کد، می‌توان یک سرویس REST کامل، ساختاریافته و خوانا ایجاد کرد که به‌صورت خودکار قابل تبدیل به مستندات OpenAPI، تولید SDK سمت کلاینت یا حتی کد سمت سرور است.

افزایش اعتبار سنجی

در TypeSpec می‌توانید به راحتی اعتبار سنجی‌ها را با annotation ها به مدل‌ها اضافه کنید. برای این کار از کد زیر استفاده کنید.

model Book {
  id: string;
  title: string @minLength(3);
  author: string @minLength(3);
  publishedYear?: int32 @minValue(1800);
}

این اعتبار سنجی‌ها مستقیما به schema اضافه می‌شوند و در فرآیند تولید OpenAPI لحاظ خواهد شد.

نحوه دریافت SSL در Apache در سرور مجازی دبیان
دریافت SSL در Apache در دبیان

مقایسه با ابزارهای دیگر OpenAPI و Swagger

شاید این سوال برای شما پیش بیاید که چرا به جای نوشتن مستقیم در OpenAPI از TypeSpec استفاده کنیم؟! به عنوان مثال، معادل سرویس بالا در OpenAPI 3 (YAML) به صورت زیر خواهد بود.

paths:
  /books:
    get:
      summary: Get list of books
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
    post:
      summary: Create a new book
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Book'
      responses:
        '201':
          description: Created
  /books/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
    put:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Book'
    delete:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
components:
  schemas:
    Book:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        author:
          type: string
        publishedYear:
          type: integer

همان طور که مشاهده می‌کیند، تعریف OpenAPI بسیار طولانی است. ارتباط بین مسیر‌ها، متد‌ها و پارامترها بسیار پراکنده است و همین موضوع خوانایی و نگهداری آن‌ها را دشوار می‌کند. از آن جایی که OpenAPI بر پایه YAML یا JSON نوشته می‌شود، دیگر قابلیت تایپ گذاری یا غیر تکراری بودن در آن وجود نخواهد داشت.

آپاچی Apache چیست؟ بررسی ویژگی‌ها، عملکرد و جایگزین آن
آپاچی Apache

نحوه ساخت الگوی REST API

برای اینکه بتوانید راحت تر ساخت API با TypeSpec را انجام دهید، مثال زیر را به عنوان یک شاخصه قرار دهید و از آن برای فهم بهتر استفاده کنید. در این مثال یک مدل Book ساخته می‌شود که سرویسی را برای مدیریت کتاب ها تعریف کرده است و اعتبار سنجی‌هایی را برای اطمینان از صحت داده‌ها افزایش داده می‌شود.

تعریف مدل داده برای Book

اولین فرآیندی که مشخص می‌شود مدل داده‌ای Book است. یک کتاب می‌تواند خصوصیات‌های زیر را داشته باشد.

• id: شناسه منحصر به فرد کتاب
• title: عنوان کتاب
• author: نویسنده کتاب
• publicationYear: سال انتشار کتاب
• isbn: شماره استاندارد بین‌المللی کتاب (ISBN)

مدل Book در TypeSpec:

model Book {
  id: integer;
  @minLength(1)
  title: string;
  @minLength(1)
  author: string;
  publicationYear: integer;
  @pattern("^\\d{3}-\\d{1,5}-\\d{1,7}-\\d{1,7}-\\d{1}$")
  isbn: string;
}

• id: شناسه یکتای کتاب (از نوع عدد صحیح)
• title و author: رشته‌هایی که عنوان و نویسنده را نمایش می‌دهند و با @minLength(1) اعتبارسنجی می‌شوند که خالی نباشند.
• publicationYear: سال انتشار کتاب (عدد صحیح)
• isbn: شماره ISBN که با الگوی مشخصی اعتبارسنجی می‌شود.

سرویس REST برای مدیریت کتاب ها

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

سرویس BooksService در TypeSpec:

service BooksService {

  @get("/books/{id}")
  getBook(id: integer): Book;

  @post("/books")
  createBook(book: Book): Book;

  @put("/books/{id}")
  updateBook(id: integer, book: Book): Book;

  @delete("/books/{id}")
  deleteBook(id: integer): void;
}

BooksService شامل چهار متد برای انجام عملیات مختلف بر روی کتاب‌ها است:

• @get("/books/{id}"): دریافت یک کتاب با شناسه مشخص.
• @post("/books"): ایجاد یک کتاب جدید.
• @put("/books/{id}"): به‌روزرسانی یک کتاب موجود بر اساس شناسه.
• @delete("/books/{id}"): حذف یک کتاب با استفاده از شناسه.

در این متدها از annotation های HTTP برای مشخص کردن نوع عملیات (GET, POST , PUT, DELETE) استفاده شده است.

افزایش اعتبار سنجی های بیشتر برای مدل Book

مانند مثالی که در قبل برای شما ارائه کرده‌ایم، می‌توانید از اعتبار سنجی‌های بیشتری به خصوص ویژگی مدل Book استفاده کنید.

model Book {
  id: integer;
  @minLength(1)
  title: string;
  @minLength(1)
  author: string;
  @minValue(1000)
  publicationYear: integer;
  @pattern("^\\d{3}-\\d{1,5}-\\d{1,7}-\\d{1,7}-\\d{1}$")
  isbn: string;
}

سرویس کامل برای مدیریت کردن کتاب ها

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

model Book {
  id: integer;
  @minLength(1)
  title: string;
  @minLength(1)
  author: string;
  @minValue(1000)
  publicationYear: integer;
  @pattern("^\\d{3}-\\d{1,5}-\\d{1,7}-\\d{1,7}-\\d{1}$")
  isbn: string;
}

service BooksService {
  @get("/books/{id}")
  getBook(id: integer): Book;

  @post("/books")
  createBook(book: Book): Book;

  @put("/books/{id}")
  updateBook(id: integer, book: Book): Book;

  @delete("/books/{id}")
  deleteBook(id: integer): void;
} 

آموزش نصب و راه‌اندازی فایروال UFW در سرور مجازی اوبونتو به زبان ساده
نصب و راه‌اندازی فایروال UFW در سرور مجازی اوبونتو

بررسی پیاده سازی دستی با ExpressJS

// server.ts
import express from 'express';

const app = express();
app.use(express.json());

interface Book {
  id: number;
  title: string;
  author: string;
  publicationYear: number;
  isbn: string;
}

const books: Book[] = [];

app.get('/books/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const book = books.find(b => b.id === id);
  if (!book) return res.status(404).send({ message: 'Book not found' });
  res.send(book);
});

app.post('/books', (req, res) => {
  const newBook: Book = req.body;
  books.push(newBook);
  res.status(201).send(newBook);
});

app.put('/books/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const index = books.findIndex(b => b.id === id);
  if (index === -1) return res.status(404).send({ message: 'Book not found' });

  books[index] = req.body;
  res.send(books[index]);
});

app.delete('/books/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const index = books.findIndex(b => b.id === id);
  if (index === -1) return res.status(404).send({ message: 'Book not found' });

  books.splice(index, 1);
  res.status(204).send();
});

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

نکته حائز اهمیت در این کد:

• کد تکراری زیاد است.
• اعتبارسنجی خودکار وجود ندارد.
• مستندسازی API به‌صورت خودکار انجام نمی‌شود.

مشکلات رایج DNS و راهکارهای موثر برای رفع و جلوگیری از آن‌ها
مشکلات DNS

بررسی پیاده سازی با ASP.NET Core

// Book.cs
public class Book
{
    public int Id { get; set; }

    [Required]
    public string Title { get; set; } = string.Empty;

    [Required]
    public string Author { get; set; } = string.Empty;

    [Range(1000, int.MaxValue)]
    public int PublicationYear { get; set; }

    [RegularExpression(@"^\d{3}-\d{1,5}-\d{1,7}-\d{1,7}-\d{1}$")]
    public string Isbn { get; set; } = string.Empty;
}

// BooksController.cs
[ApiController]
[Route("books")]
public class BooksController : ControllerBase
{
    private static readonly List<Book> books = new();

    [HttpGet("{id}")]
    public IActionResult GetBook(int id)
    {
        var book = books.FirstOrDefault(b => b.Id == id);
        if (book == null) return NotFound("Book not found");
        return Ok(book);
    }

    [HttpPost]
    public IActionResult CreateBook([FromBody] Book book)
    {
        books.Add(book);
        return CreatedAtAction(nameof(GetBook), new { id = book.Id }, book);
    }

    [HttpPut("{id}")]
    public IActionResult UpdateBook(int id, [FromBody] Book updatedBook)
    {
        var index = books.FindIndex(b => b.Id == id);
        if (index == -1) return NotFound("Book not found");

        books[index] = updatedBook;
        return Ok(updatedBook);
    }

    [HttpDelete("{id}")]
    public IActionResult DeleteBook(int id)
    {
        var book = books.FirstOrDefault(b => b.Id == id);
        if (book == null) return NotFound("Book not found");

        books.Remove(book);
        return NoContent();
    }
}

نکته حائز اهمیت در این کد:

• ساختار رسمی‌تر نسبت به Express دارد.
• اعتبارسنجی با استفاده از Annotation انجام می‌شود.
• مستندسازی خودکار نیاز به تنظیمات اضافه دارد.

نگاهی عمیق به معماری Iptables و Netfilter
معماری Iptables و Netfilter

مقایسه ExpressJS و ASP.NET Core با TypeSpec

ویژگی	TypeSpec	ExpressJS	ASP.NET Core
نحوه نوشتار:	اعلامی	دستوری	ساختاریافته
اعتبارسنجی:	خودکار	دستی	Annotation
مستندسازی:	خودکار	دستی	افزونه سازی
قابلیت استفاده مجدد:	بالا	پایین	متوسط
تولید API/SDK:	دارد	ندارد	قابل تنظیم

نحوه ساختار دهی پروژه در TypeSpes

برای اینکه خوانایی و نگهداری توسعه بهتر باشد، پیشنهاد می‌کنیم که ساختار پروژه‌تان به صورت زیر باشد.

project-root/
├── src/
│   ├── books/
│   │   ├── models.tsp
│   │   ├── routes.tsp
│   │   └── service.tsp
│   ├── users/
│   │   └── service.tsp
│   ├── common/
│   │   └── models.tsp
│   └── main.tsp
├── tspconfig.yaml
├── package.json
└── README.md

پیشنهاد لیارا برای ساختار دهی پروژه های TypeSpec

برای اینکه بتوانید خوانایی، مقیاس پذیری و نگهداری راحت تری را در پروژه خود داشته باشید، نکات زیر را رعایت کنید.

• استفاده از namespace: دسته بندی موضوعی برای مدل‌ها و سرویس‌ها و افزایش خوانایی فایل‌ها.
• تفکیک فایل‌ها براساس دامنه عملکرد: نگهداری آسان تر و استفاده مجدد از اجزای پروژه با ساخت پوشه‌های مجزا مانند /books , /users
• ساخت فایل‌های مشترک برای مدل‌ها و انواع عمومی: جلوگیری از تکرار کد با تعریف مدل‌های عمومی مانند، خطاها یا پاسخ‌های استاندارد در مسیر‌هایی مانند common/models.tsp
• استفاده از decorator ها: افزایش اعتبار سنجی خودکار و ساخت مستندات با استفاده از تگ هایی مانند @minLength , @route , @doc
• تنظیم @server برای محیط‌های مختلف: اطمینان خاطر از صحت ساختار API ها در فرآیند CI/CD و جلوگیری از بروز خطا در زمان اجرا.

نحوه همگام‌سازی دایرکتوری‌ها با BitTorrent Sync در اوبونتو ۲۴.۰۴
همگام‌سازی دایرکتوری‌ها با BitTorrent Sync در اوبونتو

سوالات متداول

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

TypeSpec چیست و چه کاربردی دارد؟

TypeSpec یک زبان مخصوص تعریف API است که با ساختار خوانا، امکان طراحی، مستندسازی و تولید خودکار فایل‌های مربوط به API مثل OpenAPI را فراهم می‌کند.

چه تفاوتی بین TypeSpec و فریم‌ ورک‌ هایی مانند Express یا ASP.NET Core وجود دارد؟

در TypeSpec همه چیز به‌صورت متمرکز تعریف می‌شود و می‌توان از آن خروجی‌های استانداردی گرفت، اما در Express یا ASP.NET Core باید همه چیز را به صورت دستی و کدنویسی مستقیم انجام دهید.

آیا امکان اعتبارسنجی در TypeSpec وجود دارد؟

بله، با استفاده از decorator هایی مانند @minLength , @pattern و @minValue می‌توانید بر روی داده‌ها محدودیت‌هایی اعمال کنید و از درستی اطلاعات ورودی مطمئن شوید.

آیا می‌توان از TypeSpec برای تولید مستندات خودکار استفاده کرد؟

بله، یکی از مزیت‌های اصلی TypeSpec همین امر است. مستندات API خودکار و دقیق بر اساس تعریف‌هایی که انجام شده تولید می‌شود.

جمع بندی

TypeSpec ابزاری قدرتمند برای طراحی و مستندسازی APIها است که با ساختاری ساده، امکان تعریف دقیق مدل‌ها، اعتبارسنجی داده‌ها و تولید خودکار مستندات را فراهم می‌کند. نسبت به فریم‌ورک‌های قدیمی مانند Express یا ASP.NET Core، خواناتر و قابل نگهداری‌ است. در پروژه‌های تیمی و مقیاس‌پذیر، انتخابی به‌صرفه و کاربردی محسوب می‌شود.