Запуск API NestJS і Prisma без памылак у зв’язках чыста P1001

Практычна ўсе функцыі бэкенду, якія команда стварае пазней — ад аутентыкацыі да мульті-тэнантнасці і контролю доступу на адміністратыўных ролях, — базуюцца на рэзультатах першых кальканіяў праекта. Якщо на пачатку зменныя сераўіса, з’язак з базай дадзеных, адносы схем і процесы міграцый будуць нараблены некачэнна, кожны пазнейшы запрос будзе спадчыцаваць гэты бядлівы стан. У гэтым кераванні показана процедура стварэння API на базе NestJS, падтрымванага Prisma і PostgreSQL; апісаны тры проблэмы, якія часта заважаюць досягнуць першага этапа, і даны чарткі для выявлення моменту, калі фундамент праекта справжнья ўсталены.

Як выглядае завершаны процес стварэння базы

Дапамагае падзеяць мету перш чым прыступаць да роботы з CLI. Процес стварэння базы ўважаецца завершаным, калі пераглядач можа клонаваць галузь і падтвердзіць наявнасць усіх следуючых элементаў:

• Програма NestJS, напісаная на TypeScript, якая запускаецца без будзь-яких адмоў

Prisma, які з’єднаны з базайтом дадзеных PostgreSQL

Канфігурацыя, яка чытаецца з зменных сэрאдавішча, а не з жорсткаяк закодаваных значэнняў

Пачатковы набор модэляў дадзеных, якія адбіваюць сферу прыменення

Міграцыя, якая можа быць застосаваная да порожней базайна дадзеных

Фокусаваныя запросы пра з’еднанне, якія рэшта команды можа пераглядзець і з’еднаць

Абмежэння спецыяльна ўзначаныя: NestJS і Prisma як едынственныя фрэймворкі і ORM, PostgreSQL як база дадзеных, а таксама існуючыя стандарты команды для канфігурацыі і Git.

Набор адзінакоў

• Фрэймворк і мова: NestJS з TypeScript
• Даступ да дадзеных: prisma (CLI) і @prisma/client (генераваны кліент для запытаў)
• Канфігурацыя: @nestjs/config
• База дадзеных: локальная інстанцыя PostgreSQL
• Парабяранне: Prisma CLI, а таксама прыгледчык або API-кліент для запуску канцэнтраў

Стварэнне канструкцыі проекта

Спачатку створыце новую аплікацыю за дапамой Nest CLI, пасля чаго дадаце Prisma і ініцыялізуэце яго ўнутрь проекта. Ініцыялізацыя стварае катэгорію prisma/ для схемы і міграцый, тады как код аплікацыі застаецца ў катэгоріі src/.

Далей створыце файл .env, які мае змест DATABASE_URL — стрэлку з’яўлення да PostgreSQL, якую чытае Prisma. Завантажыце настройкі через модуль @nestjs/config, ўжо каб аплікацыя брала значэння з сераўісу, а не з літэралав, розмешчаных у кодзе. Бяжыце пазірэць, каб файл .env быў уключаны ў .gitignore; комітаванне рэальных аутентыфікацыйных данных у першым жа PR — гэта простая, але некамфортная памылка.

Перад тым, як пісаць будзь-яе модэлі, пераканайцеся, што Prisma справды можа з’яўіцца да базы дадзеных. Якщо вы хочаце болей дакладнаў пра сам Prisma, адзіно, пагляньце на інструкцыі з налаштавання Prisma 7 з PostgreSQL у проекте на TypeScript Node.js, а таксама пераканайцеся ў актуальных документах Prisma ў паводзе з деталямі, спецыфічнымі для кожнай версіі.

Модэлюванне першых аб’ектаў

Для продукту з калькуляцыяй па аб’ектах-арендніках разумныя початковыя схемы складаюцца з чатырох модэляў:

• Tenant — аб’ект, які представляе організацыю, якая выкарыстоўвае систему
• User — аб’ект, які представляе аднасобу, якая заходзіць у систему
• Role — аб’ект для базовага прызначэння ролей у межах аб’екта-арендніка
• Invite — аб’ект для запрошэння новых корыстувачаў да аб’екта-арендніка

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

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

Дадаванне канцэнтра па стану

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

Тры памылкі, якія часта блакуюць першы этап

Prisma адхоўляе зв’язак без працоўнага поля

Сімптамы: адзначаецца неяксунасць падтверджэння схемы, пры чым лічыцца, што у зв’язку не ёсць адпаведнага поля.

Прычына: Prisma выклекае, каб зв’язкі былі заданы ў обох моделях. Якщо User апісвае Tenant, але Tenant не мае поля, якое б перыявляла його корыстувальнікаў, то з пазырку Prisma схема є непূরнай.

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

P1001: нельга дасягнуць сервера базы дадзеных

Сімптамы: Prisma адзначае код каштоўкі P1001 і не можа з’яўіцца ў зв’язку з PostgreSQL.

Прычына: зазвычай адна з двух. Аль сервер PostgreSQL не працюе, аль порт у DATABASE_URL не падаець пад той порт, на якім праслухоўвае сервер.

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

Запрос прыемкі, який, здаецца, вычыраюе все

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

Прычына: каміт быў зданы з неправильнага стану Git, таму разлік паўтарае ўсё не тое, што было запланавана.

Рашэнне: у замест на прабуюць васпрацаваць заплутаную історыю змян, стварыце новы галузь на правільной базе і застосавайце толькі тыя змяны, якія былі запланаваны. Выконанне команды git status і анаіз команды git diff па стану цялевай галузі пры выкладцы дапамагае якомога раней з’явіцься і вылучыць такія працынкі.

Перакананне настройкі

Перакананне должна быць проста і можліва да павтарэння:

• Выконайце npx prisma migrate dev і пераканаўцеся, што міграцыя выконваецца без адных бядаў
• Запускайце сервер NestJS
• Ачыніце адресу /health у браузеры або кліенте API і пераканаўцеся, што адпаведзае статус OK

Калі міграцыя выконваецца без працынкаў, а эндпункт стану дае адпаведзенне, фундамент готовы для наступных функцый.

Ключавыя выводы

• Спрыяйце бутстрэпу як даўальнай часткі з чыста вяліканутымі критэрамі адзначэння, а не як тымчасовай структуре.

Заявіце кожную асоціяцыю Prisma з обох бакоў і дазвольце prisma format падтрымваць схему у порядку.

Калі бачыце P1001, пераканайцеся, што PostgreSQL працюе і што порт у DATABASE_URL правільны, прычаму да іншага дэбагавання.

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

Маленькія, сфокусаваныя запиты на зміны з чыстай історыяй ўчаствуюць у інжынерскай роботе, а не ўсёлякія додатковыя крокі.

Спаднёе чытанне

• Размешчэнне NestJS на Bun і Prisma 7 у Cloud Run без памылак падчас кампілявання — рабочы пайплайн GitHub Actions для выкладчэння дапрыемку NestJS на Bun з Prisma 7 і Neon у Cloud Run, а таксама спасаблівання проблем з Docker і падключэннямі, якія створююць труднасці у командах.
• MovieVault Walkthrough: A Watchlist API With Express 5, Prisma 7 і JWT — спефікацыя завдання для роботы з усім стэкам з часовым лімітам, а таксама ўскладнення для бэкэнду на Express, Prisma і JWT, з прыміткамі па адзінаковай перагляду ў чысце перакананняў у правах на власнасць, каскадных адпаведзяў і обробцы памилак.