Python教程

Appearance

Python Web 开发入门 ​

Web 开发指使用 HTTP/HTTPS 提供网页或接口服务。Python 生态中有多种 Web 框架，本教程选用 FastAPI：语法接近现代 Python（配合类型注解）、性能较好、自动生成交互式接口文档，适合构建 API 服务 与小型后端。若你已阅读 类型注解 与 网络编程，会更容易理解下文。

常见框架怎么选 ​

框架特点典型场景
FastAPI异步友好、依赖 Pydantic 校验、自带 OpenAPI/Swagger 文档REST/JSON API、微服务、与前端分离的项目
Flask轻量、灵活、扩展多小型站点、原型、传统服务端渲染
Django内置 ORM、管理后台、认证等“全家桶”内容站、后台系统、需要快速搭全套功能

本教程以 FastAPI 为主线；学会路由、请求体与运行方式后，再学 Flask/Django 会更快。

环境准备 ​

在已激活的虚拟环境中安装依赖（虚拟环境见 虚拟环境的创建）：

bash
pip install fastapi uvicorn
  • FastAPI：Web 框架。
  • Uvicorn：ASGI 服务器，用于运行 FastAPI 应用。

（可选）需要官方 CLI 等扩展时，可使用 pip install "fastapi[standard]"。

第一个接口 ​

新建 main.py：

python
from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"message": "Hello, Web"}

在项目目录下启动服务：

bash
uvicorn main:app --reload

浏览器访问 http://127.0.0.1:8000/ 应看到 JSON。--reload 在开发时会在代码变更后自动重启。

标准的 Web 项目目录 ​

学习阶段用单个 main.py 足够；团队项目或功能增多时，应把路由、数据模型、业务逻辑拆开，便于测试、协作和部署。下面以 FastAPI 为例说明常见做法（Flask 常用「蓝图 + 包」分层，Django 则以「应用 app」为单位划分，思想类似）。

最小可维护结构（中小型 API） ​

适合接口数量不多、尚未引入复杂领域逻辑的项目：

text
my_api/
├── app/
│   ├── __init__.py
│   ├── main.py           # 创建 FastAPI 实例、挂载路由、中间件
│   ├── routers/          # 按资源或模块拆分路由（如 users.py、items.py）
│   ├── schemas/          # Pydantic 模型：请求体、响应体
│   └── services/         # 业务逻辑（可选：与路由解耦，方便单测）
├── tests/                # pytest 等，与业务代码分离
├── requirements.txt      # 或 pyproject.toml 锁定依赖
├── .env.example          # 示例环境变量（不含真实密钥）
└── README.md             # 如何安装、启动、配置
  • 不要把密钥写进仓库：真实配置用 .env（并加入 .gitignore），只提交 .env.example 说明需要哪些变量。
  • 静态资源：若有上传文件或打包后的前端资源，常用 static/ 或由 Nginx 单独托管，不混在 Python 包深处。

更清晰的分层（业务与数据变多时） ​

接入数据库、认证、公共配置时，可再细分为：

text
my_api/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── api/
│   │   └── v1/           # 对外 API 版本（如 /api/v1/...）
│   │       ├── router.py # 汇总子路由
│   │       └── endpoints/
│   ├── core/
│   │   └── config.py     # 读取环境变量、全局配置
│   ├── models/           # ORM 模型（如 SQLAlchemy），与表结构对应
│   ├── schemas/          # Pydantic：入参、出参、与 ORM 转换
│   ├── services/         # 业务规则、调用仓储
│   └── deps.py           # 依赖注入：当前用户、DB 会话等（也可放在 api/ 下）
├── tests/
├── requirements.txt
├── .env.example
└── README.md

各层职责简述：

目录/文件职责
main.py应用入口：创建 FastAPI()、include_router、CORS、生命周期事件
api/…/endpoints只处理 HTTP：参数、状态码、调用 service
schemas校验与序列化 JSON，与接口契约一致
models持久化结构与数据库交互（若不用 ORM，可用 repositories/ 封装 SQL）
services业务逻辑，尽量不直接操作 Request/Response
core/config配置集中管理，避免在模块里散落 os.environ
tests接口测试、单元测试，结构与 app 对应更易找

启动方式与包名 ​

把代码放在 app 包内后，常在项目根目录执行（注意模块路径）：

bash
uvicorn app.main:app --reload

其中 app.main 表示包 app 下的 main 模块，模块里的变量名仍为 app（FastAPI 实例）。

小结（目录） ​

  • 标准做法是：入口一层、路由一层、契约（schema） 与 业务（service） 分开，配置与密钥外置。
  • 项目尚小时不必一次建齐所有目录；出现重复代码或单文件过长时再拆分即可。

路径参数与查询参数 ​

python
from typing import Optional

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
def read_item(item_id: int, q: Optional[str] = None):
    """item_id 来自路径；q 为可选查询参数，如 /items/42?q=search"""
    return {"item_id": item_id, "q": q}

FastAPI 会根据类型注解做转换与校验：路径里的 item_id 若不是整数，会返回清晰的 422 错误信息。

POST 与请求体（Pydantic） ​

使用 Pydantic 模型描述 JSON 请求体，自动校验字段类型：

python
from typing import List

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    price: float
    tags: List[str] = []


@app.post("/items/")
def create_item(item: Item):
    return {"received": item.model_dump()}

向 http://127.0.0.1:8000/items/ 发送 POST，请求体示例：

json
{
  "name": "笔记本",
  "price": 5999.0,
  "tags": ["办公", "轻薄"]
}

自动生成接口文档 ​

服务运行后访问：

  • Swagger UI：http://127.0.0.1:8000/docs
  • ReDoc：http://127.0.0.1:8000/redoc

可在页面里直接试调接口，适合前后端联调与自测。

返回 HTML（可选） ​

FastAPI 常用于 API；若需要简单返回网页，可使用模板引擎（需额外安装 Jinja2）或返回 HTMLResponse：

python
from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI()


@app.get("/hello", response_class=HTMLResponse)
def hello_page():
    return "<h1>你好</h1><p>这是一段 HTML</p>"

复杂页面与大型站点可再了解 Jinja2 模板或前后端分离（前端独立项目调用本后端 API）。

生产部署提示 ​

开发环境用 uvicorn 即可。上线时通常：

  • 前面加 Nginx 等反向代理，处理 HTTPS 与静态资源；
  • 用 gunicorn + uvicorn worker 或多进程 Uvicorn 提高并发；
  • 配置环境变量、日志与限流，勿在公网暴露调试模式。

从打包、scp 上传、服务器 venv、systemd 到 Nginx 的完整步骤见：项目打包与部署。

小结 ​

  • 选用 FastAPI 可快速写出带校验的 JSON API，并自带可试用的文档页。
  • 核心概念：路由装饰器、类型注解、Pydantic 模型、Uvicorn 启动 ASGI 应用。
  • 项目变大时按 路由 / schemas / services（及 models、core） 分层，并配合 tests、依赖清单与环境变量示例，形成可维护的目录结构。
  • 需要底层 TCP/HTTP 原理时，可结合 网络编程；需要持久化时可结合 MySQL 等在路由函数中访问数据库（注意连接池与异步驱动选型）。

更多细节见 FastAPI 官方文档：https://fastapi.tiangolo.com/

Copyright © 2025-2026 京公网安备 11010102000001号 京ICP备2024078128号-1