图书馆管理系统后端 API

本项目是将原有桌面版图书馆管理系统改造为 Web 后端 API 的实践项目，基于 Flask + MySQL，实现了图书、会员、借阅管理核心功能，并提供 JWT 认证。

---

技术栈

• Python 3.10+
• Flask 3.1 – Web 框架
• MySQL 8.0 – 数据库
• Flask-JWT-Extended – JWT 身份验证
• PyMySQL / mysql-connector-python – 数据库驱动
• pytest – 单元测试与集成测试
• Flask-Swagger-UI – 交互式 API 文档（即将集成）

---

项目结构

.
├── library/ # 根目录
│ ├── app.py # 应用工厂
│ ├── config.py # 配置管理（开发/测试/生产）
│ ├── blueprint/ # 路由层（蓝图）
│ │ ├── auth.py # 认证接口（登录、注册、刷新token）
│ │ ├── books.py # 图书管理接口
│ │ ├── borrow.py # 借阅管理接口
│ │ └── members.py # 会员管理接口
│ ├── services/ # 业务逻辑层
│ │ ├── book_service.py
│ │ ├── borrow_service.py
│ │ └── member_service.py
│ ├── utils/ # 工具模块
│ │ ├── db.py # 数据库连接池与助手类
│ │ ├── decorators.py # 自定义装饰器（如 admin_required）
│ │ ├── logger.py # 日志文件
│ │ └── response.py # 统一响应格式与错误处理
│ ├── tests/ # 测试目录
│ │ ├── conftest.py # pytest 配置与 fixture
│ │ ├── test_book_.py
│ │ ├── test_borrow_.py
│ │ └── test_member_*.py
│ ├── static/ # 静态文件（Swagger 规范文件）
│ │ └── swagger.yml
│ ├── .env.example # 环境变量示例
│ ├──requirements.txt # 项目依赖列表
│ └── README.md # 版本控制忽略文件

---

快速开始

1. 环境要求

- Python 3.10 或更高版本
- MySQL 8.0 数据库服务

2. 克隆项目

git clone https://github.com/yourname/library-system.git
cd library-system

3. 创建并激活虚拟环境

python -m venv venv
source venv/bin/activate      # Linux/macOS
venv\Scripts\activate         # Windows

4. 安装依赖

pip install -r requirements.txt

5. 配置数据库

创建数据库（例如 library）

执行 SQL 脚本创建表结构（项目根目录下应提供 library.sql 或使用迁移工具）

复制环境变量示例文件并填写真实配置：

cp .env.example .env

编辑 .env 文件，设置数据库连接信息（如 DATABASE_URL）和 JWT 密钥。

6. 初始化数据库（可选）

如果已有表结构，可直接导入；若无，可运行以下命令创建表（需根据实际 SQL 文件路径调整）：

mysql -u root -p library < schema.sql

7. 运行应用

flask run

应用将启动在 http://127.0.0.1:5000

8. 运行测试

pytest tests/

测试覆盖率报告（可选）：

pytest --cov=day17_19 tests/

API 文档

启动项目后，访问 Swagger UI 交互式文档：

本地地址：http://127.0.0.1:5000/api/docs

文档基于 OpenAPI 3.0 规范编写，详细描述了每个接口的请求参数、响应格式及认证方式。

核心功能

用户认证

POST /api/auth/login – 会员登录，返回 JWT token

POST /api/auth/register – 会员注册（同时创建 members 和 user 记录）

PUT /api/auth/change-password – 修改密码（需认证）

POST /api/auth/refresh – 刷新 access_token（需 refresh token）

图书管理

GET /api/books/ – 获取所有图书

GET /api/books/<isbn> – 获取单本图书

POST /api/books/ – 添加图书（管理员）

PUT /api/books/<isbn> – 更新图书（管理员）

DELETE /api/books/<isbn> – 下架图书（管理员）

会员管理

GET /api/members/ – 获取所有会员（管理员）

GET /api/members/<member_id> – 获取会员信息（本人或管理员）

POST /api/members/ – 创建会员（管理员）

PUT /api/members/<member_id> – 更新会员信息（本人或管理员）

DELETE /api/members/<member_id> – 注销会员（管理员，需检查未还书）

借阅管理

POST /api/borrow/ – 借书（需认证）

PUT /api/borrow/<record_id>/return – 还书（需认证，本人）

PUT /api/borrow/<record_id>/renew – 续借（需认证，本人）

GET /api/borrow/my-borrows – 查看我的借阅记录（需认证）

配置说明

项目使用 config.py 管理不同环境（开发、测试、生产）的配置，并通过 .env 文件注入敏感信息。

主要环境变量：

变量名	说明	示例
FLASK_ENV	运行环境（development / testing / production）	development
DATABASE_URL	数据库连接 URL	mysql+mysqlconnector://root:pass@localhost/library
JWT_SECRET_KEY	JWT 签名密钥（建议随机字符串）	your-secret-key
DB_POOL_SIZE	数据库连接池大小	5

贡献指南

欢迎提交 Issue 或 Pull Request。请确保：

代码符合 PEP8 规范

新增功能有对应的单元测试

测试覆盖率不降低

更新相关文档（包括 Swagger 规范）

许可证

MIT

致谢

本项目作为学习实践，参考了 Flask 官方文档及社区优秀开源项目。感谢所有贡献者！