Разработка Azure Functions на местах: выправленне частых прынцыпоў зламу

Заканчыце борацца з эмулятарамі, несправнымі настройкамі та загадковымі памылкамі — гэта тое, што дзейсна працуе

Якщо простая команда func start калі-небудзь вывела на экран цэлы столбец чырвонага тексту без жадных паведамленняў, вы зусім не ўнікальны прыклад. Azure Functions працуе чудова, калі яго розмішчаюць у хмаре, але ўскладнення з яго паводлівым запускам на вашай сабе лептопе змушаюць багато разработчыкаў витрачаць цэлы апошні дзень без жадных прычын.

У гэтым кяліку не прабуецца показаць выгляджаючую версію „локальнага развіцця“ для маркетынгу, а ўместа таго рассказваецца пра тое, што на самай практыцы йдзе не так, прычіны гэтага та практычныя способы рашэння, выведзеныя з тых проблем, з якімі разработчыкі сталкаюцца рэгулярна.

1. Чаму локальная розработка Azure Functions здаецца сложней, чым трэба

Зьвяржэнне Azure Functions на вашай сабе машыне — гэта не проста експаняція калеку коду. Фактычна, вы ствараеце цэлы рунтайм у хмаре на месца: хост для Functions, налаштаванні запуску, очаквальныя лісты для зберагчыка, а інодзе таксама механізмы аутентыкацыі, пры чым не падчыняецеся ніяк Азурэю. Для таго, каб усё працавало правільна на кожным кроку, патрабуюцца тры окремыя элементы:

• Core Tools CLI ад Microsoft, які выступае заменнікам рунтайма Functions, які зазвычай доступны через сам Азурэй
• Яка-небудзь мова програмавання і SDK, на якіх напісаны вашы функцыі — чы то Node.js, Python, .NET, Java або PowerShell
• Azurite, маленькі емулятор, який імітуе Azure Storage, таму очаквальныя лісты, блобы і таблицы працуюць без рэальнага акаунта ў хмаре

Якщо хоць яка-небудзь з эйх трохі падзе няправильная версія, будзе паслабна налаштаваная або проста не будзе увімкнутая, вы страждзеце ад звычных проблем: функцый, якія адмовяюцца працаваць, паведамленняя „Акаунт сховішча не знайдзены“ або хост, які тыхо выключаецца. Калі вы зрозумеете, як гэтыя тры элементы завісяць адзін ад другога, большая частка разчароўвання знікне.

2. Што на самай працэ трэба установіць

Перш чым прыступаць да коду будзь-якай функцый, пераканаецеся, што у вас ёсьць наступнае:

• Azure Functions Core Tools — інструмент у командной лініі, які запускае хост Functions на вашам комп’ютеры

npm install -g azure-functions-core-tools@4 --unsafe-perm true

• Языковы рантайм, які падходзіць да вашай цэльвай версіі Azure (напрыклад, Node.js 18/20, Python 3.9–3.11 або .NET 8)
• Azurite — эмулятор, які заменяе Azure Storage на местных сэрверах

npm install -g azurite

• VS Code, які выкарыстоўваецца разам з расшырэнням Azure Functions — гэта не ўмовна, але гэта значна спрыяе адлучэнню бягаў і стварэнню структуры проекту

Швайны пераконтальнік, які варта адрабаты прытаму, пераходзячы да наступных крокаў:

func --version
node --version    # or python --version / dotnet --version

Разлік версій межа Core Tools і рантаймам вашага языка ўваходзіць у числе найчастэйшых і найскрытнейшых прычын, калі ўсё працуе на адной машыне, але не працуе на іншай.

3. Стварэнне вашага першага локальнага Function App

Выкарыстоўваючы CLI, створыце абсалютна новы проект:

func init MyFunctionApp --worker-runtime node
cd MyFunctionApp
func new --name HttpTriggerExample --template "HTTP trigger"

Выкананне гэтага коду стварыць структуру папак, у якой будуць host.json, local.settings.json і папка з кодам вашага трыгера. host.json адпрацоўвае настройкі для всьго хоста, такія як спосаб логавання, пакеты расширэння і таймауты. local.settings.json — это файл, прызначаны толькі для вашага комп’ютера; ён вызывае достатнюю колькість плутання пад першым запускам, таму ёму трэба спецыяльнае поясненне.

4. Файл local.settings.json — што ён робіць і чаму він ускладняе розумэнне

Этот файл зберагае вашы локальныія зменныя сераўісу і стрэлкі з’язку. Ён ніколі не выкладываецца на Azure; ўсё його призначэння — толькі локальная настройка.

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "node"
  }
}

Две часта падзейваюцыяся памылкі пояснююць большасць скарг на тое, што «хост нават не запускаецца»:

1. Забывчыця ўстановіць AzureWebJobsStorage. Практычна кожная категорыя трыгараў — Timer, Queue, Blob — завісіць ад з’єднання з системай зберагача дадзеных, нават пад час локальных запускаў. Выкорыстоўванне параметра UseDevelopmentStorage=true направляе хост на Azurite заместо рэальнага акаунта Azure Storage.
2. Неправільная настройка параметра FUNCTIONS_WORKER_RUNTIME. Калі ён не супадае з мовай, якой вы фактычна выкарыстоўваете (node, python, dotnet, java, powershell), хост проста не заваносіць вашы функцыі, часта паказваючы нечыткую прычыну абярэння заместо чыткага паведамлення пра несупаданне версіі рантайму.

5. Azurite: ваш эмулятор локальнага зберагача дадзеных (і чаму яго нельга прыхіліць)

Azurite заменяе Azure Storage для всіх програм, які працуюць локальна, імітуючы очэкваннія, блобы та таблицы працэйна вашам комп’ютере. Адхілянне гэтага крока ёсць галоўной прычынай адхэлакоў StorageException чы рашчарованых з’яўленняў, калі толькі пачынае працаваць трыгар з очэкваннем чы блобам.

Запусціце яго ў спецыяльным вікні тэрміналу перад тым, як запускаць ваш аплікэнт функцый:

azurite --silent --location ./azurite-data --debug ./azurite-data/debug.log

Якщо вы воліяце працаваць у VS Code, расширэнне Azurite дазволяе запускаць эмулятор чераз адну пункт у палітрэ команд, без неабходнасці выкорыстоўвання окремага тэрміналу. Незалежна ад выбранага спосабу, трэба, каб ён працаваў усю вашу сесію — дужа легка забыць, што ён не актыўны, і пасвятіць дзесять хвілін на пошук паведамлення «з’яўленне з’язку не выйшла», якое на самай працэ проста означае, што эмулятор так і не быў запусцаны.

6. Запуск і тэставанне функцый, якія запускаюцца па HTTP-трыгары

Калі Azurite будзе запусцены, стартавайте вашу функцыйнальную аплікацыю:

func start

У вашай тэрмінале будзе паказана локальная URL кожной функцыі, прыблізна так:

Http Functions:
    HttpTriggerExample: [GET,POST] http://localhost:7071/api/HttpTriggerExample

Якщо це запит типу GET, вы можете атакаваць яго за дапамою curl, Postman чы рабочага прыградзіка:

curl "http://localhost:7071/api/HttpTriggerExample?name=Dev"

Якщо заместа адказу вы бачыце тышу, шукайце зіткненне порта — застаўшыся процес func start чы інша аплікацыя можа вже выкорыстоўваць порт 7071. Заканчэнне непатрэбных процесаў Functions (шукайце func у Менеджары заданняў чы запускайце pkill -f func на macOS/Linux) зазвычай негаюць гэту проблему адразу.

7. Тэставанне не-HTTP трыгероў локальна (Timer, Queue, Blob, Service Bus)

HTTP-трыгеры — это просты случай. Для іншых трэба больш падготовкі:

• Трыгеры з таймерам запускаюцца аўтаматычна за схемай CRON як толькі запускаецца хост, без дадатковых выказоўкі. Чым скорэ працаваць з імі, можна тымчасова дадаць "RunOnStartup": true у вызначэнне трыгара, ўнаследкі чаго ён запускаецца негайна.
• Трыгеры з кялей выклікаюцца толькі тады, калі ў кяле, якая падтрымвана Azurite, ёсць рэальныя паведамленні. Можна дадаць тэстовае паведамленне через Azure Storage Explorer, які вяршыць зв’язак з Azurite так сама, як і з рэальным рахункам для зберагачвання, або за дапамогою розширэння для зберагачвання Azure CLI, прызначанага для вашай локальнай стрэлкі з’ўязку.

Трыгары Blob знаюцца працаваць з запазджэнням на локальным рэзынгу, адколькі запытання пра новыя блобы не выкалываюцца мгновэнна — чаканне кількох хвілін не ўскладненне, як толькі вы не павяржываецеся на трыгары Blob, базаваныя на Event Grid. Такія трыгары паслаба імітуюцца на локальным рэзынгу і зазвычай краща пераверыць на рэальным, недорогім ресурсе Azure.

Трыгары Service Bus і Event Hub зазвычай вообща не можна імітаваць на вашам комп’ютере. Для такіх варыянтав вашы лепшы варант — налагодзіць звязок з рэальным, недорогім ресурсам разработчыка Azure пад час локальных тэстаў, прычаму ў файле local.settings.json павінна быць задана аднойчынае значэнне для з’єднання.

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

8. Адлагоджэнне ў VS Code

Хтоць тут местныя настройкі пачынаюць справа прыносіць корысть. Калі буда установленая расширэння Azure Functions:

1. Ачыніце папку вашага проекту ў VS Code.
2. Разместіце точкі абаранення там, дзе яны ўам патрэбны, у коде-трыгеры.
3. Нажміце F5 — VS Code сама займаецца стварэнням проекту, запускам Azurite, якщо гэта налажана, запускам хоста Functions і падключэнням дебагера, без жадных ручных крокаў.

Автаматычна створаныя файлы .vscode/launch.json і tasks.json координуюць усё гэта за кулісамі. Якщо точкі абаранення не зупіняюць выконванне, пераканайцеся, што настройка preLaunchTask у файле launch.json дэйсна перзастраюе ваш код пры запуску хоста — застарэлы варіант коду ўсё часта яўляецца прычыной таго, што точкі абаранення, здаецца, ігноруюцца.

9. Частыя памылкі і спосабы ўсунення іх

Гэты конкретны элемент вызывае больш плутання у разработчыкаў, чым будь-які рэальны дыфект у самай средзе выканання Functions. Файл local.settings.json навмысна не включаецца у пакет развяроць з мэтай абараннення, таму якія-небудзь секрэтныя даны або значэння настройкі, якія там зберагаюцца, не будуць автаматычна перавозіцца разам з вашым дапрынтам у Azure — іх трэба дадаць окалічна, чыраз адваротны портал Azure або за дапамой інструментаў CLI/pipeline.

10. Выкананне Functions локальна з Docker

Якщо ваша команда хоча, каб локальная та прыметная среды былі абсалютна ідэнтычныя — або якщо вам трэба пераканацца ў правільнасці спецыяльнага контейнера Linux — Azure Functions таксама праследжвае варыянт на адваротнах:

func init MyFunctionApp --worker-runtime node --docker
cd MyFunctionApp
docker build -t my-function-app .
docker run -p 7071:80 -it my-function-app

Этакі падход дае большую навантажэння, чым простая функцыя func start, але ён пазбегае цэлага класу проблем типу „всё работае на маймашыні“, бясконечна важлівага для команд, якія выкарыстоўваюць спецыяльныя контейнеры або патрабуе ўзгоднасці на рэвлюсе з тым, што працуе ў працоўнай средзе.

11. Правільнае кераванне секрэтамі і зменнымі сераўысу

Не додаюце local.settings.json у систему керавання кодам. Ён прызначаны для зберагачэння рэальных стрынгаў з’яносу пад час разработкі, а проекты на основе шаблонаў за замовчаннем выключаюць яго з git — пераканайцеся, чытаўшы ваш .gitignore. Калі працуеце ў команде:

• Раздзеляйце адчыснутую версію, напрыклад local.settings.json.example, заполненую тэмпаратнымі значэннямі заместо рэальных секрэтав.

Калі вы перайдзеце за межы чыста локальнага тэставання, для всіх чутлівых дадзеных выкорыстоўваеце кансэнтры Azure Key Vault.

У CI-пайплайнах перадавайце настройкі через зменныя аптэнатуры, а не заўважайце рэальны файл налашоўкаў у репазітарыі.

12. Найкращыя практыкі для гладкага локальнага цыклу разработкі

• Запускайце Azurite раней, чым запускаеце хост Functions — порядак мае значэнне, адколі дзеянні-трыгеры часта пераглядаюць схованку як толькі запускаюцца.
• Узначыце версію Core Tools, якую выкарыстоўвае ваша команда, будзь то ў документах чы ў скрыпцы налашоўкі. Несувярэннасці версій межы апаратамі ёсць тыха, але рэальная перакантаванне для продуктыўнасці.
• Заўжды запускайце func start --verbose, калі сталося проблема з запускам — стандартны рэжым логавання часта масківае асалодныя прычыны.
• Паўтарна запускайце хост кожны раз, калі правяліце змены ў host.json або local.settings.json; жадны з гэтых файлаў не перагружаецца падчас функціі гарячага перагружання.
• Зберагачыце ресурс нізкага рангу ў Azure для типаў тригераў, такіх як Service Bus або Event Grid, якія не можна цалком рэплікацыяваць у локальным эмуляторы.

Заключныя меркі

Локальная разработка для Azure Functions не ў самай суцэльнасці неякшая — яна проста складаецца з калькі элементаў, якія ўсе павінны заставацца сувязанымі, і большасць інструкцый праходзіць поважліва праз тыя часткі, якія вызываюць справжнія проблемы: правильная эмуляцыя сховання, несувязкі ў часе выконання працоўнікаў, а таксама межы таго, што можа імітаваць ваш локальны наладжэння, і чаго не можа. Калі гэтыя тры аспекты стануць зрозумелымі, func start перестане здавацца рызыкаваннем і стане проста ўжо адной з звычайных команд.

Якшто ўсё-такі існуе адна прычынка, за якую варта пераняць што-небудзь з усьога цаго, то гэта: завжды пераканайцеся, чы рэальна Azurite працюе, перш чым пачынать рашанаваць будзь-што інше. Гэта адна-едынственная недбаласць таямніча витрачае больш часу, чым будзь-яка справжня памылка ў коде вашай функцыі.

Спадневана літэратура

• Node.js Command Reference for Local Development and Production Servers — Кансэльвабельны справак з командамі, які охопляе карыстоўванне версіямі Node.js, менеджэрамі пакетаў, налажванне сяродавысці, адлучэнне бягункоў, PM2 і развёртвання Linux без перыядоў.

Устранэнне бягоў у обробцы адзінакоў Async/Await у коде Node.js для працы ў рэальных умовах — Дазвольце вам дакладна пазнакоміцца з пяцьма распашчастыміі бягамі у обробцы адзінакоў async/await у JavaScript і Node.js, якія спрычыняюць тыхія аберання і суперканкурэнцыю, а таксама з конкрэтнымі спосабамі ўстранэння.

Устранэнне бяга з нехваткай бібліятэкі libssl.so.1.1 у Prisma на Alpine Docker — Дазвольце вам дакладна пазнакоміцца з прычынамі, чырэз якія двухцелавы механізм запытоў Prisma зламваецца на образах Docker, створаных на базе Alpine, з-за нехваткі бібліятэкі libssl, і з спосабамі яго абоўсюднага устранэння.