NestJS Enterprise Backend APIs · Урок

Чтение контекста запроса с помощью декораторов параметров

Создавайте пользовательские декораторы параметров @CurrentUser и @ClientIp с помощью createParamDecorator и ExecutionContext

Урок 1 из 413 шагов

«Чтение контекста запроса с помощью декораторов параметров» — бесплатный урок NestJS Enterprise Backend APIs на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения NestJS Enterprise Backend APIs, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс NestJS Enterprise Backend APIs содержит 4 уроков всего.

Части этого урока еще не переведены и отображаются на английском.

Why Param Decorators?

In NestJS controllers, you often need to pull the same piece of data out of the request over and over: the authenticated user, the client IP, a tenant id from a header. Doing this with @Req() and digging into request.user in every handler is repetitive and leaks framework details into your business logic.

Custom param decorators let you encapsulate that extraction once and reuse it everywhere:

@CurrentUser() instead of req.user
@ClientIp() instead of parsing x-forwarded-for

The result is cleaner, more testable, and more declarative controller code.

The Repetitive Way

Here is what you usually start with: grabbing the whole request object and reaching into it manually. It works, but every handler repeats the same lines, and the controller now knows about request.user, which is an implementation detail of your auth guard.

Notice how the actual route logic is buried under plumbing. This is exactly what a param decorator removes.

import { Controller, Get, Req } from '@nestjs/common';
import { Request } from 'express';

@Controller('profile')
export class ProfileController {
  @Get()
  getProfile(@Req() request: Request) {
    const user = (request as any).user;
    return { id: user.id, email: user.email };
  }
}

createParamDecorator

NestJS exposes the factory createParamDecorator from @nestjs/common. You give it a function that receives two arguments and returns whatever value you want injected into the handler parameter.

data — the optional argument passed when the decorator is used, e.g. @CurrentUser('email').
ctx: ExecutionContext — a wrapper around the current request context, independent of the transport (HTTP, RPC, WebSocket).

The returned value becomes the parameter's value at call time.

import { createParamDecorator, ExecutionContext } from '@nestjs/common';

export const Example = createParamDecorator(
  (data: unknown, ctx: ExecutionContext) => {
    // return any value -> it gets injected into the param
    return 'hello';
  },
);

Getting the HTTP Request

For HTTP apps you convert the generic ExecutionContext into an HTTP-specific argument host and read the request from it:

ctx.switchToHttp() returns an HttpArgumentsHost.
.getRequest() gives you the underlying request (Express or Fastify).

Using switchToHttp() keeps the decorator explicit about which transport it targets. The same context could also be switched to RPC or WS for other protocols.

import { createParamDecorator, ExecutionContext } from '@nestjs/common';
import { Request } from 'express';

export const RawRequest = createParamDecorator(
  (data: unknown, ctx: ExecutionContext): Request => {
    return ctx.switchToHttp().getRequest<Request>();
  },
);

Building @CurrentUser

Assume an auth guard (e.g. a JWT strategy) has already attached the authenticated user to request.user. The @CurrentUser() decorator simply returns it.

This is the canonical pattern in enterprise NestJS apps: the guard does authentication, and the decorator gives ergonomic access to the result without exposing the request object.

import { createParamDecorator, ExecutionContext } from '@nestjs/common';

export interface AuthUser {
  id: string;
  email: string;
  roles: string[];
}

export const CurrentUser = createParamDecorator(
  (data: unknown, ctx: ExecutionContext): AuthUser => {
    const request = ctx.switchToHttp().getRequest();
    return request.user;
  },
);

Using the data Argument

The first parameter, data, is what the caller passes inside the decorator's parentheses. You can use it to return a single property instead of the whole object:

@CurrentUser() returns the full user.
@CurrentUser('email') returns just the email.

Type the data argument as keyof AuthUser so the caller gets autocomplete and compile-time safety on the property name.

import { createParamDecorator, ExecutionContext } from '@nestjs/common';
import { AuthUser } from './auth-user.interface';

export const CurrentUser = createParamDecorator(
  (data: keyof AuthUser | undefined, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    const user: AuthUser = request.user;
    return data ? user?.[data] : user;
  },
);

Consuming @CurrentUser in a Controller

Now the controller reads beautifully. The guard guarantees the user exists; the decorator injects exactly what each handler needs. No @Req(), no manual property digging.

This separation is what makes the handler easy to unit-test: you just call the method with a plain user object.

import { Controller, Get, UseGuards } from '@nestjs/common';
import { JwtAuthGuard } from './jwt-auth.guard';
import { CurrentUser } from './current-user.decorator';
import { AuthUser } from './auth-user.interface';

@UseGuards(JwtAuthGuard)
@Controller('me')
export class MeController {
  @Get()
  getMe(@CurrentUser() user: AuthUser) {
    return user;
  }

  @Get('email')
  getEmail(@CurrentUser('email') email: string) {
    return { email };
  }
}

Building @ClientIp

Behind a load balancer or reverse proxy, the real client IP is not request.ip but the first entry of the x-forwarded-for header. A @ClientIp() decorator centralizes this logic so every handler reads the correct address.

Important: only trust x-forwarded-for when you actually run behind a trusted proxy, and enable Express's trust proxy setting. Otherwise clients can spoof the header.

import { createParamDecorator, ExecutionContext } from '@nestjs/common';
import { Request } from 'express';

export const ClientIp = createParamDecorator(
  (data: unknown, ctx: ExecutionContext): string => {
    const request = ctx.switchToHttp().getRequest<Request>();
    const forwarded = request.headers['x-forwarded-for'];
    if (typeof forwarded === 'string' && forwarded.length > 0) {
      return forwarded.split(',')[0].trim();
    }
    return request.ip ?? '';
  },
);

Pure Extraction Logic Is Testable

The valuable part of a param decorator is its pure extraction logic. You can lift that into a plain function, unit-test it with a fake request, and call it from the decorator. Here is the IP-parsing logic as a standalone, runnable program.

This demonstrates the rule for choosing the first forwarded address and the fallback behavior — no NestJS or server required to verify it.

function extractClientIp(headers: Record<string, string>, fallbackIp: string): string {
  const forwarded = headers['x-forwarded-for'];
  if (typeof forwarded === 'string' && forwarded.length > 0) {
    return forwarded.split(',')[0].trim();
  }
  return fallbackIp;
}

console.log(extractClientIp({ 'x-forwarded-for': '203.0.113.7, 70.41.3.18' }, '10.0.0.1'));
console.log(extractClientIp({}, '10.0.0.1'));
console.log(extractClientIp({ 'x-forwarded-for': '198.51.100.5' }, '10.0.0.1'));

Combining Decorators in One Handler

Param decorators compose freely. A single handler can mix built-in decorators (@Body, @Param) with your custom ones. NestJS resolves each parameter independently by its decorator metadata.

Here an audit endpoint records who did what and from where, reading the user and IP declaratively.

import { Controller, Post, Body, UseGuards } from '@nestjs/common';
import { JwtAuthGuard } from './jwt-auth.guard';
import { CurrentUser } from './current-user.decorator';
import { ClientIp } from './client-ip.decorator';
import { AuthUser } from './auth-user.interface';

@UseGuards(JwtAuthGuard)
@Controller('audit')
export class AuditController {
  @Post('action')
  record(
    @CurrentUser('id') userId: string,
    @ClientIp() ip: string,
    @Body() body: { action: string },
  ) {
    return { userId, ip, action: body.action, at: new Date().toISOString() };
  }
}

Validation and Pipes Still Apply

A custom param decorator returns a raw value, so you can still attach pipes to it just like built-in decorators. Pass a pipe as an extra argument when using the decorator.

@CurrentUser('id', ParseUUIDPipe) validates that the extracted id is a UUID.
Pipes run after the decorator factory returns its value.

This lets you keep extraction and validation cleanly separated while still benefiting from NestJS's pipe pipeline.

import { Controller, Get, ParseUUIDPipe } from '@nestjs/common';
import { CurrentUser } from './current-user.decorator';

@Controller('orders')
export class OrdersController {
  @Get('mine')
  myOrders(@CurrentUser('id', ParseUUIDPipe) userId: string) {
    return { userId };
  }
}

Quick Check

Test your understanding of how a custom param decorator reads the request.

Ответь в интерактивном уроке

Recap

You learned to read request context declaratively with custom param decorators:

createParamDecorator((data, ctx) => ...) builds a reusable decorator; the returned value is injected into the handler parameter.
ctx.switchToHttp().getRequest() retrieves the HTTP request in a transport-explicit way.
@CurrentUser() wraps request.user (populated by your auth guard) and can return a single property via the data argument typed as keyof AuthUser.
@ClientIp() centralizes x-forwarded-for parsing, with a fallback to request.ip — trust the header only behind a real proxy.
Keep extraction logic pure so it is easy to unit-test, and remember you can still chain pipes like ParseUUIDPipe onto your custom decorators.

Можно начать бесплатно

Изучай TypeScript с ИИ-репетитором — бесплатно

Пиши и запускай код прямо в браузере, получай мгновенную помощь от ИИ-репетитора 24/7 и продолжи учиться на сайте или в приложении.

Курсы: 20
Уроки: 76

Начать учиться бесплатно Посмотреть полный курс

Часто задаваемые вопросы

Урок «Чтение контекста запроса с помощью декораторов параметров» бесплатный?

Да — полный текст урока «Чтение контекста запроса с помощью декораторов параметров» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс NestJS Enterprise Backend APIs, подпишись на CoddyKit PRO. Курс NestJS Enterprise Backend APIs содержит 4 уроков всего.

Чему я научусь в уроке «Чтение контекста запроса с помощью декораторов параметров»?

Создавайте пользовательские декораторы параметров @CurrentUser и @ClientIp с помощью createParamDecorator и ExecutionContext Ты практикуешь NestJS Enterprise Backend APIs с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать NestJS Enterprise Backend APIs?

Предыдущий опыт не требуется. NestJS Enterprise Backend APIs на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.

Сколько времени занимает урок «Чтение контекста запроса с помощью декораторов параметров»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке NestJS Enterprise Backend APIs?

Да. Каждый урок NestJS Enterprise Backend APIs включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

Чтение контекста запроса с помощью декораторов параметров
Добавление метаданных с помощью SetMetadata и Reflector
Композиция декораторов с помощью applyDecorators
Декораторы на уровне класса для сквозной конфигурации

← Назад к NestJS Enterprise Backend APIs