13.2 API 核心功能开发

Flask API开发完整教程：从蓝图到JWT认证与权限控制

Flask 中文教程

本教程详细讲解Flask API核心功能开发，包括接口蓝图创建与路由注册、请求参数验证与响应格式化、JWT认证集成（使用Flask-JWT-Extended）、资源CRUD接口实现与权限控制。适合Flask初学者和开发者学习构建安全、高效的RESTful API。

Flask API开发教程：从蓝图到JWT认证与权限控制

引言

Flask是一个轻量级、灵活的Python Web框架，非常适合快速开发Web应用和RESTful API。本教程将引导你从零开始，学习如何构建一个完整的API，涵盖核心功能开发、蓝图使用、参数验证、响应格式化、JWT认证、CRUD操作和权限控制。无论你是Flask新手还是有经验的开发者，都能从中受益。

1. API核心功能开发

API（应用程序编程接口）允许不同系统之间进行数据交互。在Flask中，API核心功能通常围绕HTTP请求和响应展开。我们将从设置一个简单的Flask应用开始。

首先，安装Flask：

pip install Flask

创建一个基础应用：

from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/')
def home():
    return jsonify({'message': 'Welcome to Flask API'})

if __name__ == '__main__':
    app.run(debug=True)

运行此应用，访问 http://127.0.0.1:5000/ 将看到JSON响应。这是API的起点。

2. 接口蓝图创建与路由注册

随着API功能增加，使用蓝图（Blueprints）可以组织代码，使应用模块化。蓝图类似于Flask应用中的子应用，允许你将路由分组。

创建蓝图

假设我们要创建一个用户管理API。创建一个名为 api_bp 的蓝图：

from flask import Blueprint, jsonify

api_bp = Blueprint('api', __name__)

@api_bp.route('/users', methods=['GET'])
def get_users():
    # 假设有一个用户列表
    users = [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Bob'}]
    return jsonify(users)

注册蓝图到应用

在主应用中注册蓝图：

from flask import Flask
from api_routes import api_bp  # 假设api_routes.py包含蓝图定义

app = Flask(__name__)
app.register_blueprint(api_bp, url_prefix='/api')

现在，访问 http://127.0.0.1:5000/api/users 将返回用户列表。

3. 请求参数验证与响应格式化

处理API请求时，验证输入参数至关重要，以避免错误和安全问题。同时，格式化响应（如JSON）确保数据一致性。

请求参数验证

Flask提供了 request 对象来获取请求数据。我们可以使用Python内置功能或库（如 Flask-RESTful）进行验证。

示例：验证POST请求中的JSON数据：

from flask import request, jsonify

@api_bp.route('/user', methods=['POST'])
def create_user():
    data = request.get_json()  # 获取JSON数据
    if not data:
        return jsonify({'error': 'Invalid JSON'}), 400  # 400 Bad Request
    
    # 验证必需参数
    required_fields = ['username', 'email']
    for field in required_fields:
        if field not in data:
            return jsonify({'error': f'Missing field: {field}'}), 400
    
    # 处理用户创建逻辑
    # 假设这里保存用户到数据库
    return jsonify({'message': 'User created successfully', 'user': data}), 201  # 201 Created

响应格式化

使用 jsonify 函数自动将Python字典转换为JSON响应，并设置适当的HTTP状态码。这确保客户端接收到标准化的数据。

4. JWT认证集成（Flask-JWT-Extended）

JWT（JSON Web Tokens）是一种流行的认证机制，用于保护API端点。我们将使用Flask-JWT-Extended库来实现。

安装Flask-JWT-Extended

pip install Flask-JWT-Extended

配置和设置

在主应用中配置JWT：

from flask import Flask
from flask_jwt_extended import JWTManager

app = Flask(__name__)
app.config['JWT_SECRET_KEY'] = 'your-secret-key'  # 在生产环境中使用强密钥
jwt = JWTManager(app)

创建登录端点

实现一个登录接口，生成JWT令牌：

from flask import request, jsonify
from flask_jwt_extended import create_access_token

@api_bp.route('/login', methods=['POST'])
def login():
    data = request.get_json()
    username = data.get('username')
    password = data.get('password')
    
    # 这里应验证用户名和密码，例如查询数据库
    if username == 'admin' and password == 'password':  # 简单示例
        access_token = create_access_token(identity=username)  # 创建令牌
        return jsonify(access_token=access_token), 200
    else:
        return jsonify({'error': 'Invalid credentials'}), 401  # 401 Unauthorized

保护端点

使用 @jwt_required() 装饰器保护需要认证的路由：

from flask_jwt_extended import jwt_required

@api_bp.route('/protected', methods=['GET'])
@jwt_required()
def protected():
    return jsonify({'message': 'This is a protected endpoint'})

现在，只有提供有效JWT令牌的请求才能访问 /api/protected。

5. 资源CRUD接口实现与权限控制

CRUD（创建、读取、更新、删除）是API的核心操作。我们将基于用户资源实现CRUD接口，并添加权限控制。

实现CRUD接口

假设我们有一个简单的用户模型（例如使用SQLite或模拟数据）。创建端点：

GET /users: 获取所有用户
GET /users/: 获取单个用户
POST /users: 创建新用户
PUT /users/: 更新用户
DELETE /users/: 删除用户

示例代码（简化版，未包含完整数据库逻辑）：

from flask import request, jsonify
from flask_jwt_extended import jwt_required, get_jwt_identity

# 模拟用户数据库
users = []

@api_bp.route('/users', methods=['GET'])
@jwt_required()
def get_all_users():
    return jsonify(users)

@api_bp.route('/users/<int:user_id>', methods=['GET'])
@jwt_required()
def get_user(user_id):
    user = next((u for u in users if u['id'] == user_id), None)
    if user:
        return jsonify(user)
    else:
        return jsonify({'error': 'User not found'}), 404

@api_bp.route('/users', methods=['POST'])
@jwt_required()
def create_user():
    data = request.get_json()
    new_user = {'id': len(users) + 1, 'name': data.get('name'), 'email': data.get('email')}
    users.append(new_user)
    return jsonify(new_user), 201

@api_bp.route('/users/<int:user_id>', methods=['PUT'])
@jwt_required()
def update_user(user_id):
    data = request.get_json()
    user = next((u for u in users if u['id'] == user_id), None)
    if user:
        user.update(data)
        return jsonify(user)
    else:
        return jsonify({'error': 'User not found'}), 404

@api_bp.route('/users/<int:user_id>', methods=['DELETE'])
@jwt_required()
def delete_user(user_id):
    global users
    users = [u for u in users if u['id'] != user_id]
    return jsonify({'message': 'User deleted'}), 200

权限控制

基于JWT令牌的identity，我们可以实现简单的权限控制。例如，只有管理员才能删除用户：

from flask_jwt_extended import get_jwt_identity

@api_bp.route('/users/<int:user_id>', methods=['DELETE'])
@jwt_required()
def delete_user(user_id):
    current_user = get_jwt_identity()  # 获取当前用户身份
    # 假设我们有一个权限检查函数
    if current_user != 'admin':  # 简单示例，只允许管理员删除
        return jsonify({'error': 'Permission denied'}), 403  # 403 Forbidden
    
    global users
    users = [u for u in users if u['id'] != user_id]
    return jsonify({'message': 'User deleted'}), 200

在实际应用中，可以使用更复杂的基于角色的访问控制（RBAC）。

总结

本教程覆盖了Flask API开发的关键步骤：从设置基础应用、使用蓝图组织代码、验证请求参数、格式化响应、集成JWT认证，到实现CRUD接口和添加权限控制。通过这些内容，你应该能够构建一个功能齐全、安全的RESTful API。

进一步学习建议：

探索Flask官方文档以了解更多高级功能。
学习数据库集成，如使用SQLAlchemy。
实践部署API到生产环境，如使用Gunicorn或Docker。

祝你学习顺利，Happy coding！

上一章 13.1 项目需求与技术选型

下一章 13.3 API 文档与部署准备