让我们一起走向未来
🎓作者简介:全栈领域优质创作者
🌐个人主页:百锦再@新空间代码工作室
💡座右铭:坚持自己的坚持,不要迷失自己!要快乐
uvicorn启动
Uvicorn是一个轻量级的ASGI(Asynchronous Server Gateway Interface)服务器,用于托管Python异步Web应用程序。它通常与FastAPI、Starlette等现代异步框架一起使用。以下是如何使用Uvicorn启动一个异步Web应用程序的基本步骤:
安装Uvicorn
首先,你需要确保Uvicorn已经安装在你的Python环境中。如果还没有安装,可以通过pip安装:
pip install uvicorn
创建一个简单的异步Web应用程序
创建一个Python文件,比如main.py
,并写入以下代码:
# main.py
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def read_root():
return {"Hello": "World"}
@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
return {"item_id": item_id, "q": q}
启动Uvicorn服务器
使用命令行启动Uvicorn服务器,指向你的应用程序文件。假设你的应用程序文件名为main.py
,并且你定义的应用程序实例名为app
:
uvicorn main:app --reload
这里的--reload
参数表示在代码发生变化时自动重载服务器,这对于开发非常有用。
访问你的应用程序
启动服务器后,你可以通过浏览器或者使用工具如curl
访问http://127.0.0.1:8000
来看到你的应用程序响应。
例如,访问主页:
curl http://127.0.0.1:8000
或者访问一个具体的路由:
curl http://127.0.0.1:8000/items/1
注意事项
- Uvicorn默认监听
127.0.0.1
(localhost)的8000
端口。你可以通过--host
和--port
参数来改变监听的地址和端口。 - 使用
--reload
参数时,服务器会在代码变化时自动重启,这适用于开发环境。在生产环境中,你应该去掉--reload
参数,并使用其他方式来管理应用的部署和重启。 - Uvicorn支持多种工作模式,包括
lifespan
和startup
,这些可以在生产环境中用于初始化和清理操作。
通过这些步骤,你可以快速启动并运行一个基于Uvicorn的异步Web应用程序。
配置大全
Uvicorn 提供了丰富的配置选项,以下是一些常用的配置大全:
基本配置
-
--host
:指定主机地址,默认为127.0.0.1
。 -
--port
:指定端口号,默认为8000
。 -
--uds
:指定UNIX域套接字路径,例如--uds /tmp/uvicorn.sock
。 -
--fd
:指定文件描述符来绑定套接字。
开发配置
-
--reload
:启用自动重载。 -
--reload-dir
:指定监视Python文件更改的目录。 -
--factory
:将APP
视为应用工厂,即一个() -> <ASGI app>
可调用对象。
性能优化
-
--workers
:指定工作进程数量,默认为 CPU 核心数的 1 倍。 -
--threads
:指定每个工作进程的线程数。
安全配置
-
--ssl-keyfile
:指定SSL密钥文件。 -
--ssl-certfile
:指定SSL证书文件。
日志配置
-
--log-level
:设置日志级别,选项包括 ‘critical’, ‘error’, ‘warning’, ‘info’, ‘debug’, ‘trace’,默认为 ‘info’。 -
--no-access-log
:仅禁用访问日志,不更改日志级别。 -
--use-colors
/--no-use-colors
:启用/禁用日志记录的彩色格式。 --log-config
:日志配置文件路径,支持.json
、.yaml
格式。
部署配置
-
--env-file
:指定环境配置文件路径。
高级功能
-
--middleware
:指定中间件。
这些配置可以帮助你根据不同的需求来调整 Uvicorn 的行为,无论是在开发环境还是生产环境中。通过这些配置,你可以优化性能、增强安全性、自定义日志记录等。
FastAPI 的路径操作装饰器(如 @app.get
, @app.post
等)允许你定义路由和处理 HTTP 请求。这些装饰器接受多个参数,用以配置路由的行为。以下是这些参数的详解:
1. path
- 类型:
str
- 描述:定义路由的路径。
- 示例:
@app.get("/items/{item_id}")
2. include_in_schema
- 类型:
bool
- 默认值:
True
- 描述:指定是否在 OpenAPI schema 中包含该路由。
- 示例:
@app.get("/items/", include_in_schema=False)
3. response_model
- 类型:
Type[BaseModel]
或Union[Type[BaseModel], dict]
- 描述:指定响应模型,用于自动响应验证和文档生成。
- 示例:
from pydantic import BaseModel
class Item(BaseModel):
name: str
@app.get("/items/", response_model=List[Item])
4. response_model_include
- 类型:
str
- 描述:控制响应模型中包含的字段(
"all"
,"preset"
,"custom"
)。 - 示例:
@app.get("/items/", response_model=Item, response_model_include="preset")
5. response_model_exclude
- 类型:
List[str]
- 描述:从响应模型中排除指定字段。
- 示例:
@app.get("/items/", response_model=Item, response_model_exclude={"price"})
6. response_model_by_alias
- 类型:
bool
- 默认值:
True
- 描述:是否使用别名作为 JSON 键。
- 示例:
@app.get("/items/", response_model=Item, response_model_by_alias=False)
7. responses
- 类型:
dict
- 描述:定义额外的响应状态码和响应模型。
- 示例:
@app.get("/items/", responses={"404": {"model": Item}})
8. status_code
- 类型:
int
- 描述:指定响应的 HTTP 状态码。
- 示例:
@app.get("/items/", status_code=200)
9. tags
- 类型:
List[str]
- 描述:为路由添加标签,用于 OpenAPI 文档中的分组。
- 示例:
@app.get("/items/", tags=["items"])
10. summary
- 类型:
str
- 描述:为路由提供简短的描述,用于 OpenAPI 文档。
- 示例:
@app.get("/items/", summary="获取项目列表")
11. description
- 类型:
str
- 描述:为路由提供详细的描述,用于 OpenAPI 文档。
- 示例:
@app.get("/items/", description="获取项目列表的详细描述")
12. deprecated
- 类型:
bool
- 默认值:
False
- 描述:标记路由为已弃用,在 OpenAPI 文档中显示。
- 示例:
@app.get("/items/", deprecated=True)
13. include_in_schema
- 类型:
bool
- 默认值:
True
- 描述:指定是否在 OpenAPI schema 中包含该路由。
- 示例:
@app.get("/items/", include_in_schema=False)
14. response_class
- 类型:
Type[Response]
- 描述:自定义响应类。
- 示例:
from fastapi.responses import JSONResponse
@app.get("/items/", response_class=JSONResponse)
这些参数提供了强大的灵活性,使得你可以精确控制路由的行为和响应。通过合理使用这些参数,你可以构建功能丰富且高度可配置的 API 接口。
Fastapi接口的各种参数详解
FastAPI 接口参数主要分为五类:路径参数(Path Parameters)、查询参数(Query Parameters)、请求体(Request Body)、表单参数(Form Parameters)和头参数(Header Parameters)。下面将详细解释这些参数的使用方法和配置选项。
1. 路径参数(Path Parameters)
路径参数是 URL 的一部分,必须在 URL 中明确指定。
- 参数定义:
@app.get("/items/{item_id}")
async def read_item(item_id: int):
return {"item_id": item_id}
在这里,{item_id}
是一个路径参数,它将匹配任何位于 /items/
后面的部分,并将其作为 item_id
参数传递给函数。
2. 查询参数(Query Parameters)
查询参数在 URL 的查询字符串中,不是必须的,可以有默认值。
- 参数定义:
@app.get("/items/")
async def read_items(q: str = None):
return {"q": q}
在这里,q
是一个查询参数,如果 URL 中包含 ?q=value
,则 q
将被设置为 value
,否则为 None
。
3. 请求体(Request Body)
请求体参数来自于请求的正文,通常用于 POST 和 PUT 请求。
- 参数定义:
from pydantic import BaseModel
class Item(BaseModel):
name: str
description: str = None
price: float
tax: float = None
@app.post("/items/")
async def create_item(item: Item):
return {"item": item}
在这里,item
是一个请求体参数,FastAPI 将自动解析 JSON 请求体并将其转换为 Item
类的实例。
4. 表单参数(Form Parameters)
表单参数来自于表单数据(通常在 application/x-www-form-urlencoded
或 multipart/form-data
请求中)。
- 参数定义:
from fastapi import Form
@app.post("/items/")
async def create_item(name: str = Form(...), description: str = Form(None)):
return {"name": name, "description": description}
在这里,name
和 description
是表单参数,Form(...)
表示该参数是必须的,Form(None)
表示该参数是可选的。
5. 头参数(Header Parameters)
头参数来自于 HTTP 请求的头部。
- 参数定义:
from fastapi import Header
@app.get("/items/")
async def read_items(x_token: str = Header(None)):
return {"x_token": x_token}
在这里,x_token
是一个头参数,如果请求头中包含 X-Token
,则 x_token
将被设置为对应的值,否则为 None
。
额外参数详解
- 依赖注入(Dependencies):
FastAPI 支持依赖注入,可以在路径操作函数之前执行代码。
from fastapi import Depends
def get_token(x_token: str = Header(None)):
return x_token
@app.get("/items/")
async def read_items(token: str = Depends(get_token)):
return {"token": token}
- 响应模型(Response Model):
使用 Pydantic 模型作为响应模型,FastAPI 将自动处理响应数据的序列化。
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
@app.get("/items/", response_model=List[Item])
async def read_items():
return [{"name": "Foo", "price": 50.2}, {"name": "Bar", "price": 62.0}]
- 响应状态码(Response Status Code):
可以指定响应的 HTTP 状态码。
@app.get("/items/", status_code=200)
async def read_items():
return {"message": "Hello World"}
- 响应描述(Response Descriptions):
为不同的响应状态码添加描述。
from fastapi import HTTPException
@app.get("/items/")
async def read_items():
if some_condition:
raise HTTPException(status_code=404, detail="Item not found")
return {"item": "Foo"}
FastAPI 的这些参数提供了强大的灵活性和功能,使得你可以构建复杂且功能丰富的 API 接口。通过合理使用这些参数,你可以控制请求的数据,并根据需要进行验证和处理。