#04: Конфигурирование статических веб-приложений

Добро пожаловать на Неделю 1, день 4 из #30DaysOfSWA!!!

За последние два дня мы увидели, как службы Azure Static Web Apps устанавливают стандартные действия CI/CD (для автоматизации рабочих процессов сборки/развертывания) и прозрачно настраивают приложение для доступа к API с минимальными затратами с нашей стороны во время настройки. Но что если мы хотим настроить процесс сборки или поведение приложения? Вот тут-то и может помочь знание опций конфигурации SWA.

Что мы рассмотрим

• Конфигурация: Концепции и файлы
• Настройка: Поведение приложения
• Настройка: Процесс сборки
• Настроить: Настройки окружения
• Упражнение: Изучите приложение с открытым исходным кодом, чтобы увидеть их в действии!
• Ресурс(ы): Ссылки для более глубокого изучения темы

Об авторе

Джозеф Лин — инженер-программист в команде Azure Static Web Apps Team в Microsoft. Посмотрите его проекты на @joslinmicrosoft на GitHub.

Концепции и файлы

Когда мы думаем о настройке Static Web App, у нас есть три потенциальные цели, которые мы можем настроить:

• Приложение: Используйте файл staticwebapp.config.json (расположенный в папке, указанной для app_location) для определения правил и свойств, которые настраивают поведение приложения, например, маршрутизацию, аутентификацию, работу в сети и многое другое.
• Сборка: Static Web Apps автоматизирует рабочий процесс сборки/развертывания с помощью GitHub Actions или Azure Pipelines, настраиваемых с помощью соответствующих YAML-файлов. Например, это будет файл .github/workflows/azure-static-web-apps-xxx.yml в вашем репозитории для GitHub Actions.
• Окружение: Иногда значения конфигурации могут быть известны только во время выполнения — например, строки подключения к базе данных. Используя переменные среды, вы можете обновлять значения во время выполнения без необходимости изменять код приложения, которое их использует. Переменные среды могут быть установлены в Azure Portal (для производства) или в локальных файлах настроек (для разработки).

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

Конфигурация: Приложение

Поведение приложения настраивается с помощью файла staticwebapp.config.json, расположенного в папке, определенной app_location. Вот подмножество свойств и их назначение:

• «routes» — массив объектов «route», каждый из которых может быть связан с правилами доступа («allowedRoles»), действиями («redirect», «rewrite») — и свойствами запроса («methods») и ответа («headers», «statusCode»).
• «navigationFallback» поддерживает приложения, которые полагаются на маршрутизацию на стороне клиента, предоставляя серверный маршрут отката, который обслуживает необходимую страницу, с фильтрами для контроля использования.
• «responseOverrides» позволяет возвращать пользовательский ответ вместо стандартных кодов ошибок HTTP для более удобного использования.
• «platform» задает специфические для платформы конфигурации, например apiRuntime для версии времени выполнения языка API.

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

{
  "routes": [
    {
      "route": "/profile*",
      "allowedRoles": ["authenticated"]
    },
    {
      "route": "/admin/index.html",
      "allowedRoles": ["administrator"]
    },
    {
      "route": "/images/*",
      "headers": {
        "cache-control": "must-revalidate, max-age=15770000"
      }
    },
    {
      "route": "/api/*",
      "methods": ["GET"],
      "allowedRoles": ["registeredusers"]
    },
    {
      "route": "/api/*",
      "methods": ["PUT", "POST", "PATCH", "DELETE"],
      "allowedRoles": ["administrator"]
    },
    {
      "route": "/api/*",
      "allowedRoles": ["authenticated"]
    },
    {
      "route": "/customers/contoso*",
      "allowedRoles": ["administrator", "customers_contoso"]
    },
    {
      "route": "/login",
      "rewrite": "/.auth/login/github"
    },
    {
      "route": "/.auth/login/twitter",
      "statusCode": 404
    },
    {
      "route": "/logout",
      "redirect": "/.auth/logout"
    },
    {
      "route": "/calendar*",
      "rewrite": "/calendar.html"
    },
    {
      "route": "/specials",
      "redirect": "/deals",
      "statusCode": 301
    }
  ],
  "navigationFallback": {
    "rewrite": "index.html",
    "exclude": ["/images/*.{png,jpg,gif}", "/css/*"]
  },
  "responseOverrides": {
    "400": {
      "rewrite": "/invalid-invitation-error.html"
    },
    "401": {
      "redirect": "/login",
      "statusCode": 302
    },
    "403": {
      "rewrite": "/custom-forbidden-page.html"
    },
    "404": {
      "rewrite": "/404.html"
    }
  },
  "globalHeaders": {
    "content-security-policy": "default-src https: 'unsafe-eval' 'unsafe-inline'; object-src 'none'"
  },
  "mimeTypes": {
    ".json": "text/json"
  }
}

Конфигурация: Build

Рабочие процессы сборки Azure Static Web Apps управляются либо GitHub Actions (в файле с именем что-то вроде .github/workflows/azure-static-web-apps-xxx.yml), либо Azure Pipelines (с помощью файла azure-pipelines.yml).

Основные настройки, с которыми вам необходимо ознакомиться, следующие:

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

Конфигурация: Окружение

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

Но где они определяются? Это зависит от стадии разработки:

• Локальная разработка: При разработке приложения вы можете использовать локальный файл настроек, который не отслеживается GitHub, чтобы не допустить утечки конфиденциальной информации. Azure Functions использует файл api/local.settings.json для хранения соответствующих настроек приложения — следите за специальной серией постов из двух частей на третьей неделе, где мы расскажем о файле локальных настроек, используемом Static Web Apps CLI для более простой и унифицированной локальной разработки.
• Постановка/производство: Вы можете определить и настроить эти параметры приложения в Azure Portal через браузер или с помощью Azure CLI (см. документацию az staticwebapp appsettings), чтобы создавать и управлять параметрами приложения. Они будут зашифрованы и скопированы в среду постановки и производства.

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

How-Tos: Смотрите!

Хотите увидеть конфигурацию поведения приложения в действии? Посмотрите эти два видео из серии Azure Static Web Apps: Tips & Tricks.

Упражнения: Исследуйте!

SWA Bank — это приложение Static Web App, разработанное в качестве решения для одного из проектов учебной программы Web Dev For Beginners.

Оно было недавно обновлено, чтобы отразить лучшие практики. Изучите конфигурационные файлы в проекте — и проверьте, понимаете ли вы, как они настраивают поведение приложения и процесс сборки. Затем вернитесь к нему на третьей неделе, когда мы будем обсуждать инструменты разработчика, чтобы понять, как настраиваются и используются локальные параметры с помощью инструмента Static Web Apps CLI (swa) для локальной разработки.

Полезные ресурсы

1. Обзор конфигурации
2. Конфигурация приложения: staticwebapp.config.json
3. Конфигурация сборки: Actions или Pipelines YAML
4. Конфигурации окружения: Для бэкендов
5. Настройка параметров приложения
6. SWA Bank Repo — проект Static Web Apps для изучения и обучения.