Web Development on Snow

Flask 实战教程：面向 Python 开发者的轻量 Web 后端入门

Wed, 16 Sep 2026 10:20:00 +0800

Flask 实战教程：面向 Python 开发者的轻量 Web 后端入门

Flask 的魅力在于“小”：它不会一开始就替你规定项目结构、数据库 ORM、表单库、登录系统和管理后台。但这种自由也意味着你需要自己决定边界。本文会从一个可运行的小项目开始，逐步把自由组织成可维护的工程结构。

如果你已经会 Python 函数、装饰器、虚拟环境和基础 HTTP，Flask 很适合作为第一个 Web 后端框架。它既能写返回 HTML 的传统网站，也能写 JSON API；既能单文件快速验证想法，也能用应用工厂、Blueprint 和扩展支撑中型项目。

你已有的 Python 能力	在 Flask 中如何对应
函数	一个视图函数处理一个路由
装饰器	`@app.get()`、`@app.post()` 绑定 URL
字典和列表	可以直接返回 JSON 风格数据
模板字符串思维	用 Jinja2 渲染 HTML 页面
模块拆分	用 Blueprint 组织路由
单元测试	用 Flask test client 测接口行为

一、Flask 是什么

Flask 是一个轻量级 WSGI Web 框架。它的核心只处理 Web 框架最基础的几件事：

URL 路由；
请求对象和响应对象；
Cookie、Session、上下文；
Jinja2 模板集成；
静态文件；
错误处理；
扩展机制。

数据库、表单校验、登录认证、后台任务、API 文档等能力通常通过扩展或你的业务代码组合出来。这和 Django 的“全家桶”风格不同：Django 默认给你很多约定，Flask 默认给你一个很薄但很灵活的核心。

一次请求在 Flask 中大致会经过这些阶段：

WSGI Server 接收 HTTP 请求；
Flask 创建请求上下文；
根据 URL Rule 匹配视图函数；
执行 before_request 等钩子；
运行视图函数；
返回字符串、字典、模板响应、重定向或 Response 对象；
执行 after_request 等钩子；
WSGI Server 把响应发回客户端。

你可以把 Flask 理解成一个“请求响应协调器”：它不会强迫你怎么写业务，但会把请求到函数、函数到响应这条主线打通。

二、环境准备

先创建虚拟环境：

mkdir flask-shop
cd flask-shop

python -m venv .venv

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

安装 Flask：

`1`	`pip install Flask`

Flask 官方文档当前稳定版仍然以 pip install Flask 作为基础安装方式。生产项目建议再生成固定版本依赖：

`1`	`pip freeze > requirements.txt`

如果你准备写测试，顺手装上 pytest：

`1`	`pip install pytest`

三、第一个 Flask 应用

创建 app.py：

from flask import Flask, jsonify, request


app = Flask(__name__)

items: dict[int, dict[str, object]] = {}
next_id = 1


@app.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok"}


@app.get("/items")
def list_items():
    q = request.args.get("q", "").strip().lower()
    result = list(items.values())

    if q:
        result = [item for item in result if q in str(item["name"]).lower()]

    return jsonify(result)


@app.post("/items")
def create_item():
    global next_id

    data = request.get_json(silent=True) or {}
    name = str(data.get("name", "")).strip()
    price = data.get("price")

    if not name:
        return {"error": "name is required"}, 400

    try:
        price = float(price)
    except (TypeError, ValueError):
        return {"error": "price must be a number"}, 400

    if price <= 0:
        return {"error": "price must be greater than 0"}, 400

    item = {"id": next_id, "name": name, "price": price}
    items[next_id] = item
    next_id += 1

    return jsonify(item), 201


@app.get("/items/<int:item_id>")
def read_item(item_id: int):
    item = items.get(item_id)

    if item is None:
        return {"error": "item not found"}, 404

    return jsonify(item)

运行开发服务器：

`1`	`flask --app app run`

浏览器打开：

http://127.0.0.1:5000/health
http://127.0.0.1:5000/items

用 curl 创建一个商品：

1
2
3

curl -X POST http://127.0.0.1:5000/items \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"Keyboard\",\"price\":299}"

开发时如果想开启调试模式，可以加 --debug：

`1`	`flask --app app run --debug`

调试模式会自动重载代码并展示调试信息，但不要在生产环境开启。

四、路由、请求与响应

Flask 的基本工作方式很直接：URL 规则匹配到视图函数，视图函数返回响应。

常见路由写法：

@app.get("/")
def index():
    return "Hello Flask"


@app.get("/users/<int:user_id>")
def read_user(user_id: int):
    return {"user_id": user_id}


@app.post("/users")
def create_user():
    data = request.get_json()
    return {"received": data}, 201

请求数据通常来自几个位置：

来源	写法	场景
查询参数	`request.args.get("q")`	`/items?q=book`
路径参数	`/items/<int:item_id>`	资源 ID
JSON body	`request.get_json()`	API 请求体
表单	`request.form["name"]`	HTML 表单提交
Header	`request.headers.get("X-Token")`	鉴权、追踪 ID
Cookie	`request.cookies.get("theme")`	轻量偏好

视图函数可以返回多种值：

return "Hello"
return {"status": "ok"}
return jsonify(items)
return jsonify(item), 201
return redirect("/items")
return render_template("items.html", items=items)

Flask 适合初学者的一个原因是：你可以先用简单返回值跑通，等项目复杂后再引入更严格的响应结构和错误处理。

五、模板：用 Jinja2 返回 HTML

Flask 不只适合写 API，它也很适合写服务端渲染页面。创建目录：

flask-shop/
├── app.py
└── templates/
    ├── base.html
    └── items.html

templates/base.html：

<!doctype html>
<html lang="zh-CN">
<head>
    <meta charset="utf-8">
    <title>{% block title %}Flask Shop{% endblock %}</title>
</head>
<body>
    <header>
        <h1>Flask Shop</h1>
    </header>

    <main>
        {% block content %}{% endblock %}
    </main>
</body>
</html>

templates/items.html：

{% extends "base.html" %}

{% block title %}商品列表{% endblock %}

{% block content %}
    <h2>商品列表</h2>

    <ul>
        {% for item in items %}
            <li>{{ item.name }} - {{ item.price }}</li>
        {% else %}
            <li>暂无商品</li>
        {% endfor %}
    </ul>
{% endblock %}

在 app.py 中增加页面路由：

from flask import render_template


@app.get("/")
def index():
    return render_template("items.html", items=list(items.values()))

Jinja2 默认会对变量进行 HTML 转义，所以 {{ item.name }} 比自己拼接 HTML 字符串安全得多。除非你非常明确知道数据来源可信，否则不要随便使用 |safe。

六、表单、Session 与安全边界

Flask 给你自由，但安全边界需要主动设计。尤其是表单、Session、Cookie、模板输出和数据库查询这些地方。

先看一个简单表单页面：

<form method="post" action="/items/form">
    <label>
        名称
        <input name="name" required>
    </label>

    <label>
        价格
        <input name="price" type="number" step="0.01" min="0.01" required>
    </label>

    <button type="submit">创建</button>
</form>

后端处理：

from flask import redirect, request, url_for


@app.post("/items/form")
def create_item_from_form():
    global next_id

    name = request.form.get("name", "").strip()
    price_raw = request.form.get("price")

    if not name:
        return "name is required", 400

    try:
        price = float(price_raw)
    except (TypeError, ValueError):
        return "price must be a number", 400

    item = {"id": next_id, "name": name, "price": price}
    items[next_id] = item
    next_id += 1

    return redirect(url_for("index"))

上面只是演示最小流程。真实项目建议使用 Flask-WTF 或其他表单库来处理字段校验和 CSRF 防护。

Session 需要设置密钥：

import os

app = Flask(__name__)
app.config["SECRET_KEY"] = os.environ.get("SECRET_KEY", "dev-only-change-me")

然后可以使用 session：

from flask import session


@app.post("/login")
def login():
    session["user_id"] = 1
    return {"status": "logged in"}

需要注意：Flask 默认 Session 是签名 Cookie。客户端不能随意篡改它，但可以看到它的内容，所以不要把密码、Token、隐私数据或大量数据放进 Session。

七、项目变大后：应用工厂与 Blueprint

单文件适合入门，但项目继续长大后，app.py 很容易变成一个难维护的大文件。Flask 官方文档推荐使用应用工厂模式，也就是写一个 create_app() 函数来创建应用。

推荐结构：

flask-shop/
├── app/
│   ├── __init__.py
│   ├── blueprints/
│   │   ├── items.py
│   │   └── users.py
│   ├── templates/
│   │   ├── base.html
│   │   └── items/
│   │       └── list.html
│   ├── static/
│   │   └── style.css
│   └── config.py
├── tests/
│   └── test_items.py
└── requirements.txt

app/__init__.py：

from flask import Flask


def create_app(test_config: dict | None = None) -> Flask:
    app = Flask(__name__, instance_relative_config=True)

    app.config.from_mapping(
        SECRET_KEY="dev",
    )

    if test_config is not None:
        app.config.update(test_config)

    from app.blueprints.items import bp as items_bp

    app.register_blueprint(items_bp)

    @app.get("/health")
    def health() -> dict[str, str]:
        return {"status": "ok"}

    return app

app/blueprints/items.py：

from flask import Blueprint, jsonify, request


bp = Blueprint("items", __name__, url_prefix="/items")

items: dict[int, dict[str, object]] = {}
next_id = 1


@bp.get("")
def list_items():
    return jsonify(list(items.values()))


@bp.post("")
def create_item():
    global next_id

    data = request.get_json(silent=True) or {}
    name = str(data.get("name", "")).strip()
    price = float(data.get("price", 0))

    if not name or price <= 0:
        return {"error": "invalid item"}, 400

    item = {"id": next_id, "name": name, "price": price}
    items[next_id] = item
    next_id += 1

    return jsonify(item), 201

运行应用工厂：

`1`	`flask --app app run --debug`

这里的 --app app 会找到 app 包中的 create_app()。这种结构的优点是：测试时可以创建独立配置的应用，扩展初始化也更清晰。

八、数据库与扩展怎么选

Flask 不自带 ORM。常见组合是：

需求	常用选择
ORM	Flask-SQLAlchemy 或 SQLAlchemy
数据库迁移	Flask-Migrate / Alembic
登录态	Flask-Login
表单和 CSRF	Flask-WTF
API 参数校验	Marshmallow、Pydantic 或 Webargs
REST API 快速组织	Flask-RESTful、Flask-Smorest
后台任务	Celery、RQ、Dramatiq

初学时不要一次性把所有扩展装满。建议顺序是：

先用内存字典理解路由和请求；
再接 SQLite 和 SQLAlchemy；
再加数据库迁移；
页面项目加 Flask-WTF；
有登录需求再加 Flask-Login；
API 项目再考虑 Marshmallow、Pydantic 或 OpenAPI 相关扩展。

Flask 的扩展生态很丰富，但扩展越多，越需要清晰的初始化位置。应用工厂模式正是为了解决这个问题。

九、测试：用 test client 固定接口行为

Flask 自带 test client，适合直接测试接口。

tests/test_items.py：

from app import create_app


def test_health():
    app = create_app({"TESTING": True})
    client = app.test_client()

    response = client.get("/health")

    assert response.status_code == 200
    assert response.get_json() == {"status": "ok"}


def test_create_item():
    app = create_app({"TESTING": True})
    client = app.test_client()

    response = client.post(
        "/items",
        json={"name": "Mouse", "price": 99},
    )

    assert response.status_code == 201
    body = response.get_json()
    assert body["name"] == "Mouse"
    assert body["price"] == 99


def test_reject_invalid_item():
    app = create_app({"TESTING": True})
    client = app.test_client()

    response = client.post("/items", json={"name": "", "price": -1})

    assert response.status_code == 400

运行：

pytest

测试重点不是“把每一行都跑一遍”，而是保护接口行为：状态码、响应结构、错误分支、鉴权和关键业务规则。这样后面把内存字典替换成数据库时，测试能告诉你外部行为有没有变。

十、错误处理与状态码

Flask 允许你直接返回 (body, status_code)：

`1`	`return {"error": "item not found"}, 404`

也可以使用 abort：

from flask import abort


@app.get("/items/<int:item_id>")
def read_item(item_id: int):
    item = items.get(item_id)

    if item is None:
        abort(404)

    return item

如果想统一错误结构，可以注册错误处理器：

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


@app.errorhandler(500)
def internal_error(error):
    return {"error": "internal server error"}, 500

常用状态码：

状态码	场景
`200 OK`	查询成功
`201 Created`	创建成功
`204 No Content`	删除成功且无响应体
`400 Bad Request`	参数语义错误
`401 Unauthorized`	未登录或凭证无效
`403 Forbidden`	已登录但无权限
`404 Not Found`	资源不存在
`409 Conflict`	资源冲突
`500 Internal Server Error`	未预期服务端错误

如果你写的是 API，建议从一开始就统一错误格式。否则前端会在不同接口里解析不同形状的错误响应。

十一、从开发到生产部署

本地开发命令：

`1`	`flask --app app run --debug`

但 Flask 官方文档明确提醒：内置开发服务器只用于本地开发，不要用于生产。生产环境应交给 WSGI Server 或托管平台。

Windows 上可以用 Waitress：

1
2

pip install waitress
waitress-serve --host=0.0.0.0 --port=8000 "app:create_app()"

Linux 服务器上常见组合是 Gunicorn + Nginx：

1
2

pip install gunicorn
gunicorn "app:create_app()" --bind 0.0.0.0:8000 --workers 4

一个最小 Dockerfile：

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app ./app

EXPOSE 8000
CMD ["gunicorn", "app:create_app()", "--bind", "0.0.0.0:8000", "--workers", "4"]

生产前至少补齐：

项目	原因
固定依赖版本	避免构建时引入不可预期更新
环境变量	密钥、数据库地址、第三方 Token 不写进代码
`SECRET_KEY`	Session、CSRF 等安全能力依赖它
数据库迁移	schema 变化可追踪、可回滚
结构化日志	方便排查线上问题
健康检查	让负载均衡知道应用是否可用
HTTPS	保护 Cookie、登录态和敏感请求
反向代理	处理静态资源、TLS、压缩、限流等入口能力

十二、Flask 常见坑

坑	更稳的做法
所有代码堆在 `app.py`	入门可以，项目变大后用应用工厂和 Blueprint
把开发服务器用于生产	生产使用 Gunicorn、Waitress、uWSGI 或托管平台
不设置 `SECRET_KEY`	从环境变量读取，并在生产环境使用强随机值
手写 HTML 字符串	用 Jinja2 模板，避免未转义内容混入页面
表单写入不做 CSRF	页面项目使用 Flask-WTF 或等价方案
SQL 用字符串拼接	使用 ORM 或参数化 SQL
错误响应格式不统一	API 项目尽早统一错误结构
Blueprint 里塞太多业务	路由负责 HTTP，复杂规则移到 service 层

十三、Flask 与 FastAPI 怎么选

维度	Flask	FastAPI
框架风格	轻量、自由、扩展组合	类型驱动、API 契约强
页面渲染	Jinja2 体验成熟	也能做，但主流认知偏 API
请求校验	需要自己选扩展或手写	Pydantic 深度集成
自动文档	需要扩展	内置 OpenAPI 文档
异步支持	不是核心优势	ASGI 原生更适合异步 API
入门感受	概念少，适合理解 Web 本质	工程化 API 体验更完整

如果你想理解 Web 后端的底层主线，或者写一个页面 + 少量 API 的项目，Flask 很舒服。如果你目标是类型契约明确的纯 API 服务，尤其需要自动 OpenAPI 文档，FastAPI 往往更省心。

十四、学习路线

建议按这个顺序继续：

Jinja2 模板继承、宏和过滤器；
Blueprint 和应用工厂；
Flask-SQLAlchemy + Flask-Migrate；
Flask-WTF 和 CSRF；
Flask-Login；
错误处理和日志；
pytest + test client；
Gunicorn / Waitress / Docker 部署；
Nginx、HTTPS 和线上监控。

Flask 的好处是你可以每次只学一小块。先把请求响应、模板和测试跑通，再慢慢引入数据库、登录、表单和部署能力，学习曲线会平滑很多。

参考资料

FastAPI 实战教程：面向 Python 开发者的现代 API 入门

Tue, 15 Sep 2026 22:10:00 +0800

FastAPI 实战教程：面向 Python 开发者的现代 API 入门

如果你已经会 Python 函数、类型提示、虚拟环境和一点 HTTP 基础，FastAPI 会给你一种很顺手的体验：你写普通函数和 Pydantic 模型，它负责把请求解析、参数校验、JSON 序列化和 OpenAPI 文档串起来。

这篇文章不从“什么是 Web 框架”讲起，而是面向已经有 Python 基础的开发者，直接搭一个可运行的小 API，再逐步补上工程里绕不开的几件事：数据校验、错误处理、依赖注入、异步选择、项目拆分、测试和部署。

你已有的 Python 能力	在 FastAPI 中会怎样复用
函数与装饰器	一个路径函数就是一个接口处理函数
类型提示	自动解析路径参数、查询参数和请求体
类与数据模型	用 Pydantic 定义请求和响应契约
异常处理	用 `HTTPException` 表达 HTTP 错误
模块拆分	用 `APIRouter` 管理多组接口
测试习惯	用 `TestClient` 写接口级单元测试

一、FastAPI 解决的核心问题

FastAPI 的价值不是“少写几行 Flask 代码”，而是把现代 API 后端中高频出现的一组能力整合在一起：

基于类型提示的参数解析；
基于 Pydantic 的请求体和响应体校验；
自动生成 OpenAPI、Swagger UI 和 ReDoc；
支持同步函数和异步函数；
通过依赖注入组织鉴权、数据库会话、配置读取等横切逻辑；
基于 ASGI，天然适合高并发 I/O 场景。

一次请求进入 FastAPI 后，通常会经过这样的链路：

Uvicorn 这类 ASGI Server 接收 HTTP 请求；
FastAPI 根据 method 和 path 找到路径函数；
解析 path、query、header、cookie、body 等输入；
用 Pydantic 做类型转换和约束校验；
执行业务函数；
根据 response_model 输出稳定 JSON 结构；
同步更新 OpenAPI 文档。

也就是说，FastAPI 希望你把“接口契约”尽量写进 Python 类型和模型里，而不是散落在注释、Wiki 和前端口头约定中。

二、环境准备

截至本文写作时，FastAPI 官方文档推荐安装标准依赖包：

`1`	`pip install "fastapi[standard]"`

建议从一个干净虚拟环境开始：

mkdir fastapi-shop
cd fastapi-shop

python -m venv .venv

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

pip install "fastapi[standard]"

其中 fastapi[standard] 会带上常用运行和开发能力，比如 ASGI Server、交互式文档相关依赖等。如果你在生产项目中追求更小依赖面，也可以研究 fastapi-slim，但入门和多数业务项目建议先用标准安装。

三、第一个可运行 API

先写一个单文件版本，文件名为 main.py：

from typing import Annotated
from uuid import UUID, uuid4

from fastapi import Depends, FastAPI, Header, HTTPException, Query, status
from pydantic import BaseModel, Field


app = FastAPI(
    title="FastAPI Shop",
    version="0.1.0",
    description="A tiny shop API built with FastAPI.",
)


class ItemCreate(BaseModel):
    name: str = Field(..., min_length=1, max_length=80, examples=["Keyboard"])
    price: float = Field(..., gt=0, examples=[299.0])
    tags: list[str] = Field(default_factory=list, max_length=10)


class ItemUpdate(BaseModel):
    name: str | None = Field(default=None, min_length=1, max_length=80)
    price: float | None = Field(default=None, gt=0)
    tags: list[str] | None = Field(default=None, max_length=10)


class ItemRead(BaseModel):
    id: UUID
    name: str
    price: float
    tags: list[str]


items: dict[UUID, ItemRead] = {}


def require_token(
    x_token: Annotated[str | None, Header(alias="X-Token")] = None,
) -> str:
    if x_token != "dev-token":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid token",
        )
    return x_token


@app.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok"}


@app.get("/items", response_model=list[ItemRead])
def list_items(
    token: Annotated[str, Depends(require_token)],
    q: Annotated[str | None, Query(min_length=1, max_length=30)] = None,
) -> list[ItemRead]:
    result = list(items.values())

    if q is None:
        return result

    keyword = q.lower()
    return [item for item in result if keyword in item.name.lower()]


@app.post("/items", response_model=ItemRead, status_code=status.HTTP_201_CREATED)
def create_item(
    data: ItemCreate,
    token: Annotated[str, Depends(require_token)],
) -> ItemRead:
    item = ItemRead(id=uuid4(), **data.model_dump())
    items[item.id] = item
    return item


@app.get("/items/{item_id}", response_model=ItemRead)
def read_item(
    item_id: UUID,
    token: Annotated[str, Depends(require_token)],
) -> ItemRead:
    try:
        return items[item_id]
    except KeyError:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found",
        )


@app.patch("/items/{item_id}", response_model=ItemRead)
def update_item(
    item_id: UUID,
    data: ItemUpdate,
    token: Annotated[str, Depends(require_token)],
) -> ItemRead:
    item = read_item(item_id, token)
    updates = data.model_dump(exclude_unset=True)
    updates = {key: value for key, value in updates.items() if value is not None}
    updated = item.model_copy(update=updates)
    items[item_id] = updated
    return updated


@app.delete("/items/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_item(
    item_id: UUID,
    token: Annotated[str, Depends(require_token)],
) -> None:
    if item_id not in items:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found",
        )
    del items[item_id]

启动开发服务器：

`1`	`fastapi dev main.py`

如果你的环境没有 FastAPI CLI，也可以用 Uvicorn：

`1`	`uvicorn main:app --reload`

打开：

http://127.0.0.1:8000/health
http://127.0.0.1:8000/docs
http://127.0.0.1:8000/redoc
http://127.0.0.1:8000/openapi.json

试着创建一个商品：

curl -X POST "http://127.0.0.1:8000/items" \
  -H "Content-Type: application/json" \
  -H "X-Token: dev-token" \
  -d '{"name":"Keyboard","price":299,"tags":["peripheral"]}'

如果你把 price 改成负数，FastAPI 会直接返回 422 Unprocessable Entity，并告诉你哪个字段不符合约束。你不需要在业务函数里手写一堆 if price <= 0。

四、类型提示如何变成接口契约

FastAPI 里有三类输入最常见：

输入位置	示例	FastAPI 如何识别
路径参数	`/items/{item_id}`	函数参数名与路径模板一致
查询参数	`/items?q=key`	函数参数不在路径里，且不是 Pydantic body
请求体	JSON body	参数类型继承自 `BaseModel`

例如：

@app.get("/items/{item_id}")
def read_item(
    item_id: UUID,
    q: Annotated[str | None, Query(min_length=1)] = None,
) -> dict[str, str]:
    return {"item_id": str(item_id), "q": q or ""}

这里 item_id: UUID 会让 FastAPI 自动把字符串转换为 UUID 对象；如果传入的路径不是合法 UUID，请求会在进入函数前失败。

Annotated 的好处是把“类型”和“接口约束”分开：

`1`	`q: Annotated[str \| None, Query(min_length=1, max_length=30)] = None`

读作：q 的业务类型是 str | None，同时它作为查询参数时必须满足长度约束。这样写比把校验逻辑塞进函数体更清晰，也能同步生成文档。

五、Pydantic：把边界数据变可信

Pydantic 是 FastAPI 的数据契约核心。请求进入系统时，外部世界给你的都是“不可信字符串或 JSON”；经过 Pydantic 模型之后，业务函数拿到的是已经转换和校验过的 Python 对象。

请求模型和响应模型建议分开写：

class UserCreate(BaseModel):
    email: str
    password: str


class UserRead(BaseModel):
    id: UUID
    email: str

这样做有两个直接收益：

password 可以出现在创建请求里，但不会从响应里泄漏出去；
数据库模型、请求模型、响应模型不再互相污染。

response_model 还有一个经常被低估的价值：它能过滤掉你不想暴露的字段。

@app.post("/users", response_model=UserRead)
def create_user(data: UserCreate) -> dict[str, object]:
    return {
        "id": uuid4(),
        "email": data.email,
        "password_hash": "internal-only",
    }

即使函数返回值里有 password_hash，最终响应也只会保留 UserRead 声明的字段。对于 API 稳定性和安全边界，这一点很重要。

六、依赖注入：把横切逻辑拿出接口函数

开发业务 API 时，很多逻辑并不属于某一个接口：

读取当前登录用户；
校验 Token；
创建数据库 Session；
读取配置；
记录审计日志；
检查权限。

FastAPI 用 Depends 处理这类逻辑。前面的 require_token 就是一个最小例子：

def require_token(
    x_token: Annotated[str | None, Header(alias="X-Token")] = None,
) -> str:
    if x_token != "dev-token":
        raise HTTPException(status_code=401, detail="Invalid token")
    return x_token

在接口中声明依赖：

1
2
3

@app.get("/items")
def list_items(token: Annotated[str, Depends(require_token)]) -> list[ItemRead]:
    return list(items.values())

这样接口函数会在执行前先运行 require_token。如果依赖抛出异常，业务函数不会继续执行。

依赖也可以继续依赖其他依赖：

def get_settings() -> Settings:
    return Settings()


def get_repository(
    settings: Annotated[Settings, Depends(get_settings)],
) -> ItemRepository:
    return ItemRepository(settings.database_url)

这种组合方式让 FastAPI 项目很适合做“薄接口层 + 明确业务层”的结构。

七、项目变大后怎么拆

单文件很适合入门，但真实项目通常会快速长出用户、订单、支付、后台管理、文件上传等资源。推荐按职责拆分，而不是按“今天写了哪个接口”随手堆文件。

一个常见结构是：

fastapi-shop/
├── app/
│   ├── main.py
│   ├── api/
│   │   └── routers/
│   │       ├── items.py
│   │       └── users.py
│   ├── core/
│   │   └── config.py
│   ├── schemas.py
│   ├── models.py
│   ├── services.py
│   └── db.py
├── tests/
│   └── test_items.py
└── requirements.txt

app/api/routers/items.py 可以这样写：

from typing import Annotated
from uuid import UUID

from fastapi import APIRouter, Depends

from app.schemas import ItemCreate, ItemRead
from app.services import ItemService, get_item_service


router = APIRouter(prefix="/items", tags=["items"])


@router.post("", response_model=ItemRead, status_code=201)
def create_item(
    data: ItemCreate,
    service: Annotated[ItemService, Depends(get_item_service)],
) -> ItemRead:
    return service.create(data)


@router.get("/{item_id}", response_model=ItemRead)
def read_item(
    item_id: UUID,
    service: Annotated[ItemService, Depends(get_item_service)],
) -> ItemRead:
    return service.get(item_id)

app/main.py 只负责组装：

from fastapi import FastAPI

from app.api.routers import items


app = FastAPI(title="FastAPI Shop")
app.include_router(items.router)

这里有一个判断标准：如果路由函数开始出现复杂分支、数据库查询细节、外部 API 调用和权限规则，说明它已经不只是“HTTP 编排”了，应该把逻辑移到 service 或 repository 层。

八、`async def` 不等于自动更快

FastAPI 支持两种路径函数：

@app.get("/sync")
def sync_handler() -> dict[str, str]:
    return {"mode": "sync"}


@app.get("/async")
async def async_handler() -> dict[str, str]:
    return {"mode": "async"}

什么时候用 async def？先看函数内部在做什么。

可以用这张表快速判断：

场景	建议
调用 async 数据库驱动，如 async SQLAlchemy、asyncpg	用 `async def`
调用 async HTTP 客户端，如 httpx.AsyncClient	用 `async def`
调用普通同步库，如 requests、同步数据库驱动	用 `def`，或放到线程池/任务队列
做大量 CPU 计算，如图像处理、模型推理	不要指望 `async` 提速，考虑进程池或后台任务
不确定库是否异步	先按同步写，确认后再改

最常见的坑是：写了 async def，但函数内部直接调用 requests.get() 或同步数据库驱动。这会阻塞事件循环，让其他请求也跟着等待。

如果需要在接口中调用外部 HTTP 服务，可以这样：

import httpx


@app.get("/exchange-rate")
async def get_exchange_rate() -> dict[str, float]:
    async with httpx.AsyncClient(timeout=5) as client:
        response = await client.get("https://api.example.com/rate")
        response.raise_for_status()
    return response.json()

注意：异步不是语法装饰，它是一种 I/O 调度模型。只有你的数据库、HTTP 客户端、缓存客户端等调用链也支持 async，收益才会明显。

九、错误处理与状态码

HTTP API 不应该只返回 200，然后把错误塞进 JSON 里的 code 字段。状态码本身就是协议的一部分。

常用状态码可以这样理解：

状态码	适用场景
`200 OK`	查询、更新成功并返回内容
`201 Created`	创建资源成功
`204 No Content`	删除成功且不返回 body
`400 Bad Request`	请求语义不合法
`401 Unauthorized`	没有有效身份凭证
`403 Forbidden`	已登录但没有权限
`404 Not Found`	资源不存在
`409 Conflict`	资源状态冲突，如重复创建
`422 Unprocessable Entity`	参数类型或字段约束不通过

FastAPI 中可以用 HTTPException 表达业务错误：

from fastapi import HTTPException, status


def get_item_or_404(item_id: UUID) -> ItemRead:
    item = items.get(item_id)
    if item is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found",
        )
    return item

如果项目中错误结构需要统一，比如都返回 {"code": "...", "message": "..."}，可以再引入全局异常处理器。但在入门阶段，先把正确状态码用好，比过早设计复杂错误体系更重要。

十、测试：用接口行为保护重构

FastAPI 提供 TestClient，可以像调用普通 HTTP 接口一样测试你的应用。

安装测试依赖：

`1`	`pip install pytest`

tests/test_items.py：

from fastapi.testclient import TestClient

from main import app


client = TestClient(app)


def test_create_item() -> None:
    response = client.post(
        "/items",
        headers={"X-Token": "dev-token"},
        json={"name": "Mouse", "price": 99.0, "tags": ["peripheral"]},
    )

    assert response.status_code == 201
    body = response.json()
    assert body["name"] == "Mouse"
    assert body["price"] == 99.0
    assert "id" in body


def test_reject_invalid_price() -> None:
    response = client.post(
        "/items",
        headers={"X-Token": "dev-token"},
        json={"name": "Mouse", "price": -1},
    )

    assert response.status_code == 422


def test_reject_missing_token() -> None:
    response = client.get("/items")

    assert response.status_code == 401

运行：

pytest

接口测试的重点不是追求行覆盖率，而是锁住 API 行为：状态码、响应字段、错误场景和鉴权路径。只要这些行为被测试保护，后面把内存字典替换成数据库时就安心很多。

十一、部署前需要想清楚的事

本地开发时可以用：

`1`	`fastapi dev main.py`

生产环境不要直接用开发命令。你可以使用 FastAPI CLI 的生产命令：

`1`	`fastapi run app/main.py --host 0.0.0.0 --port 8000`

也可以显式使用 Uvicorn：

`1`	`uvicorn app.main:app --host 0.0.0.0 --port 8000`

一个最小 Dockerfile 可以长这样：

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app ./app

EXPOSE 8000
CMD ["fastapi", "run", "app/main.py", "--host", "0.0.0.0", "--port", "8000"]

生产环境至少要补齐这些点：

项目	为什么重要
固定依赖版本	避免一次重新构建引入不可预期变更
环境变量管理	数据库地址、密钥、第三方 Token 不要写死在代码里
健康检查	让负载均衡和容器平台知道服务是否可用
结构化日志	方便按 request_id、user_id、status_code 排查问题
数据库迁移	用 Alembic 等工具管理 schema 变化
超时与重试	防止外部服务拖垮自己的接口
限流与鉴权	公开 API 必须考虑滥用和越权
HTTPS 与反向代理	生产入口通常交给 Nginx、Traefik、云负载均衡等

十二、常见坑

坑	更稳的做法
把所有代码写进 `main.py`	入门可以，变大后用 `APIRouter`、service、db 分层
路由函数里写大量业务分支	路由层只处理 HTTP，业务规则移到 service
不写 `response_model`	为公开 API 写响应模型，保护字段边界
`async def` 里调用同步阻塞库	同步库用 `def`，异步链路才用 `async def`
返回 `200` 表示所有结果	正确使用 `201`、`204`、`401`、`404`、`409`、`422`
把密钥写进代码	用环境变量或 Secret 管理
不写测试就接数据库	先用行为测试保护接口，再替换持久化实现

十三、学习路线

到这里，你已经掌握了 FastAPI 最重要的主干。接下来可以按这个顺序继续：

SQLAlchemy 2.x 或 SQLModel：把内存字典换成数据库；
Alembic：管理数据库迁移；
OAuth2 / JWT：实现真实登录鉴权；
BackgroundTasks / Celery / RQ：处理慢任务；
中间件：统一日志、request_id、CORS、耗时统计；
OpenTelemetry：接入链路追踪；
Docker Compose / Kubernetes：把 API、数据库、缓存组成可部署系统。

FastAPI 的学习曲线很友好，但它不是“玩具框架”。当你把类型契约、依赖注入、测试和部署纪律一起用起来，它完全可以支撑严肃的生产 API。

参考资料

Gin Tutorial

Sun, 12 Apr 2026 13:32:51 +0800

前言

欢迎来到 Gin 框架的零基础教程！无论你是刚接触 Go 语言的新手，还是想要快速上手 Web 开发的开发者，这篇教程都会带你从零开始，一步步掌握 Go 语言中最流行的轻量级 Web 框架 ——Gin。

什么是 Gin？

Gin 是一个用 Go (Golang) 编写的高性能 HTTP Web 框架。它提供了类似 Express.js 的简洁 API，同时凭借其基于 Radix 树的路由算法，实现了极致的性能，速度比标准的 net/http 库快了多达 40 倍。

为什么选择 Gin？

🚀 极致性能：零分配路由，内存占用极低，支持高并发
📦 轻量简洁：核心代码精简，无冗余依赖，上手成本低
🔌 丰富中间件：内置日志、恢复、CORS 等中间件，支持自定义扩展
✅ 参数校验：自动绑定并验证请求参数，减少重复代码
🎯 路由分组：灵活的路由组织方式，支持 API 版本管理
🛡️ panic 恢复：内置异常捕获，防止单个请求崩溃导致整个服务挂掉

前置知识

在开始之前，你只需要：

了解基本的计算机操作（会用终端 / 命令行）
了解 Go 语言的基础语法（变量、函数、结构体等）
了解基本的 HTTP 协议概念（请求、响应、GET/POST 方法等）

第一章：环境准备与安装

1.1 安装 Go 语言环境

Gin 框架依赖 Go 语言环境，首先我们需要安装 Go。

1.1.1 下载 Go 安装包

访问 Go 官方下载页面：https://go.dev/dl/

根据你的操作系统选择对应的安装包：

Windows：选择 go1.2X.X.windows-amd64.msi（推荐 64 位）
MacOS：选择 go1.2X.X.darwin-amd64.pkg（Intel 芯片）或 go1.2X.X.darwin-arm64.pkg（M1/M2 芯片）
Linux：选择 go1.2X.X.linux-amd64.tar.gz

💡 提示：Gin v1.10+ 要求 Go 版本至少为 1.25，建议安装最新的稳定版。

1.1.2 安装 Go

Windows 用户：

双击下载的 go.msi 文件，一路点击 Next 即可。安装程序会自动配置环境变量，无需手动设置。

MacOS 用户：

双击下载的 .pkg 文件，按照提示完成安装。同样会自动配置环境变量。

Linux 用户：

# 解压到 /usr/local 目录
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.25.0.linux-amd64.tar.gz

# 配置环境变量，编辑 ~/.bashrc 或 ~/.zshrc
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

1.1.3 验证安装

打开终端，输入以下命令验证是否安装成功：

`1`	`go version`

如果输出类似下面的内容，说明安装成功：

`1`	`go version go1.25.0 linux/amd64`

1.2 配置 Go 模块（Go Modules）

从 Go 1.11 开始，Go 引入了模块（Modules）来管理依赖，这是现在官方推荐的依赖管理方式，我们必须启用它。

💡 国内用户注意：由于网络原因，直接下载依赖可能会超时，我们先配置国内代理：

# 设置 GOPROXY 代理（七牛云镜像，国内访问速度快）
# Windows PowerShell
$env:GOPROXY = "https://goproxy.cn,direct"

# Windows CMD
set GOPROXY=https://goproxy.cn,direct

# Linux/Mac
export GOPROXY=https://goproxy.cn,direct

如果你想永久生效，可以把上面的命令添加到你的系统环境变量配置文件中。

1.3 安装 Gin 框架

现在我们来创建第一个 Gin 项目，并安装 Gin 框架。

1.3.1 创建项目目录

首先，创建一个项目文件夹，比如 my-gin-app：

# 创建项目目录
mkdir my-gin-app

# 进入项目目录
cd my-gin-app

1.3.2 初始化 Go 模块

在项目目录下，初始化 Go 模块：

`1`	`go mod init my-gin-app`

这个命令会创建一个 go.mod 文件，用来管理你的项目依赖。执行成功后，你会看到输出：

1
2
3

go: creating new go.mod: module my-gin-app
go: to add module requirements and sums:
	go mod tidy

1.3.3 安装 Gin

执行以下命令安装 Gin 框架:

`1`	`go get -u github.com/gin-gonic/gin`

这个命令会：

下载 Gin 框架的最新版本
自动把依赖信息添加到 go.mod 文件中
生成 go.sum 文件，用来校验依赖的版本

等待命令执行完成，没有报错的话，Gin 就安装好了！

第二章：你的第一个 Gin 应用

2.1 编写 Hello World

现在我们来写第一个最简单的 Gin 程序，实现一个 ping 接口。

在项目根目录下，创建一个 main.go 文件，写入以下代码：

package main

// 导入必要的包
import (
	"net/http" // 标准库，用于 HTTP 状态码
	"github.com/gin-gonic/gin" // 导入 Gin 框架
)

func main() {
	// 1. 创建 Gin 引擎
	// gin.Default() 会创建一个默认的引擎，自带两个中间件：
	// - Logger：打印请求日志
	// - Recovery：捕获 panic，防止服务崩溃
	r := gin.Default()

	// 2. 定义路由
	// 当客户端用 GET 方法访问 /ping 路径时，执行后面的处理函数
	r.GET("/ping", func(c *gin.Context) {
		// c *gin.Context 是 Gin 的核心，它包含了请求和响应的所有信息

		// 3. 返回 JSON 响应
		// 第一个参数是 HTTP 状态码，http.StatusOK 就是 200
		// 第二个参数是响应数据，gin.H 是 map[string]interface{} 的快捷方式
		c.JSON(http.StatusOK, gin.H{
			"message": "pong",
			"status":  "success",
		})
	})

	// 4. 启动服务器
	// 默认监听 0.0.0.0:8080，你也可以指定端口，比如 r.Run(":9090")
	r.Run() 
}

2.2 运行程序

在终端中，执行以下命令运行程序：

`1`	`go run main.go`

如果一切正常，你会看到类似下面的输出：

[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:	export GIN_MODE=release
 - using code:	gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /ping                     --> main.main.func1 (3 handlers)
[GIN-debug] [WARNING] You trusted all proxies, this is NOT safe. We recommend you to set a value.
Please check https://pkg.go.dev/github.com/gin-gonic/gin#readme-don-t-trust-all-proxies for details.
[GIN-debug] Listening and serving HTTP on :8080

这说明你的 Gin 服务已经成功启动了，正在监听 8080 端口！

2.3 测试接口

现在打开你的浏览器，访问 http://localhost:8080/ping，或者用 curl.exe 命令测试：

`1`	`curl.exe http://localhost:8080/ping`

你会看到返回的 JSON 数据：

`1`	`{"message":"pong","status":"success"}`

🎉 恭喜！你已经成功运行了你的第一个 Gin 应用！

第三章：核心功能：路由管理

路由是 Web 框架的基础，它决定了如何响应客户端的请求。Gin 提供了非常强大灵活的路由功能。

3.1 基础路由

Gin 支持所有标准的 HTTP 方法：GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS 等。

package main

import (
	"net/http"

	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()

	// GET请求：获取资源
	r.GET("/users", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{"message": "获取用户列表"})
	})

	// POST请求：创建资源
	r.POST("/users", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{"message": "创建新用户"})
	})

	// PUT请求：更新资源（完整更新）
	r.PUT("/users/:id", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{"message": "更新用户信息"})
	})

	// DELETE请求：删除资源
	r.DELETE("/users/:id", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{"message": "删除用户"})
	})

	// Any：匹配所有请求方法
	r.Any("/test", func(c *gin.Context) {
		c.String(http.StatusOK, "支持所有请求方法：%s", c.Request.Method)
	})

	r.Run()
}

可以用 Postman 或者 curl.exe 来测试这些接口：

curl.exe -X GET http://localhost:8080/users
curl.exe -X POST http://localhost:8080/users
curl.exe -X PUT http://localhost:8080/users/123
curl.exe -X DELETE http://localhost:8080/users/123
curl.exe -X PATCH http://localhost:8080/users/123
curl.exe -X OPTIONS http://localhost:8080/test

3.2 路径参数（Route Parameters）

有时候我们需要从 URL 路径中获取动态参数，比如用户 ID、文章 ID 等。Gin 支持用 :param 的方式定义动态参数。

package main

import (
	"net/http"

	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()

	r.GET("/users/:id", func(c *gin.Context) {
		// 使用 c.Param() 获取路径参数
		userID := c.Param("id")

		c.JSON(http.StatusOK, gin.H{
			"user_id": userID,
		})
	})

	// 多个参数
	r.GET("/articles/:category/:article_id", func(c *gin.Context) {
		category := c.Param("category")
		articleID := c.Param("article_id")

		c.JSON(http.StatusOK, gin.H{
			"category":  category,
			"articleID": articleID,
		})
	})

	r.Run()
}

测试一下：

curl.exe http://localhost:8080/users/123
# 输出：{"user_id":"123"}

curl.exe http://localhost:8080/articles/tech/456
# 输出：{"article_id":"456","category":"tech"}

3.3 查询参数（Query Parameters）

查询参数是 URL 中 ? 后面的键值对，比如 /search?query=gin&page=1。

r.GET("/search", func(c *gin.Context) {
	// 获取查询参数，如果参数不存在，返回空字符串
	query := c.Query("query")
	
	// 获取查询参数，带默认值，如果参数不存在，返回默认值
	page := c.DefaultQuery("page", "1")
	limit := c.DefaultQuery("limit", "10")
	
	c.JSON(http.StatusOK, gin.H{
		"query": query,
		"page":  page,
		"limit": limit,
	})
})

测试一下：

1
2

curl.exe "http://localhost:8080/search?query=golang&page=2"
# 输出：{"limit":"10","page":"2","query":"golang"}

3.4 路由分组（Route Grouping）

当你的 API 越来越多的时候，你需要对路由进行分类管理。比如 API 版本、模块划分。Gin 的路由分组可以帮你轻松实现这一点。

package main

import (
	"net/http"

	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()

	// 创建 v1 版本的 API 分组
	v1 := r.Group("/api/v1")
	{
		// 实际路径是 /api/v1/users
		v1.GET("/users", func(c *gin.Context) {
			c.JSON(http.StatusOK, gin.H{"message": "v1 用户列表"})
		})

		// 实际路径是 /api/v1/users/:id
		v1.GET("users/:id", func(c *gin.Context) {
			c.JSON(http.StatusOK, gin.H{"message": "v1 用户详情"})
		})
	}

	// 创建 v2 版本的 API 分组
	v2 := r.Group("/api/v2")
	{
		// 实际路径是 /api/v2/users
		v2.GET("/users", func(c *gin.Context) {
			c.JSON(http.StatusOK, gin.H{"message": "v2 用户列表"})
		})

		// 实际路径是 /api/v2/users/:id
		v2.GET("users/:id", func(c *gin.Context) {
			c.JSON(http.StatusOK, gin.H{"message": "v2 用户详情"})
		})
	}

	// 嵌套分组：比如 /api/v1/admin
	admin := v1.Group("/admin")
	{
		admin.GET("/dashboard", func(c *gin.Context) {
			c.JSON(http.StatusOK, gin.H{"message": "管理员面板"})
		})
	}

	r.Run()
}

路由分组的好处是：

代码结构更清晰，便于维护
可以给整个分组统一应用中间件（后面会讲）
支持无限嵌套，满足复杂的路由组织需求

3.5 404 处理

当用户访问不存在的路由时，Gin 默认会返回 404 页面。我们可以自定义 404 的处理：

package main

import (
	"net/http"

	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()

	r.NoRoute(func(c *gin.Context) {
		c.JSON(http.StatusNotFound, gin.H{
			"code":    404,
			"message": "接口被陈导偷走了，去问问陈导吧",
		})
	})

	r.Run()
}

第四章：请求处理与参数绑定

处理客户端发来的请求数据是后端开发的核心任务。Gin 提供了非常便捷的参数绑定和验证功能。

4.1 获取表单数据

处理 HTML 表单提交（application/x-www-form-urlencoded）：

package main

import (
	"net/http"

	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()

	r.POST("/login", func(c *gin.Context) {
		// 获取表单数据
		username := c.PostForm("username")
		password := c.DefaultPostForm("password", "123456")

		c.JSON(http.StatusOK, gin.H{
			"username": username,
			"password": password,
		})
	})

	r.Run()
}

测试：

1
2

curl.exe -X POST http://localhost:8080/login -d "username=test&password=123"
# 输出：{"password":"123","username":"test"}

4.2 JSON 参数绑定

现代 API 开发最常用的就是 JSON 格式的请求体。Gin 可以自动把 JSON 请求体绑定到 Go 的结构体上，还能自动校验参数！

首先，我们定义一个结构体，用来接收请求参数：

package main

import (
	"net/http"

	"github.com/gin-gonic/gin"
)

// 定义注册请求的结构体
type RegisterRequest struct {
	// json:"username"	表示 JSON 中的字段名
	// binding:"required"	表示这个字段是必填的
	Username string `json:"username" binding:"required"`
	Password string `json:"password" binding:"required,min=6"` // 密码至少6位
	Email    string `json:"email" binding:"required,email"`    // 必须是邮箱格式
	Age      int    `json:"age" binding:"gte=18,lte=60"`       // 年龄必须在18-60之间
}

func main() {
	r := gin.Default()

	// 然后在处理函数中绑定参数：
	r.POST("/register", func(c *gin.Context) {
		var req RegisterRequest

		// ShouldBindJSON 会自动解析JSON请求体，绑定到结构体，并执行校验
		if err := c.ShouldBindJSON(&req); err != nil {
			// 如果绑定或校验失败，返回400错误
			c.JSON(http.StatusBadRequest, gin.H{
				"error": err.Error(),
			})
			return
		}

		// 绑定成功
		c.JSON(http.StatusOK, gin.H{
			"message": "注册成功",
			"data":    req,
		})
	})

	r.Run()
}

测试一下：

# 正确的请求
curl.exe -X POST http://localhost:8080/register -H "Content-Type: application/json" -d '{\"username\":\"test\",\"password\":\"123456\",\"email\":\"test@example.com\",\"age\":20}'

# 输出：{"data":{"username":"test","password":"123456","email":"test@example.com","age":20},"message":"注册成功"}

-X POST 表示使用 POST 方法
-H “Content-Type: application/json” 表示请求体是 JSON 格式
-d 后面是 JSON 数据。

# 错误的请求（年龄太小）
curl.exe -X POST http://localhost:8080/register -H "Content-Type: application/json" -d '{\"username\":\"test\",\"password\":\"123456\",\"email\":\"test@example.com\",\"age\":10}' 

# 输出：{"error":"Key: 'RegisterRequest.Age' Error:Field validation for 'Age' failed on the 'gte' tag"}

💡 常用的 binding 校验规则：

required：必填

email：邮箱格式

min=6：最小值（数字）/ 最小长度（字符串）

max=60：最大值

gte=18：大于等于

lte=60：小于等于

oneof=male female：必须是其中一个值

4.3 Query 参数绑定

除了 JSON，我们也可以把 URL 的查询参数绑定到结构体：

package main

import (
	"net/http"

	"github.com/gin-gonic/gin"
)

type UserQuery struct {
	Name string `form:"name" binding:"required"`
	Age  int    `form:"age" binding:"min=18"`
}

func main() {
	r := gin.Default()

	r.GET("/users", func(c *gin.Context) {
		var query UserQuery
		if err := c.ShouldBindQuery(&query); err != nil {
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}

		c.JSON(http.StatusOK, gin.H{"query": query})
	})

	r.Run()
}

测试：

1
2

curl.exe "http://localhost:8080/users?name=Alice&age=25"
# 输出：{"query":{"Name":"Alice","Age":25}}

4.4 文件上传

Gin 也支持文件上传，非常简单：

package main

import (
	"log"
	"net/http"
	"os"

	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()

	r.POST("/upload", func(c *gin.Context) {
		// 获取上传的文件，参数是表单的name
        // c.FormFile() 会返回一个 *multipart.FileHeader 类型的对象，包含了文件的基本信息,参数是表单的 name 属性值
		file, err := c.FormFile("file")
		if err != nil {
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}

		// 打印文件信息
		log.Printf("上传文件名: %s, 文件大小: %d KB", file.Filename, file.Size/1024)

		// 文件保存到本地
		dst := "./uploads/" + file.Filename
		// 确保 upload 目录存在。os.ModePerm 是 0777，表示所有用户都有读写执行权限，系统会根据 umask 自动调整权限。
		if err := os.MkdirAll("./uploads", os.ModePerm); err != nil {
			c.JSON(http.StatusInternalServerError, gin.H{"error": "目录创建失败"})
		}

		if err := c.SaveUploadedFile(file, dst); err != nil {
			c.JSON(http.StatusInternalServerError, gin.H{"error": "文件保存失败"})
			return
		}

		c.JSON(http.StatusOK, gin.H{
			"message":  "上传成功",
			"filename": file.Filename,
		})
	})

	r.Run()
}

测试：

`1`	`curl.exe -X POST http://localhost:8080/upload -F "file=@这是个测试文件.txt"`

第五章：响应处理

Gin 支持多种格式的响应，满足不同的场景需求。

5.1 JSON 响应（最常用）

这是 API 开发最常用的响应格式，我们之前已经用过很多次了：

c.JSON(http.StatusOK, gin.H{
	"code":    200,
	"message": "success",
	"data":    data,
})

5.2 字符串响应

简单的文本响应：

package main

import (
	"net/http"

	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()

	r.GET("/hello", func(c *gin.Context) {
		name := c.DefaultQuery("name", "Guest")
		c.String(http.StatusOK, "Hello, %s!", name)
	})

	r.Run()
}

测试：

`1`	`curl.exe "http://localhost:8080/hello"`

5.3 HTML 模板渲染

如果你需要服务端渲染 HTML 页面，Gin 也支持 HTML 模板：

首先，创建 templates 目录，然后创建 index.html 文件：

<!DOCTYPE html>
<html>
<head>
    {{.title}}
</head>
<body>
    <h1>{{.message}}</h1>
    <p>欢迎你，{{.name}}</p>
</body>
</html>

然后在 Gin 中加载模板：

package main

import (
	"net/http"

	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()

	// 加载 templates 目录下的所有 html 文件
	r.LoadHTMLGlob("templates/*")

	r.GET("/index", func(c *gin.Context) {
		// 渲染模板，传递参数
		c.HTML(http.StatusOK, "index.html", gin.H{
			"title":   "我的主页",
			"message": "欢迎来到 Gin 的世界！",
			"name":    "Gopher",
		})
	})

	r.Run()
}

测试：

`1`	`curl.exe http://localhost:8080/index`

也可以在浏览器中访问 http://localhost:8080/index，你会看到渲染后的 HTML 页面。

5.4 静态文件服务

当你有静态资源（比如 CSS、JS、图片，或者前端打包后的文件），可以用 Gin 快速托管：

// 把 /static 路径映射到本地的 ./static 目录
r.Static("/static", "./static")

// 比如你有 ./static/logo.png，就可以通过 http://localhost:8080/static/logo.png 访问

如果是前后端分离的项目，前端打包后的 dist 目录可以这样托管：

`1`	`r.Static("/", "./dist")`

5.5 文件下载

package main

import "github.com/gin-gonic/gin"

func main() {
	r := gin.Default()

	r.GET("/download", func(c *gin.Context) {
		// 直接返回文件给客户端下载
		c.File("./test.txt")
	})

	r.Run()
}

5.6 重定向

package main

import (
	"net/http"

	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()

	r.GET("/old", func(c *gin.Context) {
		// 301 永久重定向（不推荐）
		// c.Redirect(http.StatusMovedPermanently, "https://symphonyw.github.io/")

		// 302 临时重定向（默认）
		c.Redirect(http.StatusFound, "https://symphonyw.github.io/")

		// 307 临时重定向，保持请求方法不变（推荐）
		c.Redirect(http.StatusTemporaryRedirect, "https://symphonyw.github.io/")
	})

	r.Run()
}

测试：

`1`	`curl.exe -I http://localhost:8080/old`

或者直接在浏览器中访问 http://localhost:8080/old，你会被重定向到我的博客主页。

第六章：中间件（Middleware）

中间件是 Gin 中非常强大的特性，它可以在请求到达处理函数之前或之后执行一些通用的逻辑。比如日志记录、身份认证、跨域处理、权限校验等。

6.1 中间件的工作原理

中间件本质上就是一个拦截器，请求会先经过中间件，然后才到你的业务处理函数，处理完之后，响应还会再经过中间件。

你可以把它想象成安检：乘客（请求）先过安检（中间件），然后才能进去坐飞机（业务处理），出来的时候还要再过安检。

6.2 默认中间件

还记得我们之前用的 gin.Default() 吗？它默认就帮我们加了两个中间件：

gin.Logger()：打印请求日志，比如请求方法、路径、耗时、状态码等
gin.Recovery()：捕获 panic，防止因为一个请求的错误导致整个服务崩溃

如果你想要一个完全干净的引擎，没有任何中间件，可以用 gin.New()：

r := gin.New()
// 然后你可以手动添加你需要的中间件
r.Use(gin.Logger())
r.Use(gin.Recovery())

6.3 自定义中间件

我们来写一个自定义的日志中间件，看看中间件是怎么工作的：

// 自定义日志中间件
func LoggerMiddleware() gin.HandlerFunc {
	// 返回一个 gin.HandlerFunc 类型的函数
	return func(c *gin.Context) {
		// 请求处理之前执行的逻辑
		startTime := time.Now()

		// 调用下一个处理函数（可能是下一个中间件，也可能是最终的业务处理函数）
		c.Next()

		// 请求处理之后执行的逻辑
		endTime := time.Now()
		latency := endTime.Sub(startTime) // 计算耗时

		// 获取请求信息
		method := c.Request.Method
		path := c.Request.URL.Path
		statusCode := c.Writer.Status() // 响应状态码
		clientIP := c.ClientIP()       // 客户端 IP

		// 打印日志
		log.Printf("[%s] %s | %d | %s | %v", method, path, statusCode, clientIP, latency)
	}
}

然后我们就可以使用这个中间件了：

func main() {
	r := gin.Default()
	
	// 全局使用：对所有路由生效
	r.Use(LoggerMiddleware())

	// ... 定义路由 ...
}

6.4 中间件的作用范围

中间件可以作用在不同的范围：

全局中间件：对所有路由生效，用 r.Use()
分组中间件：只对某个路由分组生效，用 group.Use()
单个路由中间件：只对某个特定的路由生效，直接在路由定义时添加中间件参数

// 认证中间件示例
func AuthMiddleware() gin.HandlerFunc {
	return func(c *gin.Context) {
		// 从请求头获取 Token
		token := c.GetHeader("Authorization")
		
		// 简单的验证（实际项目中要验证 JWT）
		if token != "Bearer my-secret-token" {
			// 验证失败，终止请求链，返回 401
			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{
				"error": "未授权访问，请先登录",
			})
			return
		}

		// 验证通过，把用户信息存到 Context 中，供后续处理函数使用
		c.Set("userID", 123)
		c.Set("username", "test")

		// 继续处理请求
		c.Next()
	}
}

func main() {
	r := gin.Default()

	// 1. 全局中间件
	r.Use(LoggerMiddleware())

	// 公开路由，不需要认证
	r.POST("/login", loginHandler)

	// 2. 分组中间件：需要认证的接口
	authGroup := r.Group("/api")
	authGroup.Use(AuthMiddleware()) // 这个分组下的所有路由都需要认证
	{
		authGroup.GET("/profile", profileHandler)
		authGroup.POST("/update", updateHandler)
	}

	// 3. 单个路由中间件
	r.GET("/special", AuthMiddleware(), specialHandler)

	r.Run()
}

💡 关键方法说明：

c.Next()：调用下一个处理函数，继续执行链

c.Abort()：终止执行链，后面的处理函数不会再执行

c.Set(key, value) / c.Get(key)：在中间件和处理函数之间传递数据

6.5 常用社区中间件：解决跨域问题

开发前后端分离项目的时候，最常见的问题就是跨域（CORS）。

什么是跨域？当你的前端页面和后端 API 不在同一个域名、协议或端口下时，浏览器会出于安全考虑阻止前端访问后端接口，这就是跨域问题。

我们可以用 gin-contrib/cors 这个官方的中间件来解决。

首先安装：

`1`	`go get github.com/gin-contrib/cors`

然后使用：

import "github.com/gin-contrib/cors"

func main() {
	r := gin.Default()

	// 配置 CORS 中间件
	r.Use(cors.New(cors.Config{
		// 允许的来源，比如前端的域名
		AllowOrigins:     []string{"http://localhost:3000", "https://your-frontend.com"},
		// 允许的请求方法
		AllowMethods:     []string{"GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"},
		// 允许的请求头
		AllowHeaders:     []string{"Origin", "Content-Type", "Authorization"},
		// 是否允许携带 Cookie
		AllowCredentials: true,
		// 预检请求的缓存时间
		MaxAge:           12 * time.Hour,
	}))

	// 如果你是开发环境，想快速测试，可以用默认配置（允许所有来源，不推荐生产环境）
	// r.Use(cors.Default())

	// ... 路由 ...
}

这样就完美解决了跨域问题！

第七章：配置管理

在实际项目中，我们不会把配置（比如数据库地址、端口、密钥）硬编码在代码里，而是用配置文件来管理。最常用的就是 Viper 库。

7.1 安装 Viper

`1`	`go get github.com/spf13/viper`

7.2 编写配置文件

在项目根目录创建 config.yaml 文件：

# 服务配置
server:
  port: 8080
  mode: debug # debug/release

# 数据库配置
database:
  host: localhost
  port: 3306
  user: root
  password: 123456
  dbname: myapp

# JWT 配置
jwt:
  secret: my-secret-key
  expire: 24 # 过期时间，小时

7.3 读取配置

创建 config/config.go：

package config

import (
	"log"

	"github.com/spf13/viper"
)

// 定义配置结构体
type Config struct {
	Server   ServerConfig
	Database DatabaseConfig
	JWT      JWTConfig
}

type ServerConfig struct {
	Port int
	Mode string
}

type DatabaseConfig struct {
	Host     string
	Port     int
	User     string
	Password string
	DBName   string
}

type JWTConfig struct {
	Secret string
	Expire int
}

var GlobalConfig Config

// 加载配置
func InitConfig() {
	// 设置配置文件名（不带后缀）
	viper.SetConfigName("config")
	// 设置配置文件路径
	viper.AddConfigPath(".")
	// 设置配置文件类型
	viper.SetConfigType("yaml")

	// 读取配置文件
	if err := viper.ReadInConfig(); err != nil {
		log.Fatalf("读取配置文件失败: %v", err)
	}

	// 把配置反序列化到结构体
	if err := viper.Unmarshal(&GlobalConfig); err != nil {
		log.Fatalf("解析配置失败: %v", err)
	}

	log.Println("配置加载成功")
}

然后在 main.go 中初始化：

func main() {
	// 加载配置
	config.InitConfig()

	r := gin.Default()

	// 从配置中获取端口
	port := config.GlobalConfig.Server.Port
	r.Run(fmt.Sprintf(":%d", port))
}

这样，你就可以轻松管理不同环境的配置了，开发环境用 config.dev.yaml，生产环境用 config.prod.yaml。

第八章：身份认证：JWT

在 API 开发中，JWT（JSON Web Token）是最常用的身份认证方式。

JWT 是一种基于 Token 的认证机制，客户端登录成功后会获得一个 JWT Token，之后每次请求都携带这个 Token，服务器验证 Token 的合法性来判断用户是否有权限访问资源。

我们来看看怎么在 Gin 中使用 JWT。

8.1 安装依赖

`1`	`go get github.com/golang-jwt/jwt/v5`

8.2 实现 JWT 工具函数

创建 utils/jwt.go：

package utils

import (
	"errors"
	"time"

	"github.com/golang-jwt/jwt/v5"
	"my-gin-app/config"
)

// 定义 Claims，就是 Token 中存储的信息
type Claims struct {
	UserID   uint   `json:"user_id"`
	Username string `json:"username"`
	jwt.RegisteredClaims
}

// 生成 Token
func GenerateToken(userID uint, username string) (string, error) {
	// 设置过期时间
	expireTime := time.Now().Add(time.Duration(config.GlobalConfig.JWT.Expire) * time.Hour)

	// 创建 Claims
	claims := Claims{
		UserID:   userID,
		Username: username,
		RegisteredClaims: jwt.RegisteredClaims{
			ExpiresAt: jwt.NewNumericDate(expireTime),
			IssuedAt:  jwt.NewNumericDate(time.Now()),
			Issuer:    "my-gin-app",
		},
	}

	// 生成 Token
	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
	signedToken, err := token.SignedString([]byte(config.GlobalConfig.JWT.Secret))

	return signedToken, err
}

// 验证 Token
func ParseToken(tokenString string) (*Claims, error) {
	// 解析 Token
	token, err := jwt.ParseWithClaims(tokenString, &Claims{}, func(token *jwt.Token) (interface{}, error) {
		return []byte(config.GlobalConfig.JWT.Secret), nil
	})

	if err != nil {
		return nil, err
	}

	// 验证 Claims
	if claims, ok := token.Claims.(*Claims); ok && token.Valid {
		return claims, nil
	}

	return nil, errors.New("无效的 Token")
}

8.3 JWT 认证中间件

然后我们就可以写 JWT 认证中间件了：

func JWTAuthMiddleware() gin.HandlerFunc {
	return func(c *gin.Context) {
		// 获取 Token
		tokenString := c.GetHeader("Authorization")
		if tokenString == "" {
			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "请先登录"})
			return
		}

		// 去掉 Bearer 前缀
		tokenString = strings.TrimPrefix(tokenString, "Bearer ")

		// 验证 Token
		claims, err := utils.ParseToken(tokenString)
		if err != nil {
			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Token 无效或已过期"})
			return
		}

		// 把用户信息存到 Context 中
		c.Set("userID", claims.UserID)
		c.Set("username", claims.Username)

		c.Next()
	}
}

8.4 登录接口

func LoginHandler(c *gin.Context) {
	var req struct {
		Username string `json:"username" binding:"required"`
		Password string `json:"password" binding:"required"`
	}

	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}

	// 这里简化了，实际要去数据库查询用户，验证密码
	if req.Username == "admin" && req.Password == "123456" {
		// 生成 Token
		token, err := utils.GenerateToken(1, "admin")
		if err != nil {
			c.JSON(http.StatusInternalServerError, gin.H{"error": "生成 Token 失败"})
			return
		}

		c.JSON(http.StatusOK, gin.H{
			"token": token,
		})
		return
	}

	c.JSON(http.StatusUnauthorized, gin.H{"error": "用户名或密码错误"})
}

这样，你的 API 就有了完整的身份认证功能！

第九章：实战：用户管理 API

现在我们把前面学的所有知识整合起来，做一个完整的用户管理 API 项目。

9.1 项目结构

我们来规划一下项目的目录结构，这是一个标准的分层架构：

my-gin-app/
├── main.go              # 程序入口
├── go.mod               # 依赖管理
├── go.sum
├── config.yaml          # 配置文件
├── config/              # 配置相关
│   └── config.go
├── controllers/         # 控制器，处理请求
│   └── user_controller.go
├── middleware/          # 中间件
│   ├── auth.go
│   └── logger.go
├── models/              # 数据模型
│   └── user.go
├── utils/               # 工具函数
│   └── jwt.go
└── uploads/             # 上传文件目录

9.2 完整代码实现

我们来实现一个完整的用户管理 API，包含：

登录接口
获取用户列表
获取用户详情
创建用户
更新用户
删除用户

完整的代码就不全部贴在这里了，你可以参考前面的知识点，把它们组合起来。最终的效果是：

公开接口：登录
私有接口：需要 JWT 认证才能访问
统一的参数校验
统一的错误处理
日志记录

第十章：单元测试

写完代码之后，我们需要测试我们的接口。Gin 提供了很方便的测试方式。

创建 main_test.go：

package main

import (
	"net/http"
	"net/http/httptest"
	"testing"

	"github.com/gin-gonic/gin"
	"github.com/stretchr/testify/assert"
)

func TestPingRoute(t *testing.T) {
	// 设置为测试模式
	gin.SetMode(gin.TestMode)

	// 初始化路由
	r := gin.Default()
	r.GET("/ping", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{"message": "pong"})
	})

	// 创建测试请求
	req, _ := http.NewRequest("GET", "/ping", nil)
	w := httptest.NewRecorder()

	// 执行请求
	r.ServeHTTP(w, req)

	// 断言结果
	assert.Equal(t, 200, w.Code)
	assert.Equal(t, `{"message":"pong"}`, w.Body.String())
}

然后运行测试：

`1`	`go test -v`

第十一章：生产环境部署

当你的项目开发完成，就可以部署到生产环境了。

11.1 切换到 Release 模式

Gin 默认是 Debug 模式，会打印很多调试信息。生产环境要切换到 Release 模式：

1
2

// 在 main 函数最开始
gin.SetMode(gin.ReleaseMode)

或者通过环境变量：

`1`	`export GIN_MODE=release`

11.2 编译二进制文件

Go 可以编译成单个二进制文件，非常方便部署：

1
2

# 编译
go build -o myapp main.go

编译完成后，你会得到一个 myapp 文件，这就是你的整个应用，不需要任何依赖，直接运行就可以了。

11.3 后台运行

在 Linux 服务器上，你可以用 systemd 来管理你的服务，让它后台运行，开机自启。

创建 /etc/systemd/system/myapp.service：

[Unit]
Description=My Gin App
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/root/my-gin-app
ExecStart=/root/my-gin-app/myapp
Restart=always
Environment=GIN_MODE=release

[Install]
WantedBy=multi-user.target

然后：

# 重载配置
systemctl daemon-reload

# 启动服务
systemctl start myapp

# 设置开机自启
systemctl enable myapp

第十二章：常见问题排查

1. go get 下载依赖超时

解决：设置 GOPROXY 代理，前面已经讲过了。

2. 端口被占用

错误：listen tcp :8080: bind: address already in use
解决：换个端口，或者杀掉占用端口的进程：lsof -i :8080 然后 kill -9 PID

3. 跨域问题

解决：使用 CORS 中间件，前面已经讲过。

4. 参数绑定失败

检查：JSON 格式是否正确，结构体的字段是否是大写（Go 的反射只能访问大写字段），tag 是否正确。

5. 静态文件访问不到

检查：静态文件的路径是否正确，r.Static 的第一个参数是 URL 路径，第二个是本地路径。

总结

恭喜你！读到这里，你已经掌握了 Gin 框架的核心用法：

✅ 环境搭建：Go 安装、Gin 安装、依赖管理
✅ 基础入门：第一个 Hello World 程序
✅ 路由管理：各种 HTTP 方法、参数、路由分组
✅ 请求处理：表单、JSON、文件上传、参数校验
✅ 响应处理：JSON、HTML、静态文件、重定向
✅ 中间件：自定义中间件、CORS、JWT 认证
✅ 配置管理：用 Viper 管理配置文件
✅ 项目实战：完整的用户管理 API
✅ 部署运维：生产环境配置、部署

Gin 是一个非常强大而简洁的框架，它把 Go 语言的高性能和 Web 开发的便捷性完美结合在了一起。希望这篇教程能帮助你快速入门，开启你的 Go Web 开发之旅！

接下来，你可以继续深入学习：

数据库集成（GORM）
限流、熔断等高级中间件
日志系统
监控与链路追踪
容器化部署（Docker）

祝你学习愉快！🚀

Web Development on Snow

Flask 实战教程：面向 Python 开发者的轻量 Web 后端入门

Flask 实战教程：面向 Python 开发者的轻量 Web 后端入门

一、Flask 是什么

二、环境准备

三、第一个 Flask 应用

四、路由、请求与响应

五、模板：用 Jinja2 返回 HTML

六、表单、Session 与安全边界

七、项目变大后：应用工厂与 Blueprint

八、数据库与扩展怎么选

九、测试：用 test client 固定接口行为

十、错误处理与状态码

十一、从开发到生产部署

十二、Flask 常见坑

十三、Flask 与 FastAPI 怎么选

十四、学习路线

参考资料

FastAPI 实战教程：面向 Python 开发者的现代 API 入门

FastAPI 实战教程：面向 Python 开发者的现代 API 入门

一、FastAPI 解决的核心问题

二、环境准备

三、第一个可运行 API

四、类型提示如何变成接口契约

五、Pydantic：把边界数据变可信

六、依赖注入：把横切逻辑拿出接口函数

七、项目变大后怎么拆

八、async def 不等于自动更快

九、错误处理与状态码

十、测试：用接口行为保护重构

十一、部署前需要想清楚的事

十二、常见坑

十三、学习路线

参考资料

Gin Tutorial

前言

什么是 Gin？

前置知识

第一章：环境准备与安装

1.1 安装 Go 语言环境

1.1.1 下载 Go 安装包

1.1.2 安装 Go

1.1.3 验证安装

1.2 配置 Go 模块（Go Modules）

1.3 安装 Gin 框架

1.3.1 创建项目目录

1.3.2 初始化 Go 模块

1.3.3 安装 Gin

第二章：你的第一个 Gin 应用

2.1 编写 Hello World

2.2 运行程序

2.3 测试接口

第三章：核心功能：路由管理

3.1 基础路由

3.2 路径参数（Route Parameters）

3.3 查询参数（Query Parameters）

3.4 路由分组（Route Grouping）

3.5 404 处理

第四章：请求处理与参数绑定

4.1 获取表单数据

4.2 JSON 参数绑定

4.3 Query 参数绑定

4.4 文件上传

第五章：响应处理

5.1 JSON 响应（最常用）

5.2 字符串响应

5.3 HTML 模板渲染

5.4 静态文件服务

5.5 文件下载

5.6 重定向

第六章：中间件（Middleware）

6.1 中间件的工作原理

6.2 默认中间件

6.3 自定义中间件

6.4 中间件的作用范围

6.5 常用社区中间件：解决跨域问题

第七章：配置管理

7.1 安装 Viper

7.2 编写配置文件

7.3 读取配置

八、`async def` 不等于自动更快