Files
java-word-pdf/README.md
T

176 lines
9.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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-конфиге |
## Сборка
Требуется **Java 21** и **Maven** (бэкенд), **Node.js ≥ 20.19** (веб-интерфейс).
```bash
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
```bash
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`.
### Библиотека
```java
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`. Работа с файлами — забота
вызывающего: ядро пути не принимает.
### Веб-интерфейс и Docker
```bash
docker compose up -d --build
```
Всё на `http://localhost:8080/`: nginx-контейнер `web` раздаёт SPA и проксирует
`/api`, `/swagger-ui`, `/v3/api-docs` на бэкенд (контейнер `app` наружу не
публикуется).
Dev-режим без Docker: бэкенд `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'ом.