fix(core): DependencyGuard — понятная ошибка при старой commons-compress у потребителя #56

Merged
pjandro merged 1 commits from commons-compress-guard into main 2026-10-26 12:43:40 +03:00
7 changed files with 165 additions and 3 deletions
+2 -2
View File
@@ -51,7 +51,7 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр
|---|---| |---|---|
|`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API: `WordPdfConverter`, `WordPdfValidator` (перегрузки `checkInput`/`checkPageCount` и `validate(byte[], ConvertOptions)` — полная цепочка; без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `DrawingFoundException` (`enum Kind {CHARTS, SMARTART, OLE}` — отказ по error-флагу), `WordPdfSettings` (константы-дефолты: `MAX_INPUT_MB=5`, `MAX_PAGES=100`, защитные `MAX_DECOMPRESSED_MB=200`/`MAX_ZIP_ENTRIES=8192`, `ERROR_ON_CHARTS/SMARTART/OLE=false`), `ConvertOptions` (record: errorOnCharts, errorOnSmartArt, errorOnOle, maxMb, maxPages)| |`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API: `WordPdfConverter`, `WordPdfValidator` (перегрузки `checkInput`/`checkPageCount` и `validate(byte[], ConvertOptions)` — полная цепочка; без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `DrawingFoundException` (`enum Kind {CHARTS, SMARTART, OLE}` — отказ по error-флагу), `WordPdfSettings` (константы-дефолты: `MAX_INPUT_MB=5`, `MAX_PAGES=100`, защитные `MAX_DECOMPRESSED_MB=200`/`MAX_ZIP_ENTRIES=8192`, `ERROR_ON_CHARTS/SMARTART/OLE=false`), `ConvertOptions` (record: errorOnCharts, errorOnSmartArt, errorOnOle, maxMb, maxPages)|
|`…/wordpdf/fonts/`|`BundledFonts` (реестр/выгрузка TTF, `families()`, `FALLBACK_FAMILY`), `BundledFontMapper` (алиасы MS→open-source, self-map, DISPLAY_NAMES, public-хук `bundledFamily`), `GlyphFont` (глиф-движок fontbox: метрики/глифы без java.awt.Font)| |`…/wordpdf/fonts/`|`BundledFonts` (реестр/выгрузка TTF, `families()`, `FALLBACK_FAMILY`), `BundledFontMapper` (алиасы MS→open-source, self-map, DISPLAY_NAMES, public-хук `bundledFamily`), `GlyphFont` (глиф-движок fontbox: метрики/глифы без java.awt.Font)|
|`…/wordpdf/internal/`|7 байтовых нормализаторов + интерфейс `DocxNormalizer` + `FopFallbackFonts` (классы `public` — вызываются из родительского пакета; публичные члены только `normalize`/`STEP`/`declare`; `OleObjectNormalizer` — многочастный, публичный `normalize(byte[], boolean)`, бросает `DrawingFoundException(OLE)`)| |`…/wordpdf/internal/`|7 байтовых нормализаторов + интерфейс `DocxNormalizer` + `FopFallbackFonts` + `DependencyGuard` (проверка совместимости commons-compress, шаг 0 `convertToStream`) (классы `public` — вызываются из родительского пакета; публичные члены только `normalize`/`STEP`/`declare`/`DependencyGuard.check`; `OleObjectNormalizer` — многочастный, публичный `normalize(byte[], boolean)`, бросает `DrawingFoundException(OLE)`)|
|`…/wordpdf/internal/chart/`|17 классов Java2D-рендера диаграмм/SmartArt в PNG (public только `DrawingPreRenderer`)| |`…/wordpdf/internal/chart/`|17 классов Java2D-рендера диаграмм/SmartArt в PNG (public только `DrawingPreRenderer`)|
|`wordpdf-core/src/main/resources/fonts/`|30 TTF + 3 лицензии — бинарные фикстуры, часть jar| |`wordpdf-core/src/main/resources/fonts/`|30 TTF + 3 лицензии — бинарные фикстуры, часть jar|
|`wordpdf-core/src/test/resources/samples/`|13 закоммиченных `.docx`-фикстур (единственные .docx-фикстуры), все проходят `docs/standards/validate-fixtures.py`| |`wordpdf-core/src/test/resources/samples/`|13 закоммиченных `.docx`-фикстур (единственные .docx-фикстуры), все проходят `docs/standards/validate-fixtures.py`|
@@ -127,7 +127,7 @@ gateway). Кеш раннеров — сервер act_runner (серверна
- Ошибки публичного API — только `ConversionException extends RuntimeException`; внутренние исключения оборачиваются на границе. В chart — деградация вместо падения. - Ошибки публичного API — только `ConversionException extends RuntimeException`; внутренние исключения оборачиваются на границе. В chart — деградация вместо падения.
- Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`) — новый фикс оформлять так же (в существующем main-коде convention соблюдён лишь частично — `SymbolFontNormalizer`, `WordPdfValidator`, `Surface3dPainter` и классы app; новые правки обязаны ссылаться). - Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`) — новый фикс оформлять так же (в существующем main-коде convention соблюдён лишь частично — `SymbolFontNormalizer`, `WordPdfValidator`, `Surface3dPainter` и классы app; новые правки обязаны ссылаться).
- Константы UPPER_SNAKE с числовыми эталонными значениями (`PIE_DEPTH`, `MAX_PAGES`); начертания `V_REGULAR/V_BOLD/...`; модели — `record`; размеры в chart — в пунктах, растр × `DPI/72`. - Константы UPPER_SNAKE с числовыми эталонными значениями (`PIE_DEPTH`, `MAX_PAGES`); начертания `V_REGULAR/V_BOLD/...`; модели — `record`; размеры в chart — в пунктах, растр × `DPI/72`.
- Классы в `internal` — `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу только `normalize`/`STEP`/`declare`/`DrawingPreRenderer.run` (`rewrite`, карты — package-private); в `wordpdf-app` всё package-private кроме `WordPdfApplication`. - Классы в `internal` — `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу только `normalize`/`STEP`/`declare`/`DrawingPreRenderer.run`/`DependencyGuard.check` (`rewrite`, карты — package-private); в `wordpdf-app` всё package-private кроме `WordPdfApplication`.
- Тестовые методы: регрессионные — `объект_условие` через underscore (`ruPlain_cyrillicAndStyles`, `checkInput_bytesOverLimit`, `noKey_rejected`); чистые юниты — camelCase (`pageFieldBecomesFldSimple`, `splitsRunForUncoveredGlyph`); оба стиля разрешает PMD-паттерн `junit5TestPattern`. - Тестовые методы: регрессионные — `объект_условие` через underscore (`ruPlain_cyrillicAndStyles`, `checkInput_bytesOverLimit`, `noKey_rejected`); чистые юниты — camelCase (`pageFieldBecomesFldSimple`, `splitsRunForUncoveredGlyph`); оба стиля разрешает PMD-паттерн `junit5TestPattern`.
## Important Files ## Important Files
+44
View File
@@ -130,6 +130,50 @@ Files.write(Path.of("out.pdf"), pdf);
больше ста) бросают `ConversionException`. Работа с файлами — забота больше ста) бросают `ConversionException`. Работа с файлами — забота
вызывающего: ядро пути не принимает. вызывающего: ядро пути не принимает.
#### Зависимость 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) ### Веб-интерфейс и контейнеры (podman)
```bash ```bash
+10
View File
@@ -23,6 +23,9 @@
<!-- docx4j: последняя стабильная версия на Maven Central --> <!-- docx4j: последняя стабильная версия на Maven Central -->
<docx4j.version>17.3.2</docx4j.version> <docx4j.version>17.3.2</docx4j.version>
<!-- commons-compress: версию декларирует docx4j-core 17.3.2 (1.28.0);
не завышать — версия привязана к docx4j, а не к свежести -->
<commons-compress.version>1.28.0</commons-compress.version>
<slf4j.version>2.0.20</slf4j.version> <slf4j.version>2.0.20</slf4j.version>
<!-- Spring Boot + springdoc: последние стабильные на Maven Central --> <!-- Spring Boot + springdoc: последние стабильные на Maven Central -->
@@ -74,6 +77,13 @@
<artifactId>docx4j-export-fo</artifactId> <artifactId>docx4j-export-fo</artifactId>
<version>${docx4j.version}</version> <version>${docx4j.version}</version>
</dependency> </dependency>
<!-- Прямая зависимость ядра (DependencyGuard) + нижний порог
docx4j 17.3.2 — 1.25.0; в Boot-BOM 4.1.1 не управляется -->
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-compress</artifactId>
<version>${commons-compress.version}</version>
</dependency>
<!-- Без настроенного slf4j docx4j печатает предупреждение прямо в PDF --> <!-- Без настроенного slf4j docx4j печатает предупреждение прямо в PDF -->
<dependency> <dependency>
<groupId>org.slf4j</groupId> <groupId>org.slf4j</groupId>
+7
View File
@@ -49,6 +49,13 @@
<groupId>org.slf4j</groupId> <groupId>org.slf4j</groupId>
<artifactId>jcl-over-slf4j</artifactId> <artifactId>jcl-over-slf4j</artifactId>
</dependency> </dependency>
<!-- Используется DependencyGuard (проверка совместимости classpath);
транзитивно приходит от docx4j-core, объявлена явно как контракт
интеграции — потребитель видит её в своём дереве зависимостей -->
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-compress</artifactId>
</dependency>
<!-- ============ Тесты ============ --> <!-- ============ Тесты ============ -->
<dependency> <dependency>
@@ -11,6 +11,7 @@ import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
import ru.pjandro.wordpdf.fonts.BundledFontMapper; import ru.pjandro.wordpdf.fonts.BundledFontMapper;
import ru.pjandro.wordpdf.fonts.BundledFonts; import ru.pjandro.wordpdf.fonts.BundledFonts;
import ru.pjandro.wordpdf.internal.chart.DrawingPreRenderer; import ru.pjandro.wordpdf.internal.chart.DrawingPreRenderer;
import ru.pjandro.wordpdf.internal.DependencyGuard;
import ru.pjandro.wordpdf.internal.DocxNormalizer; import ru.pjandro.wordpdf.internal.DocxNormalizer;
import ru.pjandro.wordpdf.internal.DocxOnOffNormalizer; import ru.pjandro.wordpdf.internal.DocxOnOffNormalizer;
import ru.pjandro.wordpdf.internal.FieldNormalizer; import ru.pjandro.wordpdf.internal.FieldNormalizer;
@@ -116,10 +117,16 @@ public final class WordPdfConverter {
} }
/** /**
* Ядро конвертации: docx -> XSL-FO -> FOP -> PDF в поток. * Ядро конвертации: docx -> XSL-FO -> FOP -> PDF в поток. Шаг 0 — проверка
* совместимости commons-compress в classpath потребителя (DependencyGuard):
* без неё старая версия библиотеки дала бы мутный NoSuchMethodError внутри docx4j.
*/ */
private static void convertToStream(byte[] rawDocxBytes, String title, ConvertOptions options, private static void convertToStream(byte[] rawDocxBytes, String title, ConvertOptions options,
OutputStream os) throws Exception { OutputStream os) throws Exception {
// 0. Совместимость commons-compress: docx4j требует ковариантный
// ZipArchiveInputStream.getNextEntry() (>= 1.25.0); ниже — понятный
// ConversionException с инструкцией вместо NoSuchMethodError.
DependencyGuard.check();
// 1. Маппер шрифтов. Порядок важен: конструктор запускает // 1. Маппер шрифтов. Порядок важен: конструктор запускает
// обнаружение системных шрифтов, затем бандл-шрифты из jar // обнаружение системных шрифтов, затем бандл-шрифты из jar
// регистрируются поверх них (имеют приоритет). // регистрируются поверх них (имеют приоритет).
@@ -0,0 +1,69 @@
package ru.pjandro.wordpdf.internal;
import org.apache.commons.compress.archivers.zip.ZipArchiveEntry;
import org.apache.commons.compress.archivers.zip.ZipArchiveInputStream;
import ru.pjandro.wordpdf.ConversionException;
import java.lang.reflect.Method;
/**
* Проверка совместимости commons-compress в classpath потребителя.
*
* <p>docx4j читает zip-контейнер docx через
* {@code org.docx4j.openpackaging.io3.stores.ZipPartStore}, который вызывает
* ковариантный {@code ZipArchiveInputStream.getNextEntry(): ZipArchiveEntry}
* — он появился только в commons-compress 1.25.0. Если у потребителя старая
* версия (BOM, например Spring Boot 3.x, или nearest-wins в Maven навязали
* понижение), конвертация падала мутным {@code NoSuchMethodError} внутри
* docx4j. Guard бросает {@link ConversionException} с текстом-инструкцией
* до входа в docx4j.</p>
*
* <p>Порог определяется API-пробой (возврат {@code getMethod("getNextEntry")}),
* а не разбором строки версии: {@code getImplementationVersion()} бывает
* {@code null} в shaded/uber-jar сборках, а проба ловит ровно тот бинарный
* контракт, который реально ломается.</p>
*/
public final class DependencyGuard {
private DependencyGuard() {
}
/**
* Бросает {@link ConversionException}, если commons-compress в classpath
* несовместим с docx4j 17.3.2 (нет ковариантного {@code getNextEntry},
* т.е. версия ниже 1.25.0, либо библиотека отсутствует).
*/
public static void check() {
String reason = incompatibleReason();
if (reason != null) {
throw new ConversionException(reason);
}
}
/**
* Причина отказа или {@code null}, если classpath совместим.
* Package-private хук для юнит-теста (негативную ветку surefire покрыть
* нельзя — одна версия jar на тестовом classpath, см. DependencyGuardTest).
*/
static String incompatibleReason() {
String found;
try {
Method m = ZipArchiveInputStream.class.getMethod("getNextEntry");
if (ZipArchiveEntry.class.equals(m.getReturnType())) {
return null; // >= 1.25.0: ковариантный getNextEntry на месте
}
String v = ZipArchiveInputStream.class.getPackage().getImplementationVersion();
found = v == null ? "версия не определена" : v;
} catch (NoSuchMethodException e) {
found = "версия не определена"; // нет даже getNextEntry — доисторическая сборка
} catch (NoClassDefFoundError e) {
return "В classpath отсутствует org.apache.commons:commons-compress — "
+ "docx4j требует версию 1.28.0 (минимум 1.25.0).";
}
return "Несовместимая версия commons-compress в classpath (найдена: " + found
+ "): docx4j требует >= 1.25.0, рекомендована 1.28.0. Старую версию обычно"
+ " навязывает BOM или nearest-wins. Закрепите org.apache.commons:commons-compress"
+ " версии 1.28.0: Maven — запись в dependencyManagement, Gradle — constraints"
+ " или resolutionStrategy.force (см. README, раздел «Библиотека»).";
}
}
@@ -0,0 +1,25 @@
package ru.pjandro.wordpdf.internal;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
import static org.junit.jupiter.api.Assertions.assertNull;
/**
* Guard на тестовом classpath (commons-compress 1.28.0) — no-op.
* Негативная ветка (старая версия jar) surefire-покрытию недоступна — одна
* версия jar на classpath; проверена эмпирически подменой jar в classpath
* прогона (1.21 → ConversionException, 1.25.0/1.28.0 → OK).
*/
class DependencyGuardTest {
@Test
void checkPassesOnCurrentClasspath() {
assertDoesNotThrow(DependencyGuard::check);
}
@Test
void reasonNullOnCurrentClasspath() {
assertNull(DependencyGuard.incompatibleReason());
}
}