Шпаргалка · Бизнес-процессы
Массовый импорт
Проблема
Оптовая компания загружает каталог товаров в CSV: 200 000 строк. Разбор прямо в запросе падает по таймауту, съедает память и выбрасывает всё из-за одной плохой строки. Вместо этого файл уходит в объектное хранилище, задача импорта читает его потоком, проверяет каждую строку и отдаёт отчёт об ошибках, переживает перезапуски и повторные загрузки, пишет короткими пачками, показывает прогресс и держится в лимитах на тенанта.
Чему вы научитесь
- Почему большой файл идёт прямо в объектное хранилище по pre-signed URL и читается воркером, а не веб-сервером
- Проверка каждой строки с номерами строк и скачиваемым отчётом об ошибках: частичный успех это норма
- Дедупликация по хешу файла, чекпоинт каждые N строк и пакетные upsert, которые держат блокировки основной таблицы коротко
- Прогресс, который UI может опрашивать, и лимиты на тенанта по размеру файла, строкам и запущенным задачам
Диаграмма как код
Итоговая схема урока в виде текста: вставьте её в Jira, GitLab, GitHub, Notion или документацию, там Mermaid рисуется сам. Есть варианты для D2 и PlantUML (Confluence, IntelliJ).
Mermaid: схема
flowchart LR
n_client(["Браузер"])
n_api["API приложения"]
n_db[("БД каталога")]
n_storage[("Хранилище")]
n_queue[["Очередь задач"]]
n_worker("Воркер импорта")
n_client --x n_api
n_client --> n_storage
n_api --> n_queue
n_queue --> n_worker
n_worker --> n_storage
n_worker --> n_db
n_api --> n_dbMermaid: последовательность запросов
sequenceDiagram
participant n_client as Браузер
participant n_api as API приложения
participant n_storage as Хранилище
participant n_worker as Воркер импорта
participant n_queue as Очередь задач
participant n_db as БД каталога
Note over n_client,n_api: Веб-сервер разбирает файл прямо в запросе
n_client->>n_api: POST /products/import HTTP/1.1
n_api-->>n_client: HTTP/1.1 200 OK
Note over n_client,n_api: 200 000 строк: таймаут, память, одна плохая строка
n_client->>n_api: 14:02:10 POST /products/import 41.9 MB, 200 000 rows
Note over n_client,n_storage: Загрузка прямо в объектное хранилище
n_client->>n_storage: PUT /t_19/imp_77.csv?expires=900#38;sig=*** HTTP/1.1
n_storage-->>n_client: HTTP/1.1 200 OK
Note over n_client,n_api: Задача импорта и воркер, читающий файл потоком
n_client->>n_api: POST /imports HTTP/1.1
n_api-->>n_client: HTTP/1.1 202 Accepted
Note over n_worker,n_storage: Проверять каждую строку, собирать ошибки, хорошие строки сохранять
n_worker->>n_storage: t_19/imp_77.errors.csv
Note over n_queue,n_worker: Перезапуск начинает сначала, повторная загрузка запускает новую задачу
n_queue->>n_worker: 15:10:04 deploy: worker restarted, imp_77 was at row 122 000
Note over n_worker,n_db: Хеш файла для дедупликации, чекпоинт каждые 1 000 строк
n_worker->>n_db: UPDATE import_jobs
n_db-->>n_worker: imp_77
Note over n_worker,n_db: Одна гигантская запись блокирует каталог
n_worker->>n_db: 16:00:02 imp_81: UPDATE products FROM staging
Note over n_worker,n_db: Пакетный upsert по естественному ключу
n_worker->>n_db: INSERT INTO products (tenant_id, sku, name, price_minor)
n_db-->>n_worker: INSERT 0 1000
Note over n_client,n_api: Прогресс, который UI может опрашивать
n_client->>n_api: GET /imports/imp_77 HTTP/1.1
n_api-->>n_client: HTTP/1.1 200 OK
Note over n_client,n_api: Лимиты на тенанта
n_client->>n_api: POST /imports HTTP/1.1
n_api-->>n_client: HTTP/1.1 429 Too Many RequestsD2
direction: right
n_client: "Браузер" {
shape: rectangle
}
n_api: "API приложения" {
shape: rectangle
}
n_db: "БД каталога" {
shape: cylinder
}
n_storage: "Хранилище" {
shape: stored_data
}
n_queue: "Очередь задач" {
shape: queue
}
n_worker: "Воркер импорта" {
shape: rectangle
style.multiple: true
}
n_client -> n_api {
target-arrowhead.shape: cross
}
n_client -> n_storage
n_api -> n_queue
n_queue -> n_worker
n_worker -> n_storage
n_worker -> n_db
n_api -> n_dbPlantUML: последовательность запросов
@startuml
participant "Браузер" as n_client
participant "API приложения" as n_api
database "Хранилище" as n_storage
participant "Воркер импорта" as n_worker
queue "Очередь задач" as n_queue
database "БД каталога" as n_db
note over n_client, n_api : Веб-сервер разбирает файл прямо в запросе
n_client -> n_api : POST /products/import HTTP/1.1
n_api --> n_client : HTTP/1.1 200 OK
note over n_client, n_api : 200 000 строк: таймаут, память, одна плохая строка
n_client -> n_api : 14:02:10 POST /products/import 41.9 MB, 200 000 rows
note over n_client, n_storage : Загрузка прямо в объектное хранилище
n_client -> n_storage : PUT /t_19/imp_77.csv?expires=900&sig=*** HTTP/1.1
n_storage --> n_client : HTTP/1.1 200 OK
note over n_client, n_api : Задача импорта и воркер, читающий файл потоком
n_client -> n_api : POST /imports HTTP/1.1
n_api --> n_client : HTTP/1.1 202 Accepted
note over n_worker, n_storage : Проверять каждую строку, собирать ошибки, хорошие строки сохранять
n_worker -> n_storage : t_19/imp_77.errors.csv
note over n_queue, n_worker : Перезапуск начинает сначала, повторная загрузка запускает новую задачу
n_queue -> n_worker : [дубль] 15:10:04 deploy: worker restarted, imp_77 was at row 122 000
note over n_worker, n_db : Хеш файла для дедупликации, чекпоинт каждые 1 000 строк
n_worker -> n_db : UPDATE import_jobs
n_db --> n_worker : imp_77
note over n_worker, n_db : Одна гигантская запись блокирует каталог
n_worker -> n_db : 16:00:02 imp_81: UPDATE products FROM staging
note over n_worker, n_db : Пакетный upsert по естественному ключу
n_worker -> n_db : INSERT INTO products (tenant_id, sku, name, price_minor)
n_db --> n_worker : INSERT 0 1000
note over n_client, n_api : Прогресс, который UI может опрашивать
n_client -> n_api : GET /imports/imp_77 HTTP/1.1
n_api --> n_client : HTTP/1.1 200 OK
note over n_client, n_api : Лимиты на тенанта
n_client -> n_api : POST /imports HTTP/1.1
n_api --> n_client : HTTP/1.1 429 Too Many Requests
@endumlPlantUML: компоненты
@startuml
left to right direction
agent "Браузер" as n_client
component "API приложения" as n_api
database "БД каталога" as n_db
storage "Хранилище" as n_storage
queue "Очередь задач" as n_queue
collections "Воркер импорта" as n_worker
n_client -[#c62828]-> n_api
n_client --> n_storage
n_api --> n_queue
n_queue --> n_worker
n_worker --> n_storage
n_worker --> n_db
n_api --> n_db
@endumlИтог
Шесть правил массового импорта.
1) Никогда не разбирайте большой файл в веб-запросе: загружайте его в объектное хранилище по короткоживущему pre-signed URL, а воркер пусть читает потоком. 2) Проверяйте каждую строку, сохраняйте хорошие и давайте пользователю отчёт об ошибках с номерами строк. 3) Дедуплицируйте загрузки по хешу файла и сохраняйте чекпоинт с каждой пачкой, чтобы перезапуск продолжал работу. 4) Пишите пачками примерно по 1 000 строк, upsert по естественному ключу, короткими транзакциями. 5) Показывайте прогресс из записи задачи. 6) Ограничивайте размер файла, строки и запущенные задачи на тенанта.
Показатели: в начале и в конце
| Показатель | В начале | В конце |
|---|---|---|
| Время импорта | 3 с | 95 с |
| Импортировано строк | 100% | 99,8% |
| Память API | 180 МБ | 60 МБ |
| Ожидание блокировки | 0 с | 0 с |
Шаги
- Кейс Веб-сервер разбирает файл прямо в запросе
Бухгалтер загружает каталог товаров из старой системы в CSV.
- Проблема 200 000 строк: таймаут, память, одна плохая строка
Теперь файл весит 41,9 МБ, 200 000 строк.
- Решение Загрузка прямо в объектное хранилище
Сначала браузер просит у API URL для загрузки.
- Решение Задача импорта и воркер, читающий файл потоком
Браузер говорит API: импортируй этот файл.
- Решение Проверять каждую строку, собирать ошибки, хорошие строки сохранять
Воркер проверяет каждую строку отдельно: обязательные поля, числа, единицы измерения, дубли внутри файла.
- Проблема Перезапуск начинает сначала, повторная загрузка запускает новую задачу
Деплой перезапускает воркер на строке 122 000.
- Решение Хеш файла для дедупликации, чекпоинт каждые 1 000 строк
Каждые 1 000 строк воркер сохраняет своё место в записи задачи: последнюю готовую строку и счётчики.
- Проблема Одна гигантская запись блокирует каталог
Запись по одной строке это 200 000 походов в базу, около 7 минут.
- Решение Пакетный upsert по естественному ключу
Воркер пишет 1 000 строк одним запросом: новые товары вставляет, существующие обновляет, сопоставляя по тенанту и SKU.
- Решение Прогресс, который UI может опрашивать
Страница каждые 2 секунды опрашивает задачу и рисует полосу: строк готово, ошибок на сейчас, сколько осталось.
- Решение Лимиты на тенанта
Один тенант запускает сразу шесть импортов файлов по 2 ГБ, и задачи всех остальных ждут за ними.
- Итоги Итог
Шесть правил массового импорта.