docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
This commit is contained in:
@@ -0,0 +1,75 @@
|
||||
# API библиотеки
|
||||
|
||||
Публичный API мал и стабилен: два сервисных класса, один record, пять видов ошибок.
|
||||
Javadoc каждого члена — [apidocs](/apidocs/index.html).
|
||||
|
||||
## `WordPdfConverter`
|
||||
|
||||
```java
|
||||
public final class WordPdfConverter {
|
||||
public static byte[] convert(byte[] docxBytes, String title, ConvertOptions options)
|
||||
throws ConversionException;
|
||||
public static synchronized void warmup();
|
||||
}
|
||||
```
|
||||
|
||||
- `convert` — единственный путь конвертации (двухаргументной перегрузки **нет**).
|
||||
Принимает байты `.docx` или `.doc` (маршрутизация по сигнатуре), возвращает байты PDF.
|
||||
`title` — заголовок PDF. `options == null` → `ValidationException`.
|
||||
- `warmup()` — идемпотентный прогрев конвейера; не бросает.
|
||||
|
||||
## `WordPdfValidator`
|
||||
|
||||
Те же проверки входа **без рендера** — например, для валидации загрузки до очереди:
|
||||
|
||||
```java
|
||||
public static void checkInput(byte[] docxBytes, long maxMb) throws ValidationException;
|
||||
public static void validate(byte[] docxBytes, ConvertOptions options) throws ValidationException;
|
||||
```
|
||||
|
||||
Проверяются: непустота, размер (`maxMb`), сигнатура (zip/CFB), для docx — контейнер
|
||||
(`[Content_Types].xml` с типом документа), производные пороги (распаковка, XML,
|
||||
растры, записи zip), число страниц (lightweight-скан, без docx4j; для `.doc` —
|
||||
по сырым байтам мостом).
|
||||
|
||||
## `ConvertOptions`
|
||||
|
||||
```java
|
||||
public record ConvertOptions(boolean errorOnCharts, boolean errorOnSmartArt,
|
||||
boolean errorOnOle, long maxMb, int maxPages) {}
|
||||
```
|
||||
|
||||
**Порядок полей фиксирован.** `maxMb`/`maxPages` должны быть больше 0. Дефолтов
|
||||
в ядре нет — значения задаёт вызывающий. Диаграммы/SmartArt конвертируются всегда;
|
||||
флаги только отменяют конвертацию находкой.
|
||||
|
||||
## Ошибки
|
||||
|
||||
```
|
||||
ConversionException (RuntimeException)
|
||||
├── ValidationException — вход некорректен (не docx/doc, размер, страницы, битый zip…)
|
||||
├── ChartsFoundException — errorOnCharts и найдены диаграммы
|
||||
├── SmartArtFoundException — errorOnSmartArt и найден SmartArt
|
||||
└── OleFoundException — errorOnOle и найдены OLE-объекты
|
||||
```
|
||||
|
||||
Ловите `ConversionException` — он покрывает всё; `ValidationException` — отдельно,
|
||||
когда хотите различать «пользователь прислал мусор» и «конвертер не смог».
|
||||
|
||||
## Инвариант параллельности
|
||||
|
||||
`convert` **потокобезопасен, но сериализован**: все конвертации идут под монитором
|
||||
класса `WordPdfConverter.class` — ядро мутирует глобальный реестр шрифтов docx4j
|
||||
(`PhysicalFonts`). Параллельные вызовы корректны, но исполняются последовательно;
|
||||
собственный пул/очередь с отказом при переполнении — забота вызывающего
|
||||
(так делает `wordpdf-app`: один воркер, очередь 16).
|
||||
|
||||
## Шрифты и окружение
|
||||
|
||||
- Шрифты выгружаются из jar во временный каталог; реестр после каждой конвертации
|
||||
возвращается к бандлу — встроенные в чужие docx шрифты не «травят» последующие
|
||||
конвертации.
|
||||
- `java.awt.Font` не используется (глифы — fontbox напрямую): **fontconfig хосту не нужен**,
|
||||
контейнер без `/etc/fonts` работает.
|
||||
- Нужен SLF4J-провайдер (см. [первые шаги](getting-started.md)) — иначе текст
|
||||
предупреждений попадает в PDF.
|
||||
@@ -0,0 +1,66 @@
|
||||
# Зависимости потребителя
|
||||
|
||||
## commons-compress: единственная ловушка интеграции
|
||||
|
||||
Ядру (транзитивно, через docx4j) нужен `org.apache.commons:commons-compress`
|
||||
**≥ 1.25.0**, рекомендован **1.28.0** — версию закрепляет POM `wordpdf-core`.
|
||||
Симптом старой версии в classpath потребителя:
|
||||
|
||||
```
|
||||
NoSuchMethodError: org.apache.commons.compress.archivers.zip.ZipArchiveEntry
|
||||
org.apache.commons.compress.archivers.zip.ZipArchiveInputStream.getNextEntry()
|
||||
```
|
||||
|
||||
До входа в docx4j теперь срабатывает guard (`DependencyGuard`): вместо мутного
|
||||
`NoSuchMethodError` внутри docx4j — `ConversionException` с текстом, объясняющим,
|
||||
какую версию закрепить.
|
||||
|
||||
### Maven: закреплять в `dependencyManagement`
|
||||
|
||||
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>
|
||||
```
|
||||
|
||||
Диагностика:
|
||||
|
||||
```bash
|
||||
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`.
|
||||
|
||||
## Прочие транзитивные зависимости
|
||||
|
||||
|Артефакт|Зачем|Нужно ли трогать|
|
||||
|---|---|---|
|
||||
|`docx4j-export-fo` (+ форк FOP `docx4j-fo-renderer*`)|конвейер XSL-FO → PDF|нет|
|
||||
|`slf4j-simple`|единственный SLF4J-провайдер из коробки — без провайдера docx4j пишет «TO HIDE THESE MESSAGES» в PDF|исключить, если у приложения свой провайдер|
|
||||
|`jcl-over-slf4j`|мост commons-logging (pdfbox/fontbox) → slf4j|нет (`commons-logging` исключён)|
|
||||
|`fontbox`|чтение TTF напрямую, без `java.awt.Font`|нет|
|
||||
@@ -0,0 +1,72 @@
|
||||
# wordpdf-core: первые шаги
|
||||
|
||||
`wordpdf-core` — Java-библиотека конвертации `.docx`/`.doc` → PDF. Без LibreOffice,
|
||||
без Aspose, без системных шрифтов: все TTF упакованы в jar.
|
||||
|
||||
## Подключение
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>ru.pjandro</groupId>
|
||||
<artifactId>wordpdf-core</artifactId>
|
||||
<version>1.0.0</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
Требуется **Java 17**. Единственный обязательный аспект интеграции — версия
|
||||
`commons-compress` (см. [Зависимости](dependencies.md)).
|
||||
|
||||
## Минимальный пример
|
||||
|
||||
```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",
|
||||
new ru.pjandro.wordpdf.ConvertOptions(false, false, false, 5, 100));
|
||||
Files.write(Path.of("out.pdf"), pdf);
|
||||
```
|
||||
|
||||
Второй аргумент — заголовок PDF (пустой/`null` — без заголовка). Работа с файлами —
|
||||
забота вызывающего: ядро пути не принимает, только байты.
|
||||
|
||||
Формат входа определяется **по сигнатуре байтов**, расширение имени файла ядру
|
||||
неизвестно:
|
||||
|
||||
|Сигнатура|Маршрут|
|
||||
|---|---|
|
||||
|`PK\x03\x04`|zip → OOXML-путь (docx4j)|
|
||||
|`D0 CF 11 E0 A1 B1 1A E1`|CFB → мост .doc → .docx в памяти → тот же конвейер|
|
||||
|
||||
## Опции конвертации
|
||||
|
||||
`ConvertOptions` — record из пяти полей (детали в [API библиотеки](api.md)):
|
||||
error-флаги диаграмм/SmartArt/OLE и лимиты размера/страниц. Дефолтов в ядре нет —
|
||||
все пять значений задаёт вызывающий:
|
||||
|
||||
```java
|
||||
// отменить конвертацию, если в документе есть диаграммы; лимиты 10 МБ / 200 страниц
|
||||
var opts = new ConvertOptions(true, false, false, 10, 200);
|
||||
byte[] pdf = WordPdfConverter.convert(bytes, "Отчёт", opts);
|
||||
```
|
||||
|
||||
## Прогрев
|
||||
|
||||
Первая конвертация после старта JVM стоит ~1,3–1,7 с (инициализация JAXB/XSLT/FOP).
|
||||
`WordPdfConverter.warmup()` прогоняет весь конвейер на минимальном встроенном docx
|
||||
и идемпотентен (повторные вызовы — no-op); бросать не должен никогда — решение
|
||||
о реакции на сбой прогревает код. Вызывайте на старте приложения, если не хотите,
|
||||
чтобы первый пользователь платил за инициализацию:
|
||||
|
||||
```java
|
||||
WordPdfConverter.warmup(); // ~1,5–2,5 с, один раз при старте
|
||||
```
|
||||
|
||||
## Провайдер логов
|
||||
|
||||
В classpath потребителя **обязан быть SLF4J-провайдер**. Без него docx4j пишет
|
||||
предупреждение «TO HIDE THESE MESSAGES…» **прямо в выходной PDF**. В jar `wordpdf-core`
|
||||
для этого включён `slf4j-simple`; если ваше приложение приносит свой провайдер
|
||||
(logback и т.п.) — исключите `slf4j-simple` из транзитивных зависимостей.
|
||||
Reference in New Issue
Block a user