Web 开发 on 扎塔-Zata

Celery

Mon, 20 Oct 2025 17:12:13 +0800

Celery 详细使用教程：从入门到实践

什么是 Celery？

Celery 是一个强大、简单、灵活的分布式异步任务队列 (Asynchronous Task Queue)。它主要用于处理那些耗时较长或者可以稍后执行的任务，从而避免阻塞主程序（例如一个 Web 请求）。

主要使用场景：

异步任务： 用户注册后发送欢迎邮件、处理用户上传的图片（缩放、加水印）、生成复杂的报表。
定时任务： 每天凌晨清理一次数据、每小时从第三方 API 同步一次信息。

核心概念

要理解 Celery，你必须先了解它的四个核心组件：

生产者 (Producer)： 也就是你的主程序（例如 Flask/Django 应用）。它负责创建任务并将其发送到任务队列中。
Broker (消息中间件)： 任务的“信箱”或“中转站”。生产者将任务放入 Broker，Worker 从 Broker 中取出任务。最常用的 Broker 是 RabbitMQ（功能最全，官方推荐）和 Redis（轻量，易于上手）。
Worker (消费者)： 真正执行任务的进程。它会持续监控 Broker，一旦发现新任务，就取出并执行它。你可以同时运行多个 Worker 来实现分布式处理。
Backend (结果存储)： （可选）用于存储任务执行结果的地方。如果你需要稍后查询任务的状态或返回值（例如，在网页上显示“报表已生成”），你就需要配置 Backend。常用的 Backend 包括 Redis、RabbitMQ (amqp) 或数据库 (SQLAlchemy)。

工作流程： 生产者 (App) -> 发送任务 -> Broker (Redis/RabbitMQ) -> Worker (领取任务) -> 执行任务 -> (可选) 存入结果 -> Backend (Redis/DB)

第一部分：快速入门 (Hello, World)

我们将使用 Redis 作为 Broker 和 Backend，因为它安装简单，配置方便。

第1步：环境准备

确保你已经安装了 Python 和 Redis。

安装 Redis：
- (macOS) brew install redis，然后 redis-server
- (Linux) sudo apt install redis-server
- (Windows) 建议使用 WSL2 或 Docker。
- 确保 Redis 服务正在 localhost:6379 上运行。
安装 Python 库：
```
pip install celery redis
```

第2步：创建 Celery 应用和任务

创建一个名为 tasks.py 的文件。

import time
from celery import Celery

# 1. 创建 Celery 实例
# 第一个参数 'tasks' 是当前模块的名称，这在自动生成任务名时很重要。
# broker 和 backend 都指向我们的 Redis 服务。
# /0 和 /1 代表 Redis 的不同数据库 (db)，避免数据混淆。
app = Celery('tasks',
 broker='redis://localhost:6379/0',
 backend='redis://localhost:6379/1')

# 2. 定义一个任务
# @app.task 装饰器将这个函数注册为 Celery 任务
@app.task
def add(x, y):
 print(f"开始执行任务: {x} + {y}")
 time.sleep(5) # 模拟一个耗时的操作
 result = x + y
 print(f"任务执行完毕: {result}")
 return result

@app.task
def send_email(to, subject, body):
 print(f"向 {to} 发送邮件...")
 time.sleep(3) # 模拟I/O操作
 print(f"邮件发送成功: 主题 {subject}")
 return "Success"

第3步：运行 Celery Worker

打开一个终端，cd 到 tasks.py 所在的目录，然后运行 Worker 进程：

# -A tasks: 指定 Celery 实例 (app) 在 'tasks' 模块中
# worker: 启动 worker 进程
# --loglevel=info: 设置日志级别为 INFO，方便我们观察
celery -A tasks worker --loglevel=info

如果一切正常，你会看到一个 ASCII art 组成的 Celery Logo，并提示 [tasks]... ready.。这表示 Worker 已经连接到 Redis 并准备好接收任务了。

第4步：调用任务

打开第二个终端（保持 Worker 终端运行），进入 Python 交互环境（如 ipython 或 python）：

>>> from tasks import add, send_email

# 1. 异步调用任务
# .delay() 是 .apply_async() 的快捷方式
# 注意：这行代码会 *立即* 返回，不会等待 5 秒
print("准备调用 add(4, 4)...")
task_result = add.delay(4, 4)
print("任务已发送，ID:", task_result.id)

# 2. 尝试调用另一个任务
print("准备发送邮件...")
email_task = send_email.delay("user@example.com", "你好", "这是一封测试邮件。")
print("邮件任务已发送，ID:", email_task.id)

# 3. 查看 Worker 终端
# 此时，你应该能在第一个终端（Worker 终端）看到任务开始执行的日志。

第5步：获取任务结果

在第二个终端（Python 交互环境）中，我们可以使用 task_result 对象（它是一个 AsyncResult 实例）来检查任务状态和获取结果：

>>> # 检查任务是否完成
>>> task_result.ready()
False # (可能还是 False，因为任务在 sleep(5))

# (等待几秒钟)

>>> task_result.ready()
True

>>> # 获取任务状态
>>> task_result.status
'SUCCESS'

>>> # 获取任务的返回值
>>> # .get() 会阻塞当前进程，直到拿到结果
>>> result_value = task_result.get()
>>> print(result_value)
8

>>> # 检查邮件任务
>>> email_task.get()
'Success'

>>> # 如果任务执行出错
>>> # 你可以通过 .status 查看
# 假设我们定义了一个出错的任务
# task_error = error_task.delay()
# task_error.status
# 'FAILURE'
# task_error.get() # 这将会抛出异常

第二部分：与 Web 框架集成 (以 FastAPI 为例)

在真实项目中，你通常会在 Web 应用（如 FastAPI）中调用 Celery 任务。FastAPI 是一个现代、高性能的 Python Web 框架，基于 ASGI，支持异步操作，与 Celery 集成非常自然。

项目结构

my_fastapi_project/
├── main.py # FastAPI 应用
├── celery_app.py # Celery 实例和配置
├── tasks.py # 任务定义
└── requirements.txt

requirements.txt 示例（添加 FastAPI 相关依赖）：

fastapi==0.104.1
uvicorn[standard]==0.24.0
celery==5.3.6
redis==5.0.1

第1步：配置 Celery (celery_app.py)

创建一个中心化的 Celery 实例。由于 FastAPI 没有内置的 app.config，我们使用一个配置字典来传递参数。

# celery_app.py
from celery import Celery

# 创建 Celery 实例
celery = Celery(__name__)

# 从配置中加载 Celery 配置
def init_celery(app, config):
 celery.conf.update(config)

 # (可选) 让任务可以使用 FastAPI 的 app context（如果任务需要访问 app 状态）
 # FastAPI 没有传统的 app_context，但我们可以用类似方式处理依赖
 class ContextTask(celery.Task):
 def __call__(self, *args, **kwargs):
 # 这里可以注入 FastAPI 的依赖，如果需要
 # 对于简单任务，可省略
 return self.run(*args, **kwargs)

 celery.Task = ContextTask

第2步：定义任务 (tasks.py)

任务定义与 Flask 示例相同，几乎无需改动。

# tasks.py
import time
from celery_app import celery

# 注意：我们现在从 celery_app 导入 celery 实例
@celery.task
def long_running_simulation(user_id):
 print(f"开始为用户 {user_id} 运行模拟...")
 time.sleep(10) # 模拟一个非常耗时的操作
 print(f"用户 {user_id} 的模拟运行完毕。")
 return f"Report for {user_id}"

第3步：配置 FastAPI (main.py)

# main.py
from fastapi import FastAPI, Query
from celery_app import celery, init_celery
from tasks import long_running_simulation

app = FastAPI()

# 配置（这里直接定义，也可以用环境变量或 pydantic-settings）
config = {
 # Celery Broker
 "CELERY_BROKER_URL": "redis://localhost:6379/0",
 # Celery Backend
 "CELERY_RESULT_BACKEND": "redis://localhost:6379/1"
}

# 初始化 Celery
init_celery(app, config)

@app.get("/")
def index():
 return {"message": "你好, Celery 和 FastAPI!"}

@app.get("/start-task")
def start_task(user_id: str = Query("default_user", description="用户 ID")):
 # 这是一个 Web 请求，我们不想让它等待 10 秒
 # 我们立即将任务推送到队列
 task = long_running_simulation.delay(user_id)

 # 立即返回，并告诉前端任务 ID
 return {
 "message": "任务已启动",
 "task_id": task.id
 }, 202 # 202 Accepted 表示请求已被接受，正在处理

@app.get("/task-status/{task_id}")
def task_status(task_id: str):
 # 从 Backend 查询任务状态
 task_result = long_running_simulation.AsyncResult(task_id)

 if task_result.state == "PENDING":
 # 任务还在队列中，或刚开始
 response = {
 "state": task_result.state,
 "status": "Pending..."
 }
 elif task_result.state != "FAILURE":
 response = {
 "state": task_result.state,
 "status": "In progress...",
 }
 if task_result.state == "SUCCESS":
 response["result"] = task_result.get() # 获取最终结果
 else:
 response["result"] = task_result.info # 如果任务正在进行，.info 可能包含中间状态
 else:
 # 任务失败
 response = {
 "state": task_result.state,
 "status": str(task_result.info), # 失败的异常信息
 }
 return response

注意：

FastAPI 支持自动生成 OpenAPI 文档，你可以访问 /docs 查看交互式 API 文档。
如果需要异步路由，可以将 @app.get 改为 async def，但这里任务是同步的 Celery 调用，无需。

第4步：运行

你需要运行两个服务（确保 Redis 已启动）：

终端 1 (Celery Worker)：
```
# -A 参数指向 celery 实例所在的模块
# 指向 tasks.py 中导入的 celery 实例
celery -A tasks.celery worker --loglevel=info
```
（注：更健壮的方式是使用 celery -A celery_app.celery worker，取决于你的 __name__ 设置。指向 tasks.celery 通常可行。）

终端 2 (FastAPI App)：

uvicorn main:app --reload --host 127.0.0.1 --port 8000

测试：

访问 http://127.0.0.1:8000/start-task?user_id=123
- 你会立即收到一个 JSON 响应，包含 task_id。
- 同时，观察 Worker 终端，你会看到它开始执行 long_running_simulation。
复制那个 task_id。
访问 http://127.0.0.1:8000/task-status/{your_task_id}
- 一开始，你可能会看到 “Pending” 或 “In progress”。
- 等待 10 秒后刷新，你会看到 “SUCCESS” 和 result: "Report for 123"。
额外：访问 http://127.0.0.1:8000/docs 查看 Swagger UI，方便测试 API。

这个示例保持了与 Flask 版本的相似性，便于迁移。如果你的项目需要数据库集成或其他依赖，可以在 Celery 任务中使用 FastAPI 的依赖注入系统进一步扩展。

第三部分：定时任务 (Celery Beat)

Celery Beat 是一个调度器 (Scheduler)。它负责按计划将任务发送到 Broker，而 Worker 负责执行它们。

第1步：配置 Beat

在你的 Celery 配置中（例如 celery_app.py 或 tasks.py）添加 beat_schedule：

# 在 tasks.py 中
from celery.schedules import crontab

# ... (app = Celery(...) 的定义) ...

@app.task
def periodic_task():
 print("这是一个每 30 秒执行一次的定时任务！")

# 配置定时任务
app.conf.beat_schedule = {
 # 任务名称
 'run-every-30-seconds': {
 'task': 'tasks.periodic_task', # 任务的完整路径名
 'schedule': 30.0, # 每 30 秒
 'args': () # 任务参数（这里没有）
 },
 # 也可以使用 crontab
 'run-every-midnight': {
 'task': 'tasks.add',
 'schedule': crontab(minute=0, hour=0), # 每天午夜
 'args': (100, 200),
 }
}

# (可选) 设置时区，确保 crontab 按你期望的时区执行
app.conf.timezone = 'Asia/Shanghai'

第2步：运行 Beat

要运行定时任务，你至少需要两个进程：

Worker 进程（用于执行任务）：
```
celery -A tasks worker --loglevel=info
```
Beat 进程（用于调度任务）：
```
celery -A tasks beat --loglevel=info
```

快捷方式（开发时用）：

你也可以在一个命令中同时启动 Worker 和 Beat（不推荐在生产环境中使用 -B）：

# -B 选项表示同时启动一个嵌入的 Beat 进程
celery -A tasks worker -B --loglevel=info

启动后，你将看到 Worker 终端每 30 秒打印一次 “这是一个每 30 秒执行一次的定时任务！"。

第四部分：监控与最佳实践

1. 监控：Flower

Flower 是一个基于 Web 的 Celery 监控工具。

安装：
```
pip install flower
```

运行：

# 指向你的 Celery app，并启动 flower
celery -A tasks flower --port=5555

访问 http://localhost:5555，你将看到一个仪表盘，显示所有 Worker 的状态、已完成的任务、队列中的任务等。

2. 任务重试

网络抖动或临时性错误很常见。Celery 允许你轻松地重试任务。

import requests

# bind=True: 将任务实例 (self) 作为第一个参数注入
# max_retries: 最大重试次数
# default_retry_delay: 默认重试间隔（秒）
@app.task(bind=True, max_retries=3, default_retry_delay=60)
def fetch_api_data(self, url):
 try:
 response = requests.get(url, timeout=5)
 response.raise_for_status() # 如果是 4xx/5xx 错误，抛出异常
 return response.json()
 except requests.exceptions.RequestException as exc:
 print(f"请求失败: {exc}。正在重试...")
 # self.retry() 会抛出一个 Retry 异常，Celery 会捕获它并稍后重试
 # exc=exc 会将原始异常信息传递下去
 raise self.retry(exc=exc)

3. 关键配置项

在生产环境中，你可能需要调整一些配置：

task_serializer: 推荐使用 json 或 pickle。json 更安全，但支持的数据类型有限。
result_serializer: 同上。
task_track_started: (True) 是否在任务开始执行时就将其状态报告为 “STARTED”。
worker_concurrency: Worker 进程数，默认是 CPU 核心数。可以根据任务是 I/O 密集型还是 CPU 密集型来调整。
task_acks_late: (False) 默认情况下，Worker 在收到任务后立即向 Broker 发送确认（ack），然后才执行。如果 Worker 在执行中崩溃，任务会丢失。
- 如果设置为 True，Worker 会在任务 执行完毕 后才发送 ack。如果 Worker 崩溃，Broker 会将任务重新分配给其他 Worker。这保证了任务至少被执行一次（但可能重复执行），称为“at-least-once delivery”。

其他知识点

shared_task与app.task的区别

@shared_task 是 Celery 中一个非常重要且常用的装饰器。它的核心作用是创建可复用的、不依赖于任何特定 Celery 应用实例（app instance）的任务。

这使得它在编写可插拔的 Django、fastapi 应用、库或任何希望与项目主 Celery 应用解耦的模块时，成为首选的工具。

核心理念：为什么需要 shared_task？在标准的 Celery 设置中，你可能会这样定义一个任务：


# myproject/celery.py
from celery import Celery
app = Celery('myproject')
app.config_from_object('django.conf:settings', namespace='CELERY')

# myproject/myapp/tasks.py
from myproject.celery import app

@app.task
def add(x, y):
 return x + y

这种方法的问题在于，myapp/tasks.py 模块硬编码了对 myproject.celery.app 实例的导入。

想象一下，如果你正在编写一个希望被多个项目（比如一个开源的 Django 插件）使用的 myapp，你并不知道其他项目的 Celery 实例会叫什么名字，或者在哪里定义。如果强行导入 myproject.celery.app，这个应用在其他项目中将无法使用。

@shared_task 解决了这个问题。它创建的任务是一个“懒加载”的代理，它会在运行时自动绑定到当前项目配置的 Celery 实例上。

详细用法使用 @shared_task 非常简单，只需从 celery 模块中导入它即可。


from celery import shared_task

@shared_task
def add(x, y):
 print(f'Adding {x} + {y}')
 return x + y

当然！@shared_task 的核心优势在于解耦，它允许你定义的任务不依赖任何具体的 Celery 应用（app）实例。这在 FastAPI 项目中尤其有用，可以让你将任务逻辑（tasks.py）与应用实例配置（celery_app.py）和 Web 服务（main.py）完全分开，避免循环导入问题。下面是一个以 FastAPI 为例的详细教程。

核心理念：为什么在 FastAPI 中使用 shared_task？

想象一个场景：

你在 main.py 中创建了 FastAPI app 和 Celery celery_app。
你在 tasks.py 中定义了一个任务，这个任务需要从 main.py 导入某个工具函数或配置。
同时，你的 main.py 中的 Celery celery_app 需要导入 tasks.py 来注册任务。这就造成了循环导入（Circular Import），你的应用将无法启动。 @shared_task 解决了这个问题。你可以在 tasks.py 中定义任务，而无需从任何地方导入 Celery app 实例。然后，你创建一个单独的 celery_app.py 文件来实例化 Celery，并告诉它去哪里发现这些 shared_task。

Part 1: 项目结构

一个清晰的 FastAPI + Celery 项目结构如下：

fastapi_celery_project/
├── main.py # 你的 FastAPI 应用
├── celery_app.py # Celery 实例和配置
├── tasks/
│ ├── __init__.py
│ └── email_tasks.py # 使用 @shared_task 定义任务
└── requirements.txt

Part 2: 依赖安装

requirements.txt:

fastapi
uvicorn[standard]
celery
redis
* celery[redis] 也可以，它会捆绑 redis 库。

Part 3: 配置 Celery 实例 (celery_app.py)

这是连接所有部分的关键文件。它创建 Celery 实例，并告诉 Celery 去哪里查找任务。 celery_app.py:




from celery import Celery

# 1. 定义 Broker 和 Backend 的 URL
# 你应该使用环境变量来存储这些敏感信息，这里为了演示而硬编码
BROKER_URL = "redis://localhost:6379/0"
RESULT_BACKEND = "redis://localhost:6379/1"

# 2. 创建 Celery 实例
# 'tasks' 是这个 Celery 实例的默认名称
celery = Celery(
 'tasks',
 broker=BROKER_URL,
 backend=RESULT_BACKEND,

 # 3. 关键！指定 Celery 应该自动发现任务的模块
 # 这里我们指向 'tasks.email_tasks' 模块。
 # 这替代了 Django 的 `autodiscover_tasks()`。
 include=['tasks.email_tasks']
)

# 4. (可选) 更多 Celery 配置
celery.conf.update(
 task_serializer='json',
 accept_content=['json'],
 result_serializer='json',
 timezone='America/Los_Angeles', # 建议使用 UTC
 enable_utc=True,
 broker_connection_retry_on_startup=True,
)

Part 4: 使用 @shared_task 定义任务

现在，我们在 tasks/email_tasks.py 中定义任务，注意这里不需要导入 celery_app.py 中的 celery 实例。 tasks/email_tasks.py:




import time
from celery import shared_task

# @shared_task 装饰器让这个函数成为一个 Celery 任务
# 它不依赖于任何特定的 Celery app 实例
@shared_task
def send_welcome_email(email: str):
 """
 一个模拟发送欢迎邮件的耗时任务
 """
 print(f"Task started: Sending welcome email to {email}...")

 # 模拟一个 5 秒钟的 I/O 操作 (例如 API 调用或 SMTP 通信)
 time.sleep(5)

 print(f"Task finished: Email sent to {email}")
 return f"Successfully sent welcome email to {email}"

Part 5: 在 FastAPI 中调用任务

最后，我们在 main.py 中创建 API 端点。当端点被调用时，它会将任务推送到 Celery 队列中，然后立即返回响应。 main.py:




from fastapi import FastAPI
from tasks.email_tasks import send_welcome_email
from celery.result import AsyncResult
from celery_app import celery as celery_app_instance # 导入用于查询结果的 app 实例

app = FastAPI()

@app.get("/")
def read_root():
 return {"message": "Welcome to FastAPI + Celery"}

@app.post("/register")
def register_user(email: str):
 """
 一个注册端点，它会异步触发一个欢迎邮件任务
 """
 # .delay() 是 .apply_async() 的快捷方式
 # 它将任务发送到 Celery 队列，并立即返回
 task = send_welcome_email.delay(email)

 # 立即返回响应，告诉客户端任务已加入队列
 return {
 "message": "User registration successful. Welcome email is being sent in the background.",
 "task_id": task.id # 返回任务 ID，以便客户端稍后查询状态
 }

@app.get("/tasks/{task_id}")
def get_task_status(task_id: str):
 """
 根据任务 ID 查询任务的状态和结果
 """
 # 使用从 celery_app.py 导入的实例来创建 AsyncResult
 task_result = AsyncResult(task_id, app=celery_app_instance)

 if task_result.ready():
 # 任务已完成
 if task_result.successful():
 return {
 "task_id": task_id,
 "status": task_result.status,
 "result": task_result.get() # 获取任务的返回值
 }
 else:
 # 任务失败
 return {
 "task_id": task_id,
 "status": task_result.status,
 "result": str(task_result.info) # 获取异常信息
 }
 else:
 # 任务仍在进行中
 return {
 "task_id": task_id,
 "status": task_result.status,
 "result": None
 }

Part 6: 如何运行

你需要启动三个独立的进程：

消息代理 (Message Broker)：这里我们使用 Redis。
Celery Worker：执行任务的进程。
FastAPI 应用：接收 HTTP 请求的 Web 服务器。
启动 Redis (使用 Docker)




docker run -d -p 6379:6379 --name my-redis redis

启动 Celery Worker 在你的项目根目录 (fastapi_celery_project/) 运行：




# -A celery_app.celery 指向 '文件名.Celery实例变量名'
# worker 是命令
# --loglevel=info 是日志级别
celery -A celery_app.celery worker --loglevel=info

你会看到 Worker 启动，并成功发现了 tasks.email_tasks.send_welcome_email 任务。 3. 启动 FastAPI 服务器在另一个终端中运行：




uvicorn main:app --reload

Part 7: 测试

调用任务：curl -X POST “http://127.0.0.1:8000/register?email=example@test.com"你会立即收到响应：{“message”:“User registration successful. Welcome email is being sent in the background.”,“task_id”:”…”}
查看 Worker：在 Celery Worker 的终端中，你会看到任务在 5 秒后被执行：[… INFO/MainProcess] Task tasks.email_tasks.send_welcome_email[…] received
Task started: Sending welcome email to example@test.com…
Task finished: Email sent to example@test.com
[… INFO/MainProcess] Task tasks.email_tasks.send_welcome_email[…] succeeded in 5.01s: ‘Successfully sent email…’
查询结果 (使用你收到的 task_id)：curl http://127.0.0.1:8000/tasks/YOUR_TASK_ID_HERE
- （5秒内）状态：{“task_id”:"…",“status”:“PENDING”,“result”:null}
- （5秒后）状态：{“task_id”:"…",“status”:“SUCCESS”,“result”:“Successfully sent welcome email to example@test.com”}

shared_task 常用参数详解

@shared_task 接受所有 @app.task 的参数。

bind=True (绑定任务实例)

最常用的参数之一。它告诉 Celery 将任务实例（self）作为第一个参数传递给你的函数。这允许你访问任务的上下文（如请求ID）并执行重试。




from celery import shared_task
import requests

@shared_task(bind=True, max_retries=3)
def fetch_external_api(self, url):
 """
 一个带自动重试的任务
 self 是任务实例，不是类的 self
 """
 try:
 response = requests.get(url, timeout=10)
 response.raise_for_status() # 4xx 或 5xx 会抛出异常
 return response.json()
 except requests.RequestException as exc:
 print(f"API call failed for {url}. Retrying... (Attempt {self.request.retries + 1})")
 # self.retry() 会抛出一个异常，Celery 会捕获它并稍后重试
 # countdown=15 表示 15 秒后重试
 raise self.retry(exc=exc, countdown=15)

autoretry_for (自动重试)

bind=True 和 self.retry() 的简化版。你只需指定一个异常元组，Celery 会在捕获到这些异常时自动重试。




@shared_task(
 autoretry_for=(requests.RequestException, KeyError),
 retry_kwargs={'max_retries': 5},
 retry_backoff=True # 启用指数退避 (如 2s, 4s, 8s...)
)
def fetch_api_simple(url):
 # 不需要 try/except，也不需要 self
 # 如果 requests.get 抛出 RequestException，Celery 会自动重试
 response = requests.get(url, timeout=10)
 response.raise_for_status()
 # 如果 response.json() 中缺少某个键，抛出 KeyError，也会重试
 return response.json()['some_key']

ignore_result=True (忽略结果)

如果你的任务是“即发即忘”型（fire-and-forget），你根本不关心它的返回值（比如一个简单的日志记录任务），将此设为 True。Celery 将不会在结果后端（Redis）中存储任何结果，从而节省内存和提高性能。




@shared_task(ignore_result=True)
def log_user_action(user_id, action):
 # 这个任务只是写入日志，不需要返回任何值
 print(f"[LOG] User {user_id} performed action: {action}")

rate_limit (速率限制)

限制任务的执行频率，例如 “10/m” (每分钟 10 次) 或 “1/s” (每秒 1 次)。这对于防止对外部 API 造成过大压力非常有用。




@shared_task(rate_limit="5/m")
def call_rate_limited_api():
 # 这个任务在所有 worker 上加起来，每分钟最多执行 5 次
 ...

总结：@shared_task vs @app.task

特性	`@shared_task` (来自 `from celery import shared_task`)	`@app.task` (来自 `from celery_app import celery`)
依赖性	不依赖任何特定的 Celery app 实例。	强依赖于你导入的 `celery` 实例。
适用场景	推荐在所有项目中（包括 FastAPI）使用。 - 在 `tasks/` 模块中定义任务。 - 编写可重用库、插件。	- 仅在定义 Celery app 的主文件（`celery_app.py`）中使用。 - 非常简单的、所有代码都在一个文件中的项目。
主要优势	避免循环导入，实现代码解耦和模块化。	简单直接，但容易导致项目结构混乱。

celery调用任务的方式

在 Celery 中，调用任务（Task）的方式主要有 三种核心方法，此外还有一些辅助或高级用法。下面为你完整列出所有调用方式，并详细说明它们的作用、适用场景和区别。

✅ 一、核心调用方法（最常用）

.delay(*args, **kwargs)

作用：最简单的异步调用方式，直接将任务发送到消息队列（如 Redis）。
特点：
- 语法简洁
- 只支持传递任务参数（args 和 kwargs）
- 不支持设置执行时间、队列、重试策略等高级选项
底层实现：其实是 apply_async 的快捷封装

示例：

result = add.delay(4, 5)
result = translate_file.delay(file_path="/tmp/a.pdf", lang="zh")

✅ 适用场景：快速原型、简单任务、参数少、无需控制执行策略。

.apply_async(args=[], kwargs={}, **options)

作用：功能最全的异步调用方式，支持所有 Celery 任务调度选项。

可选参数（**options）：

参数	说明
`countdown`	多少秒后执行（如 `countdown=10` 表示 10 秒后）
`eta`	指定具体执行时间（`datetime` 对象）
`expires`	任务过期时间（秒数或 `datetime`），过期后不再执行
`queue`	发送到指定队列（需提前配置）
`routing_key`	自定义路由键（配合 RabbitMQ 使用）
`serializer`	序列化格式（如 `'json'`, `'pickle'`）
`retry`	是否自动重试（布尔值）
`retry_policy`	重试策略字典（如 `{'max_retries': 3, 'interval_start': 0}`）
`time_limit`	任务硬性超时时间（秒）
`soft_time_limit`	软超时（抛异常但可捕获）

示例：

from datetime import datetime, timedelta

 5秒后执行，60秒后过期，发到 high_priority 队列
result = translate_file.apply_async(
 kwargs={'file_path': '/tmp/doc.pdf', 'lang': 'en'},
 countdown=5,
 expires=60,
 queue='high_priority'
)

 指定时间执行
eta = datetime.utcnow() + timedelta(hours=1)
result = backup_db.apply_async(eta=eta)

✅ 适用场景：生产环境、需要精确控制任务行为（延迟、队列、过期、重试等）。

.apply(args=[], kwargs={}, **options)

作用：同步执行任务（在当前进程中立即运行，不经过消息队列！）
特点：
- 不会发送到 Broker（如 Redis）
- 不会被 Worker 执行
- 直接调用任务函数，返回结果（类似普通函数调用）
- 主要用于测试或调试

示例：

result = add.apply(args=[2, 3]) 立即执行，返回 5
print(result.get()) 5

⚠️ 警告：不要在生产 Web 请求中使用 .apply()，因为它会阻塞当前进程，失去异步意义！

✅ 适用场景：单元测试、本地调试、确保任务逻辑正确。

✅ 二、通过任务名动态调用（解耦用法）

celery_app.send_task(task_name, args=[], kwargs={}, **options)

作用：不导入任务函数，仅通过任务名字符串调用任务。
优点：
- 完全解耦：调用方不需要知道任务定义在哪个模块
- 适合微服务、插件系统、动态调度
前提：任务必须已注册（Worker 能识别该名字）

示例：

from myproject.celery import app 获取 Celery 实例

result = app.send_task(
 "doc2x.translate_file",
 kwargs={
 "file_path": "/tmp/x.pdf",
 "target_lang": "fr"
 },
 queue="translation"
)

✅ 适用场景：

调度系统不知道具体任务实现

多团队协作，任务名作为接口契约

动态决定调用哪个任务（如根据用户输入）

✅ 三、组调用与工作流（高级用法）

这些不是“单个任务调用”，而是组合多个任务的方式：

group() — 并行执行多个任务

from celery import group

jobs = group(add.s(1, 1), add.s(2, 2), add.s(3, 3))
result = jobs.apply_async()
print(result.get()) [2, 4, 6]

chain() — 串行执行（前一个输出作为后一个输入）

from celery import chain

result = chain(add.s(2, 2), mul.s(4), div.s(2)).apply_async()
 等价于: div(mul(add(2,2), 4), 2) → div(mul(4,4),2) → 16/2 = 8

chord() — 先并行执行一组任务，再回调一个任务

from celery import chord

callback = finalize.s()
header = [add.s(i, i) for i in range(4)] [0+0, 1+1, 2+2, 3+3]
result = chord(header)(callback) callback 接收 [0,2,4,6] 作为参数

✅ 这些用于复杂任务编排，属于 Celery Canvas 功能。

✅ 四、签名（Signatures）— 任务的“可调用对象”

task.s(*args, **kwargs) — 创建任务签名

作用：将任务和参数打包成一个“可传递的对象”，用于组合（如 group/chain）
不会立即执行

示例：

sig = add.s(2, 2) 签名
result = sig.delay() 现在才异步执行

常用于工作流构建。

✅ 总结：所有调用方式一览表

方法	是否异步	是否走 Broker	是否支持高级选项	典型用途
`.delay()`	✅ 是	✅ 是	❌ 否	快速调用
`.apply_async()`	✅ 是	✅ 是	✅ 是	生产环境标准调用
`.apply()`	❌ 否	❌ 否	⚠️ 部分	测试/调试
`send_task()`	✅ 是	✅ 是	✅ 是	动态/解耦调用
`group/chain/chord`	✅ 是	✅ 是	✅ 是	复杂任务编排
`.s()`（签名）	❌（需配合 delay/apply_async）	取决于后续调用	✅	构建工作流

🔒 重要提醒

所有 异步调用（.delay, .apply_async, send_task）都依赖 Broker（如 Redis） 和 Worker 进程。
如果没启动 Worker，任务会堆积在队列中，永远不会执行。
不要在 Web 请求中使用 .get() 阻塞等待结果（除非你明确知道后果）。

如何调整同时执行的任务数

这是一个非常好的问题。在生产环境中，根据负载情况动态调整 Worker 的并发数（即同时执行的任务数）是运维和资源管理的关键部分。

Celery 提供了两种主要的方式来实现这一点：

手动远程控制 (Manual Remote Control)： 你可以向正在运行的 Worker 发送命令，要求它增加或减少工作进程数。
自动伸缩 (Autoscaling)： 你可以设置一个最小和最大进程数，Celery Worker 会根据队列中的任务压力自动调整。

下面我们详细讲解这两种方法。

方法一：使用 celery control 手动调整（即时生效）

这是最直接的“我想动态调整”的答案。你可以使用 Celery 的远程控制命令 pool_grow (增加) 和 pool_shrink (减少) 来实时调整。

这要求你的 Worker 进程正在运行。

适用场景：

你预知到一波大流量即将到来（例如，市场活动开始），需要立即增加处理能力。
你发现服务器负载过高，需要立即减少并发数来“降温”。

前提条件：

Worker 必须使用支持动态伸缩的执行池 (Pool)。默认的 prefork（多进程）池是支持的。gevent 和 eventlet 也支持。
（如果你在 Windows 上运行，默认池可能不支持，你需要显式使用 -P gevent 或 -P eventlet）。

1. 增加并发数 (pool_grow)

这个命令告诉 Worker 增加 N 个工作进程。

# 语法: celery -A <app_name> control pool_grow <N>
# 假设你的应用在 tasks.py 中
# 增加 3 个工作进程
celery -A tasks control pool_grow 3

Worker 会立即响应（在日志中可以看到），并启动新的子进程来接收任务。

2. 减少并发数 (pool_shrink)

这个命令告诉 Worker 减少 N 个工作进程。Celery 会优雅地关闭这些进程，意味着它们会先完成手中正在执行的任务，然后再退出。

# 语法: celery -A <app_name> control pool_shrink <N>
# 减少 2 个工作进程
celery -A tasks control pool_shrink 2

3. 针对特定的 Worker

在生产环境中，你可能运行了多个 Worker。你可以通过 -d (destination) 参数指定要控制的 Worker：

# 1. 首先，查看所有正在运行的 Worker
celery -A tasks status

# 2. 假设你看到一个名为 worker1@my-server 的 Worker
# 只给它增加并发
celery -A tasks control pool_grow 2 -d worker1@my-server

方法二：使用 --autoscale 自动伸缩（推荐）

这是一种更“自动化”的动态调整。你不需要手动干预，Celery Worker 会自己监控任务队列的压力，并在你设定的范围内自动增加或减少工作进程。

适用场景：

任务负载波动很大且难以预测（例如，白天任务多，晚上任务少）。
你希望“设置好就不用管了”，让系统自动优化资源。

1. 启动 Worker 时开启 Autoscaling

你需要在启动 Worker 时使用 --autoscale 选项，并提供最大并发数和最小并发数。

# 语法: celery -A <app_name> worker --autoscale=<max_concurrency>,<min_concurrency>
#
# 启动一个 Worker，它最少保留 2 个工作进程，
# 但在负载高时，最多可以扩展到 10 个进程
celery -A tasks worker --autoscale=10,2 --loglevel=info

工作原理： Worker 启动时会以 min_concurrency (2个) 进程开始。当它发现队列中等待的任务增多时，它会逐渐增加进程数（pool_grow），直到达到 max_concurrency (10个)。
当队列变空，任务处理完毕后，它会逐渐减少进程数（pool_shrink），直到回到 min_concurrency (2个)，以节省系统资源。

2. 动态调整 Autoscaler 的边界

最强大的功能是：你可以将方法一和方法二结合起来。

你可以在运行时动态调整那个开启了 --autoscale 的 Worker 的最大/最小边界！

这是通过 autoscale 控制命令完成的：

# 假设 Worker 以 --autoscale=10,2 启动
# 现在是高峰期，我们希望它最多能扩展到 20 个进程，最少保持 5 个
celery -A tasks control autoscale 20,5

Worker 收到命令后，会立即更新它的自动伸缩策略。

方法三：静态调整（需要重启）

这不算是“动态”调整，但作为对比也提一下。这就是你在启动时使用 -c (concurrency) 参数来固定并发数。

# 启动一个固定 8 个工作进程的 Worker
celery -A tasks worker -c 8

如果你用这种方式启动，你仍然可以使用 pool_grow 和 pool_shrink 来临时调整它。但是，一旦这个 Worker 重启，它又会回到固定的 -c 8。

总结与建议

方法	命令	效果	最佳场景
手动调整	`celery control pool_grow <N>`	立即增加 N 个进程	应对已知的突发流量
	`celery control pool_shrink <N>`	立即（优雅地）减少 N 个进程	立即降低服务器负载
自动伸缩	`celery worker --autoscale=<max>,<min>`	Worker 根据负载自动在 max 和 min 之间调整	生产环境中最推荐的常用方式
动态调参	`celery control autoscale <new_max>,<new_min>`	实时修改 `--autoscale` 的边界	运维时根据大趋势调整策略
静态设置	`celery worker -c <N>`	启动时固定 N 个进程	开发或负载恒定的简单场景

给你的建议：

在生产环境中，始终使用 --autoscale 启动你的 Worker。

celery -A tasks worker --autoscale=16,4

然后，当你需要根据全局策略（例如，知道接下来一周是旺季）调整时，使用 celery control autoscale 来调整边界。

celery -A tasks control autoscale 32,8

这样你就能同时获得自动化的便利性和手动调控的灵活性。

Building asynchronous APIs for handling long-term tasks and dynamic resources

Mon, 20 Oct 2025 15:59:14 +0800

教程：构建处理长时间任务和动态资源的异步 API

这是一个关于如何构建一个健壮的后端系统的教程，该系统用于处理你所描述的场景：一个API接口，用于调用一个可能执行很久、并且需要动态管理并发资源（例如，受限于CPU/内存/GPU）的函数。

我们将使用异步任务队列架构，这是解决此类问题的行业标准。

核心问题

为什么不能直接在API接口中调用这个耗时函数？

HTTP 超时：客户端（浏览器、APP）等待HTTP响应的时间是有限的（通常是30-60秒）。如果你的函数执行5分钟，客户端将收到一个“超时”错误，即使用户的任务最终成功了。
服务器资源耗尽：Web服务器（如 Uvicorn, Gunicorn）的工作进程是有限的。如果5个用户同时请求这个耗时5分钟的接口，你的5个Web进程将被全部占用，导致服务器在接下来的5分钟内无法响应任何其他请求（例如登录、获取数据等），服务器会“假死”。

解决方案：异步任务队列

我们将系统拆分为三个组件：

API 服务器 (Web Server)：一个轻量级的接口。它只负责接收请求，验证参数，然后把“任务”丢进一个队列，最后立即返回一个任务ID给客户端。
任务队列 (Message Broker)：一个中间件（我们使用 Redis）。它像一个“待办事项”列表，负责存储API服务器发来的任务。
工作单元 (Worker)：一个（或多个）独立于API服务器运行的进程。它唯一的工作就是盯着任务队列，一旦有新任务，就取出来执行。

这种架构如何解决你的问题：

长时间执行：API在1毫秒内就返回了响应（{"task_id": "xxx"}），客户端不需等待。客户端可以稍后使用task_id来轮询另一个接口查询结果。
动态资源：你可以根据服务器的资源（CPU、内存）来决定启动多少个Worker进程，或者配置每个Worker同时执行多少个任务。这就是你的“动态并发控制”。

技术栈

API 服务器: FastAPI (高性能Python Web框架)
任务队列系统: Celery (Python中最流行的任务队列)
消息中间件 / 结果存储: Redis (速度极快，Celery的完美搭档)

第 1 步：环境准备

安装 Python 库:
```
pip install "fastapi[all]" celery redis
```
- fastapi[all]：安装FastAPI及Uvicorn服务器。
- celery：Celery 框架。
- redis：Celery连接Redis所需的Python客户端。
启动 Redis: 最简单的方式是使用 Docker。如果你没有Docker，请从官网下载并运行。
```
# 这将在后台启动一个Redis服务器，端口为 6379
docker run -d -p 6379:6379 redis
```

第 2 步：项目结构

创建两个文件：


/your\_project
├── tasks.py \# 定义 Celery 应用和“耗时函数”
└── main.py \# 定义 FastAPI 接口

第 3 步：编写 Worker 和任务 (`tasks.py`)

这是你“耗时函数”的真正定义之处。

# tasks.py

import time
from celery import Celery

# 1. 初始化 Celery
# 'tasks' 是当前模块的名称
# broker 是任务队列，使用 Redis 的 0 号数据库
# backend 是结果存储，使用 Redis 的 1 号数据库
celery_app = Celery(
 'tasks',
 broker='redis://localhost:6379/0',
 backend='redis://localhost:6379/1'
)

# 2. 定义你那个“耗时很长、需要动态资源”的函数
# @celery_app.task 装饰器将其注册为 Celery 任务

@celery_app.task
def run_long_analysis(dataset_id: str, complexity: int) -> dict:
 """
 这是一个模拟的耗时任务。
 在真实世界中，这里可能是：
 - 运行一个复杂的AI模型
 - 生成一份巨大的报表
 - 转码一个视频文件
 - 调用第三方的慢速 API
 """

 print(f"[任务开始] 正在分析数据集 {dataset_id}，复杂度 {complexity}...")

 try:
 # 模拟长时间工作
 # 复杂度越高，工作时间越长
 duration = complexity * 5
 time.sleep(duration)

 # 模拟资源消耗... (这部分由 Celery 的并发设置来控制)

 # 任务执行完毕，返回结果
 result = {
 "status": "success",
 "dataset_id": dataset_id,
 "analysis_time_sec": duration,
 "result_url": f"[http://example.com/results/](http://example.com/results/){dataset_id}.zip"
 }
 print(f"[任务成功] {dataset_id} 分析完毕。")
 return result

 except Exception as e:
 # 异常处理
 print(f"[任务失败] {dataset_id} 分析失败: {e}")
 return {"status": "failed", "error": str(e)}

第 4 步：编写 API 接口 (`main.py`)

这是客户端唯一能“看到”的部分。

# main.py

from fastapi import FastAPI, status
from pydantic import BaseModel
from celery.result import AsyncResult

# 1. 导入在 tasks.py 中定义的任务和app
from tasks import run_long_analysis, celery_app

# 初始化 FastAPI
app = FastAPI(title="异步任务API", description="使用 FastAPI 和 Celery")

# 2. 定义 API 的请求体（Pydantic模型）
class TaskRequest(BaseModel):
 dataset_id: str
 complexity: int # 复杂度，1-10

# 3. 定义 API 的响应体
class TaskResponse(BaseModel):
 message: str
 task_id: str


# === 接口 1: 启动任务 ===
# 状态码 202 (Accepted) 表示“已接受，正在处理”
@app.post("/api/v1/start-analysis", status_code=status.HTTP_202_ACCEPTED, response_model=TaskResponse)
def start_analysis(request: TaskRequest):
 """
 接收分析请求，将其放入任务队列，并立即返回任务ID。
 """

 # 关键: .delay()
 # 这不会在当前进程中执行函数，而是将任务消息发送到 Redis 队列
 task = run_long_analysis.delay(request.dataset_id, request.complexity)

 # 立即返回响应
 return {
 "message": "任务已接收，正在后台处理",
 "task_id": task.id
 }


# === 接口 2: 查询任务状态/结果 ===
@app.get("/api/v1/task-status/{task_id}")
def get_task_status(task_id: str):
 """
 根据任务ID查询任务的状态和结果。
 """

 # 使用 Celery 的 AsyncResult 从 Backend (Redis) 中获取结果
 task_result = AsyncResult(task_id, app=celery_app)

 if task_result.ready():
 # 任务已完成
 if task_result.successful():
 # 任务成功
 return {
 "task_id": task_id,
 "status": task_result.status, # "SUCCESS"
 "result": task_result.result # run_long_analysis 返回的字典
 }
 else:
 # 任务失败
 return {
 "task_id": task_id,
 "status": task_result.status, # "FAILURE"
 "error": str(task_result.info) # 异常信息
 }
 else:
 # 任务仍在进行中
 return {
 "task_id": task_id,
 "status": task_result.status # "PENDING" 或 "STARTED"
 }

第 5 步：运行系统（关键）

你需要启动 3 个独立的进程（打开 3 个终端窗口）。

终端 1: 运行 Redis (如果你还没启动)

docker run -d -p 6379:6379 redis

终端 2: 运行 Celery Worker (耗时函数的执行者) 这是管理你“动态资源”的地方。

# -A tasks: 指定 Celery 应用在 tasks.py 文件中的 celery_app
# worker: 启动工作单元
# --loglevel=info: 打印日志
# --concurrency=4: !!! 核心控制 !!! 
# 这表示这个 Worker 进程“同时”最多执行 4 个任务。
# 如果你的机器有 16 核 CPU，并且资源充足，可以设为 16。
# 如果你的函数非常吃内存，可能只能设为 2。
# 这就是你的“动态资源管理”。
celery -A tasks worker --loglevel=info --concurrency=4

如何扩展? 如果一台机器的 concurrency=4 不够用，你可以在另一台机器上也运行这个命令，它们会连接同一个Redis，自动分担任务！

终端 3: 运行 API 服务器

# uvicorn 会运行 main.py 中的 app
uvicorn main:app --reload

--reload 模式会在你修改代码后自动重启，方便开发。

第 6 步：测试

现在你的整套系统都跑起来了。

1. 启动一个任务 (POST) 我们请求一个复杂度为 3 的任务（即 3 * 5 = 15 秒）。

curl -X POST "[http://127.0.0.1:8000/api/v1/start-analysis](http://127.0.0.1:8000/api/v1/start-analysis)" \
 -H "Content-Type: application/json" \
 -d '{"dataset_id": "data_xyz", "complexity": 3}'

你将立即收到响应：

{
 "message": "任务已接收，正在后台处理",
 "task_id": "a9b1c8d2-....."
}

同时，在终端 2 (Worker) 的日志中，你会看到它打印了 [任务开始] ...。

2. 查询任务状态 (GET) - 5秒后 使用上一步中获取的 task_id。

curl "[http://127.0.0.1:8000/api/v1/task-status/a9b1c8d2-](http://127.0.0.1:8000/api/v1/task-status/a9b1c8d2-)....."

因为任务还在运行（总共要15秒），你会收到：

{
 "task_id": "a9b1c8d2-.....",
 "status": "PENDING"
}

3. 查询任务状态 (GET) - 20秒后 再次运行上一个命令：

curl "[http://127.0.0.1:8000/api/v1/task-status/a9b1c8d2-](http://127.0.0.1:8000/api/v1/task-status/a9b1c8d2-)....."

现在任务完成了，你会收到：

{
 "task_id": "a9b1c8d2-.....",
 "status": "SUCCESS",
 "result": {
 "status": "success",
 "dataset_id": "data_xyz",
 "analysis_time_sec": 15,
 "result_url": "[http://example.com/results/data_xyz.zip](http://example.com/results/data_xyz.zip)"
 }
}

总结

你已经成功构建了一个可扩展、健壮的异步任务系统。

API 接口 (main.py)：轻量且响应迅速。
耗时函数 (tasks.py)：在后台的 Worker 中独立运行。
资源管理：通过 celery worker --concurrency=N 来精确控制并发数，N就是你根据“动态资源”决定的数量。

jwt-with-fastapi

Fri, 12 Sep 2025 16:48:40 +0800

JWT (JSON Web Token) 深入解析与实战教程

JWT 是什么？
- JWT 的结构
  - Header (头部)
  - Payload (负载)
  - Signature (签名)
- JWT 的工作流程
基础用法：JWT 的生成与验证
- Node.js 示例 (jsonwebtoken)
- Python 示例 (PyJWT)
FastAPI 实战：构建 JWT 认证系统
- 第一步：单用户的 FastAPI 认证
- 第二步：实现多用户注册与数据库认证
安全性最佳实践

1. JWT 是什么？

JSON Web Token (JWT)，通常读作 /dʒɒt/，是一种开放标准（RFC 7519），它定义了一种紧凑且自包含的方式，用于在各方之间安全地传输信息。这些信息可以被验证和信任，因为它是经过数字签名的。

JWT 通常被用于身份验证和授权。在一个典型的场景中，当用户使用其凭据成功登录后，认证服务器将返回一个 JWT。客户端（例如，单页应用或移动应用）会将此令牌存储起来，并在向服务器发送的后续请求中附上此令牌。服务器随后会验证此令牌的有效性，并根据其中包含的信息来授权用户的请求。

由于 JWT 的自包含性，它使得认证过程变得无状态（Stateless）。这意味着服务器端不需要在会v会话中存储用户信息，极大地简化了应用程序的扩展。

JWT 的结构

一个 JWT 由三部分组成，以点（.）分隔，它们分别是：

Header（头部）
Payload（负载）
Signature（签名）

因此，一个 JWT 通常看起来像这样：xxxxx.yyyyy.zzzzz

头部通常由两部分组成：令牌的类型（typ），即 JWT，以及所使用的签名算法（alg），例如 HMAC SHA256 或 RSA。

一个典型的头部看起来像这样：

{
 "alg": "HS256",
 "typ": "JWT"
}

这个 JSON 会被 Base64Url 编码，形成 JWT 的第一部分。

Payload (负载)

负载部分包含声明（Claims）。声明是关于实体（通常是用户）和其他数据的陈述。声明有三种类型：

Registered claims（注册声明）: 一些预定义的声明，例如 iss (签发者), exp (过期时间), sub (主题)。
Public claims（公共声明）: 由使用 JWT 的人随意定义，但为了避免冲突，应该在 IANA JSON Web Token Registry 中定义它们。
Private claims（私有声明）: 为在同意使用它们的各方之间共享信息而创建的自定义声明。

一个示例负载可能如下所示：

{
 "sub": "1234567890",
 "name": "John Doe",
 "admin": true,
 "iat": 1516239022
}

该负载也会被 Base64Url 编码，以形成 JWT 的第二部分。

重要提示： 默认情况下，JWT 的负载是经过 Base64Url 编码的，而不是加密的。任何人都可以解码并读取其内容。因此，切勿在负载中存储敏感信息。

Signature (签名)

要创建签名部分，您必须获取编码后的头部、编码后的负载、一个密钥（secret），以及在头部中指定的算法，并对其进行签名。

HMACSHA256(
 base64UrlEncode(header) + "." +
 base64UrlEncode(payload),
 secret)

签名用于验证消息在传输过程中没有被篡改，并验证发送者的身份。

JWT 的工作流程

用户认证: 用户使用凭据（如用户名密码）登录。
生成并返回 JWT: 服务器验证凭据，如果成功，则创建一个 JWT 并将其返回给客户端。
客户端存储 JWT: 客户端将 JWT 存储在本地（如 localStorage 或 HTTP-Only Cookie）。
在请求中发送 JWT: 客户端访问受保护的资源时，会在请求的 Authorization 头部中以 Bearer 模式包含 JWT。
```
Authorization: Bearer <token>
```
服务器验证 JWT: 服务器验证令牌的签名。如果有效，则授权该请求。

2. 基础用法：JWT 的生成与验证

Node.js 示例 (jsonwebtoken)

安装:

npm install jsonwebtoken

代码:

const jwt = require('jsonwebtoken');

// 密钥应存储在环境变量中
const JWT_SECRET = 'your_super_secret_key';

// 1. 生成 Token
function generateToken(user) {
 const payload = { id: user.id, username: user.username };
 const options = { expiresIn: '1h' }; // 1小时后过期
 return jwt.sign(payload, JWT_SECRET, options);
}

// 2. 验证 Token (常用于 Express 中间件)
function verifyToken(req, res, next) {
 const authHeader = req.headers['authorization'];
 const token = authHeader && authHeader.split(' ')[1];

 if (token == null) return res.sendStatus(401);

 jwt.verify(token, JWT_SECRET, (err, user) => {
 if (err) return res.sendStatus(403); // Token 无效或已过期
 req.user = user;
 next();
 });
}

// 使用示例
const myUser = { id: '123', username: 'testuser' };
const token = generateToken(myUser);
console.log('生成的 JWT:', token);

Python 示例 (PyJWT)

安装:

pip install PyJWT

代码:

import jwt
import datetime

JWT_SECRET = 'your_super_secret_key'
JWT_ALGORITHM = 'HS256'

# 1. 生成 Token
def generate_token(user_id):
 payload = {
 'user_id': user_id,
 'exp': datetime.datetime.utcnow() + datetime.timedelta(hours=1), # 过期时间
 'iat': datetime.datetime.utcnow() # 签发时间
 }
 token = jwt.encode(payload, JWT_SECRET, algorithm=JWT_ALGORITHM)
 return token

# 2. 验证 Token
def verify_token(token):
 try:
 payload = jwt.decode(token, JWT_SECRET, algorithms=[JWT_ALGORITHM])
 return payload
 except jwt.ExpiredSignatureError:
 return "令牌已过期"
 except jwt.InvalidTokenError:
 return "无效的令牌"

# 使用示例
my_user_id = '456'
token = generate_token(my_user_id)
print(f"生成的 JWT: {token}")

decoded_payload = verify_token(token)
print(f"解码后的负载: {decoded_payload}")

3. FastAPI 实战：构建 JWT 认证系统

我们将使用 FastAPI 和 python-jose 库来构建一个功能完整的认证系统。python-jose 是一个功能更全的库，推荐在 FastAPI 项目中使用。

安装依赖:

pip install "fastapi[all]" python-jose "passlib[bcrypt]" sqlalchemy

第一步：单用户的 FastAPI 认证

这是一个快速入门示例，用户数据硬编码在代码中。

main_simple.py:

import os
from datetime import datetime, timedelta
from typing import Optional, Annotated

from fastapi import Depends, FastAPI, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
from jose import JWTError, jwt
from passlib.context import CryptContext
from pydantic import BaseModel

# --- 配置 ---
SECRET_KEY = os.getenv("SECRET_KEY", "your-super-secret-key")
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30

# --- Pydantic 模型 ---
class Token(BaseModel):
 access_token: str
 token_type: str

class TokenData(BaseModel):
 username: Optional[str] = None

class User(BaseModel):
 username: str
 disabled: Optional[bool] = None

class UserInDB(User):
 hashed_password: str

# --- 密码处理 ---
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

# --- 模拟数据库 ---
fake_users_db = {
 "johndoe": {
 "username": "johndoe",
 "hashed_password": pwd_context.hash("secretpassword"),
 "disabled": False,
 }
}

# --- 辅助函数 ---
def verify_password(plain_password, hashed_password):
 return pwd_context.verify(plain_password, hashed_password)

def get_user(username: str):
 if username in fake_users_db:
 user_dict = fake_users_db[username]
 return UserInDB(**user_dict)
 return None

def create_access_token(data: dict, expires_delta: Optional[timedelta] = None):
 to_encode = data.copy()
 expire = datetime.utcnow() + (expires_delta or timedelta(minutes=15))
 to_encode.update({"exp": expire})
 encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
 return encoded_jwt

# --- FastAPI 应用 ---
app = FastAPI()
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

async def get_current_active_user(token: Annotated[str, Depends(oauth2_scheme)]):
 credentials_exception = HTTPException(
 status_code=status.HTTP_401_UNAUTHORIZED,
 detail="Could not validate credentials",
 headers={"WWW-Authenticate": "Bearer"},
 )
 try:
 payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
 username: str = payload.get("sub")
 if username is None:
 raise credentials_exception
 token_data = TokenData(username=username)
 except JWTError:
 raise credentials_exception

 user = get_user(username=token_data.username)
 if user is None or user.disabled:
 raise credentials_exception
 return user

# --- 路由 ---
@app.post("/token", response_model=Token)
async def login_for_access_token(form_data: Annotated[OAuth2PasswordRequestForm, Depends()]):
 user = get_user(form_data.username)
 if not user or not verify_password(form_data.password, user.hashed_password):
 raise HTTPException(
 status_code=status.HTTP_401_UNAUTHORIZED,
 detail="Incorrect username or password",
 )
 access_token = create_access_token(
 data={"sub": user.username}, expires_delta=timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
 )
 return {"access_token": access_token, "token_type": "bearer"}

@app.get("/users/me/", response_model=User)
async def read_users_me(current_user: Annotated[User, Depends(get_current_active_user)]):
 return current_user

第二步：实现多用户注册与数据库认证

这是一个真实世界的方案，我们将引入数据库（SQLite + SQLAlchemy），并分离代码结构以提高可维护性。

项目结构:

.
├── main.py
├── crud.py
├── database.py
├── models.py
└── schemas.py

database.py:

from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

SQLALCHEMY_DATABASE_URL = "sqlite:///./sql_app.db"

engine = create_engine(
 SQLALCHEMY_DATABASE_URL, connect_args={"check_same_thread": False}
)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

models.py:

from sqlalchemy import Boolean, Column, Integer, String
from .database import Base

class User(Base):
 __tablename__ = "users"
 id = Column(Integer, primary_key=True, index=True)
 username = Column(String, unique=True, index=True)
 full_name = Column(String, index=True, nullable=True)
 email = Column(String, unique=True, index=True, nullable=True)
 hashed_password = Column(String)
 disabled = Column(Boolean, default=False)

schemas.py:

from typing import Optional
from pydantic import BaseModel

class UserBase(BaseModel):
 username: str
 email: Optional[str] = None
 full_name: Optional[str] = None

class UserCreate(UserBase):
 password: str

class User(UserBase):
 id: int
 disabled: bool
 class Config:
 orm_mode = True

class Token(BaseModel):
 access_token: str
 token_type: str

class TokenData(BaseModel):
 username: Optional[str] = None

crud.py:

from sqlalchemy.orm import Session
from . import models, schemas
from passlib.context import CryptContext

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

def get_user_by_username(db: Session, username: str):
 return db.query(models.User).filter(models.User.username == username).first()

def create_user(db: Session, user: schemas.UserCreate):
 hashed_password = pwd_context.hash(user.password)
 db_user = models.User(
 username=user.username,
 email=user.email,
 full_name=user.full_name,
 hashed_password=hashed_password
 )
 db.add(db_user)
 db.commit()
 db.refresh(db_user)
 return db_user

def verify_password(plain_password, hashed_password):
 return pwd_context.verify(plain_password, hashed_password)

main.py (最终版):

from datetime import timedelta
from typing import Annotated

from fastapi import Depends, FastAPI, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
from sqlalchemy.orm import Session
from jose import JWTError, jwt

from . import crud, models, schemas
from .database import SessionLocal, engine

# 创建数据库表
models.Base.metadata.create_all(bind=engine)

app = FastAPI()

# --- 配置和依赖 ---
SECRET_KEY = "your-super-secret-key"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

def get_db():
 db = SessionLocal()
 try:
 yield db
 finally:
 db.close()

# --- 安全和认证 ---
def create_access_token(data: dict, expires_delta: timedelta):
 to_encode = data.copy()
 expire = datetime.utcnow() + expires_delta
 to_encode.update({"exp": expire})
 return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)

async def get_current_active_user(
 token: Annotated[str, Depends(oauth2_scheme)],
 db: Session = Depends(get_db)
):
 credentials_exception = HTTPException(
 status_code=status.HTTP_401_UNAUTHORIZED,
 detail="Could not validate credentials",
 headers={"WWW-Authenticate": "Bearer"},
 )
 try:
 payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
 username: str = payload.get("sub")
 if username is None:
 raise credentials_exception
 except JWTError:
 raise credentials_exception

 user = crud.get_user_by_username(db, username=username)
 if user is None or user.disabled:
 raise credentials_exception
 return user

# --- API 端点 ---
@app.post("/users/", response_model=schemas.User)
def register_user(user: schemas.UserCreate, db: Session = Depends(get_db)):
 db_user = crud.get_user_by_username(db, username=user.username)
 if db_user:
 raise HTTPException(status_code=400, detail="Username already registered")
 return crud.create_user(db=db, user=user)

@app.post("/token", response_model=schemas.Token)
async def login_for_access_token(
 form_data: Annotated[OAuth2PasswordRequestForm, Depends()],
 db: Session = Depends(get_db)
):
 user = crud.get_user_by_username(db, username=form_data.username)
 if not user or not crud.verify_password(form_data.password, user.hashed_password):
 raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Incorrect username or password")

 access_token = create_access_token(
 data={"sub": user.username}, expires_delta=timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
 )
 return {"access_token": access_token, "token_type": "bearer"}

@app.get("/users/me/", response_model=schemas.User)
async def read_users_me(
 current_user: Annotated[schemas.User, Depends(get_current_active_user)]
):
 return current_user

如何运行和测试最终版:

将上述文件保存在同一目录下。
运行 uvicorn main:app --reload。
访问 http://127.0.0.1:8000/docs。
使用 POST /users/ 端点注册一个新用户。
使用 POST /token 端点，用新用户的凭据登录以获取 token。
点击 “Authorize”，输入 Bearer <your_token>。
访问 GET /users/me/ 端点，你将看到当前登录用户的信息。

4. 安全性最佳实践

使用强大的密钥: 密钥（Secret Key）应该足够长且难以猜测，并始终存储在环境变量或安全的密钥管理服务中。
使用 HTTPS: 始终通过 HTTPS 传输 JWT，以防止中间人攻击。
设置令牌过期时间: 为 JWT 设置一个合理的过期时间（exp 声明），以减少令牌泄露带来的风险。
不要在负载中存放敏感信息: 负载是可解码的，避免存储密码等敏感数据。
考虑令牌撤销: JWT 本质上是无状态的。如果需要立即撤销某个用户的访问权限，你需要实现一个令牌撤销机制（例如，维护一个无效令牌的黑名单）。
选择合适的签名算法: HS256 是对称算法。RS256 (非对称算法) 在某些场景下更安全，因为它允许公钥验证，而私钥可以保持安全。

fastapi-docs_swagger_UI-openAPI

Fri, 12 Sep 2025 14:26:46 +0800

FastAPI 框架在设计之初就深度集成了 OpenAPI 规范。这意味着：

自动生成文档：您无需手动编写任何 OpenAPI (Swagger) 配置文件。FastAPI 会自动分析您的代码、路径操作、参数和模型，并生成符合规范的 JSON 文件。
内置交互式界面：FastAPI 默认就包含了两个交互式的 API 文档界面：Swagger UI 和 ReDoc。您无需进行任何额外配置，开箱即用。
代码即文档：您的代码就是文档的唯一真实来源。当您修改了代码（例如，添加一个新参数），文档会自动更新，保证了同步性。

步骤 1：环境准备

首先，我们需要安装 FastAPI 和一个 ASGI 服务器，这里我们使用 uvicorn。

pip install fastapi "uvicorn[standard]"

"uvicorn[standard]" 会安装 uvicorn 以及一些推荐的依赖，以获得更好的性能。

步骤 2：创建一个简单的 FastAPI 应用

让我们从一个最基础的 “Hello World” 应用开始。创建一个名为 main.py 的文件，并写入以下代码：

# main.py
from fastapi import FastAPI

# 1. 创建一个 FastAPI 实例
app = FastAPI()

# 2. 定义一个路径操作 (Path Operation)
@app.get("/")
def read_root():
 return {"Hello": "World"}

代码解释：

我们导入 FastAPI 类并创建了一个实例 app。
我们使用 @app.get("/") 这个装饰器 (decorator) 来告诉 FastAPI，下面的 read_root 函数负责处理对路径 / 的 GET 请求。
函数返回一个字典，FastAPI 会自动将其转换为 JSON 格式的响应。

步骤 3：运行应用并查看文档

现在，在您的终端中，使用 uvicorn 来运行这个应用：

uvicorn main:app --reload

main: 指的是 main.py 文件。
app: 指的是在 main.py 中创建的 app = FastAPI() 对象。
--reload: 这个参数会让服务器在您修改代码后自动重启，非常适合开发阶段。

服务器启动后，您会看到类似下面的输出：

INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [12345]
INFO: Started server process [12347]
INFO: Waiting for application startup.
INFO: Application startup complete.

现在，打开您的浏览器，见证奇迹的时刻到了！

访问 Swagger UI:
- 在浏览器中输入：http://127.0.0.1:8000/docs
您将看到一个漂亮的、交互式的 API 文档界面，这正是由 Swagger UI 生成的。
访问 ReDoc:
- 在浏览器中输入：http://127.0.0.1:8000/redoc
您会看到另一个由 ReDoc 生成的、风格不同的文档界面。

步骤 4：通过示例深入理解

光有 “Hello World” 还不够，让我们添加更复杂的路径操作来探索 FastAPI 是如何生成更丰富的文档的。

修改您的 main.py 文件：

# main.py
from fastapi import FastAPI
from pydantic import BaseModel
from typing import Optional

# --- 模型定义 ---
# 使用 Pydantic 定义请求体的数据结构
class Item(BaseModel):
 name: str
 description: Optional[str] = None
 price: float
 tax: Optional[float] = None

# --- FastAPI 应用实例 ---
app = FastAPI(
 title="我的超酷 API",
 description="这是一个使用 FastAPI 构建的示例 API，它展示了自动生成的交互式文档。",
 version="1.0.0",
)

# --- 路径操作 ---

@app.get("/")
def read_root():
 """
 应用的根路径，返回一个欢迎信息。
 """
 return {"Hello": "World"}

@app.get("/items/{item_id}", tags=["Items"])
def read_item(item_id: int, q: Optional[str] = None):
 """
 根据 ID 读取一个物品。

 - **item_id**: 必需的路径参数，必须是整数。
 - **q**: 可选的查询参数。
 """
 return {"item_id": item_id, "q": q}

@app.post("/items/", response_model=Item, tags=["Items"])
def create_item(item: Item):
 """
 创建一个新的物品。

 请求体需要包含物品的详细信息：
 - **name**: 物品名称 (必需)
 - **price**: 物品价格 (必需)
 - **description**: 物品描述 (可选)
 - **tax**: 税费 (可选)
 """
 return item

代码详解与文档对应关系：

自定义文档信息：
- app = FastAPI(title="...", description="...", version="...")
- 这些参数会直接显示在 Swagger UI 的顶部，用来定义您的 API 的元数据。
路径参数 (/items/{item_id})：
- item_id: int：FastAPI 知道 item_id 是路径的一部分，并且通过类型注解 int 知道它必须是一个整数。
- 在 Swagger UI 中：这会被识别为一个必需的、类型为 integer 的 path 参数。
查询参数 (?q=...)：
- q: Optional[str] = None：FastAPI 看到这个函数参数不属于路径，所以它将其视为查询参数。Optional[str] 和默认值 None 告诉 FastAPI 这个参数是可选的。
- 在 Swagger UI 中：这会被识别为一个可选的、类型为 string 的 query 参数。
请求体 (Request Body)：
- item: Item：我们定义了一个 Item 类，它继承自 Pydantic 的 BaseModel。FastAPI 会将这个参数识别为请求体。
- 在 Swagger UI 中：它会自动生成一个请求体的示例 (Example Value) 和模型结构 (Schema)，清楚地展示了需要发送的 JSON 格式。
文档字符串 (Docstrings)：
- 函数下方的多行字符串（"""..."""）会被 FastAPI 提取出来，作为对应路径操作的描述，显示在 Swagger UI 中。这是一种非常 Pythonic 的文档编写方式。
标签 (tags=["Items"])：
- 通过 tags 参数，我们可以将相关的路径操作分组。
- 在 Swagger UI 中：您会看到一个名为 “Items” 的可折叠部分，里面包含了所有标记为此标签的端点，让文档结构更清晰。

步骤 5：再次运行并交互

保存您的 main.py 文件。如果 uvicorn 正在以 --reload 模式运行，它会自动重启。

现在，刷新您的 Swagger UI 页面 (http://127.0.0.1:8000/docs)。

您会看到一个内容更丰富、结构更清晰的文档：

让我们来交互一下：

展开 GET /items/{item_id}：
- 点击 “Try it out” 按钮。
- 在 item_id 字段中输入一个数字，例如 123。
- 在可选的 q 字段中输入一些文本，例如 some-query。
- 点击 “Execute” 按钮。
下方会立刻显示出服务器的响应、请求的 curl 命令以及请求的 URL。
展开 POST /items/：
- 点击 “Try it out”。
- 请求体 (Request body) 区域会变成一个可编辑的 JSON 编辑器，并且已经填好了示例。
- 您可以修改 JSON 中的值。
- 点击 “Execute”。
您将看到 FastAPI 如何验证您的输入，并返回一个符合 response_model=Item 结构的数据。

总结

通过这个示例，您可以看到 FastAPI 如何将编写代码和生成 API 文档的过程无缝地结合在一起。您只需要专注于使用 Python 的类型注解和 Pydantic 模型来编写健壮的、类型安全的代码，一份美观、实用且始终保持最新的交互式 API 文档便会自动为您生成。这是 FastAPI 框架最强大的特性之一，也是它深受开发者喜爱的重要原因。

ALL-fastapi

Fri, 12 Sep 2025 14:26:01 +0800

flutter_tutorial

Thu, 14 Aug 2025 03:58:16 +0800

从零开始的fultter之路

好的，非常乐意！从零开始学习一门新技术是令人兴奋的。我们将一步一步来，从你电脑上什么都没有，一直到运行起你的第一个 Flutter 应用。

这个过程分为几个关键阶段：

环境搭建：安装所有必要的工具。
创建项目：使用命令行创建一个新的 Flutter 应用。
运行应用：在模拟器或真实设备上把应用跑起来。
理解代码：弄懂项目中最重要的文件和代码是什么意思。
动手修改：亲手改动代码并立即看到变化。

第 1 步：环境搭建 (最重要的一步)

这是最关键也是最容易遇到问题的一步，请务必保持耐心。

1. 安装 Flutter SDK

前往 Flutter 官方网站：https://flutter.dev
点击 “Get Started” 按钮。
根据你的操作系统 (Windows, macOS, or Linux) 选择相应的安装指南。官方文档是最新、最权威的，请严格按照上面的步骤操作。
- 核心操作：下载 Flutter SDK 压缩包 -> 解压到你电脑上一个固定的位置 (例如，Windows 的 C:\src\flutter 或 Mac 的 ~/development/flutter) -> 将 Flutter 的 bin 目录添加到系统的环境变量 (PATH) 中。这一步至关重要，否则后续命令会无法识别。

2. 安装代码编辑器 (IDE)

我强烈推荐 Visual Studio Code (VS Code)，它轻量且功能强大。

下载并安装 VS Code。
打开 VS Code，点击左侧的扩展图标 (Extensions)。
搜索并安装两个最重要的扩展：
- Dart
- Flutter

3. 安装目标平台的工具

你需要告诉 Flutter 在哪里运行你的应用。

如果要开发 Android 应用:
- 安装 Android Studio。
- 安装完成后，打开 Android Studio，根据向导完成设置。它会自动安装最新的 Android SDK、Android SDK 命令行工具和 Android SDK Build-Tools。
- 在 Android Studio 中，打开 Virtual Device Manager (AVD Manager) 并创建一个安卓模拟器 (Emulator)。
如果要开发 iOS 应用 (仅限 macOS):
- 从 Mac App Store 安装 Xcode。
- 安装后，打开一次 Xcode 接受许可协议。
- Xcode 会自带 iOS 模拟器 (Simulator)。

4. 运行 flutter doctor

这是 Flutter 的“诊断医生”。打开你的终端 (Terminal) 或命令行 (Command Prompt)，运行以下命令：

flutter doctor

这个命令会检查你的环境是否准备就绪。第一次运行时，它可能会显示很多错误 (用 [X] 表示)。别担心，这是正常的。flutter doctor 会清晰地告诉你缺少什么，以及如何修复它。

你的目标是让 flutter doctor 的所有项目都打上绿色对勾 [✓]。 (至少 “Flutter”, “Android toolchain” 或 “Xcode”, 以及 “VS Code” 这几项要满足)。

第 2 步：创建你的第一个 Flutter 项目

当 flutter doctor 显示一切就绪后，就可以创建项目了。

打开你的终端/命令行。
使用 cd 命令进入一个你想要存放代码的目录，例如 Desktop 或 Documents。
运行以下命令来创建项目：
```
flutter create my_first_app
```
- my_first_app 是你的项目名称，请使用小写字母和下划线。
- Flutter 会自动为你生成一个包含示例代码的项目文件夹。
进入项目目录并用 VS Code 打开它：
```
cd my_first_app
code .
```
(命令 code . 会用 VS Code 打开当前文件夹)

第 3 步：运行你的第一个应用

选择设备：在 VS Code 的右下角，你会看到一个状态栏。点击 <no device> 区域，VS Code 会在顶部显示一个可选设备列表 (包括你已经启动的模拟器或连接的真机)。选择一个设备。
启动调试：
- 最简单的方式：按 F5 键。
- 或者，点击顶部菜单的 “Run” -> “Start Debugging”。

Flutter 会开始编译代码并安装应用到你选择的设备上。第一次启动会需要几分钟时间。成功后，你会在模拟器上看到 Flutter 的默认计数器应用。

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

第 4 步：理解项目结构和核心概念

现在我们来看看项目里有什么。在 VS Code 的左侧文件浏览器中，最重要的两个东西是：

lib/main.dart: 这是你的应用入口文件，几乎你所有的 Dart 代码都会写在 lib 文件夹里。默认的计数器应用代码就在这里。
pubspec.yaml: 这是项目配置文件。你可以用它来管理项目依赖 (比如添加网络请求、图片缓存等第三方库) 和资源 (比如图片、字体)。

Flutter 核心概念：

一切皆为 Widget (组件)：在 Flutter 中，按钮、文本、布局、甚至整个应用页面，都是 Widget。你通过像搭积木一样组合这些 Widget 来构建用户界面。
Widget 树：你的应用是由一个 Widget 嵌套另一个 Widget 构成的树状结构。例如，一个 Center Widget 里面可以包含一个 Text Widget。

第 5 步：动手修改 (体验 Hot Reload)

现在，我们将默认的计数器应用修改成我们之前那个简单的 “Hello, World” 应用。

打开 lib/main.dart 文件。
删除里面的所有代码。

将我们第一个回答中的 “Hello, World” 代码完整地粘贴进去。

import 'package:flutter/material.dart';

void main() {
 runApp(const MyApp());
}

class MyApp extends StatelessWidget {
 const MyApp({super.key});

 @override
 Widget build(BuildContext context) {
 return MaterialApp(
 title: 'Welcome to Flutter',
 home: Scaffold(
 appBar: AppBar(
 title: const Text('My First App'),
 ),
 body: const Center(
 child: Text('Hello, World!'),
 ),
 ),
 );
 }
}

保存文件 (Ctrl + S 或 Cmd + S)。

神奇的事情发生了！你几乎不需要等待，模拟器里的应用界面会瞬间从计数器更新为你刚刚编写的 “Hello, World” 页面。这就是 Hot Reload (热重载)，Flutter 的王牌特性，它极大地提升了开发效率。

下一步该做什么？

你已经迈出了最坚实的一步。接下来：

学习 Dart 语言：Flutter 是框架，Dart 是编程语言。花点时间学习 Dart 的基本语法（变量、函数、类等）。
探索常用 Widget：尝试使用更多的基础 Widget，例如 Container (容器), Row (水平布局), Column (垂直布局), ListView (列表), Image (图片) 等。
跟着官方文档学习：Flutter 官方的 Codelabs 提供了非常棒的引导式教程。
犯错和搜索：遇到问题时，学会复制错误信息到 Google 或 Stack Overflow 搜索，这是每个开发者必备的技能。

编程之路就是不断学习、实践和解决问题的过程。祝你在 Flutter 的世界里玩得开心！

Refine: 当 API 即界面，CRUD 不再是体力活

Thu, 05 Jun 2025 10:00:00 +0800

问题：后台管理界面，为什么总是重复劳动？

你有没有发现，每次写后台管理界面，都在做同样的事情：

项目列表页：表格 + 分页 + 搜索 + 排序 + 新建按钮 + 编辑按钮 + 删除按钮

项目详情页：表单 + 字段校验 + 提交按钮 + 错误提示

用户管理页：表格 + 分页 + 搜索 + 排序 + 新建按钮 + …

这些页面长得几乎一样，但你还是要：

写表格组件
写分页逻辑
写搜索过滤
写表单校验
写 API 调用
写错误处理
写乐观更新
写权限控制

一个 CRUD 页面，至少 200 行代码。10 个资源就是 2000 行。

而且这些代码有个特点：业务逻辑和 UI 混在一起。

// 典型的后台页面代码
const ProjectList = () => {
 const [projects, setProjects] = useState([]);
 const [loading, setLoading] = useState(false);
 const [page, setPage] = useState(1);
 const [search, setSearch] = useState("");

 useEffect(() => {
 setLoading(true);
 fetch(`/api/projects?page=${page}&search=${search}`)
 .then(res => res.json())
 .then(data => {
 setProjects(data.items);
 setLoading(false);
 })
 .catch(err => {
 toast.error("加载失败");
 setLoading(false);
 });
 }, [page, search]);

 // ... 还有 100 行
};

这段代码的问题：

数据获取逻辑（fetch、loading、error）和 UI 逻辑（表格、分页）混在一起
换一个资源（tasks、users），这段代码几乎要重写一遍
后端 API 改了，前端要改 N 个地方

这就是 Refine 要解决的问题。

Refine 是什么？

Refine 不是 UI 库，不是组件库，而是一个 元框架（meta-framework）。

它的核心思想：

你的后端 API 长什么样，前端 CRUD 就长什么样。

用一张图说明：

┌─────────────────────────────────────────────────────────────┐
│ 后端 API 结构 │
│ GET /api/projects → 列表页（表格 + 分页 + 搜索） │
│ GET /api/projects/:id → 详情页（表单展示） │
│ POST /api/projects → 新建页（表单 + 校验） │
│ PUT /api/projects/:id → 编辑页（表单 + 校验） │
│ DELETE /api/projects/:id → 删除功能 │
└─────────────────────────────────────────────────────────────┘
 ↓
 Refine 自动映射
 ↓
┌─────────────────────────────────────────────────────────────┐
│ 前端页面结构 │
│ /projects → ProjectList 组件 │
│ /projects/:id → ProjectShow 组件 │
│ /projects/create → ProjectCreate 组件 │
│ /projects/edit/:id → ProjectEdit 组件 │
└─────────────────────────────────────────────────────────────┘

你只需要告诉 Refine：

你的 API 在哪里（Data Provider）
你有哪些资源（Resource）
用什么 UI（shadcn/ui、Material UI、Ant Design…）

Refine 会帮你生成：

数据获取逻辑
路由配置
侧边栏菜单
权限控制
表单校验
错误处理

核心概念 1：Headless（无头）

这是 Refine 最关键的设计决策：业务逻辑和 UI 完全分离。

Refine 提供什么？

// Refine 提供的核心能力
import {
 useList, // 列表数据获取
 useOne, // 单条数据获取
 useCreate, // 新建
 useUpdate, // 更新
 useDelete, // 删除
 useForm, // 表单状态管理
 useNavigation,// 路由跳转
 useCan, // 权限判断
} from "@refinedev/core";

这些 hooks 不依赖任何 UI 库。它们只负责：

发 API 请求
管理请求状态（loading、error、data）
缓存数据
乐观更新

你用什么 UI？

完全自由。Refine 官方提供了集成：

@refinedev/mui — Material UI
@refinedev/antd — Ant Design
@refinedev/mantine — Mantine
@refinedev/chakra — Chakra UI

或者用你自己的组件：

// 用 shadcn/ui 的 Table
import { Table } from "@/components/ui/table";
import { useList } from "@refinedev/core";

const ProjectList = () => {
 const { data, isLoading } = useList({
 resource: "projects",
 });

 return (
 <Table>
 {data?.data.map(project => (
 <TableRow key={project.id}>
 <TableCell>{project.name}</TableCell>
 </TableRow>
 ))}
 </Table>
 );
};

对比 Ant Design Pro：

维度	Ant Design Pro	Refine
UI 库	强绑定 Ant Design	任意 UI 库
业务逻辑	和 UI 耦合	完全分离
自定义	要覆盖 Pro 组件	直接用自己的组件
学习成本	要学 Pro 组件体系	只学 Refine hooks

核心概念 2：Resource（资源）

Refine 把一切后台对象抽象成 Resource。

资源的定义

<Refine
 resources={[
 {
 name: "projects", // API 路径
 list: "/projects", // 列表页路由
 create: "/projects/create", // 新建页路由
 edit: "/projects/edit/:id", // 编辑页路由
 show: "/projects/:id", // 详情页路由
 meta: {
 label: "项目", // 侧边栏显示名称
 icon: <ProjectIcon />, // 侧边栏图标
 }
 },
 {
 name: "tasks",
 list: "/tasks",
 create: "/tasks/create",
 edit: "/tasks/edit/:id",
 },
 {
 name: "users",
 list: "/team", // 路由可以自定义
 },
 ]}
/>

这段配置做了什么？

1. 自动生成侧边栏菜单

┌──────────────┐
│ 📁 项目 │
│ ✅ 任务 │
│ 👥 团队 │
└──────────────┘

2. 自动生成路由表

/projects → 项目列表
/projects/create → 新建项目
/projects/edit/123 → 编辑项目 123
/projects/123 → 项目详情
/tasks → 任务列表
...

3. 自动关联 Data Provider

当你调用 useList({ resource: "projects" })，Refine 知道要去 /api/projects 取数据。

对比传统方式：

// 传统方式：每个页面单独写
<Route path="/projects" element={<ProjectList />} />
<Route path="/projects/create" element={<ProjectCreate />} />
<Route path="/projects/edit/:id" element={<ProjectEdit />} />
<Route path="/tasks" element={<TaskList />} />
<Route path="/tasks/create" element={<TaskCreate />} />
// ... 重复 N 次

用 Refine，配置一次，路由、菜单、数据源全部搞定。

核心概念 3：Data Provider（数据提供者）

这是 Refine 最有价值的设计。

Data Provider 的接口

const dataProvider = {
 // 获取列表（带分页、过滤、排序）
 getList: async ({ resource, pagination, filters, sorters }) => {
 const { current, pageSize } = pagination;
 const response = await fetch(
 `/api/${resource}?` +
 `_start=${(current - 1) * pageSize}&` +
 `_end=${current * pageSize}&` +
 filters.map(f => `${f.field}=${f.value}`).join('&')
 );
 const data = await response.json();
 const total = parseInt(response.headers.get('x-total-count'));

 return { data, total };
 },

 // 获取单条
 getOne: async ({ resource, id }) => {
 const response = await fetch(`/api/${resource}/${id}`);
 const data = await response.json();
 return { data };
 },

 // 新建
 create: async ({ resource, variables }) => {
 const response = await fetch(`/api/${resource}`, {
 method: 'POST',
 body: JSON.stringify(variables),
 });
 const data = await response.json();
 return { data };
 },

 // 更新
 update: async ({ resource, id, variables }) => {
 const response = await fetch(`/api/${resource}/${id}`, {
 method: 'PUT',
 body: JSON.stringify(variables),
 });
 const data = await response.json();
 return { data };
 },

 // 删除
 deleteOne: async ({ resource, id }) => {
 await fetch(`/api/${resource}/${id}`, { method: 'DELETE' });
 return { data: { id } };
 },
};

这个接口的意义

一次实现，所有页面复用。

// 项目列表页
const ProjectList = () => {
 const { data } = useList({ resource: "projects" });
 // 自动调用 dataProvider.getList({ resource: "projects" })
};

// 任务列表页
const TaskList = () => {
 const { data } = useList({ resource: "tasks" });
 // 自动调用 dataProvider.getList({ resource: "tasks" })
};

// 项目编辑页
const ProjectEdit = () => {
 const { data } = useOne({ resource: "projects", id: 123 });
 // 自动调用 dataProvider.getOne({ resource: "projects", id: 123 })
};

你不用在每个页面写 fetch。Refine 帮你：

拼接 URL
处理分页参数
处理过滤参数
处理排序参数
缓存响应
处理错误

内置的 Data Provider

Refine 提供了 15+ 开箱即用的 Data Provider：

Provider	用途
`@refinedev/simple-rest`	标准 REST API
`@refinedev/graphql`	GraphQL API
`@refinedev/strapi`	Strapi CMS
`@refinedev/supabase`	Supabase
`@refinedev/hasura`	Hasura GraphQL
`@refinedev/nestjs-crud`	NestJS CRUD
`@refinedev/airtable`	Airtable
`@refinedev/firebase`	Firebase

如果你的后端是 FastAPI，写一个自定义 Data Provider 即可：

// customDataProvider.ts
import dataProvider from "@refinedev/simple-rest";

export const customDataProvider = {
 ...dataProvider("https://your-fastapi.com/api"),

 // 自定义 getList，适配你的 FastAPI 分页格式
 getList: async ({ resource, pagination, filters, sorters }) => {
 const response = await fetch(
 `/api/${resource}?` +
 `page=${pagination.current}&` +
 `size=${pagination.pageSize}`
 );
 const { items, total } = await response.json();
 return { data: items, total };
 },
};

核心概念 4：Auth Provider（认证提供者）

认证逻辑也抽象成 Provider：

const authProvider = {
 // 登录
 login: async ({ email, password }) => {
 const response = await fetch("/api/auth/login", {
 method: "POST",
 body: JSON.stringify({ email, password }),
 });

 if (response.ok) {
 const { token } = await response.json();
 localStorage.setItem("token", token);
 return { success: true };
 }

 return { success: false, error: { message: "登录失败" } };
 },

 // 登出
 logout: async () => {
 localStorage.removeItem("token");
 return { success: true };
 },

 // 检查登录状态
 check: async () => {
 const token = localStorage.getItem("token");
 return token
 ? { authenticated: true }
 : { authenticated: false, redirectTo: "/login" };
 },

 // 获取当前用户
 getIdentity: async () => {
 const response = await fetch("/api/auth/me");
 const user = await response.json();
 return user;
 },

 // 权限检查
 can: async ({ action, resource }) => {
 const user = await authProvider.getIdentity();
 return user.role === "admin" || user.permissions.includes(`${action}:${resource}`);
 },
};

使用方式

// 包裹整个应用
<Refine
 authProvider={authProvider}
 // ...
>
 <App />
</Refine>

// 在组件中使用
import { useCan } from "@refinedev/core";

const DeleteButton = ({ projectId }) => {
 const { data: canDelete } = useCan({
 action: "delete",
 resource: "projects",
 params: { id: projectId },
 });

 return canDelete ? <Button>删除</Button> : null;
};

Refine 会自动处理：

未登录跳转到 /login
登录后跳回原页面
侧边栏根据权限显示/隐藏菜单项
按钮根据权限显示/隐藏

核心概念 5：Inferencer（自动生成 CRUD 页面）

这是最惊艳的功能。

使用方式

# 安装 Inferencer
npm install @refinedev/inferencer

# 运行
npx @refinedev/cli@latest inferencer

Inferencer 做了什么？

读取你的 API Schema（通过 Data Provider）
分析字段类型：
- string → 文本输入框
- number → 数字输入框
- boolean → 开关
- date → 日期选择器
- enum → 下拉选择
- relation → 关联选择器
生成完整的 CRUD 页面代码

生成的代码示例

// Inferencer 生成的列表页（简化版）
import { List, useTable } from "@refinedev/antd";
import { Table } from "antd";

export const ProjectList = () => {
 const { tableProps } = useTable({
 resource: "projects",
 });

 return (
 <List>
 <Table {...tableProps}>
 <Table.Column dataIndex="id" title="ID" />
 <Table.Column dataIndex="name" title="名称" />
 <Table.Column dataIndex="status" title="状态" />
 <Table.Column dataIndex="created_at" title="创建时间" />
 <Table.Column
 title="操作"
 render={(record) => (
 <>
 <EditButton hideText recordItemId={record.id} />
 <DeleteButton hideText recordItemId={record.id} />
 </>
 )}
 />
 </Table>
 </List>
 );
};

这个代码你可以：

直接使用（功能完整）
作为起点修改（符合你的需求）
保留核心逻辑，换 UI（用 shadcn/ui 替换 Ant Design）

实战：用 Refine + shadcn/ui 搭建后台

步骤 1：创建项目

npm create refine-app@latest my-admin -- \
 --preset next \
 --ui shadcn

步骤 2：配置 Data Provider

// src/dataProvider.ts
import dataProvider from "@refinedev/simple-rest";

export const dataProvider = {
 ...dataProvider("https://your-fastapi.com/api"),

 // 适配 FastAPI 的分页格式
 getList: async ({ resource, pagination, filters, sorters }) => {
 const params = new URLSearchParams({
 page: String(pagination.current),
 size: String(pagination.pageSize),
 });

 const response = await fetch(`/api/${resource}?${params}`);
 const { items, total } = await response.json();

 return { data: items, total };
 },
};

步骤 3：配置资源

// src/app.tsx
import { Refine } from "@refinedev/core";
import { dataProvider } from "./dataProvider";

export default function App() {
 return (
 <Refine
 dataProvider={dataProvider}
 resources={[
 {
 name: "projects",
 list: "/projects",
 create: "/projects/create",
 edit: "/projects/edit/:id",
 meta: { label: "项目" },
 },
 {
 name: "tasks",
 list: "/tasks",
 create: "/tasks/create",
 edit: "/tasks/edit/:id",
 meta: { label: "任务" },
 },
 {
 name: "users",
 list: "/team",
 meta: { label: "团队" },
 },
 ]}
 >
 {/* 你的路由配置 */}
 </Refine>
 );
}

步骤 4：用 Inferencer 生成页面

npx @refinedev/cli@latest inferencer

这会在 src/pages/ 下生成：

pages/
 projects/
 list.tsx
 show.tsx
 create.tsx
 edit.tsx
 tasks/
 list.tsx
 show.tsx
 create.tsx
 edit.tsx
 users/
 list.tsx

步骤 5：美化 UI

生成的代码用的是 shadcn/ui 组件。你可以直接修改：

// src/pages/projects/list.tsx
import { Table } from "@/components/ui/table";
import { Button } from "@/components/ui/button";
import { useList } from "@refinedev/core";

export const ProjectList = () => {
 const { data, isLoading } = useList({ resource: "projects" });

 if (isLoading) return <div>加载中...</div>;

 return (
 <div className="p-6">
 <div className="flex justify-between mb-4">
 <h1 className="text-2xl font-bold">项目列表</h1>
 <Button>新建项目</Button>
 </div>

 <Table>
 <TableHeader>
 <TableRow>
 <TableHead>名称</TableHead>
 <TableHead>状态</TableHead>
 <TableHead>创建时间</TableHead>
 </TableRow>
 </TableHeader>
 <TableBody>
 {data?.data.map((project) => (
 <TableRow key={project.id}>
 <TableCell>{project.name}</TableCell>
 <TableCell>{project.status}</TableCell>
 <TableCell>{project.created_at}</TableCell>
 </TableRow>
 ))}
 </TableBody>
 </Table>
 </div>
 );
};

对比：Refine vs 传统开发

假设你要开发一个包含 5 个资源的后台（projects、tasks、users、teams、settings）：

能力	传统开发	用 Refine
列表分页	每个页面手写（5 × 50 行）	自动
搜索过滤	每个页面手写（5 × 30 行）	自动
排序	每个页面手写（5 × 20 行）	自动
新建表单	每个页面手写（5 × 100 行）	自动生成
编辑表单	每个页面手写（5 × 100 行）	自动生成
API 错误处理	每个调用手写（N × 10 行）	统一处理
乐观更新	手写（复杂）	内置
权限控制	每个按钮判断（N × 5 行）	Provider 统一
侧边栏菜单	手写配置（50 行）	自动生成
路由配置	手写（5 × 4 × 5 行）	自动生成
总代码量	约 3000 行	约 300 行（主要是 Data Provider + UI 美化）

开发时间对比：

阶段	传统开发	用 Refine
搭建框架	2 天	0.5 天
写 CRUD 页面	5 天	0.5 天（Inferencer）
美化 UI	2 天	2 天
处理边界情况	3 天	1 天
总计	12 天	4 天

Refine 的局限

1. 后端 API 要规范

Refine 的核心假设：API 即界面。

如果你的 API 是标准的 RESTful：

GET /api/projects
GET /api/projects/:id
POST /api/projects
PUT /api/projects/:id
DELETE /api/projects/:id

Refine 可以零成本对接。

但如果你的 API 比较随意：

GET /api/get_project_list
POST /api/create_new_project
GET /api/project_detail?id=123

你就得写很多自定义 Data Provider，优势减弱。

建议：用 Refine 之前，先规范后端 API。

2. 学习成本

Refine 的概念：

Data Provider
Auth Provider
Resource
Access Control
Live Mode（实时更新）
Audit Log（操作日志）

学习曲线：中等。比从头写低，比用 Ant Design Pro 高。

3. 复杂场景还是要手写

如果你的页面：

有复杂的图表
有拖拽排序
有复杂的联动逻辑
有非 CRUD 的业务

Refine 帮不了你。它只解决 CRUD 部分。

但好消息是：Refine 不妨碍你手写。你可以在 Refine 项目里混用手写页面。

总结：Refine 的价值

Refine 解决了一个真实痛点：后台管理界面的重复劳动。

它的核心价值：

API 驱动界面：后端 API 结构决定前端页面结构
Headless 设计：业务逻辑和 UI 完全分离
Provider 抽象：数据、认证、权限统一管理
Inferencer：自动生成 CRUD 页面代码

适合的场景：

后台管理系统
Admin Panel
Dashboard
B2B 应用
内部工具

不适合的场景：

面向 C 端的产品（UI 要求高）
非 CRUD 为主的业务
API 非常不规范的后端

我的建议：

如果你的项目符合以下条件，强烈推荐尝试 Refine：

后端是 RESTful API（或者可以改成 RESTful）
大部分页面是 CRUD
愿意接受新的架构方式
用 React 技术栈

Refine + shadcn/ui 是一个很好的组合：Refine 负责业务逻辑，shadcn/ui 负责美观 UI。

这样既享受了 Refine 的开发效率，又不会变成 Ant Design 那种"一眼模板"的 UI。

参考

React框架使用教程

Thu, 29 May 2025 13:46:52 +0800

基础知识

📚 1. 学习 React 前的准备

在开始学习 React 之前，你需要对以下技术有一定的了解：

HTML (超文本标记语言)：了解基本的 HTML 结构和标签。
CSS (层叠样式表)：了解如何使用 CSS 来设置页面样式。
JavaScript (JS)：这是最重要的。你需要掌握 JavaScript 的基础知识，包括：
- 变量、数据类型、操作符
- 函数（特别是箭头函数 =>）
- 数组和对象（包括解构赋值、扩展运算符 ...）
- ES6+ 模块 (import/export)
- this 关键字 (虽然在函数组件中不常用，但理解其基本概念有益)
- 异步编程 (Promises, async/await) - 在后续学习中会用到

🛠️ 2. 搭建 React 开发环境

最快上手 React 的方式是使用官方推荐的脚手架工具 Create React App。

安装 Node.js 和 npm (或 yarn)：
- React 开发依赖 Node.js 环境。访问 Node.js 官网下载并安装最新 LTS (长期支持) 版本。
- npm (Node Package Manager) 会随 Node.js 一起安装。你也可以选择使用 yarn 作为包管理工具。
创建你的第一个 React 应用：打开你的终端或命令行工具，运行以下命令：
```
npx create-react-app my-react-app
```
这里 my-react-app 是你的项目名称，你可以替换成任何你喜欢的名字。 npx 是一个 npm 包运行器，它会下载最新版本的 create-react-app 并执行它。
进入项目目录并启动开发服务器：
```
cd my-react-app
npm start
```
或者，如果你使用 yarn：
```
cd my-react-app
yarn start
```
这会启动一个本地开发服务器（通常在 http://localhost:3000），并在你的浏览器中自动打开应用。当你修改代码并保存时，页面会自动刷新。

📂 3. 了解项目结构

create-react-app 会生成一个标准的项目结构：

my-react-app/
├── node_modules/ # 项目依赖的第三方库
├── public/ # 存放静态资源
│ ├── index.html # 应用的 HTML 入口文件
│ └── ... # 其他如 favicon.ico, manifest.json 等
├── src/ # 主要的源代码目录
│ ├── App.css # App 组件的样式
│ ├── App.js # 主要的 App 组件
│ ├── App.test.js # App 组件的测试文件
│ ├── index.css # 全局样式
│ ├── index.js # JavaScript 的入口文件，将 App 组件渲染到 HTML 中
│ ├── logo.svg # 示例图片
│ └── ... # 其他辅助文件
├── .gitignore # Git 忽略文件配置
├── package.json # 项目元数据和依赖项列表
├── package-lock.json # (或 yarn.lock) 锁定依赖版本
└── README.md # 项目说明文件

public/index.html：这是你的单页面应用的唯一 HTML 文件。React 会将你的组件渲染到这个文件中的某个 DOM 元素（通常是一个 id="root" 的 div）。
src/index.js：这是 JavaScript 的入口。它使用 ReactDOM.render() 方法将你的主组件（通常是 App 组件）挂载到 public/index.html 中的 div#root元素上。
src/App.js：这是应用的根组件。你将从这里开始构建你的用户界面。

✨ 4. React核心概念

a. JSX (JavaScript XML)

JSX 是一种 JavaScript 的语法扩展，它允许你在 JavaScript 代码中编写类似 HTML 的结构。浏览器并不直接支持 JSX，它需要通过 Babel 这样的转译器转换为普通的 JavaScript 对象。

示例：

const name = "React 学习者";
const element = <h1>你好, {name}!</h1>; // JSX 表达式

// 上面的 JSX 实际上会被 Babel 转译成类似这样的 JavaScript：
// const element = React.createElement('h1', null, '你好, ', name, '!');

在 JSX 中：

你可以嵌入 JavaScript 表达式，用花括号 {} 包裹。
HTML 属性名需要使用驼峰命名法（例如 className 而不是 class，onClick 而不是 onclick）。
所有标签必须闭合（例如 <img /> 或 <div></div>）。

b. 组件 (Components)

组件是 React 的核心。它们是独立且可复用的代码块，负责渲染 UI 的一部分。React 主要有两种类型的组件：

函数组件 (Functional Components)：这是目前推荐的方式。它们是简单的 JavaScript 函数，接收一个 props 对象作为参数，并返回一个 React 元素（通常是 JSX）。

// src/components/Welcome.js
import React from 'react';

function Welcome(props) {
 return <h1>你好, {props.name}!</h1>;
}

export default Welcome;

使用组件：

// src/App.js
import React from 'react';
import Welcome from './components/Welcome'; // 假设你创建了components目录

function App() {
 return (
 <div>
 <Welcome name="张三" />
 <Welcome name="李四" />
 </div>
 );
}

export default App;

类组件 (Class Components)：这是老版本 React 中常用的方式，基于 ES6 的 class。它们需要继承 React.Component 并实现一个 render() 方法。

// src/components/Greeting.js
import React from 'react';

class Greeting extends React.Component {
 render() {
 return <h1>你好, {this.props.name}! (来自类组件)</h1>;
 }
}

export default Greeting;

建议：对于新项目，优先使用函数组件和 Hooks。

c. Props (属性)

Props (properties 的缩写) 是组件的配置信息。它们是从父组件传递给子组件的数据。Props 是只读的，子组件不能直接修改接收到的 props。

示例见上面的 Welcome 组件，name 就是一个 prop。

d. State (状态)

State 是组件内部私有的数据，它可以随时间变化（例如用户交互、网络响应等）。当组件的 state 改变时，React 会自动重新渲染该组件。

在函数组件中，我们使用 useState Hook 来管理 state。

// src/components/Counter.js
import React, { useState } from 'react'; // 引入 useState Hook

function Counter() {
 // 声明一个名为 count 的 state 变量，初始值为 0
 // setCount 是一个用来更新 count 的函数
 const [count, setCount] = useState(0);

 return (
 <div>
 <p>你点击了 {count} 次</p>
 <button onClick={() => setCount(count + 1)}>
 点我增加
 </button>
 <button onClick={() => setCount(count > 0 ? count - 1 : 0)}>
 点我减少
 </button>
 </div>
 );
}

export default Counter;

关键点：

useState 返回一个数组：[currentStateValue, functionToUpdateState]。
通过调用 setCount(newValue) 来更新 count 的值，这会触发组件的重新渲染。
永远不要直接修改 state (例如 count = count + 1;)，总是使用 set 函数。

e. 事件处理 (Event Handling)

React 元素的事件处理和 DOM 元素的事件处理非常相似，但有一些语法差异：

React 事件的命名采用驼峰式，而不是纯小写 (例如 onClick 而不是 onclick)。
通过 JSX，你传递一个函数作为事件处理程序，而不是一个字符串。

示例见上面的 Counter 组件中的 onClick 事件。

f. 条件渲染 (Conditional Rendering)

你可以根据应用的 state 或 props 来决定渲染哪些组件或元素。常用的方法有：

if 语句
逻辑与运算符 &&
三元运算符 condition ? trueValue : falseValue

// src/components/LoginControl.js
import React, { useState } from 'react';

function UserGreeting(props) {
 return <h1>欢迎回来!</h1>;
}

function GuestGreeting(props) {
 return <h1>请登录.</h1>;
}

function LoginButton(props) {
 return <button onClick={props.onClick}>登录</button>;
}

function LogoutButton(props) {
 return <button onClick={props.onClick}>退出</button>;
}

function LoginControl() {
 const [isLoggedIn, setIsLoggedIn] = useState(false);

 const handleLoginClick = () => {
 setIsLoggedIn(true);
 };

 const handleLogoutClick = () => {
 setIsLoggedIn(false);
 };

 let button;
 let greeting;

 if (isLoggedIn) {
 button = <LogoutButton onClick={handleLogoutClick} />;
 greeting = <UserGreeting />;
 } else {
 button = <LoginButton onClick={handleLoginClick} />;
 greeting = <GuestGreeting />;
 }

 return (
 <div>
 {greeting}
 {button}
 {/* 使用三元运算符的另一种方式 */}
 {/* {isLoggedIn ? <UserGreeting /> : <GuestGreeting />}
 {isLoggedIn
 ? <LogoutButton onClick={handleLogoutClick} />
 : <LoginButton onClick={handleLoginClick} />} */}
 </div>
 );
}

export default LoginControl;

g. 列表和 Keys (Lists and Keys)

你可以使用 JavaScript 的 map() 方法来将数组渲染为元素列表。当渲染列表时，React 需要一个特殊的 key prop 来帮助识别哪些列表项被更改、添加或删除。key 应该是唯一的字符串，通常使用数据项中的 ID。

// src/components/NumberList.js
import React from 'react';

function ListItem(props) {
 // 正确！这里不需要指定 key:
 return <li>{props.value}</li>;
}

function NumberList(props) {
 const numbers = props.numbers;
 const listItems = numbers.map((number) =>
 // 正确！key 应该在数组的上下文中被指定
 <ListItem key={number.toString()} value={number} />
 );
 return (
 <ul>
 {listItems}
 </ul>
 );
}

export default NumberList;

// 在 App.js 中使用:
// import NumberList from './components/NumberList';
// const numbers = [1, 2, 3, 4, 5];
// <NumberList numbers={numbers} />

重要提示：key 只需要在兄弟节点中唯一，不需要全局唯一。不要使用数组的索引作为 key，除非列表是静态的且不会重新排序。

🚀 5. 第一个动手实践：待办事项列表 (Todo List)

让我们结合以上概念，尝试构建一个简单的待办事项列表。

创建 TodoItem.js 组件 (src/components/TodoItem.js)

import React from 'react';

function TodoItem({ todo, index, toggleTodo, removeTodo }) {
 return (
 <li style={{ textDecoration: todo.isCompleted ? 'line-through' : '' }}>
 {todo.text}
 <div>
 <button onClick={() => toggleTodo(index)}>
 {todo.isCompleted ? '撤销' : '完成'}
 </button>
 <button onClick={() => removeTodo(index)} style={{ marginLeft: '10px' }}>
 删除
 </button>
 </div>
 </li>
 );
}

export default TodoItem;

创建 TodoList.js 组件 (src/components/TodoList.js)

import React, { useState } from 'react';
import TodoItem from './TodoItem';

function TodoList() {
 const [todos, setTodos] = useState([
 { text: '学习 React', isCompleted: false },
 { text: '构建一个 Todo 应用', isCompleted: false },
 ]);
 const [inputValue, setInputValue] = useState('');

 const addTodo = (text) => {
 if (!text.trim()) return; // 不添加空内容
 const newTodos = [...todos, { text, isCompleted: false }];
 setTodos(newTodos);
 };

 const toggleTodo = (index) => {
 const newTodos = [...todos];
 newTodos[index].isCompleted = !newTodos[index].isCompleted;
 setTodos(newTodos);
 };

 const removeTodo = (index) => {
 const newTodos = [...todos];
 newTodos.splice(index, 1);
 setTodos(newTodos);
 };

 const handleSubmit = (e) => {
 e.preventDefault(); // 阻止表单默认提交行为
 addTodo(inputValue);
 setInputValue(''); // 清空输入框
 };

 return (
 <div className="todo-list">
 <h1>我的待办事项</h1>
 <form onSubmit={handleSubmit}>
 <input
 type="text"
 value={inputValue}
 onChange={(e) => setInputValue(e.target.value)}
 placeholder="添加新的待办..."
 />
 <button type="submit">添加</button>
 </form>
 <ul>
 {todos.map((todo, index) => (
 <TodoItem
 key={index} // 注意：这里用 index 做 key 仅为演示，实际项目中如有唯一 ID 更好
 index={index}
 todo={todo}
 toggleTodo={toggleTodo}
 removeTodo={removeTodo}
 />
 ))}
 </ul>
 </div>
 );
}

export default TodoList;

你可能需要一些简单的 CSS 来美化它。在 src/App.css (或新建一个 TodoList.css 并导入) 添加：

/* src/App.css 或 src/TodoList.css */
.todo-list {
 font-family: sans-serif;
 max-width: 500px;
 margin: 50px auto;
 padding: 20px;
 border: 1px solid #eee;
 border-radius: 8px;
 box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

.todo-list h1 {
 text-align: center;
 color: #333;
}

.todo-list form {
 display: flex;
 margin-bottom: 20px;
}

.todo-list input[type="text"] {
 flex-grow: 1;
 padding: 10px;
 border: 1px solid #ddd;
 border-radius: 4px;
 font-size: 16px;
}

.todo-list button {
 padding: 10px 15px;
 margin-left: 10px;
 background-color: #5cb85c;
 color: white;
 border: none;
 border-radius: 4px;
 cursor: pointer;
 font-size: 16px;
}

.todo-list button:hover {
 background-color: #4cae4c;
}

.todo-list ul {
 list-style-type: none;
 padding: 0;
}

.todo-list li {
 display: flex;
 justify-content: space-between;
 align-items: center;
 padding: 10px 0;
 border-bottom: 1px solid #eee;
}

.todo-list li:last-child {
 border-bottom: none;
}

.todo-list li button {
 background-color: #d9534f;
 font-size: 12px;
 padding: 5px 10px;
}
.todo-list li button:first-of-type { /* 针对 "完成/撤销" 按钮 */
 background-color: #f0ad4e;
}

在 src/App.js 中使用 TodoList 组件

import React from 'react';
import './App.css'; // 确保引入了样式
import TodoList from './components/TodoList'; // 确保路径正确

function App() {
 return (
 <div className="App">
 <TodoList />
 </div>
 );
}

export default App;

现在，你的浏览器应该显示一个可以添加、完成和删除待办事项的列表了！

💡 6. React Hooks 简介

Hooks 是 React 16.8 版本引入的新特性，它允许你在不编写 class 的情况下使用 state 以及其他的 React 特性。

useState：如上所述，用于在函数组件中添加 state。

useEffect：用于处理副作用（side effects），例如数据获取、订阅或手动更改 DOM。它类似于类组件中的 componentDidMount、componentDidUpdate 和 componentWillUnmount 的组合。

import React, { useState, useEffect } from 'react';

function Timer() {
 const [seconds, setSeconds] = useState(0);

 useEffect(() => {
 // 这个函数会在组件挂载后以及每次更新后执行
 const intervalId = setInterval(() => {
 setSeconds(prevSeconds => prevSeconds + 1);
 }, 1000);

 // 清理函数：这个函数会在组件卸载前执行
 return () => clearInterval(intervalId);
 }, []); // 空数组 [] 表示这个 effect 只在组件挂载和卸载时运行一次

 return (
 <div>
 计时器: {seconds} 秒
 </div>
 );
}

export default Timer;

useEffect 的依赖项数组：

[] (空数组)：Effect 只在挂载时运行一次，清理函数在卸载时运行。
[var1, var2]：Effect 在挂载时运行，并且在 var1 或 var2 改变后的每次渲染时运行。
不传第二个参数（不推荐）：Effect 在每次渲染后都会运行。

还有许多其他的 Hooks，如 useContext, useReducer, useCallback, useMemo, useRef 等，你可以在后续学习中逐步掌握。

🚀 7. 接下来学什么？

当你掌握了以上基础知识后，可以继续学习：

表单处理 (Forms)：更深入地学习受控组件和非受控组件。
组件生命周期 (Lifecycle Methods)：虽然 Hooks 简化了许多，但了解类组件的生命周期方法对理解 React 的工作方式仍有帮助。
路由 (Routing)：使用 React Router 来构建多页面的单页面应用。
状态管理 (State Management)：
- Context API：React 内置的，用于在组件树中共享状态，避免 props drilling (逐层传递 props)。
- Redux, Zustand, MobX：更强大的第三方状态管理库，适用于大型复杂应用。
数据获取 (Data Fetching)：如何从后端 API 获取数据并展示（例如使用 fetch API 或 axios 库，并结合 useEffect）。
组件库 (Component Libraries)：例如 Material-UI, Ant Design, Chakra UI 等，它们提供了预制的 UI 组件，可以加速开发。
测试 (Testing)：使用 Jest, React Testing Library 等工具为你的组件编写测试。
构建和部署 (Build and Deployment)：学习如何将你的 React 应用打包并部署到服务器或静态网站托管平台。
TypeScript 与 React：为你的 React 项目添加静态类型检查。
性能优化 (Performance Optimization)：React.memo, useCallback, useMemo, 代码分割等。

💖 8. 学习建议

多动手实践：理论学习很重要，但通过实际编写代码来巩固知识更重要。
阅读官方文档：React 的官方文档非常出色，是学习的最佳资源。
参与社区：在 Stack Overflow, Reddit (r/reactjs), DEV Community 等社区提问和交流。
从小项目开始：逐步增加项目的复杂度。
保持耐心：学习曲线可能有些陡峭，但坚持下去就会有收获。

为什么使用Vite来构建React项目

“React 和 Vite 项目”是将强大的前端库 React 与现代、极速的构建工具 Vite 结合起来的开发方式。

这是一种非常流行和高效的组合，Vite 旨在通过提供闪电般的开发服务器启动速度和极快的热模块替换 (HMR) 来显著改善前端开发体验。

以下是关于 React 和 Vite 项目的详细说明：

🚀 为什么使用 Vite 来构建 React 项目？

Vite 解决了传统构建工具（如 Create React App 背后的 Webpack）在大型项目中遇到的一些性能瓶颈。

极速的开发服务器启动： Vite 使用浏览器原生的 ES 模块 (ESM) 功能。它不需要在启动前打包整个应用，而是按需提供代码文件，使得开发服务器几乎可以瞬时启动。
闪电般的热模块替换 (HMR)： 当你修改代码时，Vite 只会更新被修改的模块，而不是重新加载整个页面。这个过程非常快，让你能够几乎实时地看到代码变更的效果，且不会丢失应用状态。
优化的构建： 在生产环境中，Vite 使用 Rollup 进行打包。Rollup 是一个非常高效的打包器，擅长 tree-shaking（移除未使用的代码）和生成高度优化的代码包。
开箱即用的体验： Vite 原生支持 TypeScript、JSX、CSS Modules 等，无需繁琐配置。

🛠️ 如何创建一个 React + Vite 项目？

创建一个 React + Vite 项目非常简单。你可以使用 npm, yarn, 或 pnpm。

打开你的终端，运行以下命令之一：

使用 NPM:

npm create vite@latest my-react-app -- --template react

使用 Yarn:

yarn create vite my-react-app --template react

使用 PNPM:

pnpm create vite my-react-app --template react

🏃‍♂️ 启动项目

创建完成后，按照终端提示的步骤操作：

进入项目目录：
```
cd my-react-app
```
安装依赖：
```
npm install
```
启动开发服务器：
```
npm run dev
```

执行 npm run dev 后，你将看到一个本地服务器地址（通常是 http://localhost:5173/）。在浏览器中打开它，你就能看到你的 React + Vite 应用了。

🆚 与 Create React App (CRA) 的对比

Vite 通常被视为 Create React App (CRA) 的现代替代品。

特性	Vite	Create React App (CRA)
开发服务器	原生 ESM，按需编译	Webpack 打包，冷启动慢
启动速度	极快（秒级）	较慢（随项目增大而变慢）
HMR	极快（基于 ESM）	较慢（通常刷新整个组件）
构建工具	Rollup (生产环境)	Webpack
配置	简单，`vite.config.js`	复杂，需 `eject` 或 Craco

总之，React + Vite 组合提供了当下最顶级的开发体验，特别是对于追求效率和性能的开发者而言。

你是想了解如何将旧的 CRA 项目迁移到 Vite，还是想知道关于 Vite 配置的更多细节（例如如何配置代理）？

如何禁止用户在浏览器中查看前端源码

首先，我们必须明确一个核心事实：你永远无法 100% 阻止用户查看你的前端代码。

Web的根本机制决定了浏览器必须下载你的HTML、CSS和JavaScript文件才能在用户屏幕上渲染出页面。只要代码在浏览器上，技术上总有办法被查看（例如通过开发者工具的“网络”或“来源”面板）。

但是，你的目标可能不是“完全隐藏”，而是“防止他人轻易地阅读、理解和复制你的原始源代码”。

对于这个目标，Vite（以及其他现代构建工具）已经为你做了大部分工作。你需要做的主要有以下几件事：

1. 依赖生产构建（Vite 默认会做）

你绝对不能将 npm run dev（开发环境）的代码部署到线上。开发环境为了便于调试，会保留所有原始代码、注释和模块路径。

你必须使用生产构建命令：

npm run build

这个命令会触发 Vite (底层使用 Rollup) 执行以下操作，这已经解决了你 90% 的担忧：

打包 (Bundling): 将你所有的 .js, .jsx 模块合并成少数几个文件。
转译 (Transpiling): 将你的 JSX 语法和 ES6+ 语法转换为浏览器兼容的普通 JavaScript。
压缩 (Minification): 这是最关键的一步。它会删除所有空格、换行、注释，并将你的变量名（如 const [userInfo, setUserInfo] = useState(null);）替换成单个字母（如 const [a,b]=useState(null);）。

结果： 用户在浏览器中看到的将是一堆紧凑、混乱、几乎无法阅读的“乱码”，这已经不是你的“源码”了，而是“编译后的机器码”。

2. 关键一步：关闭 Source Maps（源映射）

这是最重要的一步，也是新手最容易忽略的一步。

什么是 Source Map? 它是一个 .map 文件，作用是将“压缩后的代码”映射回“你的原始源代码”。它的唯一目的是帮助开发者在生产环境（线上）也能轻松地调试错误。
你的问题： 如果你将 .map 文件上传到服务器，任何人都可以使用浏览器的开发者工具，像看你本地的 src 文件夹一样，看到你所有的原始 .jsx 文件、目录结构和注释。

如何解决 (在 Vite 中):

Vite 非常智能，默认情况下在生产构建 (npm run build) 中是关闭 Source Map 的。

但如果你（或你的同事）之前为了调试方便打开过它，你需要检查你的 vite.config.js (或 vite.config.ts) 文件，确保 build.sourcemap 设置为 false。

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
 plugins: [react()],
 build: {
 // 确保这一行是 false，或者直接删掉（Vite 默认就是 false）
 sourcemap: false
 }
})

检查方法： 运行 npm run build 后，检查生成的 dist/assets 文件夹，确保里面没有 .js.map 或 .css.map 结尾的文件。

3. （不推荐）极端方案：代码混淆 (Obfuscation)

如果你觉得“压缩”还不够，还想让代码逻辑变得更难被逆向工程，下一步就是“代码混淆”。

混淆器会做一些事情，比如：

将字符串（如 “API_KEY_PUBLIC”）拆分成 ['A','P','I',...].join('')。
重写控制流（if/else 变成复杂的 switch 或循环）。
注入无意义的“僵尸代码”。

为什么不推荐？

严重性能问题： 混淆后的代码通常体积更大，运行速度更慢。
调试噩梦： 如果线上出了 bug，你自己也看不懂代码，Source Map 将完全失效。
虚假的安全感： 专业的逆向工程师依然可以（花更多时间）破解它。

如果你坚持要用，可以使用 vite-plugin-javascript-obfuscator 这类插件。

总结：你的最佳策略

对于 99% 的项目，你只需要做两件事：

始终使用 npm run build 来打包你的应用。
确保 vite.config.js 中 build.sourcemap 为 false（或未设置，使用默认值）。

最后，请记住一个黄金法则：

任何敏感信息（如 API 密钥、私有算法、管理员密码）绝对不能放在前端代码中，无论你如何压缩或混淆。 这些信息必须始终保留在你的后端服务器上。

实战

TypeScript中的两种[]符号含义

问题

在React的useState中看到这样的代码：

const [files, setFiles] = useState<FileInfo[]>([]);

为什么<FileInfo[]>里面也有一个[]？

解答

这里有两个不同的[]，它们的含义完全不同：

1. `<FileInfo[]>` - TypeScript类型注解中的`[]`

useState<FileInfo[]>

这里的[]表示数组类型：

FileInfo是单个文件信息对象的类型
FileInfo[]表示"FileInfo对象的数组"
相当于Array<FileInfo>的简写形式

2. `([])` - 初始值中的`[]`

useState<FileInfo[]>([])

这里的[]是空数组字面量：

这是JavaScript中创建空数组的语法
作为useState的初始值传入
表示状态的起始值是一个空数组

对比理解

// 完整写法更清楚地看出区别：
const [files, setFiles] = useState<Array<FileInfo>>(new Array());

// 简化写法：
const [files, setFiles] = useState<FileInfo[]>([]);

类比说明

想象一下：

<FileInfo[]>像是说"这个盒子专门装FileInfo类型的物品，而且可以装很多个"
([])像是说"开始的时候盒子是空的"

其他例子

// 数字数组，初始值为空
const [numbers, setNumbers] = useState<number[]>([]);

// 字符串数组，初始值有内容
const [names, setNames] = useState<string[]>(["Alice", "Bob"]);

// 单个对象，不是数组
const [user, setUser] = useState<FileInfo | null>(null);

总结

第一个[]是类型定义，第二个[]是实际的空数组值！

streamlit使用教程

Wed, 14 May 2025 11:53:17 +0800

一些问题和使用技巧

streamlit之下使用optuna做多进程调参

import streamlit as st
import optuna
import multiprocessing
import time

# 模拟一个简单的目标函数
def objective(trial):
 x = trial.suggest_float('x', -10, 10)
 return (x - 2) ** 2

# 优化函数
def optimize(study, n_trials, progress_queue):
 for i in range(n_trials):
 study.optimize(objective, n_trials=1)
 progress_queue.put(study.best_value)

def main():
 st.title("Optuna Optimization Progress Display")
 chose_n_trials = st.number_input("Choose number of trials", min_value=10, max_value=1000, value=100)

 # 创建或加载Optuna study
 study_name = 'optuna_study'
 try:
 study = optuna.create_study(study_name=study_name, storage='sqlite:///optuna_study.db', direction='minimize')
 except:
 study = optuna.load_study(study_name=study_name, storage='sqlite:///optuna_study.db')

 if st.button("Start Optimization"):
 progress_queue = multiprocessing.Queue()
 n_processes = 4 # 设置并行进程数
 trials_per_process = chose_n_trials // n_processes

 # 启动多进程优化
 processes = []
 for _ in range(n_processes):
 p = multiprocessing.Process(target=optimize, args=(study, trials_per_process, progress_queue))
 p.start()
 processes.append(p)

 # 初始化进度条
 progress_bar = st.progress(0)
 best_score = float('inf')

 for _ in range(chose_n_trials):
 best_value = progress_queue.get()
 if best_value < best_score:
 best_score = best_value
 progress = (_ + 1) / chose_n_trials
 progress_bar.progress(progress)
 st.write(f"Best score: {best_score}")

 # 确保所有进程完成
 for p in processes:
 p.join()

 st.success("Optimization completed!")

if __name__ == "__main__":
 main()

以一种访问权限不允许的方式做了一个访问套接字的尝试|端口占用

streamlit连接数据库并且增删改查

flask-构建一个简单的文件同步系统

Mon, 12 May 2025 09:59:01 +0800

使用Python构建文件同步系统：步骤指南

在当今互联网时代，能够在本地机器和远程服务器之间同步文件的能力变得至关重要。无论是备份重要文档、与团队成员共享大文件，还是在多个设备间保持数据一致性，一个强大的文件同步系统都能发挥重要作用。在这篇博客文章中，我们将逐步介绍如何使用Python构建一个简单而强大的文件同步系统，并为大文件传输添加进度条功能。

挑战

我们的目标是创建一个系统，能够：

将本地文件上传到远程服务器
从服务器下载文件到本地机器
检查服务器上是否存在某个文件
处理大文件传输并提供可视化反馈

解决方案

我们将分两部分构建我们的解决方案：一个使用Flask的服务器端应用程序，和一个与服务器交互的客户端脚本。

第一部分：服务器

首先，让我们使用Flask创建一个简单的服务器，它可以处理文件上传、下载和存在性检查。

from flask import Flask, request, send_file, jsonify
import os

app = Flask(__name__)
UPLOAD_FOLDER = 'uploads'
if not os.path.exists(UPLOAD_FOLDER):
 os.makedirs(UPLOAD_FOLDER)

@app.route('/upload', methods=['POST'])
def upload_file():
 if 'file' not in request.files:
 return jsonify({"error": "没有文件部分"}), 400
 file = request.files['file']
 if file.filename == '':
 return jsonify({"error": "没有选择文件"}), 400
 if file:
 filename = os.path.join(UPLOAD_FOLDER, file.filename)
 file.save(filename)
 return jsonify({"message": "文件上传成功"}), 200

@app.route('/download/<filename>', methods=['GET'])
def download_file(filename):
 filepath = os.path.join(UPLOAD_FOLDER, filename)
 if os.path.exists(filepath):
 return send_file(filepath, as_attachment=True)
 else:
 return jsonify({"error": "文件未找到"}), 404

@app.route('/check/<filename>', methods=['GET'])
def check_file(filename):
 filepath = os.path.join(UPLOAD_FOLDER, filename)
 if os.path.exists(filepath):
 return jsonify({"exists": True}), 200
 else:
 return jsonify({"exists": False}), 200

if __name__ == '__main__':
 app.run(host='0.0.0.0', port=5000)

这个服务器提供了三个主要端点：

/upload 用于文件上传
/download/<filename> 用于文件下载
/check/<filename> 用于检查服务器上是否存在某个文件

第二部分：客户端

现在，让我们创建一个客户端脚本，它可以与我们的服务器交互并处理文件同步。我们将使用 requests 库进行HTTP通信，使用 tqdm 库来显示进度条。

import requests
import os
from tqdm import tqdm

SERVER_URL = "http://your_server_ip:5000"

def upload_file(filename):
 file_size = os.path.getsize(filename)
 with open(filename, 'rb') as f:
 with tqdm(total=file_size, unit='B', unit_scale=True, desc=f"正在上传 {filename}") as pbar:
 response = requests.post(
 f"{SERVER_URL}/upload",
 files={"file": f},
 data={"filename": os.path.basename(filename)},
 headers={"Content-Length": str(file_size)},
 stream=True
 )
 for chunk in response.iter_content(chunk_size=8192):
 if chunk:
 pbar.update(len(chunk))
 print(response.json())

def download_file(filename):
 with requests.get(f"{SERVER_URL}/download/{filename}", stream=True) as response:
 if response.status_code == 200:
 total_size = int(response.headers.get('content-length', 0))
 with open(filename, 'wb') as f, tqdm(
 total=total_size, unit='B', unit_scale=True, desc=f"正在下载 {filename}"
 ) as pbar:
 for chunk in response.iter_content(chunk_size=8192):
 if chunk:
 size = f.write(chunk)
 pbar.update(size)
 print(f"文件 {filename} 下载成功")
 else:
 print(response.json())

def check_file(filename):
 response = requests.get(f"{SERVER_URL}/check/{filename}")
 return response.json()['exists']

def sync_file(filename):
 if os.path.exists(filename) and not check_file(filename):
 print(f"正在将 {filename} 上传到服务器...")
 upload_file(filename)
 elif check_file(filename) and not os.path.exists(filename):
 print(f"正在从服务器下载 {filename}...")
 download_file(filename)
 elif not check_file(filename) and not os.path.exists(filename):
 print(f"文件 {filename} 在本地和服务器上都不存在")
 else:
 print(f"文件 {filename} 在本地和服务器上都已存在")

# 使用示例
sync_file("large_file.zip")

这个客户端脚本提供了几个关键功能：

文件上传：将文件发送到服务器，并显示进度条。
文件下载：从服务器检索文件，并显示进度条。
文件检查：验证服务器上是否存在某个文件。
同步逻辑：根据文件在本地和服务器上的存在情况，决定是上传、下载还是跳过该文件。

sync_file 函数封装了我们的同步逻辑：

如果文件在本地存在但服务器上不存在，则上传。
如果文件在服务器上存在但本地不存在，则下载。
如果文件在两个位置都不存在，我们会得到通知。
如果文件在两个位置都存在，我们会得到通知，无需采取任何操作。

整合使用

要使用这个文件同步系统：

在您的远程机器上启动Flask服务器。
在客户端脚本中更新 SERVER_URL，使其指向您的服务器。
运行客户端脚本，指定您想要同步的文件。

此外，如果你是本地服务器，进行了内网穿透，可以使用以下代码，优先使用本地ip地址，下面代码做了优化，将函数封装成为一个类

import requests
import os
from tqdm import tqdm
import time

class FileSync:
 def __init__(self, server_url1, server_url2):
 self.SERVER_URL1 = server_url1
 self.SERVER_URL2 = server_url2
 self.server_url = None

 def check_server(self, url):
 try:
 response = requests.get(url, timeout=5)
 return response.status_code == 200
 except requests.RequestException:
 return False

 def get_server_url(self):
 if self.check_server(self.SERVER_URL1 + "check/test.txt"):
 self.server_url = self.SERVER_URL1
 return self.SERVER_URL1
 elif self.check_server(self.SERVER_URL2 + "check/test.txt"):
 self.server_url = self.SERVER_URL2
 return self.SERVER_URL2
 else:
 raise Exception("无法连接到任何服务器")

 def upload_file(self, filename):
 self.get_server_url()
 file_size = os.path.getsize(filename)
 with open(filename, 'rb') as f:
 with tqdm(total=file_size, unit='B', unit_scale=True, desc=f"正在上传 {filename}") as pbar:
 response = requests.post(
 f"{self.server_url}upload",
 files={"file": (os.path.basename(filename), f)},
 data={"filename": os.path.basename(filename)},
 stream=True
 )
 for chunk in iter(lambda: f.read(8192), b''):
 if chunk:
 pbar.update(len(chunk))
 print(response.json())

 def download_file(self, filename):
 self.get_server_url()
 with requests.get(f"{self.server_url}download/{os.path.basename(filename)}", stream=True) as response:
 if response.status_code == 200:
 total_size = int(response.headers.get('content-length', 0))
 block_size = 8192
 with open(filename, 'wb') as f, tqdm(
 total=total_size, unit='B', unit_scale=True, desc=f"正在下载 {filename}"
 ) as pbar:
 for chunk in response.iter_content(block_size):
 size = f.write(chunk)
 pbar.update(size)
 print(f"文件 {filename} 下载成功")
 else:
 print(response.json())

 def check_file(self, filename):
 self.get_server_url()
 basename = os.path.basename(filename)
 response = requests.get(f"{self.server_url}check/{basename}")
 return response.json()['exists']

 def sync_file(self, filename):
 try:
 self.get_server_url() # 确保使用可用的服务器
 basename = os.path.basename(filename)
 if os.path.exists(filename) and not self.check_file(basename):
 print(f"正在将 {filename} 上传到服务器...")
 self.upload_file(filename)
 elif self.check_file(basename) and not os.path.exists(filename):
 print(f"正在从服务器下载 {filename}...")
 self.download_file(filename)
 elif not self.check_file(basename) and not os.path.exists(filename):
 print(f"文件 {filename} 在本地和服务器上都不存在")
 else:
 print(f"文件 {filename} 在本地和服务器上都已存在")
 except Exception as e:
 print(f"同步过程中发生错误: {str(e)}")

# 使用示例
if __name__ == "__main__":
 sync = FileSync("http://你弟内网ip/:5000", "http://你的公网ip:5000")
 # print(sync.check_file("test.txt"))
 sync.sync_file(r"C:\BaiduSyncdisk\code&note\0A-ZATA\data\光谱数据\MZI酒精数据_21&27&79&30_.xlsx")

结论

这个简单而有效的文件同步系统展示了我们如何利用Python创建强大的工具来管理不同位置的数据。添加进度条使其特别适用于处理大文件，在可能较长的传输操作期间提供视觉反馈。

虽然这个系统是一个很好的起点，但还有许多方式可以扩展它：

添加身份验证以实现安全的文件传输
实现文件版本控制
创建监视系统，自动同步更改
开发图形用户界面，便于交互

祝您编码愉快，愿您的文件永远保持同步！

Jinja是什么？可以用在做什么？

Thu, 08 May 2025 22:00:28 +0800

Jinaja的基础概念

Jinja 是一款强大且流行的 Python 模板引擎。简单来说，它允许你创建包含占位符和逻辑的文本文件（模板），然后用动态数据填充这些占位符，最终生成新的文本文件。

Jinja 可以用来做什么？

Jinja 的用途非常广泛，尤其在以下领域：

Web 开发 (最常见的用途):
- 动态生成 HTML 页面: 这是 Jinja 最核心的应用。你可以创建 HTML 模板，其中包含动态内容（如用户信息、文章列表、产品详情等）的占位符。当用户请求页面时，Jinja 会将从数据库或其他来源获取的数据填充到模板中，生成最终的 HTML 页面发送给用户的浏览器。许多流行的 Python Web 框架，如 Flask 和 Django (虽然 Django 有自己的模板系统，但也可以集成 Jinja)，都广泛使用 Jinja。
- 生成其他 Web 内容: 除了 HTML，Jinja 也可以用来生成 XML、JSON、CSS、JavaScript 等任何基于文本的 Web 内容。
配置文件生成:
- 当需要为不同的环境（开发、测试、生产）或不同的服务器生成相似但略有差异的配置文件时，Jinja 非常有用。你可以创建一个基础的配置文件模板，然后根据具体需求传入不同的变量来生成特定的配置文件。
代码生成:
- 在某些情况下，Jinja 可以用来根据元数据或模型定义自动生成重复性的代码片段，甚至是整个代码文件。
邮件模板:
- 生成个性化的邮件内容。你可以创建邮件模板，其中包含问候语、用户特定的信息等占位符，然后用实际数据填充，发送给不同的用户。
报告生成:
- 生成基于文本的报告，例如 CSV 文件或纯文本报告，其中包含动态数据。
任何需要基于模板生成文本的场景:
- 只要你需要根据一些动态数据来生成结构化的文本输出，Jinja 都可以派上用场。

Jinja 的核心特性与优势：

易于理解和使用: Jinja 的语法设计简洁明了，借鉴了 Django 模板语言和 Python 的一些特性，对于有 Python 基础的开发者来说很容易上手。
功能强大:
- 变量插值: 使用 {{ variable_name }} 将变量的值插入到模板中。
- 控制结构: 支持 {% for %} 循环、{% if %} 条件判断等逻辑控制，使得模板具有动态行为。
- 模板继承 (Template Inheritance): 允许你创建一个基础模板 (layout)，其中包含网站的通用结构（如页眉、页脚、导航栏），然后其他子模板可以继承这个基础模板并覆盖或扩展特定的区块 (blocks)。这极大地提高了代码的复用性和可维护性。
- 宏 (Macros): 类似于编程语言中的函数，允许你定义可重用的模板片段，可以接收参数并返回值。
- 过滤器 (Filters): 使用管道符 | 对变量进行处理和转换，例如格式化日期 ({{ my_date|dateformat('%Y-%m-%d') }}), 首字母大写 ({{ my_string|capitalize }}), 计算长度 ({{ my_list|length }}) 等。Jinja 内置了许多有用的过滤器，也支持自定义过滤器。
- 测试 (Tests): 用于检查变量的特定状态，例如判断一个变量是否已定义 ({% if name is defined %}), 是否为偶数 ({% if number is even %}) 等。
- 包含 (Includes): 使用 {% include 'template_name.html' %} 可以将一个模板的内容包含到另一个模板中，方便组织和重用小的模板片段。
- 转义 (Escaping): 默认情况下，Jinja 会对输出的变量进行 HTML 转义，以防止跨站脚本攻击 (XSS)。这是非常重要的安全特性。你可以使用 |safe 过滤器来显式禁止转义（但要确保内容是安全的）。
- 沙箱执行 (Sandboxed Execution): Jinja 模板在受限的环境中执行，可以防止模板作者执行不安全的操作。
高性能: Jinja 会将模板编译成 Python 字节码来执行，从而获得较好的性能。
可扩展性: 允许开发者自定义过滤器、测试、全局函数和扩展。
广泛的社区支持和文档: 作为一款流行的工具，Jinja 拥有庞大的用户社区和完善的官方文档，遇到问题时很容易找到解决方案。

Jinja 模板基本语法示例：

<!DOCTYPE html>
<html>
<head>
 <title>{{ page_title }}</title>
</head>
<body>
 <h1>Hello, {{ username|capitalize }}!</h1>

 {% if items %}
 <h2>Here are your items:</h2>
 <ul>
 {% for item in items %}
 <li>{{ item }}</li>
 {% endfor %}
 </ul>
 {% else %}
 <p>You have no items.</p>
 {% endif %}

 {% include 'footer.html' %}
</body>
</html>

在这个例子中：

{{ page_title }} 和 {{ username|capitalize }} 是变量插值，|capitalize 是一个过滤器。
{% if items %} … {% else %} … {% endif %} 是条件判断。
{% for item in items %} … {% endfor %} 是循环。
{% include 'footer.html' %} 包含了另一个模板文件。

总结来说，Jinja 是一个功能丰富、灵活且高效的 Python 模板引擎，它通过将数据与模板分离，使得动态生成文本内容（尤其是 HTML）变得更加简单、清晰和可维护。它是 Python Web 开发中不可或缺的工具之一，并且在其他需要文本生成的场景中也表现出色。

注入依赖进一步解释

Tue, 01 Apr 2025 15:29:05 +0800

在 FastAPI 中，依赖注入（Dependency Injection, DI） 是一种设计模式，用于将某些功能或服务（称为“依赖”）动态地注入到应用程序的组件中，而不是在代码中硬编码这些依赖。它是 FastAPI 的核心特性之一，能够帮助开发者编写更模块化、可测试和可维护的代码。

下面我将详细解释 FastAPI 中的依赖注入概念，包括它的定义、工作原理、用法和实际示例。

1. 依赖注入是什么？

依赖注入的核心思想是：将一个函数或类需要的外部资源（依赖）交给调用者来提供，而不是在函数或类内部直接创建这些资源。在 FastAPI 中，依赖通常是：

数据库连接
用户认证逻辑
配置参数
外部 API 调用
其他需要在多个路由中复用的功能

FastAPI 通过其内置的依赖注入系统，允许你在路由函数或其他依赖中声明这些依赖，然后由框架自动解析并注入。

2. FastAPI 中依赖注入的工作原理

FastAPI 的依赖注入系统基于 Python 的类型注解和函数参数。它的工作方式如下：

你定义一个依赖（可以是一个函数或类）。
在路由函数或其他地方通过参数声明对这个依赖的使用。
FastAPI 在运行时解析这些依赖，按照声明的顺序调用它们，并将结果注入到需要的地方。

依赖可以是同步函数、异步函数，甚至是类实例。FastAPI 还支持依赖的嵌套（一个依赖可以依赖另一个依赖）。

3. 如何使用依赖注入

FastAPI 提供了 Depends 函数来声明依赖。以下是基本用法：

示例 1：简单的依赖注入

from fastapi import FastAPI, Depends

app = FastAPI()

# 定义一个依赖函数
def common_parameters(q: str = None, skip: int = 0, limit: int = 10):
 return {"q": q, "skip": skip, "limit": limit}

# 在路由中使用依赖
@app.get("/items/")
def read_items(commons: dict = Depends(common_parameters)):
 return {"message": "Hello Items!", "params": commons}

依赖函数：common_parameters 是一个普通的 Python 函数，返回一个字典。
Depends：在路由函数中通过 Depends(common_parameters) 声明依赖，FastAPI 会调用这个函数并将结果注入到 commons 参数。

请求：访问 http://localhost:8000/items/?q=foo&skip=5&limit=20，返回：

{"message": "Hello Items!", "params": {"q": "foo", "skip": 5, "limit": 20}}

示例 2：异步依赖

如果你的依赖涉及异步操作（比如数据库查询），可以用 async：

from fastapi import FastAPI, Depends

app = FastAPI()

async def get_db():
 db = "Database connection established" # 模拟数据库连接
 try:
 yield db
 finally:
 print("Database connection closed")

@app.get("/users/")
async def read_users(db: str = Depends(get_db)):
 return {"db": db}

async def：依赖函数是异步的。
yield：支持上下文管理，finally 块在依赖使用完毕后执行（例如关闭数据库连接）。
请求：访问 http://localhost:8000/users/，返回：
```
{"db": "Database connection established"}
```

示例 3：类作为依赖

你也可以使用类来定义依赖：

from fastapi import FastAPI, Depends

app = FastAPI()

class CommonQueryParams:
 def __init__(self, q: str = None, skip: int = 0, limit: int = 10):
 self.q = q
 self.skip = skip
 self.limit = limit

@app.get("/items/")
def read_items(commons: CommonQueryParams = Depends(CommonQueryParams)):
 return {"q": commons.q, "skip": commons.skip, "limit": commons.limit}

类依赖：CommonQueryParams 是一个类，FastAPI 会自动实例化它并注入。
请求：访问 http://localhost:8000/items/?q=test&skip=2，返回：
```
{"q": "test", "skip": 2, "limit": 10}
```

4. 依赖注入的优点

复用性：同一个依赖可以在多个路由中复用，避免重复代码。例如，验证用户身份的逻辑可以写成依赖，在所有需要认证的路由中使用。
模块化：依赖独立于路由逻辑，便于修改和替换。
测试性：通过注入假的依赖（mock），可以轻松测试路由逻辑。
自动文档：依赖的参数会自动出现在 FastAPI 的 Swagger UI 中，增强 API 可读性。

5. 高级用法

嵌套依赖

依赖可以依赖其他依赖：

from fastapi import FastAPI, Depends

app = FastAPI()

def query(q: str = None):
 return {"q": q}

def pagination(skip: int = 0, limit: int = 10, query_params: dict = Depends(query)):
 return {"skip": skip, "limit": limit, "query": query_params["q"]}

@app.get("/items/")
def read_items(params: dict = Depends(pagination)):
 return params

pagination 依赖 query：FastAPI 会先解析 query，然后将结果注入到 pagination 中。
请求：http://localhost:8000/items/?q=foo&skip=5，返回：
```
{"skip": 5, "limit": 10, "query": "foo"}
```

全局依赖

可以在整个应用或特定路径上添加依赖：

from fastapi import FastAPI, Depends

app = FastAPI(dependencies=[Depends(common_parameters)])

@app.get("/items/")
def read_items():
 return {"message": "Items with global dependency"}

dependencies 参数：所有路由都会强制使用这个依赖。

你可以查看文档 /docs

6. 实际应用场景

用户认证：检查请求头中的 token，确保用户已登录。
数据库连接：为每个请求提供数据库会话，并在请求结束后关闭。
配置加载：注入应用程序的配置参数。
日志记录：在每个请求中注入日志对象。

例如，一个简单的认证依赖：

from fastapi import FastAPI, Depends, HTTPException

app = FastAPI()

def get_current_user(token: str = None):
 if token != "valid-token":
 raise HTTPException(status_code=401, detail="Invalid token")
 return {"username": "user1"}

@app.get("/profile/")
def read_profile(user: dict = Depends(get_current_user)):
 return user

总结

FastAPI 的依赖注入是一种强大而灵活的工具，通过 Depends 和类型注解实现。它允许你将公共逻辑抽取出来，动态注入到路由中，既提高了代码复用性，又保持了清晰的结构。无论是简单的参数处理还是复杂的数据库操作，依赖注入都能很好地适应。

fastapi使用教程

Tue, 01 Apr 2025 14:43:52 +0800

代码地址

https://github.com/zata-zhangtao/Zata-code/tree/main/07-html%2Bfastapi/fastapi/tutorial/phase1-fastapi%E7%AE%80%E5%8D%95%E7%9A%84%E5%BC%80%E5%A7%8B

教程大纲

环境准备
基础示例：Hello World
路径参数和查询参数
请求体和数据验证
异步编程
依赖注入
中间件和错误处理
部署 FastAPI 应用

1. 环境准备

安装必要的工具 (我在教程中安装的python=3.11)

确保您已安装 Python 3.7 或更高版本，然后使用以下命令安装 FastAPI 和 Uvicorn（一个 ASGI 服务器，用于运行 FastAPI）：

uv add fastapi "uvicorn[standard]"

可选：安装其他依赖

pydantic：用于数据验证（FastAPI 已包含）。
httpx：用于测试 API（可选）。

2. 基础示例：Hello World

让我们从一个简单的 FastAPI 应用开始。

代码示例

创建一个文件 main.py：

from fastapi import FastAPI

app = FastAPI()

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

# 然后你就可以使用 uvicorn 01-simple_start:app --reload 去开启服务了

# 当然你也可以直接运行，使用下面的方式去开启服务

if __name__ == "__main__":
 import uvicorn
 uvicorn.run(app, host="0.0.0.0", port=8000)

运行应用

在终端中运行以下命令：

uvicorn main:app --reload

main 是文件名（不带 .py）。
app 是 FastAPI 实例的名称。
--reload 会在代码更改时自动重启服务器，适合开发环境。

测试

打开浏览器访问 http://127.0.0.1:8000，您将看到：

{"message": "Hello World"}

FastAPI 还提供交互式文档，访问 http://127.0.0.1:8000/docs 查看 Swagger UI。

![Swagger UI](images/index/index-2.png)

3. 路径参数和查询参数

路径参数

路径参数通过 URL 传递，例如 /items/1。

@app.get("/items/{item_id}")
def read_item(item_id: int):
 return {"item_id": item_id}

访问 http://127.0.0.1:8000/items/42，返回：

{"item_id": 42}

查询参数

查询参数通过 ?key=value 形式传递。

@app.get("/items/")
def read_items(skip: int = 0, limit: int = 10):
 return {"skip": skip, "limit": limit}

访问 http://127.0.0.1:8000/items/?skip=5&limit=20，返回：

{"skip": 5, "limit": 20}

4. 请求体和数据验证

FastAPI 使用 Pydantic 模型来处理请求体和数据验证。

定义 Pydantic 模型

from pydantic import BaseModel

class Item(BaseModel):
 name: str
 price: float
 is_offer: bool = None # 可选字段，默认 None

处理 POST 请求

@app.post("/items/")
def create_item(item: Item):
 return {"name": item.name, "price": item.price, "is_offer": item.is_offer}

测试

使用 Swagger UI (/docs) 或以下 curl 命令：

curl -X POST "http://localhost:8000/items/" -H "Content-Type: application/json" -d "{\"name\": \"Book\", \"price\": 9.99, \"is_offer\": true}"

{"name": "Book", "price": 9.99, "is_offer": true}

如果数据格式错误（例如 price 传入字符串），FastAPI 会自动返回验证错误。

5. 异步编程

FastAPI 支持异步函数，使用 async def，适合 I/O 密集型操作（如数据库查询）。

异步示例

import asyncio

@app.get("/async/")
async def read_async():
 await asyncio.sleep(1) # 模拟异步操作
 return {"message": "This is async"}

访问 http://127.0.0.1:8000/async/，1 秒后返回结果。

![异步编程](images/index/index-7.png)

6. 依赖注入

依赖注入允许您在多个路由中复用代码，例如身份验证或数据库连接。

定义依赖

from fastapi import Depends

async def common_parameters(q: str | None = None, skip: int = 0):
 return {"q": q, "skip": skip}

@app.get("/depends/")
async def read_depends(commons: dict = Depends(common_parameters)):
 return commons

访问 http://127.0.0.1:8000/depends/?q=test&skip=10，返回：

{"q": "test", "skip": 10}

我感觉注入依赖是一个比较难理解的内容，可以再看下面的内容增强理解

7. 中间件和错误处理

添加中间件

中间件用于处理请求和响应的全局逻辑，例如日志记录。

@app.middleware("http")
async def add_custom_header(request, call_next):
 response = await call_next(request)
 response.headers["X-Custom"] = "Example"
 return response

自定义异常处理

from fastapi import HTTPException

@app.get("/error/")
async def read_error():
 raise HTTPException(status_code=404, detail="Item not found")

访问 http://127.0.0.1:8000/error/，返回：

{"detail": "Item not found"}

8. 部署 FastAPI 应用

使用 Uvicorn 生产环境

去掉 --reload，指定主机和端口：

uvicorn main:app --host 0.0.0.0 --port 8000

使用 Gunicorn + Uvicorn

安装 Gunicorn：

pip install gunicorn

运行：

gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app

-w 4 表示 4 个工作进程。

Docker 部署

创建一个 Dockerfile：

FROM python:3.9
WORKDIR /app
COPY . /app
RUN pip install fastapi uvicorn
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

构建并运行：

docker build -t fastapi-app .
docker run -p 8000:8000 fastapi-app

9. HTTPS/SSL 配置

在生产环境中，使用 HTTPS 是保护数据传输安全的重要措施。FastAPI 可以通过 Uvicorn 轻松配置 SSL 证书。

SSL 证书准备

首先，您需要准备 SSL 证书文件：

证书文件 (.pem 或 .crt)：包含公钥和证书信息
私钥文件 (.key)：用于加密通信

配置 HTTPS 的 FastAPI 应用

import os
from pathlib import Path
from fastapi import FastAPI

app = FastAPI(title="Simple FastAPI App with SSL", version="1.0.0")

@app.get("/")
async def root():
 return {"message": "Hello World", "ssl_enabled": True}

@app.get("/health")
async def health_check():
 return {"status": "healthy", "secure": True}

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
 return {"item_id": item_id, "q": q}

@app.get("/ssl-info")
async def ssl_info():
 cert_path = Path("resources/SSLcertificate/test.aizata.com.pem")
 key_path = Path("resources/SSLcertificate/test.aizata.com.key")

 return {
 "certificate_exists": cert_path.exists(),
 "private_key_exists": key_path.exists(),
 "certificate_path": str(cert_path),
 "key_path": str(key_path)
 }

if __name__ == "__main__":
 import uvicorn
 port = 8443

 # SSL certificate paths
 ssl_cert_path = "resources/SSLcertificate/test.aizata.com.pem"
 ssl_key_path = "resources/SSLcertificate/test.aizata.com.key"

 # Check if SSL files exist
 if os.path.exists(ssl_cert_path) and os.path.exists(ssl_key_path):
 print(f"Starting server with SSL/HTTPS on port {port}...")
 uvicorn.run(
 app,
 host="0.0.0.0",
 port=port,
 ssl_certfile=ssl_cert_path,
 ssl_keyfile=ssl_key_path
 )
 else:
 print(f"SSL certificates not found, starting HTTP server on port {port}...")
 uvicorn.run(app, host="0.0.0.0", port=port)

命令行启动 HTTPS 服务

您也可以直接通过命令行启动 HTTPS 服务：

uvicorn main:app --host 0.0.0.0 --port 8443 --ssl-certfile resources/SSLcertificate/test.aizata.com.pem --ssl-keyfile resources/SSLcertificate/test.aizata.com.key

测试 HTTPS 连接

启动服务后，访问 https://localhost:8443 或 https://your-domain.com:8443：

浏览器会显示安全连接标识
API 文档地址：https://localhost:8443/docs
健康检查：https://localhost:8443/health
SSL 信息：https://localhost:8443/ssl-info

自签名证书（开发环境）

对于开发环境，您可以生成自签名证书：

# 生成私钥
openssl genrsa -out private.key 2048

# 生成自签名证书
openssl req -new -x509 -key private.key -out certificate.pem -days 365 -subj "/C=CN/ST=State/L=City/O=Organization/CN=localhost"

生产环境建议

使用受信任的 CA 证书：从 Let’s Encrypt 或其他 CA 获取免费证书
证书自动续期：设置自动续期脚本
反向代理：使用 Nginx 或 Apache 作为反向代理处理 SSL
安全头部：添加安全相关的 HTTP 头部

使用 Nginx 反向代理（推荐）

在生产环境中，通常使用 Nginx 处理 SSL 终止：

server {
 listen 443 ssl;
 server_name your-domain.com;

 ssl_certificate /path/to/certificate.pem;
 ssl_certificate_key /path/to/private.key;

 location / {
 proxy_pass http://127.0.0.1:8000;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 }
}

这样，FastAPI 应用运行在 HTTP 端口 8000，Nginx 处理 HTTPS 并代理请求到 FastAPI。

fastapi-前提知识

Tue, 01 Apr 2025 14:37:44 +0800

1. Python 基础

FastAPI 是基于 Python 的框架，因此你需要熟悉 Python 3.6+ 的基本语法和特性。以下是关键点：

1.1 变量和数据类型

Python 使用动态类型，无需显式声明变量类型。
常用数据类型：整数（int）、浮点数（float）、字符串（str）、列表（list）、字典（dict）。

name = "Alice" # 字符串
age = 25 # 整数
scores = [90, 85, 88] # 列表
person = {"name": "Alice", "age": 25} # 字典

1.2 函数和类型注解

定义函数使用 def 关键字。
FastAPI 大量使用 Python 的类型注解（Type Hints），需要熟悉。

# 基本函数
def add(a, b):
 return a + b

# 带类型注解的函数
def add_with_types(a: int, b: int) -> int:
 return a + b

print(add(3, 5)) # 输出: 8
print(add_with_types(3, 5)) # 输出: 8

类型注解是 FastAPI 的核心特性，用于参数验证和自动生成文档。

1.3 类和对象

FastAPI 使用 Pydantic 模型（基于类），需要理解面向对象编程基础。

class Person:
 def __init__(self, name: str, age: int):
 self.name = name
 self.age = age

 def greet(self) -> str:
 return f"Hello, I'm {self.name}!"

alice = Person("Alice", 25)
print(alice.greet()) # 输出: Hello, I'm Alice!

1.4 模块和包

Python 使用 import 引入模块，FastAPI 是一个外部包。
安装包使用 pip，例如：pip install fastapi。

import math
print(math.sqrt(16)) # 输出: 4.0

1.5 异常处理

使用 try 和 except 处理错误，FastAPI 中常用。

try:
 result = 10 / 0
except ZeroDivisionError:
 print("不能除以零！")

2. 异步编程基础

FastAPI 是异步框架，基于 Python 的 asyncio 库。你需要理解异步编程的核心概念：async 和 await。

2.1 同步 vs 异步

同步：代码按顺序执行，等待每个操作完成。
异步：可以在等待某个操作（如网络请求）时执行其他任务。

# 同步示例
def sync_task():
 print("任务开始")
 print("任务结束")

sync_task()

# 异步示例
import asyncio

async def async_task():
 print("任务开始")
 await asyncio.sleep(1) # 模拟耗时操作
 print("任务结束")

asyncio.run(async_task())

2.2 `async` 和 `await`

async def 定义异步函数。
await 用于暂停执行，等待异步操作完成。

import asyncio

async def say_hello():
 print("Hello")
 await asyncio.sleep(2) # 等待 2 秒
 print("World")

# 运行异步函数
asyncio.run(say_hello())

2.3 多个异步任务

使用 asyncio.gather 并发运行多个异步任务。

import asyncio

async def task1():
 await asyncio.sleep(1)
 print("任务 1 完成")

async def task2():
 await asyncio.sleep(2)
 print("任务 2 完成")

async def main():
 await asyncio.gather(task1(), task2())

asyncio.run(main())
# 输出:
# 任务 1 完成 (1秒后)
# 任务 2 完成 (2秒后)

FastAPI 使用异步来处理多个请求，提高性能，因此理解这些概念至关重要。

3. HTTP 协议基础

FastAPI 是一个 Web 框架，基于 HTTP 协议。你需要了解 HTTP 的基本工作原理。

3.1 HTTP 请求和响应

请求：客户端（如浏览器）向服务器发送的操作。
响应：服务器返回的数据。

请求示例（伪代码）：

GET /hello HTTP/1.1
Host: example.com

响应示例：

HTTP/1.1 200 OK
Content-Type: text/plain

Hello, World!

3.2 HTTP 方法

GET：获取数据。
POST：提交数据。
PUT：更新数据。
DELETE：删除数据。

FastAPI 使用这些方法定义路由，例如：

from fastapi import FastAPI

app = FastAPI()

@app.get("/hello")
def read_hello():
 return {"message": "Hello, World!"}

3.3 状态码

200 OK：成功。
404 Not Found：资源未找到。
500 Internal Server Error：服务器错误。

FastAPI 会自动返回状态码，你也可以手动指定：

@app.get("/items/{item_id}")
def read_item(item_id: int):
 if item_id > 0:
 return {"item_id": item_id}
 raise HTTPException(status_code=404, detail="Item not found")

3.4 请求头和正文

请求头：元数据，如 Content-Type。
请求正文：发送的数据，通常是 JSON。

FastAPI 使用 Pydantic 处理请求正文：

from pydantic import BaseModel

class Item(BaseModel):
 name: str
 price: float

@app.post("/items/")
def create_item(item: Item):
 return {"name": item.name, "price": item.price}

3.5 URL 和查询参数

URL 路径：如 /items/123。
查询参数：如 /items/?q=test。

FastAPI 示例：

@app.get("/items/")
def read_items(q: str = None):
 return {"query": q}

4. 实践练习

结合以上知识，尝试以下练习：

编写一个带类型注解的函数，计算两个数的和。
创建一个异步函数，模拟等待 3 秒后返回结果。
安装 FastAPI 和 Uvicorn，运行一个简单的 GET 路由，返回 JSON 数据。

示例答案：

# 练习 1
def sum_numbers(a: int, b: int) -> int:
 return a + b

# 练习 2
import asyncio
async def wait_and_return():
 await asyncio.sleep(3)
 return "等待结束"

# 练习 3
from fastapi import FastAPI
app = FastAPI()

@app.get("/")
async def root():
 return {"message": "Hello, FastAPI!"}
# 运行：uvicorn main:app --reload

Flask使用教程

Mon, 10 Mar 2025 16:00:15 +0800

Flak的基础语法和使用

1. 安装 Flask

首先，你需要安装 Flask。确保你已经安装了 Python（推荐使用 Python 3.7 或以上版本）。可以通过 pip 安装 Flask：

pip install flask

安装完成后，你可以在 Python 解释器中验证是否成功安装：

import flask
print(flask.__version__)

如果没有报错并输出版本号，说明 Flask 已成功安装。

2. 创建一个简单的 Flask 应用

让我们创建一个最基本的 Flask 应用。以下是一个简单的示例代码，保存为 app.py：

from flask import Flask

# 创建 Flask 应用实例
app = Flask(__name__)

# 定义路由和视图函数
@app.route('/')
def home():
 return '欢迎使用 Flask!'

# 运行应用
if __name__ == '__main__':
 app.run(debug=True)

代码解释：

Flask(__name__)：创建一个 Flask 应用实例，__name__ 是 Python 的内置变量，表示当前模块的名称。
@app.route('/')：定义一个路由，当用户访问根路径（/）时，触发下面的函数。
app.run(debug=True)：启动 Flask 内置的开发服务器，debug=True 启用调试模式，方便开发时查看错误。

运行应用：

在终端中进入文件所在目录，运行以下命令：

python app.py

然后在浏览器中访问 http://127.0.0.1:5000/，你会看到页面显示“欢迎使用 Flask!”。

3. 添加更多路由

Flask 允许你定义多个路由。例如，我们可以添加一个新的路由 /hello：

from flask import Flask

app = Flask(__name__)

@app.route('/')
def home():
 return '欢迎使用 Flask!'

@app.route('/hello')
def hello():
 return '你好，世界!'

if __name__ == '__main__':
 app.run(debug=True)

访问 http://127.0.0.1:5000/hello，你会看到“你好，世界!”。

动态路由：

你还可以通过路由参数传递动态值，例如：

@app.route('/user/<name>')
def user(name):
 return f'你好，{name}!'

访问 http://127.0.0.1:5000/user/Alice，页面会显示“你好，Alice!”。

from flask import Flask, request

app = Flask(__name__)

@app.route('/greet')
def greet():
 # Access query string parameters using request.args
 name = request.args.get('name', 'Guest') # Default to 'Guest' if 'name' is not provided
 return f'你好，{name}!'

if __name__ == '__main__':
 app.run(debug=True)

在浏览器中访问 URL_ADDRESS在浏览器中访问 http://127.0.0.1:5000/greet?name=Alice`，页面会显示“你好，Alice!”。

4. 使用模板渲染 HTML

直接返回字符串不适合复杂的页面。Flask 支持使用 Jinja2 模板引擎来渲染 HTML 文件。首先，创建一个 templates 文件夹，并在其中创建一个文件 index.html：

<!DOCTYPE html>
<html>
<head>
 <title>Flask 教程</title>
</head>
<body>
 <h1>欢迎，{{ name }}!</h1>
</body>
</html>

然后修改 app.py 使用模板：

from flask import Flask, render_template

app = Flask(__name__)

@app.route('/user/<name>')
def user(name):
 return render_template('index.html', name=name)

if __name__ == '__main__':
 app.run(debug=True)

render_template：渲染模板并传入变量（这里是 name）。

文件结构：

项目文件夹/
├── app.py
└── templates/
 └── index.html

访问 http://127.0.0.1:5000/user/Bob，页面会显示“欢迎，Bob!”。

5. 使用过滤器

Jinja2 提供了许多内置过滤器，用于在模板中处理变量。你也可以自定义过滤器。以下是一些常见的用法。

修改 `app.py`

我们将传递更多数据到模板中，以便展示过滤器的效果：

from flask import Flask, render_template

app = Flask(__name__)

@app.route('/user/<name>')
def user(name):
 user_data = {
 'name': name,
 'age': 25,
 'bio': '这是一个简单的介绍。',
 'join_date': '2023-10-15'
 }
 return render_template('index.html', **user_data)

if __name__ == '__main__':
 app.run(debug=True)

修改 `templates/index.html`

添加一些过滤器示例：

<!DOCTYPE html>
<html>
<head>
 <title>Flask 教程</title>
</head>
<body>
 <h1>欢迎，{{ name | upper }}!</h1>
 <p>年龄: {{ age | default('未知') }}</p>
 <p>简介: {{ bio | truncate(10) }}</p>
 <p>加入日期: {{ join_date | replace('-', '/') }}</p>
 <p>名字长度: {{ name | length }}</p>
</body>
</html>

过滤器说明

| upper：将字符串转换为大写，例如“alice”变成“ALICE”。
| default('未知')：如果变量未定义或为空，则显示默认值“未知”。
| truncate(10)：截断字符串到指定长度（这里是 10 个字符），超出部分用省略号表示。
| replace('-', '/')：将字符串中的“-”替换为“/”，例如“2023-10-15”变成“2023/10/15”。
| length：返回变量的长度，例如“Alice”的长度是 5。

运行结果

访问 http://127.0.0.1:5000/user/Alice，页面显示：

欢迎，ALICE!
年龄: 25
简介: 这是一个简...
加入日期: 2023/10/15
名字长度: 5

自定义过滤器

如果内置过滤器不够用，可以定义自己的过滤器。例如，我们添加一个反转字符串的过滤器：

修改 app.py：

from flask import Flask, render_template

app = Flask(__name__)

# 自定义过滤器：反转字符串
@app.template_filter('reverse')
def reverse_filter(s):
 return s[::-1]

@app.route('/user/<name>')
def user(name):
 user_data = {
 'name': name,
 'age': 25,
 'bio': '这是一个简单的介绍。',
 'join_date': '2023-10-15'
 }
 return render_template('index.html', **user_data)

if __name__ == '__main__':
 app.run(debug=True)

修改 index.html，添加自定义过滤器：

<!DOCTYPE html>
<html>
<head>
 <title>Flask 教程</title>
</head>
<body>
 <h1>欢迎，{{ name | upper }}!</h1>
 <p>年龄: {{ age | default('未知') }}</p>
 <p>简介: {{ bio | truncate(10) }}</p>
 <p>加入日期: {{ join_date | replace('-', '/') }}</p>
 <p>名字长度: {{ name | length }}</p>
 <p>反转名字: {{ name | reverse }}</p>
</body>
</html>

访问 http://127.0.0.1:5000/user/Alice，页面会多一行：

反转名字: ecilA

@app.template_filter('reverse')：注册一个名为 reverse 的自定义过滤器。
s[::-1]：Python 切片语法，反转字符串。

6. 处理表单数据

Flask 可以轻松处理用户提交的表单数据。以下是一个简单的例子，包含 GET 和 POST 请求：

修改 `templates/index.html`：

<!DOCTYPE html>
<html>
<head>
 <title>Flask 表单</title>
</head>
<body>
 <h1>提交你的名字</h1>
 <form method="POST">
 <input type="text" name="username">
 <input type="submit" value="提交">
 </form>
 {% if name %}
 <h2>你好，{{ name }}!</h2>
 {% endif %}
</body>
</html>

修改 `app.py`：

from flask import Flask, render_template, request

app = Flask(__name__)

@app.route('/', methods=['GET', 'POST'])
def home():
 name = None
 if request.method == 'POST':
 name = request.form['username']
 return render_template('index.html', name=name)

if __name__ == '__main__':
 app.run(debug=True)

request：从 Flask 中导入，用于获取表单数据。
methods=['GET', 'POST']：允许该路由处理 GET 和 POST 请求。
request.form['username']：获取表单中 name="username" 的输入值。

运行后，访问 http://127.0.0.1:5000/，输入名字并提交，会显示欢迎信息。

7. 使用控制语句

Jinja2 模板支持控制语句，主要包括条件语句（if、elif、else）和循环语句（for）。这些语句可以根据传入的数据动态渲染内容。

修改 `app.py`

我们将传递一个包含用户列表的数据，并添加一些条件判断的变量：

from flask import Flask, render_template

app = Flask(__name__)

# 自定义过滤器：反转字符串
@app.template_filter('reverse')
def reverse_filter(s):
 return s[::-1]

@app.route('/users')
def users():
 user_list = [
 {'name': 'Alice', 'age': 25, 'active': True},
 {'name': 'Bob', 'age': 30, 'active': False},
 {'name': 'Charlie', 'age': 15, 'active': True}
 ]
 show_details = True # 用于条件语句
 return render_template('users.html', users=user_list, show_details=show_details)

if __name__ == '__main__':
 app.run(debug=True)

创建 `templates/users.html`

在 templates 文件夹中新建 users.html，添加条件语句和循环语句：

<!DOCTYPE html>
<html>
<head>
 <title>用户列表</title>
</head>
<body>
 <h1>用户列表</h1>

 <!-- 循环语句：遍历用户列表 -->
 <ul>
 {% for user in users %}
 <li>
 {{ user.name }} (年龄: {{ user.age }})
 <!-- 条件语句：根据 active 显示状态 -->
 {% if user.active %}
 <span style="color: green;">活跃</span>
 {% else %}
 <span style="color: red;">不活跃</span>
 {% endif %}
 </li>
 {% endfor %}
 </ul>

 <!-- 条件语句：是否显示详细信息 -->
 {% if show_details %}
 <h2>额外信息</h2>
 <p>总用户数: {{ users | length }}</p>
 <p>第一个用户: {{ users[0].name | upper }}</p>
 {% else %}
 <p>详细信息已隐藏</p>
 {% endif %}

 <!-- 多条件示例 -->
 {% for user in users %}
 {% if user.age >= 18 and user.active %}
 <p>{{ user.name }} 是成年活跃用户</p>
 {% elif user.age < 18 %}
 <p>{{ user.name }} 是未成年</p>
 {% endif %}
 {% endfor %}
</body>
</html>

控制语句说明

循环语句 for：
- {% for user in users %}：遍历 users 列表，user 是每次循环的单个元素。
- 在 <ul> 中动态生成每个用户的 <li> 标签。
条件语句 if：
- {% if user.active %}：检查用户是否活跃，显示不同颜色状态。
- {% if show_details %}：根据 show_details 的值决定是否显示额外信息。
- {% elif %} 和 {% else %}：支持多条件分支。
结合过滤器：
- {{ users | length }}：计算用户列表长度。
- {{ users[0].name | upper }}：将第一个用户的名字转换为大写。

运行结果

访问 http://127.0.0.1:5000/users，页面显示：

用户列表
- Alice (年龄: 25) 活跃
- Bob (年龄: 30) 不活跃
- Charlie (年龄: 15) 活跃

额外信息
总用户数: 3
第一个用户: ALICE

Alice 是成年活跃用户
Charlie 是未成年

修改条件

如果你将 app.py 中的 show_details = True 改为 False，则“额外信息”部分会变为：

详细信息已隐藏

嵌套控制语句

你还可以在循环中嵌套条件语句，或者在条件中嵌套循环。例如，添加一个嵌套示例到 users.html：

<!-- 嵌套示例：列出活跃用户 -->
<h2>活跃用户</h2>
<ul>
{% for user in users if user.active %}
 <li>{{ user.name }}</li>
{% endfor %}
</ul>

这会输出：

活跃用户
- Alice
- Charlie

{% for user in users if user.active %}：直接在 for 循环中过滤，只遍历活跃用户。

8. 添加静态文件

Flask 支持静态文件（如 CSS、图片等）。创建一个 static 文件夹，并在其中添加 style.css：

h1 {
 color: blue;
}

修改 index.html 引入样式：

<!DOCTYPE html>
<html>
<head>
 <title>Flask 表单</title>
 <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}">
</head>
<body>
 <h1>提交你的名字</h1>
 <form method="POST">
 <input type="text" name="username">
 <input type="submit" value="提交">
 </form>
 {% if name %}
 <h2>你好，{{ name }}!</h2>
 {% endif %}
</body>
</html>

url_for('static', filename='style.css')：生成静态文件的 URL。

文件结构：

项目文件夹/
├── app.py
├── static/
│ └── style.css
└── templates/
 └── index.html

重新运行应用，标题会变成蓝色。

9. 模板继承

模板继承通过定义一个基础模板（包含通用结构），然后在子模板中扩展特定部分，非常适合构建具有一致布局的网站。

创建基础模板 `templates/base.html`

在 templates 文件夹中创建 base.html：

<!DOCTYPE html>
<html>
<head>
 <title>{% block title %}默认标题{% endblock %}</title>
 <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}">
</head>
<body>
 <header>
 <h1>欢迎使用 Flask</h1>
 <nav>
 <a href="{{ url_for('home') }}">首页</a> |
 <a href="{{ url_for('users') }}">用户列表</a>
 </nav>
 </header>

 <!-- 内容块，子模板可以覆盖 -->
 {% block content %}
 <p>这是默认内容</p>
 {% endblock %}

 <footer>
 <p>&copy; 2025 Flask 教程</p>
 </footer>
</body>
</html>

{% block title %} 和 {% block content %}：定义可被子模板覆盖的块。
{{ url_for('xxx') }}：动态生成路由链接。
静态文件 style.css 已在上文提到，确保 static 文件夹中有该文件。

修改 `app.py`

添加首页路由，并更新用户路由以使用模板继承：

from flask import Flask, render_template

app = Flask(__name__)

# 自定义过滤器：反转字符串
@app.template_filter('reverse')
def reverse_filter(s):
 return s[::-1]

@app.route('/')
def home():
 return render_template('home.html')

@app.route('/users')
def users():
 user_list = [
 {'name': 'Alice', 'age': 25, 'active': True},
 {'name': 'Bob', 'age': 30, 'active': False},
 {'name': 'Charlie', 'age': 15, 'active': True}
 ]
 show_details = True
 return render_template('users.html', users=user_list, show_details=show_details)

if __name__ == '__main__':
 app.run(debug=True)

创建子模板 `templates/home.html`

继承 base.html，覆盖特定块：

{% extends "base.html" %}

{% block title %}首页{% endblock %}

{% block content %}
 <h2>欢迎来到首页</h2>
 <p>这是一个简单的 Flask 应用示例。</p>
{% endblock %}

{% extends "base.html" %}：指定继承的基础模板。
{% block title %}：覆盖标题块。
{% block content %}：覆盖内容块。

修改 `templates/users.html` 使用继承

将之前的 users.html 修改为继承 base.html：

{% extends "base.html" %}

{% block title %}用户列表{% endblock %}

{% block content %}
 <h2>用户列表</h2>
 <ul>
 {% for user in users %}
 <li>
 {{ user.name }} (年龄: {{ user.age }})
 {% if user.active %}
 <span style="color: green;">活跃</span>
 {% else %}
 <span style="color: red;">不活跃</span>
 {% endif %}
 </li>
 {% endfor %}
 </ul>

 {% if show_details %}
 <h3>额外信息</h3>
 <p>总用户数: {{ users | length }}</p>
 <p>第一个用户: {{ users[0].name | upper }}</p>
 {% else %}
 <p>详细信息已隐藏</p>
 {% endif %}

 <h3>活跃用户</h3>
 <ul>
 {% for user in users if user.active %}
 <li>{{ user.name }}</li>
 {% endfor %}
 </ul>
{% endblock %}

文件结构

项目文件夹/
├── app.py
├── static/
│ └── style.css
└── templates/
 ├── base.html
 ├── home.html
 └── users.html

运行结果

访问 http://127.0.0.1:5000/（首页）：

欢迎使用 Flask
首页 | 用户列表
欢迎来到首页
这是一个简单的 Flask 应用示例。
© 2025 Flask 教程

访问 http://127.0.0.1:5000/users（用户列表）：

欢迎使用 Flask
首页 | 用户列表
用户列表
- Alice (年龄: 25) 活跃
- Bob (年龄: 30) 不活跃
- Charlie (年龄: 15) 活跃
额外信息
总用户数: 3
第一个用户: ALICE
活跃用户
- Alice
- Charlie
© 2025 Flask 教程

扩展说明

保留父模板内容：如果想在子模板中保留父模板的块内容，可以使用 {{ super() }}。例如：
```
{% block content %}
 {{ super() }}
 <p>追加的内容</p>
{% endblock %}
```
这会在子模板中保留 base.html 的默认内容 <p>这是默认内容</p> 并追加新内容。
多级继承：你可以让一个子模板再被其他模板继承，形成多级结构。

10. 部署（简单说明）

开发完成后，你可能想将应用部署到服务器上。常用方法：

使用 gunicorn（生产环境 Web 服务器）：

pip install gunicorn
gunicorn --bind 0.0.0.0:8000 app:app

配合 Nginx 或其他反向代理服务器。

在本地调试时，app.run() 就足够了。

总结

这是一个 Flask 的基础教程，涵盖了安装、路由、模板、表单和静态文件的使用。你可以根据需求扩展功能，例如连接数据库（如 Flask-SQLAlchemy）、添加用户认证等。如果需要更深入的讲解或特定功能，请告诉我！

Flask操作数据库

下面是一个使用 Flask 操作数据库的教程，基于 Python 的 Flask 框架和常见的 SQLite 数据库（也可以扩展到其他数据库如 MySQL 或 PostgreSQL）。我会逐步介绍如何设置 Flask 应用、连接数据库、执行 CRUD 操作（创建、读取、更新、删除），并提供示例代码。

Flask 操作数据库教程

Flask 是一个轻量级的 Python Web 框架，结合数据库操作可以快速构建动态网站或 API。本教程将使用 SQLite 作为数据库，因为它是 Python 内置的，无需额外安装。你也可以根据需要替换为其他数据库。

环境准备

在开始之前，确保你已安装 Python，并准备好以下工具：

安装 Flask
在终端运行以下命令：
```
pip install flask
```
数据库工具
本教程使用 SQLite，无需额外安装。如果想使用 MySQL 或 PostgreSQL，可以安装对应驱动，例如 pip install pymysql 或 pip install psycopg2。

项目结构
创建一个项目文件夹，结构如下：

flask_db_demo/
├── app.py
├── templates/
│ └── index.html
└── database.db (稍后生成)

步骤 1：初始化 Flask 和数据库

创建一个简单的 Flask 应用并连接 SQLite 数据库。

代码示例：app.py

from flask import Flask, render_template, request, redirect, url_for
import sqlite3

app = Flask(__name__)

# 数据库连接函数
def get_db_connection():
 conn = sqlite3.connect('database.db')
 conn.row_factory = sqlite3.Row # 返回字典形式的行数据
 return conn

# 初始化数据库和表
def init_db():
 conn = get_db_connection()
 conn.execute('''CREATE TABLE IF NOT EXISTS users (
 id INTEGER PRIMARY KEY AUTOINCREMENT,
 name TEXT NOT NULL,
 email TEXT NOT NULL UNIQUE)''')
 conn.commit()
 conn.close()

# 在应用启动时初始化数据库
init_db()

@app.route('/')
def index():
 return "Hello, Flask with Database!"

if __name__ == '__main__':
 app.run(debug=True)

说明

数据库连接：get_db_connection() 函数建立与 SQLite 文件 database.db 的连接。
表创建：init_db() 函数创建一个名为 users 的表，包含 id、name 和 email 字段。
启动应用：运行 python app.py，访问 http://127.0.0.1:5000/ 查看结果。

步骤 2：实现 CRUD 操作

接下来，我们将实现数据库的增删改查功能，并通过网页展示。

1. 创建（Create）数据

添加一个路由，允许用户通过表单提交数据。

修改 app.py

@app.route('/add', methods=['GET', 'POST'])
def add_user():
 if request.method == 'POST':
 name = request.form['name']
 email = request.form['email']
 conn = get_db_connection()
 conn.execute('INSERT INTO users (name, email) VALUES (?, ?)', (name, email))
 conn.commit()
 conn.close()
 return redirect(url_for('index'))
 return render_template('add_user.html')

创建 templates/add_user.html

<!DOCTYPE html>
<html>
<head>
 <title>Add User</title>
</head>
<body>
 <h2>Add New User</h2>
 <form method="POST">
 <label>Name:</label><input type="text" name="name" required><br>
 <label>Email:</label><input type="email" name="email" required><br>
 <button type="submit">Add</button>
 </form>
 <a href="{{ url_for('index') }}">Back to Home</a>
</body>
</html>

2. 读取（Read）数据

修改首页路由，显示所有用户信息。

修改 app.py

@app.route('/')
def index():
 conn = get_db_connection()
 users = conn.execute('SELECT * FROM users').fetchall()
 conn.close()
 return render_template('index.html', users=users)

创建 templates/index.html

<!DOCTYPE html>
<html>
<head>
 <title>User List</title>
</head>
<body>
 <h2>User List</h2>
 <table border="1">
 <tr>
 <th>ID</th>
 <th>Name</th>
 <th>Email</th>
 <th>Actions</th>
 </tr>
 {% for user in users %}
 <tr>
 <td>{{ user['id'] }}</td>
 <td>{{ user['name'] }}</td>
 <td>{{ user['email'] }}</td>
 <td>
 <a href="{{ url_for('edit_user', id=user['id']) }}">Edit</a> |
 <a href="{{ url_for('delete_user', id=user['id']) }}" onclick="return confirm('Are you sure?')">Delete</a>
 </td>
 </tr>
 {% endfor %}
 </table>
 <br>
 <a href="{{ url_for('add_user') }}">Add New User</a>
</body>
</html>

3. 更新（Update）数据

添加编辑用户的路由和页面。

修改 app.py

@app.route('/edit/<int:id>', methods=['GET', 'POST'])
def edit_user(id):
 conn = get_db_connection()
 if request.method == 'POST':
 name = request.form['name']
 email = request.form['email']
 conn.execute('UPDATE users SET name = ?, email = ? WHERE id = ?', (name, email, id))
 conn.commit()
 conn.close()
 return redirect(url_for('index'))
 user = conn.execute('SELECT * FROM users WHERE id = ?', (id,)).fetchone()
 conn.close()
 return render_template('edit_user.html', user=user)

创建 templates/edit_user.html

<!DOCTYPE html>
<html>
<head>
 <title>Edit User</title>
</head>
<body>
 <h2>Edit User</h2>
 <form method="POST">
 <label>Name:</label><input type="text" name="name" value="{{ user['name'] }}" required><br>
 <label>Email:</label><input type="email" name="email" value="{{ user['email'] }}" required><br>
 <button type="submit">Update</button>
 </form>
 <a href="{{ url_for('index') }}">Back to Home</a>
</body>
</html>

4. 删除（Delete）数据

添加删除用户的路由。

修改 app.py

@app.route('/delete/<int:id>')
def delete_user(id):
 conn = get_db_connection()
 conn.execute('DELETE FROM users WHERE id = ?', (id,))
 conn.commit()
 conn.close()
 return redirect(url_for('index'))

步骤 3：运行和测试

保存所有文件。
在终端运行 python app.py。
打开浏览器访问 http://127.0.0.1:5000/。
测试添加、编辑、删除用户功能。

注意事项

安全性
- 当前示例未处理表单验证和 SQL 注入防护（已使用参数化查询避免基本注入）。
- 生产环境中建议使用 Flask-WTF 和 CSRF 保护。
扩展性
- 可替换 SQLite 为 MySQL 或 PostgreSQL，只需修改连接字符串和驱动。
- 推荐使用 ORM（如 SQLAlchemy）简化数据库操作。
调试
- app.run(debug=True) 仅用于开发，生产环境需使用 WSGI 服务器（如 Gunicorn）。

总结

通过本教程，你学会了如何在 Flask 中连接 SQLite 数据库并实现基本的 CRUD 操作。你可以根据需求扩展功能，例如添加用户认证、分页或 API 接口。如果有疑问，欢迎提问！

gradio教程

Wed, 05 Mar 2025 21:52:18 +0800

Gradio 教程

代码地址：

https://github.com/zata-zhangtao/Zata-AI-Agent-code/blob/main/04-gradio/01-start/01-sample_example.ipynb

参考文档

https://www.gradio.app/guides/the-interface-class

1. 安装 Gradio

首先，确保你有 Python 环境，然后在终端运行以下命令安装 Gradio：

pip install gradio

2. 基本示例

让我们从一个简单的例子开始：创建一个界面，用户输入名字，程序返回问候语。

import gradio as gr
#输入文本处理程序
def greet(name):
 return "Hello " + name + "!"
#接口创建函数
#fn设置处理函数，inputs设置输入接口组件，outputs设置输出接口组件
#fn,inputs,outputs都是必填函数
demo = gr.Interface(fn=greet, inputs="text", outputs="text")
demo.launch()

运行代码后，Gradio 会生成一个本地 Web 界面（通常在 http://127.0.0.1:7860），你可以在浏览器中输入名字并看到结果。

3. 界面参数说明

fn: 要展示的核心函数（例如 greet）。
inputs: 输入组件类型（如 "text", "image", "audio" 等）。
outputs: 输出组件类型（如 "text", "image", "label" 等）。
launch(): 启动界面，可以通过参数设置是否公开。

常用输入和输出类型

"text": 文本框
"image": 图片上传或显示
"audio": 音频输入或输出
"video": 视频输入或输出
"dataframe": 数据表格

4. 进阶示例：处理多种输入

假设我们想创建一个函数，接收名字和年龄，返回个性化的消息：

import gradio as gr

def greet(name, age):
 return f"你好，{name}！今年你{age}岁了，真棒！"

interface = gr.Interface(
 fn=greet,
 inputs=["text", "number"], # 多个输入
 outputs="text",
 title="个性化问候生成器", # 添加标题
 description="输入你的名字和年龄，获取问候语！" # 添加描述
)

interface.launch()

运行后，你会看到一个有两个输入框的界面：一个文本框输入名字，一个数字框输入年龄。

5. 处理图片输入和输出

假设我们要创建一个简单的图像处理函数，将上传的图片转为灰度：

import gradio as gr
from PIL import Image

def grayscale_image(image):
 return image.convert("L") # 转换为灰度图

interface = gr.Interface(
 fn=grayscale_image,
 inputs="image", # 上传图片
 outputs="image", # 输出图片
 title="图片灰度转换器"
)

interface.launch()

用户可以上传图片，界面会返回灰度版本。

6. 自定义界面布局

如果需要更复杂的布局，可以使用 gr.Blocks：

import gradio as gr

def greet(name):
 return f"你好，{name}！"

with gr.Blocks(title="自定义问候界面") as demo:
 gr.Markdown("## 输入你的名字")
 name_input = gr.Textbox(label="名字")
 output = gr.Textbox(label="结果")
 button = gr.Button("提交")
 button.click(fn=greet, inputs=name_input, outputs=output)

demo.launch()

Blocks 允许你自由组合组件，比如按钮、文本框、图片等。

7. 分享到公网

默认情况下，Gradio 界面只运行在本地。如果你想分享给别人，可以设置 share=True：

interface.launch(share=True)

这会生成一个临时的公共链接（有效期通常为 72 小时）。

8. 常见问题

如何调试？ 添加 debug=True 参数到 launch()，会在终端显示详细日志：
```
interface.launch(debug=True)
```
如何保存用户输入？ 在函数中处理输入并保存到文件或数据库。
如何运行在特定端口？ 使用 server_port 参数：
```
interface.launch(server_port=8080)
```

9. 完整示例：带图片和文本的复杂界面

import gradio as gr
from PIL import Image

def process_input(name, image):
 grayscale_img = image.convert("L")
 message = f"你好，{name}！这是你的灰度图片。"
 return grayscale_img, message

interface = gr.Interface(
 fn=process_input,
 inputs=["text", "image"],
 outputs=["image", "text"],
 title="图片和文本处理",
 description="输入名字并上传图片，获取灰度图和问候语。"
)

interface.launch(share=True)

10. 带有tab的界面

import gradio as gr

# 定义两个简单的函数，分别用于不同的选项卡
def greet(name):
 return f"你好，{name}！"

def farewell(name):
 return f"再见，{name}！"

# 使用 Blocks 创建界面
with gr.Blocks() as demo:
 # 创建 Tabs 容器
 with gr.Tabs():
 # 第一个选项卡：打招呼
 with gr.TabItem("打招呼"):
 name_input_1 = gr.Textbox(label="输入你的名字")
 greet_output = gr.Textbox(label="输出")
 greet_button = gr.Button("提交")
 greet_button.click(fn=greet, inputs=name_input_1, outputs=greet_output)

 # 第二个选项卡：告别
 with gr.TabItem("告别"):
 name_input_2 = gr.Textbox(label="输入你的名字")
 farewell_output = gr.Textbox(label="输出")
 farewell_button = gr.Button("提交")
 farewell_button.click(fn=farewell, inputs=name_input_2, outputs=farewell_output)

# 启动应用
demo.launch()

gr.Blocks()：创建一个灵活的界面容器。
gr.Tabs()：定义一个选项卡组。
gr.TabItem(“标签名”)：定义单个选项卡，标签名会显示在界面上。
每个选项卡内可以放置输入组件（如 Textbox）、输出组件和事件（如按钮点击）。
运行这段代码后，你会看到一个带有“打招呼”和“告别”两个选项卡的界面。点击每个选项卡，可以切换到对应的功能。

11. 使用 gr.TabbedInterface 组合多个界面

import gradio as gr

# 定义两个函数
def greet(name):
 return f"你好，{name}！"

def farewell(name):
 return f"再见，{name}！"

# 创建两个独立的 Interface
interface1 = gr.Interface(fn=greet, inputs="text", outputs="text", title="打招呼")
interface2 = gr.Interface(fn=farewell, inputs="text", outputs="text", title="告别")

# 使用 TabbedInterface 组合
demo = gr.TabbedInterface(
 [interface1, interface2], # 接口列表
 ["打招呼", "告别"] # 选项卡名称列表
)

# 启动应用
demo.launch()

代码说明：

gr.TabbedInterface 接受两个主要参数：
第一个参数是一个 Interface 对象列表。
第二个参数是选项卡名称的列表，与 Interface 顺序对应。
这种方法适合快速组合已有的界面，但灵活性不如 Blocks。

12. 高级布局：结合 Row 和 Column

import gradio as gr
import numpy as np

# 定义翻转文本和图片的函数
def flip_text(text):
 return text[::-1]

def flip_image(image):
 return np.fliplr(image)

# 使用 Blocks 创建界面
with gr.Blocks(title="翻转工具") as demo:
 gr.Markdown("### 欢迎使用翻转工具")
 with gr.Tabs():
 # 文本翻转选项卡
 with gr.TabItem("翻转文本"):
 with gr.Row():
 text_input = gr.Textbox(label="输入文本")
 text_output = gr.Textbox(label="输出文本")
 text_button = gr.Button("翻转")
 text_button.click(fn=flip_text, inputs=text_input, outputs=text_output)

 # 图片翻转选项卡
 with gr.TabItem("翻转图片"):
 with gr.Row():
 image_input = gr.Image(label="上传图片", type="numpy")
 image_output = gr.Image(label="输出图片")
 image_button = gr.Button("翻转")
 image_button.click(fn=flip_image, inputs=image_input, outputs=image_output)

# 启动应用
demo.launch()

代码说明：

gr.Row()：将组件水平排列。
gr.Column()：将组件垂直排列（默认布局）。
这个例子展示了一个文本翻转和图片翻转的工具，每个功能在单独的选项卡中。

总结

Gradio 的核心优势在于简单易用，适合快速展示和测试功能。你可以根据需求扩展功能，比如集成机器学习模型、处理音频视频、或设计复杂布局。如果有具体问题或想深入某个功能，可以告诉我，我再详细讲解！

FASTAPI使用相关问题

Fri, 28 Feb 2025 00:00:00 +0000

☆ FASTAPI

运行环境和安装

安装python环境
安装fastapi
安装uvicron

开始使用fastapi

01.第一个简单程序

from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
 return {"Hello": "World"}

运行：运行有两种方式方法1. 在文件路径下运行命令（这种方式在windows中容易出问题，如果显示无法找到命令，可以使用第二种方法）

uvicron main:app --reload
# 其中，main指的是文件名main.py, app指的是文件中定义的对象app，--reload指的是代码更改后重新加载的开发模式

方法2. 代码中导入uvicron包，

from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
 return {"Hello": "World"}
if __name__ == "__main__":
 uvicorn.run(app = "main:app", host="0.0.0.0", port=8000，reload = True)

fastapi部署

使用uvicorn部署（一般在开发场景下）

step1: 安装uvicorn

pip install uvicorn

step2：运行uvicorn

有两种方式，一直是直接用代码：

if __name__ == '__main__':
 uvicorn.run("main:app", host="0.0.0.0", port=8000, log_level="info")

另一种是在控制台

uvicorn main:app --reload --host 0.0.0.0 --port 8000

step3 : 设置后台运行

但是本身uvicorn是不带后台运行功能的，因此你需要结合其他工具实现后台运行功能，我常用的是Tmux，这里不做说明参考：阮一峰 Tmux使用教程

【推荐使用下面的gunicorn部署】

使用gunicorn部署

step1：

使用gunicorn最好在你服务的main.py同级目录下面新建一个gunicorn.py文件 | 参考： https://blog.csdn.net/asd54090/article/details/137783835

# gunicorn.py
import os

# 设置守护进程
daemon=True
# 监听内网端口8000
bind='0.0.0.0:8000'
# 设置进程文件目录
pidfile='./gunicorn.pid'
chdir='./' # 工作目录
# 工作模式
worker_class='uvicorn.workers.UvicornWorker'
# 并行工作进程数 核心数*2+1个
workers=3 #multiprocessing.cpu_count()+1
# 指定每个工作者的线程数
threads=2
# 设置最大并发量
worker_connections = 2000
loglevel='debug' # 错误日志的日志级别
access_log_format = '%(t)s %(p)s %(h)s "%(r)s" %(s)s %(L)s %(b)s %(f)s" "%(a)s"'
# 设置访问日志和错误信息日志路径
log_dir = "./log"
if not os.path.exists(log_dir):
 os.makedirs(log_dir)
accesslog = "./log/gunicorn_access.log"
errorlog = "./log/gunicorn_error.log"

step2：

然后要在服务器下面安装相应的库(非常注意的一点是，step3用gunicorn启动的时候，如果有错误它控制台是不报错的，所以强烈建议先用uvicorn能启动之后再用gunicorn)

pip install fastapi
pip install gunicorn

step3:

gunicorn main:app -c gunicorn.py

可以看见，这里运行之后啥也不报

当然也可以不用配置文件，直接执行下面命令启动应用

gunicorn main:app -b 0.0.0.0:8000 -w 4 -k uvicorn.workers.UvicornWorker --daemon

step4：如果想要关闭项目需要通过Kill的方式，可以看上面的参考链接

配置Nginx代理访问(可选）

详情可见 nginx使用修改nginx的设置：

server {
 listen 80; # ngixn的主页端口
 # listen 443 ssl;
 server_name XXX.com; # 填你自己的域名或者IP
 access_log /var/log/nginx/access.log;
 location / {
 proxy_pass http://127.0.0.1:8000; # 你的服务端口
 proxy_set_header Host $host;
 proxy_set_header X-Forwarded-For
 $proxy_add_x_forwarded_for;
 }
 }

然后运行nginx -s reload 或者 service nginx restart

Web 开发 on 扎塔-Zata

Celery

Celery 详细使用教程：从入门到实践

什么是 Celery？

核心概念

第一部分：快速入门 (Hello, World)

第二部分：与 Web 框架集成 (以 FastAPI 为例)

第三部分：定时任务 (Celery Beat)

第四部分：监控与最佳实践

其他知识点

shared_task与app.task的区别

celery调用任务的方式

如何调整同时执行的任务数

Building asynchronous APIs for handling long-term tasks and dynamic resources

教程：构建处理长时间任务和动态资源的异步 API

核心问题

解决方案：异步任务队列

技术栈

第 1 步：环境准备

第 2 步：项目结构

第 3 步：编写 Worker 和任务 (tasks.py)

第 4 步：编写 API 接口 (main.py)

第 5 步：运行系统（关键）

第 6 步：测试

总结

jwt-with-fastapi

JWT (JSON Web Token) 深入解析与实战教程

目录

1. JWT 是什么？

JWT 的结构

Header (头部)

Payload (负载)

Signature (签名)

JWT 的工作流程

2. 基础用法：JWT 的生成与验证

Node.js 示例 (jsonwebtoken)

Python 示例 (PyJWT)

3. FastAPI 实战：构建 JWT 认证系统

第一步：单用户的 FastAPI 认证

第二步：实现多用户注册与数据库认证

4. 安全性最佳实践

fastapi-docs_swagger_UI-openAPI

步骤 1：环境准备

步骤 2：创建一个简单的 FastAPI 应用

步骤 3：运行应用并查看文档

步骤 4：通过示例深入理解

步骤 5：再次运行并交互

总结

ALL-fastapi

目录

flutter_tutorial

从零开始的fultter之路

Refine: 当 API 即界面，CRUD 不再是体力活

问题：后台管理界面，为什么总是重复劳动？

Refine 是什么？

核心概念 1：Headless（无头）

Refine 提供什么？

你用什么 UI？

核心概念 2：Resource（资源）

资源的定义

这段配置做了什么？

核心概念 3：Data Provider（数据提供者）

Data Provider 的接口

这个接口的意义

内置的 Data Provider

核心概念 4：Auth Provider（认证提供者）

使用方式

核心概念 5：Inferencer（自动生成 CRUD 页面）

使用方式

Inferencer 做了什么？

生成的代码示例

实战：用 Refine + shadcn/ui 搭建后台

步骤 1：创建项目

步骤 2：配置 Data Provider

步骤 3：配置资源

步骤 4：用 Inferencer 生成页面

步骤 5：美化 UI

对比：Refine vs 传统开发

Refine 的局限

1. 后端 API 要规范

第 3 步：编写 Worker 和任务 (`tasks.py`)

第 4 步：编写 API 接口 (`main.py`)

1. `<FileInfo[]>` - TypeScript类型注解中的`[]`

2. `([])` - 初始值中的`[]`

streamlit连接数据库并且增删改查