Пятая часть цикла, посвященного контейнеризации MEAN-stack приложений, в которой мы развернем MongoDB Replica Set из трех узлов в Docker Swarm.

Содержание цикла

• Часть 1 - Dockerfile, образы, контейнеры
• Часть 2 - Docker Compose
• Часть 3 - Traefik reverse proxy
• Часть 4 - Docker Swarm
• Часть 5 - Mongo Replica Set в Docker Swarm

Введение

В предыдущей части мы задеплоили приложение в Docker Swarm. Однако сервис базы данных у нас не был реплицирован. В данной статье исправим это досадное недоразумение и развернем 3 реплики базы данных на нодах нашего Docker-роя. Но с репликацией mongo есть небольшая сложность - нельзя просто указать в compose-файле replicas: 3. В случае падения одной из рабочих нод докер перенесет сервис mongo на ноду, где такой сервис уже есть. И эти сервисы начнут работать с общей data/db. Но это недопустимо. Поэтому предстоит провести небольшую настройку.

Маркируем ноды

Каждой ноде укажем label с требуемым id реплики mongo. Для этого на менеджере выполним следующие команды:

docker node update --label-add mongo.replica=0 vm0
docker node update --label-add mongo.replica=1 vm1
docker node update --label-add mongo.replica=2 vm2

Настроим сервисы

В compose-файле вместо сервиса db создадим 3 других:

services:

  # ...

  mongo0:
    image: mongo
    command:
      - "--smallfiles"
      - "--replSet"
      - "rs0"
    deploy:
      mode: global
      restart_policy:
        condition: on-failure
      placement:
        constraints:
          - node.labels.mongo.replica == 0
      labels:
        - traefik.enable=false
    volumes:
      - mongodata0:/data/db
    networks:
      - db-net


  mongo1:
    image: mongo
    command:
      - "--smallfiles"
      - "--replSet"
      - "rs0"
    deploy:
      mode: global
      restart_policy:
        condition: on-failure
      placement:
        constraints:
          - node.labels.mongo.replica == 1
      labels:
        - traefik.enable=false
    volumes:
      - mongodata1:/data/db
    networks:
      - db-net


  mongo2:
    image: mongo
    command:
      - "--smallfiles"
      - "--replSet"
      - "rs0"
    deploy:
      mode: global
      restart_policy:
        condition: on-failure
      placement:
        constraints:
          - node.labels.mongo.replica == 2
      labels:
        - traefik.enable=false
    volumes:
      - mongodata2:/data/db
    networks:
      - db-net

В командах указываем запускать mongo как replica set с именем rs0. В deploy указываем глобальный режим mode: global и задаем constraints-правило node.labels.mongo.replica == 0, т.е. запускать mongo0 только на ноде с меткой mongo.replica=0.

У сервера изменим путь для подключения mongoose к базе данных:

  server:
    ...
    environment:
      - "db:uri=mongodb://mongo0,mongo1,mongo2/docker?replicaSet=rs0"

В конфиге других сервисов ничего не меняется (см. предыдущую часть цикла).

Volumes

Для хранения баз данных создадим следующие volumes:

volumes:
  mongodata0:
  mongodata1:
  mongodata2:

и используем их в сервисах mongo:

  mongo0:
    ...
    volumes:
      - mongodata0:/data/db

Deploy

docker stack deploy -c docker-stack.mongo-rs.yml meanstack

Инициируем Replica Set в самой mongo

docker exec -it <mongo_container_id> sh

> mongo

> rs.initiate( {
   _id : "rs0",
   members: [
      { _id: 0, host: "mongo0:27017" },
      { _id: 1, host: "mongo1:27017" },
      { _id: 2, host: "mongo2:27017" }
   ]
})

Результат

В браузере по адресу http://visualizer.docker-example.local/ мы должны увидеть что-то похожее:

Код проекта на GitHub >>

Четвертая часть цикла, посвященного контейнеризации MEAN-stack приложений, в которой приложение мы разворачиваем в кластере Docker Swarm.

Содержание цикла

• Часть 1 - Dockerfile, образы, контейнеры
• Часть 2 - Docker Compose
• Часть 3 - Traefik reverse proxy
• Часть 4 - Docker Swarm
• Часть 5 - Mongo Replica Set в Docker Swarm

Введение

Docker позволяет объединить в кластер группу машин, на которых он установлен. Этот кластер называется Swarm (рой). После этого можно выполнять все те же команды Docker, но теперь они будут выполняться в кластере swarm-менеджером. Помимо менеджеров в swarm могут быть и воркеры (workers). Все машины, подключенные к swarm, называются нодами (nodes). Менеджеры также отвечают и за распределение сервисов между всеми нодами. Правила распределения и взаимодействия сервисов описываются в уже известном нам docker-compose YAML-файле. Совокупность всех сервисов в swarm носит название stack.

Создаем машины

Для начала нужно заиметь группу машин.

Под виндой 3 виртуальные машины можно создать следующим образом:

docker-machine create -d hyperv --hyperv-virtual-switch "myswitch" vm0
docker-machine create -d hyperv --hyperv-virtual-switch "myswitch" vm1
docker-machine create -d hyperv --hyperv-virtual-switch "myswitch" vm2

Как настроить Hyper-V >>

Под Mac/Linux:

docker-machine create --driver virtualbox vm0

Если хочется поиграться в условиях, приближенных к боевым, то можно поднять машины на дроплетах Digital Ocean:

docker-machine create --driver digitalocean --digitalocean-access-token xxxxx vm0
...

Пример c Digital Ocean Docker Machine >>

Посмотреть список доступных машин:

docker-machine ls

Инициируем Swarm-режим

Получим команды, которые настроят текущий shell для работы с демоном Docker на виртуальной машине:

docker-machine env vm0

Будет выведен список команд для текущей оболочки, которые нужно выполнить. В списке машин (docker-machine ls) в колонке ACTIVE символом * будет отмечена активная машина. Теперь все команды docker ... будут выполняться на ней.

Для инициации swarm-режима выполняем:

docker swarm init

В ответе будет указано, что текущая машина теперь менеджер. Также будет выведена команда для подключения к swarm рабочих нод.

Подключаем рабочие (worker) ноды

Переключаемся на другую машину и выполняем на ней предоставленную ранее команду:

docker-machine env vm1
...
docker swarm join --token SWMTKN-1-52qk72ooyql1zfxb0lezwmj52oipimmgln6zh3skbdokl6pp3c-179u2zzjdffcaqjni4zjst188 192.168.2.36:2377

Эту же процедуру проведем и с vm2.

Подключение менеджеров

Для подключения к swarm других менеджеров нужно запросить соответствующий токен:

docker swarm join-token manager

Docker Stack

Теперь у нас есть кластер на Docker Swarm, готовый к деплою нашего приложения. Однако приложение осталось чутка подготовить к запуску.

Stack - это, по сути, тот же docker-compose файл, но есть небольшие отличия. Так убираем из файла все depends_on - в swarm они не работают. Все сервисы запускаются параллельно и независимо. Поэтому на сервере пришлось настроить reconnect к базе данных в случае неудачи. Сервис может быть запущен до запуска базы данных, и тогда он уходит в цикл "падение-запуск" и, тем самым, солидно так грузит весь стек.

У сервисов добавляется раздел deploy, в котором настраиваются:

• restart_policy (condition: on-failure);
• update_config (parallelism: 2);
• число экземпляров сервиса (replicas: 3);
• правила размещения сервиса (placement constraints, preferences)
• и ряд других параметров

Также в секцию deploy необходимо перенести все lebels.

Для стека создадим новый файл:

docker-stack.yml

version: "3.5"

services:

  server:
    image: myusername/public:mean-docker-server
    deploy:
      replicas: 2
      restart_policy:
        condition: on-failure
      placement:
        constraints:
          - node.role == worker
      labels:
        - traefik.docker.network=traefik-net
        - traefik.frontend.rule=Host:api.docker-example.local
        - traefik.port=3000
    environment:
      - "db:uri=mongodb://db/docker"
    networks:
      - traefik-net
      - db-net


  client:
    image: myusername/public:mean-docker-client
    deploy:
      replicas: 2
      restart_policy:
        condition: on-failure
      placement:
        constraints:
          - node.role == worker
      labels:
        - traefik.frontend.rule=Host:docker-example.local
        - traefik.port=4000
    networks:
      - traefik-net

  db:
    image: mongo
    command:
      - "--smallfiles"
    deploy:
      mode: global
      restart_policy:
        condition: on-failure
      placement:
        constraints:
          - node.role == manager
      labels:
        - traefik.enable=false
    networks:
      - db-net


  reverse-proxy:
    image: traefik
    command:
      - "--api"
      - "--entrypoints=Name:http Address::80"
      - "--defaultentrypoints=http"
      - "--docker"
      # Включаем режим Swarm
      - "--docker.swarmMode"
      - "--docker.domain=docker-example.local"
      - "--docker.watch"
    deploy:
      mode: global
      placement:
        constraints:
          - node.role == manager
      update_config:
        parallelism: 1
        delay: 10s
      restart_policy:
        condition: on-failure
      labels:
        - traefik.frontend.rule=Host:traefik.docker-example.local
        - traefik.port=8080
    ports:
      - 80:80
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      traefik-net:
        aliases:
          - api.docker-example.local

Запустим по 2 реплики "server" и "client". В placement:constraints указываем, что запускать их требуется только на воркерах (node.role == worker).

Для сервисов "db" и "reverse-proxy" укажем mode: global (запускать по 1 сервису на каждую ноду) и node.role == manager в constraints (только на менеджерах).

Docker Swarm Visualizer

Также в сервисы добавим визуализатор работы Swarm.

services:

  ...

  visualizer:
    image: dockersamples/visualizer:stable
    deploy:
      placement:
        constraints:
          - node.role == manager
      labels:
        - traefik.frontend.rule=Host:visualizer.docker-example.local
        - traefik.port=8080
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - traefik-net

Hosts

Заменим/добавим наши фейковые домены:

# windows:    c:/windows/system32/drivers/etc/hosts
# ubuntu/mac: /etc/hosts

192.168.2.40       docker-example.local
192.168.2.40       api.docker-example.local 
192.168.2.40       traefik.docker-example.local
192.168.2.40       visualizer.docker-example.local

Здесь 192.168.2.40 - IP-адрес менеджера (vm0). Узнать его можно с помощью docker-machine ls.

Deploy

Для развертывания приложения переключаемся на ноду-менеджер:

docker-machine env vm0
...

Создаем сеть:

docker network create -d overlay traefik-net

и выполняем деплой:

docker stack deploy -c docker-stack.yml meanstack

В браузере по адресу http://visualizer.docker-example.local/ мы должны увидеть какую-то такую картину:

В следующей части попробуем зареплицировать нашу базу данных.

Код проекта на GitHub >>

Часть 5 - Mongo Replica Set в Docker Swarm >>

Третья часть цикла, посвященного контейнеризации MEAN-stack приложений, в которой мы настроим обратный прокси-сервер (reverse proxy) и балансировщик нагрузки (load balancer) Traefik.

Содержание цикла

• Часть 1 - Dockerfile, образы, контейнеры
• Часть 2 - Docker Compose
• Часть 3 - Traefik reverse proxy
• Часть 4 - Docker Swarm
• Часть 5 - Mongo Replica Set в Docker Swarm

Введение

В предыдущей части мы написали docker-compose файл, в котором настроили запуск сервисов с серверной частью приложения, клиентской частью и базой данных. Теперь же нам необходимо настроить приложение следующим образом:

• Angular приложение должно быть доступно только по адресу docker-example.local;
• серверное api должно принимать запросы по адресу api.docker-example.local;
• должен быть открыт только порт 80.

Для этого нужно поднять прокси-сервер, который будет принимать все запросы на порту 80 и по хосту ретранслировать запросы на сервис client для docker-example.local и на server для api.docker-example.local.

Самое популярное решение для этих целей - использовать прокси-сервер nginx. Однако в этом проекте я попробую использовать Traefik - молодой реверс-прокси сервер и балансировщик нагрузки, который подает большие надежды.

Такой выбор был сделан по следующим причинам:

• хорошая интеграция с Docker, Docker Swarm, Kubernetes
• более интуитивная конфигурация и настройка
• HTTPS от Let's Encrypt из коробки
• еще ряд некоторых плюшек из разряда Websocket, HTTP/2, метрики Prometheus
• интересно попробовать

Hosts

Сперва добавим наши фейковые домены в hosts:

# windows:      c:/windows/system32/drivers/etc/hosts
# ubuntu/mac:   /etc/hosts

127.0.0.1       docker-example.local
127.0.0.1       api.docker-example.local 

# Traefik Dashboard
127.0.0.1       traefik.docker-example.local

Конфигурация Traefik

Вся настройка Traefik производится в том же docker-compose файле.

docker-compose.yml

services:

  # ...

  # Добавляем сервис реверс-прокси Traefik
  reverse-proxy:
    image: traefik

    # В командах производим основную настройку
    command:

      # Включаем Traefik Dashboard (порт 8080)
      - "--api"

      # Точка входа http на порту 80 используется по умолчанию
      - "--entrypoints=Name:http Address::80"
      - "--defaultentrypoints=http"

      # Включаем режим совместимости с Docker
      - "--docker"

      # Домен по умолчанию
      - "--docker.domain=docker-example.local"

      # Следить за изменениями докера
      - "--docker.watch"

    restart: always

    # Открываем только 80 порт
    ports:
      - 80:80
    
    # Даем Traefik доступ к docker.sock 
    # для отслеживания событий Docker
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

    # Подключаемся к сети для прокси
    networks:
      traefik-net:
        
        # Альтернативное имя хотса для доступа по сети traefik-net
        aliases:
          - api.docker-example.local

    # В метках сервисов прописываем правила для Traefik
    labels:

      # Запросы на хост `traefik.docker-example.local`
      - traefik.frontend.rule=Host:traefik.docker-example.local

      # перенаправлять на порт 8080 (Traefik Dashboard) этого сервиса
      - traefik.port=8080

Настройка сервисов

Сами сервисы подключим к сети traefik-net, избавляемся от проброшенных портов. В labels зададим правила проксирования.

server service:

  server:
    image: myusername/public:mean-docker-server
    restart: on-failure
    depends_on:
      - db
    environment:
      - "db:uri=mongodb://db/docker"
    networks:

      # Подключаемся к сети 
      - traefik-net
      - db-net

    # В метках прописываем правила для Traefik
    labels:

      # Для реверс-прокси использовать сеть traefik-net
      - traefik.docker.network=traefik-net

      # Запросы на хост `api.docker-example.local`
      - traefik.frontend.rule=Host:api.docker-example.local

      # перенаправлять на порт 3000 этого сервиса
      - traefik.port=3000

client service:

  client:
    image: myusername/public:mean-docker-client
    restart: on-failure
    depends_on:
      - server
    networks:

      # Подключаемся к сети 
      - traefik-net

    labels:

      # Запросы на хост `docker-example.local`
      - traefik.frontend.rule=Host:docker-example.local

      # перенаправлять на порт 4000 этого сервиса
      - traefik.port=4000

db service:

  db:
    image: mongo
    restart: on-failure

    # К сети proxy-net не подключаемся
    # с сервером общаемся по db-net
    networks:
      - db-net

    labels:
      # В проксировании не нуждаемся
      - traefik.enable=false

Сети:

networks:
  traefik-net:
    external: true
  db-net:

В работе с сетями у траефика есть небольшая проблема. Дело в том, что docker compose при старте создает сети и к их именам добавляет префикс с названием проекта. Т.е. в compose файле мы указываем, что необходимо создать сеть traefik-net. В метке сервиса server мы указываем traefik, что для прокси из двух сетей необходимо использовать traefik.docker.network=traefik-net. Но после старта эта сеть не будет найдена, ибо докер назвал ее mean-docker-stack_traefik-net.

Есть два выхода:

1. Предугадывать переименование сети и указывать traefik.docker.network=mean-docker-stack_traefik-net;
2. Предварительно перед запуском создать external сеть traefik-net и использовать ее, указав, что она является external в docker-compose файле.

В данном случае я воспользовался вариантом №2.

Настройка HTTPS от Let's Encrypt в Traefik

Для настройки https в командах сервиса reverse-proxy добавим/заменим следующие строки:

  reverse-proxy:
    
    # ...

    command:
      - "--api"
      - "--entrypoints=Name:http Address::80 Redirect.EntryPoint:https"
      - "--entrypoints=Name:https Address::443 TLS"
      - "--defaultentrypoints=http,https"
      - "--acme"
      - "--acme.storage=/etc/traefik/acme/acme.json"
      - "--acme.entryPoint=https"
      - "--acme.httpChallenge.entryPoint=http"
      - "--acme.onHostRule=true"
      - "--acme.onDemand=false"
      - "--acme.email=contact@mydomain.com"

Во время тестирования рекомендую использовать Let's Encrypt's staging server:

      - "--acme.caServer=https://acme-staging.api.letsencrypt.org/directory"

Подробнее читать в официальной документации Traefik.

Запуск

Предварительно создадим сеть traefik-net:

docker network create traefik-net

Запускаем уже известной нам командой:

docker-compose up

Рабочее приложение наблюдаем в браузере по адресу http://docker-example.local/

В следующей части попробуем развернуть наше приложение в кластере Docker Swarm.

Код проекта на GitHub >>

Часть 4 - Docker Swarm >>

Вторая часть цикла, посвященного контейнеризации MEAN-stack приложений, в которой мы познакомимся с Docker Compose - инструментом для конфигурирования и запуска мультиконтейнерных приложений Docker.

Содержание цикла

• Часть 1 - Dockerfile, образы, контейнеры
• Часть 2 - Docker Compose
• Часть 3 - Traefik reverse proxy
• Часть 4 - Docker Swarm
• Часть 5 - Mongo Replica Set в Docker Swarm

В предыдущей части мы создали Docker-образы сервера и клиента приложения. Теперь нам нужно поднять базу данных. Можно воспользоваться все той же командой docker run. Но каждый раз запускать по отдельности все сервисы одного мультиконтейнерного приложения как-то утомительно. Хочется написать один файл конфига и запускать его одной командой. Как раз для этих целей и необходим инструмент Docker Compose. Он позволяет сконфигурировать работу сервисов (читай контейнеров) приложения в YAML-файле. Создадим этот файл.

docker-compose.yml

# Версия формата compose файла
version: "3"

services:

  # Серверное приложение
  server:

    # Можно собрать образ из Docerfile
    # build: ./server

    # Но у нас есть репозиторий. Берем образ из него
    image: myusername/public:mean-docker-server

    # Дать доступ на порту 3000
    ports:
      - "3000:3000"

    # Перезапускать сервис после падения
    restart: on-failure

    # Запускать сервис только после запуска сервиса db
    depends_on:
      - db

    # Путь к mongoDB по имени сервиса (db). docker - имя базы
    environment:
      - "db:uri=mongodb://db/docker"

    # Подключиться к сети db-net
    networks:
      - db-net


  # Клиентское приложение
  client:
    image: myusername/public:mean-docker-client
    ports:
      - "4000:4000"
    restart: on-failure
    depends_on:
      - server


  # База данных
  db:
    image: mongo
    restart: on-failure
    networks:
      - db-net


# Создаем сеть
networks:
  db-net:

Основные команды

Запуск сервисов

docker-compose up -d

Параметр -d указывает запустить в фоновом режиме.

Масштабирование сервисов

docker-compose up --scale server=2 --scale client=3

Логи

docker-compose logs

Запущенные процессы

docker-compose top

Остановка и удаление контейнеров

docker-compose down

Другие команды

docker-compose help

После запуска серверное приложение доступно на порту 3000. По сети докера оно подключается к базе данных. Однако клиентское приложение, хоть и открывается в браузере на localhost:4000, но не имеет доступа к серверному api. Для этого требуется настроить реверс прокси сервер, чем мы и займемся в следующей части.

Код проекта на GitHub >>

Часть 3 - Traefik reverse proxy >>

Ну вот и я добрался до Docker. До этого пытался, но все урывками, и цельная картина не складывалась. Но было принято решение, что свое приложение буду разворачивать в контейнерах. Поэтому сел раскуривать Docker основательно, параллельно конспектируя с целью написать статью. И вот, когда все детали сложились в общую картину, обнаружил, что наконспектировал 30+ страниц. Боюсь, что статья с таким объемом будет тяжела для восприятия, поэтому встречайте небольшой цикл, посвященный контейнеризации MEAN-stack приложений.

Для начала рекомендую пройти этот короткий официальный туториал Docker.

Содержание цикла

• Часть 1 - Dockerfile, образы, контейнеры
• Часть 2 - Docker Compose
• Часть 3 - Traefik reverse proxy
• Часть 4 - Docker Swarm
• Часть 5 - Mongo Replica Set в Docker Swarm

Описание демо-проекта

Демо-приложение не имеет особой ценности и предназначено только для того, чтобы показать работоспособность в целом. Оно должно принимать запросы, сохранять в базу данных своеобразный лог (имя хоста, req.hostname и x-real-ip заголовок запроса) и в ответе возвращать 10 последних сохраненных записей.

Структурно демо-приложение будет состоять из следующих основных частей:

• серверная часть
• клиентская часть
• база данных

В дальнейшем, по мере углубления, будут добавлены сервисы reverse proxy и мониторинга.

Код проекта на GitHub >>

Сервер

• Express.js 4.x
• Mongoose 5.x

Сгенерирован с помощью express-generator:

npm install express-generator -g
express --no-view server

Основная логика содержится в этих строках:

router.post('/', function (req, res, next) {

    let newData = Data({
        host: os.hostname(),
        req_host: req.hostname,
        req_ip: req.header('x-real-ip')
    });

    newData.save()
        .then((data) => {
            return Data.find().sort('-date').limit(10).exec();
        })
        .then((list) => {
            res.json(list)
        })
        .catch(err => {
            return next(err);
        });
});

Клиент

• Angular 6.x
• Angular Universal 6.x (SSR)

Сгенерирован с помощью Angular CLI:

npm install -g @angular/cli
ng new client

Настройка серверного рендеринга Angular >>

Кнопка, по нажатию на которую отправляется запрос на сервер, таблица со списком последних сохраненных в БД запросов:

База данных

• MongoDB 3.6

Dockerfile

Это файл, описывающий, как должна производиться сборка Docker-образа с нашим приложением. Для серверного и клиентского приложений потребуется создать два файла с названием Dockerfile.

/server/Dockerfile

# В качестве исходного используем официальный образ  
# диспетчера процессов PM2 на базе ОС Alpine
FROM keymetrics/pm2:latest-alpine

# Создаем рабочую директорию
WORKDIR /app

# Копируем в неё файлы package.json и package-lock.json
COPY package*.json ./

# Выполняем установку пакетов npm
RUN npm install

# Копируем остальные файлы приложения
COPY . ./

# Открываем наружу порт 3000
EXPOSE 3000

# Указываем команду, выполняемую при запуске контейнера
CMD [ "pm2-runtime", "start", "ecosystem.config.js" ]

/client/Dockerfile

Здесь воспользуемся возможностью многостадийной сборки образа Docker:

# Первая стадия сборки (назовем build)

# В качестве исходного используем образ NodeJS на базе ОС Alpine
FROM node:alpine AS build

# Создаем рабочую директорию
WORKDIR /app

# Копируем в неё файлы package.json и package-lock.json
COPY package*.json ./

# Устанавливаем переменную среды для loglevel
# и выполняем установку пакетов npm
ENV NPM_CONFIG_LOGLEVEL warn
RUN npm install

# Копируем остальные файлы приложения
COPY . ./

# Определяем переменную стадии со значением по умолчанию
# Для изменения в build указать --build-arg STAGE=development
ARG STAGE=production

# Выполняем сборку приложения
RUN $(npm bin)/ng build --configuration=$STAGE && \
    $(npm bin)/ng run client:ssr:$STAGE && \
    npm run webpack:server


# Вторая стадия

# Используем образ PM2
FROM keymetrics/pm2:latest-alpine AS release

# Создаем рабочую директорию
WORKDIR /app

# Копируем из build скомпилированное Angular приложение
# и файл ecosystem
COPY --from=build /app/dist ./dist
COPY --from=build /app/ecosystem.config.js ./

# Шарим порт
EXPOSE 4000

# Команда для запуска
CMD [ "pm2-runtime", "start", "ecosystem.config.js" ]

Многостадийная сборка позволяет значительно уменьшить размер финального образа, так как в него не переносятся установленные пакеты npm.

PM2

Для запуска и управления процессами Node.js приложения используем диспетчер PM2. Создадим его конфигурационный файл:

/server/ecosystem.config.js

module.exports = {
    apps: [{
        name: "server",
        script: "bin/www",
        exec_mode: "cluster",
        instances: "max",
        instance_var: 'INSTANCE_ID',
        env: {
            NODE_ENV: "development",
        },
        env_production: {
            NODE_ENV: "production",
        }
    }]
};

Приложение запускаем в режиме кластера, а instances: "max" указываем, что необходимо запускать по ноде на каждое ядро процессора.

Аналогичный файл создается и для клиента, приводить его не буду.

Образы

Сборка образов:

docker build -t server ./server
docker build -t client ./client

Параметр -t server задает имя и тег образа в формате name:tag.

Просмотр списка образов:

docker image ls

Удаление образов:

docker image rm <image_id>

При этом вводить полный id не обязательно, достаточно первых символов.

Отправка в репозиторий

Регистрируемся на Docker Hub и создаем репозиторий.

Предположим, я зарегистрировался там как myusername и создал репозиторй public. Пересоберем наши образы следующим образом:

docker build -t myusername/public:mean-docker-server ./server
docker build -t myusername/public:mean-docker-client ./client

Теперь можно отправить их:

docker push myusername/public:mean-docker-server
docker push myusername/public:mean-docker-client

Вытягивание образов

docker pull myusername/public:mean-docker-server

Остальные команды по работе с образами

docker image help

Контейнеры

Контейнер включает в себя:

• Docker-образ;
• среду исполнения;
• стандартный набор исполняемых команд.

Запуск приложения в контейнере

Для запуска приложений используем команды:

docker run -d -p 3000:3000 myusername/public:mean-docker-server
docker run -d -p 80:4000 myusername/public:mean-docker-client

Если образы локально не найдены, то они будут вытянуты из репозитория.

Образы наших приложений будут упакованы в контейнеры и запущены той командой, что мы указали в инструкции CMD Dockerfile.

Параметром -d мы указываем запустить контейнер в фоновом режиме.

Параметр -p осуществляет проброс портов. Так наше клиентское приложение в контейнере доступно на порту 4000, а инструкцией -p мы указываем привязать его на 80 порт хоста. Таким образом наше клиентское приложение будет доступно по адресу localhost:80.

Просмотр списка контейнеров

Запущенные контейнеры:

docker container ls
docker ps

Все, в том числе остановленные:

docker container ls -a
docker ps -a

Остановка/запуск контейнеров

docker container pause <container_id>
docker container unpause <container_id>

docker container stop <container_id>
docker container start <container_id>

Выполнение команд в контейнере

docker exec <options> <container_id> <command>

Например, часто используется команда, которая позволяет подключиться к командной оболочке контейнера:

docker exec -it <container_id> sh

Логи

docker container logs <container_id> 

Удаление контейнера

docker container rm <container_id>

Работающие контейнеры нужно либо сперва остановить, либо воспользоваться --force:

docker container rm <container_id> -f

Другие команды для работы с контейнерами

docker container help

Очистка

Команда:

docker system prune

удалит:

• все остановленные контейнеры
• все неиспользуемые сети
• все промежуточные (dangling) образы
• весь кэш сборки

Для удаления всех неиспользуемых образов добавить параметр -a.

В следующей статье читайте про работу с Docker Compose - инструментом для конфигурирования и запуска мультиконтейнерных приложений Docker.

Часть 2 - Docker Compose >>

Сегодня попробую запустить Angular приложение на сервере. Не буду расписывать, что такое Server side rendering (далее SSR) и для чего это нужно, а кратко опишу основные настройки и, более подробно, те проблемы, с которыми мне пришлось столкнуться. А также проведу небольшое тестирование производительности.

Базовая настройка SSR

Настройку производил по официальному мануалу, поэтому кратко и без особых комментариев. Все самое интересное начинается после первого запуска.

Устанавливаем нужные инструменты:

npm install --save @angular/platform-server @nguniversal/module-map-ngfactory-loader ts-loader @nguniversal/express-engine

Client

src/app/app.module.ts:

  imports: [
    BrowserModule.withServerTransition({appId: 'yuor-app-id'}),
    ...

Angular добавляет appId к стилям, собранным сервером, чтобы их можно было удалить при запуске клиентского приложения.

angular.json:

...
"build": {
  "builder": "@angular-devkit/build-angular:browser",
  "options": {
    "outputPath": "dist/browser",
    ...
  } 
}
...

Указываем собирать клиент в директории "dist/browser"

Server

src/app/app.server.module.ts:

import {NgModule} from '@angular/core';
import {ServerModule} from '@angular/platform-server';
import {ModuleMapLoaderModule} from '@nguniversal/module-map-ngfactory-loader';
import {FlexLayoutServerModule} from '@angular/flex-layout/server';

import {AppModule} from './app.module';
import {AppComponent} from './app.component';

@NgModule({
  imports: [
    AppModule,
    ServerModule,
    ModuleMapLoaderModule,
    FlexLayoutServerModule, // Если юзаете angular/flex-layout
  ],
  providers: [
    // Add universal-only providers here
  ],
  bootstrap: [AppComponent],
})
export class AppServerModule {
}

src/main.server.ts:

export {AppServerModule} from './app/app.server.module';

server.ts:

import 'zone.js/dist/zone-node';
import 'reflect-metadata';

import {enableProdMode} from '@angular/core';

import * as express from 'express';
import {join} from 'path';
import {ngExpressEngine} from '@nguniversal/express-engine';
import {provideModuleMap} from '@nguniversal/module-map-ngfactory-loader';

enableProdMode();

// Express server
const app = express();

const PORT = process.env.PORT || 4000;
const DIST_FOLDER = join(process.cwd(), 'dist');

// * NOTE :: leave this as require() since this file is built Dynamically from webpack
const {AppServerModuleNgFactory, LAZY_MODULE_MAP} = require('./dist/server/main');


app.engine('html', ngExpressEngine({
  bootstrap: AppServerModuleNgFactory,
  providers: [
    provideModuleMap(LAZY_MODULE_MAP)
  ]
}));

app.set('view engine', 'html');
app.set('views', join(DIST_FOLDER, 'browser'));

// Server static files from /browser
app.get('*.*', express.static(join(DIST_FOLDER, 'browser')));

// All regular routes use the Universal engine
app.get('*', (req, res) => {
  res.render('index', {req});
});

// Start up the Node server
app.listen(PORT, () => {
  console.log(`Node server listening on http://localhost:${PORT}`);
});

src/tsconfig.server.json:

{
  "extends": "../tsconfig.json",
  "compilerOptions": {
    "outDir": "../out-tsc/app",
    "baseUrl": "./",
    "module": "commonjs",
    "types": []
  },
  "exclude": [
    "test.ts",
    "**/*.spec.ts"
  ],
  "angularCompilerOptions": {
    "entryModule": "app/app.server.module#AppServerModule"
  }
}

webpack.server.config.js:

const path = require('path');
const webpack = require('webpack');

module.exports = {
  entry: {server: './server.ts'},
  resolve: {extensions: ['.js', '.ts']},
  target: 'node',
  mode: 'none',
  // this makes sure we include node_modules and other 3rd party libraries
  externals: [/node_modules/],
  output: {
    path: path.join(__dirname, 'dist'),
    filename: '[name].js'
  },
  module: {
    rules: [{test: /\.ts$/, loader: 'ts-loader'}]
  },
  plugins: [
    // Temporary Fix for issue: https://github.com/angular/angular/issues/11580
    // for 'WARNING Critical dependency: the request of a dependency is an expression'
    new webpack.ContextReplacementPlugin(
      /(.+)?angular(\\|\/)core(.+)?/,
      path.join(__dirname, 'src'), // location of your src
      {} // a map of your routes
    ),
    new webpack.ContextReplacementPlugin(
      /(.+)?express(\\|\/)(.+)?/,
      path.join(__dirname, 'src'),
      {}
    )
  ]
};

angular.json:

"architect": {
  ...
  "server": {
    "builder": "@angular-devkit/build-angular:server",
    "options": {
      "outputPath": "dist/server",
      "main": "src/main.server.ts",
      "tsConfig": "src/tsconfig.server.json"
    }
  }
  ...
}

package.json:

"scripts": {
    ...
    "build:ssr": "npm run build:client-and-server-bundles && npm run webpack:server",
    "serve:ssr": "node dist/server",
    "build:client-and-server-bundles": "ng build --prod && ng run client:server",
    "webpack:server": "webpack --config webpack.server.config.js --progress --colors",
    ...
}

Билд

npm run build:ssr

Здесь пришлось доустановить webpack-cli:

npm i -D webpack-cli

Перезапускаем билд.

Сервим

npm run serve:ssr

В консоли должно появиться:

Node server listening on http://localhost:4000

Открываем и преодолеваем

ɵHttpInterceptingHandler is not a constructor

При первом открытии страницы в браузере я получил ошибку (Github issue):

TypeError: _angular_common_http__WEBPACK_IMPORTED_MODULE_5__.ɵHttpInterceptingHandler is not a constructor at zoneWrappedInterceptingHandler

Решается обновлением зависимостей Angular:

ng update @angular/core

localStorage is not defined

У меня в приложении есть сервис TokenService, который отвечает за сохранение и извлечение аутентификационного токена в/из localStorage браузера. Но на сервере нету localStorage. Для решения этой проблемы я создал TokenServerService implements TokenService, в котором исключил все взаимодействие с localStorage. И запровайдил его в app.server.module.ts:

  providers: [
    {provide: TokenService, useClass: TokenServerService}
  ]

window

Та же беда - на сервере отсутствует.

this.onScrollSubscription = window && observableFromEvent(window, 'scroll')
      .subscribe(() => {
...

  ngOnDestroy() {
    this.onScrollSubscription && this.onScrollSubscription.unsubscribe();
  }

document

Можно поступить как и с window, но я обернул блок кода в проверку платформы:

  constructor(@Inject(PLATFORM_ID) private platformId: Object,
              ...) {
    this.isBrowser = isPlatformBrowser(this.platformId);
  }

  ngOnInit() {
    if(this.isBrowser){
      const stickyBlock = document.querySelector('.sticky-block');
      ...
    }
  }
  ...

nativeElement

В директиву автофокуса пришлось внести изменения в части проверки места запуска приложения:

  ngOnInit() {
    if (isPlatformBrowser(this.platformId) && (this._autofocus || typeof this._autofocus === 'undefined')) {
      this.el.nativeElement.focus();
    }
  }

ng2-charts

С этим модулем на сервере у меня тоже возникли проблемы:

Error: NotYetImplemented
...

Причина в том, что он использует nativeElement.getContext(). Поэтому пришлось отказаться от рендеринга диаграмм на сервере:

<div class="mash-chart" *ngIf="isBrowser">
  <app-mash-chart></app-mash-chart>
</div>

matTooltip: this._ariaDescriber.removeDescription is not a function и прочие аналогичные

А вот это крайне неприятные ошибки. Возникают не всегда, не везде, но ломают приложение полностью. Вместо ожидаемой страницы показывает стэк трэйс:

ERROR TypeError: this._ariaDescriber.removeDescription is not a function
at MatTooltip.set [as message] (/usr/src/app/server/server.js:219808:33)
at updateProp (/usr/src/app/server/server.js:15266:37)
at checkAndUpdateDirectiveInline (/usr/src/app/server/server.js:15017:19)
at checkAndUpdateNodeInline (/usr/src/app/server/server.js:16326:20)
at checkAndUpdateNode (/usr/src/app/server/server.js:16288:16)
at prodCheckAndUpdateNode (/usr/src/app/server/server.js:16832:5)
at Object.Of.t.ɵvid.e [as updateDirectives] (/usr/src/app/server/server.js:127276:851229)
at Object.updateDirectives (/usr/src/app/server/server.js:16618:29)
at checkAndUpdateView (/usr/src/app/server/server.js:16270:14)
at callViewAction (/usr/src/app/server/server.js:16511:21)

Воспроизвести можно быстро перейдя по ссылке в момент, пока происходит загрузка стартовой страницы.
Проблема известна и, вроде как, уже решена. Но решение еще не в релизе.

Также есть ряд похожих ошибок: focusMonitor.monitor is not a function, SSR crashes because of undefined functions. Все они связаны с этой проблемой самого Angular, и их частные решения выглядят какими-то костыльными. А пока добавляем в app.server.module.ts:

import {AriaDescriber, FocusMonitor} from '@angular/cdk/a11y';
import {AutofillMonitor} from '@angular/cdk/text-field';
  ...
  providers: [
    AriaDescriber,
    FocusMonitor,
    AutofillMonitor,
    ...

flex-layout устанавливает свойство display:block на инлайн элементы с fxShow/fxHide

Слетает выравнивание элементов разметки, ибо spanы, которые я скрываю/показываю в зависимости от ширины окна браузера, внезапно рендерятся как блоки.

Issue обещают пофиксить в ближайшем релизе. Можно подождать, можно указать для них display: inline.

Мерцания

После загрузки скриптов Universal удаляет пререндеренный контент и загружает вместо него клиентское приложение. Это клиентское приложение начинает обрабатывать роутинг и выполнять http запросы. Если в приложении настроены routing resolvers, то они не будут отображать содержимое компонет в router-outlet до тех пор, пока не получат (резолвят) ответ от сервера. Поэтому в промежуток времени между удалением пререндеренного контента и загрузкой данных с сервера в router-outlet будет пустота. Возникают довольно неприятные мерцания на странице.

Для предотвращения этой проблемы, помимо

// app.module.ts
  imports: [
    BrowserModule.withServerTransition({appId: 'my-app-id'})
    ...

в файле app-routing.module.ts необходимо для RouterModule указать initialNavigation: 'enabled':

@NgModule({
  imports: [RouterModule.forRoot(routes, {
    initialNavigation: 'enabled'
  })]
})

В dev это работает вполне сносно. Однако, тут и тут пишут, что в prod и с https могут быть проблемы. Требуется дополнительное тестирование.

Коды ответа (404, 500)

Поисковики ругаются на неправильно настроенное отображение несуществующих страниц:

Вероятно, на сайте некорректно настроен возврат HTTP-кода 404 Not Found, что может негативно сказаться на индексировании сайта роботом. Настройте возврат кода 404 на запрос несуществующих страниц. ©Яндекс Вэбмастер

Настроим приложение так, чтобы отрендеренная на сервере страница 404 отдавалась со статусом 404. Для этого в компоненте страницы с ошибкой error-404.component.ts добавим:

import {Component, Inject, OnInit, Optional, PLATFORM_ID} from '@angular/core';
import {RESPONSE} from '@nguniversal/express-engine/tokens';
import {isPlatformServer} from '@angular/common';

@Component({
  selector: 'app-error-404',
  templateUrl: './error-404.component.html'
})
export class Error404Component implements OnInit {

  constructor(@Inject(PLATFORM_ID) private platformId: Object,
              @Optional() @Inject(RESPONSE) private response,
              private appService: AppService) { }

  ngOnInit() {
    if (isPlatformServer(this.platformId)) {
      this.response.status(404);
    }
  }
}

Инжектим platformId и объект ответа сервера response. Если страница будет рендериться на сервере, то указываем this.response.status(404).

Требуется только запровайдить этот объект response. Делается это в файле server.ts:

import {REQUEST, RESPONSE} from '@nguniversal/express-engine/tokens';

...

app.get('*', (req, res) => {
  res.render('index', {
    req, 
    providers: [
      {
        provide: RESPONSE,
        useValue: res
      }
    ]
  });
});

Аналогично можно поступить и со страницей ошибки 500.

Проблемы с JWT аутентификацией

Мое приложение использует json web token аутентификацию пользователей. Если кратко, то пользователь вводит логин/пароль и сервер выдает ему токен. Этот токен сохраняется в localStorage браузера. Все последующие запросы на сервер выполняются с передачей этого токена в хэдере. Но при первом открытии страницы приложения, когда клиент еще не загружен и не может взять токен из хранилища и вставить его в хэдер, браузер выполняет запрос без токена. Universal пытается отрендерить страницу для неаутентифицированного пользователя. И, если данная страница для него не доступна и функция canActivate настроена на возврат страницы 404, то будет отрендерена страница 404. Таким образом получаем следующую картину:

• пользователь вошел в приложение, в браузере хранится токен;
• пользователь жмет F5 на странице, доступной только вошедшим;
• браузер запрашивает пререндер этой страницы без токена;
• render натыкается на canActivate в Router;
• canActivate редиректит на страницу 404;
• Universal отдает в браузер страницу 404;
• пользователь видит в окне браузер страницу ошибки вместо той, которую запрашивал;
• и только после загрузки и запуска клиентского приложения будет отрисована нужная страница.

И это очень некрасиво с точки зрения UX.

Для решения этой проблемы нужно менять архитектуру приложения и api, использовав для хранения токена cookies. Но мне этого делать ну никак не хочется, поэтому в функции canActivate я добавил проверку платформы и оставил редирект на 404 страницу только для браузера:

  canActivate(route: ActivatedRouteSnapshot,
              state: RouterStateSnapshot) {

    const availableRoles = route.data.availableRoles;
    const userRole = this.userService.isLoggedIn() && this.userService.getUserRole();

    if (userRole && availableRoles.includes(userRole)) {
      return true;
    } else if(isPlatformBrowser(this.platformId)) {
      this.router.navigate(['/404'], { skipLocationChange: true });
      return false;
    } else {
      return false;
    }
  }

Universal возвращает страницу с хэдером, футером, но без основного контента. После загрузки приложения будет отрисовано содержимое защищенной страницы. Или же страница 404, если пользователь не авторизирован. С точки зрения UX это выглядит как постепенная загрузка страницы. Но с точки зрения SEO это не очень хорошо. Если требуется, чтобы защищенные страницы были проиндексированы поисковиками, то нужно все же смотреть в сторону печенек. Или же, как вариант, отлавливать user agent поисковых ботов в server.ts, провайдить эту инфу в CanActivate и давать им доступ.

Стресс-тесты

Очень интересно было проверить, а какая же все-таки производительность у серверного рендеринга Angular? Почему-то все измеряют производительность только в миллисекундах, за которые рендерится страница. Мне же еще было интересно, а сколько же страниц одновременно может быть отрендерено без падения сервера? Для этого я воспользовался инструментом Artillery.io. Выбрал достаточно сложную страницу своего приложения (несколько запросов к API, несколько таблиц с ngFor, много материал компонент), которая больше всего нуждается в индексации поисковиками. В Artillery установил время теста 3 минуты и начал играть с arrivalRate. Начал с arrivalRate = 5 (каждую секунду создается 5 новых виртуальных пользователей, делающих запрос выбранной страницы):

artillery quick -d 180 -r 5 http://localhost:4000/my-hard-page

И вот результат:

arrivalRate: 5:

  Scenarios launched:  900
  Scenarios completed: 900
  Requests completed:  900
  RPS sent: 4.99
  Request latency:
    min: 287.8
    max: 514.2
    median: 324.9
    p95: 413.8
    p99: 445.2
  Scenario counts:
    0: 900 (100%)
  Codes:
    200: 900

325 ms - ну так себе.

arrivalRate: 7:

  Scenarios launched:  1260
  Scenarios completed: 1260
  Requests completed:  1260
  RPS sent: 6.99
  Request latency:
    min: 287.6
    max: 454.8
    median: 323.4
    p95: 382.7
    p99: 407
  Scenario counts:
    0: 1260 (100%)
  Codes:
    200: 1260

Похожий результат. Держимся.

arrivalRate: 9:

  Scenarios launched:  1620
  Scenarios completed: 1620
  Requests completed:  1620
  RPS sent: 8.98
  Request latency:
    min: 289.1
    max: 802.6
    median: 332.5
    p95: 583.9
    p99: 697.2
  Scenario counts:
    0: 1620 (100%)
  Codes:
    200: 1620

А вот на 9 rps уже заметно, что задержка начала расти. Подымаем еще немного:

arrivalRate: 10:

  Scenarios launched:  1800
  Scenarios completed: 1800
  Requests completed:  1800
  RPS sent: 8.09
  Request latency:
    min: 403.1
    max: 51821.2
    median: 16316.1
    p95: 47372.2
    p99: 50949.6
  Scenario counts:
    0: 1800 (100%)
  Codes:
    200: 1800

И вот он предел - c 10 rps Universal уже не справляется. Тесты проводил на реальном, довольно крупном приложении, на локальной машине с серьезным процессором и 16 ГБ оперативной памяти. На объективность не претендую и какие-либо выводы делать не берусь.

setTimeout

Как-то совсем забыл про рекомендацию избавиться от всех setTimeout в приложении. Избавился и провел еще одну серию тестов. В результате для arrivalRate = 5 удалось уменьшить среднее время ответа сервера почти в 3 раза (median: 324.9 vs 113):

arrivalRate: 5:

  Scenarios launched:  900
  Scenarios completed: 900
  Requests completed:  900
  RPS sent: 4.99
  Request latency:
    min: 93
    max: 214.2
    median: 113
    p95: 165.8
    p99: 184
  Scenario counts:
    0: 900 (100%)
  Codes:
    200: 900

Так что обязательно избавляемся от всех setTimeout в SSR!

Однако взять планку в 10 rps это все же не позволило. Время ответа выходит за все разумные пределы:

arrivalRate: 10:

  Scenarios launched:  1800
  Scenarios completed: 1613
  Requests completed:  1613
  RPS sent: 7.85
  Request latency:
    min: 499.4
    max: 69183.9
    median: 39094.5
    p95: 62356.7
    p99: 65200.5
  Scenario counts:
    0: 1800 (100%)
  Codes:
    200: 1613
  Errors:
    ECONNREFUSED: 187

Итоги

А в итоге такое неприятное ощущение, будто использую какую-то поделку, а не продукт, шестой версии, от корпорации добра, громко заявляющий:

DEVELOP ACROSS ALL PLATFORMS
Learn one way to build applications with Angular and reuse your code and abilities to build apps for any deployment target. https://angular.io/

Слишком много надо допиливать, выравнивать, чинить и костылить. В статье описал далеко не все возникшие проблемы и сложности - и так много текста получилось.

Очень хотелось бы в комментариях почитать отзывы людей, успешно использующих Angular SSR "в бою". Как повышаете производительность, как кэшируете, какие еще проблемы были у вас? Или может кто-то уже использует headless браузеры для этих целей?

Ух, давненько ничего не писал, но тут созрел повод. На моем вялотекущем проекте встала задача добавить пользователям возможность размещать и просматривать фотографии. Было решено оформить массив загруженных фоток в стиле Pinterest.

После легкого курса гуглотерапии было усвоено следующее:

• данная компоновка сетки из картинок носит условное название "Masonry" (да-да, масоны - сообщество вольных плиточников);
• есть библиотека, которая позволяет вертикально укладывать фотки будто плитки - Masonry;
• у нее нет официальной поддержки Angular;
• ее адаптации сторонних разработчиков под Angular либо очень сырые, либо заброшены (сори, без примеров и ссылок, гуглите и оценивайте сами, применяйте на свой страх и риск);
• реализация плиточной кладки на чистом CSS на момент начала 2018 года не возможна;
• готовые решения в статьях показывают не совсем верную реализацию (высота ряда равна высоте наибольшей плитки, плитки располагаются по колонкам и т.п.);
• есть интересная статья, как можно реализовать требуемый эффект на CSS Grid с помощью малой толики javascript.

Вывод: это нужно пилить самостоятельно и писать по этому поводу статью ;)

Для наглядности демо того, что должно получиться в итоге.

Ну что ж, приступим?

Постановка задачи

Думаю, что при просмотре демки, общий принцип работы данного компонента и способ построения плиток в сетке становится сразу понятен. Но все же обобщу требования:

• имеется массив из картинок;
• данные изображения требуется расположить на странице таким образом, чтобы они занимали все её свободное пространство;
• ширина всех картинок одинакова и вычисляется исходя из ширины страницы и заданного количества колонок;
• картинки по порядку располагаются в ряд;
• если картинку в текущем ряду поместить невозможно, то она переносится ниже;
• перенесенная картинка должна быть помещена в колонку с наименьшей высотой;
• последующие картинки располагаются также в колонки с наименьшей высотой (с наибольшим свободным пространством под ними).

Дополнительные требования (адаптивность/responsive design):

• количество колонок определяется разработчиком для различных диапазонов ширины окна браузера.

Дополнительные требования (декоративные):

• визуальный эффект перемещения картинок при изменении размера экрана;
• визуальный эффект при загрузке/добавлении изображения;
• визуальный эффект приближения при наведении курсора;
• визуальный эффект при клике.

Инструменты

В моем приложении, а следовательно и в примере данной статьи, используются:

• Angular ~5.2.10;
• Material ~5.2.4;
• Flex-layout ~5.0.0.

Принцип

Для построения сетки изображений будет использоваться компонент Material Grid List. Он позволяет задавать следующие параметры:

• cols - количество колонок сетки;
• rowHeight - высота каждого ряда;
• gutterSize - ширина шва между плитками сетки.

Для каждой конкретной плитки задаются:

• colspan - количество колонок, которое будет занято плиткой;
• rowspan - количество рядов, занимаемых плиткой.

Итак, основная идея заключается в том, что мы устанавливаем очень малую высоту ряда (rowHeight="1px"), картинки растягиваем на всю ширину плитки (style="width: 100%;"). Высота каждой картинки будет вычислена пропорционально ее базовым размерам. Нам остается только извлечь ее и передать в качестве значения количества рядов ([rowspan]="imageHeight").

Реализация

Наше приложение будет состоять из трех компонентов:

• app.component - главный компонент, в котором будем генерировать массив картинок и передавать его в галерею;
• grid-gallery.component - собственно компонент самой галереи;
• grid-gallery-item.component - элемент галереи, плитка, в которой будет располагаться изображение.

Начнем с реализации основного функционала, а далее доработаем его в части адаптивности и декоративности.

Интерфейс изображения

//app/image.model.ts

export interface Image {
  src: string,
  alt?: string
}

Главный компонент приложения

//app/app.component.ts

import {Component, Input} from '@angular/core';
import {Image} from "./image.model";

@Component({
  selector: 'app-component',
  templateUrl: 'app.component.html',
  styleUrls: ['app.component.scss'],
})
export class AppComponent {

  numOfImages = 10; // Требуемое количество сгенерированных изображений
  images: Image []; // Массив изображений

  constructor() {
    this.images = this.generateImagesList();
  }

  private generateImagesList(): Image[] {
    const images: Image[] = [];
    for (let i = 0; i < this.numOfImages; i++){
      const image = this.generateRandomImage();
      image.alt = `#${i}`;
      images.push(image);
    }
    return images;
  }

  private generateRandomImage(): Image {
    const width = 600;
    const height = (Math.random() * (1000 - 400) + 400).toFixed();
    return {src: `https://picsum.photos/${width}/${height}/?random`};
  }

  addImage() {
    const image = this.generateRandomImage();
    image.alt = `#${this.images.length}`;
    this.images.push(image);
  }
}

Генерируем массив из 10 изображений. Для этого используем сервис picsum.photos. Высота изображения устанавливается случайным образом из диапазона 400 - 1000 px, ширина - 600 px. Ну и метод для добавления изображения.

<!-- app/app.component.html -->

<!-- Header -->
<div class="toolbar" fxFlex='100%' fxLayout="row" fxLayoutAlign="end center">
  <button mat-raised-button color="primary" (click)="addImage()">ADD IMAGE</button>
</div>

<!-- Gallery -->
<app-grid-gallery [images]="images" [cols]="4" [rowHeight]="1"></app-grid-gallery>

В шаблоне будет хэдер с кнопкой для добавления картинки и компонент галереи app-grid-gallery. В него мы передаем наш массив с фотками, указываем требуемое количество колонок (4) и указываем высоту рядов (как писал выше - 1 px).

Ну и приступаем непосредственно к самой галерее.

Компонент галереи

// app/grid-gallery/grid-gallery.component.ts

import {Component, Input} from '@angular/core';
import {Image} from "../image.model";

@Component({
  selector: 'app-grid-gallery',
  templateUrl: './grid-gallery.component.html'
})
export class GridGalleryComponent{

  @Input() images: Image[];
  @Input() cols: number = 4; // Количество колонок
  @Input() rowHeight: number = 1; // Высота рядов, px
  @Input() gutterSize: number = 1; // Ширина шва, px
}

Здесь практически пусто. Определяем входные параметры компонента и указываем их дефолтные значения. В дальнейшем здесь также будем следить за шириной окна браузера и изменять количество колонок. Но для начала этого достаточно.

В шаблоне поинтереснее:

<!-- app/grid-gallery/grid-gallery.component.html -->

<mat-grid-list [cols]="cols"
               [rowHeight]="rowHeight"
               [gutterSize]="gutterSize+'px'">

  <mat-grid-tile *ngFor="let imageItem of images"
                 [rowspan]="item.rows">

    <app-grid-gallery-item  #item 
                            [image]="imageItem" 
                            [rowHeight]="rowHeight" 
                            [gutterSize]="gutterSize">
    </app-grid-gallery-item>

  </mat-grid-tile>

</mat-grid-list>

mat-grid-list и mat-grid-tile - компоненты Material Grid List. В цикле пробегаем по массиву изображений, генерируя для каждого mat-grid-tile. В каждую плитку вставляем компонент app-grid-gallery-item. Его рассмотрим чуть ниже.

Тут важный момент: для каждого элемента мы создаем шаблонную переменную #item и привязываем свойство компонента с количеством строк к параметру rowspan плитки:

[rowspan]="item.rows"

Компонент элемента галереи

Основное назначение данного компонента - следить за высотой картинки и вычислять количество рядов, которое должна занимать плитка, исходя из заданных rowHeight и gutterSize.

// app/grid-gallery/grid-gallery-item/grid-gallery-item.component.ts

import {Component, ElementRef, Input, ViewChild} from '@angular/core';
import {Image} from "../../image.model";

@Component({
  selector: 'app-grid-gallery-item',
  templateUrl: './grid-gallery-item.component.html',
  styleUrls: ['./grid-gallery-item.component.scss']
})
export class GridGalleryItemComponent {

  @Input() image: Image;
  @Input() rowHeight: number = 1;
  @Input() gutterSize: number = 1;

  @ViewChild('img') img: ElementRef;

  public rows: number = 0; // Число рядов, используемое для rowspan mat-grid-tile

  calculateRows() {
    this.rows = Math.floor(this.img.nativeElement.offsetHeight / (this.rowHeight + this.gutterSize));
  }
}

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

<!-- app/grid-gallery/grid-gallery-item/grid-gallery-item.component.html -->

<img  #img 
      [src]="image?.src" 
      [alt]="image?.alt"/>

В шаблоне все просто. Используем переменную шаблона #img для доступа к ней из класса через @ViewChild. Передаем src и alt.

Ну и немножко стилей:

// app/grid-gallery/grid-gallery-item/grid-gallery-item.component.scss

:host {
  height: 100%; 

  img {
    width: 100%;
  }
}

Устанавливаем высоту компонента в 100% и растягиваем картинку на всю ширину плитки.

Теперь нужно все это оживить. Для этого необходимо определить моменты, когда вызывать метод calculateRows. Во-первых, нам нужно просчитать количество строк сразу после отрисовки компонента. На ум приходит использовать хуки жизненного цикла Angular: OnInit, AfterViewInit или AfterViewChecked. Однако эти методы будут вызываться до того, как успеет подгрузиться изображение, а следовательно количество рядов не будет вычислено. Для решения этой задачи привяжем вызов метода calculateRows к событию (load) нашего изображения:

<!-- app/grid-gallery/grid-gallery-item/grid-gallery-item.component.html -->

<img  #img 
      [src]="image?.src" 
      [alt]="image?.alt"
      (load)="calculateRows()"/>

Отлично! Теперь после загрузки приложения наши картинки будут выстраиваться плитками в нужном нам порядке. Но... При изменении ширины окна браузера картинки будут изменять свой размер, а количество рядов, занимаемых плиткой, пересчитано не будет. Поэтому, во-вторых, нужно добавить декоратор @HostListener к методу calculateRows для обработки события изменения размеров окна:

// app/grid-gallery/grid-gallery-item/grid-gallery-item.component.ts

...
  @HostListener('window:resize')
  calculateRows() {
  ...
  }

Посмотреть работу компонента и код на этой стадии можно здесь.

Далее приступаем к добавлению отзывчивого дизайна.

Добавляем адаптивность

В разделе постановки задач я привел дополнительное требование, касающееся адаптивности (англ. Adaptive Web Design). Требуется обеспечить возможность указывать для компонента галереи количество колонок в зависимости от ширины окна браузера. То есть мы хотим указать, что при открытии приложения на экранах мобильных устройств с шириной до 600 px, все наши изображения должны быть выстроены в 1 колонку, для экранов с шириной 600-960 px - в две колонки, и т.д. Здесь нам и понадобится модуль Angular Flex-Layout.

// app/grid-gallery/grid-gallery.component.ts

import {Component, Input, OnInit, OnDestroy} from '@angular/core';
import {MediaChange, ObservableMedia} from '@angular/flex-layout';
import {Subscription} from "rxjs/Subscription";
import {Image} from "../image.model";

@Component({
  selector: 'app-grid-gallery',
  templateUrl: './grid-gallery.component.html'
})
export class GridGalleryComponent implements  OnInit, OnDestroy {

  @Input() images: Image[];
  @Input() cols: number = 4;
  @Input('cols.xs') cols_xs: number = 1;
  @Input('cols.sm') cols_sm: number = 2;
  @Input('cols.md') cols_md: number = 3;
  @Input('cols.lg') cols_lg: number = 4;
  @Input('cols.xl') cols_xl: number = 6;
  @Input() rowHeight: number = 1;
  @Input() gutterSize: number = 1;

  mediaWatcher: Subscription;

  constructor(private media: ObservableMedia) {
  }

  ngOnInit(){
    this.mediaWatcher = this.media.subscribe((change: MediaChange) => {
      this.cols = this[`cols_${change.mqAlias}`];
     });
  }

  ngOnDestroy(): void {
    this.mediaWatcher.unsubscribe();
  }
}

Добавляем @Input свойства cols_xs, cols_sm, cols_md, cols_lg и cols_xl для компонента галереи и указываем их значения по умолчанию. Почитать про использование медиа псевдонимов (aliases) можно здесь.

Для отслеживания события перехода от одного медиа диапазона к другому воспользуемся сервисом ObservableMedia. Подпишемся на MediaChange и из него будем вытягивать актуальный alias, а затем обновлять параметр cols для mat-grid-list.

Указывать количество колонок в шаблоне можно следующим образом:

<!-- app/app.component.html -->

<!-- Gallery -->
<app-grid-gallery [images]="images" 
                  cols.xs="1"
                  cols.sm="2"
                  cols.md="3"
                  cols.lg="4"
                  cols.xl="6">
</app-grid-gallery>

Код приложения на текущем этапе.

Наводим лоск

Добавим немного декоративной мишуры.

Во-первых, обернем наши изображения в кнопки mat-button. Это добавит эффект волны при клике по ним.

<!-- app/grid-gallery/grid-gallery-item/grid-gallery-item.component.html -->

<button mat-button>
  <img  #img 
        [src]="image?.src" 
        [alt]="image?.alt"
        (load)="calculateRows()"/>
</button>

В стилях сбросим padding для кнопок и зададим эффект медленного приближения картинки при наведении мыши:

// app/grid-gallery/grid-gallery-item/grid-gallery-item.component.scss

:host {
  height: 100%; 

  button {
    padding: 0;
  }

  img {
    width: 100%;
    transition: transform 90s;
    transform: scale(1) translateZ(0); 
  }

  &:hover {
    img {
      transition: transform 30s;
      transform: scale(1.33) translateZ(0); 
    }
  }
}

Ну и напоследок добавим анимацию появления и перемещения плиток:

// app/grid-gallery/grid-gallery.component.scss

mat-grid-tile {
  transition: top 0.3s, left 0.3s, height 0.3s;
}

Финальная версия компонента.

Надеюсь, что кому-нибудь это будет полезно. Буду рад вопросам, замечаниям и здоровой критике в комментариях. Спасибо.

Задача старая, инструменты новые. Приклеиваем футер к полу. Теперь на Angular с его новым движком компоновки Flex-layout.

Пусть мы имеем файл app.component.ts с шаблоном вида:

  template: `
    <div class="app-container">
      <div class="header"></div>
      <div class="body"></div>      
      <div class="footer"></div>
    </div>`

Для начала зададим высоту 100% для родительских элементов в файле style.css:

html, body, .app-container {
    height: 100%;
}

В шаблоне для .app-container зададим модель выравнивания в колонку с растягиванием по ширине:

<div class="app-container" fxLayout="column" fxLayoutAlign="start stretch">
...

Между блоками .body и .footer требуется добавить вспомогательный div, который будет занимать все свободное пространство между ними, когда контента до футера не хватает.

<div class="helper" fxFlex fxFlexFill></div>

Здесь важно заметить, что требуется указать и fxFlex, и fxFlexFill, хотя из документации выглядит, что прописывать fxFlex не требуется. Однако без него не работает.

Ну и собственно все! Можно поиграться с Plunker:

У этого способа есть еще одно преимущество - футер может быть динамической высоты. Т.е. не обязательно задавать фиксированную высоту для него, а она может определяться содержимым и размером окна. При этом футер все равно будет оставаться снизу и не будет перекрывать основной контент.

Как мы знаем, для загрузки файлов в html есть соответствующий тэг:

<input type="file">

И выглядит он довольно убого, не стильно, не модно. Как-то так:

Если вы работаете с Angular 2 Material, и пытаетесь найти этот элемент, то смею вас огорчить. Вот ответ разработчика:

Ну что же, будем действовать самостоятельно. Как оказалось, запилить свою, стилизованную под material кнопку загрузки, не так то сложно. Будем отталкиваться от этого:

    <input type="file" accept="image/" id="file-input">
    <label for="file-input">
        Загрузить файл
    </label>

Выглядит на форме это так:

Здесь нужно обратить внимание на то, что по клику на label мы получаем необходимую нам реакцию - открытие окна для выбора файла.

Далее в него мы и помещаем нашу красивую кнопку, использовав стиль angular material:

    <label for="file-input">
      <a md-raised-button class="btn"><i class="material-icons">file_upload</i> 
        Загрузить файл
      </a>
    </label>

И осталось только скрыть уродливый html input с помощью hidden="true":

    <input hidden="true" type="file" id="file-input">
    <label for="file-input">
      <a md-raised-button class="btn"><i class="material-icons">file_upload</i> 
        Загрузить файл
      </a>
    </label>

Проверяем:

Вот и все. Должно работать.

Чтобы оптимизировать страницы нашего приложения для поисковых систем нам необходимо иметь возможность управлять такими тегами как title, meta description и meta robots. Для этого в Angular 2 появились классы Title и Meta. На момент написания статьи данные классы в документации помечены как экспериментальные. Так что использовать на свой страх и риск.

Создадим сервис app.service.ts со следующим содержимым:

import {Injectable} from '@angular/core';
import {Title, Meta} from '@angular/platform-browser';

@Injectable()
export class AppService {

  constructor(private titleService: Title, private metaService: Meta) {  }

  setPageTitle(title: string) {
    this.titleService.setTitle(title);
  }

  setPageDescription(description: string) {
    this.metaService.updateTag({name: 'description', content: description});
  }
    
  setMetaRobots(robots: string) {
    this.metaService.updateTag({name: 'robots', content: robots});
  }
}

В модуле app.module.ts не забываем указать его в списке провайдеров:

import {AppService} from './app.service'

@NgModule({
  providers: [
    AppService
  ]
})

Теперь в других компонентах можем использовать наш сервис для задания тегов:

import {Component, OnInit} from '@angular/core';
import {AppService} from './app.service'

@Component({
  selector: 'app-component',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent implements OnInit {

  constructor(private appService: AppService) {
  }

  ngOnInit() {
    this.appService.setPageTitle('My app page title');
    this.appService.setPageDescription('My app page description');
    this.appService.setMetaRobots('Index, Follow');
  }    
}

В предыдущих статьях я описал создание RESTful API для коллекции книг на Swagger Node.js и добавление пагинации - возможности разбивать на части большой список книг в ответе сервера. Теперь же попробуем решить следующую проблему: абсолютно любой пользователь API может как просматривать книги, так и добавлять новые, редактировать и удалять их. Я хочу сделать так, чтобы операции добавления, редактирования и удаления книг были доступны только зарегистрированным пользователям. Для этого требуется встроить в API систему аутентификации пользователей.

Общие данные

Определения

Аутентификация - процедура проверки подлинности пользователя, например, путём сравнения введённого им пароля с паролем, сохранённым в базе данных пользователей.

Авторизация - предоставление определённому пользователю прав на выполнение определённых действий.

Т.о. для того, чтобы авторизировать пользователя на выполнение некоторых операций, мы должны его сперва аутентифицировать.

Применяемые стратегии аутентификации

Basic

Пользователь вводит логин и пароль. Введенные данные объединяются в строку вида:

username:password

Данная строка кодируется в Base64:

dXNlcm5hbWU6cGFzc3dvcmQ=

И передается на сервер в заголовке запроса в виде:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

На сервере строка декодируется, находится профиль пользователя, верифицируется его пароль.

По этой схеме данные пользователя, по сути, передаются в открытом виде и https обязателен к применению.

JSON Web Token (JWT)

Для подтверждения своей личности пользователь должен предоставить специальный JSON Web Token. Этот токен представляет собой строку вида:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwidXNlcm5hbWUiOiJKb2huIERvZSJ9.4emg-RQp4p0i9tDfjhhYDdlFEgHYalkQlbminY_0iSc

Эта строка состоит из трех частей, разделенных точками:

1. Заголовок (header) - строка, закодированная в Base64, представляющая собой JSON объект:

{
  "alg": "HS256",
  "typ": "JWT"
}

Обычно содержит в себе сведения о типе токена и применяемом алгоритме шифрования.

2. Полезная нагрузка (payload) - строка, закодированная в Base64, представляющая собой JSON объект. Содержит в себе некоторую полезную информацию о пользователе, например:

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": false
}

3. Подпись - строка, вычисленная по указанному в заголовке алгоритму шифрования:

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret)

secret - секретная фраза, которую знает только сервер, генерирующий токены и проверяющий их.

Получив данный токен, сервер с помощью секретной фразы шифрует по заданному алгоритму заголовок и нагрузку. Затем сверяет подпись, получившуюся при шифровании, и переданную в токене. Если они совпадают, то токен считается валидным и пользователь проходит аутентификацию. Если же в нагрузку токена внесены какие-то изменения, например "admin": true, то подписи не совпадут и аутентификация будет провалена.

Завладев чужим токеном, злоумышленник получает его права доступа. Поэтому необходимо использовать https. Также эта стратегия позволяет добавить в токен срок жизни, по истечении которого требуется обновить токен или получить новый.

Проектируем API

В конце файла swagger.yaml добавим описание наших стратегий аутентификации:

securityDefinitions:
  Basic:
    type: basic
  JWT:
    type: apiKey
    name: Authorization
    in: header

Конечные точки API (операции добавления, редактирования и удаления книг) будут защищены с помощью JWT. Т.е. пользователь, который захочет добавить книгу, сможет это сделать, только предоставив в заголовке запроса токен.

Выдавать токены будем по маршруту GET /login. Для получения токена пользователь должен ввести свое имя и пароль, т.е. пройти Basic аутентификацию. Соответственно, чтобы пройти ее, пользователь предварительно должен быть зарегестрирован в нашем приложении. Регистрация новых пользователей будет производиться по маршруту POST /signup.

Добавим в swagger.yaml файл описания для пользователя и для токена:

User:
  properties:
    username: 
      type: string
    password:
      type: string
      format: password
  required:
    - username
    - password
    
Token:
  properties:
    user:
      type: string
    token:
      type: string
  required:
    - user
    - token

Опишем маршрут для регистрации новых пользователей POST /signup:

/signup:
  x-swagger-router-controller: auth-controller
  post:
    operationId: signup
    parameters:
      - name: user
        in: body
        description: New User
        required: true
        schema:
          $ref: '#/definitions/User'
    responses:
      "200":
        description: User created
        schema:
          $ref: "#/definitions/GeneralResponse"
       # responses may fall through to errors
      default:
        description: Error
        schema:
          $ref: "#/definitions/ErrorResponse"

Маршрут для получения токена GET /login:

/login:
  x-swagger-router-controller: auth-controller
  get:
    operationId: login
    security:
      - Basic: [] # Так указываем применяемую схему!
    responses:
      "200":
        description: Log In
        schema:
          $ref: "#/definitions/Token"
       # responses may fall through to errors
      default:
        description: Error
        schema:
          $ref: "#/definitions/ErrorResponse"

И теперь в описаниях операций, которые мы хотим защитить (POST /books, PUT /books/{id} и DELETE /books/{id}), нужно добавить строки:

  security:
    - JWT: []

С YAML-файлом закончили. Приступаем к написанию логики.

Реализуем функционал аутентификации API

Нам потребуется passport.js, две стратегии аутентификации, passport-http и passport-jwt, а также jsonwebtoken - модуль для работы с JWT токенами:

npm install passport passport-http passport-jwt jsonwebtoken -save

Определим mongoose схему и модель для пользователя в файле api/models/user-model.js:

var crypto = require('crypto');
var mongoose = require('mongoose');
var Schema = mongoose.Schema;

// User
var User = new Schema({
    username: {
        type: String,
        unique: true,
        required: true
    },
    hashedPassword: {
        type: String,
        required: true
    },
    salt: {
        type: String,
        required: true
    },
    created: {
        type: Date,
        default: Date.now
    }
});

// Шифруем пароль
User.methods.encryptPassword = function (password) {
    return crypto.createHmac('sha1', this.salt).update(password).digest('hex');
};    

// Аксессоры для пароля
User.virtual('password')
    .set(function (password) {
        this._plainPassword = password;
        this.salt = crypto.randomBytes(32).toString('base64');
        this.hashedPassword = this.encryptPassword(password);
    })
    .get(function () {
        return this._plainPassword;
    });

// Проверка пароля
User.methods.checkPassword = function (password) {
    return this.encryptPassword(password) === this.hashedPassword;
};

// Проверка на уникальность 'username'
User.path('username').validate(function(value, done) {
    this.model('User').count({ username: value }, function(err, count) {
        if (err) {
            return done(err);
        }
        done(!count);
    });
}, 'username already exists');

var UserModel = mongoose.model('User', User);

module.exports = UserModel;

Пароли пользователей хранить в БД в открытом виде не будем, а будем хранить случайно сгенерированную соль и хэш пароля, полученный с помощью этой соли. При проверке будем сравнивать не сами пароли, а хэш пароля, переданного пользователем, с хэшем, хранимым в БД.

Создадим файл конфигурации config/config.js, в котором зададим секретную фразу. С ее помощью будут подписываться наши токены. Там же зададим срок жизни токенов:

const config = {
    jwt: {
        secret: 'my_supper_extra_mega_uber_secret_phrase',
        expiresIn: '2 days'
    }
};

module.exports = config;

В файле api/auth/passport.js опишем работу наших стратегий аутентификации:

var passport = require('passport');
var BasicStrategy = require('passport-http').BasicStrategy;
var JwtStrategy = require('passport-jwt').Strategy,
    ExtractJwt = require('passport-jwt').ExtractJwt;

var config = require('../../config/config');
var User = require('../models/user-model');

// Basic стратегия
passport.use(new BasicStrategy(
    function(username, password, done) {
        User.findOne({ username: username }, function (err, user) {
            if (err) {
                return done(err);
            }
            if (!user) {
                return done(null, false);
            }
            if (!user.checkPassword(password)) {
                return done(null, false);
            }
            return done(null, user);
        });
    }
));

// JWT стратегия
var opts = {};
opts.jwtFromRequest = ExtractJwt.fromAuthHeader();
opts.secretOrKey = config.jwt.secret;

passport.use(new JwtStrategy(opts, function(jwt_payload, done) {
    User.findOne({username: jwt_payload.username}, function(err, user) {
        if (err) {
            return done(err);
        }
        if (!user) {
            return done(null, false);
        }
        return done(null, user);
    });
}));

module.exports = passport;

В api/helpers/security-handlers.js напишем обработчики безопасности, которые будет использовать Swagger:

var passport = require('../auth/passport');

function Basic (req, def, scopes, callback) {
    passport.authenticate('basic', {session: false}, function (err, user, info) {
        if (err) {
            callback(new Error('Authentication error'));
        } else if (!user) {
            callback(new Error('User not found'));
        } else {
            req.user = user;
            callback();
        }
    })(req, null, callback);
}

function JWT (req, def, scopes, callback) {
    passport.authenticate('jwt', {session: false}, function (err, user, info) {
        if (err) {
            callback(new Error('Authentication error'));
        } else if (!user) {
            callback(new Error('User not found'));
        } else {
            req.user = user;
            callback();
        }
    })(req, null, callback);
}

module.exports = {
    Basic: Basic,
    JWT: JWT
};

Эти обработчики требуется подключить в конфиге SwaggerExpress в файле app.js:

var passport = require('./api/auth/passport');
var secHandlers = require ('./api/helpers/security-handlers');

app.use(passport.initialize());

...

var config = {
    appRoot: __dirname,
    swaggerSecurityHandlers: {
        Basic: secHandlers.Basic,
        JWT: secHandlers.JWT
    }
};

SwaggerExpress.create(config, function (err, swaggerExpress) {

...

Именно их названия мы указывали для операций в поле security swagger.yaml файла.

Осталось написать контроллеры для регистрации новых пользователей и для получения токена по логину и паролю. В файле api/controllers/auth-controller.js пропишем:

var jwt = require('jsonwebtoken');

var config = require('../../config/config');
var User = require('../models/user-model');

module.exports = {
    signup: signup,
    login: login
};

// Регистрация новых пользователей
function signup(req, res) {
    var user = new User (req.swagger.params.user.value);
    user.save(function (err) {
        if (err) {
            console.error(err);
            res.status(500).json({message: err.message});
        } else {
            res.json({message: 'OK'});
        }
    })
}

// Аутентификация пользователей по логину и паролю, выдача токена
function login(req, res) {
    if (req.isAuthenticated()) {
        res.json({
            user: req.user.username,
            token: 'JWT ' + jwt.sign({username: req.user.username}, config.jwt.secret, {expiresIn: config.jwt.expiresIn})
        });
    }
}

Теперь можно проверять работу аутентификации.

Тестируем аутентификацию

Запускаем mongod, выполняем swagger project start, swagger project edit. В Swagger Editor зарегистрируем нового пользователя по маршруту POST /signup.

В правой части редактора вверху появились блоки, которые позволяют аутентифицироваться:

Введем логин и пароль нашего тестового пользователя в Basic форму. Затем по маршруту GET /login получим токен для нашего пользователя:

Попробуем создать книгу по маршруту POST /books, который требует наличие JWT токена:

В ответе получим ошибку "User not found".

А теперь аутентифицируемся по JWT, вставив в поле key токен, который мы получили ранее.

И вновь попробуем создать книгу:

Аутентификация пройдена, новая книга успешно добавлена.

Ну как-то так. Весь код на Github.

В предыдущей статье мы написали на Swagger Node небольшой простенький API для работы с коллекцией книг. Однако там есть нюанс. Предположим, у нас собралась большая библиотека из нескольких десятков тысяч книг. Каждый раз, когда мы делаем запрос GET /books, наш API отдает полную коллекцию. Это отражается на скорости работы нашего приложения и количестве переданного трафика. Поэтому в этой статье попробуем организовать частичную выдачу книг.

Редактируем API

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

• count - общее количество книг в коллекции;
• limit - количество книг в одном ответе (показываемых на одной странице);
• skip - количество пропущенных книг от начала и до первой из текущей выдачи (количество книг на предыдущих страницах).

Зная эти параметры в клиентском приложении легко можно рассчитать общее количество страниц, номер текущей страницы, номера последних страниц.

skip и limit мы будем передавать в качестве параметров запроса. count должен вернуть в ответе сервер.

В файле swagger.yaml в самом конце добавим описания параметров:

parameters:
  skipParam:
    name: skip
    in: query
    description: number of items to skip
    required: false
    type: integer
    format: int32
    minimum: 0
  limitParam:
    name: limit
    in: query
    description: max records to return
    required: false
    type: integer
    format: int32
    maximum: 100
    minimum: 0

Ограничим минимальное значение для skip и limit и максимальное значение для limit. Передавать их будем в query запроса.

Добавим описание схемы для ответа с постраничной выдачей книг в definitions::

Books:
  properties:
    paging:
      type: object
      properties:
        skip:
          type: integer
        limit: 
          type: integer
        count: 
          type: integer
    data:
      type: array
      items:
        $ref: '#/definitions/Book'
  required:
      - paging
      - data

Как видим, теперь ответ сервера должен содержать объект paging с параметрами пагинации и массив с книгами data.

Подправим маршрут GET /books следующим образом:

get:
  description: Return a books list
  parameters:
    - $ref: "#/parameters/skipParam"
    - $ref: "#/parameters/limitParam"
  responses:
    "200":
      description: Success 
      schema:
        $ref: '#/definitions/Books'
    # responses may fall through to errors
    default:
      description: Error
      schema:
        $ref: "#/definitions/ErrorResponse"

Перезапустим сервер в mock-режиме:

swagger project start -m

и попробуем отправить запрос.

Работает. Можно браться за контроллер.

Модифицируем контроллер

Заменим код функции getAll на следующий:

function getAll(req, res) {
    var skip = req.swagger.params.skip.value ? req.swagger.params.skip.value : 0;
    var limit = req.swagger.params.limit.value ? req.swagger.params.limit.value : 10;

    Book.find().count(function (err, count) {

        Book.find().skip(skip).limit(limit).exec(function (err, books) {
            if (err) {
                throw err;
            } else {
                res.json({
                        paging: {
                            count: count,
                            skip: skip,
                            limit: limit
                        },
                        data: books
                    }
                );
            }
        });
    });
}

Сперва считываем параметры skip и limit и присваиваем значения по умолчанию, если они не заданы. Затем выполняем запрос в БД для определения общего количества книг count. А потом с заданными параметрами делаем соответствующую выборку книг из БД и отдаем ответ клиенту.

Убедимся, что в swagger.yaml для GET /books задан operationId: getAll. Создадим несколько книг методом POST /books и попробуем поиграться с параметрами пагинации.

Посмотреть код целиком можно в
этой ветке на гитхабе.

Можете критиковать.

Можно разработать просто лучший REST API, но без документации им просто никто не сможет пользоваться. Swagger - популярный фреймворк с развитой экосистемой инструментов, который помогает проектировать, писать, документировать и работать с RESTful API. Для Node.js есть модуль Swagger Node. С его помощью можно спроектировать API, используя mock-объекты, а только потом реализовать логику, написав соответствующие контроллеры. В данной статье мы воспользуемся подобной тактикой и попробуем Swagger в действии.

Установка и запуск примера

Для начала глобально установим swagger:

npm install -g swagger

Теперь создадим новый проект. Пускай это будет коллекция книг:

swagger project create books

В диалоге выбираем сервер express. Swagger сгенерирует нам следующую структуру:

    -- api  
    ---- controllers 
    ------ hello_world.js
    ---- helpers
    ---- mocks
    ---- swagger
    ------ swagger.yaml

    -- config 
    ---- default.yaml

    -- test
    ---- api
    ------ controllers
    -------- hello_world.js
    ------ helpers

    -- app.js
    -- package.json

app.js - это главный файл, который запускает наш сервер.

В директории api находится все, что касается нашего API: контроллеры, вспомогательные модули, mock-объекты. Здесь следует обратить внимание на файл api/swagger/swagger.yaml. В этом файле собственно и находится все описание API в формате YAML.

В файле config/default.yaml находится описание конфигурации swagger.

В каталоге test располагаются тесты для нашего кода.

При создании нового проекта swagger сгенерировал пример обработки GET заброса по маршруту /hello. Поэтому мы можем видеть контроллер hello_world.js и тест для него. Давайте попробуем запустить этот пример в редакторе Swagger Editor.

Запускаем сервер:

swagger project start

Сервер следит за файлами и при изменении перезапускается автоматически.

Теперь в другой командной строке запускаем редактор:

swagger project edit

Должно открыться окно браузера и там вы должны увидеть такую картину:

Слева отображается собственно наш файл swagger.yaml с возможностью его редактирования. А вот справа находится самое интересное - красивый список маршрутов и методов. Их можно сворачивать/разворачивать и при этом сворачивается/разворачивается код в файле. Можно удобно переходить между маршрутами. По клику на методе открывается подробная информация о параметрах, принимаемых сервером, и возможных вариантах ответа. И прямо тут можно протестировать каждый метод. Нажимаем кнопку Try this operation, вводим имя в поле name, кликаем на Send Request и смотрим на ответ сервера:

Теперь подробнее рассмотрим yaml-файл.

В самом его начале указывается формат запросов и ответов:

# формат тела запроса, который клиент может отправить (Content-Type)
consumes:
  - application/json
# формат ответа клиенту (Accepts)
produces:
  - application/json

Далее следует описание маршрута:

paths:
    /hello:
        x-swagger-router-controller: hello_world 
        get:
            description: Returns 'Hello' to the caller
            # метод контроллера
            operationId: hello
            parameters:
                - name: name
                in: query
                description: The name of the person to whom to say hello
                required: false
                type: string
            responses:
                "200":
                    description: Success
                    schema:
                        # ссылка на определение
                        $ref: "#/definitions/HelloWorldResponse"
                # могут быть и ошибки
                default:
                    description: Error
                    schema:
                        $ref: "#/definitions/ErrorResponse"

Здесь:

• x-swagger-router-controller - название файла-контроллера (/api/controllers/hello_world.js);
• operationId - функция в этом контроллере, которая обрабатывает данный запрос;
• parameters - перечень необходимых параметров. В нашем случае только один необязательный (required: false) строковый (type: string) параметр name, который должен находиться в строке запроса (in: query);
• responses - список возможных ответов сервера. Для статуса "200" через ссылку $ref определена схема HelloWorldResponse, а для ошибки - ErrorResponse. Данные определения располагаются в конце файла.

Еще взглянем на функцию hello в контроллере:

function hello(req, res) {
    var name = req.swagger.params.name.value || 'stranger';
    var hello = util.format('Hello, %s!', name);
    res.json(hello);
}

Здесь стоит обратить внимание на то, что теперь у объекта req есть свойство swagger с информацией о параметрах.

Теперь, пожалуй, можно приступать к написанию своего API.

Включаем mock-режим

Для того чтобы сосредоточиться исключительно на написании самого API и не переключаться на написание кода, можно запустить сервер в mock-режиме:

swagger project start -m

Теперь сервер будет отдавать ответы, сгенерированные на основании описанных схем. Строку operationId можно не указывать. Так для /hello в этом режиме сервер вернет ответ:

{
  "message": "Sample text"
}

GET /books

Данный роут должен возвращать список всех книг. По поводу пагинации и разбиения выдачи на части здесь заморачиваться не будем - это тема для отдельной статьи.

Удаляем пример с /hello роутом и добавляем в paths следующие строки:

/books:
  x-swagger-router-controller: book-controller
  get:
    description: Return a books list
    responses:
      "200":
        description: Success 
        schema:
          type: array
          items:
            $ref: '#/definitions/Book'
      default:
        description: Error
        schema:
          $ref: "#/definitions/ErrorResponse"

Здесь мы указываем, что будем использовать контроллер book-controller. Определяем две схемы для ответа сервера:

definitions:
  Book:
    properties:
      id:
        type: string
      title:
        type: string
      author:
        type: string
      year:
        type: integer
    required:
      - title
      - author
      - year  
  ErrorResponse:
    properties:
      message:
        type: string
    required:
      - message

Эти определения располагаем в конце файла.

Сервер может вернуть нам либо список (type: array) книг со статусом "200", либо ошибку с обязательным полем message.

Попробуем протестировать наше API:

Вернулся автоматически сгенерированный ответ. Для поля, тип которого указан как строковый, возвращается строка "Sample text". Для целочисленного поля - число. Если данный вариант не устраивает, то в директории /api/mocks можно создать свой mock-контроллер book-controller и задать ссылку на его функцию в поле operationId.

POST /books

Создадим роут для добавления новой книги. Следом за get добавим следующие строки:

post:
  description: Add a new book
  parameters:
  - name: book
    description: Book properties
    in: body
    required: true
    schema:
      $ref: "#/definitions/Book"
  responses:
    "200":
      description: Success
      schema:
        $ref: "#/definitions/GeneralResponse"
    default:
      description: Error
      schema:
        $ref: "#/definitions/ErrorResponse"

Также нам нужно определить форму ответа сервера в случае успешного добавления книги. В definitions добавим:

GeneralResponse:
  properties:
    message:
      type: string
  required:
    - message

Попробуем протестировать:

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

GET /books/{id}

Теперь попробуем получить одну книгу. Для этого нужно создать новый маршрут /books/{id}, где id - идентификатор книги - параметр, передаваемый в самом url запроса. В блок paths добавим следующие строки:

/books/{id}:
  x-swagger-router-controller: book-controller
  get:
    description: Return Book by id
    parameters:
    - name: id
      type: string
      in: path
      required: true
    responses:
      "200":
        description: Success
        schema:
          $ref: '#/definitions/Book'
      default:
        description: Error
        schema:
          $ref: "#/definitions/ErrorResponse"

PUT /books/{id}

Данный роут используется для изменения книги с id, указанным в url запроса. Изменяемые параметры передаются в теле запроса.

put:
  description: Update a book
  parameters:
  - name: id
    description: Book id
    type: string
    in: path
    required: true
  - name: book
    description: Book properties
    in: body
    required: true
    schema:
      $ref: "#/definitions/Book"
  responses:
    "200":
      description: Success
      schema:
        $ref: "#/definitions/GeneralResponse"
    default:
      description: Error
      schema:
        $ref: "#/definitions/ErrorResponse"

DELETE /books/{id}

Последняя операция - удаление по заданному id. Копипастим следующий код:

delete:
  description: Delite a book by ID
  parameters:
  - name: id
    description: Book id
    type: string
    in: path
    required: true
  responses:
    "200":
      description: Success
      schema:
        $ref: "#/definitions/GeneralResponse"
    default:
      description: Error
      schema:
        $ref: "#/definitions/ErrorResponse"

Ну вот мы и спроектировали API для нашей библиотеки. Теперь можно приступать к написанию кода.

Реализуем функционал API

Для хранения нашей коллекции книг будем использовать MongoDB. Убедитесь, что у вас она у вас установлена и запущена.

Для работы с базой данных установим Mongoose ODM:

npm install mongoose -save

В файле app.js добавим зависимость:

var mongoose = require('mongoose');

и подключимся к базе books:

SwaggerExpress.create(config, function(err, swaggerExpress) {
  if (err) { throw err; }

  mongoose.connect('mongodb://localhost/books');
  ...

Ниже можно удалить условие проверки пути /hello. Для нас это больше не актуально.

Book model

В каталоге api создадим директорию models и разместим в ней файл с моделью книги book-model.js:

var mongoose = require('mongoose');
var Schema = mongoose.Schema;

var bookSchema = new Schema({
    title:  String,
    author: String,
    year:   Number
});

var Book = mongoose.model('Book', bookSchema);

module.exports = Book;

Book controller

В директории /api/controllers создадим файл book-controller.js:

var Book = require('../models/book-model');

module.exports = {
    getAll: getAll,
    create: create,
    find: find,
    update: update,
    remove: remove
};

function getAll(req, res) {
    Book.find({}, function (err, books) {
        if (err) {
            throw err;
        } else {
            res.json(books);
        }
    });
}

function create(req, res) {
    var newBook = Book(req.swagger.params.book.value);

    newBook.save(function (err) {
        if (err) {
            throw err
        } else {
            res.json({message: 'OK'});
        }
    });
}

function find(req, res) {
    var bookId = req.swagger.params.id.value;

    Book.findById(bookId, function (err, book) {
        if (err) {
            throw err;
        } else if (!book) {
            res.status(404).json({message: 'Book not found'})
        } else {
            res.json({title: book.title, author: book.author, year: book.year});
        }
    });
}

function update(req, res) {
    var bookId = req.swagger.params.id.value;
    var newBook = req.swagger.params.book.value;

    Book.findByIdAndUpdate(bookId, newBook, function (err, book) {
        if (err) {
            throw err;
        } else {
            res.json({message: 'OK'});
        }
    });
}

function remove(req, res) {
    var bookId = req.swagger.params.id.value;

    Book.findByIdAndRemove(bookId, function (err) {
        if (err) {
            throw err;
        } else {
            res.json({message: 'OK'});
        }
    });
}

Осталось в редакторе swagger.yaml прописать для каждой операции свой operationId, соответствующий названию функции в контроллере:

  # в /books:
    get:
      operationId: getAll

    post:
      operationId: create

  # в /books/{id}:

    get:
      operationId: find

    put:
      operationId: update

    delete:
      operationId: remove

и перезапустить сервер без mock-режима:

swagger project start

Скриншоты работы контроллеров и результаты ответов сервера уже не буду выкладывать. И так вышло многабукоф. Можете протестировать самостоятельно. Код данного примера можно найти на github. Комментарии приветствуются.

Disqus - это простой, удобный и бесплатный сервис, который позволяет добавить возможность комментирования и обсуждения на страницы вашего сайта. В данном блоге используется этот сервис. Также его я решил внедрить и в свой проект, написанный на AngularJS. Однако простого руководства я не нашел, а при добавлении сторонних решений столкнулся с некоторыми трудностями. Об этом и попробую рассказать в данной статье.

Поиск готовых решений

Гуглим. Находим несколько проектов на гитхабе. Некоторые отметаем из-за срока давности, некоторые из-за малого количества звезд. В итоге я остановился вот на этом решении. Инструкция по применению выглядит просто. Код тоже весьма лаконичен и представляет собой AngularJS директиву, которую в нужном месте требуется добавить в шаблон. В контроллере прописать пару строк конфига и все. Поехали!

Установка

1. Скачиваем файл dirDisqus.js,

• либо bower install angular-utils-disqus,

• либо npm install angular-utils-disqus

2. Добавляем этот файл в index.html:

    <script src="modules/components/dirDisqus.js"></script>
   

3. Добавляем директиву angularUtils.directives.dirDisqus в список зависимостей приложения:

    angular.module('app', [
        ...
        'angularUtils.directives.dirDisqus',
    ])
   

Использование

В шаблоне страницы, там, где должен находиться блок с комментариями, нужно вставить директиву:

 <dir-disqus config="disqusConfig"></dir-disqus>

А в соответствующем контроллере:

$scope.disqusConfig = {
    disqus_shortname: 'Ваше Disqus shortname',
    disqus_identifier: 'Идентификатор комментариев',
    disqus_url: 'url страниц с комментариями',
    disqus_title: 'Заголовок страницы'
};

На сайте Disqus добавляйте свой сайт. По адресу https://ВАШ_САЙТ.disqus.com/admin/settings/general/ в настройках смотрите ваш shortname.

Идентификатор комментариев - это строка, которая должна быть уникальна для данного трэда комментов. Хорошим вариантом будет, например, строка '/december-2010/the-best-day-of-my-life/'.

В качестве url используется полный адрес страницы, на которой располагается трэд: 'http://example.com/helloworld.html'.

Проблемы

Блок комментариев появился на странице и работает. Но в консоли выводится ошибка:

TypeError: Cannot read property 'disqus_shortname' of undefined

и ссылается на строки

if (!scope.config.disqus_shortname ||
    !scope.config.disqus_identifier ||
    !scope.config.disqus_url) {
    return;
}

Pull request на фикс этой ошибки висит уже 8 месяцев, так что, видимо, автор забил. Поэтому ручками. Добавляем перед этими строками условие:

if (typeof scope.config === 'undefined'){
    return;
}

Для ленивых коммит фикса.

Теперь все работает. Почти...

Еще обнаружил, что Prerender, который скармливает поисковым ботам снэпшоты страниц сайта, не отрендеривает блок комментариев. То ли Disqus не успевает загрузиться до момента снимка, то ли это из-за iframe и отсутствия скриптов в снэпшоте. Если важна индексация, и используется данный сервис, то на это нужно обратить внимание. А если найдете решение проблемы, то обязательно поделитесь со мной в комментариях.

С введением классов в TypeScript и ES6 в настоящее время существуют определенные сценарии, которые требуют дополнительных возможностей для поддержки аннотирования или модификации классов и членов класса. Декораторы позволяют, как добавить аннотации, так и использовать синтаксис метапрограммирования при объявлении классов и их членов. Декораторы предлагают удобный декларативный синтаксис для изменения формы объявления класса.

Декораторы еще не вошли в стандарт EcmaScript и на момент написания статьи находятся на стадии stage 1 proposal. Однако, несмотря на то, что они являются экспериментальной функцией и в дальнейшем возможны изменения, декораторы активно используются в Angular2. Ангуларовские @NgModule, @Component, @Injectable - это не что иное, как эти самые декораторы. Поэтому данную тему я решил не откладывать до момента официального вхождения в стандарт. Попробую разобраться хотя бы в том, как они работают, чтобы в дальнейшем было проще с изучением Angular2.

Для того чтобы включить поддержку декораторов в TS, нужно добавить опцию experimentalDecorators в командной строке:

tsc --target ES5 --experimentalDecorators

либо в файле tsconfig.json:

{
	"compilerOptions": {
		"target": "ES5",
		"experimentalDecorators": true
	}
}

Декоратор

Декоратор представляет собой объявление вида @expression, где expression - функция, которая будет вызвана во время выполнения с информацией о декорируемом элементе. Декорировать можно классы, методы, аксессоры, свойства или параметры.

Например, для декоратора @sealed (запечатанный) можно было бы написать функцию sealed:

function sealed(target) {
    // запечатываем target
}

Фабрика декораторов

Если мы хотим настроить, как декоратор применяется к элементу, мы можем написать фабрику декораторов. Это просто функция, которая может принимать некоторые параметры и возвращать декоратор.

Пример фабрики декораторов:

function color(value: string) { // это фабрика
	return function (target) { // это декоратор
		// делаем что-то с  'target' и 'value'...
	}
}

Композиция декораторов

Несколько декораторов могут быть применены к объявлению следующим образом:

• в одну строку:

    @f @g x
  

• в несколько строк:

    @f
    @g
    x
  

Несколько декораторов вместе будут работать подобно функциям в математике, т.е. так: f(g(x)).

Декораторы классов

Декоратор класса объявляется непосредственно перед объявлением самого декорируемого класса. Применяется к конструктору класса и может быть использован для наблюдения, модификации или замены определения класса.

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

Пример декоратора класса (@sealed) для класса Greeter:

@sealed
class Greeter {
	greeting: string;
	constructor(message: string) {
		this.greeting = message;
	}
	greet() {
		return "Hello, " + this.greeting;
	}
}

Для декоратора sealed можем записать следующую функцию:

function sealed(constructor: Function) {
	Object.seal(constructor);
	Object.seal(constructor.prototype);
}

Когда декоратор @sealed будет выполнен, он запечатает и конструктор, и прототип класса Greeter.

Декораторы методов

Декоратор метода объявляется непосредственно перед самим методом. Декоратор применяется на дескрипторе свойства для данного метода и может быть использован для наблюдения, модификации или замены определения метода.

Выражение для декоратора метода будет вызвано как функция с тремя аргументами:

1. Либо функция-конструктор класса для статического метода, либо прототип класса.

2. Название метода.

3. Дескриптор свойства для данного метода.

Примечание: если версия целевого скрипта ниже ES5, то дескриптор свойства будет undefined.

Пример использования декоратора @enumerable, который включает или отключает доступность метода при перечислении свойств объекта:

class Greeter {
	greeting: string;
	constructor(message: string) {
		this.greeting = message;
	}

	@enumerable(false)
	greet() {
		return "Hello, " + this.greeting;
	}
}

Реализация фабрики для декоратора enumerable:

function enumerable(value: boolean) {
	return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
		descriptor.enumerable = value;
	};
}

Декораторы аксессоров

Декоратор аксессора объявляется непосредственно перед объявлением самого аксессора. Декоратор применяется на дескрипторе свойства для данного аксессора и может быть использован для наблюдения, модификации или замены его определения.

TypeScript не позволяет применять декоратор и к геттеру, и к сеттеру. Декоратор должен быть объявлен для первого аксессора, указанного в коде. Это происходит потому, что декоратор применяется для дескриптора свойства, которое содержит и get, и set.

Выражение для декоратора аксессора будет вызвано как функция с тремя аргументами:

1. Либо функция-конструктор класса для статического члена, либо прототип класса.

2. Название члена.

3. Дескриптор свойства для данного члена.

Примечание: если версия целевого скрипта ниже ES5, то дескриптор свойства будет undefined.

Если декоратор аксессора возвращает значение, то оно будет использовано как дескриптор свойства для данного члена.

В следующем примере декоратор аксессоров @configurable применяется для членов класса Point:

class Point {
	private _x: number;
	private _y: number;
	constructor(x: number, y: number) {
		this._x = x;
		this._y = y;
	}

	@configurable(false)
	get x() { return this._x; }

	@configurable(false)
	get y() { return this._y; }
}

Реализация фабрики для декоратора configurable:

function configurable(value: boolean) {
	return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
		descriptor.configurable = value;
	};
}

Декораторы свойств

Все то же самое. Объявляется непосредственно перед объявлением свойства. Выражение для декоратора свойства будет вызвано как функция с двумя аргументами:

1. Либо функция-конструктор класса для статического члена, либо прототип класса.

2. Название свойства.

Если декоратор свойства возвращает значение, то оно будет использовано как дескриптор.

Примечание: если версия целевого скрипта ниже ES5, то возвращаемое значение будет проигнорировано.

Можно использовать декоратор для сохранения метаданных о свойстве класса:

class Greeter {
	@format("Hello, %s")
	greeting: string;

	constructor(message: string) {
		this.greeting = message;
	}
	greet() {
		let formatString = getFormat(this, "greeting");
		return formatString.replace("%s", this.greeting);
	}
}

Мы можем написать декоратор @format и функцию getFormat следующим образом:

import "reflect-metadata";

const formatMetadataKey = Symbol("format");

function format(formatString: string) {
	return Reflect.metadata(formatMetadataKey, formatString);
}

function getFormat(target: any, propertyKey: string) {
	return Reflect.getMetadata(formatMetadataKey, target, propertyKey);
}

Здесь @format("Hello, %s") - фабрика декораторов. Когда декоратор вызывается, он добавляет запись метаданных для свойства с использованием функции Reflect.metadata из библиотеки reflect-metadata (ниже про нее будет написано). Когда вызывается функция getFormat, она считывает метаданные и возвращает требуемый формат.

Декораторы параметров

Объявляется непосредственно перед объявлением параметра. Применяется для функции-конструктора класса или для метода.

Выражение для декоратора параметра будет вызвано как функция с тремя аргументами:

1. Либо функция-конструктор класса для статического члена, либо прототип класса.

2. Название члена.

3. Порядковый номер параметра в списке аргументов функции.

Декораторы применяется только для наблюдения за параметром, объявленным в методе.
Значение, возвращаемое декоратором параметра, будет проигнорировано.

В следующем примере декоратор параметра @required применяется к параметру name функции greet:

class Greeter {
	greeting: string;

	constructor(message: string) {
		this.greeting = message;
	}

	@validate
	greet(@required name: string) {
		return "Hello " + name + ", " + this.greeting;
	}
}

Декораторы @required и @validate можно описать следующим образом:

import "reflect-metadata";

const requiredMetadataKey = Symbol("required");

function required(target: Object, propertyKey: string | symbol, parameterIndex: number) {
	let existingRequiredParameters: number[] = Reflect.getOwnMetadata(requiredMetadataKey, target, propertyKey) || [];
	existingRequiredParameters.push(parameterIndex);
	Reflect.defineMetadata(requiredMetadataKey, existingRequiredParameters, target, propertyKey);
}

function validate(target: any, propertyName: string, descriptor: TypedPropertyDescriptor<Function>) {
	let method = descriptor.value;
	descriptor.value = function () {
		let requiredParameters: number[] = Reflect.getOwnMetadata(requiredMetadataKey, target, propertyName);
		if (requiredParameters) {
			for (let parameterIndex of requiredParameters) {
				if (parameterIndex >= arguments.length || arguments[parameterIndex] === undefined) {
					throw new Error("Missing required argument.");
				}
			}
		}

		return method.apply(this, arguments);
	}
}

Декоратор @required добавляет запись метаданных, которая помечает параметр как обязательный. Декоратор @validate оборачивает метод greet в функцию, которая предварительно выполняет валидацию аргументов. В данном примере также требуется установка дополнительной библиотеки reflect-metadata, о которой речь пойдет чуть ниже.

Метаданные

В некоторых примерах была использована библиотека reflect-metadata, которая является полифиллом для эксперементального metadata API. Библиотека не является частью стандарта ECMAScript (JavaScript). Однако, как только декораторы войдут в стандарт, эти расширения будут предложены для принятия.

Установить библиотеку можно с помощью npm:

npm i reflect-metadata --save 

Для того чтобы включить поддержку метаданных в TypeScript нужно добавить опцию emitDecoratorMetadata в консоли:

tsc --target ES5 --experimentalDecorators --emitDecoratorMetadata

либо в файле tsconfig.json:

{
    "compilerOptions": {
        "target": "ES5",
        "experimentalDecorators": true,
        "emitDecoratorMetadata": true
    }
}

Когда библиотека reflect-metadata импортирована, дополнительная design-time информация о типах становится доступной в рантайме.

Мы можем увидеть в действии это в следующем примере:

import "reflect-metadata";

class Point {
	x: number;
	y: number;
}

class Line {
	private _p0: Point;
	private _p1: Point;

	@validate
	set p0(value: Point) { this._p0 = value; }
	get p0() { return this._p0; }

	@validate
	set p1(value: Point) { this._p1 = value; }
	get p1() { return this._p1; }
}

function validate<T>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) {
	let set = descriptor.set;
	descriptor.set = function (value: T) {
		let type = Reflect.getMetadata("design:type", target, propertyKey);
		if (!(value instanceof type)) {
			throw new TypeError("Invalid type.");
		}
	}
}

Компилятор TypeScript внедрит информацию о типе с помощью декоратора @Reflect.metadata. Вот эквивалентный код класса:

class Line {
	private _p0: Point;
	private _p1: Point;

	@validate
	@Reflect.metadata("design:type", Point)
	set p0(value: Point) { this._p0 = value; }
	get p0() { return this._p0; }

	@validate
	@Reflect.metadata("design:type", Point)
	set p1(value: Point) { this._p1 = value; }
	get p1() { return this._p1; }
}

Уф. Довольно сложная тема. Поэтому сильно глубоко проникнуться не получилось. Получил лишь легкое понимание принципа работы декораторов. Соответственно и статья вышла обычным сухим переводом официальной документации. Если у кого-то есть замечания, предложения или более доступные для понимания объяснения и примеры по данной теме, то буду рад комментариям. Спасибо за понимание.

P. S. Нашел на хабре добротную статью про декораторы в TypeScript с интересными примерами. Советую к прочтению. Да прибудет с вами Сила ;)