Falcon 路由机制完全指南:从 URI 模板、字段转换器到自定义路由引擎
Falcon 路由机制完全指南:从 URI 模板、字段转换器到自定义路由引擎
Falcon 是一个强调"零魔法"(no-magic)、面向性能与可靠性的 Python Web API 与微服务框架。本文基于 docs/api/routing.rst 官方路由文档,系统讲解 Falcon 的核心路由机制:基于资源的 RESTful 路由风格、URI 模板与字段表达式、内置/自定义字段转换器、编译型决策树路由器(CompiledRouter)、后缀响应器(Suffixed Responders)、静态文件路由与自定义 HTTP 方法扩展。读完本文,你将掌握从 add_route() 声明式注册到自定义路由引擎、再到源码级路由匹配原理的完整实战能力。
基于资源的 RESTful 路由模型
Falcon 采用基于资源(resource-based)的路由来鼓励 RESTful 架构风格。与 Flask/Django 那种"URL 映射到视图函数"的模式不同,Falcon 中每个资源由一个 Python 类表示,该类负责处理该资源支持的全部 HTTP 方法。
资源类为每个支持的 HTTP 方法实现一个对应的 responder 方法,命名规则为 on_ + 小写 HTTP 方法名:
on_get()—— 处理 GETon_post()—— 处理 POSTon_put()—— 处理 PUTon_patch()—— 处理 PATCHon_delete()—— 处理 DELETE- 其余方法以此类推(
on_options()、on_head()等)
重要设计原则:资源在 Falcon 中由单个类实例表示,该实例在应用启动配置路由时创建。这种设计最小化了路由开销并简化了资源类实现。但这也意味着:对于 WSGI 应用,资源类必须以线程安全的方式实现(因为多线程 WSGI 服务器会并发调用同一实例)。
最小可用示例
下面是一个完整的 WSGI 路由示例(来自官方文档 docs/api/routing.rst):
import json
import falcon
class ImagesResource:
def on_get(self, req, resp):
doc = {
'images': [
{
'href': '/images/1eaf6ef1-7f2d-4ecc-a8d5-6e8adba7cc0e.png'
}
]
}
# Create a JSON representation of the resource; this could
# also be done automatically by assigning to resp.media
resp.text = json.dumps(doc, ensure_ascii=False)
# The following line can be omitted because 200 is the default
# status returned by the framework, but it is included here to
# illustrate how this may be overridden as needed.
resp.status = falcon.HTTP_200
app = falcon.App()
images = ImagesResource()
app.add_route('/images', images)
对于 ASGI 应用,代码几乎一致,唯一区别是使用 falcon.asgi.App(),且 responder 必须是协程函数(async def):
import json
import falcon
import falcon.asgi
class ImagesResource:
async def on_get(self, req, resp):
doc = {
'images': [
{
'href': '/images/1eaf6ef1-7f2d-4ecc-a8d5-6e8adba7cc0e.png'
}
]
}
resp.text = json.dumps(doc, ensure_ascii=False)
resp.status = falcon.HTTP_200
app = falcon.asgi.App()
images = ImagesResource()
app.add_route('/images', images)
falcon.App.add_route()(WSGI)与 falcon.asgi.App.add_route()(ASGI)用于将 URI 模板与资源关联,Falcon 根据这些模板将请求映射到资源。Falcon 的路由同时覆盖普通 HTTP 请求与 WebSocket 握手。
Responder 的职责与默认行为
responder 至少必须接收两个参数,分别用于接收 falcon.Request 和 falcon.Response 对象:
def on_post(self, req, resp):
pass
req(falcon.Request)表示传入的 HTTP 请求,暴露了用于检查请求头、查询字符串参数及其他元数据的属性和方法,同时提供文件类流对象用于读取请求体数据。resp(falcon.Response)表示应用对该请求的 HTTP 响应,提供设置状态码、响应头和响应体的属性与方法,还暴露了一个 dict 风格的resp.context属性,用于在 hooks 与中间件方法之间传递任意数据。
此外,responder 不一定要直接操作 resp,也可以抛出 HTTPError 或 HTTPStatus 异常,Falcon 会将这些异常转换为对应的 HTTP 响应;也可以自行通过 app.add_error_handler() 处理它们(参见 docs/api/errors.rst)。
路由匹配的默认行为与错误处理
404:无匹配路由
如果没有路由匹配请求,控制权会交给一个默认 responder,该 responder 抛出 HTTPRouteNotFound 实例。默认情况下:
- 普通 HTTP 请求:渲染为 404 响应;
- WebSocket 握手:渲染为 403 响应,关闭码为 3404。
该行为可以通过添加自定义错误处理器修改(参考 FAQ 中关于覆盖 404/500 处理器的条目)。
405:方法不允许
如果路由匹配成功,但资源没有实现请求的 HTTP 方法对应的 responder,框架会调用默认 responder 并抛出 HTTPMethodNotAllowed 实例:
- 普通 HTTP 请求:默认渲染为 405 响应;
- WebSocket 握手:默认渲染为 403 响应,关闭码为 3405。
从源码看,这一逻辑实现在 falcon/routing/util.py 的 set_default_responders() 中:对于资源未显式实现的方法,会通过 falcon/responders.py 的 create_method_not_allowed() 构造一个抛出 HTTPMethodNotAllowed(allowed_methods) 的默认 responder,其中 allowed_methods 会被写入响应的 Allow 头。
# falcon/routing/util.py 中的核心逻辑(节选)
if default_responder is None:
default_responder = responders.create_method_not_allowed(
allowed_methods, asgi=asgi
)
for method in constants.COMBINED_METHODS:
if method not in method_map:
method_map[method] = default_responder
OPTIONS 的默认响应器
Falcon 还为 OPTIONS 请求提供默认 responder,它会考虑目标资源实际实现了哪些方法,并自动在响应中设置 Allow 头。参考 falcon/responders.py 的 create_default_options():
def options_responder(req, resp, **kwargs):
resp.status = HTTP_200
if allowed:
resp.set_header('Allow', allowed)
resp.set_header('Content-Length', '0')
注意 OPTIONS 自身被有意排除在 Allow 头之外(见 set_default_responders() 中的注释),且如果资源未实现 WEBSOCKET responder,框架会为其显式分配 405 默认 responder,避免误用通用默认行为。
默认路由引擎:编译型决策树(CompiledRouter)
Falcon 的默认路由引擎 falcon.routing.CompiledRouter 的实现位于 falcon/routing/compiled.py,其核心设计非常独特:
默认路由引擎基于决策树,该决策树首先被编译为 Python 代码,然后在运行时被求值。
具体而言:
-
将 URI 路径视为分段树:路由把 URI 拆成以
/分隔的段,逐段匹配("static nodes / complex var nodes / simple var nodes")。 -
生成内联 Python 代码:路由查找不是逐条解释路由树,而是生成一段特制的、内联的 Python 源码(
_compile()方法负责),然后用compile()/exec()编译为真正的 Python 函数。生成的查找函数签名形如:def find(path, return_values, patterns, converters, params): path_len = len(path) ... return None -
延迟编译:决策树默认只在路由器处理第一个请求时才编译(
_find初始被设置为_compile_and_find),以缩短应用启动时间。代价是:当路由数量很大时,第一个响应可能明显延迟。 -
compile 标志:在添加最后一个路由时,可以传入
compile=True强制立即编译,从而避免首个请求的延迟。源码注释提醒:若一次性添加数百个路由时总是设置该标志,反而会拖慢路由添加过程,因此建议只在添加最终路由时设置:app.add_route('/last', resource, compile=True) -
线程安全编译:多线程 Web 服务器下,启动时可能同时有多个请求触发路由,因此框架用
threading.Lock(_compile_lock)保证决策树只被编译一次。 -
参数延迟填充:生成代码时,路由参数(
paramsdict)的写入被推迟到分支匹配成功之后(通过params_stack机制),避免在最终不匹配的分支上做无用的字典赋值——这是一种刻意为之的性能优化。
路由模板的合法性校验
CompiledRouter.add_route() 在插入路由树前会执行严格的校验(_validate_template_segment()),不合法时抛出 UnacceptableRouteError(继承自 ValueError):
- 字段名必须是合法 Python 标识符:因为字段名将作为关键字参数传给 responder,因此必须匹配
[A-Za-z_][A-Za-z0-9_]*,且不能是 Python 关键字(keyword.kwlist)。 - 字段名不可重复:同一模板中重复使用字段名会报 "Field names may not be duplicated" 错误。
- URI 模板不能包含空白字符(字段表达式之外的空白)。
- 模板不能包含
//(falcon.App.add_route中会检查并抛出ValueError)。 - 同一路径层级上的简单变量节点不能有多个(如
/foo/{thing1}与/foo/{thing2}冲突),复杂节点(如/foo/{thing1}.{ext}与/foo/{thing2}.{ext})也会被判定为冲突——这些规则在CompiledRouterNode.conflicts_with()中实现。
资源即控制器
Falcon 默认路由器用 Python 类表示资源。在实践中,这些类扮演应用中的**控制器(controller)**角色:把传入请求转换成一个或多个内部动作,再基于动作结果向客户端组装响应:
┌────────────┐
request → │ │
│ Resource │ ↻ Orchestrate the requested action
│ Controller │ ↻ Compose the result
response ← │ │
└────────────┘
URI 模板与字段表达式
除了上述静态路径,Falcon 路由模板支持字段表达式(field expression):由方括号包裹的字段名,例如:
/user/{name}
对 '/user/kgriffs' 的 PUT 请求,框架会调用该路由资源的 on_put() responder,并通过额外的 name 参数传入 'kgriffs':
# WSGI
def on_put(self, req, resp, name):
pass
# ASGI
async def on_put(self, req, resp, name):
pass
模板字段对应于 responder 的命名参数或关键字参数,紧跟常规的 req、resp 之后。
字段表达式的丰富用法
字段名必须是合法 Python 标识符(因为要作为参数名)。字段不必独占整个路径段,单个路径段可以包含多个字段表达式,也可以与字面量混排。官方文档给出了两个非常典型的示例:
/repos/{org}/{repo}/compare/{usr0}:{branch0}...{usr1}:{branch1}
/serviceRoot/People('{name}')
从源码看,字段匹配正则定义在 falcon/routing/compiled.py 的 _FIELD_PATTERN:
r'{((?P<fname>[^}:]*)((?P<cname_sep>:(?P<cname>[^}\(]*))(\((?P<argstr>[^}]*)\))?)?)}'
它同时解析字段名(fname)、转换器名(cname)与转换器参数串(argstr)。如果一个字段只是整个路径段的一部分("复杂节点"),路由编译时会把该段转换为预编译的正则表达式(var_pattern),匹配时用 match.groupdict() 提取字段值。
字段转换器(Field Converters)
字段转换器用于转换 URI 模板字段值,同时可执行简单的输入校验。例如以下模板使用 int 转换器,将 tid 的值转换为 Python int——但仅当其恰好为 8 位数字时:
/teams/{tid:int(8)}
如果值格式错误、无法转换,Falcon 会以 404 响应拒绝请求。
转换器的实例化参数直接取自字段表达式,遵循标准 Python 传参语法。例如 docs/api/routing.rst 中的代码:
# IntConverter()
app.add_route(
'/a/{some_field:int}',
some_resource
)
# IntConverter(8)
app.add_route(
'/b/{some_field:int(8)}',
some_resource
)
# IntConverter(8, min=10000000)
app.add_route(
'/c/{some_field:int(8, min=10000000)}',
some_resource
)
从 falcon/routing/compiled.py 的 _instantiate_converter() 可以看到,参数串会被拼装为 ClassName(args) 形式的源码后求值(源码注释戏称 "Don't try this at home. ;)"),因此参数必须是可求值的字面量表达式。
内置转换器一览
官方文档给出的内置转换器表如下(实现位于 falcon/routing/converters.py):
| 标识符 | 类 | 示例 |
|---|---|---|
int |
IntConverter |
/teams/{tid:int(8)} |
uuid |
UUIDConverter |
/diff/{left:uuid}...{right:uuid} |
dt |
DateTimeConverter |
/logs/{day:dt("%Y-%m-%d")} |
float |
FloatConverter |
/python/versions/{version:float(min=3.7)} |
path |
PathConverter |
/prefix/{other:path} |
re |
RegexConverter |
/prefix/{name:re("[a-zA-Z]+")} |
结合源码,各转换器的详细参数如下:
IntConverter(标识符 int)——将字段值转为 int:
num_digits(int):要求值具有指定位数(至少为 1);min(int):拒绝小于该值的输入;max(int):拒绝大于该值的输入。- 实现细节:
convert()会先检查位数,再拒绝带首尾空白的字符串(int()本身会容忍空白,因此需自行检查),最后做范围校验。
FloatConverter(标识符 float)——将字段值转为 float(自 4.0 起引入):
min(float):拒绝小于该值的输入;max(float):拒绝大于该值的输入;finite(bool):是否只匹配普通有限数,默认True;设为False可额外匹配nan、inf、-inf。
DateTimeConverter(标识符 dt)——将字段值转为 datetime:
format_string(str):用于解析的 strptime 格式,默认'%Y-%m-%dT%H:%M:%S%z'(自 4.0 起从'%Y-%m-%dT%H:%M:%SZ'变更,新格式解析能力是旧格式的超集,且转换出的 datetime 对象是时区感知的)。
UUIDConverter(标识符 uuid)——将字段值转为 uuid.UUID:
- 要求字段值为 32 位十六进制数字字符串(RFC 4122 第 3 节),连字符与 URN 前缀可选。
PathConverter(标识符 path)——匹配 URL 路径的剩余部分并以字符串返回(自 4.0 起引入):
- 内部设置
CONSUME_MULTIPLE_SEGMENTS = True,即会消费模板之后的所有路径段; - 仅支持出现在 URI 模板末尾;
- 经典路由规则同样适用:对模板
/foo/bar/{matched_path:path},路径/foo/bar不会匹配;/foo/bar/会匹配并产生matched_path=''(当strip_url_path_trailing_slash为默认的False时),而当该选项为True时则不会匹配。
RegexConverter(标识符 re)——用正则表达式匹配字段值(自 4.4 起引入):
pattern(str):值必须整体匹配(锚定)的正则;必须是str而非bytes;group(str):可选命名分组,返回该组作为转换后的字段值。若该组在正则中可选(如r'product(?P<id>\d+)?')且匹配时被省略,则视为转换失败(抛出HTTPRouteNotFound,除非有 sink 匹配)。- 注意:若需匹配多段路径,可子类化并设置
CONSUME_MULTIPLE_SEGMENTS = True(见下文自定义转换器示例)。
自定义转换器(Custom Converters)
自定义转换器通过 app.router_options.converters 注册。一个转换器只需实现 BaseConverter 接口即可:
class MyConverter(falcon.routing.BaseConverter):
CONSUME_MULTIPLE_SEGMENTS = False
def convert(self, value):
# 返回转换后的值;无法转换时返回 None
...
注册与使用:
app.router_options.converters['mc'] = MyConverter
app.add_route('/{some_field:mc}', some_resource)
BaseConverter 接口定义在 falcon/routing/converters.py,包含两个成员:
CONSUME_MULTIPLE_SEGMENTS(类属性,默认False):为True时表示该转换器会消费多个 URL 路径段,且此时该转换器必须位于 URL 模板末尾(即消费剩余全部路径段)。此时convert()收到的value是路径段的 list 而非字符串。convert(value)(抽象方法):将字段值转换为其他格式/类型;返回None表示无法转换,Falcon 会据此拒绝该请求(404)。
注册规则(ConverterDict._validate())与字段名一致:转换器名称只能包含 ASCII 字母、数字和下划线,且必须以字母或下划线开头,不能为空。
线程安全警告(源码明确注明):转换器实例在请求之间共享,因此在多线程部署中,自定义转换器必须以线程安全的方式实现。
利用 CONSUME_MULTIPLE_SEGMENTS 定制一个可消费多段的 re 转换器(来自官方文档示例):
class RePathConverter(falcon.routing.RegexConverter):
CONSUME_MULTIPLE_SEGMENTS = True
def convert(self, value):
if not isinstance(value, str):
value = '/'.join(value)
return super().convert(value)
# 注册
app.router_options.converters['repath'] = RePathConverter
通过 router_options 调整路由器行为
falcon.App.router_options(以及 falcon.asgi.App.router_options)暴露 CompiledRouterOptions 实例(falcon/routing/compiled.py),它包含两个可配置项:
-
converters:命名转换器集合(即上述自定义转换器的注册处)。该属性不能整体赋值(__setattr__会抛出AttributeError),只能原地更新,例如app.router_options.converters['mc'] = MyConverter。 -
default_to_on_request(默认False,自 4.3 起引入):启用后,可在资源上定义on_request()作为默认 responder,为所有未单独实现的方法兜底:class Resource: def on_request(self, req, resp): if req.method == 'GET': ... elif req.method == 'POST': ... else: raise falcon.HTTPMethodNotAllowed(['GET', 'POST']) app = falcon.App() app.router_options.default_to_on_request = True app.add_route('/resource', Resource())注意:
on_request只处理未定义方法命名 responder 的方法(例如资源同时定义了on_post与on_request,POST 仍由on_post处理);该选项不会覆盖on_options()与on_websocket()(如需覆盖on_options,可显式别名on_options = on_request或在on_options中显式调用self.on_request(req, resp));该选项必须在调用add_route()之前启用;类级 hooks 默认不包裹默认 responder,可通过设置falcon.hooks.decorate_on_request = True启用。
自定义路由器(Custom Routers)
实例化 falcon.App 或 falcon.asgi.App 时可以传入自定义路由引擎:
router = MyRouter()
app = App(router=router)
自定义路由器可以继承默认的 CompiledRouter,也可以实现完全不同的路由策略(如基于对象的路由)。任何实现以下接口的类都可作为自定义路由器(接口定义见 docs/api/routing.rst):
class MyRouter:
def add_route(self, uri_template, resource, **kwargs):
"""将 URI 路径模板与资源关联。
Args:
uri_template (str): 路由使用的 URI 模板
resource (object): 与该 URI 模板关联的资源实例
Keyword Args:
suffix (str): 可选 responder 名称后缀。提供后,
Falcon 将 GET 请求映射到 on_get_{suffix}(),
POST 映射到 on_post_{suffix}() 等。
**kwargs (dict): 接受传给 falcon.App.add_route() 的
任何额外关键字参数,必须用 **kwargs 双星可变参数
模式接收并忽略不认识的参数。
"""
def find(self, uri, req=None):
"""查找匹配给定部分 URI 的路由。
Args:
uri (str): 要路由的请求路径
Keyword Args:
req (Request): 将被传给被路由 responder 的 Request 对象。
路由器可利用 req 进一步区分请求路由,例如根据某个
请求头判断期望的 API 版本。该参数自 1.2 起加入;
未实现该参数的路由器仍受支持以保证向后兼容。
Returns:
tuple: 由 (resource, method_map, params, uri_template)
组成的 4 元组;若无匹配则返回 None。
"""
其中 req 关键字参数自 Falcon 1.2 起加入,为向后兼容,未实现该参数的路由器依然可用。
后缀响应器(Suffixed Responders)
虽然 Falcon 鼓励 REST 架构风格,但同时也足够灵活以容纳其他范式。官方文档用"计算器 API"的例子说明了这一点。
纯 REST 风格需要为加/减分别创建资源类:
class Add():
def on_get(self, req, resp):
resp.text = str(req.get_param_as_int('x') + req.get_param_as_int('y'))
resp.status = falcon.HTTP_200
class Subtract():
def on_get(self, req, resp):
resp.text = str(req.get_param_as_int('x') - req.get_param_as_int('y'))
resp.status = falcon.HTTP_200
add = Add()
subtract = Subtract()
app = falcon.App()
app.add_route('/add', add)
app.add_route('/subtract', subtract)
但"加"与"减"并不天然对应两个独立的资源集合。此时更适合按动作属性分组(输入两个数 → 处理 → 返回结果),而后缀响应器正是为此设计:
class Calculator():
def on_get_add(self, req, resp):
resp.text = str(req.get_param_as_int('x') + req.get_param_as_int('y'))
resp.status = falcon.HTTP_200
def on_get_subtract(self, req, resp):
resp.text = str(req.get_param_as_int('x') - req.get_param_as_int('y'))
resp.status = falcon.HTTP_200
calc = Calculator()
app = falcon.App()
app.add_route('/add', calc, suffix='add')
app.add_route('/subtract', calc, suffix='subtract')
使用后缀后,responder 按动作而非数据类型分组:/add 路由将 GET 请求映射到 on_get_add(),/subtract 路由映射到 on_get_subtract()。这在纯 REST 范式不适用的场景下提供了额外灵活性。
从源码看,该机制实现在 falcon/routing/util.py 的 map_http_methods() 中:遍历 constants.COMBINED_METHODS,对每个方法拼接 'on_' + method.lower() + '_' + suffix 并 getattr 查找。特别地,如果指定了后缀但资源上找不到任何对应 responder,会抛出 SuffixedMethodNotFoundError("No responders found for the specified suffix"),有助于及早发现拼写错误。
路由工具函数(Routing Utilities)
falcon.routing 模块还提供以下工具,可供自定义路由引擎复用:
falcon.routing.map_http_methods(falcon/routing/util.py):将 HTTP 方法(GET、POST 等)映射到资源对象上的方法。遍历falcon.constants.COMBINED_METHODS,按on_<method>(可选_<suffix>)命名查找可调用对象;未实现的方法自动跳过。falcon.routing.set_default_responders:为资源未显式实现的 HTTP 方法填充默认 responder(405 Method Not Allowed 与自动的 OPTIONS 响应器,以及 WEBSOCKET 的 405)。asgi=True时生成协程版本的默认 responder。falcon.app_helpers.prepare_middleware:检查中间件接口并准备好请求处理方法(仅适用于 WSGI 应用)。falcon.app_helpers.prepare_middleware_ws:同上,但针对 ASGI 应用的 WebSocket 方法(process_request_ws()/process_resource_ws())。
静态文件路由(Static File Routes)
Falcon 可以直接从 WSGI 或 ASGI 应用中提供静态文件服务,使用的是 sink 风格的 falcon.routing.StaticRoute。通常通过 falcon.App.add_static_route 创建实例(该方法的文档中说明了通过 Python 应用提供文件的性能影响,生产环境建议交由 Nginx 等 Web 服务器处理)。
app.add_static_route('/static', '/path/to/static/directory')
StaticRoute(实现见 falcon/routing/static.py)构造参数:
prefix(str):本路由要匹配的路径前缀。请求 URI 中的路径以该字符串开头时,路径的剩余部分会被安全地拼接到源目录以确定要服务的文件——此过程经过严格校验,防止攻击者请求指定目录之外的文件。directory(str/pathlib.Path):从中提供文件的源目录,必须是绝对路径(os.path.isabs校验,否则抛出ValueError)。downloadable(bool):设为True时在响应中包含Content-Disposition头,其filename指令为请求的文件名。fallback_filename(str):请求文件不存在时使用的回退文件名;可以是前缀目录内的相对路径或任意绝对路径。当回退文件被提供时,响应头的Content-Type与Content-Disposition基于回退文件名而非请求文件名推导。
实现要点(源码级细节):
- 匹配顺序:静态路由按 LIFO 顺序匹配,且仅在动态路由与 sinks 之后尝试(见 falcon/app.py 的
add_static_route,新路由通过self._static_routes.insert(0, ...)插入头部)。 - 安全防护:
__call__中拒绝控制字符、~、?、<>、*、|、'、"、反斜杠与//;拒绝以..或/开头的归一化路径;并限制非前缀部分长度不超过 512 字符;最终再做一次file_path.startswith(self._directory)兜底校验。 - 缓存语义:自动设置
ETag(基于 mtime 与 size)与Last-Modified,支持If-None-Match/If-Modified-Since返回 304。 - Range 支持:支持
Range: bytes=...请求,返回 206 部分内容;越界请求返回HTTPRangeNotSatisfiable。 - 下载与媒体类型:
downloadable=True时设置Content-Disposition;媒体类型通过resp.options.static_media_types按扩展名映射,未知扩展名回退application/octet-stream。 - ASGI 版本:
StaticRouteAsync是StaticRoute的子类,将文件读取包装为线程池中的非阻塞异步读取(_AsyncFileReader),并拒绝 WebSocket 请求。
自定义 HTTP 方法
虽然通常不推荐,但某些应用可能需要支持标准方法(如 GET、PUT)之外的非标准 HTTP 方法。Falcon 提供了两种方式:
方式一:无 hooks 时直接修改常量(在应用设置中):
import falcon.constants
falcon.constants.COMBINED_METHODS += ['FOO', 'BAR']
方式二:使用 hooks 时设置环境变量——由于 hooks 的机制,需将自定义方法定义为逗号分隔的环境变量列表:
$ export FALCON_CUSTOM_HTTP_METHODS=FOO,BAR
完成后,自定义方法即可像其他 HTTP 方法一样定义 responder:
# WSGI
def on_foo(self, req, resp):
pass
# ASGI
async def on_foo(self, req, resp):
pass
从源码看(falcon/constants.py),COMBINED_METHODS 由四部分组成:
COMBINED_METHODS = (
HTTP_METHODS # RFC 7231/5789: CONNECT/DELETE/GET/HEAD/OPTIONS/PATCH/POST/PUT/TRACE
+ WEBDAV_METHODS # RFC 2518/4918: COPY/LOCK/MKCOL/MOVE/PROPFIND/PROPPATCH/REPORT/UNLOCK/VERSION-CONTROL 等
+ HTTP_WG_DRAFT_METHODS # 例如 QUERY
+ FALCON_CUSTOM_HTTP_METHODS # 来自环境变量
+ _META_METHODS # WEBSOCKET
)
FALCON_CUSTOM_HTTP_METHODS 在导入时读取环境变量,对每项做 strip().upper() 处理,因此环境变量中的空格与小写会被自动规范化。相应地,falcon.routing.util.map_http_methods 会遍历 COMBINED_METHODS 生成 on_<method> 的 responder 映射。
处理含特殊字符的方法名
如果 HTTP 方法包含连字符等非字母数字字符,对应的 responder 名称将不是合法 Python 标识符。例如 VERSION-CONTROL 会映射到 on_version-control。此时需要把 responder 定义为常规方法,再用 setattr 赋给期望的 responder 名:
class VersionControlResource:
def handle_version_control(self, req, resp):
pass
setattr(
VersionControlResource,
'on_version-control',
VersionControlResource.handle_version_control,
)
app.add_route('/repos', VersionControlResource())
深入理解:一次请求的完整路由链路
综合以上内容,一个请求到达 Falcon 应用后的路由处理顺序可以归纳为(可对照 falcon/app.py 与 falcon/routing/compiled.py 的源码):
- 请求进入
App.__call__,先经过中间件的process_request阶段; - 调用路由器的
find()(CompiledRouter.find()内部调用编译后的_find函数)——把路径按/拆分,沿决策树逐段比较字面量/正则/转换器,收集路径参数到paramsdict; - 匹配成功:返回
(resource, method_map, params, uri_template),然后按请求方法查method_map找到对应 responder(未实现的方法会命中默认的 405/OPTIONS responder),执行process_resource中间件后调用 responder; - 匹配失败:命中默认 404 responder(
path_not_found,见 falcon/responders.py),抛出HTTPRouteNotFound; - 若动态路由与 sinks 均未命中,最后才尝试静态路由(LIFO 顺序);仍未命中则同样返回 404。
这套设计使得 Falcon 在保证路由声明式可读性的同时,通过"把路由树编译成函数"实现了极低的路由开销——这也是其性能承诺的核心来源之一。
参考与延伸阅读
- 本文主文档:docs/api/routing.rst
- 默认路由引擎实现:falcon/routing/compiled.py
- 字段转换器实现:falcon/routing/converters.py
- 路由工具函数:falcon/routing/util.py
- 静态文件路由:falcon/routing/static.py
- 默认 responder 实现:falcon/responders.py
- HTTP 方法常量:falcon/constants.py
- 应用入口与
add_route/add_static_route:falcon/app.py - 相关测试:tests/test_compiled_router.py、tests/test_uri_converters.py、tests/test_static.py
- 配套教程:docs/user/tutorial.rst、docs/user/tutorial-asgi.rst