Pjandro ab8ea495a8 fix(app): 405/415 вместо catch-all 500; multipart-части на диске; heap в лимит контейнера
- ApiExceptionHandler: HttpRequestMethodNotSupportedException → 405,
  HttpMediaTypeNotSupportedException → 415 (JSON-контракт {error: …})
- file-size-threshold 100MB→2MB: части > 2 МБ на диск Tomcat, heap держит
  только getBytes() одной сериализованной конвертации (раньше каждая
  параллельная загрузка буферизовалась в heap до валидации размера)
- Containerfile ENTRYPOINT: -XX:MaxRAMPercentage=70; compose/compose.dev/
  прод-рендер: mem_limit: 2g у app
- ConvertController javadoc: ссылки на несуществующий ConversionService#validate нет
- Регрессии — ConvertControllerTest#methodNotSupportedReturns405/badContentTypeReturns415
2026-10-26 00:09:16 +00:00

java-word-pdf

Конвертация docx → PDF на чистом Java: docx4j + Apache FOP, без LibreOffice/Aspose. Шрифты упакованы в jar — конвертация не зависит от шрифтов, установленных в системе (работает «из коробки» на голом сервере).

Возможности

  • Поддержка RU/EN: кириллица и латиница встраиваются в PDF (embedded-подмножества).
  • Самодостаточность: TTF выгружаются из jar в временный каталог и регистрируются в docx4j/FOP.
  • Частые MS-шрифты подменяются метрически совместимыми open-source аналогами (см. «Шрифты» ниже).
  • Клиентская библиотека (wordpdf-core), REST API (wordpdf-app, Spring Boot) и веб-интерфейс (wordpdf-web, React SPA).

Структура

java-word-pdf/
├── wordpdf-core/   библиотека: конвертер, шрифты, маппинг
├── wordpdf-app/    REST API: POST /api/v1/convert (Spring Boot, Swagger UI)
└── wordpdf-web/    веб-интерфейс (React + TypeScript + Vite + Tailwind, вне Maven)

Ключевые классы (wordpdf-core):

Класс Назначение
ru.pjandro.wordpdf.WordPdfConverter публичный API: convert(byte[], String) — байты на входе, байты PDF на выходе
ru.pjandro.wordpdf.ConversionException исключение конвертации
ru.pjandro.wordpdf.fonts.BundledFonts выгрузка TTF из jar и регистрация в docx4j
ru.pjandro.wordpdf.fonts.BundledFontMapper маппинг имён шрифтов документа → TTF
ru.pjandro.wordpdf.internal.DocxOnOffNormalizer нормализация w:val="off"/"on" перед загрузкой
ru.pjandro.wordpdf.internal.FopFallbackFonts декларация fallback-семейства в FOP-конфиге

Инструменты проекта (mise)

Java, Maven, Node и Python для разработки ставит project-local mise: сам бинарь — в ./.mise/bin (gitignored), кеш инструментов — в user-директории mise, в систему ничего не устанавливается. Версии зафиксированы в корневом mise.toml (temurin-17, maven 3.9.16, node 24, python 3.15).

Первая настройка — скачивает mise, ставит инструменты и делает npm ci SPA:

sh bootstrap.sh    # Linux / macOS
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1    # Windows

Дальше команды — через обёртку ./mise.sh (Linux/macOS) или .\mise.ps1 (Windows):

./mise.sh run verify            # полный гейт перед push: тесты + PMD + JaCoCo
./mise.sh exec -- mvn -v        # любая команда с инструментами проекта в PATH
./mise.sh tasks                 # список задач с описаниями

Задачи проекта (./mise.sh run <задача>):

Задача Содержание
verify mvn clean verify — тесты + PMD + JaCoCo
app-package исполняемый jar бэкенда
app-run бэкенд на :8080, ключ выключен (после app-package)
web-install npm ci в wordpdf-web
web-build гейт SPA: tsc -b && vite build
web-lint oxlint
web-dev SPA на :5173, vite-proxy на :8080
prod-tests прод-автотесты; обязателен WORDPDF_BASE_URL, факультативно WORDPDF_API_KEY

Альтернатива обёртке — активировать mise в шелле и работать напрямую (mvn, npm, python): eval "$(./.mise/bin/mise activate bash)".

Сборка

Требуется Java 17 и Maven (бэкенд), Node.js ≥ 20.19 (веб-интерфейс) — всё это ставит project-local mise (см. «Инструменты проекта (mise)» выше). Команды ниже запускайте через ./mise.sh exec -- … (Windows: .\mise.ps1 exec -- …) либо после активации mise в шелле.

mvn clean verify                      # все модули + тесты
mvn -pl wordpdf-app -am package       # исполняемый jar бэкенда

Результат: wordpdf-app/target/wordpdf-app-<версия>.jar (все зависимости внутри). Для фронтенда — отдельный деп: npm install && npm run build в wordpdf-web/ (результат — статика в wordpdf-web/dist/).

Использование

REST API

java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf

POST /api/v1/convert принимает multipart-поле file (.docx) и синхронно возвращает байты PDF (application/pdf, attachment).

Код Смысл
200 PDF в теле ответа
400 некорректный вход: не .docx / пустой / не zip / > 5 МБ / > 100 страниц
413 тело запроса больше контейнерного лимита multipart (6 МБ)
503 очередь конвертации занята — повторить позже
504 конвертация дольше таймаута (wordpdf.convert-timeout, по умолчанию 2m)

Ошибки — JSON {"error": "..."}. Интерактивная документация: Swagger UI — /swagger-ui.html, OpenAPI — /v3/api-docs.

Библиотека

import ru.pjandro.wordpdf.WordPdfConverter;
import java.nio.file.Files;
import java.nio.file.Path;

byte[] docx = Files.readAllBytes(Path.of("doc.docx"));
byte[] pdf = WordPdfConverter.convert(docx, "doc");   // заголовок PDF
Files.write(Path.of("out.pdf"), pdf);

Ошибки валидации (не .docx по содержимому, размер больше 5 МБ, страниц больше ста) бросают ConversionException. Работа с файлами — забота вызывающего: ядро пути не принимает.

Веб-интерфейс и контейнеры (podman)

podman-compose up -d --build

Всё на http://localhost:8080/: nginx-контейнер web раздаёт SPA и проксирует /api, /swagger-ui, /v3/api-docs на бэкенд (контейнер app наружу не публикуется).

Dev-режим без контейнеров: бэкенд java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar (порт 8080) + npm run dev в wordpdf-web/ → http://localhost:5173 (Vite проксирует /api на 8080, CORS не нужен).

Шрифты

В wordpdf-core/src/main/resources/fonts/ упакованы 30 TTF: 7 текстовых семейств по 4 начертания плюс два покрывающих шрифта (только regular):

Семейство Аналог MS-шрифта
Carlito Calibri
Caladea Cambria
Arimo Arial
Tinos Times New Roman
Cousine Courier New
DejaVu Sans / DejaVu Serif fallback
Noto Naskh Arabic арабские дополнения U+07B1–U+08FF
Noto Sans Armenian армянские знаки Unicode 16

BundledFontMapper подставляет метрически совместимые аналоги при конвертации (Calibri → Carlito и т.д.). Нераспознанные шрифты и символы, не найденные в шрифте ранa (em-dash «—», кавычки, U+2000–U+2EFF), падают в DejaVu Sans (гарантированная кириллица). Знак, которого нет ни в шрифте ранa, ни там, куда его отправил docx4j, ищет себе место сам: GlyphCoverageNormalizer режет такой ран и для каждой части назначает покрывающее семейство — serif-раны в DejaVu Serif, sans — в DejaVu Sans, экзотика — в Noto. Все шрифты встраиваются в PDF как подмножества.

Лицензии шрифтов

  • Arimo, Cousine, Tinos, Carlito, Caladea — SIL OFL 1.1 (см. fonts/FONT-LICENSE.txt).
  • DejaVu Sans / DejaVu Serif — SIL OFL 1.1 / Bitstream Vera (см. fonts/DejaVu-LICENSE.txt).
  • Noto Naskh Arabic, Noto Sans Armenian — SIL OFL 1.1 (см. fonts/Noto-LICENSE.txt).

Как это работает

docx ──> нормализация байтов ──> docx4j (WordprocessingMLPackage)
     ──> XSL-FO (XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
  1. Байты .docx нормализуются, пока docx4j не увидел документ: DocxOnOffNormalizer (docx4j теряет w:val="off"/"on" при JAXB-разборе, из-за чего regular-раны могли рендериться жирным курсивом), SymbolFontNormalizer (маркеры из Symbol/Wingdings вместо «#») и FieldNormalizer (поля PAGE/NUMPAGES пересчитываются, а не печатают кэш из docx) и GlyphCoverageNormalizer (раны со знаками вне их шрифта).
  2. Документ загружается в WordprocessingMLPackage, привязывается BundledFontMapper, диаграммы и SmartArt предварительно растеризуются в PNG (DrawingPreRenderer).
  3. Экспорт в XSL-FO (XSLT-проход + WordLayoutFixups), затем Apache FOP рендерит PDF, встраивая используемые подмножества шрифтов.

Ограничения

  • Это не pixel-perfect рендер Word: раскладка, поля и некоторые эффекты приближённые (ограничения FOP/docx4j, а не «мы что-то упустили»).
  • Символы U+2000–U+2EFF (em-dash и т.п.) берутся из шрифта ранa, если в нём есть глиф, иначе — из fallback-семейства DejaVu.
  • Знаков, которых нет ни в одном шрифте бандла, это не касается: вместо них остаётся .notdef. В эталонном экспорте Word (develop/, вне git) таких два — U+2188 (ↈ) и U+218A (↊), они есть только в GNU FreeSerif под GPL, а бандл держится целиком на SIL OFL.
  • Поддержка таблиц/изображений — базовая (через docx4j/FOP).

Тесты

Тесты используют готовые .docx из wordpdf-core/src/test/resources/samples/ (генерируются POI) и проверяют извлечённый PDFBox'ом текст и встраивание шрифтов. Запуск: mvn test.

API (wordpdf-app) проверяется MockMvc-сквозняками (ConvertControllerTest) на тех же фикстурах — ядро отдаёт их test-jar'ом.

S
Description
No description provided
Readme 98 MiB
Languages
Java 95.6%
XSLT 2%
Python 0.9%
TypeScript 0.9%
Shell 0.3%
Other 0.2%