熊尼玛的七亩地

Python Flask 快速入门指南

本文介绍如何使用 Flask 快速搭建一个简单的 Web 应用，包括环境配置、基础示例和部署方法。

前置要求

  • Python: 3.11+ (推荐 3.11 或 3.12)
  • pyenv: 用于 Python 版本管理（可选但推荐）
  • pip: Python 包管理器

环境准备

如果使用 pyenv 管理 Python 版本：

1
2
3
4
5
6
7
8
# 安装 Python 3.12
pyenv install 3.12.0

# 创建虚拟环境
pyenv virtualenv 3.12.0 flask_demo_env

# 激活虚拟环境
pyenv activate flask_demo_env

或者使用 Python 内置的 venv：

1
2
3
4
5
6
7
8
# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
# macOS/Linux:
source venv/bin/activate
# Windows:
venv\Scripts\activate

项目结构

1
2
3
4
5
flask_demo/
├── app.py              # 主应用文件
├── requirements.txt    # 依赖列表
├── run.sh             # 启动脚本
└── README.md          # 项目说明

依赖安装

requirements.txt

1
2
Flask==3.0.0
gunicorn==21.2.0

安装依赖包

1
2
3
4
5
6
7
# 使用国内镜像加速（可选）
pip install --no-cache-dir -r requirements.txt \
  -i https://mirrors.aliyun.com/pypi/simple/ \
  --trusted-host mirrors.aliyun.com

# 或使用官方源
pip install -r requirements.txt

基础示例

app.py

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
from flask import Flask, jsonify, request

app = Flask(__name__)

@app.route('/')
def hello_world():
    """首页"""
    return 'Hello, World!'

@app.route('/api/hello')
def api_hello():
    """API 示例"""
    return jsonify({
        'message': 'Hello from Flask API',
        'status': 'success'
    })

@app.route('/api/echo', methods=['POST'])
def api_echo():
    """POST 请求示例"""
    data = request.get_json()
    return jsonify({
        'received': data,
        'message': 'Data received successfully'
    })

@app.route('/health')
def health_check():
    """健康检查端点"""
    return jsonify({'status': 'healthy'}), 200

if __name__ == '__main__':
    # 开发模式运行
    app.run(debug=True, host='0.0.0.0', port=5000)

运行方式

方式一：开发模式（Flask 内置服务器）

1
2
3
4
5
6
7
8
9
# 设置环境变量
export FLASK_APP=app.py
export FLASK_ENV=development

# 运行应用
flask run

# 或直接运行
python app.py

方式二：生产模式（Gunicorn）

run.sh

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
#!/bin/bash

# 设置环境变量
export FLASK_APP=app.py

# 使用 Gunicorn 运行
# -w: worker 进程数（建议设置为 CPU 核心数 * 2 + 1）
# -b: 绑定地址和端口
# --access-logfile: 访问日志文件
# --error-logfile: 错误日志文件
gunicorn -w 4 \
         -b 0.0.0.0:5000 \
         --access-logfile - \
         --error-logfile - \
         --timeout 120 \
         app:app

运行服务器

1
2
3
4
5
# 添加执行权限
chmod +x run.sh

# 运行
./run.sh

方式三：使用 systemd（生产环境推荐）

创建 systemd 服务文件 /etc/systemd/system/flask-demo.service：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[Unit]
Description=Flask Demo Application
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/path/to/flask_demo
Environment="PATH=/path/to/venv/bin"
ExecStart=/path/to/venv/bin/gunicorn -w 4 -b 127.0.0.1:5000 app:app
Restart=always

[Install]
WantedBy=multi-user.target

启动服务：

1
2
3
sudo systemctl daemon-reload
sudo systemctl enable flask-demo
sudo systemctl start flask-demo

测试应用

使用 curl 测试

1
2
3
4
5
6
7
8
9
10
11
12
13
# 测试首页
curl http://localhost:5000/

# 测试 API
curl http://localhost:5000/api/hello

# 测试 POST 请求
curl -X POST http://localhost:5000/api/echo \
  -H "Content-Type: application/json" \
  -d '{"name": "Flask", "version": "3.0"}'

# 健康检查
curl http://localhost:5000/health

使用浏览器访问

打开浏览器访问：

最佳实践

1. 项目结构优化

对于大型项目，建议使用蓝图（Blueprints）组织代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# app.py
from flask import Flask
from api import api_bp

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

# api/__init__.py
from flask import Blueprint

api_bp = Blueprint('api', __name__)

@api_bp.route('/users')
def get_users():
    return {'users': []}

2. 配置管理

使用配置文件管理不同环境的设置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# config.py
import os

class Config:
    SECRET_KEY = os.environ.get('SECRET_KEY') or 'dev-secret-key'
    DEBUG = False

class DevelopmentConfig(Config):
    DEBUG = True

class ProductionConfig(Config):
    DEBUG = False

# app.py
from flask import Flask
from config import DevelopmentConfig, ProductionConfig

app = Flask(__name__)
app.config.from_object(DevelopmentConfig)  # 或 ProductionConfig

3. 错误处理

添加全局错误处理：

1
2
3
4
5
6
7
@app.errorhandler(404)
def not_found(error):
    return jsonify({'error': 'Not found'}), 404

@app.errorhandler(500)
def internal_error(error):
    return jsonify({'error': 'Internal server error'}), 500

4. 日志配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import logging
from logging.handlers import RotatingFileHandler

if not app.debug:
    file_handler = RotatingFileHandler('logs/flask_demo.log', 
                                       maxBytes=10240, 
                                       backupCount=10)
    file_handler.setFormatter(logging.Formatter(
        '%(asctime)s %(levelname)s: %(message)s [in %(pathname)s:%(lineno)d]'
    ))
    file_handler.setLevel(logging.INFO)
    app.logger.addHandler(file_handler)
    app.logger.setLevel(logging.INFO)
    app.logger.info('Flask Demo startup')

性能优化建议

  1. 使用 WSGI 服务器: 生产环境使用 Gunicorn 或 uWSGI，不要使用 Flask 内置服务器
  2. 启用缓存: 使用 Flask-Caching 缓存频繁访问的数据
  3. 数据库连接池: 使用 SQLAlchemy 等 ORM 时配置连接池
  4. 静态文件服务: 使用 Nginx 等 Web 服务器处理静态文件
  5. 异步任务: 使用 Celery 处理耗时任务

安全建议

  1. 设置 SECRET_KEY: 用于会话加密，生产环境使用环境变量
  2. HTTPS: 生产环境必须使用 HTTPS
  3. 输入验证: 验证所有用户输入，防止 SQL 注入、XSS 等攻击
  4. CORS 配置: 如果提供 API，正确配置 CORS
  5. 依赖更新: 定期更新依赖包，修复安全漏洞

常见问题

Q: 如何修改端口？

A: 修改 run.sh 中的端口号，或使用环境变量：

1
2
export PORT=8000
gunicorn -b 0.0.0.0:$PORT app:app

Q: 如何查看日志？

A: Gunicorn 的日志会输出到标准输出，也可以重定向到文件：

1
gunicorn app:app --access-logfile access.log --error-logfile error.log

Q: 如何优雅重启？

A: 使用 kill -HUP <pid> 或 systemd 的 systemctl reload 命令

参考资源

总结

本文介绍了 Flask 的基础使用方法，包括：

  • 环境配置和依赖安装
  • 基础应用示例
  • 开发和生产环境的运行方式
  • 最佳实践和安全建议

对于更复杂的应用，建议参考 Flask 官方文档和最佳实践指南。

0%