FastAPI应用中条件必填参数的最优处理方案问询

好问题！其实FastAPI底层依赖的Pydantic提供了几种比手写root_validator更简洁的方式来处理这种互斥必填的校验场景，我给你整理两种实用方案：

方案1：用Union拆分模型（最推荐，可读性+文档友好） #

你可以把两种合法的地址格式拆成两个独立的子模型，然后用Union让请求体接受任意一种格式。这种方式不仅自动帮你完成必填校验，还能让API文档清晰展示两种提交选项，用户一眼就能明白规则。

示例代码：

from pydantic import BaseModel, Field
from typing import Union

# 格式1：仅提交完整地址字符串
class AddressWithString(BaseModel):
    address_string: str
    # 排除冗余字段，避免用户混淆提交
    address_street: None = Field(None, exclude=True)
    addres_number: None = Field(None, exclude=True)

# 格式2：分开提交街道和门牌号
class AddressWithParts(BaseModel):
    address_string: None = Field(None, exclude=True)
    address_street: str
    addres_number: str

# 最终的地址Schema是两种格式的二选一
Address = Union[AddressWithString, AddressWithParts]

在FastAPI路由中直接使用这个Address类型：

from fastapi import FastAPI

app = FastAPI()

@app.post("/submit-address")
async def process_address(address: Address):
    # 统一处理成业务需要的格式
    if isinstance(address, AddressWithString):
        return {"processed_address": address.address_string}
    else:
        return {"processed_address": f"{address.addres_number} {address.address_street}"}

这种方案的优势：

• 无需手动编写验证逻辑，Pydantic自动校验合法性
• API文档会明确展示两种请求体结构，用户体验更佳
• 代码逻辑清晰，后续维护更方便

方案2：用Pydantic v2的model_validator简化验证逻辑 #

如果不想拆分模型，在Pydantic v2中可以用更简洁的model_validator替代旧版的root_validator，写法更清爽：

from pydantic import BaseModel, Field, model_validator
from typing import Optional

class Address(BaseModel):
    address_string: Optional[str] = Field(None)
    address_street: Optional[str] = Field(None)
    addres_number: Optional[str] = Field(None)

    @model_validator(mode="after")
    def validate_address_rules(self):
        # 核心校验逻辑：要么有完整字符串，要么同时有街道和门牌号
        has_full_address = self.address_string is not None
        has_address_parts = self.address_street is not None and self.addres_number is not None

        if not has_full_address and not has_address_parts:
            raise ValueError("必须提供address_string，或者同时提供address_street和addres_number")
        if has_full_address and has_address_parts:
            raise ValueError("不能同时提供address_string和address_street/addres_number")
        
        return self

这种方式保留了单模型的结构，但验证逻辑比旧版root_validator更简洁直观。

补充说明 #

FastAPI/Pydantic目前没有专门的内置装饰器来直接定义这种“互斥必填”规则，因为这类校验属于个性化业务逻辑。不过上面两种方案都比你当前的写法更简洁高效，尤其是第一种Union拆分的方式，更符合API设计的最佳实践。

内容的提问来源于stack exchange，提问作者Nicolas Martinez