initial commit

2025-12-12 17:38:53 +03:00
commit 2bbc104000
1 changed files with 463 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,463 @@
+# Методические указания по разработке Web API на Node.js для школьников
+
+## Введение
+Данные методические указания предназначены для школьников, имеющих базовые навыки работы с HTML/CSS, Git и SSH. Цель курса — освоить основы разработки Web API с использованием Node.js и фреймворка Express за ограниченное время (3 часа на занятие и несколько занятий в семестр). Упор сделан на практические задания с минимально необходимой теорией.
+
+---
+
+## 📘 **Урок 1: Создание репозитория и организации структуры проекта**
+
+### **Цель урока**: Создать GitHub-репозиторий, организовать структуру проекта и научиться работать с ветками в Git.
+
+### **Краткая теория**:
+- **GitHub** — платформа для хостинга и совместной разработки IT-проектов с использованием системы контроля версий Git.
+- **Репозиторий** — хранилище кода и истории его изменений.
+- **Ветка (branch)** — изолированная копия проекта для разработки новой функциональности без влияния на основной код (часто называется `main` или `master`).
+
+### **Практические шаги**:
+1. **Создайте репозиторий на GitHub**:
+    *   Авторизуйтесь на [GitHub](https://github.com).
+    *   Нажмите `+` в правом верхнем углу и выберите `New repository`.
+    *   В поле `Repository name` укажите название, отражающее тему вашего API (например, `my-first-api`).
+    *   Оставьте репозиторий публичным (`Public`).
+    *   **Поставьте галочку** `Add a README.md`. Это создаст начальный файл описания проекта.
+    *   Нажмите `Create repository`.
+
+2. **Клонируйте репозиторий и создайте учебную ветку**:
+    ```bash
+    # Склонируйте репозиторий на компьютер
+    git clone git@github.com:<ваш-логин>/<название-репозитория>.git
+    cd <название-репозитория>
+
+    # Создайте и переключитесь на новую ветку 'study'
+    git checkout -b study
+    # Если в команде двое, каждый создает свою ветку (например, study-ivanov)
+    # git checkout -b study-фамилия
+    ```
+
+### **Что должно получиться**:
+*   Создан удаленный репозиторий на GitHub с файлом `README.md`.
+*   На вашем компьютере есть локальная копия проекта.
+*   Вы находитесь в новой ветке (`study` или `study-фамилия`), а не в основной (`main`).
+
+---
+
+## 📦 **Урок 2: Инициализация проекта Node.js**
+
+### **Цель урока**: Создать структуру папок для backend и инициализировать проект Node.js.
+
+### **Краткая теория**:
+- **Node.js** — это среда выполнения JavaScript вне браузера, которая позволяет создавать серверные приложения.
+- **package.json** — это файл манифеста проекта Node.js, который содержит его описание, версию, список зависимостей и скриптов.
+
+### **Практические шаги**:
+1. **Создайте папку `backend`** и перейдите в неё:
+    ```bash
+    mkdir backend
+    cd backend
+    ```
+2. **Инициализируйте проект Node.js**. Используйте флаг `-y`, чтобы принять значения по умолчанию, и `--type=module` для поддержки современного синтаксиса ES-модулей:
+    ```bash
+    npm init -y --type=module
+    ```
+
+### **Проверка результата**:
+Убедитесь, что в папке `backend` появился файл `package.json`. В его первой строке должно быть указано `"type": "module"`.
+
+---
+
+## 🚀 **Урок 3: Установка фреймворка Express**
+
+### **Цель урока**: Установить библиотеку Express — популярный фреймворк для создания веб-приложений и API на Node.js.
+
+### **Краткая теория**:
+- **Express** — это минималистичный и гибкий фреймворк, который значительно упрощает создание серверных приложений и маршрутов.
+- **Зависимости (dependencies)** — это сторонние библиотеки (пакеты), которые использует ваш проект. Они управляются с помощью `npm` (Node Package Manager).
+
+### **Практические шаги**:
+В папке `backend` выполните команду установки:
+```bash
+npm install express
+```
+
+### **Что должно получиться**:
+*   В файле `package.json` в раздел `"dependencies"` добавится `"express"` с номером версии.
+*   В проекте появится папка `node_modules`, где хранятся все установленные библиотеки.
+
+---
+
+## 🗑️ **Урок 4: Работа с `.gitignore` и первый коммит**
+
+### **Цель урока**: Научиться игнорировать ненужные для репозитория файлы и зафиксировать изменения.
+
+### **Краткая теория**:
+- **`node_modules`** — это папка со всеми зависимостями проекта. Её **нельзя** добавлять в Git, так как она очень большая и её можно восстановить командой `npm install`.
+- **`.gitignore`** — специальный файл, в котором перечисляются шаблоны файлов и папок, которые Git должен игнорировать.
+
+### **Практические шаги**:
+1. **Создайте файл `.gitignore`** в корне вашего проекта (на одном уровне с папкой `backend`).
+2. **Добавьте в него шаблоны**. Вы можете создать базовое содержимое на сайте [gitignore.io](https://www.toptal.com/developers/gitignore). Введите `Node, Windows, VisualStudioCode` и скопируйте сгенерированный текст в ваш файл.
+3. **Убедитесь, что в `.gitignore` есть строки**:
+    ```
+    node_modules/
+    .env
+    ```
+4. **Выполните коммит**:
+    ```bash
+    # Вернитесь в корень проекта (если вы в папке backend)
+    cd ..
+
+    # Добавьте все новые файлы в staging area
+    git add .
+
+    # Зафиксируйте изменения с комментарием
+    git commit -m "feat: инициализирован проект Node.js с Express, добавлен .gitignore"
+    ```
+
+---
+
+## 📄 **Урок 5: Создание базовой структуры сервера**
+
+### **Цель урока**: Создать основные файлы приложения и понять их роль.
+
+### **Краткая теория**:
+Серверное приложение на Express обычно разделяют на несколько файлов для лучшей организации:
+- **`server.js`** — точка входа. Запускает сервер, подключает основные настройки.
+- **`app.js`** — ядро приложения. Содержит настройки Express и все маршруты (routes).
+
+### **Практические шаги**:
+1. В папке `backend` создайте папку `src`.
+2. Внутри `src` создайте два файла: `app.js` и `server.js`.
+3. **В файл `app.js`** пока добавьте только создание экземпляра приложения:
+    ```javascript
+    // backend/src/app.js
+    import express from 'express';
+
+    const app = express();
+
+    export default app; // Экспортируем app для использования в server.js
+    ```
+4. **В файл `server.js`** добавьте код запуска сервера:
+    ```javascript
+    // backend/src/server.js
+    import app from './app.js';
+
+    const PORT = process.env.PORT || 3000;
+
+    app.listen(PORT, () => {
+        console.log(`Сервер запущен и слушает порт ${PORT}`);
+    });
+    ```
+
+### **Что должно получиться**:
+Создана модульная структура приложения. Пока при запуске сервер будет работать, но на любой запрос возвращать ошибку `404`, так как маршруты не определены.
+
+---
+
+## ▶️ **Урок 6: Первый запуск сервера**
+
+### **Цель урока**: Запустить сервер и убедиться, что он работает, возвращая ожидаемую ошибку.
+
+### **Практические шаги**:
+1. Из папки `backend` выполните команду:
+    ```bash
+    node src/server.js
+    ```
+2. В консоли должно появиться сообщение: `Сервер запущен и слушает порт 3000`.
+3. Откройте браузер и перейдите по адресу `http://localhost:3000`.
+4. **Вы должны увидеть стандартную страницу ошибки `Cannot GET /`**. Это ожидаемо, так как мы не создали обработчик для корневого маршрута (`/`).
+5. Остановите сервер, нажав `Ctrl + C` в терминале.
+6. **Выполните коммит**:
+    ```bash
+    git add .
+    git commit -m "feat: создана базовая структура сервера, успешный запуск"
+    git push origin study # Или study-фамилия
+    ```
+
+---
+
+## 🖐️ **Урок 7: Создание первого маршрута (Hello World)**
+
+### **Цель урока**: Создать простейший обработчик GET-запроса и получить ответ от сервера.
+
+### **Краткая теория**:
+- **Маршрут (route)** — это правило, которое определяет, как сервер будет реагировать на клиентский запрос к определенному URL (конечной точке) и HTTP-методу (GET, POST и т.д.).
+- **Обработчик (handler)** — функция, которая принимает запрос (`req`) и формирует ответ (`res`).
+
+### **Практические шаги**:
+1. Откройте файл `backend/src/app.js`.
+2. **Добавьте обработчик для корневого маршрута (`/`) перед строкой `export default app;`**:
+    ```javascript
+    // Обработчик GET-запроса на корневой URL '/'
+    app.get('/', (req, res) => {
+        // Устанавливаем заголовок ответа
+        res.setHeader('Content-Type', 'text/plain');
+        // Отправляем текстовый ответ
+        res.send('Hello World from my API!');
+    });
+    ```
+3. Запустите сервер снова (`node src/server.js`) и обновите страницу `http://localhost:3000` в браузере.
+4. **Вы должны увидеть надпись `Hello World from my API!`**.
+5. **Выполните коммит**.
+
+---
+
+## 🔢 **Урок 8: Работа с параметрами пути (Path Parameters)**
+
+### **Цель урока**: Научиться создавать динамические маршруты и извлекать данные из URL.
+
+### **Краткая теория**:
+- **Статические маршруты** — это фиксированные адреса, например, `/about` или `/contacts`. Они всегда одинаковы.
+- **Динамические маршруты** — это адреса, которые могут меняться. Например, страница профиля с разными именами пользователей: `/user/anna`, `/user/max`.
+- **Параметры пути (Path Parameters)** — специальные части URL, которые меняются. В Express они обозначаются двоеточием (`:`), например: `/user/:username`.
+- Когда кто-то заходит на `/user/anna`, Express видит `:username` в маршруте и понимает: "вместо `:username` подставлено `anna`". Это значение сохраняется в `req.params`.
+
+### **Примеры разных параметров**:
+
+1. **Один параметр**:
+```javascript
+// Когда заходят на /hello/Максим
+app.get('/hello/:name', (req, res) => {
+    const name = req.params.name; // = "Максим"
+    res.send(`Привет, ${name}!`);
+});
+```
+
+2. **Несколько параметров**:
+```javascript
+// Когда заходят на /book/сказки/5
+app.get('/book/:genre/:page', (req, res) => {
+    const genre = req.params.genre; // = "сказки"
+    const page = req.params.page;   // = "5"
+    res.send(`Жанр: ${genre}, Страница: ${page}`);
+});
+```
+
+3. **Параметр в середине пути**:
+```javascript
+// Когда заходят на /category/электроника/product/123
+app.get('/category/:categoryName/product/:productId', (req, res) => {
+    const category = req.params.categoryName; // = "электроника"
+    const productId = req.params.productId;   // = "123"
+    res.send(`Категория: ${category}, Товар: ${productId}`);
+});
+```
+
+### **Практические шаги**:
+1. В файле `app.js` добавьте маршрут:
+```javascript
+// Пример запроса: GET http://localhost:3000/double/7
+app.get('/double/:number', (req, res) => {
+    const input = req.params.number; // Получаем параметр из URL
+    
+    // Проверяем, является ли параметр числом
+    if (!isNaN(input)) {
+        const number = parseFloat(input);
+        const result = number * 2;
+        res.send(`Если удвоить ${number}, получится ${result}`);
+    } else {
+        res.status(400).send('Пожалуйста, укажите число. Например: /double/10');
+    }
+});
+```
+
+2. Протестируйте:
+   - `http://localhost:3000/double/7` → работает
+   - `http://localhost:3000/double/abc` → ошибка
+
+---
+
+## ➕➖✖️➗ **Урок 9: Практическое задание — Текстовый API-калькулятор**
+
+### **Цель задания**: Создать простой калькулятор, который принимает числа в URL и возвращает текстовый результат.
+
+### **Задание**:
+Создайте 4 маршрута для основных математических операций. Формат ответа — обычный текст.
+
+**Маршруты и примеры**:
+1. **Сложение**: `GET /api/calc/sum/:a/:b`
+   - Пример: `GET /api/calc/sum/5/3`
+   - Ответ: `5 + 3 = 8`
+
+2. **Вычитание**: `GET /api/calc/subtract/:a/:b`
+   - Пример: `GET /api/calc/subtract/10/4`
+   - Ответ: `10 - 4 = 6`
+
+3. **Умножение**: `GET /api/calc/multiply/:a/:b`
+   - Пример: `GET /api/calc/multiply/7/2`
+   - Ответ: `7 * 2 = 14`
+
+4. **Деление**: `GET /api/calc/divide/:a/:b`
+   - Пример: `GET /api/calc/divide/15/3`
+   - Ответ: `15 / 3 = 5`
+
+### **Как это сделать**:
+1. Для каждого маршрута получите параметры из `req.params.a` и `req.params.b`
+2. Преобразуйте их в числа: `const num1 = parseFloat(req.params.a)`
+3. Выполните операцию
+4. Верните ответ в формате: ``res.send(`${num1} + ${num2} = ${result}`)``
+
+### **Важно**:
+- Пока не нужно проверять, корректные ли данные прислал пользователь
+- Используйте шаблонные строки (обратные кавычки) для формирования ответа
+
+---
+
+## ⚠️ **Урок 10: Базовые проверки в калькуляторе**
+
+### **Цель урока**: Добавить минимальную проверку входных данных.
+
+### **Задание**:
+Доработайте калькулятор из урока 9, добавив две простые проверки:
+
+1. **Проверка, что оба параметра — числа**
+2. **Для деления — проверка, что второй параметр не ноль**
+
+### **Как это сделать**:
+
+**Шаг 1: Проверка на число**
+В начале каждого обработчика добавьте:
+```javascript
+const a = parseFloat(req.params.a);
+const b = parseFloat(req.params.b);
+
+// Проверяем, являются ли оба параметра числами
+if (isNaN(a) || isNaN(b)) {
+    return res.status(400).send('Ошибка: оба параметра должны быть числами');
+}
+```
+
+**Шаг 2: Проверка деления на ноль**
+Только в обработчике деления добавьте после проверки на числа:
+```javascript
+// Проверка деления на ноль
+if (b === 0) {
+    return res.status(400).send('Ошибка: на ноль делить нельзя');
+}
+```
+
+### **Что должно происходить**:
+- `/api/calc/sum/5/3` → `5 + 3 = 8` (работает)
+- `/api/calc/sum/5/abc` → `Ошибка: оба параметра должны быть числами` (ошибка 400)
+- `/api/calc/divide/10/0` → `Ошибка: на ноль делить нельзя` (ошибка 400)
+
+---
+
+## 📊 **Урок 11: Введение в формат JSON**
+
+### **Цель урока**: Понять, что такое JSON и научиться отправлять данные в этом формате.
+
+### **Краткая теория**:
+- **JSON (JavaScript Object Notation)** — популярный формат для обмена данными;
+- у JSON есть строгий набор правил:
+  - Все ключи в двойных кавычках
+  - Значения: строки (в кавычках), числа, true/false, null, массивы [], объекты {}
+- **Пример JSON**:
+```json
+{
+  "имя": "Иван",
+  "возраст": 16,
+  "хобби": ["программирование", "шахматы"],
+  "студент": true
+}
+```
+
+### **Практическое задание**:
+1. Создайте маршрут `GET /api/user/:id`
+2. Если `:id` — число, верните JSON с информацией о пользователе:
+```javascript
+app.get('/api/user/:id', (req, res) => {
+    const id = req.params.id;
+    
+    if (!isNaN(id)) {
+        // Формируем вручную объект пользователя.
+        // Пока что просто притворимся, что мы загрузили его из базы данных.
+        const userData = {
+            userId: Number(id),
+            name: "Алексей Петров",
+            email: "alexey@example.com",
+            registered: true
+        };
+        
+        // Отправляем как JSON
+        res.json(userData);
+    } else {
+        // Если id не число - ошибка в JSON формате
+        res.status(400).json({
+            error: "ID должен быть числом",
+            example: "/api/user/123"
+        });
+    }
+});
+```
+3. Протестируйте в браузере:
+   - `http://localhost:3000/api/user/123` → увидите красиво оформленный JSON
+   - `http://localhost:3000/api/user/abc` → JSON с ошибкой
+
+### Обратите внимание
+В примере мы возвращаем фальшивые данные. С настоящими динамическими данными (списки/объекты БД) мы поработаем позже. 
+
+---
+
+## 🔄 **Урок 12: Калькулятор с JSON-ответами**
+
+### **Цель урока**: Переделать текстовый калькулятор для возврата JSON.
+
+### **Задание**:
+Измените все 4 операции калькулятора так, чтобы они возвращали данные в JSON-формате.
+
+### **Формат успешного ответа**:
+```json
+{
+  "success": true,
+  "operation": "sum",
+  "arguments": {
+    "a": 5,
+    "b": 3
+  },
+  "result": 8
+}
+```
+
+### **Формат ответа с ошибкой**:
+```json
+{
+  "success": false,
+  "error": {
+    "code": "DIVISION_BY_ZERO",
+    "message": "Делитель не может быть равен нулю"
+  }
+}
+```
+
+### **Как изменить код**:
+
+1. **Заменяем `res.send()` на `res.json()`**
+2. **Для успешного ответа** формируем объект:
+```javascript
+const response = {
+    success: true,
+    operation: "sum", // или "subtract", "multiply", "divide"
+    arguments: {
+        a: a,
+        b: b
+    },
+    result: a + b // здесь ваша операция
+};
+res.json(response);
+```
+
+3. **Для ошибок**:
+```javascript
+res.status(400).json({
+    success: false,
+    error: {
+        code: "INVALID_NUMBERS", // или "DIVISION_BY_ZERO"
+        message: "Оба параметра должны быть числами"
+    }
+});
+```
+
+### **Примеры кодов ошибок**:
+- `"INVALID_NUMBERS"` — когда параметры не числа
+- `"DIVISION_BY_ZERO"` — когда делим на ноль