NestJS'da API versioning — v1, v2 va deprecation (8.27-bob)

  MUAMMO: API javobini o'zgartirish → eski mijozlar buziladi

  v1 javob:  { "name": "Ali", "phone": "+998..." }
  O'zgartirdingiz:  { "fullName": "Ali", "contact": { "phone": "..." } }
  → Eski mobil ilova "name" kutadi → undefined → ilova buziladi!

  YECHIM — VERSIONING:
  /v1/users → eski format (eski mijozlar)
  /v2/users → yangi format (yangi mijozlar)
  → ikkalasi ishlaydi (eski sindirilmaydi)

  NON-BREAKING (versiya kerak EMAS — qo'shish mumkin):
  ✓ Yangi ixtiyoriy maydon qo'shish (javobga)
  ✓ Yangi endpoint qo'shish
  ✓ Yangi ixtiyoriy parametr (default bilan)

  BREAKING (versiya KERAK — eski mijozni buzadi):
  ❌ Maydon o'chirish/nomini o'zgartirish
  ❌ Javob strukturasini o'zgartirish
  ❌ Maydon turini o'zgartirish (string → object)
  ❌ Majburiy parametr qo'shish
  ❌ Xulq o'zgarishi (status kod, validatsiya qoidasi)

  → Faqat BREAKING o'zgarish uchun yangi versiya (har o'zgarishga emas)

  ┌──────────────┬──────────────────────────────────────────────┐
  │ URI          │ /v1/users, /v2/users                         │
  │              │ ✓ Aniq, ko'rinadigan, oson test (brauzer)    │
  │              │ ✗ "toza REST emas" (resurs URL o'zgaradi)    │
  │              │ → ENG KENG (amaliy, aniq)                     │
  ├──────────────┼──────────────────────────────────────────────┤
  │ Header       │ Accept-Version: 2 / X-API-Version: 2         │
  │              │ ✓ URL toza; ✗ ko'rinmaydi (test qiyin)       │
  ├──────────────┼──────────────────────────────────────────────┤
  │ Media type   │ Accept: application/vnd.api.v2+json          │
  │              │ ✓ "toza REST"; ✗ murakkab                    │
  ├──────────────┼──────────────────────────────────────────────┤
  │ Query        │ /users?version=2                             │
  │              │ ✓ oddiy; ✗ kesh/yo'naltirish muammosi        │
  └──────────────┴──────────────────────────────────────────────┘

// main.ts — versioning yoqish
import { VersioningType } from "@nestjs/common";

app.enableVersioning({
  type: VersioningType.URI,                           // /v1/, /v2/ (2.3)
  defaultVersion: "1",
});

// Controller — versiya bilan
@Controller({ path: "users", version: "1" })
export class UsersV1Controller {
  @Get() hammasi() { return this.service.eskiFormat(); }
}

@Controller({ path: "users", version: "2" })          // /v2/users
export class UsersV2Controller {
  @Get() hammasi() { return this.service.yangiFormat(); }
}

import { VersioningType } from "@nestjs/common";

// (1) URI — /v1/users (eng keng)
app.enableVersioning({ type: VersioningType.URI, prefix: "v", defaultVersion: "1" });

// (2) HEADER — maxsus header'da versiya (URL bir xil qoladi)
app.enableVersioning({ type: VersioningType.HEADER, header: "X-API-Version" });
// Mijoz: GET /users + "X-API-Version: 2"

// (3) MEDIA_TYPE — Accept sarlavhasida versiya (toza REST — resurs URL o'zgarmaydi)
app.enableVersioning({ type: VersioningType.MEDIA_TYPE, key: "v=" });
// Mijoz: GET /users + "Accept: application/json;v=2"  → key "v=" dan keyingi qiymat = versiya

// (4) CUSTOM — versiyani so'rovdan o'zingiz ajratib olasiz (extractor funksiya)
app.enableVersioning({
  type: VersioningType.CUSTOM,
  // So'rovdan versiyani qaytaradigan funksiya (masalan, subdomen yoki maxsus mantiq)
  extractor: (req: Record<string, any>): string | string[] => {
    const host = req.headers?.host ?? "";       // masalan, "v2.api.example.com"
    const match = host.match(/^v(\d+)\./);        // subdomen'dan versiya
    return match ? match[1] : "1";                // topilmasa — v1 (default)
  },
});

// Muammo: v1 va v2 ko'p kod takrorlaydi
// Yechim: umumiy service, faqat FARQNI versiyalash (DTO/transformer)

@Injectable()
export class UsersService {                           // umumiy biznes mantiq (bir marta)
  hammasi() { return this.repo.find(); }              // ichki domen format
}

// V1 — eski format (transformer)
@Controller({ path: "users", version: "1" })
export class UsersV1Controller {
  constructor(private service: UsersService) {}
  @Get() async hammasi() {
    const users = await this.service.hammasi();
    return users.map((u) => ({ name: u.ism, phone: u.telefon }));   // V1 format (8.5 Response DTO)
  }
}
// V2 — yangi format
@Controller({ path: "users", version: "2" })
export class UsersV2Controller {
  @Get() async hammasi() {
    const users = await this.service.hammasi();
    return users.map((u) => ({ fullName: u.ism, contact: { phone: u.telefon } }));   // V2
  }
}

  DEPRECATION — eski versiyani ASTA-SEKIN to'xtatish (birdan emas):

  1. E'lon: "v1 6 oydan keyin to'xtaydi, v2 ga o'ting" (oldindan!)
  2. Ogohlantirish header: Deprecation: true, Sunset: 2026-12-31
  3. Hujjat: v1 deprecated, v2 tavsiya
  4. Monitoring: v1 hali kim ishlatadi (kuzatish)
  5. To'xtatish: muddat o'tgach (mijozlar ko'chgach)

  ❗ Mijozga VAQT bering (mobil — oylar kerak); birdan to'xtatmang

  ❗ KAM versiya saqlang (har versiya — qo'shimcha yuk):
  - 1-2 faol versiya (joriy + oldingi)
  - Eskisini deprecate qiling (yangi qo'shilganda)
  - "Versiyasiz qancha mumkin" (non-breaking — 2.2)

  Semantic versioning (API):
  - Major (v1→v2): breaking change (yangi versiya)
  - Minor/patch: non-breaking (versiyasiz qo'shish)

  → Versiya — oxirgi chora (avval non-breaking yo'lini izlash)

  MIGRATSIYA — mijozni v1'dan v2'ga ko'chirish rejasi:

  1. v2 chiqadi (v1 hali ishlaydi — ikkalasi parallel)
  2. v1 deprecate (Deprecation/Sunset header — 2.6)
  3. Migratsiya qo'llanmasi (v1→v2 farqlar: qaysi maydon o'zgardi, mapping)
  4. Mijoz o'z tezligida ko'chadi (monitoring bilan kuzatasiz — Misol 8)
  5. v1 trafigi ~0 → to'xtatish

  TRANSFORMER — v1↔v2 formatni bir joyda ushlash:
  domen (User) → V1Dto (eski) / V2Dto (yangi) — bitta domen, ikki xarita

// Bir domen (User) → ikki versiya xaritasi (migratsiya ko'prigi)
export class UserMapper {
  // v2 → v1 (eski mijoz uchun — yangi maydonlarni yashiradi/tekislaydi)
  static toV1(u: User) {
    return { name: u.ism, phone: u.telefon };            // eski tekis struktura
  }
  // domen → v2 (yangi mijoz uchun — boy struktura)
  static toV2(u: User) {
    return {
      fullName: u.ism,
      contact: { phone: u.telefon, email: u.email },      // ichma-ich (breaking)
      createdAt: u.createdAt.toISOString(),
    };
  }
}
// → yangi maydon domenga qo'shilsa, faqat toV2 o'zgaradi; toV1 barqaror (v1 mijoz buzilmaydi)

  REST:  versiya (v1/v2) — butun endpoint takrorlanadi
  GraphQL: odatda VERSIYASIZ — schema evolyutsiyasi (bitta endpoint)

  GraphQL yondashuvi:
  - Yangi maydon QO'SHISH (non-breaking — mijoz so'ramasa, ta'sir yo'q)
  - Eski maydonni @deprecated bilan belgilash (o'chirmasdan)
  - Mijoz faqat kerakli maydonni so'raydi → versiya kamdan-kam kerak

import { Field, ObjectType } from "@nestjs/graphql";

@ObjectType()
export class UserType {
  @Field()
  fullName: string;

  // Eski maydon — o'chirilmaydi, deprecated deb belgilanadi (mijozga ogohlantirish)
  @Field({ deprecationReason: "'fullName' ishlating; 'name' keyinchalik olib tashlanadi" })
  name: string;
}

  ✓ Faqat BREAKING uchun versiya (non-breaking — versiyasiz — 2.2)
  ✓ URI versioning (aniq, eng keng — 2.3)
  ✓ Umumiy service + versiyalangan DTO/transformer (DRY — 2.5)
  ✓ Kam versiya (1-2 faol — 2.7)
  ✓ Deprecation (asta-sekin, ogohlantirish, vaqt — 2.6)
  ✓ Hujjatlash (Swagger — har versiya — 8.8)
  ✓ Monitoring (eski versiya kim ishlatadi — 8.15, 2.6)
  ✓ defaultVersion (versiyasiz so'rov — 2.4)
  ✓ Versiyalashni boshidan rejalashtir (keyin qo'shish qiyin)

// Yoqish 2.4-bob: app.enableVersioning({ type: VersioningType.URI, defaultVersion: "1" })
// Turlar 2.4-bob: VersioningType.URI | HEADER | MEDIA_TYPE | CUSTOM
//   HEADER:     { type: ..., header: "X-API-Version" }
//   MEDIA_TYPE: { type: ..., key: "v=" }              // Accept: application/json;v=2
//   CUSTOM:     { type: ..., extractor: (req) => "2" } // versiyani o'zingiz ajratasiz
// Controller 2.4-bob: @Controller({ path: "users", version: "2" })
// Metod: @Version("2")  bitta(...) {}
// Bir nechta versiya: @Version(["1", "2"])
// Neutral (versiyasiz): version: VERSION_NEUTRAL       // barcha versiyada

// main.ts
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.enableVersioning({
    type: VersioningType.URI,                         // /v1/, /v2/
    defaultVersion: "1",                              // versiyasiz → v1
    prefix: "v",                                       // /v1/ (default "v")
  });
  await app.listen(3000);
}
// GET /v1/users → V1; GET /v2/users → V2; GET /users → v1 (default)

// Umumiy service (biznes mantiq — bir marta — 8.1)
@Injectable()
export class UsersService {
  constructor(@InjectRepository(User) private repo: Repository<User>) {}
  async hammasi(): Promise<User[]> { return this.repo.find(); }
  async bitta(id: string): Promise<User> {
    const u = await this.repo.findOneBy({ id });
    if (!u) throw new NotFoundException();
    return u;
  }
}

// V1 controller — eski format
@Controller({ path: "users", version: "1" })
export class UsersV1Controller {
  constructor(private service: UsersService) {}
  @Get()
  async hammasi() {
    const users = await this.service.hammasi();
    return users.map((u) => UserV1Dto.from(u));       // eski format (8.5)
  }
}

// V2 controller — yangi format
@Controller({ path: "users", version: "2" })
export class UsersV2Controller {
  constructor(private service: UsersService) {}        // SHU service (DRY)
  @Get()
  async hammasi() {
    const users = await this.service.hammasi();
    return users.map((u) => UserV2Dto.from(u));       // yangi format
  }
}

// V1 format (eski)
export class UserV1Dto {
  name: string;
  phone: string;
  static from(u: User): UserV1Dto {
    return { name: u.ism, phone: u.telefon };          // eski struktura
  }
}

// V2 format (yangi — breaking change)
export class UserV2Dto {
  fullName: string;
  contact: { phone: string; email: string };
  createdAt: string;
  static from(u: User): UserV2Dto {
    return {
      fullName: u.ism,
      contact: { phone: u.telefon, email: u.email },   // yangi struktura (breaking)
      createdAt: u.createdAt.toISOString(),
    };
  }
}
// → bir domen (User), ikki format (versiya) — transformer (DRY)

// Ba'zi endpoint o'zgarmadi (neutral), ba'zisi versiyalangan
@Controller({ path: "products" })
export class ProductsController {
  constructor(private service: ProductsService) {}

  @Get()
  @Version(VERSION_NEUTRAL)                           // har versiyada bir xil (o'zgarmagan)
  hammasi() { return this.service.hammasi(); }

  @Get(":id")
  @Version("1")                                       // v1 format
  bittaV1(@Param("id") id: string) {
    return this.service.bitta(id).then((p) => ({ id: p.id, narx: p.narx }));
  }

  @Get(":id")
  @Version("2")                                       // v2 format (qo'shimcha)
  bittaV2(@Param("id") id: string) {
    return this.service.bitta(id).then((p) => ({
      id: p.id, narx: { miqdor: p.narx, valyuta: "UZS" }, chegirma: p.chegirma,
    }));
  }
}

// Eski versiyani deprecated belgilash (ogohlantirish)
@Injectable()
export class DeprecationInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const res = context.switchToHttp().getResponse();
    const version = context.switchToHttp().getRequest().version;

    if (version === "1") {                            // v1 deprecated
      res.setHeader("Deprecation", "true");
      res.setHeader("Sunset", "2026-12-31");          // qachon to'xtaydi (2.6)
      res.setHeader("Link", '</v2/users>; rel="successor-version"');   // v2 ga ishora
    }
    return next.handle();
  }
}
// → v1 ishlatuvchi mijoz ogohlantirish ko'radi (response header)

// main.ts — header versioning (URL toza)
app.enableVersioning({
  type: VersioningType.HEADER,
  header: "X-API-Version",                            // X-API-Version: 2
  defaultVersion: "1",
});
// Mijoz: GET /users + header "X-API-Version: 2" → V2
// URL bir xil (/users), versiya header'da

// Har versiya alohida Swagger hujjat (8.8)
const configV1 = new DocumentBuilder().setTitle("API v1").setVersion("1.0").build();
const docV1 = SwaggerModule.createDocument(app, configV1, {
  include: [UsersV1Controller, /* v1 controllers */],
});
SwaggerModule.setup("api/v1/docs", app, docV1);

const configV2 = new DocumentBuilder().setTitle("API v2").setVersion("2.0").build();
const docV2 = SwaggerModule.createDocument(app, configV2, {
  include: [UsersV2Controller],
});
SwaggerModule.setup("api/v2/docs", app, docV2);
// → har versiya o'z hujjati (mijoz qaysi versiyani ishlatsa, o'shani ko'radi)

// Eski versiya kim ishlatishini kuzatish (deprecation rejasi uchun)
@Injectable()
export class VersionMetricsInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const req = context.switchToHttp().getRequest();
    const version = req.version || "1";
    // Metrika (8.15 — qaysi versiya, qancha so'rov)
    this.metrics.increment(`api.version.${version}`, { endpoint: req.route?.path });
    return next.handle();
  }
}
// → "v1 hali 30% so'rov" → deprecation muddatini rejalashtirib bo'lmaydi (mijozlar bor)
// → "v1 0.1%" → to'xtatish mumkin (deyarli hech kim ishlatmaydi)

// Non-breaking — versiya KERAK EMAS (qo'shish)
@Controller({ path: "users", version: "1" })
export class UsersController {
  @Get(":id")
  async bitta(@Param("id") id: string) {
    const u = await this.service.bitta(id);
    return {
      name: u.ism,
      phone: u.telefon,
      // YANGI ixtiyoriy maydon qo'shish — non-breaking (eski mijoz e'tiborsiz qoldiradi)
      avatar: u.avatar,                               // qo'shish OK (versiyasiz)
      // ❌ "name" o'chirish/o'zgartirish — breaking (versiya kerak)
    };
  }
}
// → iloji boricha non-breaking (versiyasiz) — versiya oxirgi chora (2.7)

  src/
  ├── users/
  │   ├── users.service.ts           (umumiy biznes — versiyasiz — Misol 2)
  │   ├── controllers/
  │   │   ├── users-v1.controller.ts (Misol 2)
  │   │   └── users-v2.controller.ts
  │   ├── dto/
  │   │   ├── user-v1.dto.ts          (eski format — Misol 3)
  │   │   └── user-v2.dto.ts          (yangi format)
  │   └── users.module.ts
  ├── common/
  │   ├── deprecation.interceptor.ts (Misol 5)
  │   └── version-metrics.interceptor.ts (Misol 8)

  Strategiya:
  - Service qatlami — versiyasiz (DRY — biznes mantiq bir marta)
  - Controller + DTO — versiyalangan (faqat format farqi)
  - Non-breaking → versiyasiz qo'shish 2.2-bob
  - Breaking → yangi versiya + eski deprecate 2.6-bob
  - 1-2 faol versiya (kam — 2.7)

// Bitta DTO — @Expose({ groups }) bilan versiyaga qarab turli maydonlar
import { Expose, Type, plainToInstance } from "class-transformer";

export class UserResponseDto {
  @Expose({ groups: ["v1", "v2"] })                     // ikkala versiyada ham
  id: string;

  @Expose({ groups: ["v1"], name: "name" })             // faqat v1 (eski nom)
  ismV1: string;

  @Expose({ groups: ["v2"] })                           // faqat v2 (yangi nom)
  fullName: string;

  @Expose({ groups: ["v2"] })                           // v2'da qo'shilgan (yangi)
  @Type(() => ContactDto)
  contact: ContactDto;
}

// Controller — versiyaga qarab guruh tanlaydi (bitta DTO, ikki chiqish)
@Get()
async hammasi(@Req() req: Request) {
  const users = await this.service.hammasi();
  const guruh = req["version"] === "2" ? "v2" : "v1";   // versiyadan guruh
  return plainToInstance(UserResponseDto, users, { groups: [guruh] });
}
// → transformer sinflar takrorini kamaytiradi (bitta DTO, guruh bilan versiyalash)

// main.ts — MEDIA_TYPE (Accept sarlavhasi orqali — "toza REST")
app.enableVersioning({
  type: VersioningType.MEDIA_TYPE,
  key: "v=",                                            // Accept: application/json;v=2
  defaultVersion: "1",
});

// yoki CUSTOM — versiyani so'rovdan o'zingiz ajratasiz (masalan, subdomen)
app.enableVersioning({
  type: VersioningType.CUSTOM,
  extractor: (req: Record<string, any>): string => {
    const header = req.headers?.["accept-version"];      // "2024-01-01" kabi sana-versiya
    return typeof header === "string" ? header : "1";    // topilmasa — v1
  },
  defaultVersion: "1",
});
// → CUSTOM sana asosidagi versiyalash (Stripe uslubi) yoki subdomen uchun ham mos

// e2e — har versiya alohida sinaladi (v1 va v2 shartnomasi buzilmaganini tasdiqlash)
describe("Users API versioning", () => {
  let app: INestApplication;

  beforeAll(async () => {
    const moduleRef = await Test.createTestingModule({ imports: [AppModule] }).compile();
    app = moduleRef.createNestApplication();
    app.enableVersioning({ type: VersioningType.URI, defaultVersion: "1" });
    await app.init();
  });

  it("v1 eski formatni qaytaradi (name, phone)", () => {
    return request(app.getHttpServer())
      .get("/v1/users")
      .expect(200)
      .expect((res) => {
        expect(res.body[0]).toHaveProperty("name");      // v1 shartnomasi
        expect(res.body[0]).not.toHaveProperty("fullName");
      });
  });

  it("v2 yangi formatni qaytaradi (fullName, contact)", () => {
    return request(app.getHttpServer())
      .get("/v2/users")
      .expect(200)
      .expect((res) => {
        expect(res.body[0]).toHaveProperty("fullName");  // v2 shartnomasi
        expect(res.body[0].contact).toHaveProperty("phone");
      });
  });

  it("versiyasiz so'rov defaultVersion (v1) ni beradi", () => {
    return request(app.getHttpServer()).get("/users").expect(200)
      .expect((res) => expect(res.body[0]).toHaveProperty("name"));
  });

  afterAll(async () => await app.close());
});
// → har versiya shartnomasi test bilan qulflanadi (kelajakdagi o'zgarish v1'ni buzsa — test qizil)

❌ maydon o'zgartirish to'g'ridan (eski mijoz buziladi — 2.1)
✅ yangi versiya (v2)

❌ non-breaking ham versiya (versiya inflyatsiyasi — 2.2)
✅ faqat breaking; non-breaking — versiyasiz

❌ butun mantiq ikki marta 2.5-bob
✅ umumiy service + versiyalangan DTO

❌ ogohlantirishsiz o'chirish (mijoz sinadi — 2.6)
✅ deprecation (vaqt, ogohlantirish)

❌ boshqarib bo'lmaydigan yuk 2.7-bob
✅ 1-2 faol versiya