FastAPI-Pydantic字符串Enum值含空格致服务启动失败求助

这个错误的核心是FastAPI（依赖Pydantic的类型处理逻辑）在解析带空格的Enum字符串值时，误将其判定为无效的Python前向引用表达式，具体细节：

• 纯Python环境中，Enum仅负责成员与值的映射存储，不会对值做额外语法校验，带空格的字符串值完全合法。
• FastAPI启动时会基于Pydantic模型生成OpenAPI规范，同时会对类型做深度解析（包括将枚举值转换为可被解析的Python表达式格式）。带空格的字符串（比如'Migration Config'）不符合Python表达式语法——Python会将其拆分为两个独立标识符，解析器判定这不是合法表达式，从而抛出"Forward reference must be an expression"错误。

以下两种方式可解决问题，既能保留带空格的对外展示值，又能避免启动报错：

方法1：Enum成员值用下划线，通过Pydantic别名映射带空格格式 #

保持Enum成员的字符串值为下划线格式（规避语法解析问题），再通过Pydantic的序列化别名，在返回响应时自动转换为带空格的字符串：

from enum import Enum
from pydantic import BaseModel, Field
from fastapi import FastAPI

app = FastAPI()

class ProjectType(str, Enum):
    MIGRATION_CONFIG = "migration_config"

class ProjectModel(BaseModel):
    # 序列化时将字段值转换为带空格的形式
    type: ProjectType = Field(..., serialization_alias="Migration Config")

@app.get("/project")
def get_project() -> ProjectModel:
    return ProjectModel(type=ProjectType.MIGRATION_CONFIG)

方法2：显式指定Enum的序列化行为 #

如果必须让Enum的原始值为带空格字符串，可通过Pydantic的model_config配置，强制直接使用枚举的字符串值序列化，绕过表达式解析逻辑：

from enum import Enum
from pydantic import BaseModel, ConfigDict
from fastapi import FastAPI

app = FastAPI()

class ProjectType(str, Enum):
    MIGRATION_CONFIG = "Migration Config"

class ProjectModel(BaseModel):
    model_config = ConfigDict(use_enum_values=True)
    type: ProjectType

@app.get("/project")
def get_project() -> ProjectModel:
    return ProjectModel(type=ProjectType.MIGRATION_CONFIG)

内容的提问来源于stack exchange，提问作者H.Sheng