Усередзіне DenoX: маршрутызацыя файлоў, фрагменты MVC і контракт AGENTS.md у Deno

Падключэнне сервера рэдкая часць ценнае часткі проекту з адзюнктыўной часткаю; важлівыя — это функцыяны, якія реалізуюцца. Rails, Laravel і Next.js прывабілі развівачаў тым, што самі прымалі рашэнні па тэхнічныяй структуре, а Deno, завдзяк сваім правам на безпеку за замовчаннем, натыўнаму TypeScript і вбудоўваным інструментам, ёсць ідэяльным кандыдатам на аднаковае падходжэнне. DenoX — это фреймворк цэлага стаку на адной базе з Deno, створаны на Hono, які прагчае стаць самэй такой упорнай прымусовай шаром. Яго адказы на часта з’яўляюцыяся структурныя запитанні, а таксама спосаб, якім ён іх фіксуе для агентаў кодавання на базе AI, — это шаблоны, якія можна перадаўваць у будзь-якай адзюнктыўной частцы на базе TypeScript.

Праслойка з упорнай позыцыяй, якая заполняе прасоў

Deno 2 прынёс сабе сумеснасць з npm, рэйстры JSR, вырашаную стандартную бібліятэку і адзін бінарны файл, які можа выканаць перагляд коду, форматаванне, тэставанне, кампіляванне і пакетаванне (дапаможыцца стацыяй пра тое, як Deno 2.x рашыў проблемы сумеснасці з Node і вялікага колькаства інструментаў для дапамогі). Тое, чаго не можа даць просты рантайм, — это адностайна думка па пытаннях, пра якія спарчваюцца всі команды: дзе павінна знаходзіцца бізнес-логіка, як адчыняюцца пра бягі, хто перакантролюе настройкі і дзе рэалізуе лімітаванне частоты запытаў.

DenoX адпавядае на яны адной прынцыпам: прынятныя стандарты парадуецца над настройкамі, якія перакантролююцца за дапамогою інструментаў. Документаваныя стандарты могу змініцца; тые, якія перакантролююцца ў процесе CI, застаюць незменнымі.

Маршрутызацыя на адной заснове файлоў за дапамогою створанай і зберажанай табелі

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

src/frontend/pages/
├── index.ts            →  /
├── about/main.ts       →  /about
├── users/main.ts       →  /users
└── posts/[id].ts       →  /posts/:id

Адаптация не выканаліваецца пад час работы. Выкананне deno task routes праходзіць па дрэве маршрутаў і стварае статычную, дэтерміністычную табліцу маршрутаў. Два фактары робяць гэта надзеяным:

• Статычныя маршруты завжды рэгіструюцца раней за дынамічныя, таму /users/new ніколі не можа быть практычна падмяненым /users/:id. У рутерах з прыемам першага падпадання, такіх як Hono, порядак рэгістрацыі є часткаю ўзору працы, і яго стварэнне усуняе класычны выхад для тонкіх багоў.
• Створаны файл зберагаецца ў рэпазітарыі, і процес CI не выйдзе, якщо ён застарэў.

Сторанкі — это звычныя функцыі

Сторанка — это звычны модуль TypeScript. Ён імпортуе тип Context з Hono і дапаможнік для адхоўвання HTML:

import type { Context } from "hono";
import { escapeHtml } from "@/shared/html.ts";

Пасля чаго ён экспортуе об’ект config, які выбірае лейаут і стандартную функцыю, якая вяртае рэч з HTML:

export const config = { layout: "default" } as const;export default function homePage(c: Context): string {
  const name = escapeHtml(c.req.query("name") ?? "world");
  return `<h1>Hello, ${name}!</h1>`;
}

Деталь, яка заслуговае на увагу, — это escapeHtml. Параметр запита name контролюецца корыстнікам, і яго прямая адгукаванне ў маркап будзе класычным прыкладам падобнага XSS-вады. У DenoX адгукаванне ненадзеянага вхідных дадзенаў не ёсць рэкамендацыяй, а правілам, запісаным у інжынерскай даговоре проекту. Паколькі старонкі вяртаюць необработаныя строкі без шаблоннага двіжка з аўтаматычным адгукаваннем, кожная адгукаванне зовнішняй дакументацыі павінна пройсці через гэты помачнік.

Функцыяны фрагменты з фіксаванай структурой

У частцы API кожная функцыя ёсць самостойным фрагментам з тым жа наборам файлоў, кожны з якіх мае адну задачу:

src/api/users/
├── user.model.ts        entities only
├── user.dto.ts          unknown → typed DTO (boundary validation)
├── user.repository.ts   interface + default implementation
├── user.service.ts      business rules only — no HTTP, no HTML
├── user.controller.ts   HTTP adapter only
└── user.routes.ts       composition root (constructor injection)

Модуль DTO ператварае невядомы вхідны дадзеныя на об’ект з атрыбутамі на грані, тады нічыя іншы элементы стака не працюе з первісным тэламом запиту. Сервісы маюць толькі бізнес-правіла і нічога не ведаюць пра HTTP чы гэтыкс. Кантролеры ўособлівае HTTP-адаптары. Файл з маршрутамі ёсць корнем складання, дзе залежнасці падключаюцца через ввод у констрактары.

Сервісы залежаць ад інтэрфейсаў рэпазітарыяў, а не ад конкретных класаў. Таму замена памятнага сховішча на Postgres чы Deno KV значыць змяну аднае файла за кожной функцыяй.

Памылкі як аб’екты з атрыбутамі

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

async create(dto: CreateUserDto): Promise<User> {
  const existing = await this.repository.findByEmail(dto.email);
  if (existing !== null) {
    throw new ConflictException(`Email "${dto.email}" is already registered`);
  }
  return await this.repository.create(dto);
}

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

Безпека реалізаваная аднойчы, застосоўваная всюды

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

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

Тры слоі тэстав за аднам камандам

Архітектура тэстав выходзіць за межы простых перакантрацоўках:

• Тэсты на елементах абрабоцваюць чыстую логіку за дапамогою макаў для запісу вызоў і не выклекаюць ніяких прав Deno.
• Інтэграцыйныя тэсты працуюць з усім налаштаваным прыгледам праз app.request(), перакантрацуючы коды статусу, адпаведныя рэспансы і нават заголовкі безпекі, не ачынаючы сокета.

Тэсты «з канца ў канец» запускаюць рэальны Deno.serve на тымчасовым порту і атакуюць яго рэальнымі запытамі fetch, у тым часе адзін з іх намеравана спрацоўвае лімітар швайнароўкі, каб паўнастаяць, што будзе вярнуты код 429.

Полная перацэнка якасці, якая абходзіць форматаванне, перагляд коду, пераканальвання табелі маршрутаў, строгую перацэнку типаў і всія роўны тэстав, выконваецца за дапамогою deno task ci, а пайплайн GitHub Actions выконвае самэ гэтая последовасць.

Адна команда для развяртывання, без обработкі аутентыкацыйных дадзеных

У рэпозітарыі є маніфесты для Fly.io, Railway, Render, Docker і захоўваная елемента systemd для VPS, а таксама высокай якосці падтрымка Deno Deploy. Адна задача перыядае цілі, выводзіць прыклад выконання або выконвае развяртыванне:

deno task deploy            # list targets
deno task deploy fly        # dry run: steps + env reminders
deno task deploy fly --run  # execute (auth delegated to the platform CLI)

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

AGENTS.md як обавязковы інжынерны дактар

Найболей выдатная частка DenoX — это файл AGENTS.md, які знаходзіцца ў коране рэпазітарыя і служыць авторытатным дактаментам як для людзей-разработчыкаў, так і для AI-агентаў. У яму заданы тэхналогічны стак, апісана стандартная структура дырэктарый і пераказаныя спільныя элементы, якія нельга перазмацаваць: логгер, іерархія асобы, кантэйнер адпаведзей і модуль налашчання.

У яму таксама описан працэс разработкі, адмовлены ў спецыфікацыях:

1. Спефікацыя, такая як specs/feature.md, запісваецца з атрыбутам status: draft.
2. Людзі пераглядаюць яе і зменшаюць статус на status: approved.
3. Толькі пасля затверджэння праця пераходзіць да стадій архітектуры, планавання, рэалізацыі, тэставання і документавання.

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

Калі агенты пішуць большае колька коду, стандарты маюць значэнне толькі тады, калі іх можна автаматычна пераканаць; версіяванне контракта праз код і падтрымка яго за дапамою CI ператварае рэкамендаціі на правіла дзейства. Чытайце пра аналогічны падход да файлаў інструкцый для асистэнтав у стацыі Vercel пра навык AGENTS.md для наяўнення najlepsых практык у React.

Выкананне локальна

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

git clone https://github.com/olavomello/denox.git
cd denox
cp .env.example .env
deno task dev

Потым ачыніце http://localhost:8000, вызначыце /api/users, намеравана апрашыце невярныя даны і пераканайцеся, што пакет з адазамі пра бягучыя кантракты застаецца чыстым і не мітківае стэк-трэсы. Таксама ёсць версія для роботы у реальнам часе. Проект распространяецца пад ліцензыей MIT; у яго планах — адаптары Deno KV і Postgres, автаматычная рэгістрацыя лейаутаў, спецыяльны CLI, модуль автаналіза і генераванне OpenAPI, пры чым кожны з эых элементаў плануецца стварыць па той самай схеме, калі спачатку ствараецца спефікацыя. Перад ўжываннем пераканайцеся у яго текущым стане ў рэпазітарыі.

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

• Ствараце табелі маршрутаў пад час будовы, зарэгіструйце статычныя маршруты раней за дынамічныя, зберажыце выходны кантэнт і дазвольце системам CI адхіліць застарэлыя файлы.
• Дадзіце кожнай функцыяй фіксаваную структуру: DTO-ы для меж, рэпазітарыі на адной з інтерфейсаў, сервісы без выкарыстоўвання HTTP і лёгкія кантролеры.

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

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

Напісце файл AGENTS.md, які вымагае людскай апраўды спецыфікацый, і застосавайце яго правілы ў CI, каб яны дазволялі працаваць як агентам, так і людям.