361 lines
24 KiB
Markdown
361 lines
24 KiB
Markdown
# java-word-pdf
|
||
|
||
Конвертация **.docx/.doc → PDF** на чистом Java: `docx4j` 17.3.6 + форк
|
||
`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–8 нормализации XML-частей одним zip-проходом (+ `OleObjectNormalizer`, правило 9)|
|
||
|`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:
|
||
|
||
```bash
|
||
sh bootstrap.sh # Linux / macOS
|
||
```
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
|
||
```
|
||
|
||
Дальше команды — через обёртку `./mise.sh` (Linux/macOS) или `.\mise.ps1` (Windows):
|
||
|
||
```bash
|
||
./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 в шелле.
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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`).
|
||
|
||
### Библиотека
|
||
|
||
```java
|
||
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») — закреплять нужно именно в нём:
|
||
|
||
```xml
|
||
<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`: уберите понижение либо
|
||
закрепите нужную версию:
|
||
|
||
```kotlin
|
||
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)
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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-раны
|
||
рендерились жирным курсивом), невидимые символы, раны со знаками вне их
|
||
шрифта (резка по покрытию глифов), `w:jc` center/right + `w:tblInd` →
|
||
абсолютный отступ таблицы, `w:suff="space"` → пробел в номере списка,
|
||
скрытые раны (`w:vanish`), руби (надстрочница вырезается). Маркеры
|
||
Symbol/Wingdings и поля `PAGE`/`NUMPAGES` не переписываем — с docx4j 17.3.x
|
||
экспорт делает это сам (маркеры → Unicode, complex-поля → пересчёт вместо
|
||
кэша). Затем вычищаются OLE-объекты (правило 9,
|
||
`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"`, кернинг, кэш `REF`/`SEQ`/`TOC`,
|
||
надстрочница руби) — полный перечень с доказательствами:
|
||
`docs/agent/render-limitations.md`. `w:framePr` с docx4j 17.3.6 позиционируется.
|
||
- На `.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` + сводка покрытия комментарием в 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/`):
|
||
|
||
```bash
|
||
WORDPDF_BASE_URL=<стенд> WORDPDF_API_KEY=<ключ> ./mise.sh run prod-tests
|
||
```
|
||
|
||
31 проверка; без ключа 27 требующих его пропускаются.
|