下面我将为你详细介绍几种主流的封装方法,从简单到复杂，并给出完整的代码示例。

核心概念

无论使用哪种技术,封装接口的核心思想都是：

1. 定义你的核心业务逻辑：这是你想要封装的 Python 函数或类。
2. 选择一个 Web 框架：这个框架会处理 HTTP 请求和响应的细节（如解析 URL、获取请求体、设置响应头等）。
3. 将业务逻辑映射到 Web 端点：告诉框架哪个 URL 路径对应哪个 Python 函数。
4. 处理输入和输出：
   • 输入：从 HTTP 请求中获取数据（从 URL 路径、查询参数或请求体中）。
   • 输出：将 Python 函数的返回值（通常是 Python 字典或对象）转换成标准格式（如 JSON）并作为 HTTP 响应返回。

使用 Flask (轻量级，适合中小型项目)

Flask 是一个简单、灵活的 Python Web 框架，非常适合快速构建 API，它被称为“微框架”，因为它只提供核心功能，其他功能可以通过扩展添加。

安装 Flask

pip install Flask

示例：创建一个简单的加法 API

核心业务逻辑

# logic.py
def add_numbers(a, b):
    """将两个数字相加"""
    if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
        raise ValueError("参数必须是数字")
    return a + b

创建 Flask 接口

# app.py
from flask import Flask, request, jsonify
from logic import add_numbers
# 创建 Flask 应用实例
app = Flask(__name__)
# 定义一个路由，处理 POST 请求到 /add
@app.route('/add', methods=['POST'])
def add():
    # 从请求的 JSON body 中获取数据
    data = request.get_json()
    # 检查数据是否存在
    if not data or 'a' not in data or 'b' not in data:
        return jsonify({'error': '请提供 a 和 b 两个参数'}), 400 # 400 Bad Request
    try:
        # 调用核心业务逻辑函数
        result = add_numbers(data['a'], data['b'])
        # 返回 JSON 响应
        return jsonify({'result': result})
    except ValueError as e:
        # 处理参数错误
        return jsonify({'error': str(e)}), 400
    except Exception as e:
        # 处理其他未知错误
        return jsonify({'error': '服务器内部错误'}), 500
# 运行应用
if __name__ == '__main__':
    # debug=True 在开发时使用，会自动重载并显示详细错误
    app.run(debug=True, port=5000)

如何运行和测试

• 运行：在终端中运行 app.py 文件。

  python app.py

• 测试：你可以使用 curl 或 Postman 等工具来测试这个接口。

  # 使用 curl 发送 POST 请求
  curl -X POST -H "Content-Type: application/json" -d '{"a": 10, "b": 5}' http://127.0.0.1:5000/add

• 预期输出：

  {"result": 15}

使用 FastAPI (现代高性能，推荐)

FastAPI 是一个现代、快速的（高性能）Web 框架，用于构建 API，它最大的优点是自动生成 OpenAPI (Swagger) 文档，并且有强大的数据验证功能。

安装 FastAPI 和 Uvicorn (ASGI 服务器)

pip install "fastapi[all]"
# 或者分开安装
pip install fastapi
pip install uvicorn

示例：创建一个用户信息 API

核心业务逻辑

# logic.py
def get_user_info(user_id: int):
    """根据用户ID获取用户信息"""
    # 这里只是一个模拟，实际应用中可能从数据库查询
    users = {
        1: {"name": "Alice", "email": "alice@example.com"},
        2: {"name": "Bob", "email": "bob@example.com"},
    }
    if user_id in users:
        return users[user_id]
    return None

创建 FastAPI 接口

# app.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Optional
from logic import get_user_info
app = FastAPI()
# 定义请求体的数据模型，FastAPI会自动进行数据验证
class User(BaseModel):
    name: str
    email: str
# 定义一个路由，处理 GET 请求到 /users/{user_id}
# {user_id} 是一个路径参数，FastAPI会自动尝试转换为 int
@app.get("/users/{user_id}", response_model=Optional[User])
def read_user(user_id: int):
    user = get_user_info(user_id)
    if user is None:
        # 如果用户不存在，返回 404 Not Found 错误
        raise HTTPException(status_code=404, detail="用户未找到")
    return user
# 定义一个路由，处理 POST 请求到 /users/
@app.post("/users/", response_model=User)
def create_user(user: User):
    # 在实际应用中，这里会有代码将用户数据存入数据库
    print(f"创建用户: {user.name}, {user.email}")
    return user
# 运行应用
if __name__ == '__main__':
    # 使用 uvicorn 运行 FastAPI 应用
    uvicorn.run(app, host="0.0.0.0", port=8000)

如何运行和测试

• 运行：在终端中运行 app.py 文件。

  python app.py

• 自动文档：打开浏览器访问 http://127.0.0.1:8000/docs，你会看到一个由 Swagger UI 生成的交互式 API 文档，你可以在页面上直接测试 API！
• 测试：
  • GET 请求：

    curl http://127.0.0.1:8000/users/1

    输出: {"name":"Alice","email":"alice@example.com"}

  • POST 请求：

    curl -X POST -H "Content-Type: application/json" -d '{"name": "Charlie", "email": "charlie@example.com"}' http://127.0.0.1:8000/users/

    输出: {"name":"Charlie","email":"charlie@example.com"}

使用 Django REST framework (功能强大，适合大型项目)

Django 是一个功能全面的 Web 框架，而 Django REST framework (DRF) 是专门为构建 API 而设计的强大扩展，它提供了序列化、视图、权限等高级功能。

安装 Django 和 DRF

pip install django
pip install djangorestframework

创建 Django 项目和应用

# 创建项目
django-admin startproject myapi
cd myapi
# 创建应用
python manage.py startapp api

配置项目 在 myapi/settings.py 中，将 rest_framework 添加到 INSTALLED_APPS：

# myapi/settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',  # 添加这一行
    'api',             # 添加你的应用
]

定义模型和序列化器 在 api/models.py 中定义数据模型：

# api/models.py
from django.db import models
class Book(models.Model):= models.CharField(max_length=100)
    author = models.CharField(max_length=100)
    published_date = models.DateField()
    def __str__(self):
        return self.title

运行数据库迁移：

python manage.py makemigrations
python manage.py migrate

在 api/serializers.py 中创建序列化器（负责将模型实例转换为JSON）：

# api/serializers.py
from rest_framework import serializers
from .models import Book
class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = '__all__' # 包含所有字段

创建视图 在 api/views.py 中创建 API 视图：

# api/views.py
from rest_framework import viewsets
from .models import Book
from .serializers import BookSerializer
# ViewSet 提供了 list, create, retrieve, update, destroy 等默认行为
class BookViewSet(viewsets.ModelViewSet):
    queryset = Book.objects.all().order_by('-published_date')
    serializer_class = BookSerializer

配置 URL 在 api/urls.py 中创建路由文件（如果不存在，请手动创建）：

# api/urls.py
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import BookViewSet
# 创建一个路由器并注册我们的 ViewSet
router = DefaultRouter()
router.register(r'books', BookViewSet)
# API URL 现在由路由器自动确定
urlpatterns = [
    path('', include(router.urls)),
]

在 myapi/urls.py 中包含应用的 URL：

# myapi/urls.py
from django.contrib import admin
from django.urls import path, include
urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('api.urls')), # 添加这一行
]

运行和测试

• 运行：

  python manage.py runserver

• 测试：
  • 访问 http://127.0.0.1:8000/api/books/，你会看到一个由 DRF 提供的、功能齐全的 API 测试页面。
  • 你可以在这个页面上直接创建、查看、编辑和删除图书，无需编写任何额外的代码。

总结与选择

如何选择？

• 如果你是初学者或想快速搭建一个简单的 API：选择 Flask。
• 如果你想要一个现代、高性能、自带优秀文档的 API：强烈推荐 FastAPI，这是目前的新趋势。
• 如果你已经在使用 Django，或者你的项目非常复杂，需要一套完整的解决方案（包括后台管理、权限控制等）：选择 Django REST Framework。