# 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