Backend 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 框架零基础教程：从入门到实战

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）

祝你学习愉快！🚀

关于 Go 标准库 net 包和 TChannel 包的深入解析

Thu, 09 Apr 2026 11:26:03 +0800

net 包是 Go 语言标准库中网络编程的核心基石，它提供了跨平台的网络 I/O 抽象，支持 TCP/IP、UDP、域名解析、Unix 域套接字等几乎所有主流网络协议。无论是构建简单的客户端 / 服务端，还是开发复杂的分布式系统，net 包都是最底层的支撑工具。

本文档将从基础到高级，全面解析 net 包的核心功能，针对常用功能进行详细展开，并提供可直接运行的实战代码示例。

1. 包概述

net 包的设计理念是统一接口，分层抽象：

高层接口：Dial、Listen、Accept 等通用函数，屏蔽底层协议差异
中层接口：Conn、Listener、PacketConn 等接口，定义通用的读写、监听行为
底层实现：针对 TCP、UDP、IP、Unix 等不同协议的具体实现，提供协议特有的配置能力

大多数场景下，开发者只需要使用高层接口即可完成开发；而在需要精细控制网络行为的场景下，可以深入到底层实现进行调优。

2. 核心基础类型

网络编程的第一步是处理地址，net 包提供了多种地址类型来适配不同的协议。

2.1 IP 地址（`IP` 类型）

IP 类型是一个字节切片，用于表示 IPv4 或 IPv6 地址，它提供了一系列方法来判断地址的属性。

`1`	`type IP []byte`

核心方法与示例

package main

import (
	"fmt"
	"net"
)

func main() {
	// 1. 解析IP地址
	ip := net.ParseIP("192.168.1.100")
	if ip == nil {
		fmt.Println("无效的IP地址")
		return
	}

	// 2. 判断地址类型
	fmt.Println("是否为回环地址:", ip.IsLoopback()) // false
	fmt.Println("是否为私有地址:", ip.IsPrivate())   // true
	fmt.Println("是否为IPv4地址:", ip.To4() != nil)  // true
	// To4方法会返回IPv4地址的4字节表示，如果不是IPv4地址则返回nil；To16方法会返回IPv6地址的16字节表示，如果不是IPv6地址则返回nil。

	// 3. 构造IPv4地址
	ipv4 := net.IPv4(127, 0, 0, 1)
	fmt.Println("回环地址:", ipv4.String()) // 127.0.0.1

	// 4. 掩码计算
	ip2 := net.ParseIP("192.168.1.100")
	mask := net.IPv4Mask(255, 255, 255, 0)
	networkIP := ip2.Mask(mask)
	fmt.Println("网段地址:", networkIP.String()) // 192.168.1.0
}

2.2 IP 网段（`IPNet` 类型）

IPNet 用于表示一个 IP 网段，常用于判断某个 IP 是否属于某个子网，这在防火墙、路由匹配等场景中非常常用。

核心方法与示例

package main

import (
	"fmt"
	"log"
	"net"
)

func main() {
	// 1. 解析CIDR格式的网段
	ip, ipNet, err := net.ParseCIDR("192.168.1.50/24")
	if err != nil {
		log.Fatal(err)      // 解析失败，CIDR格式不正确，或者IP地址无效。
		// log.Fatal会导致程序崩溃，适合在示例代码中使用，但在生产环境中应该使用更优雅的错误处理方式，如log.Printf或返回错误给调用者。
	}

	fmt.Println("IP地址:", ip.String())       // 192.168.1.0
	fmt.Println("网段:", ipNet.String())        // 192.168.1.0/24

	// 2. 判断IP是否属于该网段
	testIP := net.ParseIP("192.168.1.100")
	fmt.Println(testIP.String(), "是否在网段内：", ipNet.Contains(testIP)) // true

	testIP2 := net.ParseIP("8.8.8.8")
	fmt.Println(testIP2.String(), "是否在网段内：", ipNet.Contains(testIP2)) // false
}

2.3 传输层地址（TCPAddr/UDPAddr）

TCP 和 UDP 地址都包含 IP 和端口两部分，用于标识网络中的一个端点。

地址解析示例

package main

import (
	"fmt"
	"log"
	"net"
)

func main() {
	// 解析TCP地址
	tcpAddr, err := net.ResolveTCPAddr("tcp", "localhost:8080")
	if err != nil {
		log.Println(err.Error())
		return
	}
	fmt.Println("TCP地址:", tcpAddr.String()) // 127.0.0.1:8080

	// 解析UDP地址
	udpAddr, err := net.ResolveUDPAddr("udp", "localhost:8080")
	if err != nil {
		log.Println(err.Error())
		return
	}
	fmt.Println("UDP地址:", udpAddr.String()) // 127.0.0.1:8080
}

2.4 地址处理工具函数

处理 host:port 格式的地址时，JoinHostPort 和 SplitHostPort 是最常用的工具，它们能正确处理 IPv6 地址的括号格式。

package main

import (
	"fmt"
	"log"
	"net"
)

func main() {
	// 拼接主机和端口
	host := "127.0.0.1"
	port := "8080"
	addr := net.JoinHostPort(host, port)
	fmt.Println("拼接后地址:", addr) // 127.0.0.1:8080

	// 拆分地址
	host2, port2, err := net.SplitHostPort(addr)
	if err != nil {
		log.Println(err.Error())
		return
	}
	fmt.Println("拆分后主机:", host2, "端口:", port2)

	// 正确处理IPv6地址
	ipv6Addr := "[::1]:8080"
	host3, port3, _ := net.SplitHostPort(ipv6Addr)
	fmt.Println("IPv6拆分后主机:", host3, "端口:", port3) // ::1 8080
}

3. TCP 网络编程（面向连接可靠传输）

TCP 是面向连接的可靠传输协议，是互联网中最常用的传输层协议。net 包通过 TCPListener 和 TCPConn 来实现 TCP 通信。

3.1 基础 TCP 服务端

TCP 服务端的工作流程是：监听端口 -> 接受连接 -> 处理连接。Go 中通过 goroutine 可以轻松实现高并发的服务端。

package main

import (
	"bufio"     // 提供了缓冲读取和写入功能，适用于网络连接的读写操作，可以按行读取数据。
	"fmt"
	"net"
	"log"
)

func handleConnection(conn *net.TCPConn) {
	// 确保连接关闭
	defer conn.Close()
	log.Printf("客户端 %s 已连接", conn.RemoteAddr())

	// 读取客户端数据
	reader := bufio.NewReader(conn)
	for {
		// 按行读取数据
		data, err := reader.ReadString('\n')
		if err != nil {
			log.Printf("客户端 %s 已断开", conn.RemoteAddr())
			return
		}

		log.Printf("收到来自 %s 的消息: %s", conn.RemoteAddr(), data)
		// 回显消息
		_, err = conn.Write([]byte("Echo: " + data))
		if err != nil {
			log.Printf("发送数据失败: %v", err)
			return
		}
	}
}

func main() {
	// 解析监听地址
	addr, err := net.ResolveTCPAddr("tcp", ":8080") // 监听8080端口
	if err != nil {
		log.Println(err.Error())
		return
	}

	// 监听端口
	listener, err := net.ListenTCP("tcp", addr)
	if err != nil {
		log.Println(err.Error())
		return
	}
	defer listener.Close()
	log.Println("TCP服务端已启动，监听 :8080")

	for {
		// 接受新连接
		conn, err := listener.AcceptTCP()
		if err != nil {
			log.Printf("接受连接失败: %v", err)
			continue
		}

		// 启动goroutine处理连接，实现并发
		go handleConnection(conn)
	}
}

3.2 基础 TCP 客户端

TCP 客户端通过主动连接服务端来建立连接，然后进行数据读写。

package main

import (
	"bufio"
	"fmt"
	"net"
	"os"
	"log"
)

func main() {
	// 连接服务端，中间这个nil表示本地地址，通常设置为nil让系统自动分配一个可用的端口。
	conn, err := net.DialTCP("tcp", nil, &net.TCPAddr{IP: net.ParseIP("127.0.0.1"), Port: 8080})
	if err != nil {
		log.Println(err.Error())
		return
	}
	defer conn.Close()

	log.Println("已连接到服务端")

	// 从标准输入读取消息
	scanner := bufio.NewScanner(os.Stdin)   // 从标准输入读取用户输入，os.Stdin表示标准输入设备，通常是键盘。
	writer := bufio.NewWriter(conn)         
	// 创建一个缓冲写入器，用于向TCP连接写数据，它会将数据先写入内存缓冲区，只有在调用Flush方法时才会真正发送到网络上，这样可以提高效率，减少系统调用次数。
	// conn是之前建立的TCP连接，bufio.NewWriter(conn)创建了一个新的缓冲写入器，将TCP连接作为底层的写入目标。

	for scanner.Scan() {
		text := scanner.Text()
		// 发送消息
		_, err = writer.WriteString(text + "\n")
		if err != nil {
			log.Println(err.Error())
		return
		}
		writer.Flush()

		// 读取响应
		resp, err := bufio.NewReader(conn).ReadString('\n') // 以换行符为分隔符读取服务端响应，直到遇到换行符为止。
		if err != nil {
			log.Println(err.Error())
		return
		}
		fmt.Println("服务端响应:", resp)
	}
}

如此即可实现一个简单的 TCP 客户端，能够向服务端发送消息并接收响应。

3.3 TCP 连接高级配置

TCPConn 提供了一系列方法来调整 TCP 协议的参数，以适配不同的业务场景。

3.3.1 禁用 Nagle 算法（`SetNoDelay`）

Nagle 算法是 TCP 协议中的一个优化机制，它会将小数据包合并成一个大数据包发送，以减少网络开销。但在某些实时性要求高的场景下（如在线游戏、即时通信），这种合并会引入不必要的延迟，因此需要禁用 Nagle 算法。

Nagle 算法默认会合并小数据包以减少网络开销，但会引入延迟。对于实时性要求高的场景（如游戏、即时通信），需要禁用它。

// 建立连接后
conn, err := net.DialTCP("tcp", nil, serverAddr)
if err != nil {
	log.Println(err.Error())
		return
}

// 禁用Nagle算法，小数据包立即发送
err = conn.SetNoDelay(true)
if err != nil {
	log.Printf("设置NoDelay失败: %v", err)
}

3.3.2 TCP 保活机制（`SetKeepAlive`）

TCP 保活机制可以自动检测死连接，避免长时间占用资源。Go 1.13+ 还支持更精细的保活配置。

// 启用保活机制
err = conn.SetKeepAlive(true)
if err != nil {
	log.Printf("启用保活失败: %v", err)
}

// 方式1：简单设置保活间隔（旧API）
err = conn.SetKeepAlivePeriod(30 * time.Second)
if err != nil {
	log.Printf("设置保活间隔失败: %v", err)
}

// 方式2：精细配置保活参数（Go 1.13+ 新API）
err = conn.SetKeepAliveConfig(net.KeepAliveConfig{
	Enable:   true,
	Idle:     30 * time.Second,  // 空闲30秒后开始发送探针
	Interval: 10 * time.Second,  // 探针间隔10秒
	Count:    3,                 // 连续3次失败则断开连接
})
if err != nil {
	log.Printf("设置保活配置失败: %v", err)
}

3.3.3 连接半关闭

TCP 支持半关闭，即可以单独关闭读或写通道，这在某些场景下非常有用（比如发送完数据后告诉服务端不再发送，但还能接收响应）。

// 发送完所有数据后，关闭写通道
err = conn.CloseWrite()
if err != nil {
	log.Printf("关闭写通道失败: %v", err)
}

// 此时还可以继续读取服务端的响应
data, err := conn.Read(buf)

// 读取完后，关闭读通道
err = conn.CloseRead()

4. UDP 网络编程（无连接数据报传输）

UDP 是无连接的传输协议，不需要建立连接，直接发送数据包，适用于对实时性要求高、可容忍少量丢包的场景（如音视频、心跳检测）。

4.1 基础 UDP 服务端

package main

import (
	"fmt"
	"net"
	"log"
)

func main() {
	// 解析UDP地址
	addr, err := net.ResolveUDPAddr("udp", ":8080")
	if err != nil {
		log.Println(err.Error())
		return
	}

	// 监听UDP端口
	conn, err := net.ListenUDP("udp", addr)
	if err != nil {
		log.Println(err.Error())
		return
	}
	defer conn.Close()
	log.Println("UDP服务端已启动，监听 :8080")

	buf := make([]byte, 1024)
	for {
		// 读取UDP数据包，同时获取客户端地址
		n, clientAddr, err := conn.ReadFromUDP(buf)
		if err != nil {
			log.Printf("读取数据失败: %v", err)
			continue
		}

		data := string(buf[:n])
		log.Printf("收到来自 %s 的消息: %s", clientAddr, data)

		// 向客户端发送响应
		resp := []byte("UDP Ack: " + data)
		_, err = conn.WriteToUDP(resp, clientAddr)
		if err != nil {
			log.Printf("发送响应失败: %v", err)
		}
	}
}

4.2 基础 UDP 客户端

package main

import (
	"fmt"
	"net"
	"log"
)

func main() {
	// 服务端地址
	serverAddr, err := net.ResolveUDPAddr("udp", "127.0.0.1:8080")
	if err != nil {
		log.Println(err.Error())
		return
	}

	// 建立UDP连接（UDP的连接只是逻辑绑定，不发送网络包）,中间这个nil表示本地地址，通常设置为nil让系统自动分配一个可用的端口。
	conn, err := net.DialUDP("udp", nil, serverAddr)
	if err != nil {
		log.Println(err.Error())
		return
	}
	defer conn.Close()

	// 发送数据
	_, err = conn.Write([]byte("Hello UDP Server!"))
	if err != nil {
		log.Println(err.Error())
		return
	}

	// 读取响应
	buf := make([]byte, 1024)
	n, err := conn.Read(buf)
	if err != nil {
		log.Println(err.Error())
		return
	}

	fmt.Println("服务端响应:", string(buf[:n]))
}

如此即可实现一个简单的 UDP 客户端，能够向服务端发送消息并接收响应。

4.3 实战：UDP 心跳检测

UDP 非常适合做心跳检测，因为它轻量、无连接开销。

package main

import (
	"net"
	"time"
	"log"
)

func main() {
	serverAddr, _ := net.ResolveUDPAddr("udp", "127.0.0.1:8080")
	conn, _ := net.DialUDP("udp", nil, serverAddr)
	defer conn.Close()

	// 定时器，每秒发送一次心跳
	ticker := time.NewTicker(1 * time.Second)
	defer ticker.Stop()

	for range ticker.C {
		// 发送心跳包
		_, err := conn.Write([]byte("HEARTBEAT"))
		if err != nil {
			log.Printf("发送心跳失败: %v", err)
			continue
		}

		// 设置读取超时，检测服务端是否存活
		conn.SetReadDeadline(time.Now().Add(2 * time.Second))
		buf := make([]byte, 1024)
		n, err := conn.Read(buf)
		if err != nil {
			log.Printf("心跳检测失败，服务端可能已下线: %v", err)
			continue
		}

		log.Printf("心跳正常，服务端响应: %s", string(buf[:n]))
	}
}

如图所示，UDP 心跳检测可以快速判断服务端的存活状态，适用于分布式系统中的健康检查和服务发现。

5. DNS 域名解析

net 包提供了完整的 DNS 解析能力，从基础的域名转 IP，到高级的 MX、SRV、TXT 记录查询。

5.1 基础域名解析

package main

import (
	"fmt"
	"net"
	"log"
)

func main() {
	// 解析域名对应的IP列表（同时返回IPv4和IPv6）
	ips, err := net.LookupIP("google.com")
	if err != nil {
		log.Println(err.Error())
		return
	}

	for _, ip := range ips {
		fmt.Println("IP地址:", ip.String())
	}

	// 反向解析：根据IP查找域名
	names, err := net.LookupAddr("8.8.8.8")
	if err != nil {
		log.Println(err.Error())
		return
	}
	for _, name := range names {
		fmt.Println("8.8.8.8对应的域名:", name)
	}
}

解析结果如下图所示：

5.2 高级 DNS 记录查询

package main

import (
	"fmt"
	"net"
	"log"
)

func main() {
	// 1. 查询MX记录（邮件服务器记录）。MX记录是Mail Exchanger Record的缩写，邮件交换记录，用于指定处理该域邮件的服务器地址和优先级。
	mxs, err := net.LookupMX("gmail.com")
	if err != nil {
		log.Println(err.Error())
		return
	}
	fmt.Println("Gmail的邮件服务器:")
	for _, mx := range mxs {
		fmt.Printf("  优先级: %d, 服务器: %s\n", mx.Pref, mx.Host)
	}

	// 2. 查询SRV记录（服务发现记录，常用于微服务）。SRV记录是Service Record的缩写，用于指定提供特定服务的服务器地址、端口和优先级，常用于微服务架构中的服务发现。
	cname, srvs, err := net.LookupSRV("xmpp-server", "tcp", "gmail.com")
	if err != nil {
		log.Println(err.Error())
		return
	}
	fmt.Println("\nXMPP服务的SRV记录:")
	fmt.Println("CNAME:", cname)
	for _, srv := range srvs {
		fmt.Printf("  目标: %s:%d, 优先级: %d, 权重: %d\n", srv.Target, srv.Port, srv.Priority, srv.Weight)
	}

	// 3. 查询TXT记录（常用于验证域名、SPF、DKIM等）。TXT记录是Text Record的缩写，用于存储任意文本信息，常用于域名验证、SPF（Sender Policy Framework）和DKIM（DomainKeys Identified Mail）等邮件安全机制。
	txts, err := net.LookupTXT("gmail.com")
	if err != nil {
		log.Println(err.Error())
		return
	}
	fmt.Println("\nTXT记录:")
	for _, txt := range txts {
		fmt.Println("  ", txt)
	}
}

查询结果如下图所示：

5.3 自定义 DNS 解析器

默认情况下，net 包使用系统的 DNS 配置，但我们可以自定义 DNS 服务器，比如使用 Google DNS 或 Cloudflare DNS。

package main

import (
	"context"
	"fmt"
	"net"
	"time"
)

func main() {
	// 自定义DNS解析器，使用Google的8.8.8.8
	resolver := &net.Resolver{
		// 强制使用Go原生的DNS解析器，不使用系统的cgo解析
		PreferGo: true,
		// 自定义DNS服务器的连接
		Dial: func(ctx context.Context, network, address string) (net.Conn, error) {
			d := net.Dialer{
				Timeout: 3 * time.Second,
			}
			// 连接到自定义的DNS服务器
			return d.DialContext(ctx, "udp", "8.8.8.8:53")
		},
	}

	// 使用自定义解析器解析域名
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	ips, err := resolver.LookupIP(ctx, "ip4", "google.com")
	if err != nil {
		log.Println(err.Error())
		return
	}

	for _, ip := range ips {
		fmt.Println("通过8.8.8.8解析到的IP:", ip.String())
	}
}

解析结果如下图所示：

6. 错误处理与超时控制

网络编程中，错误处理和超时控制是保证服务稳定性的关键。

6.1 网络错误类型（`net.Error`）

net 包的所有网络错误都实现了 net.Error 接口，它提供了 Timeout() 和 Temporary() 方法来区分错误类型。

package main

import (
	"fmt"
	"net"
	"time"
)

func main() {
    // 这里用google.com:80作为测试地址，设置一个非常短的超时时间来触发错误
	conn, err := net.DialTimeout("tcp", "google.com:80", 1*time.Second)
	if err != nil {
		// 判断错误是否为网络错误
		if ne, ok := err.(net.Error); ok {
			fmt.Println("是否为超时错误:", ne.Timeout())
			fmt.Println("是否为临时错误:", ne.Temporary())
		}
		fmt.Println("错误信息:", err)
		return
	}
	defer conn.Close()
	fmt.Println("连接成功")
}

之所以 Timeout() 和 Temporary() 都返回 true，是因为在这个场景下，连接超时被认为是一个临时错误，可能是网络状况不佳导致的，重试可能会成功。

6.2 超时控制详解

net 包提供了多层级的超时控制：

1. 连接超时

在建立连接时设置超时，避免长时间卡在连接阶段。

// 方式1：使用DialTimeout
conn, err := net.DialTimeout("tcp", "google.com:80", 5*time.Second)

// 方式2：使用Dialer+Context
d := net.Dialer{Timeout: 5*time.Second}
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
conn, err := d.DialContext(ctx, "tcp", "google.com:80")

2. 读写超时

连接建立后，为读写操作设置超时，避免单个读写操作阻塞。

// 统一设置读写超时
conn.SetDeadline(time.Now().Add(30 * time.Second))

// 单独设置读超时
conn.SetReadDeadline(time.Now().Add(10 * time.Second))

// 单独设置写超时
conn.SetWriteDeadline(time.Now().Add(10 * time.Second))

7. 高级连接配置：`Dialer`

Dialer 是 net 包中用于配置连接的核心结构体，它可以统一配置连接的超时、保活、DNS 解析器等参数。

7.1 Dialer 核心配置

package main

import (
	"context"
	"fmt"
	"log"
	"net"
	"time"
)

func main() {
	// 配置Dialer
	dialer := &net.Dialer{
		// 连接超时：如果在指定时间内无法建立连接，则返回错误
		Timeout:   5 * time.Second,
		// 保活间隔：每隔30秒发送一次TCP保活探针
		KeepAlive: 30 * time.Second,
		// 本地地址，用于指定出站网卡
		LocalAddr: nil,
		// 自定义DNS解析器
		Resolver: &net.Resolver{
            // 强制使用Go原生的DNS解析器，不使用系统的cgo解析
			PreferGo: true,
            // 自定义DNS服务器的连接
			Dial: func(ctx context.Context, network, address string) (net.Conn, error) {
				return net.Dial("udp", "8.8.8.8:53")
			},
		},
	}

	// 使用Dialer建立连接
	conn, err := dialer.DialContext(context.Background(), "tcp", "google.com:80")
	if err != nil {
		log.Println(err.Error())
		return
	}
	defer conn.Close()

	fmt.Println("连接成功")
}

如果连不上会得到以下输出：

如果连接成功会得到以下输出：

8. Unix 域套接字（本地进程间通信）

Unix 域套接字是用于同一主机上进程间通信的机制，比 TCP 更快，不需要经过网络协议栈，延迟更低。

8.1 流式 Unix 域套接字（类似 TCP）

// 服务端
package main

import (
	"net"
	"os"
	"log"
)

func main() {
	sockPath := "/tmp/test.sock"
	// 清理旧的sock文件
	os.Remove(sockPath)

	// 监听Unix域套接字
	listener, err := net.Listen("unix", sockPath)
	if err != nil {
		log.Println(err.Error())
		return
	}
	defer listener.Close()
	defer os.Remove(sockPath)

	log.Println("Unix服务端已启动")

	for {
		conn, err := listener.Accept()
		if err != nil {
			continue
		}
		go func(c net.Conn) {
			defer c.Close()
			// 处理连接，和TCP完全一样
			buf := make([]byte, 1024)
			n, _ := c.Read(buf)
			c.Write([]byte("Echo: " + string(buf[:n])))
		}(conn)
	}
}

// 客户端
package main

import (
	"fmt"
	"net"
)

func main() {
	// 连接Unix域套接字
	conn, err := net.Dial("unix", "/tmp/test.sock")
	if err != nil {
		log.Println(err.Error())
		return
	}
	defer conn.Close()

	conn.Write([]byte("Hello IPC!"))
	buf := make([]byte, 1024)
	n, _ := conn.Read(buf)
	fmt.Println(string(buf[:n]))
}

9. 原始 IP 与 ICMP：实现 Ping 工具

通过 net 包的原始 IP 连接，我们可以实现 ICMP 协议，也就是常用的 ping 工具。

注意：ICMP 原始套接字在部分系统上需要 root 权限。

package main

import (
	"fmt"
	"net"
	"time"
)

// 计算ICMP校验和
func checkSum(msg []byte) uint16 {
	sum := 0
	for i := 0; i < len(msg)-1; i += 2 {
		sum += int(msg[i])*256 + int(msg[i+1])
	}
	sum = (sum >> 16) + (sum & 0xffff)
	sum += sum >> 16
	return uint16(^sum)
}

func ping(host string) error {
	// 建立ICMP连接
	conn, err := net.Dial("ip4:icmp", host)
	if err != nil {
		return err
	}
	defer conn.Close()

	// 构造ICMP Echo请求包
	msg := make([]byte, 64)
	msg[0] = 8 // Type: Echo Request
	msg[1] = 0 // Code: 0
	// Checksum占位
	msg[2] = 0
	msg[3] = 0
	// Identifier
	id := uint16(1234)
	msg[4] = byte(id >> 8)
	msg[5] = byte(id & 0xff)
	// Sequence
	seq := uint16(1)
	msg[6] = byte(seq >> 8)
	msg[7] = byte(seq & 0xff)

	// 计算校验和
	sum := checkSum(msg)
	msg[2] = byte(sum >> 8)
	msg[3] = byte(sum & 0xff)

	start := time.Now()
	// 发送ICMP包
	_, err = conn.Write(msg)
	if err != nil {
		return err
	}

	// 设置超时
	conn.SetReadDeadline(time.Now().Add(2 * time.Second))
	recv := make([]byte, 1024)
	n, err := conn.Read(recv)
	if err != nil {
		return err
	}

	duration := time.Since(start)
	// 解析响应，ICMP响应的Type为0
	if recv[20] == 0 { // 跳过20字节IP头
		fmt.Printf("%s is up, 延迟: %v\n", host, duration)
		return nil
	}
	return fmt.Errorf("收到非预期的响应")
}

func main() {
	err := ping("8.8.8.8")
	if err != nil {
		fmt.Println("Ping失败:", err)
	}
}

10. 网络接口与本机信息获取

net 包还提供了获取本机网卡、IP 信息的能力。

获取本机所有非回环 IP

package main

import (
	"fmt"
	"net"
)

func main() {
	// 获取所有网络接口的地址
	addrs, err := net.InterfaceAddrs()
	if err != nil {
		log.Println(err.Error())
		return
	}

	for _, addr := range addrs {
		// 转换为IPNet
		if ipNet, ok := addr.(*net.IPNet); ok {
			// 排除回环地址
			if !ipNet.IP.IsLoopback() {
				// 只打印IPv4地址
				if ipNet.IP.To4() != nil {
					fmt.Println("本机IP:", ipNet.IP.String())
				}
			}
		}
	}
}

11. 其他常用工具示例

11.1 简单端口扫描

通过 DialTimeout 我们可以快速实现一个简单的端口扫描工具，检测目标主机的端口是否开放。

package main

import (
	"fmt"
	"net"
	"sync"
	"time"
)

func main() {
	target := "localhost"
	var wg sync.WaitGroup

	// 扫描1-1024端口
	for port := 1; port <= 1024; port++ {
		wg.Add(1)
		go func(p int) {
			defer wg.Done()
			address := fmt.Sprintf("%s:%d", target, p)
			// 用500ms超时检测端口
			conn, err := net.DialTimeout("tcp", address, 500*time.Millisecond)
			if err == nil {
				fmt.Printf("端口 %d 开放\n", p)
				conn.Close()
			}
		}(port)
	}
	wg.Wait()
	fmt.Println("扫描完成")
}

11.2 内存管道 Pipe

Pipe 函数可以创建一对内存中的连接，用于进程内的通信，它实现了 net.Conn 接口，所以可以像网络连接一样进行读写。

package main

import (
	"fmt"
	"net"
)

func main() {
	// 创建内存管道
	r, w := net.Pipe()

	// 写入端goroutine
	go func() {
		defer w.Close()
		// 写入数据
		_, err := w.Write([]byte("Hello from Pipe!"))
		if err != nil {
			log.Println(err.Error())
		return
		}
	}()

	// 读取端
	buf := make([]byte, 1024)
	n, err := r.Read(buf)
	if err != nil {
		log.Println(err.Error())
		return
	}

	fmt.Println("读取到的数据:", string(buf[:n]))
}

11.3 Go 1.26 新特性：Dialer 新方法

Go 1.26 为 Dialer 新增了针对特定协议的方法，比如 DialTCP、DialUDP，这些方法支持预解析的地址，兼顾了预解析的效率和 context 的可取消性。

package main

import (
	"context"
	"fmt"
	"net"
	"net/netip"
	"time"
)

func main() {
	// 预解析地址，避免每次连接都解析
	raddr := netip.MustParseAddrPort("127.0.0.1:8080")

	dialer := &net.Dialer{
		Timeout: 5 * time.Second,
	}

	// 使用新的DialTCP方法，支持context
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	conn, err := dialer.DialTCP(ctx, "tcp", netip.AddrPort{}, raddr)
	if err != nil {
		log.Println(err.Error())
		return
	}
	defer conn.Close()

	fmt.Println("连接成功")
}

11.4 自定义 DNS 在 HTTP 客户端中的应用

我们可以将自定义的 DNS 解析器和 HTTP 客户端结合，让 HTTP 请求也使用自定义的 DNS 服务器。

package main

import (
	"context"
	"fmt"
	"net"
	"net/http"
	"io/ioutil"
	"time"
)

func main() {
	// 自定义DNS解析器，使用Cloudflare的1.1.1.1
	resolver := &net.Resolver{
		PreferGo: true,
		Dial: func(ctx context.Context, network, address string) (net.Conn, error) {
			d := net.Dialer{Timeout: 3 * time.Second}
			return d.DialContext(ctx, "udp", "1.1.1.1:53")
		},
	}

	// 自定义Transport的DialContext
	transport := &http.Transport{
		DialContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
			// 拆分主机和端口
			host, port, err := net.SplitHostPort(addr)
			if err != nil {
				return nil, err
			}

			// 用自定义解析器解析主机
			ips, err := resolver.LookupHost(ctx, host)
			if err != nil {
				return nil, err
			}

			// 逐个尝试连接解析到的IP
			for _, ip := range ips {
				dialer := &net.Dialer{Timeout: 5 * time.Second}
				conn, err := dialer.DialContext(ctx, network, net.JoinHostPort(ip, port))
				if err == nil {
					return conn, nil
				}
			}
			return nil, fmt.Errorf("所有IP连接失败")
		},
	}

	// 创建使用自定义DNS的HTTP客户端
	client := &http.Client{
		Transport: transport,
		Timeout:   10 * time.Second,
	}

	// 发送请求
	resp, err := client.Get("https://example.com")
	if err != nil {
		log.Println(err.Error())
		return
	}
	defer resp.Body.Close()

	body, _ := ioutil.ReadAll(resp.Body)
	fmt.Println("响应状态:", resp.Status)
	fmt.Println("响应长度:", len(body))
}

12. 避坑指南

始终处理错误：网络操作的错误必须处理，不能忽略，尤其是 Accept、Read、Write 这些核心操作。
资源释放：使用 defer conn.Close() 确保连接关闭，避免文件描述符泄漏。
超时控制：所有网络操作都要设置超时，避免阻塞导致服务不可用。
并发处理：TCP 服务端必须用 goroutine 处理每个连接，才能实现高并发。
参数调优：
- 实时场景：禁用 Nagle 算法（SetNoDelay(true)）
- 长连接场景：启用 TCP 保活，快速检测死连接
- 批量传输：保持 Nagle 算法，增大读写缓冲区，提升吞吐量
DNS 缓存：默认的 DNS 解析没有缓存，高并发场景下建议自己实现 DNS 缓存，避免频繁解析。
Unix 域套接字：本地进程间通信优先使用 Unix 域套接字，比 TCP 性能更好。

通过以上内容，你已经基本掌握了 Go net 包的核心用法，从基础的 TCP/UDP 通信，到高级的 DNS 解析、ICMP 实现，都可以基于此进行开发。无论是构建简单的网络工具，还是开发复杂的分布式系统，net 包都是你不可或缺的利器。希望这份文档能帮助你更好地理解和使用 Go 的网络编程能力！

MySQL教程

Sat, 04 Apr 2026 13:48:03 +0800

前言

欢迎来到 MySQL 的世界！无论你是刚接触编程的新手，还是想要补充数据库技能的开发者，这份教程都将为你提供最系统、最详细的学习路径。

MySQL 作为全球最流行的开源关系型数据库，凭借其轻量、高效、跨平台、免费的特性，已经成为 Web 开发、数据分析、后端服务的标配存储方案。从个人博客到大型电商平台，从学生管理系统到金融交易系统，MySQL 都能胜任。

本教程全程基于MySQL 8.0 LTS 稳定版编写，覆盖从环境搭建到生产级运维的全流程，所有代码均可直接复制执行，所有知识点都配有实战案例，确保零基础的你也能一步到位，彻底掌握 MySQL。

第一章：MySQL 基础认知

在动手操作之前，我们先搞懂几个核心概念，帮你建立对 MySQL 的整体认知。

1.1 核心概念

概念	通俗解释
数据库（DB）	存储数据的大仓库，一个 MySQL 服务可以装很多个仓库，比如电商库、学生库
数据表（Table）	仓库里的 Excel 表格，用来分类存储数据，比如用户表、订单表
字段（Column）	表格里的列，比如用户表的`id`、`name`、`age`
记录（Row）	表格里的行，一条完整的数据，比如`1,张三,20`就是一个用户的记录
SQL	操作数据库的标准语言，就像你和数据库沟通的普通话

1.2 MySQL 整体架构

MySQL 采用经典的客户端 - 服务器架构，整个系统分为三层，理解这个架构能帮你搞懂 SQL 是怎么执行的：

连接层：负责处理客户端的连接请求、权限验证
服务层：核心层，负责 SQL 解析、优化、执行，还有内置函数、权限管理等
存储引擎层：真正负责数据存储和提取的模块，不同引擎有不同的特性

1.3 存储引擎：选对工具事半功倍

MySQL 的存储引擎就像不同的文件管理器，你可以根据业务需求选择：

引擎	特点	适用场景
InnoDB	默认引擎，支持事务、外键、行级锁， crash-safe	99% 的业务场景，生产环境首选
MyISAM	轻量，不支持事务，表级锁，查询快	只读的日志表、静态数据
Memory	数据存在内存里，速度极快，重启就没	临时缓存表、中间计算

💡 提示：不用纠结，直接用默认的 InnoDB 就对了，它能满足你所有的学习和开发需求。

第二章：环境搭建：全平台安装指南

这一章我们来搞定 MySQL 的安装，覆盖 Windows、Linux、Mac 三大平台，每一步都有避坑提示，保证你一次成功。

2.1 Windows 平台安装（图形化界面，新手首选）

Windows 用户推荐用官方的 MSI 安装包，全程图形化操作，不用敲命令。

步骤 1：下载安装包

打开官网下载页：https://dev.mysql.com/downloads/installer/
下载MySQL Installer for Windows的完整安装包（约 500M，不要下小的在线包）

步骤 2：安装流程

双击安装包，选择Developer Default（开发者默认），这个会自动帮你装齐所有需要的组件
等待依赖安装完成，一路 Next 到配置页面
Type and Networking：保持默认，端口 3306 不要改
认证方式：保持默认的强密码加密
设置 root 密码：务必记牢！比如Mysql@2026，要包含大小写、数字、特殊字符
Windows 服务：保持默认，勾选开机自启
点击 Execute，等待安装完成

步骤 3：配置环境变量（解决 mysql 不是内部命令）

找到 MySQL 的 bin 目录，默认是C:\Program Files\MySQL\MySQL Server 8.0\bin
右键此电脑→属性→高级系统设置→环境变量
找到系统变量里的 Path，双击添加上面的 bin 目录
重启 CMD，输入mysql -u root -p，输入密码能进入命令行就成功了！

2.2 Linux 平台安装（生产环境主流）

Linux 是企业生产环境的首选，我们覆盖 CentOS 和 Ubuntu 两大主流发行版。

CentOS/Rocky Linux 安装

# 1. 卸载系统自带的mariadb，避免冲突
yum remove -y mariadb*
# 2. 配置MySQL官方源
wget https://dev.mysql.com/get/mysql80-community-release-el8-3.noarch.rpm
rpm -ivh mysql80-community-release-el8-3.noarch.rpm
# 3. 安装MySQL
yum install -y mysql-community-server
# 4. 启动服务，设置开机自启
systemctl start mysqld
systemctl enable mysqld
# 5. 获取临时密码
grep 'temporary password' /var/log/mysqld.log
# 6. 登录修改密码
mysql -u root -p
ALTER USER 'root'@'localhost' IDENTIFIED BY 'Mysql@Linux2026!';

Ubuntu/Debian 安装

# 1. 更新源，清理旧版本
apt update -y && apt upgrade -y
apt remove -y mysql* mariadb*
# 2. 安装MySQL
apt install -y mysql-server
# 3. 启动服务
systemctl start mysql
systemctl enable mysql
# 4. 执行安全加固，设置密码
mysql_secure_installation

2.3 Mac 平台安装（Homebrew 一键搞定）

Mac 用户强烈推荐用 Homebrew 安装，比 dmg 包简单太多，自动适配 Intel 和 M 芯片。

# 1. 如果你没装Homebrew，先装它
/bin/bash -c "$(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew-install.sh)"
# 2. 安装MySQL
brew update
brew install mysql
# 3. 启动服务
brew services start mysql
# 4. 安全加固，设置密码
mysql_secure_installation

2.4 安装报错急救包

99% 的安装失败都是这些问题，对照着解决：

1045 错误：密码错误：检查密码大小写，不要复制多余空格
2003 错误：连不上服务器：MySQL 服务没启动，或者防火墙拦了 3306 端口
命令找不到：环境变量没配对，重启终端试试
服务启动失败：之前的 MySQL 没卸载干净，或者路径有中文

第三章：SQL 核心语法入门

终于到了最核心的部分，SQL 语言！SQL 分为四大类，我们一个个来学。

后续的代码演示都在Navicat里操作的，命令行也一样，跟着敲一遍，理解更深刻！

3.1 DDL：数据库和表的结构操作

DDL 是用来定义数据库、表的结构的，比如建库、建表、改表。

数据库操作

-- 1. 创建数据库，不存在才创建，指定编码为utf8mb4（支持emoji）
CREATE DATABASE IF NOT EXISTS test_db DEFAULT CHARSET utf8mb4;

-- 2. 查看所有数据库
SHOW DATABASES;

-- 3. 使用/切换到这个数据库
USE test_db;

-- 4. 删除数据库（谨慎！删了就没了）
DROP DATABASE IF EXISTS test_db;

数据类型：选对类型很重要

建表之前要先搞懂字段的数据类型，这决定了你能存什么数据：

类型	说明	常用场景
INT	整数，4 字节	ID、年龄、数量
TINYINT	小整数，1 字节	状态、性别（1/0）
VARCHAR(n)	可变长度字符串	用户名、手机号、标题
TEXT	长文本	文章内容、描述
DECIMAL(m,n)	精确小数	金额、价格（比如 DECIMAL (10,2) 就是最多 10 位，2 位小数）
DATE	日期	生日、入职日期
DATETIME	日期时间	创建时间、更新时间

创建表

-- 创建用户表，包含各种约束和注释
CREATE TABLE IF NOT EXISTS `user` (
    `id` INT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '用户ID，自增主键',
    `username` VARCHAR(50) NOT NULL UNIQUE COMMENT '用户名，唯一',
    `name` VARCHAR(10) NOT NULL COMMENT '姓名',
    `age` TINYINT UNSIGNED DEFAULT 0 COMMENT '年龄',
    `gender` ENUM('男','女','未知') DEFAULT '未知' COMMENT '性别',
    `phone` CHAR(11) NOT NULL UNIQUE COMMENT '手机号',
    `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间，自动填充',
    PRIMARY KEY (`id`) -- 主键，唯一标识一条记录
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户信息表';

表的修改和删除

-- 查看表结构
DESC `user`;

-- 查看建表的SQL语句
SHOW CREATE TABLE `user`;

-- 添加字段：给user表加个email字段
ALTER TABLE `user` ADD `email` VARCHAR(50) AFTER `phone`;

-- 修改字段：把phone的长度改成20
ALTER TABLE `user` MODIFY `phone` VARCHAR(20);

-- 删除字段
ALTER TABLE `user` DROP `email`;

-- 删除表（谨慎！）
DROP TABLE IF EXISTS `user`;

3.2 DML：数据的增删改

DDL 是改结构，DML 是改表里的数据，也就是我们常说的增删改。

user表的结构如图所示：

插入数据（INSERT）

-- 1. 插入单条数据，指定字段
INSERT INTO `user` (`username`, `name`, `age`, `gender`, `phone`) 
VALUES ('zhangsan', '张三', 20, '男', '13800138001');

-- 2. 批量插入多条数据，效率更高
INSERT INTO `user` (`username`, `name`, `age`, `gender`, `phone`) 
VALUES 
('lisi', '李四', 22, '女', '13800138002'),
('wangwu', '王五', 25, '男', '13800138003'),
('zhaoliu', '赵六', 18, '未知', '13800138004');

-- 3. 插入所有字段，按表的顺序来，id自增可以传NULL
INSERT INTO `user` VALUES (NULL, 'sunqi', '孙七', 21, '男', '13800138005', NOW());

SELECT * FROM `user`

更新数据（UPDATE）

⚠️ 新手最容易踩的坑：UPDATE 一定要加 WHERE 条件！不然会把全表的数据都改了！

-- 1. 更新单条数据：把id=1的张三的年龄改成21
UPDATE `user` SET `age` = 21 WHERE `id` = 1;

-- 2. 更新多个字段：把李四的年龄和性别都改了
UPDATE `user` SET `age` = 23, `gender` = '女' WHERE `id` = 2;

-- 3. 批量更新：给所有20岁以下的用户年龄加1（谨慎使用！）
UPDATE `user` SET `age` = `age` + 1 WHERE `age` < 20;

删除数据（DELETE）

⚠️ 同样！DELETE 一定要加 WHERE！不然全表数据都没了！

-- 1. 删除单条数据：删除id=4的赵六
DELETE FROM `user` WHERE `id` = 4;

-- 2. 批量删除：删除所有年龄大于100的无效数据
DELETE FROM `user` WHERE `age` > 100;

-- 3. 清空整个表，重置自增ID（比DELETE快，但是不可回滚）
TRUNCATE TABLE `user`;

3.3 DQL：数据查询（核心中的核心）

DQL 是我们用的最多的，查询数据！90% 的数据库操作都是查询。

基础查询

-- 1. 查询所有字段（不推荐，效率低，要啥查啥）
SELECT * FROM `user`;

-- 2. 查询指定字段
SELECT `name`, `age`, `gender` FROM `user`;

-- 3. 给字段起别名，方便看
SELECT `name` AS 姓名, `age` AS 年龄, `gender` AS 性别 FROM `user`;

-- 4. 去重：查询所有不重复的性别
SELECT DISTINCT `gender` FROM `user`;

条件查询（WHERE）

按条件过滤数据，这是查询最常用的：

运算符	作用	示例
=	等于	WHERE id = 1
!= / <>	不等于	WHERE age != 20
> < >= <=	比较	WHERE age > 18
BETWEEN … AND …	区间	WHERE age BETWEEN 18 AND 25
IN(…)	匹配多个值	WHERE id IN (1,2,3)
IS NULL / IS NOT NULL	空值判断	WHERE phone IS NULL
LIKE	模糊查询	WHERE name LIKE ‘张%’
AND / OR	逻辑与 / 或	WHERE age>18 AND gender=’ 男'

实战示例：

-- 1. 查询年龄大于20的男性
SELECT * FROM `user` WHERE `age` > 20 AND `gender` = '男';

-- 2. 查询年龄在18到25之间的用户
SELECT * FROM `user` WHERE `age` BETWEEN 18 AND 25;

-- 3. 查询姓名是张三或者李四的
SELECT * FROM `user` WHERE `name` IN ('张三', '李四');

-- 4. 查询姓张的用户（%匹配任意字符）
SELECT * FROM `user` WHERE `name` LIKE '张%';

-- 5. 查询姓名是两个字的用户（_匹配单个字符）
SELECT * FROM `user` WHERE `name` LIKE '__';

排序查询（ORDER BY）

把查询结果按某个字段排序：

-- 1. 按年龄升序（从小到大，ASC是默认）
SELECT * FROM `user` ORDER BY `age` ASC;

-- 2. 按年龄降序（从大到小）
SELECT * FROM `user` ORDER BY `age` DESC;

-- 3. 多字段排序：先按年龄排，年龄相同按创建时间排
SELECT * FROM `user` ORDER BY `age` DESC, `create_time` DESC;

分页查询（LIMIT）

数据太多的时候，分页显示，比如每页 10 条：

-- 语法：LIMIT 起始索引, 每页条数
-- 起始索引 = (页码 - 1) * 每页条数

-- 第1页，每页2条
SELECT * FROM `user` LIMIT 0, 2;

-- 第2页，每页2条
SELECT * FROM `user` LIMIT 2, 2;

-- 第3页，每页2条
SELECT * FROM `user` LIMIT 4, 2;

分组查询（GROUP BY）

分组统计，比如按性别统计人数，按班级统计平均分：

-- 聚合函数：用来统计的函数
-- COUNT(*)：统计行数，SUM()：求和，AVG()：平均值，MAX()：最大值，MIN()：最小值

-- 1. 按性别分组，统计每个性别的人数和平均年龄
SELECT 
    `gender`, 
    COUNT(*) AS 人数, 
    AVG(`age`) AS 平均年龄 
FROM `user` 
GROUP BY `gender`;

-- 2. 先过滤，再分组：查询20岁以上的用户，按性别分组
SELECT `gender`, COUNT(*) FROM `user` WHERE `age` > 21 GROUP BY `gender`;

-- 3. 分组后再过滤：筛选人数大于1的分组（HAVING是分组后的过滤，WHERE是分组前的）
SELECT `gender`, COUNT(*) AS cnt FROM `user` GROUP BY `gender` HAVING cnt > 1;

第四章：高级查询技巧

学会了基础查询，我们来学更复杂的，多表查询、子查询这些。

4.1 多表连接查询

实际业务中，数据往往存在多个表里，比如用户表、订单表，我们需要把它们关联起来查询。

首先我们准备两个表：

-- 订单表
CREATE TABLE `order` (
    `id` INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
    `order_no` VARCHAR(30) NOT NULL UNIQUE,
    `user_id` INT UNSIGNED NOT NULL,
    `amount` DECIMAL(10,2) NOT NULL,
    `create_time` DATETIME DEFAULT NOW(),
    FOREIGN KEY (`user_id`) REFERENCES `user`(`id`)
) ENGINE=InnoDB;

-- 插入测试数据
INSERT INTO `order` (`order_no`, `user_id`, `amount`) VALUES
('ORD001', 1, 99.9),
('ORD002', 1, 199.9),
('ORD003', 2, 299.9);

内连接（INNER JOIN）

只查两个表都匹配的数据，也就是有订单的用户：

-- 查询用户的姓名和他的订单
SELECT 
    u.`name`, o.`order_no`, o.`amount`
FROM `user` u
INNER JOIN `order` o ON u.`id` = o.`user_id`;

左连接（LEFT JOIN）

查左表的所有数据，右表匹配不上的就显示 NULL，比如查所有用户，包括没有订单的：

-- 查询所有用户，以及他们的订单，没有订单的也显示
SELECT 
    u.`name`, o.`order_no`, o.`amount`
FROM `user` u
LEFT JOIN `order` o ON u.`id` = o.`user_id`;

右连接（RIGHT JOIN）

和左连接相反，查右表的所有数据，左表匹配不上的显示 NULL，用的比较少。

4.2 子查询

子查询就是嵌套在 SQL 里的查询，用来处理复杂的条件。

-- 1. 标量子查询：查询年龄大于平均年龄的用户
SELECT `name`, `age` FROM `user` 
WHERE `age` > (SELECT AVG(`age`) FROM `user`);

-- 2. 表子查询：查询有订单的用户
SELECT * FROM `user` 
WHERE `id` IN (SELECT DISTINCT `user_id` FROM `order`);

-- 3. exists子查询：查询有订单的用户，效率比IN高
SELECT * FROM `user` u
WHERE EXISTS (SELECT 1 FROM `order` o WHERE o.`user_id` = u.`id`);

第五章：数据完整性与约束：保证数据绝对正确

很多人刚学的时候，会插入乱七八糟的数据，比如手机号重复、年龄负数、订单的用户不存在，约束就是用来解决这个问题的，它是数据库的 ”守门员”，保证你存进去的数据都是合法的。

5.1 约束的核心作用

约束是定义在表上的强制规则，数据库会自动帮你检查，如果你插入 / 更新的数据违反了规则，直接拒绝执行，从根源上避免脏数据。

5.2 非空约束（NOT NULL）：这个字段必须填

非空约束是最基础的，它规定这个字段不能为空，你插入数据的时候必须给它赋值。

实战示例

-- 创建表的时候，给name加非空约束
CREATE TABLE `user` (
    `id` INT PRIMARY KEY AUTO_INCREMENT,
    `name` VARCHAR(50) NOT NULL, -- 姓名不能为空
    `age` INT
);

-- 测试：插入name为空的数据，会直接报错！
INSERT INTO `user`(`name`, `age`) VALUES(NULL, 20);
-- 报错：Column 'name' cannot be null

💡 提示：必填的字段一定要加 NOT NULL，比如用户名、手机号，不然很容易出现空数据。

5.3 唯一约束（UNIQUE）：这个字段不能重复

唯一约束规定，这个字段的所有值都不能重复，比如用户名、手机号、身份证号，这些都是不能重复的。

实战示例

-- 给username和phone加唯一约束
CREATE TABLE `user` (
    `id` INT PRIMARY KEY AUTO_INCREMENT,
    `username` VARCHAR(50) NOT NULL UNIQUE, -- 用户名唯一
    `phone` CHAR(11) NOT NULL UNIQUE, -- 手机号唯一
    `name` VARCHAR(50) NOT NULL
);

-- 测试：插入重复的用户名，会报错！
INSERT INTO `user`(`username`, `phone`, `name`) VALUES('zhangsan', '13800138001', '张三');
INSERT INTO `user`(`username`, `phone`, `name`) VALUES('zhangsan', '13800138002', '张三2');
-- 报错：Duplicate entry 'zhangsan' for key 'user.username'

💡 注意：唯一约束允许 NULL 值，而且可以有多个 NULL，因为 NULL 不等于任何值，包括它自己。

5.4 主键约束（PRIMARY KEY）：数据的唯一身份证

主键约束是非空 + 唯一的组合，它是一条记录的唯一标识，一个表只能有一个主键。

主键的作用：

唯一标识一条记录，不会有重复
其他表的外键要关联它
默认的主键索引，查询主键的时候速度极快

主键的选择

如果经常纠结主键选什么，这里给你一个最佳实践：

不要用业务字段当主键：比如手机号、身份证号，这些业务字段可能会变
用自增 ID 当主键：INT UNSIGNED NOT NULL AUTO_INCREMENT，简单、高效、不会变
UUID 主键：分布式系统用，不过会导致索引碎片，新手不用考虑

5.5 默认约束（DEFAULT）：没填的话，用默认值

默认约束就是，如果你插入数据的时候没给这个字段赋值，就用默认值，非常方便。

实战示例

CREATE TABLE `user` (
    `id` INT PRIMARY KEY AUTO_INCREMENT,
    `name` VARCHAR(50) NOT NULL,
    `age` INT DEFAULT 0, -- 年龄默认0
    `gender` ENUM('男','女','未知') DEFAULT '未知', -- 性别默认未知
    `status` TINYINT DEFAULT 1, -- 状态默认1：启用
    `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP -- 创建时间默认当前时间
);

-- 插入数据的时候，不用填这些字段，自动用默认值
INSERT INTO `user`(`name`) VALUES('张三');
-- 结果：age=0, gender=未知, status=1, create_time=现在的时间

5.6 检查约束（CHECK）：自定义数据规则

MySQL 8.0 终于支持 CHECK 约束了！你可以自定义数据的规则，比如年龄必须大于 0，余额不能小于 0。

实战示例

CREATE TABLE `account` (
    `id` INT PRIMARY KEY AUTO_INCREMENT,
    `name` VARCHAR(50) NOT NULL,
    `age` INT CHECK (age > 0), -- 年龄必须大于0
    `balance` DECIMAL(10,2) CHECK (balance >= 0) -- 余额不能小于0
);

-- 测试：插入年龄为-1的，会报错！
INSERT INTO `account`(`name`, `age`, `balance`) VALUES('张三', -1, 100);
-- 报错：Check constraint 'account_chk_1' is violated.

5.7 外键约束（FOREIGN KEY）：关联数据的完整性

外键是用来保证两个表的关联数据正确的，比如订单表的user_id，必须在用户表存在，不能出现一个订单的用户是不存在的。

实战示例

-- 先建主表：用户表
CREATE TABLE `user` (
    `id` INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
    `name` VARCHAR(50) NOT NULL
);

-- 再建从表：订单表，user_id关联用户表的id
CREATE TABLE `order` (
    `id` INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
    `order_no` VARCHAR(30) NOT NULL,
    `user_id` INT UNSIGNED NOT NULL,
    `amount` DECIMAL(10,2) NOT NULL,
    -- 定义外键：user_id关联users的id
    FOREIGN KEY (user_id) REFERENCES `user`(id)
);

-- 测试：插入一个不存在的user_id的订单，会报错！
INSERT INTO `order`(`order_no`, `user_id`, `amount`) VALUES('ORD001', 999, 100);
-- 报错：Cannot add or update a child row: a foreign key constraint fails

5.8 外键的级联操作：删主表数据的时候，从表怎么办？

默认情况下，如果你要删的用户还有订单，MySQL 是不让你删的，这就是RESTRICT模式，防止你误删。

但是有时候我们希望，删用户的时候，把他的订单也一起删了，这时候就可以用级联操作：

级联模式	作用
RESTRICT	默认，不让你删，必须先删从表数据
CASCADE	级联，删主表数据的时候，把从表关联的数据也一起删了
SET NULL	删主表数据的时候，把从表的外键设为 NULL
NO ACTION	和 RESTRICT 一样，啥也不做

级联删除实战

-- 先建主表：用户表
CREATE TABLE `user` (
    `id` INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
    `name` VARCHAR(50) NOT NULL
);

-- 建表的时候，指定级联删除
CREATE TABLE `order` (
    `id` INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
    `order_no` VARCHAR(30) NOT NULL,
    `user_id` INT UNSIGNED NOT NULL,
    `amount` DECIMAL(10,2) NOT NULL,
    -- 删用户的时候，级联删除他的订单
    FOREIGN KEY (user_id) REFERENCES `user`(id) ON DELETE CASCADE
);

INSERT INTO `user` VALUES(NULL, '张三');

INSERT INTO `order` VALUES(NULL, 'a0001', 1, 100);

-- 现在删用户，他的订单会自动被删掉
DELETE FROM `user` WHERE id = 1;

SELECT * FROM `order`
-- 关联的order里的user_id=1的订单，也一起没了

💡 避坑：外键虽然能保证数据完整性，但是会降低性能，高并发的生产环境，很多公司会选择在业务层保证数据一致性，不用外键，咱们学习的时候可以先用着。

第六章：事务管理：保证数据绝对不出错

你有没有遇到过这种情况：转账的时候，A 的钱扣了，B 的钱没加上？这就是没有事务导致的。

事务就是把一组操作打包成一个 ”原子操作”，要么全成功，要么全失败，绝对不会出现只成功一半的情况。

MySQL 中使用 START TRANSACTION 开启事务，COMMIT 提交事务，ROLLBACK 回滚事务。

6.1 事务的 ACID 特性：事务的四大金刚

1. 原子性（Atomicity）：要么全做，要么全不做

原子性是事务最基础的特性，事务里的所有操作，就像一个原子一样，不可分割，不会只做一半。

比如转账的两个操作：A 减 100，B 加 100，这两个必须同时成功，或者同时失败，不能只成功一个。

2. 一致性（Consistency）：数据的状态永远是对的

一致性是说，事务执行前后，数据的完整性约束没有被破坏。

比如转账前，A 有 1000，B 有 1000，总钱数是 2000；转账后，A 有 900，B 有 1100，总钱数还是 2000，这就是一致的。如果 A 减了 100，B 没加，总钱数变成 1900，这就是不一致的，事务会阻止这种情况。

3. 隔离性（Isolation）：多个事务互不干扰

隔离性是说，多个事务同时执行的时候，互相看不到对方的中间状态，不会互相干扰。

比如你和我同时操作同一个账户，我的事务不会影响你的事务，你的也不会影响我的。

4. 持久性（Durability）：提交了就永远不会丢

事务提交之后，数据就永久写到磁盘里了，就算系统断电、崩溃，数据也不会丢。

6.2 事务的基本操作：转账实战

我们用转账的例子，来看看事务怎么用：

-- 先建账户表
CREATE TABLE `account` (
    `id` INT PRIMARY KEY AUTO_INCREMENT,
    `name` VARCHAR(50) NOT NULL,
    `balance` DECIMAL(10,2) NOT NULL DEFAULT 0
);

-- 插入测试数据：A有1000，B有1000
INSERT INTO `account`(`name`, `balance`) VALUES('A', 1000), ('B', 1000);

现在我们要做转账：A 给 B 转 100 块。

-- 1. 开启事务，关闭自动提交
-- 开启事务之后，你做的所有操作都是临时的，没提交之前别人看不到
START TRANSACTION;

-- 2. 执行操作：A减100
UPDATE account SET balance = balance - 100 WHERE id = 1;

-- 3. 执行操作：B加100
UPDATE account SET balance = balance + 100 WHERE id = 2;

-- 4. 检查一下，没问题的话，提交事务，生效
COMMIT;

-- 5. 如果中间出错了，比如网络断了，就回滚，回到事务之前的状态
ROLLBACK;

💡 提示：MySQL 默认是自动提交的，也就是你执行一条 SQL，它就自动提交了，所以你要手动开事务，它才会把你的操作打包。

6.3 并发问题：多个事务同时操作会出什么问题？

如果只有一个事务，那没问题，但是实际生产中，几百个事务同时执行，就会出现并发问题，主要有三个：

1. 脏读：读到了别人未提交的数据

脏读就是，一个事务读到了另一个事务还没提交的数据，然后那个事务回滚了，你读到的就是脏数据。

举个例子：

事务 1：A 给 B 转 100，A 减了 100，还没提交
事务 2：查 A 的余额，读到了 900
事务 1：出错了，回滚，A 的余额变回 1000
结果：事务 2 读到的 900 就是脏数据，根本不存在

2. 不可重复读：同一个事务里，两次读同一个数据，结果不一样

不可重复读就是，在同一个事务里，你两次读同一个数据，结果不一样，因为中间被别的事务改了。

举个例子：

事务 1：查 A 的余额，读到 1000
事务 2：改 A 的余额，改成 900，提交了
事务 1：再查 A 的余额，读到 900
结果：同一个事务里，两次读同一个数据，结果不一样，这就是不可重复读

3. 幻读：同一个事务里，两次查询，行数不一样

幻读就是，在同一个事务里，你两次查同一个范围的数据，第二次多了一行，就像幻觉一样。

举个例子：

事务 1：查年龄 > 20 的用户，查到 2 行
事务 2：插入了一个年龄 25 的用户，提交了
事务 1：再查年龄 > 20 的用户，查到 3 行
结果：同一个事务里，两次查一样的条件，结果行数不一样，这就是幻读

6.4 事务隔离级别：解决并发问题

为了解决这些并发问题，SQL 定义了四个隔离级别，级别越高，并发问题越少，但是性能越差。

隔离级别	脏读	不可重复读	幻读	说明
读未提交（Read Uncommitted）	✅	✅	✅	最低，基本不用，性能最好
读已提交（Read Committed）	❌	✅	✅	Oracle 默认，解决了脏读
可重复读（Repeatable Read）	❌	❌	✅	MySQL 默认，解决了脏读、不可重复读
串行化（Serializable）	❌	❌	❌	最高，所有问题都解决，但是性能最差，完全串行

💡 提示：MySQL 默认的可重复读，通过 MVCC（多版本并发控制），其实也解决了幻读，所以你不用改隔离级别，默认的就够用了。

6.5 事务避坑

不要开长事务：事务不要开太久，不然会锁表，影响其他业务，比如你开了事务，然后去调用接口，半天不提交，这就会出问题
异常一定要回滚：代码里如果出错了，一定要调用 ROLLBACK，不然事务会一直挂着
不要在事务里做远程调用：远程调用很慢，会把事务拖长
不要用事务做批量导入：大的批量操作，拆成小事务，不然锁太久了

第七章：索引：让查询快 1000 倍的秘密

很多人刚学的时候，数据少，查询很快，等数据到了 100 万，查询就慢的要死，这就是因为没加索引！

索引就是把数据按照某个字段进行排序，建立一个快速查找的目录，就像书的目录一样，有了索引，你就不用一页一页翻书了，直接就能找到你要的内容，查询速度能提升几百上千倍！

7.1 索引的原理：B + 树到底是什么？

MySQL 默认的索引是B + 树，这是一种有序的平衡树，所有的数据都存在叶子节点，而且叶子节点是有序的，用链表连起来。

B + 树的特点：

有序：所有数据都是排好序的，所以范围查询、排序都特别快
查询快：查询的时间复杂度是 O (log n)，100 万的数据，只要查 20 次就找到了
叶子节点有序：叶子节点是用链表连起来的，所以遍历全表也很快

7.2 索引的类型：不同的索引用在不同的地方

类型	作用	适用场景
主键索引	主键自带的，聚簇索引，每个表必须有	主键 ID，查询 ID 的时候
二级索引	普通的索引，叶子节点存主键	普通的查询字段，比如 name
唯一索引	唯一字段的索引，值不能重复	手机号、用户名、订单号
复合索引	多个字段的索引，比如 (name, age)	经常一起查询的多个字段
覆盖索引	查询的字段都在索引里，不用回表	只查几个字段的查询
全文索引	文本的模糊搜索，比如文章内容	全文检索，比如搜索文章

7.3 回表：什么是回表，怎么避免？

二级索引的叶子节点存的是数据的主键，所以你用二级索引查到主键之后，还要用主键去主键索引里查完整的数据，这就叫回表，回表会多一次 IO，所以会慢一点。

如果你的查询的字段，都在索引里，那就不用回表了，这就是覆盖索引，速度会快很多。

比如：

-- 我们有复合索引(name, age)
-- 这个查询，只查name和age，都在索引里，不用回表，覆盖索引
SELECT `name`, `age` FROM `user` WHERE `name` = '张三';

-- 这个查询，要查phone，phone不在索引里，所以要回表
SELECT `name`, `age`, `phone` FROM `user` WHERE `name` = '张三';

7.4 最左前缀原则：复合索引的核心规则

复合索引是多个字段的索引，比如(a,b,c)，它的顺序很重要，查询的时候，必须从最左边的字段开始匹配，这就是最左前缀原则。

举个例子，我们有复合索引(name, age, gender)：

查询条件	能不能用到索引？
WHERE `name` = ‘张三’	✅ 能，匹配最左的 name
WHERE `name` = ‘张三’ AND `age` = 20	✅ 能，匹配 name’+age
WHERE `name` = ‘张三’ AND `age` = 20 AND `gender` = ‘男’	✅ 能，匹配全部
WHERE `age` = 20 AND `gender` = ‘男’	❌ 不能，跳过了最左的 name
WHERE `name` = ‘张三’ AND `gender` = ‘男’	✅ 能，name 能用到，gender 用不到

💡 所以建复合索引的时候，要把查询频繁的、区分度高的字段放最左边，把范围查询的字段放右边。

7.5 索引操作：怎么加索引

-- 1. 创建普通索引：给name字段加索引
CREATE INDEX idx_user_name ON `user`(`name`);

-- 2. 创建唯一索引：给phone加唯一索引
CREATE UNIQUE INDEX idx_user_phone ON `user`(`phone`);

-- 3. 创建复合索引：给name、age、gender加复合索引
CREATE INDEX idx_user_name_age_gender ON `user`(`name`, `age`, `gender`);

-- 4. 查看表的所有索引
SHOW INDEX FROM `user`;

-- 5. 删除索引
DROP INDEX idx_user_name ON `user`;

7.6 索引失效：最容易踩的坑，加了索引也没用

很多人加了索引，但是查询还是很慢，因为索引失效了，也就是你写的 SQL，导致索引用不了，变成了全表扫描。

我们一个个来看，这些都是最容易踩的坑：

1. 对索引字段做函数操作

如果你对索引字段做函数操作，MySQL 就没法用索引了，因为索引存的是原始值，不是函数处理后的值。

反例（索引失效）：

1
2

-- 对create_time做了YEAR函数，索引失效
SELECT * FROM user WHERE YEAR(create_time) = 2026;

正例（索引生效）：

1
2

-- 用范围查询，不用函数，索引生效
SELECT * FROM user WHERE create_time >= '2026-01-01' AND create_time < '2027-01-01';

2. 模糊查询，开头用通配符

LIKE '%xxx'，开头的通配符，会导致索引失效，因为索引是有序的，开头不确定的话，没法匹配。

反例（索引失效）：

1
2

-- 开头的%，索引失效
SELECT * FROM user WHERE name LIKE '%张三';

正例（索引生效）：

1
2

-- 结尾的%，索引生效
SELECT * FROM user WHERE name LIKE '张三%';

3. 用 OR 连接没有索引的字段

如果 OR 的两个字段，一个有索引，一个没有，那整个查询都不会用索引。

反例（索引失效）：

1
2

-- name有索引，age没有，OR导致整个索引失效
SELECT * FROM user WHERE name = '张三' OR age = 20;

4. 隐式类型转换

如果字段是字符串，你传了数字，MySQL 会自动做类型转换，导致索引失效。

反例（索引失效）：

1
2

-- phone是字符串，你传了数字13800138001，隐式转换，索引失效
SELECT * FROM user WHERE phone = 13800138001;

正例（索引生效）：

1
2

-- 传字符串，索引生效
SELECT * FROM user WHERE phone = '13800138001';

5. 用 NOT、’!=、<>、IS NOT NULL

这些操作，会导致索引失效，因为 MySQL 觉得全表扫描更快。

7.7 怎么看索引有没有生效：Explain 执行计划

很多人加了索引，不知道有没有生效，这时候就可以用EXPLAIN，它能告诉你 SQL 的执行计划，索引有没有用到。

用法很简单，在 SQL 前面加 EXPLAIN：

`1`	`EXPLAIN SELECT * FROM user WHERE name = '张三';`

然后看结果里的type字段，这个是查询的类型，越好的类型，速度越快：

system > const > eq_ref > ref > range > index > ALL

如果type是ALL，那就是全表扫描，索引没生效！如果是ref、range这些，就是索引生效了。

还有key字段，显示的是用到的索引，如果这个是空的，就是没用到索引。

7.8 索引使用的最佳实践

不要给小表加索引：数据就几百条，全表扫描比索引还快
不要给区分度低的字段加索引：比如性别，只有男 / 女，加了索引也没用
不要给频繁修改的字段加索引：修改数据的时候，要同步修改索引，会变慢
索引不是越多越好：每个索引都会占用空间，而且会拖慢增删改的速度，一个表的索引不要超过 5 个
慢查询优化：开启慢查询日志，找到慢 SQL，然后给它们加索引

第八章：可视化工具：不用敲命令也能操作

很多人觉得命令行难，没关系，我们有可视化工具，点点鼠标就能操作！

8.1 Navicat：最流行的图形化工具

Navicat 是最常用的 MySQL 管理工具，界面友好，功能强大，新手首选。

连接数据库

打开 Navicat，点击左上角的「连接」→「MySQL」
连接名随便填，比如「本地 MySQL」
主机填localhost，端口 3306，用户名 root，密码填你安装时的密码
点击「测试连接」，成功就可以了

可视化建表

右键你的数据库→「新建表」
直接在表格里填字段名、类型、约束，点点鼠标就搞定
填完点保存，表就建好了，不用写 DDL！

数据操作

双击打开表，直接就能编辑数据，像 Excel 一样
导入导出数据，点点鼠标就能把 Excel 的数据导进去

8.2 MySQL Workbench：官方免费工具

Workbench 是 MySQL 官方出的免费工具，不用花钱，功能也很全。

操作和 Navicat 差不多，新手也能很快上手，而且是官方的，兼容性最好。

第九章：数据备份与恢复：防止数据丢了

新手最容易忽略的就是备份！等你误删了库，才发现没备份，哭都来不及！

我们用 MySQL 自带的mysqldump工具，这是最常用的逻辑备份工具，简单好用。

⚠️ 注意：mysqldump 是终端命令，要在 CMD/Linux 终端里执行，不是在 MySQL 客户端里！

9.1 备份操作

1. 单库备份（最常用）

1
2

# 备份test_db库，生成sql文件
mysqldump -u backup_user -p --default-character-set=utf8mb4 --single-transaction test_db > D:mysql_backuptest_db_backup.sql

2. 只备份表结构，不备份数据

1
2

# 只备份结构，用来迁移表结构
mysqldump -u root -p --no-data test_db > D:mysql_backuptest_db_struct.sql

3. 全实例备份，备份所有库

1
2

# 备份整个MySQL的所有库，用来迁移服务器
mysqldump -u root -p --all-databases > D:mysql_backupfull_backup.sql

9.2 恢复操作

1. 单库恢复

# 先创建空库
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS test_db DEFAULT CHARSET utf8mb4"
# 恢复备份
mysql -u root -p test_db < D:mysql_backuptest_db_backup.sql

2. 客户端里恢复

1
2
3

-- 也可以在MySQL客户端里用source命令
USE test_db;
source D:/mysql_backup/test_db_backup.sql; -- 注意路径用正斜杠

9.3 备份避坑

定期备份：最好每天自动备份，不要手动
备份后要验证：备份完了打开 sql 文件看看，有没有内容，别备份了个空文件
定期恢复演练：别等出事了才发现备份是坏的
备份路径不要有中文：不然会报错

第十章：完整实战：电商订单系统

学了这么多，我们来做一个完整的实战案例，电商订单系统，把所有知识点串起来！

10.1 建库建表

-- 1. 创建数据库
CREATE DATABASE IF NOT EXISTS shop CHARACTER SET utf8mb4;
USE shop;

-- 2. 用户表
CREATE TABLE users (
    id INT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '用户ID',
    username VARCHAR(50) NOT NULL UNIQUE COMMENT '用户名',
    phone VARCHAR(20) NOT NULL COMMENT '手机号',
    status TINYINT DEFAULT 1 COMMENT '状态:1启用0禁用',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '注册时间',
    PRIMARY KEY (id),
    INDEX idx_phone (phone)
) ENGINE=InnoDB COMMENT='用户表';

-- 3. 商品表
CREATE TABLE products (
    id INT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '商品ID',
    name VARCHAR(200) NOT NULL COMMENT '商品名称',
    price DECIMAL(10,2) UNSIGNED NOT NULL COMMENT '价格',
    stock INT UNSIGNED DEFAULT 0 COMMENT '库存',
    status TINYINT DEFAULT 1 COMMENT '上架状态',
    PRIMARY KEY (id),
    INDEX idx_name (name)
) ENGINE=InnoDB COMMENT='商品表';

-- 4. 订单表
CREATE TABLE orders (
    id INT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '订单ID',
    user_id INT UNSIGNED NOT NULL COMMENT '用户ID',
    total_amount DECIMAL(10,2) UNSIGNED NOT NULL COMMENT '订单金额',
    status ENUM('pending','paid','shipped','completed','cancelled') DEFAULT 'pending' COMMENT '订单状态',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    paid_at TIMESTAMP NULL COMMENT '支付时间',
    PRIMARY KEY (id),
    INDEX idx_user (user_id),
    INDEX idx_status (status),
    FOREIGN KEY (user_id) REFERENCES users(id)
) ENGINE=InnoDB COMMENT='订单表';

10.2 插入测试数据

-- 插入用户
INSERT INTO users(username, phone) VALUES
('张三', '13800138001'),
('李四', '13800138002'),
('王五', '13800138003');

-- 插入商品
INSERT INTO products(name, price, stock) VALUES
('笔记本电脑', 5999.00, 10),
('无线鼠标', 89.90, 100),
('机械键盘', 299.00, 50);

-- 插入订单
INSERT INTO orders(user_id, total_amount, status) VALUES
(1, 5999.00, 'paid'),
(1, 388.90, 'completed'),
(2, 89.90, 'pending');

10.3 复杂查询实战

-- 1. 查询每个用户的订单数和消费总额
SELECT 
    u.username,
    COUNT(o.id) AS 订单数,
    IFNULL(SUM(o.total_amount), 0) AS 消费总额
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
GROUP BY u.id
ORDER BY 消费总额 DESC;

-- 2. 查询已支付的订单，关联用户和商品
-- （这里我们可以扩展订单详情表，不过新手先理解这个）

第十一章：必避的 10 个坑

最后，总结一下最容易踩的坑，帮你少走弯路：

UPDATE/DELETE 忘记加 WHERE：这是最常见的，一不小心全表数据没了，执行前先 SELECT 看看对不对
字符集乱码：建库建表一定要用 utf8mb4，不要用 latin1，备份恢复也要指定字符集
密码忘记：root 密码一定要记牢，重置密码很麻烦
外键导致删不了表：有外键关联的话，要先删从表，或者关掉外键校验
大表 SELECT：大表查所有字段，会把数据库卡死，要啥查啥，加 LIMIT
长事务：事务不要开太久，会锁表，影响业务
索引建太多：索引不是越多越好，会拖慢增删改的速度
备份不验证：备份完了一定要看看备份文件有没有内容，别备份了个空的
root 用户到处用：生产环境不要用 root，要创建专用用户，最小权限原则
路径有中文：MySQL 对中文路径兼容性差，安装、备份的路径都用英文

附录：SQL 速查表

操作	SQL 语句
创建数据库	`CREATE DATABASE db DEFAULT CHARSET utf8mb4;`
切换数据库	`USE db;`
建表	`CREATE TABLE t(id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(50));`
插入	`INSERT INTO t(name) VALUES('test');`
更新	`UPDATE t SET name='test2' WHERE id=1;`
删除	`DELETE FROM t WHERE id=1;`
查询	`SELECT * FROM t WHERE id=1;`
分页	`SELECT * FROM t LIMIT 0,10;`
排序	`SELECT * FROM t ORDER BY id DESC;`
分组	`SELECT name,COUNT(*) FROM t GROUP BY name;`

写在最后

MySQL 是一个入门简单但内涵丰富的工具，这份教程带你从零基础入门，到掌握生产级的技能。学习数据库最重要的就是多练，把这些 SQL 都自己敲一遍，做几个小项目，很快就能上手了。

希望这份教程能帮你彻底搞定 MySQL，开启你的数据之旅！

RabbitMQ零基础教程（Go版）

Mon, 30 Mar 2026 19:45:57 +0800

前言

RabbitMQ 是目前最流行的开源消息中间件之一，它基于 AMQP 协议（Advanced Message Queuing Protocol），能够帮我们实现系统解耦、异步通信、流量削峰等功能，是微服务架构中必不可少的组件。

读完这份教程，你将学会：

RabbitMQ 的核心概念，再也不怕听不懂术语
如何在各种系统上快速安装部署 RabbitMQ
如何用 Go 语言连接和操作 RabbitMQ
RabbitMQ 的 6 种核心工作模式，以及它们的适用场景
生产环境必备的高级特性：消息确认、持久化、死信队列等

一、RabbitMQ 核心概念：用快递站帮你搞懂

很多新手刚接触 RabbitMQ 时，会被一堆术语搞晕：生产者、消费者、交换机、队列… 别担心，我们用生活中最常见的快递站来类比，保证你一看就懂。

1.1 核心组件类比

想象一下，你开了一家淘宝店，每天要给全国各地的用户发快递。你不会自己一个个送快递，而是把包裹交给快递站，由快递站来帮你完成后续的配送。

RabbitMQ 就相当于这个 快递站，它的各个组件对应快递站的不同角色：

`RabbitMQ` 术语	快递站类比	作用说明
生产者 (Producer)	发快递的你（淘宝卖家）	负责生产消息，把消息发送给 `RabbitMQ`
消费者 (Consumer)	收快递的买家	负责从 `RabbitMQ` 接收并处理消息
交换机 (Exchange)	快递分拣中心	接收你发来的包裹，根据地址把包裹分到不同的快递柜
队列 (Queue)	小区的快递柜	用来暂存包裹，买家什么时候有空什么时候来取
绑定 (Binding)	分拣中心到快递柜的路线	告诉分拣中心：XX 地址的包裹，要放到 XX 快递柜里
路由键 (Routing Key)	包裹上的收货地址	你发包裹时写的地址，用来告诉分拣中心这个包裹要送到哪（也就是目的地）
虚拟主机 (VHost)	独立的快递园区	用来隔离不同的业务，比如淘宝的快递和京东的快递各用一个园区，互不干扰

1.2 消息流转的完整流程

搞懂了这些角色，整个消息流转的过程就非常清晰了：

你（生产者）打包好商品，写好收货地址（路由键），把包裹交给快递站（RabbitMQ）
包裹先送到分拣中心（交换机）
分拣中心根据你写的地址，按照之前定好的路线（绑定），把包裹放到对应的快递柜（队列）里
买家（消费者）下班后来到小区，从对应的快递柜里取出包裹，完成签收

整个过程中：

你不需要等买家签收，交完包裹就可以去忙别的了（异步处理）
就算买家今天没空取，包裹也会一直存在快递柜里，等他明天来取（消息存储）
双 11 包裹爆仓时，快递柜能帮你暂存所有包裹，不会因为突然的流量把系统冲垮（流量削峰）

1.3 架构图直观理解

下面这张架构图，能帮你更直观地理解这些组件之间的关系：

二、环境搭建：5 分钟搞定 RabbitMQ 服务

接下来我们要把 RabbitMQ 服务跑起来，这里我最推荐你用 Docker 来安装，因为它最简单，一行命令就能搞定，不用管什么依赖、版本问题。当然，我也会给你提供其他系统的安装方式。

2.1 推荐方式：Docker 一键安装

如果你已经装了 Docker，只需要执行下面这一条命令：

`1`	`docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3-management`

第一次运行会自动下载镜像，等它下载完了，容器就会启动成功了。我这里已经是下载好了，所以直接就启动了。

解释一下这几个参数：

-p 5672:5672：这是 RabbitMQ 的通信端口，我们的 Go 程序就是通过这个端口连接 RabbitMQ 的
-p 15672:15672：这是 Web 管理界面的端口，装完之后我们可以通过浏览器来可视化管理 RabbitMQ
rabbitmq:3-management：这个镜像已经内置了管理插件，不用我们手动装了

执行完之后，等个几十秒，容器启动成功就好了。

2.2 其他系统的安装方式

如果你不想用 Docker，也可以用系统包管理器安装：

Ubuntu/Debian

# 安装 Erlang 环境（RabbitMQ 是用 Erlang 写的）
sudo apt-get update
sudo apt-get install erlang

# 安装 RabbitMQ
sudo apt-get install rabbitmq-server

# 启动服务
sudo systemctl start rabbitmq-server

# 启用管理插件
sudo rabbitmq-plugins enable rabbitmq_management

CentOS/RHEL

# 添加 yum 源
sudo vim /etc/yum.repos.d/rabbitmq.repo

# 写入以下内容
[rabbitmq_server]
name=rabbitmq_server
baseurl=https://packagecloud.io/rabbitmq/rabbitmq-server/el/7/$basearch
repo_gpgcheck=1
gpgcheck=1
enabled=1
gpgkey=https://packagecloud.io/rabbitmq/rabbitmq-server/gpgkey

# 安装
sudo yum install -y rabbitmq-server

# 启动服务
sudo systemctl start rabbitmq-server

# 启用管理插件
sudo rabbitmq-plugins enable rabbitmq_management

Windows

直接去官网下载安装包：https://www.rabbitmq.com/download.html 下载完之后一路下一步安装就行，安装完成后服务会自动启动。

2.3 访问 Web 管理界面

不管你用哪种方式安装，装完之后，打开浏览器，访问：

`1`	`http://localhost:15672`

你会看到这样的登录界面：

默认用户名：guest
默认密码：guest

登录进去之后，你就能看到 RabbitMQ 的管理后台了，长这样：

这个后台非常有用，你可以在这里查看队列、交换机、连接数，还能手动发消息、查看消息堆积情况，后面我们跑代码的时候，也可以在这里实时看到消息的流转。

注意：默认的 guest 用户只能从 localhost 访问，如果你的 RabbitMQ 是部署在远程服务器上，需要新建一个管理员用户，我会在后面的最佳实践部分讲。

2.4 Go 客户端安装

RabbitMQ 服务装好了，接下来我们要准备 Go 语言的客户端，用来连接和操作 RabbitMQ。

官方推荐的 Go 客户端是 amqp091-go，这是原来的 streadway/amqp 的官方维护版本，现在已经完全替代了旧的库。

创建一个新的 Go 项目（空项目即可），然后执行下面的命令安装依赖：

# 初始化项目（如果是新项目）
go mod init rabbitmq-demo

# 安装 RabbitMQ 客户端
go get github.com/rabbitmq/amqp091-go

好了，到这里，我们的环境就全部准备好了！接下来我们就可以开始写代码，一个个体验 RabbitMQ 的工作模式了。

三、入门实战：Hello World 简单队列

我们从最简单的 简单队列 模式开始，这是 RabbitMQ 最基础的用法，就像我们平时发消息给一个人，一对一的通信。

3.1 模式说明

简单队列的结构非常简单：

`1`	`生产者 -> 队列 -> 消费者`

生产者把消息发送到一个队列
消费者从这个队列里读取消息
一条消息只能被一个消费者消费一次

这个模式非常适合简单的点对点通信，比如：下单成功后，通知库存服务扣库存。

3.2 编写生产者代码

首先，我们写一个生产者，用来发送消息：

// producer.go
package main

import (
    "log"

    amqp "github.com/rabbitmq/amqp091-go"
)

// 错误处理的辅助函数
func failOnError(err error, msg string) {
    if err != nil {
        log.Panicf("%s: %s", msg, err)
    }
}

func main() {
    // 1. 连接到 RabbitMQ 服务器
    conn, err := amqp.Dial("amqp://guest:guest@localhost:5672/")
    failOnError(err, "无法连接到 RabbitMQ")
    defer conn.Close() // 函数结束时关闭连接

    // 2. 创建一个通道（Channel），所有的操作都是通过通道完成的
    ch, err := conn.Channel()
    failOnError(err, "无法创建通道")
    defer ch.Close()

    // 3. 声明一个队列，队列的名字叫 "hello"
    q, err := ch.QueueDeclare(
        "hello", // 队列名称
        false,   // 是否持久化（重启后队列是否保留）
        false,   // 是否自动删除（没有消费者时自动删除队列）
        false,   // 是否排他（只有当前连接能访问）
        false,   // 是否不等待
        nil,     // 额外参数
    )
    failOnError(err, "无法声明队列")

    // 4. 要发送的消息
    body := "Hello World! 这是我的第一条 RabbitMQ 消息"

    // 5. 发送消息
    err = ch.Publish(
        "",     // 交换机名称，这里用默认的交换机
        q.Name, // 路由键，这里就是队列的名字
        false,  // 是否强制
        false,  // 是否立即
        amqp.Publishing{
            // ContentType 是消息的内容类型，这里我们用 text/plain 表示纯文本
            ContentType: "text/plain", // 消息的内容类型
            Body:        []byte(body), // 消息的内容，转成字节数组
        })
    failOnError(err, "无法发送消息")

    log.Printf(" [x] 已发送消息: %s", body)
}

3.3 编写消费者代码

然后，我们写一个消费者，用来接收消息：

// consumer.go
package main

import (
	"log"

	amqp "github.com/rabbitmq/amqp091-go"
)

func failOnError(err error, msg string) {
	if err != nil {
		log.Panicf("%s: %s", msg, err)
	}
}

func main() {
	// 1. 同样的，先连接 RabbitMQ，创建通道
	conn, err := amqp.Dial("amqp://guest:guest@localhost:5672/")
	failOnError(err, "无法连接到 RabbitMQ")
	defer conn.Close()

	// 2. 创建一个通道（Channel），所有的操作都是通过通道完成的
	ch, err := conn.Channel()
	failOnError(err, "无法创建通道")
	defer ch.Close()

	// 3. 同样声明队列，这里要和生产者的队列名一致
	// 为什么要两边都声明？因为我们不知道生产者和消费者谁先启动
	// 如果队列已经存在，声明操作不会做任何事，只会返回队列的信息；如果队列不存在，声明操作会创建一个新的队列，所以很安全
	q, err := ch.QueueDeclare(
		"hello", // 队列名称
		false,   // 是否持久化（重启后队列是否保留）
		false,   // 是否自动删除（没有消费者时自动删除队列）
		false,   // 是否排他（只有当前连接能访问）
		false,   // 是否不等待
		nil,     // 额外参数
	)
	failOnError(err, "无法声明队列")

	// 4. 注册消费者，监听这个队列的消息
	msgs, err := ch.Consume(
		q.Name, // 要监听的队列名称
		"",     // 消费者名称，空的话服务器会自动生成
		true,   // 是否自动确认（后面会详细讲）
		false,  // 是否排他（只有当前连接能访问）
		false,  // 是否本地
		false,  // 是否不等待
		nil,    // 额外参数
	)
	failOnError(err, "无法注册消费者")

	// 5. 启动一个协程来处理消息
	// 因为接收消息是阻塞的，所以我们要放到协程里，不阻塞主程序
	go func() {
		for d := range msgs {
			// 收到消息了！
			log.Printf(" [x] 收到消息: %s", d.Body)
		}
	}()

	log.Printf(" [*] 等待消息中... 按 CTRL+C 退出")
	// 阻塞主程序，不让它退出
	<-make(chan bool)
}

3.4 运行测试

现在我们来运行一下：

首先打开另一个终端，运行生产者：

`1`	`go run producer.go`

生产者这边会输出： [x] 已发送消息: Hello World! 这是我的第一条 RabbitMQ 消息

在生产者终端看到这个输出，说明消息已经成功发送到 RabbitMQ 了。

同时我们可以在 Web 管理后台的 Queues 标签页里看到 hello 队列，点击进去可以看到消息数量是 1，说明消息已经进入队列了。

在下方的 Get messages 标签页里，我们也能看到这条消息的内容：

再先打开一个终端，运行消费者：

`1`	`go run consumer.go`

你会看到输出： [*] 等待消息中... 按 CTRL+C 退出，说明消费者已经启动，在等消息了。然后会再输出： [x] 收到消息: Hello World! 这是我的第一条 RabbitMQ 消息，说明消费者成功接收到了消息。

我们也可以在 Web 管理后台看到，hello 队列里的消息数量从 1 变成了 0，说明消息已经被消费者取走了。

完美！我们的第一个 RabbitMQ 程序就跑通了！

四、工作队列：任务分发与负载均衡

接下来我们看第二个模式：工作队列（Work Queue）。

4.1 模式说明

工作队列的结构是这样的：

`1`	`生产者 -> 队列 -> 多个消费者`

它的作用是什么呢？当我们有很多耗时的任务要处理时，我们可以启动多个消费者，让它们一起分担这些任务，实现负载均衡。

比如，我们有 10 个图片压缩的任务，启动两个消费者，每个消费者处理 5 个，这样处理速度就快了一倍。

4.2 轮询分发 vs 公平分发

RabbitMQ 默认的分发方式是轮询分发：它会把任务按顺序一个一个分给消费者，不管这个消费者有没有处理完上一个任务。

这就会有个问题：如果有一个任务特别耗时，另一个很快，就会导致一个消费者忙死，另一个闲死。

所以我们一般会用公平分发：告诉 RabbitMQ，一次只给一个消费者发一个任务，等这个消费者处理完了，再给它发下一个。这样就能保证任务会均匀地分给空闲的消费者。

4.3 代码实现

我们来写个例子，模拟任务处理：

生产者：发送任务

// task_producer.go
package main

import (
	"log"
	"strconv"
	"strings"
	"time"

	amqp "github.com/rabbitmq/amqp091-go"
)

func failOnError(err error, msg string) {
	if err != nil {
		log.Panicf("%s: %s", msg, err)
	}
}

func main() {
	conn, err := amqp.Dial("amqp://guest:guest@localhost:5672/")
	failOnError(err, "无法连接到 RabbitMQ")
	defer conn.Close()

	ch, err := conn.Channel()
	failOnError(err, "无法创建通道")
	defer ch.Close()

	// 声明队列，这次我们把队列设为持久化
	q, err := ch.QueueDeclare(
		"task_queue", // 队列名
		true,         // 持久化，RabbitMQ 重启后队列不丢
		false,        // 不自动删除
		false,        // 不排他
		false,        // 不等待
		nil,
	)
	failOnError(err, "无法声明队列")

	// 发送10个任务
	for i := 0; i < 10; i++ {
		// 任务内容，我们用点来表示任务的耗时，一个点代表1秒
		// 比如 "task3 ..." 表示这个任务要处理3秒
		// strconv.Itoa(i)：把整数 i 转换成字符串，这样我们就能看到每个任务的编号了
		// strings.Repeat(".", i/2)：重复 i/2 次点号，这样任务的耗时就会随着 i 的增加而增加
		task := "task" + strconv.Itoa(i) + " " + strings.Repeat(".", i/2)
		err = ch.Publish(
			"",     // 默认交换机
			q.Name, // 路由键
			false,
			false,
			amqp.Publishing{
				// 消息也设为持久化，这样重启后消息不丢
				DeliveryMode: amqp.Persistent,
				ContentType:  "text/plain",
				Body:         []byte(task),
			})
		failOnError(err, "无法发送消息")
		log.Printf(" [x] 发送任务: %s", task)

		time.Sleep(100 * time.Millisecond)
	}
}

消费者：处理任务

// worker.go
package main

import (
	"bytes"
	"log"
	"time"

	amqp "github.com/rabbitmq/amqp091-go"
)

func failOnError(err error, msg string) {
	if err != nil {
		log.Panicf("%s: %s", msg, err)
	}
}

func main() {
	conn, err := amqp.Dial("amqp://guest:guest@localhost:5672/")
	failOnError(err, "无法连接到 RabbitMQ")
	defer conn.Close()

	ch, err := conn.Channel()
	failOnError(err, "无法创建通道")
	defer ch.Close()

	q, err := ch.QueueDeclare(
		"task_queue", true, false, false, false, nil,
	)
	failOnError(err, "无法声明队列")

	// 关键！设置预取计数，开启公平分发
	// Qos 是 Quality of Service 的缩写，意思是服务质量，这个设置告诉 RabbitMQ 在同一时间只给一个消费者分发一个消息，直到这个消费者处理完了并确认了这个消息，RabbitMQ 才会给它分发下一个消息。这样就能实现公平分发了，不会让某个消费者因为处理慢而积压大量消息。
	// 告诉 RabbitMQ，一次只给我一个任务，我处理完了你再给我下一个
	err = ch.Qos(
		1,     // 预取数量
		0,     // 预取大小
		false, // 是否全局
	)
	failOnError(err, "无法设置 Qos")

	// 注册消费者，注意这里我们把自动确认关了，这样我们就可以在处理完消息后手动确认。
	msgs, err := ch.Consume(
		q.Name, "",
		false, // 自动确认设为 false，我们要手动确认
		false, false, false, nil,
	)
	failOnError(err, "无法注册消费者")

	go func() {
		for d := range msgs {
			log.Printf(" [x] 开始处理任务: %s", d.Body)

			// 模拟任务处理，点的数量就是耗时
			t := time.Duration(bytes.Count(d.Body, []byte("."))) * time.Second
			time.Sleep(t)

			log.Printf(" [x] 任务处理完成: %s", d.Body)

			// 手动确认消息，告诉 RabbitMQ：这个消息我处理完了，你可以删了
			d.Ack(false)
		}
	}()

	log.Printf(" [*] 工作进程已启动，等待任务...")
	<-make(chan bool)
}

4.4 运行测试

现在我们来测试一下：

1个工作进程 : 1个生产者先启动工作进程：

`1`	`go run worker.go`

你会看到输出： [*] 工作进程已启动，等待任务...，说明消费者已经启动了。

然后启动生产者：

`1`	`go run task_producer.go`

你会看到，生产者发送了 10 个任务，工作进程一个人吃了 10 个任务，处理完一个才处理下一个。

2个工作进程 : 1个生产者启动两个工作进程，打开两个终端，都运行：

`1`	`go run worker.go`

然后运行生产者：

`1`	`go run task_producer.go`

你会看到，两个工作进程会自动分担这 10 个任务，快的消费者会处理更多的任务，慢的也不会被拖累，这就是公平分发的效果。

这里要重点注意：我们把自动确认关了，用了手动确认。这非常重要！如果消费者处理到一半崩溃了，手动确认的话，RabbitMQ 会把这个任务重新放回队列，交给另一个消费者处理，不会丢消息。

五、发布订阅：广播消息给所有消费者

接下来是 发布 / 订阅（Publish/Subscribe） 模式，这个模式下，一条消息会被发送给所有的消费者，也就是广播。

5.1 模式说明

发布订阅的结构是这样的：

`1`	`生产者 -> 交换机(Fanout) -> 多个队列 -> 多个消费者`

这里我们用到了 Fanout 类型的交换机，这种交换机的作用很简单：它会把收到的所有消息，广播给所有绑定到它的队列，完全不管路由键是什么。

比如，我们做一个日志系统，所有服务的日志都发给这个交换机，然后：

一个消费者把日志存到磁盘
一个消费者把日志打印到屏幕
一个消费者把日志发到监控系统所有消费者都能收到同一条日志消息，互不干扰。

5.2 代码实现

生产者：发送日志

// log_producer.go
package main

import (
	"context"
	"log"
	"strconv"
	"time"

	amqp "github.com/rabbitmq/amqp091-go"
)

func failOnError(err error, msg string) {
	if err != nil {
		log.Panicf("%s: %s", msg, err)
	}
}

func main() {
	conn, err := amqp.Dial("amqp://guest:guest@localhost:5672/")
	failOnError(err, "无法连接到 RabbitMQ")
	defer conn.Close()

	ch, err := conn.Channel()
	failOnError(err, "无法创建通道")
	defer ch.Close()

	// 声明一个 Fanout 类型的交换机
	err = ch.ExchangeDeclare(
		"logs",   // 交换机名称
		"fanout", // 类型：fanout 就是广播
		true,     // 持久化
		false,    // 自动删除
		false,    // 内部
		false,    // 不等待
		nil,
	)
	failOnError(err, "无法声明交换机")

	// 每隔1秒发一条日志
	for i := 0; ; i++ {
		logMsg := "这是一条日志消息，序号: " + strconv.Itoa(i)

		// 发送消息到交换机
		err = ch.PublishWithContext(
			context.Background(),
			"logs", // 交换机名称
			"",     // 路由键，fanout 模式下这个参数会被忽略，随便写什么都行
			false, false,
			amqp.Publishing{
				ContentType: "text/plain",
				Body:        []byte(logMsg),
			})
		failOnError(err, "无法发送消息")
		log.Printf(" [x] 发送日志: %s", logMsg)

		time.Sleep(1 * time.Second)
	}
}

消费者 1：打印日志到屏幕

// log_console.go
package main

import (
	"log"

	amqp "github.com/rabbitmq/amqp091-go"
)

func failOnError(err error, msg string) {
	if err != nil {
		log.Panicf("%s: %s", msg, err)
	}
}

func main() {
	conn, err := amqp.Dial("amqp://guest:guest@localhost:5672/")
	failOnError(err, "无法连接到 RabbitMQ")
	defer conn.Close()

	ch, err := conn.Channel()
	failOnError(err, "无法创建通道")
	defer ch.Close()

	// 同样声明交换机，要和生产者的一致，否则消费者无法接收到消息
	err = ch.ExchangeDeclare("logs", "fanout", true, false, false, false, nil)
	failOnError(err, "无法声明交换机")

	// 而且我们把 exclusive 设为 true，这样消费者断开连接后，队列会自动删除
	q, err := ch.QueueDeclare(
		"log_console_queue", // 队列名
		false,               // 不持久化
		false,               // 不自动删除
		true,                // 排他，连接断了就删
		false,               // 不等待
		nil,
	)
	failOnError(err, "无法声明队列")

	// 把队列绑定到交换机上
	err = ch.QueueBind(
		q.Name, // 队列名
		"",     // 路由键，fanout 模式下忽略
		"logs", // 交换机名
		false,
		nil,
	)
	failOnError(err, "无法绑定队列")

	// 消费消息
	msgs, err := ch.Consume(q.Name, "", true, false, false, false, nil)
	failOnError(err, "无法注册消费者")

	go func() {
		for d := range msgs {
			log.Printf(" [控制台消费者] 收到日志: %s", d.Body)
		}
	}()

	log.Println(" [*] 控制台日志消费者已启动")
	<-make(chan bool)
}

消费者 2：把日志存到文件

// log_file.go
package main

import (
	"log"
	"os"

	amqp "github.com/rabbitmq/amqp091-go"
)

func failOnError(err error, msg string) {
	if err != nil {
		log.Panicf("%s: %s", msg, err)
	}
}

func main() {
	conn, err := amqp.Dial("amqp://guest:guest@localhost:5672/")
	failOnError(err, "无法连接到 RabbitMQ")
	defer conn.Close()

	ch, err := conn.Channel()
	failOnError(err, "无法创建通道")
	defer ch.Close()

	err = ch.ExchangeDeclare("logs", "fanout", true, false, false, false, nil)
	failOnError(err, "无法声明交换机")

	q, err := ch.QueueDeclare("log_file_queue", false, false, true, false, nil)
	failOnError(err, "无法声明队列")

	err = ch.QueueBind(q.Name, "", "logs", false, nil)
	failOnError(err, "无法绑定队列")

	// 打开文件，准备写日志
	f, err := os.OpenFile("app.log", os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
	if err != nil {
		log.Fatal(err)
	}
	defer f.Close()

	msgs, err := ch.Consume(q.Name, "", true, false, false, false, nil)
	failOnError(err, "无法注册消费者")

	go func() {
		for d := range msgs {
			logMsg := string(d.Body)
			log.Printf(" [文件消费者] 保存日志到文件: %s", logMsg)
			// 写入文件
			f.WriteString(logMsg + "\n")
			f.Sync()
		}
	}()

	log.Println(" [*] 文件日志消费者已启动")
	<-make(chan bool)
}

5.3 运行测试

现在运行一下:

先启动控制台消费者：

`1`	`go run log_console.go`

再启动文件消费者：

`1`	`go run log_file.go`

最后启动生产者：

`1`	`go run log_producer.go`

你会发现，两个消费者都能收到所有的日志消息！生产者发一条，两个消费者各收到一条，完美实现了广播的效果。

六、路由模式：精准定向分发消息

接下来是路由模式（Routing），这个模式下，我们可以根据消息的类型，把消息发给指定的消费者。

6.1 模式说明

路由模式用的是 Direct 类型的交换机，这种交换机会根据路由键的精确匹配来转发消息。

比如，我们还是做日志系统，这次我们想：

error 级别的日志，存到磁盘，用来排查问题
info、warning 级别的日志，只打印到屏幕

那我们就可以：

生产者发消息时，给 error 日志的路由键设为 error，info 的设为 info，warning 的设为 warning
存磁盘的消费者，只绑定 error 这个路由键
打印屏幕的消费者，绑定 info 和 warning 两个路由键

这样，error 日志两个消费者都能收到，info 日志只有屏幕消费者能收到，非常灵活。

6.2 代码实现

生产者：按级别发日志

// routing_producer.go
package main

import (
    "context"
    "log"
    "time"

    amqp "github.com/rabbitmq/amqp091-go"
)

func failOnError(err error, msg string) {
    if err != nil {
        log.Panicf("%s: %s", msg, err)
    }
}

func main() {
    conn, err := amqp.Dial("amqp://guest:guest@localhost:5672/")
    failOnError(err, "无法连接到 RabbitMQ")
    defer conn.Close()

    ch, err := conn.Channel()
    failOnError(err, "无法创建通道")
    defer ch.Close()

    // 声明 Direct 类型的交换机
    err = ch.ExchangeDeclare(
        "logs_direct", // 交换机名
        "direct",      // 类型：direct
        true, false, false, false, nil,
    )
    failOnError(err, "无法声明交换机")

    // 模拟发不同级别的日志
    logs := []struct {
        level   string
        message string
    }{
        {"info", "这是一条普通的信息日志"},
        {"warning", "这是一条警告日志"},
        {"error", "这是一条错误日志！系统出问题了"},
    }

    for _, l := range logs {
        err = ch.PublishWithContext(
            context.Background(),
            "logs_direct", // 交换机
            l.level,       // 路由键，就是日志级别
            false, false,
            amqp.Publishing{
                ContentType: "text/plain",
                Body:        []byte(l.message),
            })
        failOnError(err, "无法发送消息")
        log.Printf(" [x] 发送[%s]日志: %s", l.level, l.message)

        time.Sleep(500 * time.Millisecond)
    }
}

消费者 1：只接收 error 日志，存到磁盘

// error_consumer.go
package main

import (
    "log"
    "os"

    amqp "github.com/rabbitmq/amqp091-go"
)

func failOnError(err error, msg string) {
    if err != nil {
        log.Panicf("%s: %s", msg, err)
    }
}

func main() {
    conn, err := amqp.Dial("amqp://guest:guest@localhost:5672/")
    failOnError(err, "无法连接到 RabbitMQ")
    defer conn.Close()

    ch, err := conn.Channel()
    failOnError(err, "无法创建通道")
    defer ch.Close()

    err = ch.ExchangeDeclare("logs_direct", "direct", true, false, false, false, nil)
    failOnError(err, "无法声明交换机")

    q, err := ch.QueueDeclare("", false, false, true, false, nil)
    failOnError(err, "无法声明队列")

    // 只绑定 error 路由键
    err = ch.QueueBind(q.Name, "error", "logs_direct", false, nil)
    failOnError(err, "无法绑定队列")

    f, err := os.OpenFile("error.log", os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
    if err != nil {
        log.Fatal(err)
    }
    defer f.Close()

    msgs, err := ch.Consume(q.Name, "", true, false, false, false, nil)
    failOnError(err, "无法注册消费者")

    go func() {
        for d := range msgs {
            logMsg := string(d.Body)
            log.Printf(" [Error消费者] 保存错误日志: %s", logMsg)
            f.WriteString(logMsg + "\n")
            f.Sync()
        }
    }()

    log.Println(" [*] Error 消费者已启动，只处理 error 日志")
    <-make(chan bool)
}

消费者 2：接收所有日志，打印到屏幕

// all_log_consumer.go
package main

import (
    "log"

    amqp "github.com/rabbitmq/amqp091-go"
)

func failOnError(err error, msg string) {
    if err != nil {
        log.Panicf("%s: %s", msg, err)
    }
}

func main() {
    conn, err := amqp.Dial("amqp://guest:guest@localhost:5672/")
    failOnError(err, "无法连接到 RabbitMQ")
    defer conn.Close()

    ch, err := conn.Channel()
    failOnError(err, "无法创建通道")
    defer ch.Close()

    err = ch.ExchangeDeclare("logs_direct", "direct", true, false, false, false, nil)
    failOnError(err, "无法声明交换机")

    q, err := ch.QueueDeclare("", false, false, true, false, nil)
    failOnError(err, "无法声明队列")

    // 绑定 info 路由键
    err = ch.QueueBind(q.Name, "info", "logs_direct", false, nil)
    failOnError(err, "无法绑定队列")
    // 绑定 warning 路由键
    err = ch.QueueBind(q.Name, "warning", "logs_direct", false, nil)
    failOnError(err, "无法绑定队列")
    // 绑定 error 路由键
    err = ch.QueueBind(q.Name, "error", "logs_direct", false, nil)
    failOnError(err, "无法绑定队列")

    msgs, err := ch.Consume(q.Name, "", true, false, false, false, nil)
    failOnError(err, "无法注册消费者")

    go func() {
        for d := range msgs {
            log.Printf(" [控制台消费者] 收到日志: %s", d.Body)
        }
    }()

    log.Println(" [*] 控制台消费者已启动，处理所有级别日志")
    <-make(chan bool)
}

6.3 运行测试

运行一下：

启动 error 消费者：

`1`	`go run error_consumer.go`

启动控制台消费者：

`1`	`go run all_log_consumer.go`

启动生产者：

`1`	`go run routing_producer.go`

你会看到：

error 日志，两个消费者都收到了
info 和 warning 日志，只有控制台消费者收到了

完美！这就是精准路由的效果。

七、主题模式：通配符灵活路由

接下来是最灵活的主题模式（Topic），这个模式下，路由键支持通配符，我们可以做更复杂的消息过滤。

7.1 模式说明

主题模式用的是 Topic 类型的交换机，它和 Direct 很像，但是它的路由键匹配支持通配符：

*：匹配一个单词
#：匹配零个或多个单词

这里的单词，是用点 . 分隔的。

比如，我们的路由键可以是 order.create、order.update、user.register 这种格式，然后：

order.*：可以匹配 order.create、order.update，但是匹配不了 user.register
#：可以匹配所有的路由键
*.create：可以匹配 order.create、user.create

这个模式非常适合多层级的消息路由，比如我们要按模块、按操作类型来过滤消息。

7.2 代码实现

我们来做一个订单和用户的消息通知系统：

生产者：发送不同类型的消息

// topic_producer.go
package main

import (
	"context"
	"log"
	"time"

	amqp "github.com/rabbitmq/amqp091-go"
)

func failOnError(err error, msg string) {
	if err != nil {
		log.Panicf("%s: %s", msg, err)
	}
}

func main() {
	conn, err := amqp.Dial("amqp://guest:guest@localhost:5672/")
	failOnError(err, "无法连接到 RabbitMQ")
	defer conn.Close()

	ch, err := conn.Channel()
	failOnError(err, "无法创建通道")
	defer ch.Close()

	// 声明 Topic 类型的交换机
	err = ch.ExchangeDeclare(
		"events_topic", // 交换机名
		"topic",        // 类型：topic
		true, false, false, false, nil,
	)
	failOnError(err, "无法声明交换机")

	// 模拟发送不同的事件
	events := []struct {
		routingKey string
		message    string
	}{
		{"order.create", "用户创建了新订单"},
		{"order.update", "订单状态更新了"},
		{"user.register", "新用户注册了"},
		{"user.login", "用户登录了"},
	}

	for _, e := range events {
		// Publish只能发送消息到交换机，路由键由我们指定，消费者根据路由键来决定是否接收消息
		// 而PublishWithContext可以指定上下文，支持超时等功能
		err = ch.PublishWithContext(
			context.Background(), // 上下文：这里使用背景上下文，表示没有特定的超时或取消条件
			"events_topic",       // 交换机名
			e.routingKey,         // 路由键，消费者根据这个键来决定是否接收消息
			false, false,
			amqp.Publishing{
				ContentType: "text/plain",
				Body:        []byte(e.message),
			})
		failOnError(err, "无法发送消息")
		log.Printf(" [x] 发送事件[%s]: %s", e.routingKey, e.message)

		time.Sleep(500 * time.Millisecond)
	}
}

消费者 1：只关心订单相关的事件

// order_consumer.go
package main

import (
    "log"

    amqp "github.com/rabbitmq/amqp091-go"
)

func failOnError(err error, msg string) {
    if err != nil {
        log.Panicf("%s: %s", msg, err)
    }
}

func main() {
    conn, err := amqp.Dial("amqp://guest:guest@localhost:5672/")
    failOnError(err, "无法连接到 RabbitMQ")
    defer conn.Close()

    ch, err := conn.Channel()
    failOnError(err, "无法创建通道")
    defer ch.Close()

    err = ch.ExchangeDeclare("events_topic", "topic", true, false, false, false, nil)
    failOnError(err, "无法声明交换机")

    q, err := ch.QueueDeclare("", false, false, true, false, nil)
    failOnError(err, "无法声明队列")

    // 绑定 order.*，匹配所有 order 开头的事件
    err = ch.QueueBind(q.Name, "order.*", "events_topic", false, nil)
    failOnError(err, "无法绑定队列")

    msgs, err := ch.Consume(q.Name, "", true, false, false, false, nil)
    failOnError(err, "无法注册消费者")

    go func() {
        for d := range msgs {
            log.Printf(" [订单服务] 收到事件: %s", d.Body)
        }
    }()

    log.Println(" [*] 订单服务消费者已启动，只处理订单相关事件")
    <-make(chan bool)
}

消费者 2：关心所有的事件

// all_event_consumer.go
package main

import (
    "log"

    amqp "github.com/rabbitmq/amqp091-go"
)

func failOnError(err error, msg string) {
    if err != nil {
        log.Panicf("%s: %s", msg, err)
    }
}

func main() {
    conn, err := amqp.Dial("amqp://guest:guest@localhost:5672/")
    failOnError(err, "无法连接到 RabbitMQ")
    defer conn.Close()

    ch, err := conn.Channel()
    failOnError(err, "无法创建通道")
    defer ch.Close()

    err = ch.ExchangeDeclare("events_topic", "topic", true, false, false, false, nil)
    failOnError(err, "无法声明交换机")

    q, err := ch.QueueDeclare("", false, false, true, false, nil)
    failOnError(err, "无法声明队列")

    // 绑定 #，匹配所有的事件
    err = ch.QueueBind(q.Name, "#", "events_topic", false, nil)
    failOnError(err, "无法绑定队列")

    msgs, err := ch.Consume(q.Name, "", true, false, false, false, nil)
    failOnError(err, "无法注册消费者")

    go func() {
        for d := range msgs {
            log.Printf(" [监控服务] 收到所有事件: %s", d.Body)
        }
    }()

    log.Println(" [*] 监控服务消费者已启动，处理所有事件")
    <-make(chan bool)
}

7.3 运行测试

运行一下：

启动订单消费者：

`1`	`go run order_consumer.go`

启动监控消费者：

`1`	`go run all_event_consumer.go`

启动生产者：

`1`	`go run topic_producer.go`

你会看到：

订单相关的两个事件，两个消费者都收到了
用户相关的两个事件，只有监控消费者收到了

这就是主题模式的灵活之处，你可以用通配符很方便地做各种消息过滤。

八、RPC 模式：同步远程调用

前面的模式都是异步的，但是有时候我们需要同步的调用：我发一个请求，然后等你给我返回结果，这就是 RPC（远程过程调用）模式。

8.1 模式说明

RPC 模式的流程是这样的：

客户端发送一个请求消息，同时指定两个东西：
- reply_to：告诉服务端，处理完结果要把响应发到哪个队列
- correlation_id：请求的唯一 ID，用来区分不同的请求
服务端收到请求，处理，然后把响应发到 reply_to 指定的队列，并且带上 correlation_id
客户端监听响应队列，根据 correlation_id 找到对应的响应

这样就实现了同步的远程调用。

8.2 代码实现

我们来实现一个计算斐波那契数的 RPC 服务：

RPC 服务端

// rpc_server.go
package main

import (
    "log"
    "strconv"

    amqp "github.com/rabbitmq/amqp091-go"
)

func failOnError(err error, msg string) {
    if err != nil {
        log.Panicf("%s: %s", msg, err)
    }
}

// 计算斐波那契数
func fib(n int) int {
    if n == 0 {
        return 0
    }
    if n == 1 {
        return 1
    }
    return fib(n-1) + fib(n-2)
}

func main() {
    conn, err := amqp.Dial("amqp://guest:guest@localhost:5672/")
    failOnError(err, "无法连接到 RabbitMQ")
    defer conn.Close()

    ch, err := conn.Channel()
    failOnError(err, "无法创建通道")
    defer ch.Close()

    // 声明 RPC 请求队列
    q, err := ch.QueueDeclare(
        "rpc_queue", // 请求队列名
        false, false, false, false, nil,
    )
    failOnError(err, "无法声明队列")

    // 设置 Qos，保证公平分发
    err = ch.Qos(1, 0, false)
    failOnError(err, "无法设置 Qos")

    msgs, err := ch.Consume(
        q.Name, "", false, false, false, false, nil,
    )
    failOnError(err, "无法注册消费者")

    log.Println(" [*] RPC 服务已启动，等待请求...")

    for d := range msgs {
        // 解析请求参数
        n, err := strconv.Atoi(string(d.Body))
        if err != nil {
            log.Printf("无效的参数: %s", d.Body)
            d.Ack(false)
            continue
        }

        log.Printf(" [.] 计算 fib(%d)", n)
        // 计算结果
        response := fib(n)

        // 把响应发回给客户端
        err = ch.Publish(
            "", // 默认交换机
            d.ReplyTo, // 客户端指定的响应队列
            false, false,
            amqp.Publishing{
                ContentType:   "text/plain",
                CorrelationId: d.CorrelationId, // 带上请求的ID
                Body:          []byte(strconv.Itoa(response)),
            })
        failOnError(err, "无法发送响应")

        // 确认请求消息
        d.Ack(false)
    }
}

RPC 客户端

// rpc_client.go
package main

import (
    "log"
    "math/rand"
    "strconv"
    "time"

    amqp "github.com/rabbitmq/amqp091-go"
)

func failOnError(err error, msg string) {
    if err != nil {
        log.Panicf("%s: %s", msg, err)
    }
}

type RPCClient struct {
    conn         *amqp.Connection
    channel      *amqp.Channel
    callbackQueue amqp.Queue
    corrID       string
    responses    map[string]chan string
}

func NewRPCClient() *RPCClient {
    conn, err := amqp.Dial("amqp://guest:guest@localhost:5672/")
    failOnError(err, "无法连接到 RabbitMQ")

    ch, err := conn.Channel()
    failOnError(err, "无法创建通道")

    // 声明回调队列，用来接收响应
    callbackQueue, err := ch.QueueDeclare(
        "", false, false, true, false, nil,
    )
    failOnError(err, "无法声明回调队列")

    // 监听回调队列
    msgs, err := ch.Consume(
        callbackQueue.Name, "", true, false, false, false, nil,
    )
    failOnError(err, "无法注册消费者")

    client := &RPCClient{
        conn:         conn,
        channel:      ch,
        callbackQueue: callbackQueue,
        responses:    make(map[string]chan string),
    }

    // 后台协程处理响应
    go client.handleResponses(msgs)

    return client
}

func (c *RPCClient) handleResponses(msgs <-chan amqp.Delivery) {
    for d := range msgs {
        // 根据 correlationId 找到对应的响应通道
        corrId := d.CorrelationId
        if ch, ok := c.responses[corrId]; ok {
            ch <- string(d.Body)
        }
    }
}

func (c *RPCClient) Call(n int) (string, error) {
    // 生成唯一的 correlationId
    c.corrID = strconv.Itoa(rand.Intn(999999))
    ch := make(chan string)
    c.responses[c.corrID] = ch

    // 发送请求
    err := c.channel.Publish(
        "", "rpc_queue", false, false,
        amqp.Publishing{
            ContentType:   "text/plain",
            CorrelationId: c.corrID,
            ReplyTo:       c.callbackQueue.Name, // 告诉服务端响应发到哪
            Body:          []byte(strconv.Itoa(n)),
        })
    failOnError(err, "无法发送请求")

    // 等待响应
    response := <-ch
    delete(c.responses, c.corrID)
    return response, nil
}

func (c *RPCClient) Close() {
    c.conn.Close()
}

func main() {
    client := NewRPCClient()
    defer client.Close()

    // 调用 RPC，计算 fib(30)
    log.Println(" [x] 请求 fib(30)")
    res, err := client.Call(30)
    failOnError(err, "RPC 调用失败")

    log.Printf(" [.] 结果: %s", res)
}

8.3 运行测试

运行一下：

先启动服务端：

`1`	`go run rpc_server.go`

然后启动客户端：

`1`	`go run rpc_client.go`

客户端会输出：

1
2

[x] 请求 fib(30)
[.] 结果: 832040

我们就实现了一个基于 RabbitMQ 的 RPC 调用。

可以单独运行 rpc_client.go ，然后去 Web 管理界面查看 rpc_queue 队列，你会看到客户端发出的请求消息，服务端处理完后，消息就会从队列里消失。

九、生产环境必备：高级特性

到这里，RabbitMQ 的核心工作模式我们就都讲完了，接下来我们讲几个生产环境必须要掌握的高级特性。

9.1 消息确认机制（ACK）

前面我们已经提到过，消息确认机制是保证消息不丢失的关键。

当你把 autoAck 设为 true 时，RabbitMQ 把消息发出去之后，就立刻把消息删了，不管消费者有没有处理完。如果消费者刚收到消息，还没处理就崩溃了，那这个消息就丢了。

而当你把 autoAck 设为 false 时，RabbitMQ 会等消费者手动调用 d.Ack() 之后，才会把消息删掉。如果消费者崩溃了，RabbitMQ 会把这个消息重新放回队列，发给其他消费者，保证消息不会丢。

除了 Ack，还有两个方法：

d.Nack(false, true)：拒绝这个消息，并且让它重新入队，用来重试
d.Nack(false, false)：拒绝这个消息，并且直接丢弃，用来处理坏消息

9.2 消息持久化

持久化是为了保证 RabbitMQ 重启之后，消息不会丢。要实现完整的持久化，你需要同时设置三个地方：

队列的 durable 参数设为 true：这样 RabbitMQ 重启后，队列不会丢
消息的 DeliveryMode 设为 amqp.Persistent：这样消息会被存到磁盘，重启后不会丢
交换机的 durable 参数设为 true：这样交换机重启后不会丢

注意：这三个要同时设置，缺一不可！不然还是会丢消息。

9.3 发布确认（Publisher Confirm）

前面的 ACK 是消费者给 RabbitMQ 的确认，那生产者怎么知道消息真的被 RabbitMQ 收到了呢？这就需要发布确认机制。

开启发布确认后，RabbitMQ 收到消息后，会给生产者发一个确认，告诉生产者：我收到了。如果没收到，生产者就可以重试。

代码示例：

// 开启发布确认
err = ch.Confirm(false)
failOnError(err, "无法开启确认")

// 创建一个通道来接收确认
confirms := ch.NotifyPublish(make(chan amqp.Confirmation, 1))

go func() {
    for confirm := range confirms {
        if confirm.Ack {
            log.Printf("消息 %d 已被服务器确认", confirm.DeliveryTag)
        } else {
            log.Printf("消息 %d 被服务器拒绝了", confirm.DeliveryTag)
            // 重试发送
        }
    }
}()

9.4 死信队列（DLQ）

死信队列，就是用来存放那些死掉的消息的队列。什么是死信？就是：

消息被消费者拒绝了，并且没有重新入队
消息过期了（TTL 到了）
队列满了，消息放不下了

这些消息不会直接被扔掉，而是会被转发到死信交换机，然后存到死信队列里，我们可以后续排查问题，或者重试处理。

最常见的用法就是用死信队列实现延迟消息：比如我们要做订单超时关闭，下单后 30 分钟没支付，就自动关闭订单。

我们可以这样做：

声明一个普通队列，设置它的 TTL 是 30 分钟，并且设置死信交换机
下单的时候，把消息发到这个队列
30 分钟后，消息过期了，就会被转发到死信队列
我们的消费者监听死信队列，收到消息后，就去检查订单状态，如果没支付就关闭

代码示例：

// 声明死信交换机
err = ch.ExchangeDeclare("dlx_exchange", "direct", true, false, false, false, nil)
failOnError(err, "无法声明死信交换机")

// 声明死信队列
dlq, err := ch.QueueDeclare("dlq_queue", true, false, false, false, nil)
failOnError(err, "无法声明死信队列")

// 绑定死信队列到死信交换机
err = ch.QueueBind(dlq.Name, "order_timeout", "dlx_exchange", false, nil)
failOnError(err, "无法绑定死信队列")

// 声明延迟队列，设置 TTL 和死信交换机
args := amqp.Table{
    "x-message-ttl":             30 * 60 * 1000, // 30分钟，单位毫秒
    "x-dead-letter-exchange":    "dlx_exchange",  // 死信交换机
    "x-dead-letter-routing-key": "order_timeout", // 死信路由键
}
delayQueue, err := ch.QueueDeclare("delay_queue", true, false, false, false, args)
failOnError(err, "无法声明延迟队列")

这样，我们把订单消息发到 delay_queue，30 分钟后，它就会自动跑到 dlq_queue 里，我们的消费者就可以处理了。

十、最佳实践与常见问题

最后，给你一些生产环境的最佳实践：

10.1 用户权限管理

默认的 guest 用户只能本地访问，生产环境一定要新建用户，不要用默认的：

# 添加用户
rabbitmqctl add_user myuser mypassword

# 设置用户为管理员
rabbitmqctl set_user_tags myuser administrator

# 给用户授权
rabbitmqctl set_permissions -p / myuser ".*" ".*" ".*"

10.2 连接与重连

RabbitMQ 的连接是会断的，网络抖动、服务重启都会导致连接断开，所以实际开发时，你的客户端一定要有重连机制，不要断了就直接挂了。

可以把连接的代码放在一个循环里，连接失败了就等几秒钟再重试：

for {
    conn, err := amqp.Dial("amqp://myuser:mypassword@localhost:5672/")
    if err != nil {
        log.Printf("连接失败，5秒后重试: %s", err)
        time.Sleep(5 * time.Second)
        continue
    }
    // 连接成功，继续后续操作
    break
}

如果连接后发生网络抖动，导致连接断开了，也要监听连接的 NotifyClose 通道，及时重连：

conn, err := amqp.Dial("amqp://myuser:mypassword@localhost:5672/")
failOnError(err, "无法连接到 RabbitMQ")

// 监听连接关闭事件
notifyClose := conn.NotifyClose(make(chan *amqp.Error, 1))

go func() {
    err := <-notifyClose
    log.Printf("连接关闭: %s", err)
    // 重连逻辑
    for {
        conn, err = amqp.Dial("amqp://myuser:mypassword@localhost:5672/")
        if err != nil {
            log.Printf("重连失败，5秒后重试: %s", err)
            time.Sleep(5 * time.Second)
            continue
        }
        log.Println("重连成功")
        break
    }
}()

10.3 幂等性消费

网络问题可能会导致消息重复投递，所以你的消费端一定要保证幂等性：就是同一个消息，消费多少次，结果都是一样的。

常见的做法：

用消息的唯一 ID，存到 Redis，消费之前先查一下有没有处理过
数据库的唯一索引，防止重复插入
业务状态机，比如订单状态，只有待支付的才能处理超时，已经支付的就忽略

10.4 监控

一定要开启监控，监控队列的堆积情况、连接数、消息速率，有问题及时报警。RabbitMQ 的管理后台已经提供了很多指标，你也可以用 Prometheus 来采集。

总结

恭喜你！看完这份教程，你已经掌握了 RabbitMQ 的核心用法了！

我们从最基础的概念开始，一步步学会了：

RabbitMQ 的核心组件和消息流转
6 种核心工作模式：简单队列、工作队列、发布订阅、路由、主题、RPC
生产环境必备的高级特性：ACK、持久化、死信队列
各种场景下的 Go 代码实现

RabbitMQ 是一个非常强大的工具，掌握了它，你就能在分布式系统中轻松实现异步通信、解耦、削峰这些功能。

接下来，你可以自己动手把这些代码跑一遍，加深理解，然后就可以在你的项目中使用它了！

Go gRPC 教程

Thu, 26 Mar 2026 17:29:38 +0800

前言

gRPC 是一个高性能、开源的远程过程调用（RPC）框架，由 Google 开发。它基于 HTTP/2 协议设计，默认使用 Protocol Buffers 作为序列化工具，支持跨语言、跨平台的服务调用。对于 Go 语言开发者来说，gRPC 是构建微服务架构的首选工具之一，它能够极大地简化服务间的通信开发，同时提供极高的性能。

本文章将从最基础的概念开始，带你一步步完成从环境搭建到实战开发，再到容器化部署的全流程，覆盖 Windows、Linux、Mac 三大主流系统，以及 Docker 容器化部署方案，让你从零开始，快速掌握 Go 语言下的 gRPC 开发。

一、核心概念入门

1.1 什么是 gRPC？

gRPC 是一个现代化的 RPC 框架，它允许客户端应用直接调用不同机器上的服务端方法，就像调用本地方法一样。它基于 HTTP/2 协议，带来了以下优势：

多路复用：在同一个 TCP 连接上并行处理多个请求，减少连接开销
流处理：支持客户端、服务端的双向流处理
强类型接口：基于 Protobuf 定义服务接口，天然支持跨语言
高性能：二进制序列化，比 JSON 等文本格式更快、更小

1.2 什么是 Protocol Buffers？

Protocol Buffers（简称 Protobuf）是 Google 推出的一种轻量级、高效的结构化数据序列化格式，它比 XML、JSON 更小、更快、更简单。在 gRPC 中，我们使用 Protobuf 来定义服务的接口和消息结构，然后通过编译器生成不同语言的代码。

1.3 gRPC 的四种服务类型

gRPC 支持四种不同类型的服务调用模式，以满足不同的业务场景：

简单 RPC（Unary RPC）：最基础的调用模式，客户端发送一个请求，服务端返回一个响应，就像普通的函数调用一样。
客户端流 RPC（Client-side Streaming RPC）：客户端发送多个请求给服务端，服务端处理完后返回一个响应。
服务端流 RPC（Server-side Streaming RPC）：客户端发送一个请求，服务端返回多个响应流。
双向流 RPC（Bidirectional Streaming RPC）：客户端和服务端都可以通过读写流来发送多个消息，双方可以独立地读写。

1.4 gRPC 工作架构

下图展示了 gRPC 客户端与服务端的基础交互架构：

客户端侧：业务代码调用本地的 gRPC Stub（客户端桩），Stub 会把调用参数通过 Protobuf 序列化为二进制数据，再通过 HTTP/2 客户端把请求发送出去。
网络传输：基于 TCP 连接的 HTTP/2 协议，支持多路复用，同一个连接可以并行处理多个请求。
服务端侧：HTTP/2 服务端收到请求后，先通过 Protobuf 反序列化出请求参数，交给 gRPC 服务端，再转发到你的业务服务实现，处理完成后把结果原路返回给客户端。

二、Protobuf 基础语法

在开始开发之前，我们需要先掌握 Protobuf 的基础语法，因为我们所有的服务定义都需要写在 .proto 文件中。我们这里使用最新的 proto3 语法，这也是目前 gRPC 推荐的版本。

2.1 基础文件结构

一个标准的 .proto 文件的基础结构如下：

// 1. 声明语法版本，必须放在文件第一行（注释除外）
syntax = "proto3";

// 2. 包声明，用于防止命名冲突，相当于命名空间
package helloworld;

// 3. Go语言专属选项，指定生成代码的包路径和包名
// 格式为: 生成文件的输出路径; 包名
option go_package = "./;pb";

2.2 消息（Message）定义

消息是 Protobuf 中数据的载体，你可以把它理解为 Go 语言中的结构体，用来定义传输的数据结构。

// 定义请求消息
message HelloRequest {
  // 字段格式: 类型 字段名 = 字段编号;
  string name = 1;
}

// 定义响应消息
message HelloReply {
  string message = 1;
}

关键字段说明

字段类型：支持基础类型（int32、int64、float、bool、string 等），也支持嵌套的消息类型。
字段编号：每个字段都必须有一个唯一的数字编号，范围是 1~536870911，其中 1~15 占用 1 个字节，16~2047 占用 2 个字节，所以高频使用的字段尽量用小编号。

重复字段：如果需要定义数组 / 列表，使用 repeated 关键字：

message Person {
  string name = 1;
  // repeated 表示这是一个列表
  repeated string hobbies = 2;
}

2.3 服务（Service）定义

服务定义了 gRPC 接口的方法，用来声明客户端可以调用的远程方法：

// 定义 Greeter 服务
service Greeter {
  // 定义一个简单的 RPC 方法
  // 格式: rpc 方法名(请求消息) returns (响应消息);
  rpc SayHello (HelloRequest) returns (HelloReply);
}

三、开发环境搭建

接下来我们分别介绍在 Windows、Linux、Mac 三大系统下的 gRPC Go 开发环境搭建步骤，你可以根据自己的系统选择对应的部分。

3.1 前置条件：安装 Go 语言

首先你需要安装 Go 语言环境，gRPC 要求 Go 版本 >= 1.19，推荐使用最新的稳定版本。

下载地址：Go 官方下载页
安装完成后，打开终端 / 命令行，执行 go version 验证是否安装成功：
1 2

go version # 输出类似: go version go1.22.0 linux/amd64

3.2 安装 Protobuf 编译器（protoc）

protoc 是 Protobuf 的编译器，用来把我们的 .proto 文件编译成不同语言的代码。

Linux 系统（Ubuntu/Debian）

使用 apt 包管理器直接安装：

sudo apt update
sudo apt install -y protobuf-compiler
# 验证安装
protoc --version
# 输出: libprotoc 3.xx.x，确保版本 >= 3.0

Mac 系统

使用 Homebrew 安装：

1
2
3

brew install protobuf
# 验证安装
protoc --version

Windows 系统

前往 Protobuf 发布页，下载对应 Windows 版本的压缩包，比如 protoc-xx.x-x-win64.zip
解压压缩包，把解压后的 bin 目录下的 protoc.exe 所在的路径添加到系统的 Path 环境变量中：
- 右键此电脑 -> 属性 -> 高级系统设置 -> 环境变量
- 在系统变量中找到 Path，点击编辑，添加 protoc.exe 所在的文件夹路径
打开新的命令行，执行 protoc --version 验证是否安装成功。

3.3 安装 Go 语言的 Protobuf 插件

protoc 本身只支持基础的 C++ 等语言，要生成 Go 语言的代码，我们需要安装两个 Go 专属的插件：

protoc-gen-go：用来生成基础的 Protobuf 消息结构代码
protoc-gen-go-grpc：用来生成 gRPC 的服务端和客户端代码

执行以下命令安装这两个插件：

# 安装基础的 Protobuf 插件
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest

# 安装 gRPC 插件
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

安装完成后，需要把 Go 的二进制目录添加到系统的 PATH 环境变量中，这样系统才能找到这两个插件：

1
2
3

# 查看 Go 的 GOPATH 路径
go env GOPATH
# 输出类似: /home/user/go 或者 C:\Users\YourName\go

Linux/Mac：在终端中执行以下命令，或者把它添加到 ~/.bashrc 或 ~/.zshrc 中永久生效：
1

export PATH="$PATH:$(go env GOPATH)/bin"
Windows：把 %GOPATH%\bin（通常是 C:\Users\你的用户名\go\bin）添加到系统的 Path 环境变量中。

验证插件是否安装成功：

1
2
3

# 执行这两个命令，如果没有提示命令不存在，就说明安装成功了
protoc-gen-go --version
protoc-gen-go-grpc --version

四、实战入门：Hello World 示例

现在我们来完成一个最基础的 Hello World 示例，带你完整走一遍 gRPC 开发的全流程。

4.1 创建项目结构

首先创建我们的项目目录，结构如下：

grpc-hello/
├── go.mod
├── go.sum
├── proto/
│   └── helloworld.proto  # 我们的 proto 定义文件
├── server/
│   └── main.go           # 服务端代码
└── client/
    └── main.go           # 客户端代码

执行以下命令初始化项目：

# 创建项目文件夹
mkdir grpc-hello && cd grpc-hello

# 初始化 Go mod
go mod init github.com/yourname/grpc-hello

4.2 编写 Protobuf 定义文件

创建 proto/helloworld.proto 文件，写入以下内容：

syntax = "proto3";

package helloworld;

option go_package = "../pb;pb";

// 定义请求消息
message HelloRequest {
  string name = 1;
}

// 定义响应消息
message HelloReply {
  string message = 1;
}

// 定义 Greeter 服务
service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
}

4.3 生成 Go 代码

现在我们使用 protoc 编译器，把上面的 .proto 文件编译成 Go 语言的代码。在项目根目录执行以下命令：

`1`	`protoc --go_out=. --go-grpc_out=. proto/helloworld.proto`

执行完成后，你会发现项目根目录下多了一个 pb 文件夹，里面有两个文件：

helloworld_grpc.pb.go：gRPC 相关的服务端、客户端代码
helloworld.pb.go：Protobuf 消息结构的代码

4.4 编写服务端代码

创建 server/main.go 文件，这是我们的 gRPC 服务端代码，用来处理客户端的请求：

package main

import (
	"context"
	"log"
	"net"

	"google.golang.org/grpc"
	pb "github.com/yourname/grpc-hello/pb" // 替换成你自己的模块路径
)

// 定义服务结构体，必须嵌入 pb.UnimplementedGreeterServer
// 这是为了兼容未来的接口扩展，保证向前兼容
type server struct {
	pb.UnimplementedGreeterServer
}

// 实现 SayHello 方法，这是我们在 proto 中定义的服务方法
func (s *server) SayHello(ctx context.Context, in *pb.HelloRequest) (*pb.HelloReply, error) {
	// 打印收到的请求信息
	log.Printf("Received request from: %v", in.GetName())
	// 返回响应
	return &pb.HelloReply{Message: "Hello " + in.GetName()}, nil
}

func main() {
	// 监听 50051 端口，这是 gRPC 的默认端口
	lis, err := net.Listen("tcp", ":50051")
	if err != nil {
		log.Fatalf("failed to listen: %v", err)
	}

	// 创建 gRPC 服务端实例
	s := grpc.NewServer()
	// 把我们的服务注册到 gRPC 服务端中
	pb.RegisterGreeterServer(s, &server{})

	log.Printf("server listening at %v", lis.Addr())
	// 启动服务，开始处理请求
	if err := s.Serve(lis); err != nil {
		log.Fatalf("failed to serve: %v", err)
	}
}

4.5 编写客户端代码

创建 client/main.go 文件，这是我们的客户端代码，用来调用服务端的远程方法：

package main

import (
	"context"
	"log"
	"time"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"
	pb "github.com/yourname/grpc-hello/pb" // 替换成你自己的模块路径
)

func main() {
	// 连接到 gRPC 服务端，这里我们连接本地的 50051 端口
	// 使用 insecure  credentials，因为我们的示例没有开启 TLS
	conn, err := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
	if err != nil {
		log.Fatalf("did not connect: %v", err)
	}
	// 函数结束时关闭连接
	defer conn.Close()

	// 创建 Greeter 客户端
	c := pb.NewGreeterClient(conn)

	// 设置超时时间，防止请求阻塞
	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
	defer cancel()

	// 调用远程的 SayHello 方法
	r, err := c.SayHello(ctx, &pb.HelloRequest{Name: "World"})
	if err != nil {
		log.Fatalf("could not greet: %v", err)
	}

	// 打印响应结果
	log.Printf("Greeting: %s", r.GetMessage())
}

4.6 运行测试

现在我们来启动服务端，然后运行客户端，测试我们的 gRPC 服务。

首先启动服务端：
1

go run server/main.go
你会看到输出：server listening at [::]:50051，说明服务端已经启动成功了。
打开一个新的终端，运行客户端：
1

go run client/main.go
客户端会输出：Greeting: Hello World，说明调用成功了！
回到服务端的终端，你会看到服务端输出：Received request from: World，说明服务端成功收到了客户端的请求。

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

五、Docker 容器化部署

当我们开发完成后，我们可以把我们的 gRPC 服务打包成 Docker 镜像，方便部署和分发。这里我们使用多阶段构建的方式，来最小化镜像的体积。

5.1 编写 Dockerfile

在项目的根目录创建 Dockerfile 文件，内容如下：

# 第一阶段：构建阶段，使用完整的 Go 环境来编译代码
FROM golang:1.22-alpine AS builder

# 设置工作目录
WORKDIR /app

# 复制 go.mod 和 go.sum，先下载依赖，利用 Docker 缓存
COPY go.mod go.sum ./
RUN go mod download

# 复制所有代码
COPY . .

# 编译代码，CGO_ENABLED=0 表示静态编译，不依赖动态库
# GOOS=linux 指定目标系统是 Linux
RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o grpc-server ./server/main.go

# 第二阶段：运行阶段，使用极小的 alpine 镜像，只保留编译后的二进制文件
FROM alpine:latest

# 安装 ca-certificates，用于 TLS 证书验证
RUN apk --no-cache add ca-certificates

WORKDIR /root/

# 从构建阶段复制编译好的二进制文件
COPY --from=builder /app/grpc-server .

# 暴露服务端口
EXPOSE 50051

# 启动服务
CMD ["./grpc-server"]

5.2 构建 Docker 镜像

在项目根目录执行以下命令，构建 Docker 镜像：

`1`	`docker build -t grpc-hello-server:latest .`

这个命令会自动完成多阶段构建，最终生成的镜像体积非常小，通常只有十几 MB，比直接用 Go 基础镜像小了几十倍。

5.3 运行 Docker 容器

构建完成后，我们可以运行这个镜像，启动我们的 gRPC 服务：

`1`	`docker run -p 50051:50051 grpc-hello-server:latest`

这个命令会把容器的 50051 端口映射到主机的 50051 端口，这样我们就可以像之前一样，用本地的客户端来连接这个服务了。

5.4 测试容器化服务

现在你可以运行之前的客户端代码，来测试容器中的服务：

`1`	`go run client/main.go`

你会看到和之前一样的输出，说明容器化的服务已经正常工作了！

六、常见问题与排错

6.1 protoc: command not found

这说明系统找不到 protoc 命令，你需要检查：

是否已经正确安装了 protoc
是否把 protoc 的路径添加到了系统的 PATH 环境变量中

6.2 Plugin protoc-gen-go not found

这说明系统找不到 protoc-gen-go 插件，检查：

是否已经正确安装了插件
是否把 $GOPATH/bin 添加到了 PATH 环境变量中

6.3 模块路径错误

在导入 pb 包的时候，一定要替换成你自己的 go mod 初始化的模块路径，否则会出现导入错误。

6.4 连接超时

如果客户端连接服务端超时，检查：

服务端是否已经正常启动
端口是否正确，防火墙是否开放了对应的端口
如果是 Docker 部署，检查端口映射是否正确

总结

通过本指南，你已经完成了从 0 开始的 gRPC 学习，掌握了：

gRPC 和 Protobuf 的核心概念
三大系统下的开发环境搭建
完整的 gRPC 服务开发流程
Docker 容器化部署方案

接下来你可以继续深入学习 gRPC 的高级特性，比如 TLS 加密、认证拦截、流处理、负载均衡等，来构建生产级的微服务应用。

Redis基础学习文档

Tue, 24 Mar 2026 17:05:27 +0800

Redis基础学习文档

基础篇

Redis数据结构介绍

Redis是一个key-value的数据库，key一般是String类型，value的类型多种多样：我们可以在官网（https://redis.io/commands）查看不同的命令用法。同时我们也可以在命令行通过help指令来查找命令。

Redis的通用命令

通用命令是部分数据类型的，都可以使用的命令，常见的有：

KEYS：查看符合模板的所有key。模糊查询的效率不高，又因为Redis是单线程的，所以不建议在生产环境设备上使用
DEL：删除一个或多个指定的key
EXISTS：检查一个或多个key是否存在
EXPIRE：为一个key设置有效期（过期时间），单位为秒，有效期到期时，key会被自动删除
TTL：查看一个key的剩余有效期，单位为秒注意：当一个key设置了过期时间后，如果在过期时间到期之前再次设置了过期时间，那么原来的过期时间会被覆盖掉，新的过期时间会重新计算。并且过期后TTL命令会返回-2，表示key不存在了；如果一个key没有设置过期时间，那么TTL命令会返回-1，表示这个key是永久有效的。

String类型

String类型是Redis中最基本的数据类型，key和value都是字符串类型。不过根据字符串的格式不同，String类型又可以分为以下几种：

普通字符串：普通的字符串类型，可以存储任何文本数据，最大长度为512MB。
数字字符串：可以存储整数或浮点数，可以进行数学运算和自增操作。
二进制字符串：可以存储二进制数据，如图片、音频等非文本数据。
JSON字符串：可以存储JSON格式的数据，可以方便地进行数据交换和存储复杂的数据结构。

不管是哪种格式，底层都是字节数组形式存储，只不过是编码方式不同。字符串类型的最大空间不能超过512MB，如果超过了这个限制，Redis会返回错误。

String类型的常用命令有：

SET：设置一个key的值，如果key已经存在，则覆盖原来的值
GET：获取一个key的值，如果key不存在，则返回nil
MSET：同时设置多个key的值
MGET：同时获取多个key的值
INCR：将一个key的值加1，如果key不存在，则先将其设置
INCRBY：将一个key的值加上指定的整数，如果key不存在，则先将其设置。也可以实现自减的效果。
INCRBYFLOAT：将一个key的值加上指定的浮点数，如果key不存在，则先将其设置
DECR：将一个key的值减1，如果key不存在，则先将其设置
DECRBY：将一个key的值减去指定的整数，如果key不存在，则先将其设置
SETNX：只有当key不存在时才设置key的值，如果key已经存在，则不做任何操作
SETEX：设置一个key的值，并为key设置过期时间，单位为秒
PSETEX：设置一个key的值，并为key设置过期时间，单位为毫秒

KEY的层级结构

Redis的key是一个字符串，可以包含任何字符，包括空格和特殊字符。为了方便管理和组织key，Redis没有提供真正的层级结构，但我们可以通过在key中使用分隔符（如冒号:）来模拟层级结构。例如，我们有一个项目叫heima，有user和product两种不同类型的数据，我们可以这样定义key：

user相关的key：heima:user:1、heima:user:2、heima:user:3等
product相关的key：heima:product:1、heima:product:2、heima:product:3等

如果value是一个对象，例如一个user对象，我们可以将其序列化成JSON字符串存储在Redis中，这样就可以方便地进行数据交换和存储复杂的数据结构。

Hash类型

Hash类型，也叫散列，其value是一个无序字典，类似于C++中的unordered_map。Hash类型的key是一个字符串，而value是一个包含多个field和value的字典。每个field都是一个字符串，每个value也是一个字符串。主要特征有：

Hash类型的元素是无序的，不能通过索引访问
Hash类型的元素是唯一的，不能重复
Hash类型的元素可以在字典中添加或删除
查询速度快，适合于需要频繁查询的场景，例如用户信息、商品信息等。

Hash类型的常用命令有：

HSET key field value：设置hash表key中field的值为value，如果key不存在，则创建一个新的hash表；如果field已经存在，则覆盖原来的值
HGET key field：获取hash表key中field的值，如果key不存在或field不存在，则返回nil
HMSET key field1 value1 field2 value2 ...：同时设置hash表key中多个field的值，如果key不存在，则创建一个新的hash表；如果field已经存在，则覆盖原来的值
HMGET key field1 field2 ...：同时获取hash表key中多个field的值，如果key不存在或field不存在，则返回nil
HGETALL key：获取hash表key中所有field和value的值，如果key不存在，则返回nil
HKEYS key：获取hash表key中所有field的值，如果key不存在，则返回nil
HVALS key：获取hash表key中所有value的值，如果key不存在，则返回nil
HDEL key field1 field2 ...：删除hash表key中指定的field，如果key不存在或field不存在，则不做任何操作
HLEN key：获取hash表key中field的数量，如果key不存在，则返回0
HEXISTS key field：检查hash表key中是否存在field，如果key不存在或field不存在，则返回0；如果存在，则返回1
HINCRBY key field increment：将hash表key中field的值加上指定的整数increment，如果key不存在，则先创建一个新的hash表；如果field不存在，则先将其设置为0；如果field的值不是一个整数，则返回错误
HSETNX key field value：只有当hash表key中field不存在时才设置field的值为value，如果key不存在，则先创建一个新的hash表；如果field已经存在，则不做任何操作

List类型

Redis的List类型与C++中的std::list类似，是一个双向链表。List类型的key是一个字符串，而value是一个包含多个元素的列表，每个元素都是一个字符串。特征也与std::list类似：

List类型的元素是有序的，可以通过索引访问
List类型的元素可以重复
List类型的元素可以在头部或尾部添加或删除
查询速度一般，适合于需要频繁插入和删除的场景，例如消息队列、任务列表等。常用来存储一个有序数据，例如朋友圈点赞列表、微博评论列表等。

List类型的常用命令有：

LRANGE key start stop：获取列表key中指定范围内的元素，start和stop都是索引，索引从0开始，负数表示从列表尾部开始计算，例如-1表示最后一个元素，-2表示倒数第二个元素，以此类推。如果key不存在，则返回nil；如果start或stop超出范围，则返回空列表
LPUSH key value1 value2 ...：将一个或多个值插入到列表key的头部，如果key不存在，则创建一个新的列表；如果key存在但不是列表类型，则返回错误
LPOP key：移除并返回列表key的头部元素，如果key不存在或列表为空，则返回nil
RPUSH key value1 value2 ...：将一个或多个值插入到列表key的尾部，如果key不存在，则创建一个新的列表；如果key存在但不是列表类型，则返回错误
RPOP key：移除并返回列表key的尾部元素，如果key不存在或列表为空，则返回nil
LLEN key：获取列表key中元素的数量，如果key不存在，则返回0
LINDEX key index：获取列表key中指定索引位置的元素，如果key不存在或索引超出范围，则返回nil
LSET key index value：设置列表key中指定索引位置的元素为value，如果key不存在或索引超出范围，则返回错误
BLPOP key [key ...] timeout：移除并返回一个或多个列表key的头部元素，如果key不存在或列表为空，则返回nil；如果timeout为0，表示永远等待；如果timeout为正整数，表示等待指定的秒数，如果在等待期间有元素被添加到列表中，则立即返回；如果在等待期间没有元素被添加到列表中，则返回nil
BRPOP key [key ...] timeout：移除并返回一个或多个列表key的尾部元素，如果key不存在或列表为空，则返回nil；如果timeout为0，表示永远等待；如果timeout为正整数，表示等待指定的秒数，如果在等待期间有元素被添加到列表中，则立即返回；如果在等待期间没有元素被添加到列表中，则返回nil BLPOP和BRPOP命令常用于实现消息队列的功能，例如生产者将消息推送到列表中，消费者从列表中弹出消息进行处理。如果消费者在等待期间没有收到消息，可以设置一个超时时间来避免无限等待。

Set类型

Redis的Set类型是一种无序集合，类似于C++中的std::unordered_set，可以看作是一个value为null的Hash类型。因为也是一个hash表，所以具备与Hash类型相似的特征：

Set类型的元素是无序的，不能通过索引访问
Set类型的元素是唯一的，不能重复
Set类型的元素可以在集合中添加或删除
查询速度快，适合于需要频繁查询的场景，例如标签系统、好友关系等。

Set类型的常用命令有：

SADD key member1 member2 ...：将一个或多个成员添加到集合key中，如果key不存在，则创建一个新的集合；如果key存在但不是集合类型，则返回错误
SREM key member1 member2 ...：从集合key中移除一个或多个成员，如果key不存在或成员不存在，则不做任何操作
SCARD key：获取集合key中成员的数量，如果key不存在，则返回0
SISMEMBER key member：检查集合key中是否存在成员，如果key不存在或成员不存在，则返回0；如果存在，则返回1
SMEMBERS key：获取集合key中所有成员的值，如果key不存在，则返回nil
SINTER key1 key2 ...：获取一个或多个集合key的交集，如果key不存在，则返回nil；如果key存在但不是集合类型，则返回错误
SUNION key1 key2 ...：获取一个或多个集合key的并集，如果key不存在，则返回nil；如果key存在但不是集合类型，则返回错误
SDIFF key1 key2 ...：获取一个或多个集合key的差集，如果key不存在，则返回nil；如果key存在但不是集合类型，则返回错误

Sorted Set类型

Redis的SortedSet类型是一个可排序的set几何，与C++中的std::set类似，但底层数据结构却差别很大。SortedSet中的每一个元素都带有一个分数（score），Redis会根据分数来对元素进行排序。底层实现是一个跳表（skip list），跳表是一种基于链表的数据结构，通过增加多级索引来提高查询效率。SortedSet具备以下特性：

SortedSet类型的元素是有序的，可以通过索引访问
SortedSet类型的元素是唯一的，不能重复
SortedSet类型的元素可以在集合中添加或删除
查询速度快，适合于需要频繁查询的场景，例如排行榜、社交网络等。因为SortedSet的可排序特性，经常被用来实现排行榜这样的功能。

SortedSet类型的常用命令有：

ZADD key score1 member1 [score2 member2 ...]：将一个或多个成员添加到有序集合key中，并为每个成员设置分数，如果key不存在，则创建一个新的有序集合；如果key存在但不是有序集合类型，则返回错误；如果成员已经存在，则更新其分数
ZREM key member1 member2 ...：从有序集合key中移除一个或多个成员，如果key不存在或成员不存在，则不做任何操作
ZSCORE key member：获取有序集合key中成员的分数，如果key不存在或成员不存在，则返回nil
ZRANK key member：获取有序集合key中成员的排名，排名从0开始，如果key不存在或成员不存在，则返回nil
ZREVRANK key member：获取有序集合key中成员的反向排名，排名从0开始，如果key不存在或成员不存在，则返回nil
ZCARD key：获取有序集合key中成员的数量，如果key不存在，则返回0
ZCOUNT key min max：获取有序集合key中分数在min和max之间的成员数量，如果key不存在，则返回0；如果key存在但不是有序集合类型，则返回错误
ZINCRBY key increment member：将有序集合key中成员的分数增加increment，如果key不存在，则先创建一个新的有序集合；如果成员不存在，则先将其设置为0；如果成员的分数不是一个数字，则返回错误
ZRANGE key start stop [WITHSCORES]：获取有序集合key中指定范围内的成员，start和stop都是索引，索引从0开始，负数表示从集合尾部开始计算，例如-1表示最后一个成员，-2表示倒数第二个成员，以此类推。如果key不存在，则返回nil；如果start或stop超出范围，则返回空列表；如果指定了WITHSCORES选项，则返回成员和分数的列表
ZREVRANGE key start stop [WITHSCORES]：获取有序集合key中指定范围内的成员，start和stop都是索引，索引从0开始，负数表示从集合尾部开始计算，例如-1表示最后一个成员，-2表示倒数第二个成员，以此类推。如果key不存在，则返回nil；如果start或stop超出范围，则返回空列表；如果指定了WITHSCORES选项，则返回成员和分数的列表
ZRANGEBYSCORE key min max [WITHSCORES]：获取有序集合key中分数在min和max之间的成员，如果key不存在，则返回nil；如果key存在但不是有序集合类型，则返回错误；如果指定了WITHSCORES选项，则返回成员和分数的列表
ZINTER key numkeys key1 key2 ...：获取一个或多个有序集合key的交集，如果key不存在，则返回nil；如果key存在但不是有序集合类型，则返回错误；如果指定了WITHSCORES选项，则返回成员和分数的列表
ZUNION key numkeys key1 key2 ...：获取一个或多个有序集合key的并集，如果key不存在，则返回nil；如果key存在但不是有序集合类型，则返回错误；如果指定了WITHSCORES选项，则返回成员和分数的列表
ZDIFF key numkeys key1 key2 ...：获取一个或多个有序集合key的差集，如果key不存在，则返回nil；如果key存在但不是有序集合类型，则返回错误；如果指定了WITHSCORES选项，则返回成员和分数的列表
ZINTERSTORE destination numkeys key1 key2 ...：计算一个或多个有序集合key的交集，并将结果存储在destination中，如果destination已经存在，则覆盖原来的值；如果key不存在，则返回nil；如果key存在但不是有序集合类型，则返回错误
ZUNIONSTORE destination numkeys key1 key2 ...：计算一个或多个有序集合key的并集，并将结果存储在destination中，如果destination已经存在，则覆盖原来的值；如果key不存在，则返回nil；如果key存在但不是有序集合类型，则返回错误
ZDIFFSTORE destination numkeys key1 key2 ...：计算一个或多个有序集合key的差集，并将结果存储在destination中，如果destination已经存在，则覆盖原来的值；如果key不存在，则返回nil；如果key存在但不是有序集合类型，则返回错误

Golang学习笔记

Wed, 21 Jan 2026 13:54:12 +0800

此Blog用于记录学习Golang时的笔记。视频网址：https://www.bilibili.com/video/BV1gf4y1r79E?spm_id_from=333.788.videopod.episodes&vd_source=a28b0a61baf52e2de1f7120e1c9d88e1 视频作者：刘丹冰

Go学习笔记

第一部分

基本结构

main函数不能有形参和返回值

// 程序入口
package main

// fmt 常用标准库
import "fmt"

func main() {
    fmt.Println("Hello World!")

    return 0
}

变量声明方式、赋值方式

默认0

1
2
3

    var a int
    fmt.Println("a =", a)
    fmt.Printf("type of a: %T\n", a)

赋初值

1
2
3

    var b int = 100
    fmt.Println("b =", b)
    fmt.Printf("type of b: %T\n", b)

省去类型名，类似python

1
2
3

    var c = 200
    fmt.Println("c =", c)
    fmt.Printf("type of c: %T\n", c)

省去var（最常用方法），直接自动匹配

1
2
3

    d := 300
    fmt.Println("d =", d)
    fmt.Printf("type of d: %T\n", d)

注：此方式不可用于声明全局变量

常量声明方式、iota的用法

// const和iota
// const就是定义变量时把var换成const
const PI = 3.1415926

// iota初值为0，往下每行自增1，用于给多个常量赋值
const (
    BEIJING = 10 * iota
    SHANGHAI
    SHENZHEN
)
const (
    a, b = iota + 1, iota + 2 // iota = 0,a = 1,b = 2
    c, d                      // iota = 1,c = 2,d = 3
    e, f                      // iota = 2,e = 3,f = 4

    g, h = iota * 2, iota * 3 // iota = 3,g = 6,h = 9
    i, j                      // iota = 4,i = 8,j = 12
)

函数、返回值

单返回值函数

go中的函数参数关键字func在前，类型名与返回值皆在后

func foo1(a string, b int) int {
    fmt.Println("====foo1====")
    fmt.Println("a =", a, ", b=", b)
    c := 100

    return c
}

多返回值函数(1)

多返回值就用括号包起来

func foo2(a string, b int) (int, int) {
    fmt.Println("====foo2====")
    fmt.Println("a =", a, ", b=", b)
    c := 100

    return c, c + 10
}

多返回值函数(2)

go中的函数参数关键字func在前，类型名与返回值皆在后

func foo3(a string, b int) (r1 int, r2 int) {
    fmt.Println("====foo3====")
    fmt.Println("a =", a, ", b=", b)

    //c := 100
    //return c, c + 10

    // 或者给有名称的返回值赋值
    fmt.Println("r1 =", r1, ", r2 =", r2) // r1,r2属于foo3的形参，初始化默认为0
    r1 = 100
    r2 = 200

    return
}

多返回值函数(3)

go中的函数参数关键字func在前，类型名与返回值皆在后

func foo4(a string, b int) (r1, r2 int) {
    fmt.Println("====foo4====")
    fmt.Println("a =", a, ", b =", b)

    //c := 100
    //return c, c + 10

    // 或者给有名称的返回值赋值
    r1 = 100
    r2 = 200

    return
}

import时init方法调用流程

import匿名及别名导包形式

匿名导包

匿名导包用 _ 表示，可以导入某个包但不使用

import _ "fmt"

func main() {
	// 不会报未使用的错
}

别名导包

匿名导包用 . 表示，使用包中的方法时无需指明是哪个包的方法

import . "fmt"

func main() {
	Println("hello world")
    // fmt.Println("hello world")
}

defer语句

defer是在某个函数要结束时执行的语句，多个defer会用过压栈再出栈的顺序执行. 最终的执行顺序应该是func3 -> func2 -> func1。

值得注意的是，当defer和return同时存在时，也是先执行return再执行defer。

func returnFunc() int {
	fmt.Println("this is returnFunc")
	return 0
}
func deferFunc() {
	fmt.Println("this is deferFunc")
}
func test() int {
	defer deferFunc()
	return returnFunc()
}

执行函数test后，输出的结果是：

1
2

this is returnFunc
this is deferFunc

第二部分

数组的定义

// 固定长度数组在函数中的参数类型必须一致，且传参是以复制的形式
func test1(myArray [5]int) {
	fmt.Printf("myArray = %v\n", myArray) // %v 表示输出：详细信息
}

func main() {
	//定长数组
	var myArray [5]int

	fmt.Println("myArray =", myArray) // 默认全0：[0 0 0 0 0]

	myArray1 := [10]int{1, 2, 3, 4, 5}
	fmt.Println("myArray1 =", myArray1) // 未赋值的位置全0：[1 2 3 4 5 0 0 0 0 0]

	// for循环写法
	for i := 0; i < len(myArray); i++ {
		fmt.Printf("myArray[%d]=%d", i, myArray[i])
	}
	fmt.Printf("\n")
	for index, value := range myArray1 {
		fmt.Printf("myArray[%d]=%d", index, value)
	}
	fmt.Printf("\n")
	// _ 用于表示匿名变量，不会被使用
	for _, value := range myArray1 {
		fmt.Printf("myArray1[%d]=%d", value, value)
	}
	fmt.Printf("\n")

	// 变长数组
	arr := make([]int, 10) // 默认全0
	fmt.Printf("arr=%v\n", arr)

	// 查看数组的数据类型
	fmt.Printf("myArray types = %T\n", myArray)   // 数据类型为[5]int
	fmt.Printf("myArray1 types = %T\n", myArray1) // 数据类型为[10]int\

	test1(myArray)
}

输出：

myArray = [0 0 0 0 0]
myArray1 = [1 2 3 4 5 0 0 0 0 0]
myArray[0]=0myArray[1]=0myArray[2]=0myArray[3]=0myArray[4]=0
myArray[0]=1myArray[1]=2myArray[2]=3myArray[3]=4myArray[4]=5myArray[5]=0myArray[6]=0myArray[7]=0myArray[8]=0myArray[9]=0
myArray1[1]=1myArray1[2]=2myArray1[3]=3myArray1[4]=4myArray1[5]=5myArray1[0]=0myArray1[0]=0myArray1[0]=0myArray1[0]=0myArray1[0]=0
arr=[0 0 0 0 0 0 0 0 0 0]
myArray types = [5]int
myArray1 types = [10]int
myArray = [0 0 0 0 0]

数组的复制

浅拷贝

    arr1 := []int{1, 2, 3, 4}
    fmt.Printf("arr1=%v\n", arr1)

    arr2 := arr1
    fmt.Printf("arr2=%v\n", arr2)

    arr1[0] = 999
    fmt.Printf("arr1=%v\n", arr1)
    fmt.Printf("arr2=%v\n", arr2)

    fmt.Printf("%p\n", arr1)
    fmt.Printf("%p\n", arr2)

输出：

arr1=[1 2 3 4]
arr2=[1 2 3 4]
arr1=[999 2 3 4]
arr2=[999 2 3 4]
0xc0000141e0
0xc0000141e0

深拷贝(copy)

    arr1 := []int{1, 2, 3, 4}
    fmt.Printf("arr1=%v\n", arr1)

    arr2 := make([]int, 3)
    copy(arr2, arr1)
    fmt.Printf("arr2=%v\n", arr2)
    arr3 := make([]int, 10)
    copy(arr3, arr1)
    fmt.Printf("arr3=%v\n", arr3)

    arr1[0] = 999
    fmt.Printf("arr1=%v\n", arr1)
    fmt.Printf("arr2=%v\n", arr2)
    fmt.Printf("arr3=%v\n", arr3)

    fmt.Printf("%p\n", arr1)
    fmt.Printf("%p\n", arr2)
    fmt.Printf("%p\n", arr3)

输出：

arr1=[1 2 3 4]
arr2=[1 2 3]
arr3=[1 2 3 4 0 0 0 0 0 0]
arr1=[999 2 3 4]
arr2=[1 2 3]
arr3=[1 2 3 4 0 0 0 0 0 0]
0xc0000141e0
0xc000010150
0xc0000121e0

参数为数组的函数写法及修改的情况

func test1(arr1 []int) {
    arr1 = append(arr1, 10)    // 无法得到append后的数组
}
func test2(arr1 []int) []int {
    arr1 = append(arr1, 10)    // 通过返回值接收，可以得到append后的数组
    return arr1
}
func test3(arr1 []int) {
    arr1[0] = 1                   // 可以得到修改后的数组，因此是通过引用传递的参数
}
func main() {
    arr1 := make([]int, 6)

    test1(arr1)
    fmt.Printf("arr1 = %d\n", arr1)

    arr1 = test2(arr1)
    fmt.Printf("arr1 = %d\n", arr1)

    test3(arr1)
    fmt.Printf("arr1 = %d\n", arr1)
}

输出：

1
2
3

arr1 = [0 0 0 0 0 0]
arr1 = [0 0 0 0 0 0 10]
arr1 = [1 0 0 0 0 0 10]

切片slice的尺寸和容量，以及判空

func main() {
    slice1 := []int{1, 2, 3, 4, 5}
    fmt.Printf("slice1=%v, size=%d, cap=%d\n", slice1, len(slice1), cap(slice1))

    slice2 := make([]int, 4)
    fmt.Printf("slice2=%v, size=%d, cap=%d\n", slice2, len(slice2), cap(slice2)) // 默认状态下cap等于size

    slice3 := make([]int, 3, 5) // make(dataType,size,cap)
    fmt.Printf("slice3=%v, size=%d, cap=%d\n", slice3, len(slice3), cap(slice3)) // 指定状态下cap大于等于size

    slice1 = append(slice1, 9)
    fmt.Printf("slice1=%v, size=%d, cap=%d\n", slice1, len(slice1), cap(slice1)) // cap不足时，cap翻倍，与cpp的vector类似

    // 判断一个slice是否为0
    var slice []int
    if slice == nil {
       fmt.Printf("slice is nil\n")
    } else {
       fmt.Printf("slice is %v\n", slice)
    }
}

输出：

slice1=[1 2 3 4 5], size=5, cap=5
slice2=[0 0 0 0], size=4, cap=4
slice3=[0 0 0], size=3, cap=5
slice1=[1 2 3 4 5 9], size=6, cap=10
slice is nil

切片截取（设置上下限）

func main() {
    slice1 := []int{1, 2, 3, 4, 5}

    fmt.Printf("slice1[0:3] = %d\n", slice1[0:3]) // 左闭右开的区间
    fmt.Printf("slice1[:3] = %d\n", slice1[:3])   // 左边不填默认为0
    fmt.Printf("slice1[1:] = %d\n", slice1[1:])   // 右边不填默认为len(slice)

    slice2 := slice1[0:3]
    fmt.Printf("slice2 = %d\n", slice2)
}

输出：

slice1[0:3] = [1 2 3]
slice1[:3] = [1 2 3]
slice1[1:] = [2 3 4 5]
slice2 = [1 2 3]

map的声明、赋值和遍历

第一种声明方式：先声明，再make

    // 声明myMap1是一种map类型，key是int，value是string
    var myMap1 map[int]string
    if myMap1 == nil {
       fmt.Printf("mymap1 is nil\n")
       myMap1 = make(map[int]string, 10)
    }

    myMap1[1] = "Beijing"
    myMap1[2] = "Shanghai"
    myMap1[3] = "Guangzhou"
    myMap1[4] = "Shenzhen"
    myMap1[5] = "Iceland"

    fmt.Println(myMap1)

    for k, v := range myMap1 {
       fmt.Println(k, v)
    }

输出：

mymap1 is nil
map[1:Beijing 2:Shanghai 3:Guangzhou 4:Shenzhen 5:Iceland]
3 Guangzhou
1 Beijing
2 Shanghai
4 Shenzhen
5 Iceland

第二种声明方式：直接make

    myMap2 := make(map[int]string)
    myMap2[1] = "Beijing"
    myMap2[2] = "Shanghai"
    myMap2[3] = "Guangzhou"
    myMap2[4] = "Shenzhen"
    myMap2[5] = "Iceland"

    fmt.Println(myMap2)

输出：

`1`	`map[1:Beijing 2:Shanghai 3:Guangzhou 4:Shenzhen 5:Iceland]`

第三种声明方式：声明、赋值同时进行

	myMap3 := map[int]string{
		1: "Beijing",
		2: "Shanghai",
		3: "Guangzhou",
		4: "Shenzhen",
		5: "Iceland",
	}

	fmt.Println(myMap3)

输出：

`1`	`map[1:Beijing 2:Shanghai 3:Guangzhou 4:Shenzhen 5:Iceland]`

map的增删改查

        myMap := map[int]string{
           1: "Beijing",
           2: "Shanghai",
           3: "Guangzhou",
           4: "Shenzhen",
           5: "Iceland",
        }
        fmt.Println(myMap)
    
        // 添加
        myMap[6] = "NewYork"
        fmt.Println(myMap)
    
        // 删除
        delete(myMap, 3)
        fmt.Println(myMap)
    
        // 修改
        myMap[2] = "Tokyo"
        fmt.Println(myMap)
    
        // 遍历
        for key, value := range myMap {
           fmt.Println(key, value)
        }

输出

map[1:Beijing 2:Shanghai 3:Guangzhou 4:Shenzhen 5:Iceland]
map[1:Beijing 2:Shanghai 3:Guangzhou 4:Shenzhen 5:Iceland 6:NewYork]
map[1:Beijing 2:Shanghai 4:Shenzhen 5:Iceland 6:NewYork]
map[1:Beijing 2:Tokyo 4:Shenzhen 5:Iceland 6:NewYork]
4 Shenzhen
5 Iceland
6 NewYork
1 Beijing
2 Tokyo

第三部分

struct基本定义与使用

// 声明一种新的数据类型
type myInt int

// 定义一个结构体
type Book struct {
    title  string
    author string
}

func main() {
    var a myInt = 66
    fmt.Println(a)

    var book1 Book
    book1.title = "Go Programming Language"
    book1.author = "www.golang.com"
    fmt.Printf("%v\n", book1)
    fmt.Printf("book1.title:%s, book1.author:%s\n", book1.title, book1.author)
}

输出

1
2
3

66
{Go Programming Language www.golang.com}
book1.title:Go Programming Language, book1.author:www.golang.com

类的表示与封装

值得注意的是，Go与cpp不同，cpp是显式定义类的成员类型(public、private)，而Go是通过首字母是否大写来表示是否是public。

// 如果类名首字母大写，表示其他包也能够访问
type Hero struct {
    // 如果说类的属性首字母大写，表示该属性是对外能够访问的(public)，否则只能在类的内部使用(private)
    Name  string
    Ad    int
    Level int
}

// hero Hero表示当前函数绑定在调用这个函数的Hero对象中，其实也就是一个参数，所以最好传指针进去
// 相当于cpp中类里的成员函数
func (hero *Hero) GetName() string {
    fmt.Println("Name:", hero.Name)
    return hero.Name
}

func (hero *Hero) Show() {
    fmt.Println("Hero:", hero.Name)
    fmt.Println("Ad:", hero.Ad)
    fmt.Println("Level:", hero.Level)
}

//  func (hero Hero) SetName(newName string) {
//     //hero 是调用该方法的对象的一个副本(浅拷贝)
//     hero.Name = newName
//  }

// 最好是使用hero *Hero来绑定
func (hero *Hero) SetName(newName string) {
    //this 是调用该方法的对象的一个副本(浅拷贝)
    hero.Name = newName
}

func main() {
    // 创建一个对象
    hero := Hero{Name: "Spider-Man", Ad: 5, Level: 1}

    hero.Show()

    fmt.Println(hero.GetName())
    hero.SetName("wxz")
    fmt.Println(hero.GetName())
}

输出

Hero: Spider-Man
Ad: 5
Level: 1
Name: Spider-Man
Spider-Man
Name: wxz
wxz

继承的语法

type Human struct {
    name string
    sex  string
}

func (h *Human) Eat() {
    fmt.Printf("Human.Eat()...\n")
}

func (h *Human) Walk() {
    fmt.Printf("Human.Walk()...\n")
}

// ================================
// 子类
type Superman struct {
    Human // Superman类继承了Human类的属性和方法
    level int
}

// 重写父类的方法
func (s *Superman) Walk() {
    fmt.Printf("Superman.Walk()...\n")
}

//func (s *Superman) Eat() {
//  fmt.Printf("Superman.Eat()...\n")
//}

func (s *Superman) Show() {
    fmt.Println(s.name)
    fmt.Println(s.sex)
    fmt.Println(s.level)
}

func main() {
    h := Human{"zhang3", "male"}
    h.Eat()
    h.Walk()

    //s := Superman{Human{"lisi", "male"}, 5}
    var s Superman
    s.name = "lisi"
    s.sex = "male"
    s.level = 5

    s.Show() // 子类的方法
    s.Eat()  // 父类的方法
    s.Walk() // 子类的方法
}

输出

Human.Eat()...
Human.Walk()...
lisi
male
5
Human.Eat()...
Superman.Walk()...

面向对象多态的实现与基本要素

先定义一下接口和具体的类，接口的本质是一个指针。

type Animal interface {
    Sleep()
    GetColor() string
    GetType() string
}

具体的类必须要重写接口中所有的方法，如果没有重写完全的话，接口的指针就无法指向具体的类。

cat类：

type Cat struct {
    Color string
}

func (cat *Cat) Sleep() {
    fmt.Printf("Cat is sleeping...\n")
}
func (cat *Cat) GetColor() string {
    return cat.Color
}
func (cat *Cat) GetType() string {
    return "Cat"
}

dog类：

type Dog struct {
    Color string
}

func (dog *Dog) Sleep() {
    fmt.Printf("Dog is sleeping...\n")
}
func (dog *Dog) GetColor() string {
    return dog.Color
}
func (dog *Dog) GetType() string {
    return "Dog"
}

具体用法

func main() {
    // 父类对象指针指向子类指针，调用的方法是子类的方法
    var animal Animal
    animal = &Cat{"red"}
    animal.Sleep()

    animal = &Dog{"yellow"}
    animal.Sleep()
}

输出：

1
2

Cat is sleeping...
Dog is sleeping...

// 注意，这边的Animal接口类本质是一个指针，所有传参时应该穿指针进去
func ShowAnimal(animal Animal) {
    animal.Sleep()
    fmt.Println(animal.GetColor())
    fmt.Println(animal.GetType())
}

func main() {
    // 可以定义具体的类然后取地址
    cat := Cat{"red"}
    dog := Dog{"yellow"}
    ShowAnimal(&cat)
    fmt.Printf("==============\n")
    ShowAnimal(&dog)
    fmt.Printf("==============\n")

    // 也可以直接定义类的指针然后传指针
    catP := &Cat{"red"}
    dogP := &Dog{"yellow"}
    ShowAnimal(catP)
    fmt.Printf("==============\n")
    ShowAnimal(dogP)
}

输出：

Cat is sleeping...
red
Cat
==============
Dog is sleeping...
yellow
Dog
==============
Cat is sleeping...
red
Cat
==============
Dog is sleeping...
yellow
Dog

interface空接口万能类型与类型断言机制

interface空接口

interface{}是万能数据类型

// interface{}是万能数据类型
func myFunc(arg interface{}) {
	fmt.Println("myFunc is called...")
	fmt.Println(arg)
	fmt.Println("type of arg: ", reflect.TypeOf(arg))
	// 或者是
	// fmt.Printf("type of d: %T\n", arg)
}
func main() {
	myFunc(1)
	myFunc("Hello World")
	myFunc(true)
}

输出：

myFunc is called...
1
type of arg:  int
myFunc is called...
Hello World
type of arg:  string
myFunc is called...
true
type of arg:  bool

类型断言机制

interface{}提供“类型断言”的机制，用于区分此时引用的底层数据类型到底是什么

// interface{}是万能数据类型
func myFunc(arg interface{}) {
	value, ok := arg.(int)
	if !ok {
		fmt.Println("arg is not int type")
	} else {
		fmt.Println("arg is int type, value is: ", value)
	}
}

func main() {
	myFunc(1)
	myFunc("Hello World")
	myFunc(true)
}

输出：

1
2
3

arg is int type, value is:  1
arg is not int type
arg is not int type

变量内置的pair结构详细说明

在 Go 中，一个接口变量（interface variable）在运行时内部可以看作是一个pair：(Type, Value)

Type(动态类型)：这是接口实际持有的具体类型（例如 *Book）。
Value (动态值)：这是持有具体数据的指针或值的副本。

定义接口与结构体

type Reader interface { ReadBook() }
type Writer interface { WriteBook() }
type Book struct {}

// *Book 实现了 Reader 接口
func (b *Book) ReadBook() { fmt.Println("Read a book.") }
// *Book 实现了 Writer 接口
func (b *Book) WriteBook() { fmt.Println("Write a book.") }

这里 *Book（Book 的指针类型）同时实现了 Reader 和 Writer 两个接口的全部方法。这意味着 *Book 类型的变量既可以赋值给 Reader，也可以赋值给 Writer。

func main() {
	// b: pair<type:Book, value:book{}地址>
	b := &Book{"To Live"}

	// r: pair<type: , value: >
	var r Reader
	fmt.Println(reflect.TypeOf(r), r)
	// r: pair<type:Book, value:book{}地址>
	r = b
	fmt.Println(reflect.TypeOf(r), r)
	r.ReadBook()

	// w: pair<type: , value: >
	var w Writer
	fmt.Println(reflect.TypeOf(w), w)
	// w: pair<type:Book, value:book{}地址>
	w = r.(Writer)
	fmt.Println(reflect.TypeOf(w), w)
	w.WriteBook()
}

输出：

<nil> <nil>
*main.Book &{To Live}
Read a book.
<nil> <nil>
*main.Book &{To Live}
Write a book.

从上面的输出可以看出，接口类在未赋值时的pair为(nil,nil)。我们可以把 r 和 w 想象成两个不同的“窗口”，它们看着同一个“房间”（具体的 Book 对象）：

b (具体指针):

指向内存中的 Book{}。

r (Reader 接口):

动态类型: *Book
动态值: 指向 b
能力: 只能看见 ReadBook()

w (Writer 接口):

(通过 r.(Writer) 转换而来)
动态类型: *Book (和 r 一样！)
动态值: 指向 b (和 r 一样！)
能力: 只能看见 WriteBook()

反射reflect机制用法

反射基本类型

reflect.TypeOf() 用于获取变量的类型
reflect.ValueOf() 用于获取变量的值

// interface{}作为万能类型，类似模板
func reflectNum(arg interface{}) {
	fmt.Println("type : ", reflect.TypeOf(arg))
	fmt.Println("value : ", reflect.ValueOf(arg))
}
func main() {
	var num float64 = 3.1415926

	reflectNum(num)
}

输出：

1
2

type :  float64
value :  3.1415926

反射复杂类型

type User struct {
	Id   int
	Name string
	Age  int
}

func (u *User) Call() {
	fmt.Println("user is called ..")
	fmt.Printf("%v\n", u)
}
func (u User) Display() {
	fmt.Println("user is displayed ..")
	fmt.Printf("%v\n", u)
}

func DoFiledAndMethod(input interface{}) {
	//获取input的type
	inputType := reflect.TypeOf(input)
	fmt.Println("inputType : ", inputType)

	//获取input的value
	inputValue := reflect.ValueOf(input)
	fmt.Println("inputValue : ", inputValue)

	//通过type获取里面的字段
	//1. 获取interface的reflect.Type，通过Type得到NumField，进行遍历
	//2. 得到每个field，数据类型
	//3. 通过field有一个Interface()方法得到对应的value
	for i := 0; i < inputType.NumField(); i++ {
		field := inputType.Field(i)
		value := inputValue.Field(i).Interface()

		// 变量名 变量类型：变量的值
		fmt.Printf("%s %s: %v\n", field.Name, field.Type, value)
	}

	//通过type获取里面的方法，调用
	fmt.Println(inputType.NumMethod())
 	// 这里得到的是1，因为Call方法是绑定在*User类型上的，而本方法中reflect.TypeOf()传的是User类型，所以不会计算Call方法
	
 	for i := 0; i < inputType.NumMethod(); i++ {
		method := inputType.Method(i)
		fmt.Printf("%s %s: %v\n", method.Name, method.Type, method.Func)
	}
    
}
func main() {
	user := User{1, "wxz", 22}

	DoFiledAndMethod(user)
}

输出：

inputType :  main.User
inputValue :  {1 wxz 22}
Id int: 1
Name string: wxz
Age int: 22
1
Display func(main.User): 0x7ff7b08a24e0

结构体标签

相当于注释

type Resume struct {
	Name string `info:"name" doc:"我的名字"`
	Sex  string `info:"sex"`
}

func findTag(str interface{}) {
	//t := reflect.TypeOf(str).Elem() // Elem()表示当前结构体的所有元素，其作用是获取指针指向的元素，或者容器（如 Map、Slice、Array、Chan）里的元素类型。
	t := reflect.TypeOf(str)

	for i := 0; i < t.NumField(); i++ {
		taginfo := t.Field(i).Tag.Get("info")
		tagdoc := t.Field(i).Tag.Get("doc")
		fmt.Println("info:", taginfo, " doc:", tagdoc)
	}
}
func main() {
	var re Resume
	re = Resume{"wxz", "male"}

	findTag(re)
}

输出：

1
2

info: name  doc: 我的名字
info: sex  doc:

结构体标签在json中的应用

前置准备（导包，创建结构体）：

import (
	"encoding/json"
	"fmt"
)

type Movie struct {
	Title  string   `json:"title"`
	Year   int      `json:"year"`
	Price  int      `json:"rmb"`
	Actors []string `json:"actors"`
}

编码的过程结构体—> json

movie := Movie{"喜剧之王", 2000, 10, []string{"xingye", "zhangbozhi"}}

	// 编码的过程  结构体---> json
	jsonStr, err := json.Marshal(movie)

	if err != nil {
		fmt.Println("json marshal error:", err)
		return
	}

	// 这边输出的字段的名称就是上面在结构体中写的标签
	fmt.Println("jsonStr =", string(jsonStr))
	// 或者 fmt.Printf("jsonStr = %s\n", string(jsonStr))

输出如下，可以复制到json在线解析的网站中验证：

`1`	`jsonStr = {"title":"喜剧之王","year":2000,"rmb":10,"actors":["xingye","zhangbozhi"]}`

解码的过程 jsonstr—> 结构体

	//jsonStr = {"title":"喜剧之王","year":2000,"rmb":10,"actors":["xingye","zhangbozhi"]}
	my_movie := Movie{}
	err = json.Unmarshal(jsonStr, &my_movie)
	if err != nil {
		fmt.Println("json unmarshal error:", err)
		return
	}
	fmt.Printf("%#v\n", my_movie)
	fmt.Printf("%v\n", my_movie)

输出：

1
2

main.Movie{Title:"喜剧之王", Year:2000, Price:10, Actors:[]string{"xingye", "zhangbozhi"}}
{喜剧之王 2000 10 [xingye zhangbozhi]}

第四部分

goroutine基本模型和调度设计策略

在go中把协程co-routine做了一些修改，包括内存占用和名字（goroutine）。

最大支持GOMAXPROCS个goroutine并行

创建goroutine

// 子goroutine
func newTask() {
	i := 0
	for { // 死循环
		i++
		fmt.Printf("new Goroutine : i = %d\n", i)
		time.Sleep(1 * time.Second)
	}
}

// 主goroutine
func main() {
	// go关键字：创建一个go程，去执行newTask() 流程
	go newTask()

	i := 0
	for { // 死循环
		i++
		fmt.Printf("main Goroutine : i = %d\n", i)
		time.Sleep(1 * time.Second)
	}
}

输出：

main Goroutine : i = 1
new Goroutine : i = 1
new Goroutine : i = 2
main Goroutine : i = 2
new Goroutine : i = 3
main Goroutine : i = 3
...
...

也可以用匿名函数创建goroutine

// 主goroutine
func main() {

	// 用go创建承载一个形参为空，返回值为空的一个函数
	go func() {
		defer fmt.Println("A.defer")

		func() {
			defer fmt.Println("B.defer")
			// 退出当前goroutine
			runtime.Goexit()
			fmt.Println("B")
		}()

		fmt.Println("A")
		//// 退出当前goroutine
		//runtime.Goexit()

	}() // 最后这对括号用于传参

	go func(a int, b int) bool {
		fmt.Println("a = ", a, "b = ", b)
		return true
	}(10, 20)

	for {
		time.Sleep(1 * time.Second)
	}
}

输出：

B
B.defer
A
A.defer
a =  10 b =  20

其中，下面这条语句用于退出当前goroutine

`1`	`runtime.Goexit()`

channel的基本定义和使用

无缓冲channel

无缓冲的channel若只有写没有读，则写go程会阻塞；如果只有读没有写，则读go程会阻塞。

	// 定义一个无缓冲区的channel，channel就是一个数据结构，且能够保证goroutine间的同步和互斥
	c := make(chan int)

	go func() {
		defer fmt.Println("goroutine结束")

		fmt.Println("goroutine 正在运行...")

		c <- 666 // 将666发送给c
	}()

	num := <-c // 从c中接收数据，并赋值给num

	fmt.Println("num =", num)
	fmt.Println("main goroutine 结束...")

输出：

goroutine 正在运行...
goroutine结束
num = 666
main goroutine 结束...

有缓冲channel

有缓冲的channel只有当缓冲区满且还在写入时，写go程才会阻塞；只有当缓冲区空且还在读取时，读go程才会阻塞。

c := make(chan int, 3) // 带有3个缓冲区的channel

	fmt.Println("len(c) =", len(c), "cap(c) =", cap(c))

	go func() {
		defer fmt.Println("子go程结束")

		for i := 0; i < 4; i++ {
			c <- i
			fmt.Println("子go程正在运行，发送的元素 =", i, " len(c) =", len(c), ", cap(c) =", cap(c))
		}
	}()

	time.Sleep(2 * time.Second)

	for i := 0; i < 4; i++ {
		num := <-c // 从c中接收数据，并赋值给num
		fmt.Println("num =", num)
	}

	fmt.Println("main 结束")

当channel满，若继续写数据，则会阻塞。
当channel空，若继续读数据，也会阻塞。
输出：

len(c) = 0 cap(c) = 3
子go程正在运行，发送的元素 = 0  len(c) = 1 , cap(c) = 3
子go程正在运行，发送的元素 = 1  len(c) = 2 , cap(c) = 3
子go程正在运行，发送的元素 = 2  len(c) = 3 , cap(c) = 3
num = 0
num = 1
num = 2
num = 3
main 结束
子go程正在运行，发送的元素 = 3  len(c) = 2 , cap(c) = 3
子go程结束

channel的关闭特点

close关键字可以关闭一个channel，channel关闭后只能读不能写，且向未make的channel（nil channel）收发数据都会被阻塞

	c := make(chan int)

	go func() {
		for i := 0; i < 5; i++ {
			c <- i
		}

		// close关键字可以关闭一个channel，channel关闭后只能读不能写，且向未make的channel（nil channel）收发数据都会被阻塞
		close(c)
	}()

	for {
		// ok 如果为true表示channel没有关闭，如果为false表示channel已经关闭
		if data, ok := <-c; ok { // if的条件是 ok
			fmt.Println(data)
		} else {
			break
		}
	}

	fmt.Println("Main finished...")

输出：

0
1
2
3
4
Main finished...

channel与range

类似C++中的for(auto i:arr)

	c := make(chan int)

	go func() {
		for i := 0; i < 5; i++ {
			c <- i
		}

		// close关键字可以关闭一个channel，channel关闭后只能读不能写，且向未make的channel（nil channel）收发数据都会被阻塞
		close(c)
	}()

	/*  
	for {
		// ok 如果为true表示channel没有关闭，如果为false表示channel已经关闭
		if data, ok := <-c; ok { // if的条件是 ok
			fmt.Println(data)
		} else {
			break
		}
	}
	*/
    // 上面这段代码可以替换为下面这段代码

	// 可以使用range来迭代不断操作channel
	for data := range c {
		fmt.Println(data)
	}

	fmt.Println("Main finished...")

输出相同：

0
1
2
3
4
Main finished...

channel与select

单流程下的一个go只能监控一个channel的状态，通过select可以监控多个channel的状态

func fibonacci(c chan int, quit chan int) {
	x, y := 1, 1

	for {
		select {
		case c <- x: // 如果c可写，则此case就会进来
			x, y = y, x+y
		case <-quit: // 如果quit可读，则此case就会进来
			fmt.Println("quit")
			return
		}
	}
}

func main() {
	c := make(chan int)
	quit := make(chan int)

	// sub go
	go func() {
		for i := 0; i < 6; i++ {
			fmt.Println(<-c)
		}

		quit <- 0
	}()

	// main go，channel传参传的都是引用
	fibonacci(c, quit)
}

输出：

1
1
2
3
5
8
quit

第五部分

什么是Go Modules？

Go modules是Go语言的依赖解决方案，发布于Go1.11，成长于Go1.12，丰富于Go1.13，正式于Go1.14，推荐在生产上使用。

Go modules目前集成在Go的工具链中，只要安装了Go，自然而然也就可以使用Go modules了，而Go modules的出现也解决了在Go1.11前的几个常见争议问题：

Go语言长久以来的依赖管理问题。
“淘汰”现有的GOPATH的使用模式。
同意社区中的其他的依赖管理工具（提供迁移功能）。

GOPATH的弊端

在 GOPATH 的 $GOPATH/src 下进行 .go 文件或源代码的存储，我们可以称其为 GOPATH 的模式，这个模式拥有一些弊端。

A. 无版本控制概念。 在执行go get的时候，你无法传达任何的版本信息的期望，也就是说你也无法知道自己当前更新的是哪一个版本，也无法通过指定来拉取自己所期望的具体版本。
B.无法同步一致第三方版本号。在运行 Go 应用程序的时候，你无法保证其它人与你所期望依赖的第三方库是相同的版本，也就是说在项目依赖库的管理上，你无法保证所有人的依赖版本都一致。
C.无法指定当前项目引用的第三方版本号。没办法处理 v1、v2、v3 等等不同版本的引用问题，因为 GOPATH 模式下的导入路径都是一样的，都是github.com/foo/bar。

Go Modules模式

go mod命令
go mod环境变量可以通过 go env 命令来进行查看

GO111MODULE

Go语言提供了 GO111MODULE这个环境变量来作为 Go modules 的开关，其允许设置以下参数：

auto：只要项目包含了 go.mod 文件的话启用 Go modules，目前在 Go1.11 至 Go1.14 中仍然是默认值。
on：启用 Go modules，推荐设置，将会是未来版本中的默认值。
off：禁用 Go modules，不推荐设置。

可以在终端执行：go env -w GO111MODULE=on 来设置。

GOPROXY

这个环境变量主要是用于设置 Go 模块代理（Go module proxy）,其作用是用于使 Go 在后续拉取模块版本时直接通过镜像站点来快速拉取。

GOPROXY 的默认值是：https://proxy.golang.org,direct

实际上 “direct” 是一个特殊指示符，用于指示 Go 回源到模块版本的源地址去抓取（比如 GitHub 等），场景如下：当值列表中上一个 Go 模块代理返回 404 或 410 错误时，Go 自动尝试列表中的下一个，遇见 “direct” 时回源，也就是回到源地址去抓取，而遇见 EOF 时终止并抛出类似 “invalid version: unknown revision…” 的错误。

GOSUMDB

它的值是一个 Go checksum database，用于在拉取模块版本时（无论是从源站拉取还是通过 Go module proxy 拉取）保证拉取到的模块版本数据未经过篡改，若发现不一致，也就是可能存在篡改，将会立即中止。

GOSUMDB 的默认值为：sum.golang.org，在国内也是无法访问的，但是 GOSUMDB 可以被 Go 模块代理所代理（详见：Proxying a Checksum Database）。

因此我们可以通过设置 GOPROXY 来解决，而先前我们所设置的模块代理 goproxy.cn 就能支持代理 sum.golang.org，所以这一个问题在设置 GOPROXY 后，你可以不需要过度关心。

另外若对 GOSUMDB 的值有自定义需求，其支持如下格式：

格式 1：<SUMDB_NAME>+<PUBLIC_KEY>。
格式 2：<SUMDB_NAME>+<PUBLIC_KEY> <SUMDB_URL>。

也可以将其设置为“off”，也就是禁止 Go 在后续操作中校验模块版本。

GONOPROXY/GONOSUMDB/GOPRIVATE

这三个环境变量都是用在当前项目依赖了私有模块，例如像是你公司的私有 git 仓库，又或是 github 中的私有库，都是属于私有模块，都是要进行设置的，否则会拉取失败。

更细致来讲，就是依赖了由 GOPROXY 指定的 Go 模块代理或由 GOSUMDB 指定 Go checksum database 都无法访问到的模块时的场景。

而一般建议直接设置 GOPRIVATE，它的值将作为 GONOPROXY 和 GONOSUMDB 的默认值，所以建议的最佳姿势是直接使用 GOPRIVATE。

并且它们的值都是一个以英文逗号 “,” 分割的模块路径前缀，也就是可以设置多个，例如：

`1`	`$ go env -w GOPRIVATE="git.example.com,github.com/eddycjy/mquote"`

设置后，前缀为 git.xxx.com 和 github.com/eddycjy/mquote 的模块都会被认为是私有模块。

如果不想每次都重新设置，我们也可以利用通配符，例如：

`1`	`$ go env -w GOPRIVATE="*.example.com"`

这样子设置的话，所有模块路径为 example.com 的子域名（例如：git.example.com）都将不经过 Go module proxy 和 Go checksum database，需要注意的是不包括 example.com 本身。

Backend 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 框架零基础教程：从入门到实战

前言

什么是 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` 不等于自动更快

2.1 IP 地址（`IP` 类型）

2.2 IP 网段（`IPNet` 类型）

3.3.1 禁用 Nagle 算法（`SetNoDelay`）

3.3.2 TCP 保活机制（`SetKeepAlive`）

6.1 网络错误类型（`net.Error`）

7. 高级连接配置：`Dialer`