FastAPI 请求参数

RESTful API 简介

这里只做简单介绍，更多信息请查看阮一峰的文章RESTful API 设计指南

在 RESTful API 的定义里面，每一个 URL 对应的都是一种资源（ resource），所以 URL 中出现的都是名词，而且对应的都是复数。对这个资源的各种增、删、改、查等操作，通过配合 HTTP 的方法 POST、DELETE、PUT、GET 来实现。对于一个系统的用户资源来讲，我们一般会做如下定义：

GET /users：列出所有用户
POST /users：新建一个用户
GET /users/{id}：获取某个指定用户的信息
PUT /users/{id}：更新某个指定用户的信息（提供该用户的全部信息）
PATCH /users/{id}：更新某个指定用户的信息（提供该用户的部分信息）
DELETE /users/{id}：删除某个用户

后面的文章中我们会慢慢的实现全部的接口

FastAPI 请求

在main.py 中增加一下函数，返回两个用户 Trevor 和 Foo， 用户 ID 分别是 1 和 2 。

@app.get('/users')
def get_users():
    return [
        {"name": "Trevor", "age": 30, "id": 1},
        {"name": "Foo", "age": 20, "id": 2},
    ]

运行程序，然后打开 http://127.0.0.1:8000/docs 将会看到

Screen Shot 2021-09-11 at 3.47.59 PM

点击 Try it out > Execute, 你可以看到请求结果了。

Screen Shot 2021-09-11 at 3.49.22 PM

query 参数

如果列表太长，我们想分页怎么办? 我们来改造下 get_users 函数,增加两个数字参数。

你可能注意到每个参数后面的 int，，这在 python 中被称作 Type Hint，请参照这篇文章做一些了解, 更多信息请查看官方文档。

@app.get('/users')
def get_users(skip: int, limit: int):
    users = [
        {"name": "Trevor", "age": 30, "id": 1},
        {"name": "Foo", "age": 20, "id": 2},
        {"name": "Foo3", "age": 20, "id": 3},
        {"name": "Foo4", "age": 20, "id": 4},
        {"name": "Foo5", "age": 20, "id": 5},
        {"name": "Foo6", "age": 20, "id": 6},
        {"name": "Foo7", "age": 20, "id": 7},
        {"name": "Foo8", "age": 20, "id": 8},
        {"name": "Foo9", "age": 20, "id": 9},
        {"name": "Foo10", "age": 20, "id": 10},
    ]
    return users[skip:skip+limit]

在打开 docs 来看一下，如下图所示，函数的参数会自动被识别为 query 参数。

Screen Shot 2021-09-11 at 4.20.28 PM

输入skip = 1，limit=5, 得到一下结果, id 从 2 开始，总共 5 个 user。

[
  {
    "name": "Foo",
    "age": 20,
    "id": 2
  },
  {
    "name": "Foo3",
    "age": 20,
    "id": 3
  },
  {
    "name": "Foo4",
    "age": 20,
    "id": 4
  },
  {
    "name": "Foo5",
    "age": 20,
    "id": 5
  },
  {
    "name": "Foo6",
    "age": 20,
    "id": 6
  }
]

如果需要可选参数怎么办？那你就需要 Optional了。如果有些参数需要默认值怎么办？我们继续改造 get_users

@app.get('/users')
def get_users(limit: int, name: Optional[str] = None, skip: int = 0):
    users = []
       ....
    return {
        "limit": limit,
        "skipt": skip,
        "name": name,
        "items": users[skip:skip+limit]
    }

然后再来看文档，limit 是必需，name 是可选，skip 给了默认值 0

Screen Shot 2021-09-11 at 5.05.37 PM

数据类型校验

如果你在定义函数的时候定义了具体累心个，FastAPI 会自动进行类型校验。我们通过下面的方式给 limit 一个 float 类型。将下面的代码在 Terminal 内运行一下。

 curl -X 'GET' \
  'http://127.0.0.1:8000/users?limit=5.5&skip=0' \  
  -H 'accept: application/json'

你会得到下面的结果,告诉你错误的参数类型、名称和具体的错误信息，真香。

{
    "detail": [
        {
            "loc": [
                "query",  // 参数类型
                "limit"   // 参数名称
            ],
            "msg": "value is not a valid integer",  // 错误信息
            "type": "type_error.integer"   
        }
    ]
}