应用程序类

Falcon同时支持WSGI (falcon.App )以及ASGI (falcon.asgi.App )协议。通过实例化相应的 App 类来创建可调用的WSGI或ASGI“应用程序”。

因为Falcon的 App 类是基于 WSGI 和 ASGI ，您可以用任何符合标准的服务器托管它们。

import falcon
import falcon.asgi

wsgi_app = falcon.App()
asgi_app = falcon.asgi.App()

WSGI应用程序

class falcon.App(media_type='application/json', request_type=<class 'falcon.request.Request'>, response_type=<class 'falcon.response.Response'>, middleware=None, router=None, independent_middleware=True, cors_enable=False, sink_before_static_route=True)[源代码]

这个类是进入基于Falcon的WSGI应用程序的主要入口点。

每个App实例都提供一个可调用的 WSGI 接口和路由引擎(对于ASGI应用，请参阅 falcon.asgi.App )。

备注

这个 API 类已重命名为 App 在Falcon3.0中。为了向后兼容，旧的类名仍然可以作为别名使用，但在将来的版本中将被删除。

关键字参数:

  • media_type (str) -- 初始化时要使用的默认媒体类型 RequestOptions 和 ResponseOptions 。这个 falcon 模块为常见媒体类型提供了许多常量，例如 falcon.MEDIA_MSGPACK ， falcon.MEDIA_YAML ， falcon.MEDIA_XML 等。

  • middleware -- 实现以下中间件组件接口的单个中间件组件对象或可迭代的对象(实例化类)。请注意，只需要为您想要处理的事件实现方法；Falcon只需跳过任何缺少的中间件方法：：class ExampleComponent：def process_request(self，req，resp)：“在路由请求之前对其进行处理。注意：因为Falcon根据req.path路由每个请求，所以通过在process_request()中将该属性设置为新值，可以有效地重新路由请求。args：req：最终将路由到ON_的请求对象 * responder method. resp: Response object that will be routed to the on_* 应答者。“def process_resource(self，req，resp，resource，params)：”处理请求和资源 之后 路由。注意：仅当请求与资源的路由匹配时才会调用此方法。args：req：将传递给路由响应方的请求对象。Resp：将传递给响应器的响应对象。资源：请求被路由到的资源对象。如果未找到请求的路由，则可能为None。params：一个类似字典的对象，表示从路由的URI模板字段派生的任何附加参数，它将作为关键字参数传递给资源的响应器方法。“def PROCESS_RESPONSE(SELF，REQ，RESP，RESOURCE，REQ_SUCCESSED)”响应的后处理(在路由之后)。args：req：请求对象。Resp：响应对象。资源：请求被路由到的资源对象。如果未找到请求的路由，则可能为None。REQ_SUCCESSED：如果框架处理和路由请求时没有引发异常，则为true；否则为false。“”(另请参阅： Middleware )

  • request_type -- Request -要使用的类，而不是Falcon的默认类。除了其他功能之外，此功能还提供了从 falcon.Request 为了重写 context_type 类变量(默认值： falcon.Request )

  • response_type -- Response -要使用的LIKE类，而不是Falcon的默认类(默认： falcon.Response )

  • router (object) -- 用于替代默认引擎的自定义路由器的实例。（另见： Custom Routers ）

  • independent_middleware (bool) -- 设置为 False 如果响应中间件不能独立于请求中间件是否引发异常而执行（默认 True ）。当此选项设置为 False ，中间件组件的 process_response() 当同一组件的 process_request() （或堆栈中较高的组件）引发异常。

  • cors_enable (bool) -- 将此标志设置为 True 为所有响应启用简单的CORS策略，包括对飞行前请求的支持。的一个实例 CORSMiddleware 可以改为传递给中间件参数以自定义其行为。(默认 False )。(另请参阅： CORS )

  • sink_before_static_route (bool) -- 指示是否应在此之前(何时)处理接收器 True )或之后(当 False )静电路线。这仅在没有匹配的路由时才有效。(默认 True )

req_options

一组与传入请求相关的行为选项。（另见： RequestOptions ）

类型:

falcon.request.RequestOptions

resp_options

与传出响应相关的一组行为选项。（另见： ResponseOptions ）

类型:

falcon.response.ResponseOptions

router_options

路由器的配置选项。如果正在使用自定义路由器，并且它不公开任何可配置选项，则引用此属性将引发 AttributeError .

（另见： CompiledRouterOptions ）

add_error_handler(exception: Union[Type[BaseException], Iterable[Type[BaseException]]], handler: Optional[Callable[[Request, Response, BaseException, dict], Any]] = None)[源代码]

为一个或多个异常类型注册处理程序。

可以为任何异常类型注册错误处理程序，包括 HTTPError 或 HTTPStatus .这个特性为日志记录和处理由响应程序、钩子和中间件组件引发的异常提供了一个中心位置。

处理程序可以引发的实例 HTTPError 或 HTTPStatus 向客户传达有关问题的信息。或者，处理程序可以修改 resp 直接。

如果引发的异常是相应异常类型的实例，则错误处理程序与该异常“匹配”。如果多个错误处理程序与引发的异常匹配，框架将选择最具体的一个，这由引发的异常类型的方法解析顺序确定。如果注册了多个错误处理程序，则 same 异常类，则使用最近注册的处理程序。

例如，假设我们按如下方式注册错误处理程序：

app = App()
app.add_error_handler(falcon.HTTPNotFound, custom_handle_not_found)
app.add_error_handler(falcon.HTTPError, custom_handle_http_error)
app.add_error_handler(Exception, custom_handle_uncaught_exception)
app.add_error_handler(falcon.HTTPNotFound, custom_handle_404)

如果有一个实例 falcon.HTTPForbidden 被引发，它将由 custom_handle_http_error() 。 falcon.HTTPError 是的超类 falcon.HTTPForbidden 和一个子类 Exception ，因此它是具有注册处理程序的最具体的异常类型。

如果有一个实例 falcon.HTTPNotFound 被引发，它将由 custom_handle_404() ，而不是由 custom_handle_not_found() ，因为 custom_handle_404() 是最近注册的。

备注

缺省情况下，框架安装三个处理程序，一个用于 HTTPError ，一个用于 HTTPStatus ，一个用于标准 Exception 类型，这样可以防止将未捕获的异常传递给WSGI服务器。可以通过为所讨论的异常类型添加自定义错误处理程序方法来覆盖这些方法。

参数:

  • exception (type or iterable of types) -- 在处理请求时，每当发生属于指定类型的实例的错误时，将调用关联的处理程序。可以指定单个类型或类型的ITerable。

  • handler (callable) -- 采用以下形式的函数或可调用对象 func(req, resp, ex, params) 。如果未显式指定，则处理程序将缺省为 exception.handle ，在哪里 exception 是上面指定的错误类型，并且 handle 是静电方法(即，用 @staticmethod )，它接受与刚才描述的参数相同的参数。例如：：CLASS CustomException(CustomBaseException)：@staticmethod def Handle(req，resp，ex，params)：#TODO：记录错误#CONVERT TO TERVER TO FORK FORCON。HTTPError RAISE FORCON.HTTPError(FLACON.HTTP_792)如果指定的是异常类型的可迭代类型，而不是单个类型，则必须显式指定处理程序。

在 3.0 版本发生变更: 错误处理程序现在由最具体的匹配错误类选择，而不是由最近注册的匹配错误类选择。

add_middleware(middleware: object) → None[源代码]

添加一个或多个附加中间件组件。

参数:

middleware -- 要添加的单个中间件组件或组件的可迭代。组件将被按顺序调用，就好像它们已被附加到传递给类初始化器的原始中间件列表中一样。

add_route(uri_template: str, resource: object, **kwargs)[源代码]

将模板化的URI路径与资源关联。

Falcon根据一组URI模板将传入请求路由到资源。如果客户机请求的路径与给定路由的模板匹配，则请求将被传递到关联的资源进行处理。

备注

如果没有与请求匹配的路由，则控件将传递给只引发 HTTPRouteNotFound . 默认情况下，此错误将呈现为404响应，但可以通过添加自定义错误处理程序来修改此行为（另请参见 this FAQ topic ）

另一方面，如果路由匹配，但资源没有为请求的HTTP方法实现响应程序，则框架将调用一个默认响应程序，该响应程序将引发 HTTPMethodNotAllowed .

此方法委托给已配置的路由器的 add_route() 方法。若要重写默认行为，请将自定义路由器对象传递给 App 初始化器。

（另见： Routing ）

参数:

  • uri_template (str) -- 模板化的URI。必须注意确保模板不会掩蔽任何水槽图案(如果注册了任何水槽图案)。(另请参阅： add_sink() )..警告：：如果 strip_url_path_trailing_slash 已启用， uri_template 应该在没有尾随劈开的情况下提供。(另请参阅： Falcon如何处理请求路径中的尾随斜杠？ )

  • resource (instance) -- 对象，该对象表示睡觉资源。Falcon将GET请求传递给 on_get() ，将请求提交给 on_put() 如果您的资源不支持任何HTTP方法，只要不定义相应的请求处理程序，Falcon就会做正确的事情。。。注意：使用异步版本的 App ，所有请求处理程序都必须是可等待的协程函数。

关键字参数:

  • suffix (str) -- 此路由的可选响应方名称后缀。如果提供后缀，Falcon会将GET请求映射到 on_get_{{suffix}}() ，将请求发布到 on_post_{{suffix}}() 这样，可以将多个紧密相关的路由映射到同一资源。例如，单个资源类可以使用带后缀的响应器来区分对单个项目的请求与对这些相同项目的集合的请求。除了资源的常规路由之外，另一个类可能使用带后缀的响应器来处理快捷链接路由。例如：：class baz(Object)：def on_get_foo(self，req，resp)：pass def on_get_bar(self，req，resp)：pass baz=baz()app=Falcon.App()app.add_route(‘/foo’，baz，suffix=‘foo’)app.add_route(‘/bar’，baz，suffix=‘bar’)

  • compile (bool) -- 使用默认值时可以提供的可选标志 CompiledRouter 编译此调用的路由逻辑，因为否则它将延迟编译，直到路由第一个请求。看见 CompiledRouter.add_route() 了解更多详细信息。

备注

上面未定义的任何其他关键字参数都将传递给基础路由器 add_route() 方法。默认路由器忽略任何其他关键字参数，但自定义路由器可能利用此功能在设置路由时接收其他选项。自定义路由器必须使用可变模式接受此类参数 (**kwargs ）并忽略它们不支持的任何关键字参数。

add_sink(sink: Callable, prefix: Union[str, Pattern] = '/')[源代码]

为App注册接收器方法。

如果没有与请求匹配的路由，但请求的URI中的路径与接收器前缀匹配，则falcon将把控制权传递给关联的接收器，而不考虑请求的HTTP方法。

当创建静态资源和响应程序时，使用接收器可以排出并动态处理大量路由，这是不切实际的。例如，您可以使用接收器创建智能代理，将请求转发到一个或多个后端服务。

参数:

  • sink (callable) -- 采用以下形式的可调用对象 func(req, resp, **kwargs) 。。。注意：使用异步版本的 App ，这一定是一个协和程序。

  • prefix (str) -- 一个正则表达式字符串，通常以“/”开头，如果它与请求的URI的路径部分匹配，它将触发接收器。可以同时指定字符串和预编译的regex对象。字符从URI路径的开头开始匹配。。注意：命名的组被转换成kwargs，并以此方式传递到接收器。。警告：如果前缀与已注册的路由模板重叠，则路由将优先，并屏蔽接收器。（另见： add_route() ）

add_static_route(prefix: str, directory: Union[str, Path], downloadable: bool = False, fallback_filename: Optional[str] = None)[源代码]

将路由添加到静态文件目录。

静态路由提供了一种直接服务文件的方法。当您没有该选项、需要授权或出于测试目的时，此功能提供了在Web服务器级别提供文件的替代方法。

警告

直接从Web服务器（而不是通过python应用程序）提供文件服务的效率总是更高的，因此在生产部署中应该首选。出于安全原因，对于运行应用程序的帐户，目录和回退文件名（如果提供）应为只读。

警告

如果您需要通过Falcon应用程序提供大文件和/或渐进式下载(例如视频流)，请检查您的应用程序服务器的超时设置是否可以满足预期的请求持续时间(例如，流行的Gunicorn Kill sync 30秒后工作)，除非另有配置)。

备注

对于ASGI应用程序，通过在默认执行器上调度文件读取，使文件读取成为非阻塞的。

静态路由按后进先出顺序匹配。因此，如果两个路由使用相同的前缀，则第二个路由将覆盖第一个路由。这也意味着应该增加更具体的路线 之后 不太具体的。例如，以下序列将导致 '/foo/bar/thing.js' 被映射到 '/foo/bar' 路线，以及 '/foo/xyz/thing.js' 被映射到 '/foo' 路线：

app.add_static_route('/foo', foo_path)
app.add_static_route('/foo/bar', foobar_path)
参数:

  • prefix (str) -- 与此路由匹配的路径前缀。如果请求的URI中的路径以该字符串开头，则路径的其余部分将附加到源目录以确定要提供的文件。这样做是安全的，以防止攻击者在指定目录之外请求文件。请注意，静态路由按后进先出的顺序匹配，并且仅在检查动态路由和接收器之后尝试。

  • directory (Union[str, pathlib.Path]) -- 提供文件的源目录。

  • downloadable (bool) -- 设置为 True 在响应中包含内容处置头。“file name”指令只是设置为请求文件的名称。

  • fallback_filename (str) -- 找不到请求的文件时使用的回退文件名。可以是前缀文件夹内的相对路径，也可以是任何有效的绝对路径。

set_error_serializer(serializer: Callable[[Request, Response, BaseException], Any])[源代码]

重写的实例的默认序列化程序 HTTPError .

当响应程序引发的实例 HTTPError ，falcon自动将其转换为HTTP响应。默认序列化程序支持JSON和XML，但可以被此方法重写以使用自定义序列化程序以支持其他媒体类型。

备注

如果使用自定义媒体类型，并且该类型包含“+json”或“+xml”后缀，则默认序列化程序将分别将错误转换为json或xml。

备注

的默认错误处理程序，则可能无法调用使用此方法设置的自定义序列化程序 HTTPError 已被覆盖。看见 add_error_handler() 了解更多详细信息。

这个 HTTPError 类包含助手方法，例如 to_json() 和 to_dict() ，可以在自定义序列化程序中使用。例如：：

def my_serializer(req, resp, exception):
    representation = None

    preferred = req.client_prefers((falcon.MEDIA_YAML, falcon.MEDIA_JSON))

    if preferred is not None:
        if preferred == falcon.MEDIA_JSON:
            resp.data = exception.to_json()
        else:
            resp.text = yaml.dump(exception.to_dict(), encoding=None)
        resp.content_type = preferred

    resp.append_header('Vary', 'Accept')
参数:

serializer (callable) -- 形式上的函数 func(req, resp, exception) 在哪里 req 是传递给响应程序方法的请求对象， resp 是响应对象，并且 exception 是的实例 falcon.HTTPError .

ASGI应用程序

class falcon.asgi.App(*args, request_type=<class 'falcon.asgi.request.Request'>, response_type=<class 'falcon.asgi.response.Response'>, **kwargs)[源代码]

这个类是进入基于Falcon的ASGI应用程序的主要入口点。

每个App实例都提供一个可调用的 ASGI 接口和路由引擎(对于WSGI应用程序，请参见 falcon.App )。

关键字参数:

  • media_type (str) -- 初始化时要使用的默认媒体类型 RequestOptions 和 ResponseOptions 。这个 falcon 模块为常见媒体类型提供了许多常量，例如 falcon.MEDIA_MSGPACK ， falcon.MEDIA_YAML ， falcon.MEDIA_XML 等。

  • middleware -- 实现如下所示的中间件组件接口的单个中间件组件对象或可迭代的对象(实例化的类)。该界面支持处理ASGI工作器寿命事件和每个请求的事件。但是，由于寿命事件是ASGI规范的可选部分，因此它们可能会触发，也可能不会触发，具体取决于您的ASGI服务器。寿命事件处理程序可用于执行主事件循环的启动或关闭活动。这方面的一个示例是创建一个连接池，然后关闭该连接池以释放连接。。。注意：在多进程环境中，寿命事件将针对与每个进程关联的单个事件循环独立触发。。。注意：框架要求所有中间件方法都作为协程函数通过 async def 。属性来区分ASGI方法，从而实现既支持ASGI应用程序又支持WSGI应用程序的中间件类 *_async 后缀(另请参阅： Middleware )。只需要为您想要处理的事件实现方法；Falcon只需跳过任何缺少的中间件方法：：class ExampleComponent：Async def process_start(self，scope，event)：“处理ASGI生命周期启动事件。当服务器准备好启动和接收连接时，但在它开始这样做之前调用。要停止启动处理并通知服务器应该终止，只需引发异常，框架就会将其转换为服务器的“lifespan.Startup.Failed”事件。args：Scope(Dict)：生命周期协议的ASGI作用域字典。寿命范围在事件循环的持续时间内存在。event(Dict)：启动事件的ASGI事件字典。“”“Async def PROCESS_SHUTDOWN(Self，Scope，Event)：“处理ASGI寿命关闭事件。在服务器已停止接受连接并关闭所有活动连接时调用。要停止关机处理并通知服务器应该立即终止，只需引发异常，框架就会将其转换为服务器的“lifespan.shutdown.ailed”事件。args：Scope(Dict)：生命周期协议的ASGI作用域字典。寿命范围在事件循环的持续时间内存在。事件(DICT)：关闭事件的ASGI事件字典。“”“Async def process_request(self，req，resp)：“在路由请求之前先处理请求。注意：因为Falcon根据req.path路由每个请求，所以通过在process_request()中将该属性设置为新值，可以有效地重新路由请求。args：req：最终将路由到ON_的请求对象 * responder method. resp: Response object that will be routed to the on_* 应答者。“异步定义PROCESS_RESOURCE(SELF，REQ，RESP，RESOURCE，PARAMS)：”处理请求和资源 之后 路由。注意：仅当请求与资源的路由匹配时才会调用此方法。args：req：将传递给路由响应方的请求对象。Resp：将传递给响应器的响应对象。资源：请求被路由到的资源对象。可能是 None 如果未找到该请求的路由，则返回。params：一个类似字典的对象，表示从路由的URI模板字段派生的任何附加参数，它将作为关键字参数传递给资源的响应器方法。“异步定义PROCESS_RESPONSE(SELF，REQ，RESP，RESOURCE，REQ_SUCCESSED)”响应的后处理(在路由之后)。args：req：请求对象。Resp：响应对象。资源：请求被路由到的资源对象。可能是 None 如果未找到该请求的路由，则返回。REQ_SUCCESSED：如果框架处理和路由请求时没有引发异常，则为true；否则为false。“”(另请参阅： Middleware )

  • request_type -- Request -要使用的类，而不是Falcon的默认类。除了其他功能之外，此功能还提供了从 falcon.asgi.Request 为了重写 context_type 类变量(默认值： falcon.asgi.Request )

  • response_type -- Response -要使用的LIKE类，而不是Falcon的默认类(默认： falcon.asgi.Response )

  • router (object) -- 用于替代默认引擎的自定义路由器的实例。（另见： Custom Routers ）

  • independent_middleware (bool) -- 设置为 False 如果响应中间件不能独立于请求中间件是否引发异常而执行（默认 True ）。当此选项设置为 False ，中间件组件的 process_response() 当同一组件的 process_request() （或堆栈中较高的组件）引发异常。

  • cors_enable (bool) -- 将此标志设置为 True 为所有响应启用简单的CORS策略，包括对飞行前请求的支持。的一个实例 CORSMiddleware 可以改为传递给中间件参数以自定义其行为。(默认 False )。(另请参阅： CORS )

  • sink_before_static_route (bool) -- 指示是否应在此之前(何时)处理接收器 True )或之后(当 False )静电路线。这仅在没有匹配的路由时才有效。(默认 True )

req_options

一组与传入请求相关的行为选项。（另见： RequestOptions ）

类型:

falcon.request.RequestOptions

resp_options

与传出响应相关的一组行为选项。（另见： ResponseOptions ）

类型:

falcon.response.ResponseOptions

ws_options

一组与WebSocket连接相关的行为选项。(另请参阅： WebSocketOptions )

router_options

路由器的配置选项。如果正在使用自定义路由器，并且它不公开任何可配置选项，则引用此属性将引发 AttributeError .

（另见： CompiledRouterOptions ）

add_error_handler(exception: Union[Type[BaseException], Iterable[Type[BaseException]]], handler: Optional[Callable[[Request, Response, BaseException, dict], Any]] = None)[源代码]

为一个或多个异常类型注册处理程序。

可以为任何异常类型注册错误处理程序，包括 HTTPError 或 HTTPStatus .这个特性为日志记录和处理由响应程序、钩子和中间件组件引发的异常提供了一个中心位置。

处理程序可以引发的实例 HTTPError 或 HTTPStatus 向客户传达有关问题的信息。或者，处理程序可以修改 resp 直接。

如果引发的异常是相应异常类型的实例，则错误处理程序与该异常“匹配”。如果多个错误处理程序与引发的异常匹配，框架将选择最具体的一个，这由引发的异常类型的方法解析顺序确定。如果注册了多个错误处理程序，则 same 异常类，则使用最近注册的处理程序。

例如，假设我们按如下方式注册错误处理程序：

app = App()
app.add_error_handler(falcon.HTTPNotFound, custom_handle_not_found)
app.add_error_handler(falcon.HTTPError, custom_handle_http_error)
app.add_error_handler(Exception, custom_handle_uncaught_exception)
app.add_error_handler(falcon.HTTPNotFound, custom_handle_404)

如果有一个实例 falcon.HTTPForbidden 被引发，它将由 custom_handle_http_error() 。 falcon.HTTPError 是的超类 falcon.HTTPForbidden 和一个子类 Exception ，因此它是具有注册处理程序的最具体的异常类型。

如果有一个实例 falcon.HTTPNotFound 被引发，它将由 custom_handle_404() ，而不是由 custom_handle_not_found() ，因为 custom_handle_404() 是最近注册的。

备注

缺省情况下，框架安装三个处理程序，一个用于 HTTPError ，一个用于 HTTPStatus ，一个用于标准 Exception 类型，这样可以防止将未捕获的异常传递给WSGI服务器。可以通过为所讨论的异常类型添加自定义错误处理程序方法来覆盖这些方法。

方法时引发泛型未处理异常。 WebSocket 连接时，默认处理程序将使用标准关闭代码关闭连接 1011 (内部错误)。如果您的ASGI服务器不支持此代码，框架将使用代码 3011 相反，您也可以通过 error_close_code 的属性 ws_options 。

另一方面，如果一个 on_websocket() 响应者引发 HTTPError ，则默认错误处理程序将关闭 WebSocket 与框架的连接关闭通过添加以下内容派生的代码 3000 到HTTP状态代码(例如， 3404 )

参数:

exception (type or iterable of types) -- 在处理请求时，每当发生属于指定类型的实例的错误时，将调用关联的处理程序。可以指定单个类型或类型的ITerable。

关键字参数:

handler (callable) -- 采用以下形式的协程函数：：async def func(req，resp，ex，params，ws=NONE)：pass在WebSocket连接的情况下， resp 参数将为 None ，而 ws 关键字参数将接收 WebSocket 表示连接的对象。如果 handler 未向提供关键字参数 add_error_handler() ，则处理程序将默认为 exception.handle ，在哪里 exception 是上面指定的错误类型，并且 handle 是静电方法(即，用 @staticmethod )，它接受刚才描述的参数。例如：：class CustomException(CustomBaseException)：@staticmethod Async def Handle(req，resp，ex，params)：#TODO：记录错误#CONVERT TERVE TO FORKON。HTTPError RAISE FORCON.HTTPError(Falcon.HTTP_792)注意，如果指定的是异常类型的可迭代类型，而不是单个类型，则必须使用 handler 关键字参数。

add_route(uri_template: str, resource: object, **kwargs)[源代码]

将模板化的URI路径与资源关联。

Falcon根据一组URI模板将传入请求路由到资源。如果客户机请求的路径与给定路由的模板匹配，则请求将被传递到关联的资源进行处理。

备注

如果没有与请求匹配的路由，则控件将传递给只引发 HTTPRouteNotFound . 默认情况下，此错误将呈现为404响应，但可以通过添加自定义错误处理程序来修改此行为（另请参见 this FAQ topic ）

另一方面，如果路由匹配，但资源没有为请求的HTTP方法实现响应程序，则框架将调用一个默认响应程序，该响应程序将引发 HTTPMethodNotAllowed .

此方法委托给已配置的路由器的 add_route() 方法。若要重写默认行为，请将自定义路由器对象传递给 App 初始化器。

（另见： Routing ）

参数:

  • uri_template (str) -- 模板化的URI。必须注意确保模板不会掩蔽任何水槽图案(如果注册了任何水槽图案)。(另请参阅： add_sink() )..警告：：如果 strip_url_path_trailing_slash 已启用， uri_template 应该在没有尾随劈开的情况下提供。(另请参阅： Falcon如何处理请求路径中的尾随斜杠？ )

  • resource (instance) -- 对象，该对象表示睡觉资源。Falcon将GET请求传递给 on_get() ，将请求提交给 on_put() 如果您的资源不支持任何HTTP方法，只要不定义相应的请求处理程序，Falcon就会做正确的事情。。。注意：使用异步版本的 App ，所有请求处理程序都必须是可等待的协程函数。

关键字参数:

  • suffix (str) -- 此路由的可选响应方名称后缀。如果提供后缀，Falcon会将GET请求映射到 on_get_{{suffix}}() ，将请求发布到 on_post_{{suffix}}() 这样，可以将多个紧密相关的路由映射到同一资源。例如，单个资源类可以使用带后缀的响应器来区分对单个项目的请求与对这些相同项目的集合的请求。除了资源的常规路由之外，另一个类可能使用带后缀的响应器来处理快捷链接路由。例如：：class baz(Object)：def on_get_foo(self，req，resp)：pass def on_get_bar(self，req，resp)：pass baz=baz()app=Falcon.App()app.add_route(‘/foo’，baz，suffix=‘foo’)app.add_route(‘/bar’，baz，suffix=‘bar’)

  • compile (bool) -- 使用默认值时可以提供的可选标志 CompiledRouter 编译此调用的路由逻辑，因为否则它将延迟编译，直到路由第一个请求。看见 CompiledRouter.add_route() 了解更多详细信息。

备注

上面未定义的任何其他关键字参数都将传递给基础路由器 add_route() 方法。默认路由器忽略任何其他关键字参数，但自定义路由器可能利用此功能在设置路由时接收其他选项。自定义路由器必须使用可变模式接受此类参数 (**kwargs ）并忽略它们不支持的任何关键字参数。

add_sink(sink: Callable, prefix: Union[str, Pattern] = '/')[源代码]

为App注册接收器方法。

如果没有与请求匹配的路由，但请求的URI中的路径与接收器前缀匹配，则falcon将把控制权传递给关联的接收器，而不考虑请求的HTTP方法。

当创建静态资源和响应程序时，使用接收器可以排出并动态处理大量路由，这是不切实际的。例如，您可以使用接收器创建智能代理，将请求转发到一个或多个后端服务。

参数:

  • sink (callable) -- 采用以下形式的可调用对象 func(req, resp, **kwargs) 。。。注意：使用异步版本的 App ，这一定是一个协和程序。

  • prefix (str) -- 一个正则表达式字符串，通常以“/”开头，如果它与请求的URI的路径部分匹配，它将触发接收器。可以同时指定字符串和预编译的regex对象。字符从URI路径的开头开始匹配。。注意：命名的组被转换成kwargs，并以此方式传递到接收器。。警告：如果前缀与已注册的路由模板重叠，则路由将优先，并屏蔽接收器。（另见： add_route() ）

选项

class falcon.RequestOptions[源代码]

定义一组可配置的请求选项。

此类的实例通过 falcon.App.req_options 和 falcon.asgi.App.req_options 为了配置某些 Request 和 falcon.asgi.Request 行为。

keep_blank_qs_values

设置为 False 忽略缺少值或空值的查询字符串参数（默认值 True ）。对于逗号分隔的值，此选项还确定是否保留已分析列表中的空元素。

类型:

布尔

auto_parse_form_urlencoded

设置为 True 以便在请求的内容类型为时自动使用请求流并将结果合并到请求的查询字符串参数中。 application/x-www-form-urlencoded （默认） False ）

为WSGI应用程序启用此选项将使表单参数可通过 params ， get_param() 等。

警告

这个 auto_parse_form_urlencoded 选项在ASGI应用程序中不受支持，从Falcon 3.0开始，WSGI应用程序不建议使用该选项，而是支持通过访问URL编码的表单 media 。

另请参阅： 如何访问已发布的表单参数？

警告

启用此选项后，请求的正文流将保留在EOF。框架不保留原始数据。

备注

在非ASCII字节的百分比编码之前，字段的字符编码假定为UTF-8。特别节目 _charset_ 字段被忽略（如果存在）。

Falcon希望根据标准W3C算法对表单编码的请求体进行编码（另请参见http://goo.gl/6rlcux）。

类型:

布尔

auto_parse_qs_csv

设置为 True 拆分任何非百分比编码逗号上的查询字符串值(默认 False )。

什么时候 False 中，包含逗号的值保持原样。在此模式下，列表项仅取自查询字符串内相同参数名称的倍数(即 t=1,2,3&t=4 变成了 ['1,2,3', '4'] )。

什么时候 auto_parse_qs_csv 设置为 True 查询字符串值也以非百分比编码的逗号拆分，并且这些项被添加到最终列表(即 t=1,2,3&t=4,5 变成了 ['1', '2', '3', '4', '5'] )。

警告

启用此选项将导致框架误解任何包含文字(非百分比编码)逗号的JSON值。如果查询字符串可能包含JSON，您可以使用JSON数组语法代替CSV作为解决办法。

类型:

布尔

strip_url_path_trailing_slash

设置为 True 为了去掉URL路径末尾的尾随斜杠（如果存在）（默认 False ）。当启用此选项时，通过去除尾随斜杠字符来规范化URL路径。这允许应用程序为可能以正斜杠结尾或不以正斜杠结尾的路径定义到资源的单个路由。但是，在某些情况下，这种行为可能有问题，例如在使用基于URL的签名的身份验证方案时。

类型:

布尔

default_media_type

当Content-Type标头缺失或不明确时，用于反序列化请求正文的默认媒体类型。该值通常设置为提供给 falcon.App 或 falcon.asgi.App 初始值设定项；但是，如果独立创建，则默认为 falcon.DEFAULT_MEDIA_TYPE 。

类型:

STR

media_handlers

用于配置要处理的媒体类型的类字典对象。默认情况下，为 application/json ， application/x-www-form-urlencoded 和 multipart/form-data 媒体类型。

类型:

处理程序

class falcon.ResponseOptions[源代码]

定义一组可配置的响应选项。

此类的实例通过 falcon.App.resp_options 和 falcon.asgi.App.resp_options 为了配置某些 Response 行为。

secure_cookies_by_default

设置为 False 在开发环境中使 secure 所有cookie的属性默认为 False .这可以通过不需要HTTPS来简化测试。但是，请注意，此设置可以通过 set_cookie() 的 secure 克瓦格

类型:

布尔

default_media_type

未显式设置Content-Type标头时呈现响应时使用的默认Internet媒体类型(RFC 2046)。该值通常设置为在以下情况下提供的媒体类型 falcon.App 已初始化；但是，如果独立创建，则默认为 falcon.DEFAULT_MEDIA_TYPE 。。

类型:

STR

media_handlers

用于配置要处理的媒体类型的类字典对象。默认情况下，为 application/json ， application/x-www-form-urlencoded 和 multipart/form-data 媒体类型。

类型:

处理程序

static_media_types

点前缀文件扩展名到Internet媒体类型的映射（RFC2046）。默认为 mimetypes.types_map 打电话后 mimetypes.init() .

类型:

双关语

class falcon.routing.CompiledRouterOptions[源代码]

定义一组可配置的路由器选项。

此类的实例通过 falcon.App.router_options 和 falcon.asgi.App.router_options 为了配置某些 CompiledRouter 行为。

converters

表示可在URI模板字段表达式中引用的命名转换器的集合。添加额外的转换器只是将标识符映射到转换器类的问题：

app.router_options.converters['mc'] = MyConverter

然后可以使用标识符在URI模板中使用转换器：：

app.add_route('/{some_field:mc}', some_resource)

转换器名称只能包含ASCII字母、数字和下划线，并且必须以字母或下划线开头。

警告

转换器实例在请求之间共享。因此，在线程部署中，必须注意以线程安全的方式实现自定义转换器。

（另见： Field Converters ）