网页 综合 更新时间 2026-11-17 03:00:11

Query Parameters and String Validations - FastAPI

自动蜘蛛 fastapi.tiangolo.com 正文约 3938 字
Use the official FastAPI skill for your installed version. Install it from your project directory:
See Develop with AI.
FastAPI allows you to declare additional information and validation for your parameters.
Let's take this application as example:
The query parameter q is of type str | None, that means that it's of type str but could also be None, and indeed, the default value is None, so FastAPI will know it's not required.
FastAPI will know that the value of q is not required because of the default value = None.
Having str | None will allow your editor to give you better support and detect errors.
We are going to enforce that even though q is optional, whenever it is provided, its length doesn't exceed 50 characters.
To achieve that, first import:
Prefer to use the Annotated version if possible.
FastAPI added support for Annotated (and started recommending it) in version 0.95.0.
If you have an older version, you would get errors when trying to use Annotated.
Make sure you Upgrade the FastAPI version to at least 0.95.1 before using Annotated.
Remember I told you before that Annotated can be used to add metadata to your parameters in the Python Types Intro?
Now it's the time to use it with FastAPI. 🚀
We had this type annotation:
What we will do is wrap that with Annotated, so it becomes:
Both of those versions mean the same thing, q is a parameter that can be a str or None, and by default, it is None.
Now let's jump to the fun stuff. 🎉
Now that we have this Annotated where we can put more information (in this case some additional validation), add Query inside of Annotated, and set the parameter max_length to 50:
Prefer to use the Annotated version if possible.
Notice that the default value is still None, so the parameter is still optional.
But now, having Query(max_length=50) inside of Annotated, we are telling FastAPI that we want it to have additional validation for this value, we want it to have maximum 50 characters. 😎
Here we are using Query() because this is a query parameter. Later we will see others like Path(), Body(), Header(), and Cookie(), that also accept the same arguments as Query().
Previous versions of FastAPI (before 0.95.0) required you to use Query as the default value of your parameter, instead of putting it in Annotated, there's a high chance that you will see code using it around, so I'll explain it to you.
For new code and whenever possible, use Annotated as explained above. There are multiple advantages (explained below) and no disadvantages. 🍰
This is how you would use Query() as the default value of your function parameter, setting the parameter max_length to 50:
As in this case (without using Annotated) we have to replace the default value None in the function with Query(), we now need to set the default value with the parameter Query(default=None), it serves the same purpose of defining that default value (at least for FastAPI).
...makes the parameter optional, with a default value of None, the same as:
But the Query version declares it explicitly as being a query parameter.
Then, we can pass more parameters to Query. In this case, the max_length parameter that applies to strings:
This will validate the data, show a clear error when the data is not valid, and document the parameter in the OpenAPI schema path operation.
Keep in mind that when using Query inside of Annotated you cannot use the default parameter for Query.
Instead, use the actual default value of the function parameter. Otherwise, it would be inconsistent.
For example, this is not allowed:
...because it's not clear if the default value should be "rick" or "morty".
So, you would use (preferably):
...or in older code bases you will find:
Using Annotated is recommended instead of the default value in function parameters, it is better for multiple reasons. 🤓
The default value of the function parameter is the actual default value, that's more intuitive with Python in general. 😌
访问原文 返回搜索 https://fastapi.tiangolo.com/./tutorial/query-params-str-validations/
本页为82搜索生成的网页快照,内容来自站内索引;演示数据的原文链接仅作示例。