快速入门与核心概念

# Python 3.10+ 标准语法
def get_user_info(
    name: str,
    age: int,
    height: float,
    is_active: bool,
    tags: list[str],          # 列表，元素均为字符串
    metadata: dict[str, any]  # 字典，键为字符串
) -> dict[str, any]:
    return {"name": name, "age": age, "is_active": is_active}

from typing import Optional, Union

# Python 3.10 之前
legacy_var: Optional[str] = None       # 等价于 Union[str, None]

# Python 3.10+ 现代写法（强烈推荐）
modern_var: str | None = None
mixed_id: int | str = "user_1001"

from typing import Annotated
from fastapi import FastAPI, Query, Path, Depends

app = FastAPI()

# 语法格式：Annotated[类型, 元数据/校验规则/依赖]
UserId = Annotated[int, Path(title="用户ID", ge=1, le=1000000)]
PageSize = Annotated[int, Query(title="每页大小", ge=1, le=100, default=20)]

@app.get("/users/{user_id}")
async def get_user(
    user_id: UserId,
    page_size: PageSize = 20
):
    return {"user_id": user_id, "page_size": page_size}

# 1. 创建并激活虚拟环境 (Python 3.10+)
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# .\venv\Scripts\activate  # Windows

# 2. 安装 FastAPI 以及标准工具链
pip install "fastapi[all]"

# 或者使用现代 fastapi-cli (FastAPI 0.110+ 官方推荐)
pip install "fastapi[standard]"

# main.py
from fastapi import FastAPI

# 1. 创建 FastAPI 应用实例
app = FastAPI(
    title="AI Agent 微服务平台",
    description="基于 FastAPI 构建的高性能大语言模型与 Agent 接口服务",
    version="1.0.0",
    docs_url="/docs",      # Swagger UI 文档路径，设为 None 可关闭
    redoc_url="/redoc"     # ReDoc 文档路径
)

# 2. 定义根路径操作装饰器与函数
@app.get("/", summary="系统健康检查", tags=["系统状态"])
async def root():
    return {
        "status": "healthy",
        "message": "Welcome to FastAPI AI Service!",
        "framework": "FastAPI 0.110+"
    }

# 3. 带参数的操作
@app.get("/items/{item_id}", summary="查询商品详情", tags=["商品模块"])
async def read_item(item_id: int, q: str | None = None):
    return {"item_id": item_id, "query_param": q}

from fastapi import FastAPI

tags_metadata = [
    {
        "name": "用户模块",
        "description": "用户账户注册、登录认证、个人资料管理相关接口。",
    },
    {
        "name": "智能体",
        "description": "基于 LLM 与 LangGraph 的 Agent 任务调度与对话流接口。",
        "externalDocs": {
            "description": "Agent 架构白皮书",
            "url": "https://example.com/docs/agent-whitepaper",
        },
    },
]

app = FastAPI(
    title="企业级 AI 开放平台",
    description="""
    ## 欢迎使用企业级 AI 开放平台 API
    本接口文档基于 **OpenAPI 3.1** 标准规范构建，支持：
    * 🚀 **高并发异步处理**
    * 🔐 **OAuth2 + JWT 安全认证**
    * 🤖 **大模型实时打字机流式推送 (SSE)**
    """,
    version="2.0.0",
    terms_of_service="https://example.com/terms/",
    contact={
        "name": "AI 研发中心架构组",
        "url": "https://example.com/support",
        "email": "support@example.com",
    },
    license_info={
        "name": "Apache 2.0",
        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
    },
    openapi_tags=tags_metadata,
    openapi_url="/api/v1/openapi.json",  # 定制 OpenAPI JSON 路径
    docs_url="/docs",                    # Swagger UI 文档路径
    redoc_url="/redoc"                   # ReDoc 文档路径
)

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()

# 将本地 ./static 目录挂载到 /static 路径下
# 例如 ./static/images/logo.png 可通过 http://127.0.0.1:8000/static/images/logo.png 访问
app.mount("/static", StaticFiles(directory="static"), name="static")

# 启动方式 1: 官方 fastapi 命令行 (FastAPI 0.110+)
fastapi dev main.py

# 启动方式 2: Uvicorn 经典命令行
uvicorn main:app --reload --host 0.0.0.0 --port 8000

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)