Пасткі падчынення Next.js 16: стандартныя паралельныя маршруты і мідлвэрк для проксі

Большая частка зусиль падае пры апгрэйд Next.js 16 на змяну асінхронных параметраў params і searchParams, таму што гэта спрычынае серьозныя проблемы ў всіх частках праграмы. Две іншыя, менш выразныя змяны ў маршрутах таксама заставляюць зважна ставіцца да ўсіх аспектаў: тепер для паралельных слотаў маршрутаў неабходны явны файл default.js, а перехопленне запытоў пераходзіць з middleware.ts у новую практыку proxy.ts. Жадна з гэтых змян не спрычынае проблем у сторунках, якімі вы корыстаецеся ўжо кожны дзень, і самэ гэта прычына, чаму яны застаюцца непазначанымі пад час тэставання. У гэтым кяле пояснююцься обе змяны, прычыны ўпоследжання ўсвядомлення іх проблем, а таксама даўаецца чартак для перагляду, які трэба выкарыстоўваць пры падготовцы да апгрэйду.

Для паралельных слотаў маршрутаў неабходны файл default.js

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

У Next.js 16 ад кожнага ўзорка ачакуецца наявнасць файла default.js. Гэты файл ёст кантэнт, які Next.js адрасавае для ўзорка, калі текущы URL не мае болей спецыфічнага падтрымкі. Без такога файла навігацыя, якая прыводзіць да такой комбінацыі, вяртае код 404 замест таго, каб грацыязна перайсці на альтернатыўны варыянт; як зазначаецца ў прымітках да апдэйта Next.js 16, сам процес зборкі можа адмовіцца працаваць, калі ўзорак не мае стандартнага файла, таму трэба паконтролаваць точную працэзгуласць для вашай версіі. Панель керування з ўзоркам каналу выглядае так:

app/
  dashboard/
    @feed/
      page.tsx       ← the "active" state for this slot
      default.js      ← required fallback when no more-specific match exists
    layout.tsx
    page.tsx

Зазвычай фаллбэк не патрабуе многа. Адразыўванне null закрывае этот слот, а компонент для стану «пусто» працюе тады, калі хочаце, ўбачлівасць панелі застаўся:

// app/dashboard/@feed/default.js
export default function Default() {
  return null;
}

Чаму нехватка стандартнага рашэння пазірае пазней

Пад час разработкі вы пераважна пераходзіце межа станамі, якія створылі і працавалі з імі, і ўсе яны падходзяць да чагось у кожным слоте. Проблема выяўляецца, калі корыстувач прабывае дасягнуць камбінацыі, якой ніхто не пробаваў: глыбокія лінкі, адновэшчанне стороніцы на вярстанай URL, або маршрут, які існуе для галоўнага кантэнту, але не для ленты новых паведамленняў. Полны завантажэнне стороніцы не можа перадаўжыць пярэйшны стан слота, таму Next.js патрабуе файл default.js, каб знать, што адразыць. У практыцы гэта значыць, што код 404 часта адзвяртае запаноўваючыся кліент у працэсе эксплуатацыі, а не ў часах разработкі. Дадаванне файла для кожнага слота, нават калі думаеце, што яго ніколі не будзе выкарыстоўваць, — это недорога страховка.

З middleware.ts да proxy.ts

Другая змяна стосуецца перехаплення запыткаў на ўзначальнай ступені. Next.js 16 вводзіць proxy.ts як стандарт для логіки, яка раней была ў middleware.ts, і старая назва файла поступова знімаецца. На момент напісання міграцыя включае перэименаванне файла і яго экспортаванай функціі, прычаму проксі плануецца запускать на средовышчы Node.js; пераканайцеся ў чынный даследжэнні ўсіх деталяў і офіцыяльным кодамодзе, які выкаанаў механічную частку.

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

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

Абсалютная замена зместу з кантэкста middleware.ts на proxy.ts прыяжджае да таго, што кожны элемент логікі будзе дзейсціць аднакова па новыя правілы. У замене трэба дакладна разглядзець, калі саме файл выканае своі задачы, і окрема пераканаліцца ў кожной з яго адпаведальнасцяў:

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

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

Две незв’язаныя змяны з аднаковым патэрном неудач

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

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

Чарт аудыту для апгрэйда

Перш чым заявіць, што апгрэйд Next.js 16 завершаны, пераканайцеся ў наступным:

1. Кожны паралельны слот маршруту мае файл default.js. Абшукайце у каталозе app/ папкі, якія пачынаюцца з @, і пераканайцеся ў кожнай з яных.
2. Логіку мідлвэра было пераглянуто ў спадарожчыне з proxy.ts, адзіну абавязак за раз, не перайменаваючы яе і не прыймаючы, што яна ідэнтычная.

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

Незвычныя шляхі навігацыі, такія як глęбокія лінкі, перзапуск стораніцы на вложаных URL-адрэсах і маршрутах, да якіх ніколі не дасягнуць звычным клікам, былі спецыяльна перапрацаваны, адколі самэ там ховаюцца паралельныя коды 404.

Чаму панелі керавання з мнагацяльным викорыстоўванням несу найбольшы рызык

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

Памылка тут рэдкая калі не вырабляе явных наследкав. Узамест адзінай сторонней сторунки вы атрымляеце звесткі пра тое, што адны корыстувач на час побачыў данні іншага корыстувача, што ёсць прыблізна такім жа сер'ёзным інцыдентам, які толькі можа быць у продукцыі типу SaaS. Мнагаслоўная захоўка дапамагае: нават калі проксі адпаведзае на запит корыстувача, доступ да даных у серверных складовых і прыемніках маршрутаў должны знову пераканацца ў прыналежнасці даных корыстувача, а не павержацца толькі значэнням заголовка, які надаўся зверху. Для кэшавання на аднойчыні таксама неабходна адпаведная аберагаўка, адтолькі ключы кэшу павинны включаць інформацію пра корыстувача; стаття на Next.js 16 use cache і рэвалідацыя на аднойчыні розглядае гэты аспект.

Частыя запытанні

Чы глуха памылка пад час прыхоўдзення default.js?

Не абсалютна. У версіях, які выкарыстоўваюць гэтае правіла, з’являецца код 404 або памылка падчас складання, але толькі для шляхоў навігацыі, якія выходзяць да відсутняй альтэрнатывы. Паколькі памылка з’яўляецца далека ад таго месца, якое ёй стала прычыной, ее лёгка спачатку спылучыць з загальнай памылкі маршрутацыі, якщо толькі не ведаць пра гэтыя змены.

Можна ўсё ж выкарыстоўваць middleware.ts нараз?

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

Як швыта знайсці слоты без default.js?

Абсалютнае шуканне папак у app/, назвы якіх пачынаюцца з @, і выведзенне тых, які не маюць файлу default.js (альбо default.tsx). Одна пераглядка за дапамою функцыі шукання файла ў вашым рэдаггере або короткі каманда shell дапаможаюць знайсці всі такі папкі.

Заключныя заўважэнні

Змены ў Next.js 16, якія з наібольшай верыгоднасцю можу спакусіць проблемы, — это не тые, якія наражаюць на аберанцію стандартны ход роботы. Паралельныя слоты маршрутаў без стандартнага файлу, а таксама спешна перэименаваны проксі, часам праходзяць практычныя тэсты, але зазнаюць невыкарыстання ў крайніх ситуацыях, інодзе прыводзячы да проблем з безпекай. Да кожнага слота трэба дадаць стандартны файл, пераглянуць логіку перехоплення задач па аднаце, і выдзеліць рэальны час на тэставанне маршрутаў, якіх ніколі не пераглядаюць пад час звычайных тэстаў.