跳到内容

异常 - HTTPExceptionWebSocketException

这些是你可以在代码中抛出以向客户端显示错误的异常。

当你抛出异常时,就像正常的 Python 代码一样,后续的执行将被中止。这样你就可以在代码的任何地方抛出这些异常,以中止请求并向客户端显示错误。

你可以使用

  • HTTPException
  • WebSocketException

这些异常可以直接从 fastapi 导入

from fastapi import HTTPException, WebSocketException

fastapi.HTTPException

HTTPException(status_code, detail=None, headers=None)

基类: HTTPException

你可以在自己的代码中抛出此 HTTP 异常,以向客户端显示错误。

这适用于客户端错误、无效认证、无效数据等情况。不适用于你代码中的服务器错误。

更多信息请参阅 FastAPI 错误处理文档

示例

from fastapi import FastAPI, HTTPException

app = FastAPI()

items = {"foo": "The Foo Wrestlers"}


@app.get("/items/{item_id}")
async def read_item(item_id: str):
    if item_id not in items:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item": items[item_id]}
参数 描述
status_code

发送给客户端的 HTTP 状态码。

类型: int

detail

在 JSON 响应的 detail 键中发送给客户端的任何数据。

类型: Any 默认值: None

headers

在响应中发送给客户端的任何头信息。

类型: Optional[Dict[str, str]] 默认值: None

源码位于 fastapi/exceptions.py
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
def __init__(
    self,
    status_code: Annotated[
        int,
        Doc(
            """
            HTTP status code to send to the client.
            """
        ),
    ],
    detail: Annotated[
        Any,
        Doc(
            """
            Any data to be sent to the client in the `detail` key of the JSON
            response.
            """
        ),
    ] = None,
    headers: Annotated[
        Optional[Dict[str, str]],
        Doc(
            """
            Any headers to send to the client in the response.
            """
        ),
    ] = None,
) -> None:
    super().__init__(status_code=status_code, detail=detail, headers=headers)

status_code instance-attribute

status_code = status_code

detail instance-attribute

detail = detail

headers instance-attribute

headers = headers

fastapi.WebSocketException

WebSocketException(code, reason=None)

基类: WebSocketException

你可以在自己的代码中抛出此 WebSocket 异常,以向客户端显示错误。

这适用于客户端错误、无效认证、无效数据等情况。不适用于你代码中的服务器错误。

FastAPI 官方文档的“WebSockets”部分 阅读更多信息。

示例

from typing import Annotated

from fastapi import (
    Cookie,
    FastAPI,
    WebSocket,
    WebSocketException,
    status,
)

app = FastAPI()

@app.websocket("/items/{item_id}/ws")
async def websocket_endpoint(
    *,
    websocket: WebSocket,
    session: Annotated[str | None, Cookie()] = None,
    item_id: str,
):
    if session is None:
        raise WebSocketException(code=status.WS_1008_POLICY_VIOLATION)
    await websocket.accept()
    while True:
        data = await websocket.receive_text()
        await websocket.send_text(f"Session cookie is: {session}")
        await websocket.send_text(f"Message text was: {data}, for item ID: {item_id}")
参数 描述
code

协议中定义的 有效关闭码 之一。

类型: int

reason

关闭 WebSocket 连接的原因。

它是 UTF-8 编码的数据。原因的解释取决于应用程序,WebSocket 协议未对其进行规定。

它可能包含人类可读的文本,或客户端代码可解释的文本等。

类型: Union[str, None] 默认值: None

源码位于 fastapi/exceptions.py
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
def __init__(
    self,
    code: Annotated[
        int,
        Doc(
            """
            A closing code from the
            [valid codes defined in the specification](https://datatracker.ietf.org/doc/html/rfc6455#section-7.4.1).
            """
        ),
    ],
    reason: Annotated[
        Union[str, None],
        Doc(
            """
            The reason to close the WebSocket connection.

            It is UTF-8-encoded data. The interpretation of the reason is up to the
            application, it is not specified by the WebSocket specification.

            It could contain text that could be human-readable or interpretable
            by the client code, etc.
            """
        ),
    ] = None,
) -> None:
    super().__init__(code=code, reason=reason)

code instance-attribute

code = code

reason instance-attribute

reason = reason or ''