elibrary

基于 Spring Boot、MyBatis 和 MySQL 的轻量级图书管理后端。

环境要求

• JDK 17 或更高版本
• MySQL 8

项目通过 Gradle Wrapper 管理构建工具，无需预先安装 Gradle。

初始化数据库

mysql -u root -p -e "create database if not exists library character set utf8mb4"
mysql -u root -p library < document/sql/database.sql

如果数据库由旧版项目创建，请执行一次升级脚本；脚本检测到重复作者、一本书存在多条作者关联或孤立关联时会停止，并提示先处理数据：

mysql -u root -p library < document/sql/migration/V2__enforce_unique_indexes.sql

配置

应用通过环境变量读取数据库配置，不在仓库中保存密码：

export DB_URL='jdbc:mysql://localhost:3306/library?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai'
export DB_USERNAME='root'
export DB_PASSWORD='your-password'

可选配置：

• SCHEDULING_ENABLED：是否启用图书数量定时日志，默认 true
• BOOK_COUNT_FIXED_DELAY：定时任务间隔（毫秒），默认 5000
• BOOK_COUNT_CRON：Cron 表达式，默认 1-2 * * * * ?

构建与运行

./gradlew clean test
./gradlew bootRun

构建可执行 JAR：

./gradlew bootJar
java -jar build/libs/elibrary-0.0.1-SNAPSHOT.jar

测试使用内存 H2 数据库，不依赖本地 MySQL。

Docker 运行

安装 Docker Engine（含 Compose 插件）后，可以同时启动应用和 MySQL：

cp .env.example .env
docker compose up --build -d
docker compose ps

应用默认监听 http://localhost:8080，MySQL 默认映射到本机 3306 端口。可在 .env 中修改端口、数据库账号、定时任务和 JVM 内存参数；示例密码仅适用于本地开发，部署前必须替换。

查看应用日志和停止服务：

docker compose logs -f app
docker compose down

document/sql/database.sql 会在 MySQL 数据卷第一次创建时自动执行。修改初始化脚本后如需重建本地数据库，可以删除 Compose 数据卷再启动；该操作会清空容器中的数据库数据：

docker compose down --volumes
docker compose up --build -d

只构建和运行应用镜像时，需要另行提供可访问的 MySQL，并传入数据库环境变量：

docker build -t elibrary:local .
docker run --rm -p 8080:8080 \
  --add-host=host.docker.internal:host-gateway \
  -e DB_URL='jdbc:mysql://host.docker.internal:3306/library?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai' \
  -e DB_USERNAME='root' \
  -e DB_PASSWORD='your-password' \
  elibrary:local

API

新接口采用标准 REST 路由，原有 /list、/search、/insert、/update/{id}、/delete/{id} 路径及其历史 HTTP 方法仍然保留兼容。

方法	路径	功能
GET	/api/v1/book/{id}	获取图书详情
GET	/api/v1/book/page?page=0&size=20&name=	分页检索图书，单页最多 100 条
POST	/api/v1/book	新增图书并返回生成的 ID
PUT	/api/v1/book/{id}	更新图书及作者关联
DELETE	/api/v1/book/{id}	删除图书
GET	/api/v1/author/{id}	获取作者详情
GET	/api/v1/author/{id}/books	查询作者的全部图书
POST	/api/v1/author	新增作者并返回生成的 ID
PUT	/api/v1/author/{id}	更新作者
DELETE	/api/v1/author/{id}	删除没有关联图书的作者

参数错误、资源不存在和资源冲突分别返回 HTTP 400、404 和 409，响应体保持统一的 code、message、data 结构。

MyBatis 代码生成

生成器依赖与应用运行时依赖相互隔离。设置数据库环境变量后执行：

./gradlew generateMyBatis

生成器会更新 model、mapper 和 Mapper XML，请在提交前审查生成差异。