Python写接口的步骤及完整代码示例

在现代 Web 应用与微服务开发中，使用 Python 编写后端 API 接口是一项基础且核心的技能。构建一个符合工业标准的 RESTful 接口，关键路径在于：确定底层框架、定义请求与响应的数据契约、编写业务处理逻辑、处理异常状态码，并最终完成服务的运行与测试验证。本文将以类型安全和高性能的现代主流框架 FastAPI 为核心实现工具，辅以完整的端到端代码与流程图解，帮助读者建立清晰、可实操的 Python 接口开发技能。

一、前期准备与依赖安装

在开始编写代码前，建议为项目创建独立的虚拟环境，以避免第三方包与系统环境产生版本冲突。编写接口需要两个核心组件：Web 框架本身（FastAPI）以及用于驱动异步事件循环的 ASGI 服务器（Uvicorn）。

在终端中执行以下命令完成环境初始化与库安装：

# 创建并激活虚拟环境
python3 -m venv .venv
source .venv/bin/activate  # Windows 用户请执行 .venv\Scripts\activate

# 安装核心依赖库
pip install fastapi uvicorn

安装完成后，FastAPI 会自动引入 Pydantic 库用于数据结构验证，无需单独手动配置。

二、接口核心设计与数据流向

一个标准的 Web 接口本质上是网络请求的“路由分发器”和“数据转换管道”。当客户端（如浏览器、移动端或前端前端框架）发起 HTTP 请求时，Python 服务端程序会经历协议解析、路径匹配、模型验证、视图计算到数据序列化的全过程。

三、完整可运行代码示例

在项目目录下新建名为 main.py 的文件。以下示例实现了一个完整的商品信息管理接口服务，包含以下核心能力：

• 使用 Pydantic 定义严格的请求载荷模型（包含字段类型与长度约束）；
• GET /api/v1/items：支持可选关键字过滤的列表查询接口；
• GET /api/v1/items/{item_id}：通过路径参数查询特定资源，并在资源不存在时返回 404；
• POST /api/v1/items：接收 JSON 请求体创建新资源，校验通过后返回 201 Created 状态码。

# main.py
from typing import Optional, List
from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel, Field

# 1. 实例化 FastAPI 应用
app = FastAPI(
    title="商品服务接口 API",
    description="Python 编写的标准 RESTful 接口示例",
    version="1.0.0"
)

# 2. 声明数据契约模型 (Pydantic Schema)
class ItemCreate(BaseModel):
    name: str = Field(..., min_length=1, max_length=50, description="商品名称")
    price: float = Field(..., gt=0, description="商品价格，必须大于 0")
    description: Optional[str] = Field(None, max_length=200, description="商品可选描述")
    in_stock: bool = Field(default=True, description="是否有库存")

class ItemResponse(ItemCreate):
    id: int = Field(..., description="系统分配的唯一标识符")

# 3. 模拟内存数据存储
database_items: List[dict] = [
    {"id": 1, "name": "机械键盘", "price": 499.0, "description": "87键客制化键盘", "in_stock": True},
    {"id": 2, "name": "无线鼠标", "price": 199.0, "description": "双模轻量化鼠标", "in_stock": False}
]

# 4. 实现 GET 列表查询接口
@app.get("/api/v1/items", response_model=List[ItemResponse], tags=["Items"])
def list_items(keyword: Optional[str] = None):
    """获取商品列表，支持名称模糊搜索"""
    if keyword:
        filtered = [item for item in database_items if keyword.lower() in item["name"].lower()]
        return filtered
    return database_items

# 5. 实现 GET 单个资源详情接口
@app.get("/api/v1/items/{item_id}", response_model=ItemResponse, tags=["Items"])
def get_item(item_id: int):
    """根据 ID 获取单个商品详情"""
    for item in database_items:
        if item["id"] == item_id:
            return item
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail=f"商品 ID {item_id} 未找到"
    )

# 6. 实现 POST 创建资源接口
@app.post("/api/v1/items", response_model=ItemResponse, status_code=status.HTTP_201_CREATED, tags=["Items"])
def create_item(payload: ItemCreate):
    """创建新商品"""
    # 检查是否重名
    for existing in database_items:
        if existing["name"] == payload.name:
            raise HTTPException(
                status_code=status.HTTP_400_BAD_REQUEST,
                detail="相同名称的商品已存在"
            )
    
    new_id = len(database_items) + 1
    new_item = {
        "id": new_id,
        "name": payload.name,
        "price": payload.price,
        "description": payload.description,
        "in_stock": payload.in_stock
    }
    database_items.append(new_item)
    return new_item

四、启动服务与请求测试

编写完代码后，使用 Uvicorn 启动本地开发服务器。在命令行中运行以下指令：

uvicorn main:app --host 127.0.0.1 --port 8000 --reload

参数说明：

• main:app：代表读取 main.py 文件中的 app 变量对象；
• --reload：开启代码热更新模式，保存文件后服务器会自动重新载入，适合本地调试。

1. 交互式文档调试

服务启动成功后，在浏览器中打开 http://127.0.0.1:8000/docs，可以看到由 FastAPI 自动生成的 Swagger UI 界面。无需编写任何额外文档配置文件，即可直接在线点击发送测试请求并查看响应体。

2. 使用 cURL 发送验证请求

也可以直接使用终端 curl 命令测试接口：

测试一：创建新商品（POST 请求）

curl -X POST "http://127.0.0.1:8000/api/v1/items" \
  -H "Content-Type: application/json" \
  -d '{"name": "人体工学椅", "price": 1280.5, "description": "网布高回弹", "in_stock": true}'

返回的示例响应（状态码 201）：

{
  "name": "人体工学椅",
  "price": 1280.5,
  "description": "网布高回弹",
  "in_stock": true,
  "id": 3
}

测试二：非法数据拦截验证（输入非法价格）

若故意传递非法的负数价格 -50：

curl -X POST "http://127.0.0.1:8000/api/v1/items" \
  -H "Content-Type: application/json" \
  -d '{"name": "特价鼠标垫", "price": -50}'

系统将自动拦截并返回标准 422 错误，避免脏数据进入业务逻辑：

{
  "detail": [
    {
      "type": "greater_than",
      "loc": ["body", "price"],
      "msg": "Input should be greater than 0",
      "input": -50.0
    }
  ]
}

五、两种常见做法的关键差异分析：FastAPI 与 Flask

在 Python 生态中，构建接口除了 FastAPI 之外，传统的 Flask 同样被广泛使用。理解二者在一致业务条件下的差异，有助于根据项目场景选择合适的实现方式。

主要区别体现在以下两点：

• 数据校验与类型安全：Flask 本身非常轻量，接收到 JSON 后通常需要开发者自行编写 if not request.json.get("name") 之类的判断逻辑，字段类型转换较为繁琐；而 FastAPI 直接依托 Python 类型注解，在函数签名层面就完成了结构化数据的绑定与自动校验。
• I/O 吞吐模型：FastAPI 建立在 Starlette 和 AsyncIO 基础之上，能够直接编写 async def 处理长连接与高并发网络请求；Flask 默认基于 WSGI 同步模式，若遇到大批量的外部 API 调用或慢查询，容易造成工作进程堵塞。

六、生产实践注意事项与常见问题

在接口开发过程中，初学者常遇到以下两个问题：

1. 请求报错 422 Unprocessable Entity：这是 FastAPI 的参数校验机制生效的提示。请检查客户端传递的 JSON 键名是否与 Pydantic 模型完全一致，以及数值字段是否被错误地传入了字符串类型。
2. 浏览器前端联调报错 CORS 跨域拦截：前后端分离开发时，若前端域名或端口与后端不同，需在 FastAPI 中通过 CORSMiddleware 明确配置允许的源（origins）、方法与请求头。