checkDocxContainer получает бюджеты параметром; validate считает их из ConvertOptions.maxMb()/maxPages(): clamp(maxMb×10MiB + maxPages×64KiB, 16MiB, MAX_DECOMPRESSED_MB) и clamp(maxMb×4MiB + maxPages×32KiB, 4MiB, MAX_DECOMPRESSED_XML_MB) (коэффициенты/полы — package-private константы WordPdfConverter, compile-time инлайн — WordPdfValidator по-прежнему без зависимости от docx4j). Константы WordPdfSettings — жёсткие крышки (публичный API, защита JAXB DOM). Сообщения печатают вычисленный бюджет. Тесты: пол (16 МБ при maxMb=1), масштабирование и крышка (64 МБ при maxMb=10); доки синхронизированы.
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/checkPageCount/checkPageCountDoc/isBinaryDoc/validate) |
ru.pjandro.wordpdf.ConvertOptions |
опции конвертации (record errorOnCharts, errorOnSmartArt, errorOnOle, maxMb, maxPages; ConvertOptions.defaults()) |
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 |
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 страниц); параметрами
запроса не переопределяются.
| Код | Смысл |
|---|---|
| 200 | PDF в теле ответа |
| 400 | некорректный вход (пустой / расширение не .docx/.doc / содержимое не zip и не CFB / зашифрованный .doc / больше wordpdf.max-mb / больше wordpdf.max-pages страниц), отсутствующая часть 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-шрифты)
- Вход проверяется до рендера: размер → сигнатура (zip PK или CFB) → (.docx:
контейнер и страницы lightweight-StAX по zip; .doc: страницы по чистому
бинарному документу мостом) —
WordPdfValidator, без зависимости от docx4j. - XML-части переписывает
DocxRewritePipelineодним zip-проходом — десять правил (порядок значим): strict→transitional (w:start/w:end, проценты),on/off→true/false(иначе docx4j теряет значение, и regular-раны рендерились жирным курсивом), маркеры Symbol/Wingdings → Unicode (вместо «#»), поляPAGE/NUMPAGES→w:fldSimple(пересчитываются, а не печатают кэш из docx), невидимые символы, раны со знаками вне их шрифта (резка по покрытию глифов),w:jccenter/right +w:tblInd→ абсолютный отступ таблицы,w:suff="space"→ пробел в номере списка, скрытые раны (w:vanish), руби (надстрочница вырезается). Затем вычищаются OLE-объекты (правило 11,OleObjectNormalizer, картинка-плейсхолдер сохраняется). - Документ загружается в
WordprocessingMLPackage, привязываетсяBundledFontMapper. - Диаграммы и SmartArt предварительно растеризуются в PNG 300 dpi
(
DrawingPreRenderer) — XSLT-экспорт docx4j их не умеет. - Экспорт в 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. - На
.docerror-флаги диаграмм/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+ сводка покрытия комментарием в 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 требующих его пропускаются.