Flask API开发最佳实践 - Auth0

在使用 FastAPI 则以灵活性和高性能著称。在本文中，我们将重点探讨使用 Flask 开发 API 的最佳实践。

使用正确的名称和 HTTP 谓词设计 API 端点

设计清晰易懂的 API 是开发者的基本目标。通过合理的 URI 命名和 HTTP 动词的使用，开发者可以直观地理解 API 的功能和行为。

资源命名的基本原则

在 REST 架构中，资源是一级数据表示。为资源命名时，保持一致性是关键。以下是一些命名资源的最佳实践：

使用复数形式的名词表示资源：
- ✅ /users 表示用户集合，/users/{userId} 表示单个用户。
- ✅ /users/{userId}/playlists 表示用户的播放列表。
使用连字符 - 分隔单词：
- ✅ /users/{userId}/mobile-devices
- ❌ /users/{userId}/mobileDevices
使用正斜杠 / 表示层次结构：
- ✅ /users/{userId}/orders
- ❌ /users-orders/{userId}
统一使用小写字母：
- ✅ /users/{userId}/devices
- ❌ /Users/{userId}/Devices

动作命名的最佳实践

对于与资源无关的操作，例如结账或运行任务，建议在 URI 中使用动词表示动作：

✅ /users/{userId}/cart/checkout 表示执行结账操作。

同时，CRUD 操作（创建、读取、更新、删除）应通过 HTTP 动词来实现，而非在 URI 中显式表示。例如：

GET：用于检索数据，例如 /users 获取用户列表。
POST：用于创建新资源，例如 /users 创建新用户。
PUT：用于更新资源，例如 /users/{userId} 更新用户信息。
DELETE：用于删除资源，例如 /users/{userId} 删除用户。
PATCH：用于部分更新资源，例如 /users/{userId} 更新部分用户信息。

通过这些原则，开发者可以设计出清晰且易于维护的 API。

如何正确构建你的应用程序

构建 Flask 应用程序的方式可能因项目规模、需求和个人偏好而异。以下是一个推荐的项目结构，基于多年的生产经验：

project/

├── api/

│   ├── models/

│   │   └── __init__.py

│   ├── routes/

│   │   └── home.py

│   ├── schemas/

│   │   └── __init__.py

│   ├── services/

│   │   └── __init__.py

│   └── __init__.py

├── tests/

│   ├── routes/

│   │   └── test_home.py

│   └── __init__.py

├── app.py

├── Pipfile

└── Pipfile.lock

模块功能解析

models：定义数据模型，通常与数据库表结构相关。
routes：定义应用程序的 URI 和资源操作。
schemas：定义 API 的输入输出结构，明确参数和返回数据。
services：处理业务逻辑，与数据库或其他服务交互。

在 Flask 中，使用蓝图（Blueprint）可以更好地组织路由。例如：

from flask import Blueprint

home_api = Blueprint('home', __name__, url_prefix='/home-service')@home_api.route('/')
def welcome():
    return {"message": "Welcome to the Flask Starter Kit"}, 200

通过蓝图，可以轻松管理路由的分组和前缀。

从代码构建文档

构建 API 后，开发者需要清晰的文档来指导使用。使用 Swagger 可以自动生成交互式文档。以下是一个简单的示例：

from flasgger import swag_from

@home_api.route('/')
@swag_from({
    'responses': {
        200: {
            'description': 'Welcome to the Flask Starter Kit',
            'schema': {
                'type': 'object',
                'properties': {
                    'message': {'type': 'string'}
                }
            }
        }
    }
})
def welcome():
    """API 欢迎端点
    ---
    返回欢迎信息。
    """
    return {"message": "Welcome to the Flask Starter Kit"}, 200

通过结合 Flask 和 Flasgger，可以快速生成动态文档，提升开发效率。

测试驱动开发（TDD）

测试是确保代码质量的重要手段。采用测试驱动开发（TDD）可以显著提高开发效率和代码可靠性。TDD 的基本流程如下：

编写测试：

def test_sum():
   assert sum_two_numbers(3, 5) == 8

运行测试（失败）：由于函数尚未实现，测试会失败。

实现功能：

def sum_two_numbers(a, b):
   return a + b

重新运行测试（通过）：验证功能是否满足需求。

通过这种方式，开发者可以在开发过程中快速发现并修复问题。

结论

在 API 开发中，最佳实践因项目而异，但以下原则可以帮助您构建高效、易维护的 API：

在命名上保持一致性。
通过模块化结构组织代码。
利用工具从代码生成文档。
采用测试驱动开发确保代码质量。

希望本文能为您的 Flask API 开发提供有价值的参考！

原文链接: https://auth0.com/blog/best-practices-for-flask-api-development/