Управление доступом к маршрутам с помощью стражей

Стражи маршрутов — это функции, которые определяют, может ли пользователь перейти на определённый маршрут или покинуть его. Они похожи на контрольные пункты, которые управляют доступом пользователя к определённым маршрутам. Стражи маршрутов часто используют для аутентификации и контроля доступа.

Создание стража маршрута

Создать страж маршрута можно с помощью Angular CLI:

ng generate guard CUSTOM_NAME

Вам будет предложено выбрать, какой тип стража маршрута использовать, после чего будет создан соответствующий файл CUSTOM_NAME-guard.ts.

Типы возвращаемых значений стражей маршрутов

Все стражи маршрутов могут возвращать одни и те же значения. Это позволяет гибко управлять навигацией:

Типы стражей маршрутов

Angular предоставляет четыре типа стражей маршрутов, каждый из которых предназначен для своей задачи:

Все стражи имеют доступ к сервисам, предоставляемым на уровне маршрута, а также к сведениям о маршруте через аргумент route.

CanActivate

Страж CanActivate определяет, может ли пользователь получить доступ к маршруту. Чаще всего он используется для аутентификации и авторизации.

Ему доступны следующие аргументы по умолчанию:

• route: ActivatedRouteSnapshot — содержит сведения об активируемом маршруте
• state: RouterStateSnapshot — содержит текущее состояние маршрутизатора

Он может возвращать стандартные типы возвращаемых значений стражей.

export const authGuard: CanActivateFn = (
  route: ActivatedRouteSnapshot,
  state: RouterStateSnapshot,
) => {
  const authService = inject(AuthService);
  return authService.isAuthenticated();
};

Совет: чтобы перенаправить пользователя, верните URLTree или RedirectCommand. Не возвращайте false, а затем не выполняйте программный вызов navigate для перенаправления пользователя.

Дополнительные сведения см. в документации API для CanActivateFn.

CanActivateChild

Страж CanActivateChild определяет, может ли пользователь получить доступ к дочерним маршрутам определённого родительского маршрута. Он полезен, когда нужно защитить целый раздел вложенных маршрутов. Иными словами, canActivateChild выполняется для всех дочерних маршрутов. Если у дочернего компонента есть собственный дочерний компонент, canActivateChild выполнится один раз для обоих компонентов.

Ему доступны следующие аргументы по умолчанию:

• childRoute: ActivatedRouteSnapshot — содержит сведения о «будущем» снимке (то есть состоянии, к которому маршрутизатор пытается перейти) активируемого дочернего маршрута
• state: RouterStateSnapshot — содержит текущее состояние маршрутизатора

Он может возвращать стандартные типы возвращаемых значений стражей.

export const adminChildGuard: CanActivateChildFn = (
  childRoute: ActivatedRouteSnapshot,
  state: RouterStateSnapshot,
) => {
  const authService = inject(AuthService);
  return authService.hasRole('admin');
};

Дополнительные сведения см. в документации API для CanActivateChildFn.

CanDeactivate

Страж CanDeactivate определяет, может ли пользователь покинуть маршрут. Частый сценарий использования — предотвращение перехода с формы, содержащей несохранённые данные.

Ему доступны следующие аргументы по умолчанию:

• component: T — экземпляр деактивируемого компонента
• currentRoute: ActivatedRouteSnapshot — содержит сведения о текущем маршруте
• currentState: RouterStateSnapshot — содержит текущее состояние маршрутизатора
• nextState: RouterStateSnapshot — содержит состояние маршрутизатора, к которому выполняется переход

Он может возвращать стандартные типы возвращаемых значений стражей.

export const unsavedChangesGuard: CanDeactivateFn<Form> = (
  component: Form,
  currentRoute: ActivatedRouteSnapshot,
  currentState: RouterStateSnapshot,
  nextState: RouterStateSnapshot,
) => {
  return component.hasUnsavedChanges()
    ? confirm('You have unsaved changes. Are you sure you want to leave?')
    : true;
};

Дополнительные сведения см. в документации API для CanDeactivateFn.

CanMatch

Страж CanMatch определяет, может ли маршрут соответствовать шаблону при сопоставлении путей. В отличие от других стражей, отказ приводит к проверке других совпадающих маршрутов, а не к полной блокировке навигации. Это может быть полезно для флагов функций, A/B-тестирования или условной загрузки маршрутов.

Ему доступны следующие аргументы по умолчанию:

• route: Route — проверяемая конфигурация маршрута
• segments: UrlSegment[] — сегменты URL, не использованные при проверке предыдущих родительских маршрутов
• currentSnapshot: PartialMatchRouteSnapshot — текущий снимок маршрута на данном этапе сопоставления

Он может возвращать стандартные типы возвращаемых значений стражей, но если он возвращает false, Angular проверяет другие совпадающие маршруты, а не полностью блокирует навигацию.

export const featureToggleGuard: CanMatchFn = (
  route: Route,
  segments: UrlSegment[],
  currentSnapshot: PartialMatchRouteSnapshot,
) => {
  const featureService = inject(FeatureService);
  return featureService.isFeatureEnabled('newDashboard');
};

Он также позволяет использовать разные компоненты для одного и того же пути.

// 📄 routes.ts
const routes: Routes = [
  {
    path: 'dashboard',
    component: AdminDashboard,
    canMatch: [adminGuard],
  },
  {
    path: 'dashboard',
    component: UserDashboard,
    canMatch: [userGuard],
  },
];

В этом примере, когда пользователь переходит по адресу /dashboard, будет использован первый маршрут, для которого сработает соответствующий страж.

Дополнительные сведения см. в документации API для CanMatchFn.

Применение стражей к маршрутам

Создав стражи маршрутов, настройте их в определениях маршрутов.

В конфигурации маршрута стражи указываются в виде массивов, что позволяет применять к одному маршруту несколько стражей. Они выполняются в том порядке, в котором указаны в массиве.

import {Routes} from '@angular/router';
import {authGuard} from './guards/auth.guard';
import {adminGuard} from './guards/admin.guard';
import {canDeactivateGuard} from './guards/can-deactivate.guard';
import {featureToggleGuard} from './guards/feature-toggle.guard';

const routes: Routes = [
  // Basic CanActivate - requires authentication
  {
    path: 'dashboard',
    component: Dashboard,
    canActivate: [authGuard],
  },

  // Multiple CanActivate guards - requires authentication AND admin role
  {
    path: 'admin',
    component: Admin,
    canActivate: [authGuard, adminGuard],
  },

  // CanActivate + CanDeactivate - protected route with unsaved changes check
  {
    path: 'profile',
    component: Profile,
    canActivate: [authGuard],
    canDeactivate: [canDeactivateGuard],
  },

  // CanActivateChild - protects all child routes
  {
    path: 'users', // /user - NOT protected
    canActivateChild: [authGuard],
    children: [
      // /users/list - PROTECTED
      {path: 'list', component: UserList},
      // /users/detail/:id - PROTECTED
      {path: 'detail/:id', component: UserDetail},
    ],
  },

  // CanMatch - conditionally matches route based on feature flag
  {
    path: 'beta-feature',
    component: BetaFeature,
    canMatch: [featureToggleGuard],
  },

  // Fallback route if beta feature is disabled
  {
    path: 'beta-feature',
    component: ComingSoon,
  },
];