mufassall

Шпаргалка · Бизнес-процессы

Массовый импорт

13 мин · Средний · mufassall.dtwin.uz/ru/l/bulk-import/

← Открыть урок

Проблема

Оптовая компания загружает каталог товаров в CSV: 200 000 строк. Разбор прямо в запросе падает по таймауту, съедает память и выбрасывает всё из-за одной плохой строки. Вместо этого файл уходит в объектное хранилище, задача импорта читает его потоком, проверяет каждую строку и отдаёт отчёт об ошибках, переживает перезапуски и повторные загрузки, пишет короткими пачками, показывает прогресс и держится в лимитах на тенанта.

Чему вы научитесь

  • Почему большой файл идёт прямо в объектное хранилище по pre-signed URL и читается воркером, а не веб-сервером
  • Проверка каждой строки с номерами строк и скачиваемым отчётом об ошибках: частичный успех это норма
  • Дедупликация по хешу файла, чекпоинт каждые N строк и пакетные upsert, которые держат блокировки основной таблицы коротко
  • Прогресс, который UI может опрашивать, и лимиты на тенанта по размеру файла, строкам и запущенным задачам
Итоговая сцена
30%60%45%

Диаграмма как код

Итоговая схема урока в виде текста: вставьте её в 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_db

Mermaid: последовательность запросов

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 Requests

D2

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_db

PlantUML: последовательность запросов

@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
@enduml

PlantUML: компоненты

@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%
Память API180 МБ60 МБ
Ожидание блокировки0 с0 с

Шаги

  1. Кейс Веб-сервер разбирает файл прямо в запросе

    Бухгалтер загружает каталог товаров из старой системы в CSV.

  2. Проблема 200 000 строк: таймаут, память, одна плохая строка

    Теперь файл весит 41,9 МБ, 200 000 строк.

  3. Решение Загрузка прямо в объектное хранилище

    Сначала браузер просит у API URL для загрузки.

  4. Решение Задача импорта и воркер, читающий файл потоком

    Браузер говорит API: импортируй этот файл.

  5. Решение Проверять каждую строку, собирать ошибки, хорошие строки сохранять

    Воркер проверяет каждую строку отдельно: обязательные поля, числа, единицы измерения, дубли внутри файла.

  6. Проблема Перезапуск начинает сначала, повторная загрузка запускает новую задачу

    Деплой перезапускает воркер на строке 122 000.

  7. Решение Хеш файла для дедупликации, чекпоинт каждые 1 000 строк

    Каждые 1 000 строк воркер сохраняет своё место в записи задачи: последнюю готовую строку и счётчики.

  8. Проблема Одна гигантская запись блокирует каталог

    Запись по одной строке это 200 000 походов в базу, около 7 минут.

  9. Решение Пакетный upsert по естественному ключу

    Воркер пишет 1 000 строк одним запросом: новые товары вставляет, существующие обновляет, сопоставляя по тенанту и SKU.

  10. Решение Прогресс, который UI может опрашивать

    Страница каждые 2 секунды опрашивает задачу и рисует полосу: строк готово, ошибок на сейчас, сколько осталось.

  11. Решение Лимиты на тенанта

    Один тенант запускает сразу шесть импортов файлов по 2 ГБ, и задачи всех остальных ждут за ними.

  12. Итоги Итог

    Шесть правил массового импорта.

Термины

Upsert
Одним запросом вставить строку или обновить её, если строка с таким ключом уже есть (ON CONFLICT ... DO UPDATE). Повтор безвреден.
Чекпоинт
Позиция, которую длинная задача сохраняет с каждой закоммиченной пачкой, чтобы после перезапуска продолжить оттуда, а не начинать заново.