Initial commit: Bun web server with middleware, routing, and comprehensive documentation
This commit is contained in:
244
DOCS_INDEX.md
Normal file
244
DOCS_INDEX.md
Normal file
@ -0,0 +1,244 @@
|
||||
# 🎓 Документация Bun Web Server - Встроенные возможности
|
||||
|
||||
## 📋 Все файлы документации
|
||||
|
||||
| Файл | Описание | Для кого |
|
||||
|------|---------|----------|
|
||||
| **README.md** | Основная документация проекта | Все |
|
||||
| **BUN_RENDERING.md** | Подробное руководство по встроенным методам рендера | Разработчики |
|
||||
| **BUN_CAPABILITIES.md** | Итоговая сводка из 10 встроенных возможностей |快速справка |
|
||||
| **DOCS_INDEX.md** | Этот файл - индекс всей документации | Навигация |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Быстрый старт
|
||||
|
||||
### Установка и запуск
|
||||
```bash
|
||||
bun install
|
||||
bun run dev
|
||||
```
|
||||
|
||||
Сервер запустится на **http://localhost:3002**
|
||||
|
||||
---
|
||||
|
||||
## 📚 Что изучить в каком порядке
|
||||
|
||||
### 1️⃣ Новичкам (начните отсюда)
|
||||
```
|
||||
1. README.md - Структура проекта и основные маршруты
|
||||
2. BUN_CAPABILITIES.md - 10 встроенных возможностей
|
||||
3. Попробуйте демо маршруты: /demo/*
|
||||
```
|
||||
|
||||
### 2️⃣ Разработчикам (углубленное изучение)
|
||||
```
|
||||
1. BUN_RENDERING.md - Подробное сравнение методов
|
||||
2. src/bun-rendering-examples.ts - Примеры кода
|
||||
3. src/bun-rendering-guide.ts - Теоретическое описание
|
||||
```
|
||||
|
||||
### 3️⃣ Расширению проекта
|
||||
```
|
||||
1. README.md → Раздел "Как расширять"
|
||||
2. Добавьте свои обработчики в src/handlers/
|
||||
3. Создавайте новые middleware в src/middleware/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Встроенные возможности Bun (Топ 10)
|
||||
|
||||
### Все 10 возможностей на одной странице:
|
||||
|
||||
```
|
||||
✅ 1. Template Literals - Самый быстрый HTML рендер (0.1ms)
|
||||
✅ 2. JSX/TSX компиляция - Встроенная без конфигурации
|
||||
✅ 3. React SSR - renderToString() из коробки
|
||||
✅ 4. Bun.file() - Супер быстрая работа с файлами
|
||||
✅ 5. Streaming API - Web Standard потоки
|
||||
✅ 6. JSON оптимизация - Встроенная V8 оптимизация
|
||||
✅ 7. Web Standards API - Request, Response, Headers и т.д.
|
||||
✅ 8. TypeScript - Встроенная компиляция
|
||||
✅ 9. HTTP кеширование - Cache-Control, ETag
|
||||
✅ 10. Cookie поддержка - Set-Cookie из коробки
|
||||
```
|
||||
|
||||
**Рекомендация:** Используйте Template Literals в 80% случаев!
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Демонстрационные маршруты
|
||||
|
||||
Все примеры встроенных возможностей доступны по URL:
|
||||
|
||||
```
|
||||
GET /demo/fast-render - Быстрый HTML рендер
|
||||
GET /demo/dynamic-data - Динамический контент (таблица)
|
||||
GET /demo/optimized-json - JSON с оптимизацией
|
||||
GET /demo/streaming - Streaming контент
|
||||
GET /demo/cached-asset - Кеширование браузером
|
||||
GET /demo/cookie - Установка Cookie
|
||||
GET /demo/all - Информация о всех методах
|
||||
```
|
||||
|
||||
### Тестирование в терминале:
|
||||
```bash
|
||||
curl http://localhost:3002/demo/fast-render
|
||||
curl http://localhost:3002/demo/all | jq
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Производительность методов рендера
|
||||
|
||||
| Метод | Скорость | Когда использовать |
|
||||
|-------|----------|-------------------|
|
||||
| Template Literals | ⚡⚡⚡ 0.1ms | **80% случаев** |
|
||||
| Bun.file() | ⚡⚡⚡ 0.05ms | Статические файлы |
|
||||
| Streaming | ⚡⚡⚡ 0.05ms | Большие файлы |
|
||||
| React SSR | ⚡ 2-5ms | Компоненты |
|
||||
| HTML Builder | ⚡⚡ 0.2ms | Специальные |
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Структура проекта
|
||||
|
||||
```
|
||||
src/
|
||||
├── index.ts # Точка входа + маршруты
|
||||
├── server.ts # Основной сервер
|
||||
├── router.ts # Маршрутизация
|
||||
├── middleware.ts # Система middleware
|
||||
├── render.ts # SSR рендер
|
||||
├── utils.ts # Утилиты
|
||||
├── types.ts # TypeScript типы
|
||||
│
|
||||
├── handlers/ # Обработчики маршрутов
|
||||
│ ├── homeHandler.ts # Главная страница
|
||||
│ └── apiHandler.ts # API endpoints
|
||||
│
|
||||
├── middleware/ # Middleware
|
||||
│ ├── builtIn.ts # Встроенные (logging, CORS и т.д.)
|
||||
│ └── advanced.ts # Продвинутые (caching, validation)
|
||||
│
|
||||
├── components/ # React компоненты (если используются)
|
||||
│ ├── Layout.tsx
|
||||
│ └── pages/
|
||||
│ └── HomePage.tsx
|
||||
│
|
||||
├── bun-rendering-guide.ts # Теория встроенных возможностей
|
||||
└── bun-rendering-examples.ts # Примеры встроенных возможностей
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💻 Основные маршруты сервера
|
||||
|
||||
### API Endpoints
|
||||
```
|
||||
GET / - Главная страница (HTML)
|
||||
GET /api/hello - Приветствие (JSON)
|
||||
GET /api/status - Статус сервера (JSON)
|
||||
POST /api/echo - Эхо данных (JSON)
|
||||
```
|
||||
|
||||
### Demo маршруты
|
||||
```
|
||||
GET /demo/fast-render - Пример Template Literals
|
||||
GET /demo/dynamic-data - Пример динамического контента
|
||||
GET /demo/optimized-json - Пример JSON оптимизации
|
||||
GET /demo/streaming - Пример Streaming
|
||||
GET /demo/cached-asset - Пример кеширования
|
||||
GET /demo/cookie - Пример Cookie
|
||||
GET /demo/all - Все методы в одном
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Технический стек
|
||||
|
||||
- **Runtime:** Bun (встроенный)
|
||||
- **Язык:** TypeScript
|
||||
- **Framework:** Встроенные Web APIs (без фреймворка)
|
||||
- **Middleware:** Собственная реализация
|
||||
- **Routing:** Собственная реализация
|
||||
- **Templates:** Template Literals (встроенный JS)
|
||||
|
||||
---
|
||||
|
||||
## 📖 Рекомендуемый порядок чтения
|
||||
|
||||
### День 1: Основы
|
||||
1. Запустить сервер: `bun run dev`
|
||||
2. Посетить http://localhost:3002
|
||||
3. Пройтись по всем `/demo/*` маршрутам
|
||||
4. Прочитать BUN_CAPABILITIES.md
|
||||
|
||||
### День 2: Углубление
|
||||
1. Прочитать BUN_RENDERING.md
|
||||
2. Изучить src/bun-rendering-examples.ts
|
||||
3. Тестировать примеры через curl/Postman
|
||||
4. Экспериментировать с Template Literals
|
||||
|
||||
### День 3: Расширение
|
||||
1. Создать новый endpoint в src/handlers/
|
||||
2. Добавить свой middleware в src/middleware/
|
||||
3. Зарегистрировать в src/index.ts
|
||||
4. Протестировать
|
||||
|
||||
---
|
||||
|
||||
## 🎁 Преимущества встроенных решений Bun
|
||||
|
||||
| Преимущество | Описание |
|
||||
|--------------|---------|
|
||||
| **Производительность** | Template Literals 0.1ms vs React 2-5ms |
|
||||
| **Простота** | Не нужны фреймворки/библиотеки |
|
||||
| **Встроенность** | Все из одного runtime |
|
||||
| **Типизация** | TypeScript встроенный |
|
||||
| **Стандарты** | Web Standards API |
|
||||
| **Минимум кода** | Не нужно писать много boilerplate |
|
||||
|
||||
---
|
||||
|
||||
## ❓ Частые вопросы
|
||||
|
||||
### Какой метод выбрать?
|
||||
→ **Template Literals в 80% случаев**, React когда нужны компоненты
|
||||
|
||||
### Какой проект это хорошо для?
|
||||
→ APIs, SSR сервера, микросервисы, edge computing
|
||||
|
||||
### Нужны ли фреймворки?
|
||||
→ Нет! Встроенные Web APIs достаточно
|
||||
|
||||
### Как это работает без npm пакетов?
|
||||
→ Все встроено в Bun runtime
|
||||
|
||||
### Можно ли использовать React?
|
||||
→ Да! Установите через `bun install react react-dom`
|
||||
|
||||
---
|
||||
|
||||
## 📞 Поддержка
|
||||
|
||||
Для подробной информации смотрите:
|
||||
- **BUN_RENDERING.md** - Подробное руководство
|
||||
- **BUN_CAPABILITIES.md** - Быстрая справка
|
||||
- **README.md** - Полная документация
|
||||
- **src/** - Исходный код с комментариями
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Следующие шаги
|
||||
|
||||
1. ✅ Запустить `bun run dev`
|
||||
2. ✅ Посетить http://localhost:3002
|
||||
3. ✅ Изучить `/demo/*` маршруты
|
||||
4. ✅ Прочитать BUN_CAPABILITIES.md
|
||||
5. ✅ Создать собственный endpoint
|
||||
|
||||
**Happy Bun coding! 🎉**
|
||||
|
||||
Reference in New Issue
Block a user