Замена wordpdf-cli на Spring Boot REST API: wordpdf-app, SPA wordpdf-web, docker-compose

This commit is contained in:
Pjandro
2026-10-13 16:38:18 +00:00
parent aec4dbffe7
commit 8c390104d2
44 changed files with 3439 additions and 337 deletions
+43 -13
View File
@@ -11,14 +11,16 @@ LibreOffice/Aspose. Шрифты упакованы в jar — конверта
в docx4j/FOP.
- Частые MS-шрифты подменяются метрически совместимыми open-source аналогами
(см. «Шрифты» ниже).
- Клиентская библиотека (`wordpdf-core`) и CLI (`wordpdf-cli`, fat-jar).
- Клиентская библиотека (`wordpdf-core`), REST API (`wordpdf-app`, Spring Boot)
и веб-интерфейс (`wordpdf-web`, React SPA).
## Структура
```
java-word-pdf/
├── wordpdf-core/ библиотека: конвертер, шрифты, маппинг
└── wordpdf-cli/ командная строка (fat-jar через maven-shade)
├── wordpdf-app/ REST API: POST /api/v1/convert (Spring Boot, Swagger UI)
└── wordpdf-web/ веб-интерфейс (React + TypeScript + Vite + Tailwind, вне Maven)
```
Ключевые классы (`wordpdf-core`):
@@ -34,28 +36,39 @@ java-word-pdf/
## Сборка
Требуется **Java 17** и **Maven**.
Требуется **Java 21** и **Maven** (бэкенд), **Node.js ≥ 20.19** (веб-интерфейс).
```bash
mvn clean verify # сборка всех модулей + тесты
mvn -pl wordpdf-cli package # только fat-jar CLI
mvn clean verify # все модули + тесты
mvn -pl wordpdf-app -am package # исполняемый jar бэкенда
```
Результат: `wordpdf-cli/target/wordpdf-cli-<версия>.jar` (fat-jar, все
зависимости внутри).
Результат: `wordpdf-app/target/wordpdf-app-<версия>.jar` (все зависимости
внутри). Для фронтенда — отдельный деп: `npm install && npm run build`
в `wordpdf-web/` (результат — статика в `wordpdf-web/dist/`).
## Использование
### CLI
### REST API
```bash
java -jar wordpdf-cli-1.0.0.jar in.docx # рядом создаётся in.pdf
java -jar wordpdf-cli-1.0.0.jar in.docx out.pdf # в указанный файл
java -jar wordpdf-cli-1.0.0.jar a.docx b.docx # пакетно: каждый -> свой .pdf
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
```
Коды возврата: `0` — успех, `1` — ошибка использования, `2` — не удалось
конвертировать хотя бы один файл.
`POST /api/v1/convert` принимает multipart-поле `file` (.docx) и синхронно
возвращает байты PDF (`application/pdf`, attachment).
|Код|Смысл|
|---|---|
|200|PDF в теле ответа|
|400|некорректный вход: не .docx / пустой / не zip / > 5 МБ / > 100 страниц|
|413|тело запроса больше контейнерного лимита multipart (6 МБ)|
|503|очередь конвертации занята — повторить позже|
|504|конвертация дольше таймаута (`wordpdf.convert-timeout`, по умолчанию 2m)|
Ошибки — JSON `{"error": "..."}`. Интерактивная документация:
Swagger UI — `/swagger-ui.html`, OpenAPI — `/v3/api-docs`.
### Библиотека
@@ -69,6 +82,20 @@ WordPdfConverter.convert(Path.of("doc.docx"), Path.of("out.pdf")); // явный
Ошибки валидации (не `.docx`, файл не найден) бросают `ConversionException`.
### Веб-интерфейс и Docker
```bash
docker compose up -d --build
```
Всё на `http://localhost:8080/`: nginx-контейнер `web` раздаёт SPA и проксирует
`/api`, `/swagger-ui`, `/v3/api-docs` на бэкенд (контейнер `app` наружу не
публикуется).
Dev-режим без Docker: бэкенд `java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar`
(порт 8080) + `npm run dev` в `wordpdf-web/` → `http://localhost:5173`
(Vite проксирует `/api` на 8080, CORS не нужен).
## Шрифты
В `wordpdf-core/src/main/resources/fonts/` упакованы 30 TTF: 7 текстовых
@@ -139,3 +166,6 @@ docx ──> нормализация байтов ──> docx4j (Wordprocessin
Тесты используют готовые `.docx` из `wordpdf-core/src/test/resources/samples/`
(генерируются POI) и проверяют извлечённый PDFBox'ом текст и встраивание
шрифтов. Запуск: `mvn test`.
API (`wordpdf-app`) проверяется `MockMvc`-сквозняками (`ConvertControllerTest`)
на тех же фикстурах — ядро отдаёт их test-jar'ом.