FastAPI组合框架能力
FastAPI 是构建 Web API 的 Python 框架:Uvicorn 作为 Web 服务器接收请求,Starlette 负责 Web 路由,FastAPI 在其上结合 pydantic 做数据验证并生成 API 文档。它在本书中用于实现订单接口;这些是框架层分工,不等于订单业务逻辑。
主题对照
比较 Flask、FastAPI、Pydantic 等框架中的路由、参数绑定、输入输出模型验证、错误提示和模块化组织。
FastAPI 是构建 Web API 的 Python 框架:Uvicorn 作为 Web 服务器接收请求,Starlette 负责 Web 路由,FastAPI 在其上结合 pydantic 做数据验证并生成 API 文档。它在本书中用于实现订单接口;这些是框架层分工,不等于订单业务逻辑。
FastAPI 的 HTTP 方法装饰器把路径与处理函数绑定,例如 @app.get('/orders') 注册读取端点。处理函数返回的数据由框架转换成 HTTP 响应;需要不同结果码时可在装饰器中设置状态码。路由声明同时承载了“请求到哪里”和“由谁处理”。
在 FastAPI 中,路径模板的 {order_id} 与处理函数的同名参数相连;声明参数为 UUID 后,框架会拒绝不符合该格式的输入。路径变量不只是字符串占位符,类型声明还把一部分输入校验移到了接口边界。
pydantic 模型可把 API Schema 落到 Python 类型:模型继承 BaseModel,字段用类型提示,枚举约束可选值,受限整数与列表约束下界。接口实现应逐项核对规范中的必填、默认值和范围;写了模型类并不代表契约自动完整覆盖。
在 FastAPI 处理函数中,把请求体声明为参数并标注相应的 pydantic 模型,框架就能在进入业务处理前校验载荷。比如创建订单需要 CreateOrderSchema,缺少必填字段应被拒绝。模型定义和路由参数绑定缺一不可。
请求体校验错误应指出字段所在路径,而不只说“参数错误”。订单示例中的 body/order/0/product 可定位到 order 数组第一项的 product。原书把这种定位类比为 JSON Pointer;实际响应中的 loc 可能是分段数组,不能把展示形式直接等同于标准指针字符串。
在书中订单模型的默认行为下,客户端把 quantity 拼错时,服务端会把正确字段视为缺失并采用默认值 1,调用方却以为传入了数量 5。忽略未知字段会掩盖契约偏差;是否严格拒绝需按实际框架版本和模型配置核验。
字段可选表示请求中可以省略,不表示显式传入 null 也有效。订单数量省略时可用默认值 1,但若契约禁止 null,模型就需单独校验。把“缺失”和“空值”混为一谈会让客户端与服务端对同一载荷产生不同理解。
请求验过还不够,服务端返回的载荷也可能缺字段或格式错误。在书中 FastAPI 示例中,路由的 response_model 用 pydantic 模型验证出站数据;额外字段会被移除,缺少必填字段会报错。客户端依赖的是响应契约,不是服务端对象原貌。
书中 FastAPI 示例把查询参数写进端点函数签名,并用类型标注交给框架解析和校验。cancelled: Optional[bool] = None 与 limit: Optional[int] = None 既表达字段类型,也允许调用者不传;处理函数随后可依是否传值决定过滤方式。
可选布尔查询参数需要区分“没有传”与“传了 false”。书中先判断 cancelled is not None,再按 true 或 false 分别筛选已取消或未取消订单;若只写 if cancelled,false 会被误当成未传,过滤意图就丢失。
宽容读取允许请求带有未声明字段,接口演进时可能更容易兼容旧客户端;代价是拼写错误也会被忽略。订单数量写成 quantit 后落回默认值 1 就是例子。是否宽容应按契约变动频率与静默误处理的后果取舍。
若契约要求尽早暴露客户端拼写错误,可把请求模型设为拒绝未声明字段。书中 pydantic 示例在模型 Config 中设 extra = Extra.forbid,让 quantit 这类字段触发 422,而非被默默丢弃。具体配置写法应以所用 pydantic 版本核对。
框架从代码自动生成的 API 规范只反映当前实现,代码若写错,文档也会跟着错;生成器还可能缺少某些 OpenAPI 表达能力。应把设计规范与生成结果对照,并明确对外展示哪一份,避免消费者把实现偏差误认为约定行为。
flask-smorest 把 Flask 的 Web 路由与 marshmallow 的数据校验、序列化组合起来:端点按 Flask 模式实现,载荷模型由 marshmallow 字段声明。与 FastAPI 使用 pydantic 和 Python 类型标注的路径相比,应用的端点、模型与业务职责仍可分离。选择框架时应辨明校验规则由哪一层提供。
同一路径暴露多个 HTTP 方法时,类视图可用一个类代表该路径,以 get、post 等方法分别处理操作,把共享的路径行为集中起来。只暴露一个方法的路径可用函数视图,结构更轻。[[路径与方法共同定端点]]说明路径和方法仍需共同识别最终端点。
Flask 蓝图将一组 URL 的路由与配置聚合,再注册到应用。flask-smorest 的蓝图在此基础上连接请求/响应模型与 API 文档能力。按业务边界组织蓝图,可让路由定义集中,同时保留应用入口统一装配各组端点。
marshmallow 的 Schema 子类用字段对象声明载荷结构,字段可设置必填、取值范围、枚举约束,并可嵌套或继承已有模式。接口层把模式接到请求和响应处理时,校验规则才落实到端点;模式声明本身不等于业务状态校验。
把 API 标题、版本、规范版本与文档路径等参数集中在配置对象中,再由应用加载,可使入口组装与参数定义分开。对同一服务的不同运行环境,这种边界便于核查配置差异;具体键名和取值仍应按实际框架版本验证。
查询参数也可由载荷模式声明类型与可选性,再把模式绑定到端点的 query 位置,框架便能从 URL 读取、转换并交给处理函数。过滤时仍需区分未传与假值,例如布尔 false 不能用真假判断当成缺失。参见 [[None区别未传与假值]]。
请求校验与响应序列化可能是不对称的:书中 flask-smorest 的 arguments() 校验并反序列化请求,response() 只序列化响应。若服务端数据也可能畸形,应在输出前显式调用模式校验并处理错误;这增加计算成本,需按数据风险与性能预算决定范围。参见 [[出站响应也要按模型验证]]。
点击箭头逐层展开,点击卡片标题查看详情。路径上下文仅用于连接层级,不计入主题卡片数。
来源书籍
系统架构类
书籍类型:工程实践
清单覆盖 6/7
238 张卡片
与 1 张主题卡片存在结构化链接;来自相同书籍;属于相同分类
来自相同书籍;属于相同分类
来自相同书籍;属于相同分类
来自相同书籍;属于相同分类
来自相同书籍;属于相同分类
来自相同书籍;属于相同分类