Pjandro e9abcd38c8
PR checks / web (pull_request) Successful in 40s
PR checks / java (pull_request) Successful in 1m16s
Main: tests, deploy, autotests / java (push) Successful in 38s
Main: tests, deploy, autotests / web (push) Successful in 41s
Main: tests, deploy, autotests / images-web (push) Successful in 35s
Main: tests, deploy, autotests / images-app (push) Successful in 47s
Main: tests, deploy, autotests / deploy (push) Successful in 1m59s
Main: tests, deploy, autotests / autotests (push) Successful in 44s
Main: tests, deploy, autotests / rollback (push) Has been skipped
CI: единственный прогон тестов в контейнере без fontconfig
Хостовые Setup JDK/Maven/кеш~/.m2 и mvn на раннере убраны: полный
mvn clean verify (тесты + PMD + JaCoCo) исполняется только в образе
Containerfile.test (без libfontconfig и /etc/fonts). Отчёты JaCoCo
извлекаются из образа docker create/cp (отсутствие отчёта — пустая
сводка, не падение). mise verify остаётся сырым mvn без docker/podman.
2026-11-10 01:09:13 +03:00

java-word-pdf

Конвертация .docx/.doc → PDF на чистом Java: docx4j 17.3.2 + форк Apache FOP, без LibreOffice/Aspose. Бинарный .doc (Word 97–2003) читается собственным мостом [MS-DOC]/[MS-CFB] и переносится в .docx в памяти — дальше идёт тем же конвейером. Шрифты упакованы в jar — конвертация не зависит от шрифтов, установленных в системе (работает «из коробки» на голом сервере).

Возможности

  • Поддержка RU/EN: кириллица и латиница встраиваются в PDF (embedded-подмножества).
  • Самодостаточность: TTF выгружаются из jar в временный каталог и регистрируются в docx4j/FOP.
  • Частые MS-шрифты подменяются метрически совместимыми open-source аналогами (см. «Шрифты» ниже).
  • Диаграммы и SmartArt растеризуются в PNG собственным Java2D-движком — без Word/LibreOffice.
  • Бинарный .doc (Word 97–2003): текст, стили, таблицы, списки, колонтитуки, картинки — собственный мост internal/doc без внешних зависимостей; error-флаги диаграмм/SmartArt/OLE на .doc не срабатывают (BLIP-плейсхолдеры уже растры → вставляются картинками; EMF/WMF/PICT пропускаются с warn).
  • OLE-внедрения вычищаются перед загрузкой; картинка-плейсхолдер из документа сохраняется.
  • Клиентская библиотека (wordpdf-core), REST API (wordpdf-app, Spring Boot) и веб-интерфейс (wordpdf-web, React SPA).

Структура

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

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

Класс Назначение
ru.pjandro.wordpdf.WordPdfConverter публичный API: convert(byte[], String, ConvertOptions) — .docx/.doc по сигнатуре байтов, байты PDF на выходе; warmup() — прогрев ядра
ru.pjandro.wordpdf.WordPdfValidator валидация входа и lightweight-оценка страниц без рендера (checkInput/validate; подсчёт страниц — внутренний метод)
ru.pjandro.wordpdf.ConvertOptions опции конвертации (record errorOnCharts, errorOnSmartArt, errorOnOle, maxMb, maxPages); дефолтов в ядре нет — значения задаёт вызывающий
ru.pjandro.wordpdf.ConversionException ошибки конвертации; подтипы ValidationException (некорректный вход) и DrawingFoundException (enum Kind {CHARTS, SMARTART, OLE})
ru.pjandro.wordpdf.fonts.BundledFonts выгрузка TTF из jar и регистрация в docx4j
ru.pjandro.wordpdf.fonts.BundledFontMapper маппинг имён шрифтов документа → TTF
ru.pjandro.wordpdf.internal.DocxRewritePipeline правила 1–10 нормализации XML-частей одним zip-проходом (+ OleObjectNormalizer, правило 11)
ru.pjandro.wordpdf.internal.doc.DocToDocx мост бинарного .doc → in-memory .docx (convert/countPages)
ru.pjandro.wordpdf.internal.FopFallbackFonts декларация fallback-семейства в FOP-конфиге
ru.pjandro.wordpdf.internal.chart.DrawingPreRenderer диаграммы/SmartArt → PNG до XSL-FO

Инструменты проекта (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
verify-nofontconfig mvn clean verify в контейнере без fontconfig (гейт CI; требует podman/docker)
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.0 || >=22.12.0 (engines Vite 8; mise ставит Node 24) — всё это ставит 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 (все зависимости внутри). Для фронтенда — отдельные команды (вне Maven): npm ci && npm run build в wordpdf-web/ — по закоммиченному package-lock.json (то же делают задачи mise web-install/web-build; результат — статика в wordpdf-web/dist/).

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

REST API

java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
curl -H "X-API-Key: $WORDPDF_API_KEY" -F "file=@doc.docx" \
    http://localhost:8080/api/v1/convert -o doc.pdf

POST /api/v1/convert принимает multipart-поле file (.docx или .doc) и синхронно возвращает байты PDF (application/pdf, Content-Disposition: attachment; filename*=UTF-8''… — имя файла санитизировано, кириллица разрешена).

Ключ доступа. Заголовок X-API-Key сверяется со свойством wordpdf.api-key (env WORDPDF_API_KEY); пустое свойство — аутентификация выключена (java -jar, dev-стенд). Без ключа открыты /actuator/, /swagger-ui, /v3/api-docs; без ключа или с неверным — 401 {"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}.

Факультативные query/form-параметры errorOnCharts/errorOnSmartArt/errorOnOle (Boolean, дефолт false): при true соответствующие объекты в документе отменяют конвертацию с 422. Диаграммы/SmartArt конвертируются в растры всегда; OLE-объекты при errorOnOle=false тихо удаляются.

Лимиты входа: свойства wordpdf.max-mb/wordpdf.max-pages (env WORDPDF_MAX_MB/WORDPDF_MAX_PAGES, дефолты 5 МБ / 100 страниц) — дефолт эндпоинта; query/form-параметры maxMb/maxPages переопределяют его в обе стороны (значения ≤ 0 → 400). Остальные пороги (распаковка архива, XML-части, площади растров, число записей zip) выводятся из лимитов входа.

Код Смысл
200 PDF в теле ответа
400 некорректный вход (пустой / расширение не .docx/.doc / содержимое не zip и не CFB / зашифрованный .doc / больше лимита размера (maxMb или wordpdf.max-mb) / больше лимита страниц (maxPages или wordpdf.max-pages) / maxMb≤0 / maxPages≤0), отсутствующая часть file, некорректное значение error-флага
401 нет или неверен X-API-Key
404 неизвестный путь (в т.ч. /v3/api-docs при выключенном springdoc)
405 не-POST
413 тело запроса больше контейнерного лимита multipart (100 МБ; авторитетный лимит входа — wordpdf.max-mb, он даёт 400 раньше)
415 не-multipart тело
422 сработал error-флаг: в документе найдены диаграммы / SmartArt / OLE-объекты
500 ошибка ядра/рендера
503 очередь конвертации (16 мест) переполнена — повторить позже
504 конвертация дольше wordpdf.convert-timeout (по умолчанию 2m)

Ошибки — JSON {"error": "..."}. Конвертации сериализуются одним воркером: ядро мутирует глобальный реестр шрифтов; головой очереди на старте стоит warmup() — первый запрос после деплоя идёт за прогретым ядром (~0,1–0,4 с вместо 1,4–1,9 с). Интерактивная документация: Swagger UI — /swagger-ui.html, OpenAPI — /v3/api-docs (доступны на java -jar и dev-стенде; в compose-стеке springdoc выключён: SPRINGDOC_API_DOCS_ENABLED=false, SPRINGDOC_SWAGGER_UI_ENABLED=false).

Библиотека

import ru.pjandro.wordpdf.WordPdfConverter;
import ru.pjandro.wordpdf.ConvertOptions;
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
// с опциями: errorOnCharts/errorOnSmartArt/errorOnOle, лимиты МБ/страниц
pdf = WordPdfConverter.convert(docx, "doc", new ConvertOptions(true, false, false, 5, 100));
Files.write(Path.of("out.pdf"), pdf);

Ошибки валидации (содержимое не .docx/не .doc по сигнатуре, размер больше 5 МБ, страниц больше ста, зашифрованный .doc) бросают ValidationException (подтип ConversionException). Формат определяется по сигнатуре байтов: PK\x03\x04 → .docx-путь, CFB-подпись D0 CF 11 E0 A1 B1 1A E1 → мост → тот же конвейер. Те же проверки без рендера доступны отдельно: WordPdfValidator.validate(bytes, options). Работа с файлами — забота вызывающего: ядро пути не принимает.

Зависимость commons-compress (интеграция в чужой проект)

Ядру (через docx4j) нужен org.apache.commons:commons-compress >= 1.25.0, рекомендована 1.28.0 — версию закрепляет POM ядра. Симптом старой версии в classpath потребителя — NoSuchMethodError: org.apache.commons.compress.archivers.zip.ZipArchiveEntry org.apache.commons.compress.archivers.zip.ZipArchiveInputStream.getNextEntry(). До входа в docx4j теперь срабатывает guard: ConversionException с текстом, объясняющим, какую версию закрепить.

Maven. BOM (например, Spring Boot 3.x) пинит свою версию commons-compress, а dependencyManagement потребителя перекрывает транзитивные версии («nearest wins») — закреплять нужно именно в нём:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-compress</artifactId>
            <version>1.28.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

Диагностика: mvn dependency:tree -Dincludes=org.apache.commons:commons-compress.

Gradle. По умолчанию Gradle выбирает максимальную версию и конфликт разрешает сам — guard не сработает и не нужен. Понижает версию только явный constraints / platform / resolutionStrategy: уберите понижение либо закрепите нужную версию:

dependencies {
    constraints {
        implementation("org.apache.commons:commons-compress:1.28.0")
    }
}

(либо resolutionStrategy.force("org.apache.commons:commons-compress:1.28.0")). Диагностика: gradle dependencies --configuration runtimeClasspath.

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

cp .env.example .env    # WORDPDF_API_KEY: openssl rand -hex 32
podman-compose up -d --build

Наружный вход — nginx-контейнер gateway на http://localhost:9010/ (контейнер app наружу не публикуется). Файл compose.yml fail-closed: без WORDPDF_API_KEY в .env стек не поднимется. Маршруты gateway: /api/, /swagger-ui, /v3/api-docs, /actuator → app:8080 (таймауты прокси 300s, client_max_body_size 100m), остальное → web — чистая статика SPA.

Dev-стенд без ключа, с включённым springdoc:

podman-compose -f compose.dev.yml up -d --build --force-recreate   # http://<LAN-IP>:9011

(--force-recreate обязателен: без него podman-compose пересоберёт образ, но контейнеры оставит на старом — будет крутиться jar прошлой сборки)

Dev-режим без контейнеров: бэкенд java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar (порт 8080, ключ выключен) + npm run dev в wordpdf-web/ → http://localhost:5173 (Vite проксирует /api, /swagger-ui, /v3/api-docs на 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/.doc ──> валидация входа ──> (.doc: мост → .docx в памяти)
     ──> нормализация байтов ──> docx4j (WordprocessingMLPackage)
     ──> диаграммы → PNG ──> XSL-FO (вендорный XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
  1. Вход проверяется до рендера: размер → сигнатура (zip PK или CFB) → (.docx: контейнер и страницы lightweight-StAX по zip; .doc: страницы по чистому бинарному документу мостом) — WordPdfValidator, без зависимости от docx4j.
  2. XML-части переписывает DocxRewritePipeline одним zip-проходом — десять правил (порядок значим): strict→transitional (w:start/w:end, проценты), on/off → true/false (иначе docx4j теряет значение, и regular-раны рендерились жирным курсивом), маркеры Symbol/Wingdings → Unicode (вместо «#»), поля PAGE/NUMPAGES → w:fldSimple (пересчитываются, а не печатают кэш из docx), невидимые символы, раны со знаками вне их шрифта (резка по покрытию глифов), w:jc center/right + w:tblInd → абсолютный отступ таблицы, w:suff="space" → пробел в номере списка, скрытые раны (w:vanish), руби (надстрочница вырезается). Затем вычищаются OLE-объекты (правило 11, OleObjectNormalizer, картинка-плейсхолдер сохраняется).
  3. Документ загружается в WordprocessingMLPackage, привязывается BundledFontMapper.
  4. Диаграммы и SmartArt предварительно растеризуются в PNG 300 dpi (DrawingPreRenderer) — XSLT-экспорт docx4j их не умеет.
  5. Экспорт в XSL-FO идёт вендорным стилем xslt/docx2fo.xslt (копия стилиста docx4j-export-fo с AUDIT-FIX-патчами: w:position → baseline-shift, w:moveFrom/w:moveTo/w:bdo/w:dir), перед рендером LayoutPostRenderer компенсирует расхождение docx4j↔Word по padding таблиц; Apache FOP (форк docx4j-fo-renderer) рендерит 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).
  • Часть расхождений с Word — неустранимые невозможности FOP/docx4j (jc="distribute", suff="tab", кернинг, framePr, кэш REF/SEQ/TOC, надстрочница руби) — полный перечень с доказательствами: docs/agent/render-limitations.md.
  • На .doc error-флаги диаграмм/SmartArt/OLE не срабатывают: BLIP-плейсхолдеры бинарного формата — уже растры, они вставляются картинками; EMF/WMF/PICT пропускаются с warn.

Тесты

Тесты используют 25 закоммиченных фикстур (13 .docx + 12 .doc) из wordpdf-core/src/test/resources/samples/ (в тестах не генерируются; пересоздание — test-утилита SampleDocxGenerator) и проверяют извлечённый PDFBox'ом текст и встраивание шрифтов. Запуск: mvn test; полный гейт перед push — ./mise.sh run verify (тесты + PMD + JaCoCo).

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

CI/CD и деплой

  • Pull request → Gitea Actions (pr.yml): Java — единственный mvn clean verify в контейнере без fontconfig + сводка покрытия комментарием в PR; Web — npm ci, build, lint.
  • Push в main → main.yml: тесты → сборка и push образов wordpdf-app/wordpdf-web в реестр → deploy (job рендерит прод-конфиги, podman-compose pull && up -d --force-recreate, health-гейты, автооткат при провале) → prod-автотесты против живого стенда.
  • Координаты прод-сервера и креды вне репозитория — Gitea Actions Variables/Secrets (настройка: GITEA-vars.md). Наружный вход стенда — путь /pdf-converter/ за пользовательским nginx.
  • Локальный прогон prod-автотестов (задача prod-tests: pip install зависимостей + pytest -q . в prod-autotests/):
WORDPDF_BASE_URL=<стенд> WORDPDF_API_KEY=<ключ> ./mise.sh run prod-tests

31 проверка; без ключа 27 требующих его пропускаются.

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%