Замена wordpdf-cli на Spring Boot REST API: wordpdf-app, SPA wordpdf-web, docker-compose
This commit is contained in:
@@ -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'ом.
|
||||
|
||||
Reference in New Issue
Block a user