Build a Flask REST API in 12 Steps: 2026 Guide（2026-07-12）

如果你正在寻找一种轻量、灵活且上手极快的方式构建后端 API，Flask 依然是 Python 生态中最受欢迎的选择之一。到了 2026 年，Flask 3.x 已经稳定运行，并吸取了 FastAPI、Starlette 等框架的优势，在性能、安全性和扩展性上都有了显著提升。本文将用 12 个清晰步骤，带你从零搭建一个生产级别的 REST API。

为什么选择 Flask 3.x？

根据 2026 年 Stack Overflow 开发者调查，超过 38% 的 Python 后端开发者仍将 Flask 作为首选框架，这得益于它的模块化设计和极低的学习曲线。Flask 3.x 原生支持异步路由、更严格的类型提示，以及内置的 JSON 序列化优化，处理 1000 并发的简单 CRUD 请求时，响应时间比 2.x 版本平均降低了 22%。

核心优势一览

轻量无侵入：你可以自由选择数据库、认证方式（JWT、OAuth 2.1）和 ORM（SQLAlchemy 2.0+）。
生态成熟：超过 30,000 个第三方扩展，覆盖从任务队列（Celery）到实时 websocket 的一切。

12 步构建你的 API

下面我们快速走完一个图书管理 API 的搭建过程——每一步都附有代码片段和实用技巧。

Step 1: 环境准备与项目初始化

# 使用 Python 3.12+ 虚拟环境
python3 -m venv venv
source venv/bin/activate
pip install Flask==3.1 flask-smorest==0.42

实用建议：2026 年推荐 flask-smorest 替代 marshmallow，它自动生成 API 文档（OpenAPI 3.1）并自带数据验证。

Step 2: 创建基础 Flask 应用

from flask import Flask

app = Flask(__name__)
app.config['API_TITLE'] = 'Library API'
app.config['API_VERSION'] = 'v1'

@app.route('/')
def home():
    return {'message': 'Hello, 2026!'}

Step 3: 定义数据模型（SQLAlchemy + SQLite）

from flask_sqlalchemy import SQLAlchemy
db = SQLAlchemy()

class Book(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(120), nullable=False)
    author = db.Column(db.String(80), nullable=False)
    published = db.Column(db.Integer)

案例数据：插入 3 本畅销书，例如《The Pragmatic Programmer》发布于 1999 年。

Step 4: 编写第一个 CRUD 路由

@app.route('/books', methods=['GET'])
def get_books():
    books = Book.query.all()
    return {'books': [b.to_dict() for b in books]}, 200

Step 5: 添加数据验证（使用 Marshmallow Schema）

from marshmallow import Schema, fields

class BookSchema(Schema):
    id = fields.Int(dump_only=True)
    title = fields.Str(required=True, validate=validate.Length(min=1))
    author = fields.Str(required=True)

2026 年新趋势：使用 Python 3.12 的 @dataclass 配合 attrs 库，可替代部分 Schema 工作。

Step 6-8: 实现 POST、PUT、DELETE

这 3 步本质是 Django 风格的增删改查，但 Flask 允许你完全控制响应头和状态码：

@app.route('/books/<int:book_id>', methods=['PUT'])
def update_book(book_id):
    book = Book.query.get_or_404(book_id)
    data = request.get_json()
    if 'title' in data: book.title = data['title']
    db.session.commit()
    return BookSchema().dump(book), 200

Step 9: 异常处理与包装

@app.errorhandler(404)
def not_found(error):
    return {'error': 'Resource not found'}, 404

Step 10: 引入认证（JWT）

from flask_jwt_extended import JWTManager, jwt_required

jwt = JWTManager(app)

@app.route('/books', methods=['POST'])
@jwt_required()
def create_book():
    # ... 内部逻辑

Step 11: 自动生成 API 文档

使用 flask-smorest，只需一行配置，即可在 /swagger-ui 获得交互式文档。

Step 12: 测试与部署

# 使用 pytest 进行单元测试
pytest test_app.py -v
# 部署到 Render 或 Railway（支持无服务器部署）

实用建议总结

性能优化：对于高流量 API，使用 gunicorn + gevent 作为 WSGI 服务器，而不是 Flask 内置服务器（它只能处理单线程）。
安全注意：永远不要在代码中硬编码 secret_key，使用环境变量或 Vault 管理密钥。
版本控制：在 URL 路径中加 /v1/books，方便 API 后续升级。

你的下一步行动

Flask 的优势在于它不是“黑盒”——你可以快速上手、快速交付，并在需要时深入到框架底层进行定制。今天是开始最好的时机：打开终端，根据以上 12 步创建一个你自己的 API（比如个人博客、记账工具或天气查询接口），并在 GitHub 上开源分享。

当别人还在纠结“选哪个框架”时，你的第一个 API 已经跑在云上了。现在就行动吧。

免责声明：本文所提供的信息、代码示例和建议仅用于教育与技术参考目的。作者不对因使用本文内容导致的任何直接或间接损失承担责任。Flask 框架及其依赖库的版本更新可能影响代码运行效果，请始终参考官方文档进行适配。所有数据（如框架使用率、性能提升百分比）均基于 2026 年公开发布的报告和社区统计，实际结果可能因环境差异而不同。