ایجاد کلاس API جدید

این راهنما نحوه ایجاد یک کلاس API جدید در فریمورک کیمیا را توضیح می‌دهد.

پیش‌نیازها

قبل از شروع، اطمینان حاصل کنید که:

• یک اپلیکیشن کیمیا دارید (به راهنمای ایجاد اپلیکیشن جدید مراجعه کنید)
• با ساختار پایه APIها آشنا هستید

ساختار کلاس API

کلاس پایه (Base Class)

هر کلاس API باید از کلاس base ارث‌بری کند که در فایل app/apis/base.ts تعریف شده است:

import { base } from "./base";

export class myApi extends base {
  // متدهای API اینجا تعریف می‌شوند
}

کلاس base شامل متدهای کاربردی مانند:

• appName(): نام برنامه
• appInfoLog() و appErrorLog(): لاگ‌گیری
• و هرنوع تابع مشترک دیگر...

ثبت کلاس API

کلاس‌های API باید در فایل app/apis/apis.ts ثبت شوند:

import { APIDefinition } from "@core/server";
import { myApi } from "./myApi";

export type AppAPI = "myApi" | "otherApi";
export const AppAPIs: APIDefinition<AppAPI>[] = [
  {
    name: "myApi",
    class: myApi,
  },
];

تعریف متدهای API

دکوراتورهای اصلی

@api دکوراتور

برای تعریف نقطه پایانی API استفاده می‌شود:

@api.get({ path: "my-endpoint", name: "my_endpoint_api" })
async myMethod() {
  return this.response("Hello World");
}

@api.post({ path: "create-item", name: "create_item_api" })
async createItem() {
  // کد ایجاد آیتم
}

پارامترهای path و name اجباری هستند.

@swagger دکوراتور

برای مستندسازی API استفاده می‌شود:

@swagger.parameters([
  { name: "id", type: "number", required: true, in: "query" },
  { name: "name", type: "string", required: false, in: "body" },
])
@swagger.OkResponseTSInterface("MyResponseType")

@check دکوراتور

برای کنترل دسترسی استفاده می‌شود:

@check.adminAccess()
async adminOnlyMethod() {
  // این متد فقط برای ادمین‌ها قابل دسترسی است
}

اعتبارسنجی پارامترها

از متد validateParams برای اعتبارسنجی پارامترهای ورودی استفاده کنید:

const res = await this.validateParams([
  { name: "id", cast: "number", required: true },
  { name: "name", required: true },
  { name: "email", required: false, defaultValue: "" },
]);

if (res.isFailed) return null;

const { id, name, email } = res.params;

پاسخ‌دهی

از متد this.response() برای ارسال پاسخ استفاده کنید:

// پاسخ موفق
return this.response(data);

// پاسخ خطا
return this.error400("Invalid input");
return this.error404("Not found");
return this.error500("Internal server error");

دسترسی به پارامترها

// پارامتر query/body
const id = this.param("id", 0, true); // پارامتر اجباری
const name = this.param("name", "default"); // پارامتر اختیاری

// دسترسی به کاربر درخواست‌دهنده
const user = this.requestUser;

// دسترسی به درخواست
const request = this.request;

مثال کامل

import { base } from "./base";
import { api, swagger, check } from "@core/server";

export class userApi extends base {
  @api.get({ path: "users", name: "get_users_api" })
  @swagger.OkArrayResponseTSInterface("User")
  async getUsers() {
    const users = await UserModel.findAll();
    return this.response(users);
  }

  @api.post({ path: "users", name: "create_user_api" })
  @swagger.bodyParameterWithTSInterface("CreateUserRequest")
  @check.adminAccess()
  async createUser() {
    const res = await this.validateParams([
      { name: "name", required: true },
      { name: "email", required: true },
      { name: "age", cast: "number", required: false },
    ]);

    if (res.isFailed) return null;

    const user = await UserModel.create(res.params);
    return this.response(user);
  }

  @api.put({ path: "users", name: "update_user_api" })
  @swagger.parameters([
    { name: "id", type: "number", required: true, in: "query" },
  ])
  @swagger.bodyParameterWithTSInterface("UpdateUserRequest")
  async updateUser() {
    const res = await this.validateParams([
      { name: "id", cast: "number", required: true },
      { name: "name", required: false },
      { name: "email", required: false },
    ]);

    if (res.isFailed) return null;

    const user = await UserModel.findByPk(res.params.id);
    if (!user) return this.error404("User not found");

    await user.update(res.params);
    return this.response(user);
  }
}

نکات مهم

• نام کلاس بهتر است با حروف کوچک باشد و با Api پایان یابد (مثل userApi)
• باید کلاس مورد نظر را در فایل apis.ts ثبت کنید.
• متدهای API باید async باشند
• بهتر است از validateParams برای اعتبارسنجی ورودی‌ها استفاده کنید
• از متدهای appInfoLog و appErrorLog برای لاگ‌گیری استفاده کنید
• پاسخ‌ها باید از طریق this.response() ارسال شوند
• خطاها باید با متدهای مناسب مانند error400, error404 مدیریت شوند

توسعه بیشتر

پس از ایجاد کلاس API پایه، می‌توانید:

• مدل‌های داده مرتبط را در app/models/ تعریف کنید
• رابط‌های TypeScript را در app/interfaces.ts اضافه کنید
• میان‌افزارهای سفارشی در app/middlewares/ پیاده‌سازی کنید
• رویدادهای مرتبط را در app/events/ مدیریت کنید