【FastAPI筑基-Day8】参数高级校验精讲Path/Query/Body长度/范围/正则/自定义报错工业级接口规范专栏FastAPI 零基础后端实战系列标签FastAPI、参数校验、Query、Path、Body、Pydantic、后端接口规范前置学习Day7 三大传参方式、Day5 Pydantic 基础校验一、前言通过 Day7 的学习我们已经能写 GET、POST 接口接收路径参数、查询参数、Body 请求体参数。但是普通参数只能校验类型内容却毫无限制年龄可以传-999手机号可以传12345用户名可以传 100 个字符分页参数可以传 0、负数每个接口手动写 if 判断代码又臭又长还容易漏。本文说了什么FastAPI 内置的四大校验工具——Path、Query、Body、Field实现工业级参数精细化校验。实现了什么一个包含路径参数校验、查询参数分页校验、请求体模型校验、正则校验、自定义错误提示的完整可运行项目。目的是什么学完再也不用手写 if 校验参数FastAPI 自动拦截非法参数、自动返回标准错误信息接口质量直接达到企业生产级规范。二、核心四大校验工具FastAPI 的参数校验全部基于 Pydantic共四个工具各司其职fromfastapiimportPath,Query,BodyfrompydanticimportField工具作用适用场景Path路径参数校验ID、编号必须为正数Query查询参数校验分页、搜索、过滤条件Body单个 Body 参数校验简单请求体字段FieldPydantic 模型字段校验最常用配合 BaseModel 使用学完这个你就能体会到什么叫声明式校验——你只管声明规则验证交给框架。三、路径参数 Path 高级校验路径参数最常见的场景是用户 ID、文章 ID、订单号要求必须是正整数且在一定范围内。常用参数参数含义ge大于等于greater or equalle小于等于less or equalgt大于greater thanlt小于less thandescription参数说明文档代码示例fromfastapiimportFastAPI,Path appFastAPI(titleDay8 Path 参数校验)app.get(/user/{user_id})defget_user(user_id:intPath(...,ge1,le99999,description用户ID正整数),):return{user_id:user_id,msg:查询成功}...表示必填参数ge1限制最小值为 1le99999限制最大值为 99999。运行验证 合法用户ID GET /user/100 → {user_id:100,msg:查询成功} 非法用户ID (0) GET /user/0 → {code:400,msg:参数错误Input should be greater than or equal to 1} 非法用户ID (-10) GET /user/-10 → {code:400,msg:参数错误Input should be greater than or equal to 1}传 0 或负数直接被拦截不需要写一行if user_id 0。四、查询参数 Query 高级校验分页/搜索专用项目中分页、搜索、关键字筛选全部用 Query 校验。支持字符串长度、数字范围、默认值、必填。代码示例fromfastapiimportQueryapp.get(/user/list)deflist_user(page:intQuery(1,ge1,description页码),size:intQuery(10,ge1,le100,description每页数量),keyword:strQuery(,max_length20,description搜索关键字),):return{page:page,size:size,keyword:keyword}三个参数的校验规则一目了然page默认第 1 页最小 1无上限size默认每页 10 条限制 1~100防止一次性请求过多数据keyword默认为空最长 20 字符运行验证 合法查询 GET /user/list?page2size20keywordadmin → {page:2,size:20,keyword:admin} 非法 size200 GET /user/list?size200 → {code:400,msg:参数错误Input should be less than or equal to 100} 超长关键字 GET /user/list?keywordaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa → {code:400,msg:参数错误String should have at most 20 characters}分页参数校验是后端防恶意请求的第一道防线size限 100 条再大的数据量用游标分页。五、请求体 Body Field 精细化校验POST 核心业务中 90% 的参数校验都在这里用户名、密码、年龄、手机号……全部通过 Pydantic 模型统一管理。代码示例frompydanticimportBaseModel,FieldclassRegisterModel(BaseModel):username:strField(...,min_length2,max_length10)password:strField(...,min_length6,max_length16)age:intField(18,ge0,le120)phone:strField(...,patternr^1[3-9]\d{9}$)app.post(/register)defregister(data:RegisterModel):return{code:200,msg:注册成功,data:data.model_dump()}运行验证 合法注册 POST /register {username:admin,password:123456,age:18,phone:13800138000} → {code:200,msg:注册成功,data:{username:admin,password:123456,age:18,phone:13800138000}} 非法手机号 POST /register {username:admin,password:123456,phone:12345} → {code:400,msg:参数错误String should match pattern ^1[3-9]\\d{9}$} 用户名太短 POST /register {username:a,password:123456,phone:13800138000} → {code:400,msg:参数错误String should have at least 2 characters}手机号正则^1[3-9]\d{9}$匹配 11 位以 1 开头、第二位 3~9 的中国手机号非法格式直接拒绝。六、正则表达式校验手机号/邮箱/账号正则校验是 Field 的杀手级功能手机号、邮箱、账号格式全靠它。frompydanticimportBaseModel,FieldclassUserModel(BaseModel):phone:strField(...,patternr^1[3-9]\d{9}$,description手机号)email:strField(...,patternr^\w\w\.\w$,description邮箱)在 Pydantic v2 中参数名是patternv1 中是regex注意区分。七、必填参数与可选参数写法必填使用...Ellipsisusername:strField(...,min_length2)可选可空使用None作为默认值city:str|NoneField(None,max_length20)注意str | None语法要求 Python 3.10老版本用Optional[str]。八、自定义错误提示企业级必备默认的校验错误信息是英文的前端同学看不懂。我们可以用异常处理器统一替换为中文提示fromfastapiimportFastAPIfromfastapi.exceptionsimportRequestValidationErrorfromfastapi.responsesimportJSONResponse appFastAPI()app.exception_handler(RequestValidationError)asyncdefvalidation_exception_handler(request,exc):msgexc.errors()[0][msg]returnJSONResponse(status_code400,content{code:400,msg:参数错误msg})加上这段代码后所有参数校验错误统一返回{code: 400, msg: 参数错误...}前端拿到的永远是标准格式直接展示给用户即可。九、Day8 完整可运行代码FastAPI筑基 Day8 参数高级校验 —— 配套可运行代码fromfastapiimportFastAPI,Path,Queryfromfastapi.exceptionsimportRequestValidationErrorfromfastapi.responsesimportJSONResponsefrompydanticimportBaseModel,Field appFastAPI(titleDay8 参数高级校验)app.exception_handler(RequestValidationError)asyncdefvalidation_exception_handler(request,exc):msgexc.errors()[0][msg]returnJSONResponse(status_code400,content{code:400,msg:参数错误msg})app.get(/user/list)defdemo2_query_param(page:intQuery(1,ge1,description页码),size:intQuery(10,ge1,le100,description每页数量),keyword:strQuery(,max_length20,description搜索关键字),):return{page:page,size:size,keyword:keyword}app.get(/user/{user_id})defdemo1_path_param(user_id:intPath(...,ge1,le99999,description用户ID),):return{user_id:user_id,msg:查询成功}classRegisterModel(BaseModel):username:strField(...,min_length2,max_length10)password:strField(...,min_length6,max_length16)age:intField(18,ge0,le120)phone:strField(...,patternr^1[3-9]\d{9}$)app.post(/register)defdemo3_body_field(data:RegisterModel):return{code:200,msg:注册成功,data:data.model_dump()}if__name____main__:importuvicorn uvicorn.run(app,host127.0.0.1,port8000)注意/user/list和/user/{user_id}两个路由必须把list放在{user_id}前面否则/user/list会被{user_id}匹配为 id“list” 导致校验失败。这是 FastAPI 路由按定义顺序匹配的特性。运行方式pipinstallfastapi uvicorn pydantic python3 day8.py打开http://127.0.0.1:8000/docs自动生成 Swagger 接口文档在线测试校验效果。实际运行结果 1. 合法用户ID GET /user/100 → {user_id:100,msg:查询成功} 2. 非法用户ID (0) GET /user/0 → {code:400,msg:参数错误Input should be greater than or equal to 1} 3. 非法用户ID (-10) GET /user/-10 → {code:400,msg:参数错误Input should be greater than or equal to 1} 4. 合法查询参数 GET /user/list?page2size20keywordadmin → {page:2,size:20,keyword:admin} 5. 非法 size200 GET /user/list?size200 → {code:400,msg:参数错误Input should be less than or equal to 100} 6. 超长关键字 GET /user/list?keywordaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa → {code:400,msg:参数错误String should have at most 20 characters} 7. 合法注册 POST /register {username:admin,password:123456,age:18,phone:13800138000} → {code:200,msg:注册成功,data:{username:admin,password:123456,age:18,phone:13800138000}} 8. 非法手机号 POST /register {username:admin,password:123456,phone:12345} → {code:400,msg:参数错误String should match pattern ^1[3-9]\\d{9}$} 9. 用户名太短 POST /register {username:a,password:123456,phone:13800138000} → {code:400,msg:参数错误String should have at least 2 characters}十、Day8 核心知识点总结知识点说明Path路径参数校验ge/le限制数字范围必填参数用...Query查询参数校验分页、搜索参数max_length限制字符串长度Field模型字段校验min_length/max_length/pattern最常用正则pattern手机号、邮箱、账号格式校验必填 vs 可选...必填None可选自定义错误提示重写RequestValidationError异常处理器至此你的接口已经达到企业生产级规范——参数校验、自动文档、中文错误提示全套齐活。十一、下期预告Day9FastAPI 静态文件 跨域 CORS 配置解决前端跨域报错、托管图片/js/css 文件彻底打通前后端联调无障碍 FastAPI筑基_Day8_参数高级校验精讲
【FastAPI筑基-Day8】参数高级校验精讲Path/Query/Body长度/范围/正则/自定义报错工业级接口规范专栏FastAPI 零基础后端实战系列标签FastAPI、参数校验、Query、Path、Body、Pydantic、后端接口规范前置学习Day7 三大传参方式、Day5 Pydantic 基础校验一、前言通过 Day7 的学习我们已经能写 GET、POST 接口接收路径参数、查询参数、Body 请求体参数。但是普通参数只能校验类型内容却毫无限制年龄可以传-999手机号可以传12345用户名可以传 100 个字符分页参数可以传 0、负数每个接口手动写 if 判断代码又臭又长还容易漏。本文说了什么FastAPI 内置的四大校验工具——Path、Query、Body、Field实现工业级参数精细化校验。实现了什么一个包含路径参数校验、查询参数分页校验、请求体模型校验、正则校验、自定义错误提示的完整可运行项目。目的是什么学完再也不用手写 if 校验参数FastAPI 自动拦截非法参数、自动返回标准错误信息接口质量直接达到企业生产级规范。二、核心四大校验工具FastAPI 的参数校验全部基于 Pydantic共四个工具各司其职fromfastapiimportPath,Query,BodyfrompydanticimportField工具作用适用场景Path路径参数校验ID、编号必须为正数Query查询参数校验分页、搜索、过滤条件Body单个 Body 参数校验简单请求体字段FieldPydantic 模型字段校验最常用配合 BaseModel 使用学完这个你就能体会到什么叫声明式校验——你只管声明规则验证交给框架。三、路径参数 Path 高级校验路径参数最常见的场景是用户 ID、文章 ID、订单号要求必须是正整数且在一定范围内。常用参数参数含义ge大于等于greater or equalle小于等于less or equalgt大于greater thanlt小于less thandescription参数说明文档代码示例fromfastapiimportFastAPI,Path appFastAPI(titleDay8 Path 参数校验)app.get(/user/{user_id})defget_user(user_id:intPath(...,ge1,le99999,description用户ID正整数),):return{user_id:user_id,msg:查询成功}...表示必填参数ge1限制最小值为 1le99999限制最大值为 99999。运行验证 合法用户ID GET /user/100 → {user_id:100,msg:查询成功} 非法用户ID (0) GET /user/0 → {code:400,msg:参数错误Input should be greater than or equal to 1} 非法用户ID (-10) GET /user/-10 → {code:400,msg:参数错误Input should be greater than or equal to 1}传 0 或负数直接被拦截不需要写一行if user_id 0。四、查询参数 Query 高级校验分页/搜索专用项目中分页、搜索、关键字筛选全部用 Query 校验。支持字符串长度、数字范围、默认值、必填。代码示例fromfastapiimportQueryapp.get(/user/list)deflist_user(page:intQuery(1,ge1,description页码),size:intQuery(10,ge1,le100,description每页数量),keyword:strQuery(,max_length20,description搜索关键字),):return{page:page,size:size,keyword:keyword}三个参数的校验规则一目了然page默认第 1 页最小 1无上限size默认每页 10 条限制 1~100防止一次性请求过多数据keyword默认为空最长 20 字符运行验证 合法查询 GET /user/list?page2size20keywordadmin → {page:2,size:20,keyword:admin} 非法 size200 GET /user/list?size200 → {code:400,msg:参数错误Input should be less than or equal to 100} 超长关键字 GET /user/list?keywordaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa → {code:400,msg:参数错误String should have at most 20 characters}分页参数校验是后端防恶意请求的第一道防线size限 100 条再大的数据量用游标分页。五、请求体 Body Field 精细化校验POST 核心业务中 90% 的参数校验都在这里用户名、密码、年龄、手机号……全部通过 Pydantic 模型统一管理。代码示例frompydanticimportBaseModel,FieldclassRegisterModel(BaseModel):username:strField(...,min_length2,max_length10)password:strField(...,min_length6,max_length16)age:intField(18,ge0,le120)phone:strField(...,patternr^1[3-9]\d{9}$)app.post(/register)defregister(data:RegisterModel):return{code:200,msg:注册成功,data:data.model_dump()}运行验证 合法注册 POST /register {username:admin,password:123456,age:18,phone:13800138000} → {code:200,msg:注册成功,data:{username:admin,password:123456,age:18,phone:13800138000}} 非法手机号 POST /register {username:admin,password:123456,phone:12345} → {code:400,msg:参数错误String should match pattern ^1[3-9]\\d{9}$} 用户名太短 POST /register {username:a,password:123456,phone:13800138000} → {code:400,msg:参数错误String should have at least 2 characters}手机号正则^1[3-9]\d{9}$匹配 11 位以 1 开头、第二位 3~9 的中国手机号非法格式直接拒绝。六、正则表达式校验手机号/邮箱/账号正则校验是 Field 的杀手级功能手机号、邮箱、账号格式全靠它。frompydanticimportBaseModel,FieldclassUserModel(BaseModel):phone:strField(...,patternr^1[3-9]\d{9}$,description手机号)email:strField(...,patternr^\w\w\.\w$,description邮箱)在 Pydantic v2 中参数名是patternv1 中是regex注意区分。七、必填参数与可选参数写法必填使用...Ellipsisusername:strField(...,min_length2)可选可空使用None作为默认值city:str|NoneField(None,max_length20)注意str | None语法要求 Python 3.10老版本用Optional[str]。八、自定义错误提示企业级必备默认的校验错误信息是英文的前端同学看不懂。我们可以用异常处理器统一替换为中文提示fromfastapiimportFastAPIfromfastapi.exceptionsimportRequestValidationErrorfromfastapi.responsesimportJSONResponse appFastAPI()app.exception_handler(RequestValidationError)asyncdefvalidation_exception_handler(request,exc):msgexc.errors()[0][msg]returnJSONResponse(status_code400,content{code:400,msg:参数错误msg})加上这段代码后所有参数校验错误统一返回{code: 400, msg: 参数错误...}前端拿到的永远是标准格式直接展示给用户即可。九、Day8 完整可运行代码FastAPI筑基 Day8 参数高级校验 —— 配套可运行代码fromfastapiimportFastAPI,Path,Queryfromfastapi.exceptionsimportRequestValidationErrorfromfastapi.responsesimportJSONResponsefrompydanticimportBaseModel,Field appFastAPI(titleDay8 参数高级校验)app.exception_handler(RequestValidationError)asyncdefvalidation_exception_handler(request,exc):msgexc.errors()[0][msg]returnJSONResponse(status_code400,content{code:400,msg:参数错误msg})app.get(/user/list)defdemo2_query_param(page:intQuery(1,ge1,description页码),size:intQuery(10,ge1,le100,description每页数量),keyword:strQuery(,max_length20,description搜索关键字),):return{page:page,size:size,keyword:keyword}app.get(/user/{user_id})defdemo1_path_param(user_id:intPath(...,ge1,le99999,description用户ID),):return{user_id:user_id,msg:查询成功}classRegisterModel(BaseModel):username:strField(...,min_length2,max_length10)password:strField(...,min_length6,max_length16)age:intField(18,ge0,le120)phone:strField(...,patternr^1[3-9]\d{9}$)app.post(/register)defdemo3_body_field(data:RegisterModel):return{code:200,msg:注册成功,data:data.model_dump()}if__name____main__:importuvicorn uvicorn.run(app,host127.0.0.1,port8000)注意/user/list和/user/{user_id}两个路由必须把list放在{user_id}前面否则/user/list会被{user_id}匹配为 id“list” 导致校验失败。这是 FastAPI 路由按定义顺序匹配的特性。运行方式pipinstallfastapi uvicorn pydantic python3 day8.py打开http://127.0.0.1:8000/docs自动生成 Swagger 接口文档在线测试校验效果。实际运行结果 1. 合法用户ID GET /user/100 → {user_id:100,msg:查询成功} 2. 非法用户ID (0) GET /user/0 → {code:400,msg:参数错误Input should be greater than or equal to 1} 3. 非法用户ID (-10) GET /user/-10 → {code:400,msg:参数错误Input should be greater than or equal to 1} 4. 合法查询参数 GET /user/list?page2size20keywordadmin → {page:2,size:20,keyword:admin} 5. 非法 size200 GET /user/list?size200 → {code:400,msg:参数错误Input should be less than or equal to 100} 6. 超长关键字 GET /user/list?keywordaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa → {code:400,msg:参数错误String should have at most 20 characters} 7. 合法注册 POST /register {username:admin,password:123456,age:18,phone:13800138000} → {code:200,msg:注册成功,data:{username:admin,password:123456,age:18,phone:13800138000}} 8. 非法手机号 POST /register {username:admin,password:123456,phone:12345} → {code:400,msg:参数错误String should match pattern ^1[3-9]\\d{9}$} 9. 用户名太短 POST /register {username:a,password:123456,phone:13800138000} → {code:400,msg:参数错误String should have at least 2 characters}十、Day8 核心知识点总结知识点说明Path路径参数校验ge/le限制数字范围必填参数用...Query查询参数校验分页、搜索参数max_length限制字符串长度Field模型字段校验min_length/max_length/pattern最常用正则pattern手机号、邮箱、账号格式校验必填 vs 可选...必填None可选自定义错误提示重写RequestValidationError异常处理器至此你的接口已经达到企业生产级规范——参数校验、自动文档、中文错误提示全套齐活。十一、下期预告Day9FastAPI 静态文件 跨域 CORS 配置解决前端跨域报错、托管图片/js/css 文件彻底打通前后端联调无障碍