Как реализовать версионность в API NestJS?
Версионность API — это важный аспект разработки веб-приложений, позволяющий пользователям и разработчикам взаимодействовать с разными версиями вашего API без нарушения работы существующих функций и сервисов. В NestJS есть несколько способов реализации версионности. Рассмотрим основные подходы:
1. Версионность через URL
Один из самых простых способов реализации версионности — это добавление версии в URL. Например:
GET /api/v1/users
GET /api/v2/users
Для этого необходимо использовать декоратор @Controller с указанием версии:
import { Controller, Get } from '@nestjs/common';
@Controller('api/v1/users')
export class UsersV1Controller {
@Get()
getUsers() {
return [{ id: 1, name: 'User V1' }];
}
}
@Controller('api/v2/users')
export class UsersV2Controller {
@Get()
getUsers() {
return [{ id: 1, name: 'User V2' }, { id: 2, name: 'New User V2' }];
}
}
2. Версионность через заголовки
Еще один подход — использование HTTP заголовков для определения версии API. Например, вы можете использовать заголовок Accept:
Accept: application/vnd.myapp.v1+json
Для этого потребуется специальный миддлвер или фильтр, который будет определять, какую версию контроллера вызывают. Создадим фильтр:
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';
@Injectable()
export class VersionMiddleware implements NestMiddleware {
use(req: Request, res: Response, next: NextFunction) {
const acceptHeader = req.headers['accept'];
if (acceptHeader?.includes('vnd.myapp.v1')) {
req.version = 'v1';
} else if (acceptHeader?.includes('vnd.myapp.v2')) {
req.version = 'v2';
}
next();
}
}
Затем зарегистрируйте этот миддлвер в вашем модуле:
import { Module, MiddlewareConsumer } from '@nestjs/common';
import { UsersV1Controller } from './users-v1.controller';
import { UsersV2Controller } from './users-v2.controller';
import { VersionMiddleware } from './version.middleware';
@Module({
controllers: [UsersV1Controller, UsersV2Controller],
})
export class AppModule {
configure(consumer: MiddlewareConsumer) {
consumer.apply(VersionMiddleware).forRoutes('*');
}
}
3. Версионность через группировку
Если у вас много контроллеров, так же можно создавать группы для версий внутри одного контроллера:
import { Controller, Get, UseGuards } from '@nestjs/common';
@Controller('api/users')
export class UsersController {
@Get('v1')
getUsersV1() {
return [{ id: 1, name: 'User V1' }];
}
@Get('v2')
getUsersV2() {
return [{ id: 1, name: 'User V2' }, { id: 2, name: 'New User V2' }];
}
}
Заключение
Создание версионного API — это неотъемлемая часть планирования развития вашего приложения. Выберите подход, который лучше всего подходит для вашего проекта. Каждый метод имеет свои преимущества и недостатки, и его использование зависит от ваших конкретных требований и архитектуры приложения.
Не забывайте также проводить тестирование и документацию версий вашего API для разработчиков, которые будут его использовать.