fix(core): DependencyGuard — понятная ошибка при старой commons-compress у потребителя
PR checks / web (pull_request) Successful in 49s
PR checks / java (pull_request) Successful in 1m2s
Main: tests, deploy, autotests / web (push) Successful in 44s
Main: tests, deploy, autotests / java (push) Successful in 57s
Main: tests, deploy, autotests / images-web (push) Successful in 30s
Main: tests, deploy, autotests / images-app (push) Successful in 5m12s
Main: tests, deploy, autotests / deploy (push) Successful in 1m34s
Main: tests, deploy, autotests / autotests (push) Successful in 49s
Main: tests, deploy, autotests / rollback (push) Has been skipped
PR checks / web (pull_request) Successful in 49s
PR checks / java (pull_request) Successful in 1m2s
Main: tests, deploy, autotests / web (push) Successful in 44s
Main: tests, deploy, autotests / java (push) Successful in 57s
Main: tests, deploy, autotests / images-web (push) Successful in 30s
Main: tests, deploy, autotests / images-app (push) Successful in 5m12s
Main: tests, deploy, autotests / deploy (push) Successful in 1m34s
Main: tests, deploy, autotests / autotests (push) Successful in 49s
Main: tests, deploy, autotests / rollback (push) Has been skipped
docx4j 17.3.2 требует ковариантный ZipArchiveInputStream.getNextEntry() (>= 1.25.0); BOM/nearest-wins потребителя мог навязать старую версию — конвертация падала NoSuchMethodError внутри docx4j. Теперь шаг 0 convertToStream бросает ConversionException с инструкцией; commons-compress объявлена явной зависимостью ядра (1.28.0, версия docx4j); README — закрепление версии в Maven/Gradle. Регрессия — DependencyGuardTest, негативная ветка проверена подменой jar (1.21 → ConversionException).
This commit was merged in pull request #56.
This commit is contained in:
@@ -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/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-core/src/main/resources/fonts/`|30 TTF + 3 лицензии — бинарные фикстуры, часть jar|
|
||||
|`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 — деградация вместо падения.
|
||||
- Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`) — новый фикс оформлять так же (в существующем main-коде convention соблюдён лишь частично — `SymbolFontNormalizer`, `WordPdfValidator`, `Surface3dPainter` и классы app; новые правки обязаны ссылаться).
|
||||
- Константы 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`.
|
||||
|
||||
## Important Files
|
||||
|
||||
@@ -130,6 +130,50 @@ Files.write(Path.of("out.pdf"), pdf);
|
||||
больше ста) бросают `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)
|
||||
|
||||
```bash
|
||||
|
||||
@@ -23,6 +23,9 @@
|
||||
|
||||
<!-- docx4j: последняя стабильная версия на Maven Central -->
|
||||
<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>
|
||||
|
||||
<!-- Spring Boot + springdoc: последние стабильные на Maven Central -->
|
||||
@@ -74,6 +77,13 @@
|
||||
<artifactId>docx4j-export-fo</artifactId>
|
||||
<version>${docx4j.version}</version>
|
||||
</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 -->
|
||||
<dependency>
|
||||
<groupId>org.slf4j</groupId>
|
||||
|
||||
@@ -49,6 +49,13 @@
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>jcl-over-slf4j</artifactId>
|
||||
</dependency>
|
||||
<!-- Используется DependencyGuard (проверка совместимости classpath);
|
||||
транзитивно приходит от docx4j-core, объявлена явно как контракт
|
||||
интеграции — потребитель видит её в своём дереве зависимостей -->
|
||||
<dependency>
|
||||
<groupId>org.apache.commons</groupId>
|
||||
<artifactId>commons-compress</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- ============ Тесты ============ -->
|
||||
<dependency>
|
||||
|
||||
@@ -11,6 +11,7 @@ import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
|
||||
import ru.pjandro.wordpdf.fonts.BundledFontMapper;
|
||||
import ru.pjandro.wordpdf.fonts.BundledFonts;
|
||||
import ru.pjandro.wordpdf.internal.chart.DrawingPreRenderer;
|
||||
import ru.pjandro.wordpdf.internal.DependencyGuard;
|
||||
import ru.pjandro.wordpdf.internal.DocxNormalizer;
|
||||
import ru.pjandro.wordpdf.internal.DocxOnOffNormalizer;
|
||||
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,
|
||||
OutputStream os) throws Exception {
|
||||
// 0. Совместимость commons-compress: docx4j требует ковариантный
|
||||
// ZipArchiveInputStream.getNextEntry() (>= 1.25.0); ниже — понятный
|
||||
// ConversionException с инструкцией вместо NoSuchMethodError.
|
||||
DependencyGuard.check();
|
||||
// 1. Маппер шрифтов. Порядок важен: конструктор запускает
|
||||
// обнаружение системных шрифтов, затем бандл-шрифты из 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());
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user