|
|
# iTi-Flask 项目文档
|
|
|
|
|
|
## 📚 文档索引
|
|
|
|
|
|
### 核心文档
|
|
|
|
|
|
- **[HTTP_RESPONSE_UTILS.md](./HTTP_RESPONSE_UTILS.md)** - HTTP 响应包装工具使用指南
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🎯 快速开始
|
|
|
|
|
|
### HTTP 响应工具
|
|
|
|
|
|
统一的 API 响应格式包装工具，提供 `success()`, `fail()`, `page()` 等函数。
|
|
|
|
|
|
```python
|
|
|
from iti.applications.common.utils import success, fail, page
|
|
|
|
|
|
# 成功响应
|
|
|
@app.get('/api/users/<int:user_id>')
|
|
|
def get_user(user_id):
|
|
|
user = User.query.get(user_id)
|
|
|
return success(user, message='获取成功')
|
|
|
|
|
|
# 失败响应
|
|
|
@app.get('/api/users/<int:user_id>')
|
|
|
def get_user(user_id):
|
|
|
user = User.query.get(user_id)
|
|
|
if not user:
|
|
|
return fail('用户不存在', code=404)
|
|
|
return success(user)
|
|
|
|
|
|
# 分页响应
|
|
|
@app.get('/api/users')
|
|
|
def get_users():
|
|
|
pagination = User.query.paginate(page=1, per_page=10)
|
|
|
return page(pagination, message='获取用户列表成功')
|
|
|
```
|
|
|
|
|
|
**详细文档：** [HTTP_RESPONSE_UTILS.md](./HTTP_RESPONSE_UTILS.md)
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🗂️ 项目结构
|
|
|
|
|
|
```
|
|
|
back/
|
|
|
├── docs/ # 📚 文档目录
|
|
|
│ ├── README.md # 文档索引（本文件）
|
|
|
│ └── HTTP_RESPONSE_UTILS.md # HTTP 工具使用指南
|
|
|
│
|
|
|
├── src/
|
|
|
│ ├── applications/
|
|
|
│ │ ├── __init__.py # 应用工厂
|
|
|
│ │ ├── extensions/ # 扩展初始化
|
|
|
│ │ │ ├── http.py # BaseResponse Schema
|
|
|
│ │ │ └── ...
|
|
|
│ │ └── common/
|
|
|
│ │ └── utils/
|
|
|
│ │ ├── __init__.py # 工具导出
|
|
|
│ │ └── http.py # 🔥 HTTP 响应包装工具
|
|
|
│ │
|
|
|
│ ├── config.py # 配置文件
|
|
|
│ └── app.py # 应用入口
|
|
|
│
|
|
|
├── tests/ # 测试目录
|
|
|
├── hatch.toml # Hatch 配置
|
|
|
└── pyproject.toml # 项目配置
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🔧 工具模块
|
|
|
|
|
|
### `applications.common.utils`
|
|
|
|
|
|
**提供的函数：**
|
|
|
|
|
|
| 函数 | 说明 | 示例 |
|
|
|
|------|------|------|
|
|
|
| `success()` | 成功响应包装 | `return success(data, message='成功')` |
|
|
|
| `fail()` | 失败响应包装 | `return fail('错误', code=404)` |
|
|
|
| `page()` | 分页响应包装 | `return page(pagination)` |
|
|
|
| `pagination_builder()` | 分页信息构建器 | `pagination_builder(None, page=1, size=10, total=100)` |
|
|
|
|
|
|
**提供的 Schema：**
|
|
|
|
|
|
| Schema | 说明 |
|
|
|
|--------|------|
|
|
|
| `PaginationSchema` | 分页信息 Schema（`per_page` → `size`） |
|
|
|
| `PageDataSchema` | 分页数据 Schema |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 📝 编码规范
|
|
|
|
|
|
### 1. 统一返回格式
|
|
|
|
|
|
所有 API 响应必须使用统一格式：
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"data": <返回数据>,
|
|
|
"code": <业务状态码>,
|
|
|
"message": <提示信息>
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 2. HTTP 状态码
|
|
|
|
|
|
- ✅ **成功和业务失败都返回 HTTP 200**
|
|
|
- ✅ 由 `code` 字段区分业务状态
|
|
|
- ✅ 前端统一处理，无需捕获 HTTP 异常
|
|
|
|
|
|
### 3. 分页参数
|
|
|
|
|
|
- ✅ 使用 `page` 表示页码（从 1 开始）
|
|
|
- ✅ 使用 `size` 表示每页数量（不是 `per_page`）
|
|
|
|
|
|
**示例：**
|
|
|
```
|
|
|
GET /api/users?page=1&size=10
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🧪 测试
|
|
|
|
|
|
### 运行测试
|
|
|
|
|
|
```bash
|
|
|
# 运行 HTTP 工具测试
|
|
|
hatch run test tests/test_http_utils.py -v
|
|
|
|
|
|
# 运行所有测试
|
|
|
hatch run test
|
|
|
|
|
|
# 带详细输出
|
|
|
hatch run test -v
|
|
|
```
|
|
|
|
|
|
### 测试覆盖率
|
|
|
|
|
|
```bash
|
|
|
# 生成覆盖率报告
|
|
|
hatch run cov
|
|
|
|
|
|
# 查看 HTML 报告
|
|
|
# 打开 htmlcov/index.html
|
|
|
```
|
|
|
|
|
|
### 测试统计
|
|
|
|
|
|
| 测试文件 | 测试数量 | 说明 |
|
|
|
|---------|---------|------|
|
|
|
| `test_config.py` | 7 个 | 配置相关测试 |
|
|
|
| `test_limiter.py` | 6 个 | 限流器测试 |
|
|
|
| `test_http_utils.py` | 33 个 | HTTP 工具测试 |
|
|
|
| **总计** | **46 个** | 全部通过 ✅ |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🚀 开发环境
|
|
|
|
|
|
### 启动开发服务器
|
|
|
|
|
|
```bash
|
|
|
hatch run dev
|
|
|
```
|
|
|
|
|
|
### 生产环境
|
|
|
|
|
|
```bash
|
|
|
hatch run prod:start
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 📖 相关链接
|
|
|
|
|
|
- [APIFlask 官方文档](https://apiflask.com/)
|
|
|
- [Flask 官方文档](https://flask.palletsprojects.com/)
|
|
|
- [Flask-SQLAlchemy 文档](https://flask-sqlalchemy.palletsprojects.com/)
|
|
|
|
|
|
---
|
|
|
|
|
|
**最后更新：** 2025-10-14
|
|
|
**维护者：** iTi-Flask Team
|
|
|
|