Skip to content

docs: сервер это контент курса, а не деталь реализации #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fey merged 1 commit into from
Sep 3, 2026
Merged

docs: сервер это контент курса, а не деталь реализации #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,8 @@ Caddy :$PORT
* **Валидация отвечает 400, уроки учат на 422.** Отображение делает
`setErrorHandler` в `http-api.ts` по коду `FST_ERR_VALIDATION`.

**Дефолты `skip` и `limit` в спецификации несут пагинацию.** `skip: uint16 = 0` и `limit: uint16 = 30` выглядят необязательными, но значение по умолчанию подставляет валидатор, и без них пагинация ломается **частично**: `skip` продолжает работать, `limit` перестаёт. Снаружи это читается как «limit не поддерживается», хотя причина в правке спецификации.

## Примеры ответов это текст уроков

Значения в `@example` подобраны под то, что уроки уже печатают:
Expand Down Expand Up @@ -155,6 +157,8 @@ Caddy :$PORT

Проверку всех кодов держит `make test`.

**Трейлинг-слеш маршруты не прощают:** `/postman/users/` отдаёт 404. В текстах курсов адрес пишется без слеша.

## Версии прибиты не для порядка

Зависимости на prism больше нет. Если мок когда-нибудь вернут, с ним вернутся и
Expand All @@ -181,6 +185,10 @@ Caddy :$PORT
типы из него и падает на `git diff`, хотя спецификации в репозитории не менялись.
Лечится `make compile`.

**`make generate` очищает `custom-server/src/generated/` перед записью.** Неудачная проба сносит закоммиченное, поэтому сгенерированное восстанавливается из git, а не переписывается руками.

Сервисы в тесте заводятся `detached: true` и снимаются группой (`process.kill(-pid)`): без этого внук `npx` переживает `SIGTERM` обёртке и держит трубы открытыми. Трубу обязательно вычитывать. Процессы снимаются по PID, потому что `pkill -f "fastify start"` совпадает с текстом собственной команды и убивает свою же оболочку. Пустой вывод **у всех** сервисов сразу означает нехватку ресурсов машины, а не поломку кода.

Caddy в прогоне не участвует, в раннере его нет: порты опрашиваются напрямую, как
это делает Caddy со срезанным префиксом. Сборка гоняется и на пуллреквестах,
публикация образа — только с `main`.
Expand Down Expand Up @@ -220,6 +228,8 @@ make deploy APP=http_example HOST=timeweb SKIP=caddy,cron
* первые три пользователя и первые два поста автора 1 приведены в уроке
дословно.

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

## Набор данных не меняется

`POST` и `DELETE` отвечают 201 и 204, но список задач остаётся прежним: создание
Expand Down
16 changes: 12 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,10 @@
<https://twirl.github.io/The-API-Book/API.ru.html>
# http-example

Учебный HTTP-сервер Хекслета: [https://http.hexlet.app](https://http.hexlet.app). На него **живьём ходят студенты** из курсов HTTP API, протокол HTTP, Postman и js-playwright, а уроки и самостоятельные работы цитируют его ответы дословно, вплоть до значений полей.

Отсюда главное свойство проекта: **ответы сервера это контент курса**, а не деталь реализации. Правка данных здесь делает неверным текст урока в другом репозитории, и по коду это не видно. Поэтому правила работы с проектом собраны в [AGENTS.md](./AGENTS.md), и читать их стоит до первой правки — там же разобрано, почему наборы данных такого размера, почему они не меняются и какие коды ответов несут уроки.

Устройство короткое: четыре спецификации на TypeSpec (`typespec/<app>/`, по одной на курс) компилируются в OpenAPI, а маршруты, валидацию и авторизацию строит из них `fastify-openapi-glue`. Руками написаны только данные и то, что в OpenAPI не выражается. Значит документация и поведение разъехаться не могут: студент читает ту же спецификацию, по которой работает сервер.

## Prerequisites

Expand All @@ -7,13 +13,15 @@

## Commands

See [Makefile](./Makefile)

```bash
make setup # зависимости и компиляция спецификаций
make test # прогон против всех четырёх префиксов
make compose-build
make compose # Open http://localhost:8080
make compose # http://localhost:8080
```

Остальные цели — в [Makefile](./Makefile).

---

[![Hexlet Ltd. logo](https://raw.githubusercontent.com/Hexlet/assets/master/images/hexlet_logo128.png)](https://hexlet.io?utm_source=github&utm_medium=link&utm_campaign=http-example)
Expand Down