Versiyalash

Versiyalash bir ilovada controllerlar yoki alohida route'larning turli versiyalarini ishga tushirish imkonini beradi. Ilovalar tez-tez o'zgaradi va oldingi versiyani qo'llab-quvvatlash zarur bo'lgan paytda breaking changes kiritish odatiy hol.

Qo'llab-quvvatlanadigan versiyalashning 4 turi mavjud:

URI Versioning Type

URI Versioning so'rov URI ichida uzatilgan versiyani ishlatadi, masalan https://example.com/v1/route va https://example.com/v2/route.

Ilovangiz uchun URI Versioningni yoqish uchun quyidagilarni bajaring:

1const app = await NestFactory.create(AppModule);
2// or "app.enableVersioning()"
3app.enableVersioning({
4  type: VersioningType.URI,
5});
6await app.listen(process.env.PORT ?? 3000);

Header Versioning Type

Header Versioning foydalanuvchi ko'rsatgan maxsus request header orqali versiyani belgilaydi; header qiymati so'rov uchun ishlatiladigan versiya bo'ladi.

Header Versioning uchun HTTP so'rovlar misollari:

Ilovangiz uchun Header Versioningni yoqish uchun quyidagilarni bajaring:

1const app = await NestFactory.create(AppModule);
2app.enableVersioning({
3  type: VersioningType.HEADER,
4  header: 'Custom-Header',
5});
6await app.listen(process.env.PORT ?? 3000);

header xossasi so'rov versiyasini o'z ichiga oladigan header nomi bo'lishi kerak.

Media Type Versioning Type

Media Type Versioning so'rovning Accept header'idan foydalanib versiyani ko'rsatadi.

Accept header ichida versiya media type'dan nuqtali-vergul bilan ajratiladi, ;. So'ng u so'rov uchun ishlatiladigan versiyani ifodalovchi key-value juftligini o'z ichiga oladi, masalan Accept: application/json;v=2. Key versiyani aniqlashda ko'proq prefiks sifatida ko'riladi; versiyani aniqlash key va ajratgichni o'z ichiga oladigan qilib sozlanadi.

Ilovangiz uchun Media Type Versioningni yoqish uchun quyidagilarni bajaring:

1const app = await NestFactory.create(AppModule);
2app.enableVersioning({
3  type: VersioningType.MEDIA_TYPE,
4  key: 'v=',
5});
6await app.listen(process.env.PORT ?? 3000);

key xossasi versiyani o'z ichiga olgan key-value juftligining key va ajratgichidan iborat bo'lishi kerak. Accept: application/json;v=2 misolida key qiymati v= bo'ladi.

Custom Versioning Type

Custom Versioning so'rovning istalgan jihatidan versiyani (yoki versiyalarni) ko'rsatish uchun foydalanadi. Kiruvchi so'rov extractor funksiyasi yordamida tahlil qilinadi va u satr yoki satrlar massivini qaytaradi.

Agar so'rovchi bir nechta versiyani taqdim etsa, extractor funksiya eng katta/yuqori versiyadan eng kichik/past versiyagacha tartiblangan satrlar massivini qaytarishi mumkin. Versiyalar yuqoridan pastgacha tartibda route'lar bilan moslashtiriladi.

Agar extractor bo'sh satr yoki bo'sh massiv qaytarsa, hech qanday route mos kelmaydi va 404 qaytariladi.

Masalan, agar kiruvchi so'rov 1, 2, 3 versiyalarini qo'llab-quvvatlashini ko'rsatsa, extractor MUST [3, 2, 1] ni qaytarishi kerak. Bu eng yuqori mumkin bo'lgan route versiyasi avval tanlanishini ta'minlaydi.

Agar [3, 2, 1] versiyalari ajratib olingan bo'lsa, lekin route'lar faqat 2 va 1 versiyalariga mavjud bo'lsa, 2 versiyasiga mos keluvchi route tanlanadi (3 versiyasi avtomatik tarzda e'tibordan chetda qoladi).

Ilovangiz uchun Custom Versioningni yoqish uchun extractor funksiyasini yarating va uni quyidagicha ilovaga uzating:

1// Example extractor that pulls out a list of versions from a custom header and turns it into a sorted array.
2// This example uses Fastify, but Express requests can be processed in a similar way.
3const extractor = (request: FastifyRequest): string | string[] =>
4  [request.headers['custom-versioning-field'] ?? '']
5     .flatMap(v => v.split(','))
6     .filter(v => !!v)
7     .sort()
8     .reverse()
9
10const app = await NestFactory.create(AppModule);
11app.enableVersioning({
12  type: VersioningType.CUSTOM,
13  extractor,
14});
15await app.listen(process.env.PORT ?? 3000);

Foydalanish

Versiyalash controllerlarni, individual route'larni versiyalash imkonini beradi, shuningdek ayrim resurslar versiyalashdan voz kechishi uchun yo'l taqdim etadi. Versiyalashdan foydalanish, ilovangiz qaysi Versioning Type'dan foydalanyapti deganidan qat'i nazar, bir xil.

Controller versiyalari

Controllerga versiya qo'llanishi mumkin, bu controller ichidagi barcha route'lar uchun versiyani belgilaydi.

Controllerga versiya qo'shish uchun quyidagilarni bajaring:

1@Controller({
2  version: '1',
3})
4export class CatsControllerV1 {
5  @Get('cats')
6  findAll(): string {
7    return 'This action returns all cats for version 1';
8  }
9}

Route versiyalari

Versiya alohida route'ga qo'llanishi mumkin. Bu versiya route'ga ta'sir qiladigan boshqa versiyalarni, masalan Controller Version'ni override qiladi.

Alohida route'ga versiya qo'shish uchun quyidagilarni bajaring:

1import { Controller, Get, Version } from '@nestjs/common';
2
3@Controller()
4export class CatsController {
5  @Version('1')
6  @Get('cats')
7  findAllV1(): string {
8    return 'This action returns all cats for version 1';
9  }
10
11  @Version('2')
12  @Get('cats')
13  findAllV2(): string {
14    return 'This action returns all cats for version 2';
15  }
16}

Bir nechta versiyalar

Controller yoki route'ga bir nechta versiya qo'llanilishi mumkin. Bir nechta versiyadan foydalanish uchun versiyani Array sifatida belgilang.

Bir nechta versiya qo'shish uchun quyidagilarni bajaring:

1@Controller({
2  version: ['1', '2'],
3})
4export class CatsController {
5  @Get('cats')
6  findAll(): string {
7    return 'This action returns all cats for version 1 or 2';
8  }
9}

Versiya "Neutral"

Ba'zi controllerlar yoki route'lar versiyadan qat'i nazar bir xil funksionallikka ega bo'lishi mumkin. Buni qo'llab-quvvatlash uchun versiyani VERSION_NEUTRAL symboliga o'rnatish mumkin.

Kiruvchi so'rov VERSION_NEUTRAL controller yoki route'ga so'rovda versiya bor-yo'qligidan qat'i nazar moslanadi.

Versiya neutral controller yoki route qo'shish uchun quyidagilarni bajaring:

1import { Controller, Get, VERSION_NEUTRAL } from '@nestjs/common';
2
3@Controller({
4  version: VERSION_NEUTRAL,
5})
6export class CatsController {
7  @Get('cats')
8  findAll(): string {
9    return 'This action returns all cats regardless of version';
10  }
11}

Global default versiya

Agar har bir controller yoki individual route uchun versiya berishni istamasangiz, yoki versiya ko'rsatilmagan controller/route'lar uchun default versiya belgilamoqchi bo'lsangiz, defaultVersion ni quyidagicha o'rnatishingiz mumkin:

1app.enableVersioning({
2  // ...
3  defaultVersion: '1'
4  // or
5  defaultVersion: ['1', '2']
6  // or
7  defaultVersion: VERSION_NEUTRAL
8});

Middleware versiyalash

Middlewares ham versiyalash metadatasidan foydalanib middleware'ni muayyan route versiyasiga moslab sozlashi mumkin. Buning uchun MiddlewareConsumer.forRoutes() metodiga parametr sifatida versiya raqamini bering:

1import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
2import { LoggerMiddleware } from './common/middleware/logger.middleware';
3import { CatsModule } from './cats/cats.module';
4import { CatsController } from './cats/cats.controller';
5
6@Module({
7  imports: [CatsModule],
8})
9export class AppModule implements NestModule {
10  configure(consumer: MiddlewareConsumer) {
11    consumer
12      .apply(LoggerMiddleware)
13      .forRoutes({ path: 'cats', method: RequestMethod.GET, version: '2' });
14  }
15}

Yuqoridagi kod bilan LoggerMiddleware faqat /cats endpointining '2' versiyasiga qo'llanadi.