- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2.9 KiB
Зависимости потребителя
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»)
— закреплять нужно именно в нём:
<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: уберите понижение либо закрепите нужную версию:
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 |
нет |