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,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`|нет|
|
||||
Reference in New Issue
Block a user