学生信息管理系统 API

一个基于 Python FastAPI 构建的学生信息管理接口项目，提供学生记录的增删改查（CRUD）功能。数据使用内存列表存储，无需任何数据库，开箱即用，并内置完整的 Swagger 在线 API 文档。

功能特性

• 完整的 CRUD 接口：新增、查询（列表/详情）、更新、删除学生信息
• 丰富的学生字段：姓名、性别、年龄、学号、班级、专业、邮箱、手机号等
• 列表查询增强：支持关键词搜索（姓名/学号/专业）、班级过滤、分页查询
• 参数校验：基于 Pydantic 模型自动校验请求参数（性别枚举、手机号格式、年龄范围等）
• 内置 Swagger 文档：访问 /docs 即可在线调试全部接口
• 内存+单例存储：数据存储于进程内存中，线程安全，重启即重置
• 预置示例数据：启动时自动写入 4 条示例学生记录，便于快速体验

技术栈

组件	说明
Python	3.10+
FastAPI	高性能 Web 框架，自动生成 OpenAPI 文档
Uvicorn	ASGI 服务器
Pydantic	数据校验与序列化（v2）
Pytest	单元测试

## 快速开始

### 1. 克隆项目

```bash
git clone https://atomgit.com/Lzx616721/lzx_demo_0919.git
cd lzx_demo_0919
```

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 启动服务

```bash
# 方式一：使用 Uvicorn 命令
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# 方式二：直接运行主模块（内部调用 uvicorn）
python app/main.py
```

启动成功后控制台会显示服务地址：

```
INFO: Uvicorn running on http://0.0.0.0:8000
```

### 4. 访问文档

打开浏览器访问以下地址：

| 地址 | 说明 |
| ------------------------ | ------------------------------------- |
| http://localhost:8000/docs | Swagger UI 交互式 API 文档（推荐） |
| http://localhost:8000/redoc | ReDoc 风格 API 文档 |
| http://localhost:8000/ | 服务健康检查 |

## 项目结构

```
lzx_demo_0919/
├── app/
│ ├── __init__.py
│ ├── main.py # FastAPI 应用入口，注册路由
│ ├── models.py # Pydantic 数据模型（请求/响应）
│ ├── database.py # 内存数据存储层（单例+线程安全）
│ └── routers/
│ ├── __init__.py
│ └── students.py # 学生 CRUD 路由定义
├── tests/
│ └── test_students.py # 接口单元测试
├── requirements.txt # Python 依赖清单
├── README.md # 项目说明文档
└── blog.md # 技术博客说明文章
```

## API 接口说明

所有接口前缀均为 `/api/v1/students`。

### 1. 查询学生列表

```
GET /api/v1/students
```

**Query 参数：**

| 参数 | 类型 | 必填 | 说明 |
| --------- | ---- | ---- | ----------------------------- |
| keyword | str | 否 | 关键词，匹配姓名/学号/专业 |
| grade | str | 否 | 班级过滤（模糊匹配） |
| page | int | 否 | 页码，从 1 开始，默认 1 |
| page_size | int | 否 | 每页条数，默认 10，最大 100 |

**响应示例：**

```json
{
"total": 4,
"page": 1,
"page_size": 10,
"items": [
{
"id": 1,
"name": "张三",
"gender": "男",
"age": 20,
"student_no": "2021001",
"grade": "计算机2101班",
"major": "计算机科学与技术",
"email": "2021001@example.com",
"phone": "13800000000",
"created_at": "2026-09-19T16:47:54.921239",
"updated_at": "2026-09-19T16:47:54.921239"
}
]
}
```

### 2. 新增学生

```
POST /api/v1/students
```

**请求体（JSON）：**

```json
{
"name": "钱七",
"gender": "男",
"age": 22,
"student_no": "2021005",
"grade": "软件工程2105班",
"major": "软件工程",
"email": "qianqi@example.com",
"phone": "13900000000"
}
```

**响应：** `201 Created`，返回创建完成的学生对象（含系统自动分配的 `id`、`created_at`、`updated_at`）。

### 3. 查询学生详情

```
GET /api/v1/students/{student_id}
```

**路径参数：** `student_id` - 学生主键 ID

**响应：** `200 OK`，返回学生详情；若不存在返回 `404`。

### 4. 更新学生信息

```
PUT /api/v1/students/{student_id}
```

**请求体（JSON）：** 与新增一样，但所有字段均可选，仅更新传入的字段（部分更新）。

**响应：** `200 OK`，返回更新后的学生对象；若不存在返回 `404`。

### 5. 删除学生

```
DELETE /api/v1/students/{student_id}
```

**响应：** `204 No Content`；若不存在返回 `404`。

## 状态码约定

| 状态码 | 说明 |
| ------ | ----------------------------- |
| 200 | 查询/更新成功 |
| 201 | 新增成功 |
| 204 | 删除成功 |
| 404 | 资源不存在 |
| 422 | 参数校验失败（格式/范围错误） |

## 运行测试

```bash
pip install pytest
pytest tests/ -v
```

当前共 13 个测试用例，覆盖健康检查、各类 CRUD 操作及异常分支。

## 数据说明

本项目使用内存列表存储数据，具备以下特点：

- 数据仅存在于当前进程内，服务重启后数据重置
- 使用单例模式 + 线程锁保证多请求并发访问安全
- 启动时自动预置 4 条示例数据，方便演示

如需持久化，可在此基础上扩展接入 SQLite、MySQL 等方式，存储层接口（`app/database.py`）已做隔离，替换成本低。

## 许可协议

MIT