reference/docs/fastapi.md

FastAPI 备忘清单
===

FastAPI 是一个用于构建 API 的现代、快速（高性能）的 web 框架，使用 Python 3.6+ 并基于标准的 Python 类型提示。Python: `3.9.5`   FastAPI: `0.103.1`

入门
---
<!--rehype:body-class=cols-1-->

### 最小程序

下面代码会直接启动http服务，也可以使用 `uvicorn main:app --reload`

```python
from fastapi import FastAPI
import uvicorn

app = FastAPI()

# http://127.0.0.1:8000/
@app.get("/")
async def root():
    return {"message": "Hello World"}

if __name__ == '__main__':
    uvicorn.run(app='main:app', reload=True)
```

### 路径参数

#### 最基本的路径参数

```python
# http://127.0.0.1:8000/items/1
@app.get("/items/{item_id}")
async def read_item(item_id):
    return {"item_id": item_id} # item_id自定义
```

#### 多个路径参数

```python
# http://127.0.0.1:8000/items/1/2
@app.get("/items/{item_id}/{user_id}")
async def read_item(item_id, user_id):
    return {"item_id": item_id, "user_id": user_id}
```

#### 有类型的路径参数

```python
# http://127.0.0.1:8000/items/1
@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}
```

#### 文件路径参数

```python
# http://127.0.0.1:8000/file//home/my/my.txt
@app.get("/file/{file_path:path}")
async def read_item(file_path):
    return {"file_path": file_path}
```

### 查询参数

#### 带默认值的查询参数

```python
# http://127.0.0.1:8000/items/?skip=0&limit=2
fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]
@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10):
    return fake_items_db[skip: skip + limit]
```

#### 可选查询参数

```python
# http://127.0.0.1:8000/items/1?q=admin
from typing import Union
@app.get("/items/{item_id}")
async def read_item(item_id: str, q: Union[str, None] = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}
```

#### 多路径多查询参数

```python
# http://127.0.0.1:8000/users/1/items/2
# or 
# http://127.0.0.1:8000/users/1/items/2?q=query&short=true
@app.get("/users/{user_id}/items/{item_id}")
async def read_user_item(
        user_id: int, item_id: str, q: Union[str, None] = None, short: bool = False
):
    item = {"item_id": item_id, "owner_id": user_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update(
            {"description": "This is an amazing item that has a long description"}
        )
    return item
```

#### 必需查询参数

```python
# http://127.0.0.1:8000/items/123?needy=yes
@app.get("/items/{item_id}")
async def read_user_item(item_id: str, needy: str):
    item = {"item_id": item_id, "needy": needy}
    return item
```

### 请求体

```python
from pydantic import BaseModel
from typing import Union
class Item(BaseModel):
    name: str = '小明'
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
@app.post("/items/")
async def create_item(item: Item):
    print(item.name)
    return item
```

#### 调用

```bash
curl -X 'POST' \
  'http://127.0.0.1:8000/items/' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "小明",
  "description": "string",
  "price": 0,
  "tax": 0
}'
```

### 查询参数和字符串校验

```python
from fastapi import Query
@app.get("/items/")
async def read_items(q: Union[str, None] = Query(default=None, max_length=50)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results
```

#### 参数列表

| 参数       | 含义         | 类型          |
| ---------- | ------------ | ------------- |
| default    | 默认值       | 任意类型或... |
| max_length | 最大长度     | int           |
| min_length | 最小长度     | int           |
| pattern    | 正则匹配     | string        |
| alias      | 别名参数     | string        |
| deprecated | 准备弃用参数 | bool          |

#### 多个相同的查询参数

```python
# http://127.0.0.1:8000/items/?q=foo&q=bar
@app.get("/items/")
async def read_items(q: Union[List[str], None] = Query(default=None)):
    query_items = {"q": q}
    return query_items
```

### 路径参数和数值校验

Path用法基本和Query相同，参考：[FastAPI官方文档](https://fastapi.tiangolo.com/zh/tutorial/path-params-numeric-validations/)

#### 导入 Path

```python
from fastapi import FastAPI, Path, Query
from typing_extensions import Annotated
```

#### 声明元数据

```python
@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get")],
    q: Annotated[Union[str, None], Query(alias="item-query")] = None,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results
```

#### 参数列表

| 参数  | 含义                | 类型      |
| ----- | ------------------- | --------- |
| ...   | 和Query具有相同参数 | ...       |
| ge    | 大于等于            | int float |
| gt    | 大于                | int float |
| le    | 小于等于            | int float |
| le    | 小于等于            | int float |
| title | api文档的标题       | string    |

### 其他参数

都具有Query的参数，max_length、min_length等

#### Cookie参数

```python
from fastapi import Cookie
@app.get("/items/")
async def read_items(ads_id: Annotated[Union[str, None], Cookie()] = None):
    return {"ads_id": ads_id}
```

#### Header 参数

```python
from fastapi import Header
@app.get("/items/")
async def read_items(user_agent: Annotated[Union[str, None], Header()] = None,items_id: Annotated[Union[int, None], Header(ge=1)] = None):
    return {"User-Agent": user_agent, "items_id": items_id}
```

### 表单数据

接收的不是 JSON，而是表单字段时，要使用 Form。

#### 安装

`pip install python-multipart`

#### HTML

```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
</head>
<body>
<form method="post" action="http://127.0.0.1:8000/login">
    <span>账号：</span><input type="text" name="username">
    <br>
    <span>密码：</span><input type="password" name="password">
    <br>
    <input type="submit" value="登录">
</form>
</body>
</html>
```

#### FastAPI

```python
from fastapi import FastAPI, Form
import uvicorn
app = FastAPI()
@app.post("/login/")
async def login(username: str = Form(), password: str = Form()):
    return {"username": username}
if __name__ == '__main__':
    uvicorn.run(app='main:app', reload=True)
```

### 文件上传

```python
from fastapi import FastAPI, UploadFile
from fastapi.responses import HTMLResponse
@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    print(file.file.read().decode())
    return {"filenames": file.filename, "type": str(type(file.file))}
@app.get("/")
async def main():
    content = """<body>
<form action="/uploadfile/" enctype="multipart/form-data" method="post">
<input name="file" type="file" multiple>
<input type="submit">
</form>
</body>"""
    return HTMLResponse(content=content)
```

#### UploadFile属性

| 属性名       | 含义     | 返回                                    |
| ------------ | -------- | --------------------------------------- |
| filename     | 文件名   | 上传的文件名                            |
| content_type | 内容类型 | MIME 类型                               |
| file         | 文件     | SpooledTemporaryFile具有read，write方法 |

#### UploadFile async方法

| 方法名       | 含义                                      |
| ------------ | ----------------------------------------- |
| write(data)  | 把 `data` 写入文件                        |
| read(size)   | 按指定数量的字节读取文件内容              |
| seek(offset) | 移动至文件 `offset` （`int`）字节处的位置 |
| close()      | 关闭文件                                  |

参考
---

- [Python 备忘清单](./python.md) _(jaywcjlove.github.io)_
- [FastAPI 官方文档](https://fastapi.tiangolo.com/zh/tutorial/) _(fastapi.tiangolo.com)_