# book-catalog

**Repository Path**: xiaopengyou/book-catalog

## Basic Information

- **Project Name**: book-catalog
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-01
- **Last Updated**: 2026-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Book Catalog

一个基于 Spring Boot 的图书目录 RESTful 服务，提供图书的新增、查询、分页查询、更新和删除功能，无前端界面。

## 技术栈

- Java 17、Spring Boot 3.3.5
- Spring Web、Spring Data JPA、Bean Validation
- MySQL 8.x
- JUnit 5、Mockito、MockMvc、JaCoCo
- Maven

## 功能

- 图书 CRUD：新增、按 ID 查询、分页查询、全量更新、删除
- ISBN 唯一性校验及数据库唯一约束保护
- 统一 JSON 异常响应：400、404、409、500
- 分页与白名单排序：`id`、`title`、`author`、`publishedDate`、`price`
- 单元测试与 API 测试，JaCoCo 覆盖率门槛 80%

## 项目结构

```text
.
├── docs/                         # 设计文档与 AI 使用记录
├── sql/book_catalog.sql          # MySQL 初始化脚本
├── src/main/java/com/example/bookcatalog/
│   ├── controller/                # REST 接口
│   ├── dto/                       # 请求、响应及错误对象
│   ├── entity/                    # JPA 实体
│   ├── exception/                 # 领域异常与统一异常处理
│   ├── factory/                   # Factory 模式
│   ├── mapper/                    # Entity 与 DTO 转换
│   ├── repository/                # Repository 模式
│   └── service/                   # 业务逻辑与事务
├── src/main/resources/
│   ├── application.yml            # 公共配置
│   ├── application-dev.yml        # 本地开发配置
│   └── application-prod.yml       # 生产环境配置
└── src/test/                      # 单元测试与 API 测试
```

## 快速启动

### 1. 准备环境

- 安装 JDK 17、Maven 和 MySQL 8.x。
- 创建数据库及表：

```bash
mysql -h 127.0.0.1 -P 3306 -u root -proot < sql/book_catalog.sql
```

### 2. 启动开发环境

默认 profile 为 `dev`，使用 `127.0.0.1:3306/book_catalog`、`root/root`：

```bash
mvn spring-boot:run
```

服务启动后地址为 `http://localhost:8080`。

### 3. 启动生产环境

生产连接信息由环境变量提供，不提交生产凭据：

```bash
export SPRING_PROFILES_ACTIVE=prod
export DB_URL='jdbc:mysql://db-host:3306/book_catalog?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai'
export DB_USERNAME='your_username'
export DB_PASSWORD='your_password'
mvn spring-boot:run
```

## API

基础路径：`/api/v1/books`

| 操作 | 方法 | 路径 | 成功状态码 |
| --- | --- | --- | --- |
| 新增图书 | `POST` | `/api/v1/books` | `201 Created` |
| 查询图书 | `GET` | `/api/v1/books/{id}` | `200 OK` |
| 分页查询 | `GET` | `/api/v1/books?page=0&size=20&sort=id,desc` | `200 OK` |
| 更新图书 | `PUT` | `/api/v1/books/{id}` | `200 OK` |
| 删除图书 | `DELETE` | `/api/v1/books/{id}` | `204 No Content` |

新增或更新请求：

```json
{
  "isbn": "978-7-115-12345-6",
  "title": "Spring Boot 实战",
  "author": "示例作者",
  "publishedDate": "2025-01-01",
  "price": 79.90
}
```

示例：

```bash
curl -X POST http://localhost:8080/api/v1/books \
  -H 'Content-Type: application/json' \
  -d '{"isbn":"978-7-115-12345-6","title":"Spring Boot 实战","author":"示例作者","publishedDate":"2025-01-01","price":79.90}'
```

错误响应格式：

```json
{
  "timestamp": "2026-09-01T10:00:00Z",
  "status": 409,
  "code": "ISBN_ALREADY_EXISTS",
  "message": "ISBN 已存在",
  "path": "/api/v1/books",
  "fieldErrors": []
}
```

## 设计模式

- **Repository 模式**：`BookRepository` 隔离业务层与 Spring Data JPA。
- **Builder 模式**：`BookResponse.Builder` 逐字段构建不可变响应对象。
- **Factory 模式**：`BookFactory` 集中创建新的 `Book` 实体，并由 `BookMapper` 注入使用。

## 测试与覆盖率

执行完整验证：

```bash
mvn clean verify
```

该命令运行 JUnit 5 单元测试与 MockMvc API 测试，并在 `target/site/jacoco/index.html` 生成覆盖率报告。项目已配置 JaCoCo 对业务包强制执行不低于 80% 的指令覆盖率。

## 文档

- [总体设计](docs/book-catalog-service-design.md)
- [详细设计](docs/book-catalog-service-detailed-design.md)
- [数据库初始化脚本](sql/book_catalog.sql)
- [AI 使用记录](docs/AI_PROMPTS.md)