OpenClaw 功能强大，但在内存占用和启动速度方面存在挑战。针对这些问题，主打极速、轻量的 Rust 重构版 ZeroClaw 应运而生。

整篇文章的目标只有一个：

让你看完后，能在本地服务器上部署 ZeroClaw，体验 7.8MB 内存、秒启动的 AI 助手，并在实际项目中发挥它的价值。

一、ZeroClaw 是什么？为什么值得一试？

1.1 性能对比

如果把它和 OpenClaw 放在一起对比，ZeroClaw 可以说是个妥妥的性能怪兽。

根据官方基准测试（macOS arm64，2026年2月，针对 0.8GHz 边缘硬件标准化），ZeroClaw 的表现如下：

这个项目用 Rust 编写，ZeroClaw 运行时内存不到 5MB、启动时间小于 10ms、二进制体积仅约 3.4MB，支持在树莓派或者低配云主机上部署 Agent。

从性能角度看，它具备几个关键特性：

• 🏎️ 极致精简：< 5MB 内存占用，比 OpenClaw 核心小 99%


• 💰 成本极低：高效到可以在 $10 硬件上运行，比 Mac mini 便宜 98%


• ⚡ 闪电启动：启动速度提升 400 倍，在 < 10ms 内启动（即使在 0.6GHz 核心上也能在 1 秒内启动）


• 🌍 真正可移植：跨 ARM、x86 和 RISC-V 的单一自包含二进制文件

1.2 适用场景

场景 A：资源受限环境

如果你需要在树莓派、低配云主机（1GB 内存）上部署 AI Agent，ZeroClaw 无疑是最优选。

它那极低的资源占用，能大幅减少服务器资源的浪费。用省下的内存，来运行多一点其他业务，不香吗？

场景 B：自动化流水线与服务器运维

如果需求是每天定时抓取博客、监控服务器日志，或者在配置较低的云服务器上部署，ZeroClaw 的轻量特性让它成为理想选择。

场景 C：批量部署

对于需要在一人企业中批量部署多个 AI Agent 的场景，ZeroClaw 的小体积和低资源占用，让批量部署成为可能。

1.3 架构设计：一切都是 Trait

ZeroClaw 的核心设计理念是：每个子系统都是一个 trait，只需更改配置即可交换实现，无需修改代码。

ZeroClaw 架构图，展示各个子系统（Provider、Channel、Memory、Tools 等）的 trait 设计和可插拔架构

核心子系统：

这种设计让 ZeroClaw 具有极强的可扩展性和灵活性，你可以根据实际需求替换任何组件，而无需修改核心代码。

二、开始前你需要准备好的东西

动手之前，先确认这几样已经就绪。

三、手把手安装：10 分钟搞定 ZeroClaw

3.1 环境准备：安装 Rust

由于 ZeroClaw 是纯 Rust 项目，如果我们电脑里还没安装 Rust，需要先把 Rust 环境准备好。

Linux / macOS：一条命令安装

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

source $HOME/.cargo/env



rustc --version

cargo --version

看到版本号后，说明 Rust 安装成功，可以继续后面的 ZeroClaw 编译和安装步骤了。

开始安装

安装成功

Windows：通过 WSL 安装（推荐 ZeroClaw 场景）

ZeroClaw 更适合跑在 Linux 环境里，所以在 Windows 下，推荐先装好 WSL（如 Ubuntu），然后在 WSL 终端里执行和 Linux 一样的命令，看到版本号后，就可以在这个 WSL 环境中继续后面的 ZeroClaw 编译和安装步骤了。

3.2 编译安装 ZeroClaw

环境装好后，我们把代码拉下来，就能开始编译安装了。

这里推荐 Release 版，因为它体积最小、速度最快：

# 克隆仓库

git clone https://github.com/zeroclaw-labs/zeroclaw.git

cd zeroclaw



# 编译 Release 版本（优化后的版本）

cargo build --release



# 安装到系统路径

cargo install --path . --force

⚠️ 编译时间较长

首次编译 Rust 项目可能需要 5 - 10 分钟，取决于你的机器性能。这是正常现象，因为 Rust 需要编译所有依赖。

解决：耐心等待，或者使用 cargo build --release -j $(nproc) 来并行编译加速。

编译完成后，验证安装：

zeroclaw --version

如果显示版本号，说明安装成功。

3.3 基础配置：交互式向导

这个项目不仅安装快，配置也极其人性化。交互式向导:

zeroclaw onboard --interactive

这是一个完整的 7 步交互式向导，会引导你完成所有配置。

配置向导会引导你完成：

配置完成后，配置文件通常保存在：

• Linux/macOS：~/.zeroclaw/config.toml


• Windows（WSL）：~/.zeroclaw/config.toml

⚠️ 渠道白名单配置

如果配置后收到消息但 ZeroClaw 没有响应，可能是白名单配置问题。

解决：

1. 查看日志，找到发送者的身份标识


2. 运行 zeroclaw onboard --channels-only 重新配置白名单


3. 或者临时使用 "*" 允许所有（仅用于测试）

3.4 启动和使用 ZeroClaw

启动守护进程

如果你希望 ZeroClaw 长期运行，处理定时任务和自动响应：

zeroclaw daemon

此时，它就在后台默默运行了。

我们可以随时用以下命令查看它的状态：

zeroclaw status

其他实用命令：

# 运行系统诊断

zeroclaw doctor



# 检查渠道健康状态

zeroclaw channel doctor



# 查看集成信息（如 Telegram）

zeroclaw integrations info Telegram



# 管理后台服务

zeroclaw service install

zeroclaw service status

现在，你就拥有一个 24 小时待命的全功能 AI 助手。

四、配置文件详解：定制你的 ZeroClaw

配置文件位置：~/.zeroclaw/config.toml（由 onboard 命令创建）

4.1 基础配置

# API 密钥（支持加密存储）

api_key = "sk-..."

default_provider = "openrouter"  # 默认 provider

default_model = "anthropic/claude-sonnet-4-20250514"  # 默认模型

default_temperature = 0.7  # 默认温度参数

4.2 内存配置

[memory]

backend = "sqlite"              # "sqlite", "markdown", "none"

auto_save = true                # 自动保存

embedding_provider = "openai"   # "openai", "noop"

vector_weight = 0.7             # 向量搜索权重

keyword_weight = 0.3            # 关键词搜索权重

4.3 Gateway 配置

[gateway]

require_pairing = true          # 首次连接需要配对码

allow_public_bind = false       # 拒绝 0.0.0.0 绑定（无隧道时）

4.4 自主性配置

[autonomy]

level = "supervised"            # "readonly", "supervised", "full"

workspace_only = true           # 限制在工作区范围内

allowed_commands = ["git", "npm", "cargo", "ls", "cat", "grep"]  # 允许的命令

forbidden_paths = ["/etc", "/root", "/proc", "/sys", "~/.ssh", "~/.gnupg", "~/.aws"]  # 禁止访问的路径

4.5 其他配置

[runtime]

kind = "native"                # 当前仅支持 "native"



[heartbeat]

enabled = false                 # 是否启用定时任务

interval_minutes = 30           # 任务执行间隔



[tunnel]

provider = "none"               # "none", "cloudflare", "tailscale", "ngrok", "custom"



[secrets]

encrypt = true                  # API 密钥加密存储



[browser]

enabled = false                 # 是否启用浏览器工具

allowed_domains = ["docs.rs"]   # 允许访问的域名



[composio]

enabled = false                 # 是否启用 Composio（1000+ OAuth 应用）

📌 提示：配置文件支持热重载，修改后重启服务即可生效。建议使用 zeroclaw doctor 检查配置是否正确。

五、OpenClaw 和 ZeroClaw，怎么选？

简单说，可以按场景来选：

• 如果你更关注交互体验、家庭中枢、可视化能力，已经在用 Mac mini 等环境做本地 AI 中控，那继续用 OpenClaw 会更顺手。


• 如果你更在意资源占用、启动速度、批量部署，尤其是打算在树莓派、低配云服务器上长期跑 Agent，那 ZeroClaw 会是更合适的选择。

很多时候，两者是可以并存的：用 OpenClaw 做「大中枢」，用 ZeroClaw 覆盖「边缘节点」和自动化脚本，各自发挥所长。

六、相关资源

GitHub 项目地址：

github.com/zeroclaw-la…

官方文档：

• GitHub README

我的其他相关文章：

• 《GitHub 10万+ Star 的 Moltbot 部署实战：手把手带你在本地跑起来这只「龙虾」🦞》


• 《一步步带你手搓专属 IM APP，控制本地 OpenClaw，破局国内 IM 封闭受限》


• 《手把手教你安装 OpenClaw 并接入飞书，让本地 AI 在飞书里听你指挥》


• 《手把手带你实现：飞书 → OpenClaw → Cursor Agent → OpenClaw → 飞书》

结语：ZeroClaw 作为 OpenClaw 的 Rust 重构版，在保持核心功能的同时，大幅降低了资源占用和启动时间。对于需要在资源受限环境或批量部署场景下使用 AI Agent 的朋友来说，ZeroClaw 无疑是一个值得尝试的选择。

希望本文能够帮助你顺利完成部署，在实际项目中发挥 ZeroClaw 的价值。如果在部署过程中遇到问题，欢迎查阅官方文档或相关社区获取帮助。

引言:从通用助手到领域专家

想象一下这些场景:

场景 1: 重复的上下文说明

你: "帮我分析这个 BigQuery 数据,记住要排除测试账户,使用 user_metrics 表..."

Claude: "好的,我来分析..."



[第二天]

你: "再帮我分析一次销售数据,还是那个表,记得排除测试账户..."

Claude: "好的,我来分析..."  # 😓 又要重复一遍

场景 2: 领域知识的重复传授

你: "帮我处理这个 PDF 表单,PDF 的表单字段结构是..."

Claude: "明白了"



[一周后]

你: "再处理一个 PDF 表单..."

Claude: "请告诉我 PDF 表单的结构"  # 😓 忘记了

场景 3: 工作流程的不一致

你: "生成 API 文档,记得包含请求示例、响应格式、错误码..."

Claude: "好的" # ✅ 这次做得很好



[下次]

你: "再生成一份 API 文档"

Claude: [生成的文档] # ❌ 这次忘记了错误码部分

这些问题的根源是:每次对话都是全新的开始,Claude 无法记住你的领域知识、偏好和工作流程。

💡 Skills 系统的价值

Skills 就是解决这个问题的方案——它让你能够:

本文核心内容:

"把你反复向 Claude 解释的偏好、流程、领域知识打包成 Skills,让 AI 成为你的领域专家"

一、什么是 Skills?

1.1 核心概念

Agent Skills(智能体技能)是一种模块化的能力扩展系统,它为 Claude 提供了:

• 领域专业知识: 如 PDF 处理技巧、数据库 schema、业务规则


• 工作流程: 如代码审查流程、文档生成流程、数据分析流程


• 最佳实践: 如命名规范、代码风格、错误处理模式

1.2 Skills vs 普通 Prompt

类比理解:

• 普通 Prompt 像是每次都要"现场培训"新员工


• Skills 像是给员工提供"岗位手册",需要时自己查阅

1.3 Skills 遵循开放标准

Claude Code Skills 基于 Agent Skills 开放标准,这意味着:

• ✅ 标准化格式,跨 AI 工具兼容


• ✅ 社区生态,可以使用他人创建的 Skills


• ✅ 长期支持,不会因产品升级而失效

Claude Code 在标准基础上扩展了:

• 🔧 调用控制机制


• 🤖 子代理执行能力


• 📥 动态上下文注入

二、Skills 工作原理:渐进式披露架构

2.1 为什么需要渐进式披露?

问题:如果把所有 Skills 的详细内容都加载到上下文中会怎样?

假设你有 10 个 Skills,每个包含 5000 tokens 的详细指导...

总共: 50,000 tokens



但你可能只需要使用其中 1-2 个 Skill!

浪费: 40,000+ tokens(80% 的上下文窗口!)

解决方案:渐进式披露——只加载需要的内容,按需展开详细信息。

2.2 三级加载机制

第一级:元数据(Metadata)- 始终加载

---

name: pdf-processing

description: Extract text and tables from PDF files, fill forms, merge documents.

             Use when working with PDF files or when the user mentions PDFs, forms,

             or document extraction.

---

• 加载时机: Claude 启动时


• Token 消耗: 每个 Skill 约 100 tokens


• 作用: 让 Claude 知道有哪些 Skills 可用,以及何时触发

关键字段解析:

• name: Skill 标识符(小写字母、数字、连字符)


• description: 功能说明 + 触发场景(最重要的字段!)

⚠️ 重要: description 是 Skill 触发的关键。Claude 根据用户请求与 description 的匹配度决定是否加载该 Skill。

第二级:指令(Instructions)- 触发时加载

# PDF Processing



## Quick start



Use pdfplumber to extract text from PDFs:



\`\`\`python

import pdfplumber



with pdfplumber.open("document.pdf") as pdf:

    text = pdf.pages[0].extract_text()

\`\`\`



For advanced form filling, see [FORMS.md](FORMS.md).

• 加载时机: 当用户请求匹配 Skill 描述时


• Token 消耗: 通常少于 5k tokens


• 作用: 提供具体的操作指导和工作流程

第三级:资源和代码(Resources & Code)- 按需访问

pdf-skill/

├── SKILL.md          # 主指令文件(第二级)

├── FORMS.md          # 表单填写指南(按需读取)

├── REFERENCE.md      # 详细 API 参考(按需读取)

└── scripts/

    └── fill_form.py  # 工具脚本(执行时不加载代码)

• 加载时机: 仅当 SKILL.md 中引用时


• Token 消耗: 脚本执行时只有输出占用 tokens


• 作用: 提供专业参考材料和可执行工具

2.3 实例演示:从触发到加载

场景: 用户请求"帮我提取 PDF 中的文本"

┌─────────────────────────────────────────┐

│ 步骤 1: Claude 检查所有 Skill 的元数据 │

└─────────────────────────────────────────┘

              ↓

┌─────────────────────────────────────────┐

│ 匹配到 pdf-processing Skill             │

│ description 包含 "Extract text from PDF"│

└─────────────────────────────────────────┘

              ↓

┌─────────────────────────────────────────┐

│ 步骤 2: 加载 SKILL.md 的指令内容        │

│ (~3k tokens)                            │

└─────────────────────────────────────────┘

              ↓

┌─────────────────────────────────────────┐

│ 步骤 3: Claude 发现需要表单填写         │

│ 读取 FORMS.md (~2k tokens)              │

└─────────────────────────────────────────┘

              ↓

┌─────────────────────────────────────────┐

│ 总 Token 消耗: 约 5k tokens             │

│ 其他 9 个 Skills: 0 tokens(未加载)      │

└─────────────────────────────────────────┘

对比无渐进式披露:

❌ 传统方式: 10 个 Skills × 5k = 50k tokens

✅ 渐进式披露: 只加载 1 个 Skill = 5k tokens

节省: 45k tokens (90% 的上下文!)

三、Skills 的文件结构

3.1 最小化 Skill

最简单的 Skill 只需要一个文件:

my-skill/

└── SKILL.md          # 唯一必需的文件

SKILL.md 示例:

---

name: code-review-checklist

description: Provides a code review checklist for pull requests. Use when reviewing code or when the user asks for code review guidelines.

---



# Code Review Checklist



When reviewing code, check:



1. **Functionality**: Does the code do what it's supposed to?

2. **Readability**: Is the code easy to understand?

3. **Tests**: Are there appropriate tests?

4. **Performance**: Are there any obvious performance issues?

5. **Security**: Are there any security vulnerabilities?



For each item, provide specific feedback with examples.

3.2 完整 Skill 结构

对于复杂的 Skills,可以组织成多文件结构:

pdf-processing-skill/

├── SKILL.md              # 核心指令(必需)

├── FORMS.md              # 表单填写详细指南

├── REFERENCE.md          # PDF 库 API 参考

├── EXAMPLES.md           # 常见用例示例

└── scripts/

    ├── analyze_form.py   # 分析表单工具

    ├── fill_form.py      # 填写表单工具

    └── validate.py       # 验证输出工具

3.3 YAML Frontmatter 规范

必填字段:

---

name: skill-name              # 必填

description: Skill description # 必填

---

字段要求:

命名规范:

✅ 推荐: 动名词形式(Gerund Form)

processing-pdfs

analyzing-spreadsheets

reviewing-code

managing-databases

❌ 避免: 过于模糊

helper          # 太模糊

utils           # 不知道干什么

tool            # 功能不明确

3.4 Description 字段的重要性

⚠️ 警告: description 是 Skill 触发的关键,必须用第三人称!

为什么必须第三人称?

description 会被注入到系统提示中,视角不一致会导致困惑:

系统提示: "You are Claude, an AI assistant..."

Skill description: "I can help you process PDFs"  # ❌ 第一人称,视角冲突!

正确示例:

---

name: pdf-processing

description: Extract text and tables from PDF files, fill forms, merge documents.

             Use when working with PDF files or when the user mentions PDFs, forms,

             or document extraction.

---

不正确示例:

❌ description: I can help you process Excel files  # 第一人称

❌ description: You can use this to process Excel   # 第二人称

❌ description: Helps with documents                # 过于模糊

编写技巧:

四、创建你的第一个 Skill

4.1 确定需求

问题导向:

问自己:

示例场景:

场景 1: BigQuery 数据分析

• ❌ 每次都要说明表结构


• ❌ 每次都要强调"排除测试账户"


• ❌ 每次都要说明查询模式


• ✅ 创建一个 BigQuery Skill!

场景 2: 公司文档规范

• ❌ 每次都要说明文档模板


• ❌ 每次都要强调格式要求


• ❌ 每次都要纠正不符合规范的部分


• ✅ 创建一个文档规范 Skill!

4.2 编写 SKILL.md

步骤 1: 创建目录和文件

mkdir my-bigquery-skill

cd my-bigquery-skill

touch SKILL.md

步骤 2: 编写 YAML Frontmatter

---

name: bigquery-analytics

description: Analyze BigQuery data from the user_metrics and sales tables. Use when the user asks about data analysis, metrics, or BigQuery queries. Always exclude test accounts and apply standard date filters.

---

步骤 3: 编写核心指令

# BigQuery Analytics



## Database Schema



### user_metrics table

- user_id (STRING): Unique user identifier

- event_date (DATE): Event date

- metrics_value (FLOAT): Metric value

- account_type (STRING): "production" or "test"



### sales table

- order_id (STRING): Order identifier

- user_id (STRING): User ID (foreign key to user_metrics)

- amount (FLOAT): Order amount

- order_date (DATE): Order date



## Standard Filtering Rules



**Always apply these filters:**

1. Exclude test accounts: `WHERE account_type = 'production'`

2. Date range: Default to last 30 days unless specified

3. Remove null values: `WHERE metrics_value IS NOT NULL`



## Query Patterns



### Pattern 1: User activity analysis

\`\`\`sql

SELECT

  event_date,

  COUNT(DISTINCT user_id) as active_users,

  AVG(metrics_value) as avg_metric

FROM user_metrics

WHERE account_type = 'production'

  AND event_date >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)

GR0UP BY event_date

ORDER BY event_date;

\`\`\`



### Pattern 2: Sales analysis

\`\`\`sql

SELECT

  DATE_TRUNC(order_date, MONTH) as month,

  COUNT(*) as order_count,

  SUM(amount) as total_revenue

FROM sales s

JOIN user_metrics u ON s.user_id = u.user_id

WHERE u.account_type = 'production'

GR0UP BY month

ORDER BY month;

\`\`\`



## Important Notes



- **Performance**: Always use partitioned date fields in WHERE clause

- **Costs**: Preview query cost before running on large datasets

- **Timezone**: All dates are in UTC

五、核心最佳实践

5.1 简洁为王(Conciseness is Key)

核心原则: 上下文窗口是公共资源,你的 Skill 要与系统提示、对话历史、其他 Skills 共享。

✅ 好的示例(约 50 tokens)

## Extract PDF Text



Use pdfplumber for text extraction:



\`\`\`python

import pdfplumber



with pdfplumber.open("file.pdf") as pdf:

    text = pdf.pages[0].extract_text()

\`\`\`

❌ 糟糕的示例(约 150 tokens)

## Extract PDF Text



PDF(便携式文档格式)是一种常见的文件格式,包含文本、图像等内容。

要从 PDF 中提取文本,你需要使用一个库。有很多 PDF 处理库可用,

但我们推荐 pdfplumber,因为它易于使用且能处理大多数情况。

首先,你需要使用 pip 安装它。然后你可以使用下面的代码...

为什么简洁版更好?

• ✅ 假设 Claude 已经知道 PDF 是什么


• ✅ 假设 Claude 知道库的工作原理


• ✅ 直接提供关键信息:用什么库、怎么用


• ✅ 节省 100 tokens,留给其他 Skills 使用

⚠️ 记住: 不要低估 Claude 的智能!它是通用 AI,不需要你解释基础概念。

5.2 设置适当的自由度

根据任务的脆弱性和可变性,选择合适的指导程度。

🌟 高自由度(基于文本的指令)

适用场景:

• 多种方法都可行


• 决策依赖上下文


• 启发式方法指导

示例:代码审查流程

## Code Review Process



1. Analyze code structure and organization

2. Check for potential bugs or edge cases

3. Suggest improvements for readability and maintainability

4. Verify compliance with project standards

特点: 给出大方向,信任 Claude 根据具体情况调整。

🎯 中等自由度(伪代码或带参数的脚本)

适用场景:

• 存在首选模式


• 允许一定变化


• 配置影响行为

示例:生成报告

## Generate Report



Use this template and customize as needed:



\`\`\`python

def generate_report(data, format="markdown", include_charts=True):

    # Process data

    # Generate output in specified format

    # Optionally include visualizations

\`\`\`

特点: 提供模板和参数,允许根据需求调整。

🔒 低自由度(特定脚本,少量或无参数)

适用场景:

• 操作易错且脆弱


• 一致性至关重要


• 必须遵循特定顺序

示例:数据库迁移

## Database Migration



Execute this script strictly:



\`\`\`bash

python scripts/migrate.py --verify --backup

\`\`\`



Do not modify the command or add extra parameters.

特点: 精确指令,不允许偏离。

🌉 类比理解

把 Claude 想象成在不同地形上探索的机器人:

• 悬崖边的窄桥(低自由度): 只有一条安全路径 → 提供详细护栏和精确指令


• 丘陵地带(中等自由度): 几条推荐路径 → 提供地图和指南针


• 无障碍的开阔草地(高自由度): 多条路径都能成功 → 给出大致方向,信任 Claude 找到最佳路线

5.3 渐进式披露模式

模式 1:高层指南 + 引用

结构:

SKILL.md (简要指南)

   ↓ 引用

[FORMS.md] [REFERENCE.md] [EXAMPLES.md]

示例:

# PDF Processing



## Quick Start



Use pdfplumber to extract text:

\`\`\`python

import pdfplumber

with pdfplumber.open("file.pdf") as pdf:

    text = pdf.pages[0].extract_text()

\`\`\`



## Advanced Features



**Form Filling**: See [FORMS.md](FORMS.md) for complete guide

**API Reference**: See [REFERENCE.md](REFERENCE.md) for all methods

**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

优势:

• Claude 只在需要时才读取 FORMS.md、REFERENCE.md 或 EXAMPLES.md


• 未使用的文件 = 0 tokens 消耗

模式 2:按领域组织

适用场景: 多领域的 Skills,避免加载无关上下文

结构:

bigquery-skill/

├── SKILL.md              # 概述和导航

└── reference/

    ├── finance.md        # 财务指标

    ├── sales.md          # 销售数据

    ├── product.md        # 产品分析

    └── marketing.md      # 营销活动

示例:

# BigQuery Analytics



## Domain Reference



- **Finance Metrics**: See [reference/finance.md](reference/finance.md)

- **Sales Data**: See [reference/sales.md](reference/sales.md)

- **Product Analytics**: See [reference/product.md](reference/product.md)

- **Marketing Campaigns**: See [reference/marketing.md](reference/marketing.md)

优势:

• 用户询问销售指标时,只读取 sales.md


• finance.md 和其他文件保持在文件系统中,消耗 0 tokens

模式 3:条件细节

# DOCX Processing



## Create Documents



Use docx-js to create new documents. See [DOCX-JS.md](DOCX-JS.md).



## Edit Documents



For simple edits, modify XML directly.



**Track Changes**: See [REDLINING.md](REDLINING.md)

**OOXML Details**: See [OOXML.md](OOXML.md)

优势:

• 常见操作(创建文档)在主文件中


• 高级功能(追踪更改)按需引用

💡 重要: 保持引用层级为一级深度。避免 SKILL.md → advanced.md → details.md 这样的深层嵌套。

5.4 工作流和反馈循环

复杂任务的工作流模式

为多步骤任务提供清晰的检查清单:

## PDF Form Filling Workflow



Copy this checklist and track progress:



\`\`\`

Task Progress:

- [ ] Step 1: Analyze form (run analyze_form.py)

- [ ] Step 2: Create field mapping (edit fields.json)

- [ ] Step 3: Validate mapping (run validate_fields.py)

- [ ] Step 4: Fill form (run fill_form.py)

- [ ] Step 5: Verify output (run verify_output.py)

\`\`\`



**Step 1: Analyze Form**



Run: `python scripts/analyze_form.py input.pdf`



This extracts form fields and their locations, saving to `fields.json`.



**Step 2: Create Field Mapping**



Edit `fields.json` to add values for each field.



**Step 3: Validate Mapping**



Run: `python scripts/validate_fields.py fields.json`



Fix any validation errors before proceeding.



**Step 4: Fill Form**



Run: `python scripts/fill_form.py input.pdf fields.json output.pdf`



**Step 5: Verify Output**



Run: `python scripts/verify_output.py output.pdf`



If validation fails, return to Step 2.

实现反馈循环

常见模式: 运行验证器 → 修复错误 → 重复

这种模式极大提高输出质量。

示例:文档编辑流程

## Document Editing Flow



1. Make edits to `word/document.xml`

2. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`

3. If validation fails:

   - Review error messages carefully

   - Fix issues in XML

   - Run validation again

4. **Only proceed when validation passes**

5. Repack: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`

6. Test output document

为什么反馈循环重要?

• ✅ 及早发现错误(在应用更改前)


• ✅ 机器可验证(脚本提供客观验证)


• ✅ 可逆计划(Claude 可以迭代而不破坏原始文件)


• ✅ 清晰调试(错误消息指向具体问题)

5.5 内容指南

避免时间敏感信息

❌ 糟糕示例(会过时):

如果你在 2025 年 8 月之前做这件事,使用旧 API。

2025 年 8 月之后,使用新 API。

✅ 好的示例(使用"旧模式"部分):

## Current Method



Use v2 API endpoint: `api.example.com/v2/messages`



## Legacy Patterns



<details>

<summary>Legacy v1 API (deprecated 2025-08)</summary>



v1 API uses: `api.example.com/v1/messages`



This endpoint is no longer supported.

</details>

使用一致的术语

在整个 Skill 中选择一个术语并坚持使用:

✅ 一致性好:

• 始终使用 "API endpoint"


• 始终使用 "field"


• 始终使用 "extract"

❌ 不一致:

• 混用 "API endpoint"、"URL"、"API route"、"path"


• 混用 "field"、"box"、"element"、"control"


• 混用 "extract"、"pull"、"get"、"retrieve"

六、高级技巧

6.1 包含可执行代码的 Skills

解决问题,而非推卸责任

编写 Skills 脚本时,显式处理错误情况,而非推卸给 Claude。

✅ 好的示例:显式处理错误

def process_file(path):

    """处理文件,如果不存在则创建。"""

    try:

        with open(path) as f:

            return f.read()

    except FileNotFoundError:

        # 创建默认内容而非失败

        print(f"文件 {path} 未找到,创建默认文件")

        with open(path, 'w') as f:

            f.write('')

        return ''

    except PermissionError:

        # 提供替代方案而非失败

        print(f"无法访问 {path},使用默认值")

        return ''

❌ 糟糕示例:推卸给 Claude

def process_file(path):

    # 直接失败,让 Claude 自己想办法

    return open(path).read()

提供工具脚本

即使 Claude 可以编写脚本,预制脚本也有优势:

工具脚本的好处:

• 比生成代码更可靠


• 节省 tokens(无需在上下文中包含代码)


• 节省时间(无需代码生成)


• 确保使用的一致性

示例:

## Tool Scripts



**analyze_form.py**: Extract all form fields from PDF



\`\`\`bash

python scripts/analyze_form.py input.pdf > fields.json

\`\`\`



Output format:

\`\`\`json

{

  "field_name": {"type": "text", "x": 100, "y": 200},

  "signature": {"type": "sig", "x": 150, "y": 500}

}

\`\`\`



**validate_boxes.py**: Check for boundary box overlaps



\`\`\`bash

python scripts/validate_boxes.py fields.json

# Returns: "OK" or lists conflicts

\`\`\`



**fill_form.py**: Apply field values to PDF



\`\`\`bash

python scripts/fill_form.py input.pdf fields.json output.pdf

\`\`\`

💡 重要区分: 在指令中明确说明 Claude 应该:

• 执行脚本(最常见): "运行 analyze_form.py 以提取字段"


• 读取作为参考(用于复杂逻辑): "参见 analyze_form.py 了解字段提取算法"

6.2 创建可验证的中间输出

当 Claude 执行复杂、开放式任务时,可能会出错。"计划-验证-执行"模式通过让 Claude 首先创建结构化格式的计划,然后在执行前用脚本验证该计划,从而及早发现错误。

示例场景

要求: Claude 根据电子表格更新 PDF 中的 50 个表单字段。

没有验证:Claude 可能:

• ❌ 引用不存在的字段


• ❌ 创建冲突的值


• ❌ 遗漏必填字段


• ❌ 错误应用更新

有验证:工作流变为:

分析 → 创建计划文件 → 验证计划 → 执行 → 验证输出

添加一个中间 changes.json 文件,在应用更改前进行验证。

实现示例

## Bulk Form Update Workflow



**Step 1: Analyze**

- Extract current form fields

- Save to `current_fields.json`



**Step 2: Create Change Plan**

- Based on spreadsheet, create `changes.json`:

  \`\`\`json

  {

    "field_updates": [

      {"field": "customer_name", "value": "John Doe"},

      {"field": "order_total", "value": "1250.00"}

    ]

  }

  \`\`\`



**Step 3: Validate Plan**

- Run: `python scripts/validate_changes.py changes.json`

- Script checks:

  - All referenced fields exist

  - Values are in correct format

  - No conflicts

- **Only proceed if validation passes**



**Step 4: Execute**

- Apply changes: `python scripts/apply_changes.py changes.json`



**Step 5: Verify Output**

- Run: `python scripts/verify_output.py output.pdf`

为什么此模式有效

• 及早发现错误: 在应用更改前验证发现问题


• 机器可验证: 脚本提供客观验证


• 可逆计划: Claude 可以在不触及原始文件的情况下迭代计划


• 清晰调试: 错误消息指向具体问题

使用时机

• 批量操作


• 破坏性更改


• 复杂验证规则


• 高风险操作

💡 实现技巧: 让验证脚本输出详细的错误消息:

❌ 模糊: "Validation failed"

✅ 清晰: "Field 'signature_date' not found. Available fields: customer_name, order_total, signature_date_signed"

这帮助 Claude 快速修复问题。

6.3 MCP 工具引用

如果你的 Skill 使用 MCP(Model Context Protocol)工具,始终使用完全限定的工具名称以避免"工具未找到"错误。

格式

ServerName:tool_name

示例

## Query Database Schema



Use the BigQuery:bigquery_schema tool to retrieve table schema.



\`\`\`

Use tool: BigQuery:bigquery_schema

Parameters: {"table": "user_metrics"}

\`\`\`



## Create GitHub Issue



Use the GitHub:create_issue tool to create an issue.



\`\`\`

Use tool: GitHub:create_issue

Parameters: {"title": "Bug report", "body": "Description"}

\`\`\`

说明

• BigQuery 和 GitHub 是 MCP 服务器名称


• bigquery_schema 和 create_issue 是这些服务器中的工具名称

没有服务器前缀,Claude 可能无法找到工具,特别是当有多个 MCP 服务器可用时。

七、常见反模式

❌ 反模式 1:Windows 风格路径

问题:使用反斜杠 \ 作为路径分隔符

❌ 错误:

参见 scripts\helper.py

参见 reference\guide.md

✅ 正确:

参见 scripts/helper.py

参见 reference/guide.md

原因:

• Unix 风格路径跨所有平台工作


• Windows 风格路径在 Unix 系统上会导致错误

❌ 反模式 2:提供太多选项

问题:列出所有可能的方法,让 Claude 困惑

❌ 错误:

你可以使用 pypdf,或 pdfplumber,或 PyMuPDF,或 pdf2image,

或 pikepdf,或 PyPDF2,或 pdfrw,或 pdfminer...

✅ 正确:

使用 pdfplumber 进行文本提取:

\`\`\`python

import pdfplumber

\`\`\`



对于需要 OCR 的扫描 PDF,改用 pdf2image 配合 pytesseract。

原则:

• 提供默认推荐方法


• 只在特殊情况下提供替代方案


• 不要列出所有可能性

❌ 反模式 3:深层嵌套引用

问题:引用链太长,Claude 难以跟踪

❌ 错误:

SKILL.md → advanced.md → details.md → examples.md

✅ 正确:

SKILL.md

  ↓ 直接引用

[ADVANCED.md] [DETAILS.md] [EXAMPLES.md]

原则:

• 保持从 SKILL.md 的引用为一级深度


• 所有引用文件应直接从 SKILL.md 链接

❌ 反模式 4:过度解释基础概念

问题:解释 Claude 已经知道的内容

❌ 错误:

PDF(Portable Document Format,便携式文档格式)是 Adobe 公司

开发的一种文件格式,可以在不同操作系统上保持一致的显示效果。

PDF 文件包含文本、图像、矢量图形等多种内容类型...

✅ 正确:

使用 pdfplumber 提取 PDF 文本。

原则:

• 假设 Claude 的智能


• 只提供 Claude 不知道的领域特定知识

❌ 反模式 5:第一人称描述

问题:使用"我"、"你"等人称

❌ 错误:

description: I can help you process Excel files and generate reports.

✅ 正确:

description: Process Excel files and generate reports. Use when working with spreadsheets or when the user mentions Excel, CSV, or data analysis.

原因:

• description 被注入系统提示


• 第一人称会导致视角冲突

八、总结与行动

8.1 核心收益

通过 Skills 系统,你可以:

8.2 Skills 与其他功能的关系

8.3 实践建议

对于个人开发者:

对于团队:

对于技术 Leader:

8.4 未来展望

Skills 系统的发展方向:

"把你反复向 Claude 解释的偏好、流程、领域知识打包成 Skills,让 AI 成为你的领域专家"

实用资源

• Claude Code 官方 Skills


• 一人公司所需要的Skill集合


• AI Coding资料集合，内含github众多高星skill项目

🔗 相关文章:

• 上一篇: Agent 系统详解:从使用到自定义开发


• 下一篇: Plugin 扩展实战:增强 Claude Code 的能力

如果这篇文章对你有帮助,欢迎点赞、收藏、分享!有任何问题或建议,欢迎在评论区留言讨论。让我们一起学习,一起成长!

也欢迎访问我的个人主页发现更多宝藏资源

前置条件

环境

openclaw需要Node.js 22或者更高版本

笔者在CentOS 7虚拟机上使用源码包安装或者fnm安装Node.js会提示这样那样的错误；

源码包安装会有环境的问题：python、g++版本太老……

用fnm安装后提示

node: /lib64/libstdc++.so.6: version `CXXABI_1.3.11' not found (required by node) node: /lib64/libstdc++.so.6: version `CXXABI_1.3.8' not found (required by node) node: /lib64/libstdc++.so.6: version `GLIBCXX_3.4.20' not found (required by node) node: /lib64/libstdc++.so.6: version `GLIBCXX_3.4.21' not found (required by node) node: /lib64/libstdc++.so.6: version `CXXABI_1.3.9' not found (required by node) node: /lib64/libm.so.6: version `GLIBC_2.27' not found (required by node) node: /lib64/libc.so.6: version `GLIBC_2.27' not found (required by node) node: /lib64/libc.so.6: version `GLIBC_2.28' not found (required by node) node: /lib64/libc.so.6: version `GLIBC_2.25' not found (required by node)

所以在自己的云服务器上搭建了

node安装

nodejs github地址

nodejs 网站地址可查看LTS版本

官方推荐这三种方式

nvm

官方给出的安装方式

# 下载并安装 nvm：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash



# 代替重启 shell

\. "$HOME/.nvm/nvm.sh"



# 下载并安装 Node.js：

nvm install 24



# 验证 Node.js 版本：

node -v # Should print "v24.14.0".



# 验证 npm 版本：

npm -v # Should print "11.9.0".

但是这里会提示网络不可达，所以nvm我们采用离线的方式进行安装

nvm GitHub地址

解压

配置环境变量

• vi ~/.bashrc

export NVM_DIR="/usr/local/nvm-0.40.4"

[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm

[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion



# 使其生效

source ~/.bashrc

验证

nvm -v

显示对应的版本号

查看可用的node版本

# 查看可安装的 node 版本

nvm ls-remote

安装对应的版本

# 安装指定版本的 node

nvm install 24.14.0

fnm

官方给出的安装方式

# 下载并安装 fnm：

curl -o- https://fnm.vercel.app/install | bash

# 下载并安装 Node.js：

fnm install 24

# 验证 Node.js 版本：

node -v # Should print "v24.14.0".

# 验证 npm 版本：npm -v # Should print "11.9.0".

但是这里会提示网络不可达，所以fnm我们采用离线的方式进行安装

fnmGitHub地址

下载后解压

添加环境变量

• vi /etc/profile

# /usr/local/fnm-1.38.1为fnm解压后的存放位置并不是fnm文件的绝对路径，而是存放位置

export PATH=$PATH:/usr/local/fnm-1.38.1

# 使其生效

source /etc/profile

• vi ~/.bashrc

eval "$(fnm env --use-on-cd --shell bash)"

# 使其生效

source ~/.bashrc

验证

fnm --version

返回对应的版本号

Docker

官方给出的安装方式

# Docker 对每个操作系统都有特定的安装指导。

# 请参考 https://docker.com/get-started/ 给出的官方文档



# 拉取 Node.js Docker 镜像：

docker pull node:24-alpine



# 创建 Node.js 容器并启动一个 Shell 会话：

docker run -it --rm --entrypoint sh node:24-alpine



# 验证 Node.js 版本：

node -v # Should print "v24.14.0".



# 验证 npm 版本：

npm -v # Should print "11.9.0".

安装docker

阿里云文档

非阿里云服务器，需将mirrors.cloud.aliyuncs.com替换为https://mirrors.al…

#添加Docker软件包源

sudo wget -O /etc/yum.repos.d/docker-ce.repo http://mirrors.cloud.aliyuncs.com/docker-ce/linux/centos/docker-ce.repo



# 【非阿里云服务区不需要执行这一步】执行后，该文件中的所有https://mirrors.aliyun.com都会被替换为http://mirrors.cloud.aliyuncs.com

sudo sed -i 's|https://mirrors.aliyun.com|http://mirrors.cloud.aliyuncs.com|g' /etc/yum.repos.d/docker-ce.repo



#安装Docker社区版本，容器运行时containerd.io，以及Docker构建和Compose插件

sudo yum -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

配置阿里云加速镜像

sudo mkdir -p /etc/docker 

sudo tee /etc/docker/daemon.json <<-'EOF' 

{ 

"registry-mirrors": ["https://xxxx.mirror.aliyuncs.com"] 

} 

EOF 

sudo systemctl daemon-reload 

sudo systemctl restart docker

阿里云docker加速器地址

直接拉取镜像由于网络的问题可能导致镜像拉取失败

下载好镜像上传到服务器进行加载

docker load -i node_24-alpine.tar

运行

# 创建 Node.js 容器并启动一个 Shell 会话：

docker run -it --rm --entrypoint sh node:24-alpine

# 验证 Node.js 版本：

node -v # Should print "v24.14.0".

# 验证 npm 版本：

npm -v # Should print "11.9.0".

源码包安装

v24.14.0 LTS GitHub地址

下载后解压

tar -zxaf node-24.14.0.tar.gz

cd node-24.14.0

# 检查依赖并生成 Makefile（可添加自定义参数，如 --prefix=/usr/local/node）

./configure --prefix=/usr/local/node

# 编译（-j4 表示使用 4 核 CPU 加速，根据实际核心数调整）

make -j4

# 安装到系统目录（默认 /usr/local/bin）

make install

问题

• python

./configure --prefix=/usr/local/node/ --python=/usr/local/python_3.14.3/bin/python3.14 Node.js configure: Found Python 3.6.8... Please use python3.14 or python3.13 or python3.12 or python3.11 or python3.10 or python3.9.

• bz2

[root@localhost node-24.14.0]# ./configure --prefix=/usr/local/node Node.js configure: Found Python 3.14.3... Traceback (most recent call last): File "/usr/local/node-24.14.0/./configure", line 28, in <module> import configure File "/usr/local/node-24.14.0/configure.py", line 13, in <module> import bz2 File "/usr/local/python_3.14.3/lib/python3.14/bz2.py", line 17, in <module> from _bz2 import BZ2Compressor, BZ2Decompressor ModuleNotFoundError: No module named '_bz2'

• g++

Node.js configure: Found Python 3.14.3... WARNING: C++ compiler (CXX=g++, 4.8.5) too old, need g++ 12.2.0 or clang++ 8.0.0 WARNING: warnings were emitted in the configure phase INFO: configure completed successfully

个人不太推荐

npm 包管理器安装

npm i -g openclaw

安装完成后

openclaw onboard

访问Dashboard

由于程序运行在linux服务器上没有GUI界面所以想要可视化访问需要做一系列的操作

运行 SSH 隧道命令

ssh -N -L 18789:127.0.0.1:18789 root@xx.x.x.xxx

光标在下方就表示隧道建立了

浏览器访问

http://localhost:18789 直接访问会报身份认证失败
http://localhost:18789/#token=c74d1xxxxdccaxxx8bdcxxx 回车即可进入可视化控制台

一键安装

官网安装教程这里不再赘述

源码编译

官网安装教程这里不再赘述

Docker

官网安装教程这里不再赘述

常用命令

• 查看版本

openclaw --version

• 交互式设置向导

openclaw onboard [--install-daemon]

• 启动网关

openclaw gateway [--port 18789]

• 重启网关

openclaw gateway restart

• 健康检查与快速修复

openclaw doctor [--deep]

• 交互式配置

openclaw configure

链接

官网安装

OpenClaw 官方文档

大家好，我是猿java。

数据库的三大范式，它是数据库设计中最基本的三个规范，那么，三大范式是什么？在实际开发中，我们一定要严格遵守三大范式吗？这篇文章，我们一起来聊一聊。

1. 三大范式

1. 第一范式（1NF，确保每列保持原子性）

第一范式要求数据库中的每个表格的每个字段（列）都具有原子性，即字段中的值不可再分割。换句话说，每个字段只能存储一个单一的值，不能包含集合、数组或重复的组。

如下示例： 假设有一个学生表 Student，结构如下：

在这个表中，电话号码字段包含多个号码，违反了1NF的原子性要求。为了满足1NF，需要将电话号码拆分为单独的记录或创建一个新的表。

满足 1NF后的设计：

学生表 Student

电话表 Phone

1.2 第二范式（2NF，确保表中的每列都和主键相关）

第二范式要求满足第一范式，并且消除表中的部分依赖，即非主键字段必须完全依赖于主键，而不是仅依赖于主键的一部分。这主要适用于复合主键的情况。

如下示例：假设有一个订单详情表 OrderDetail，结构如下：

在上述表中，主键是复合主键 (订单ID, 商品ID)。商品名称和单价只依赖于复合主键中的商品ID，而不是整个主键，存在部分依赖，违反了2NF。

满足 2NF后的设计：

订单详情表 OrderDetail

商品表 Product

1.3 第三范式（3NF，确保每列都和主键列直接相关,而不是间接相关）

第三范式要求满足第二范式，并且消除表中的传递依赖，即非主键字段不应依赖于其他非主键字段。换句话说，所有非主键字段必须直接依赖于主键，而不是通过其他非主键字段间接依赖。

如下示例：假设有一个员工表 Employee，结构如下：

在这个表中，部门名称依赖于部门ID，而部门ID依赖于主键员工ID，形成了传递依赖，违反了3NF。

满足3NF后的设计：

员工表 Employee

部门表 Department

通过将部门信息移到单独的表中，消除了传递依赖，使得数据库结构符合第三范式。

最后，我们总结一下数据库设计的三大范式：

• 第一范式（1NF）： 确保每个字段的值都是原子性的，不可再分。


• 第二范式（2NF）： 在满足 1NF的基础上，消除部分依赖，确保非主键字段完全依赖于主键。


• 第三范式（3NF）： 在满足 2NF的基础上，消除传递依赖，确保非主键字段直接依赖于主键。

2. 破坏三范式

在实际工作中，尽管遵循数据库的三大范式（1NF、2NF、3NF）有助于提高数据的一致性和减少冗余，但在某些情况下，为了满足性能、简化设计或特定业务需求，我们可能需要违反这些范式。

下面列举了一些常见的破坏三范式的原因及对应的示例。

2.1 性能优化

在高并发、大数据量的应用场景中，严格遵循三范式可能导致频繁的联表查询，增加查询时间和系统负载。为了提高查询性能，设计者可能会通过冗余数据来减少联表操作。

假设有一个电商系统，包含订单表 Orders 和用户表 Users。在严格 3NF设计中，订单表只存储 用户ID，需要通过联表查询获取用户的详细信息。

但是，为了查询性能，我们通常会在订单表中冗余存储 用户姓名 和 用户地址等信息，因此，查询订单信息时无需联表查询 Users 表，从而提升查询速度。

破坏 3NF后的设计：

2.2 简化查询和开发

严格规范化可能导致数据库结构过于复杂，增加开发和维护的难度，为了简化查询逻辑和减少开发复杂度，我们也可能会选择适当的冗余。

比如，在内容管理系统（CMS）中，文章表 Articles 和分类表 Categories 通常是独立的，如果频繁需要显示文章所属的分类名称，联表查询可能增加复杂性。因此，通过在 Articles 表中直接存储 分类名称，可以简化前端展示逻辑，减少开发工作量。

破坏 3NF后的设计：

2.3 报表和数据仓库

在数据仓库和报表系统中，通常需要快速读取和聚合大量数据。为了优化查询性能和数据分析，可能会采用冗余的数据结构，甚至使用星型或雪花型模式，这些模式并不完全符合三范式。

在销售数据仓库中，为了快速生成销售报表，可能会创建一个包含维度信息的事实表。

破坏 3NF后的设计：

在事实表中直接存储 产品名称 和 类别，避免了需要联表查询维度表，提高了报表生成的效率。

2.4 特殊业务需求

在某些业务场景下，可能需要快速响应特定的查询或操作，这时通过适当的冗余设计可以满足业务需求。

比如，在实时交易系统中，为了快速计算用户的账户余额，可能会在用户表中直接存储当前余额，而不是每次交易时都计算。

破坏 3NF后的设计：

在交易记录表中存储每笔交易的增减，但直接在用户表中维护 当前余额，避免了每次查询时的复杂计算。

2.5 兼顾读写性能

在某些应用中，读操作远多于写操作。为了优化读性能，可能会通过数据冗余来提升查询速度，而接受在数据写入时需要额外的维护工作。

社交媒体平台中，用户的好友数常被展示在用户主页上。如果每次请求都计算好友数量，效率低下。可以在用户表中维护一个 好友数 字段。

破坏3NF后的设计：

通过在 Users 表中冗余存储 好友数，可以快速展示，无需实时计算。

2.6 快速迭代和灵活性

在快速发展的产品或初创企业中，数据库设计可能需要频繁调整。过度规范化可能导致设计不够灵活，影响迭代速度。适当的冗余设计可以提高开发的灵活性和速度。

一个初创电商平台在初期快速上线，数据库设计时为了简化开发，可能会将用户的收货地址直接存储在订单表中，而不是单独创建地址表。

破坏3NF后的设计：

这样设计可以快速上线，后续根据需求再进行规范化和优化。

2.7 降低复杂性和提高可理解性

有时，过度规范化可能使数据库结构变得复杂，难以理解和维护。适度的冗余可以降低设计的复杂性，提高团队对数据库结构的理解和沟通效率。

在一个学校管理系统中，如果将学生的班级信息独立为多个表，可能增加理解难度。为了简化设计，可以在学生表中直接存储班级名称。

破坏3NF后的设计：

通过在学生表中直接存储 班级名称 和 班主任，减少了表的数量，简化了设计。

3. 总结

本文，我们分析了数据库的三范式以及对应的示例，它是数据库设计的基本规范。但是，在实际工作中，为了满足性能、简化设计、快速迭代或特定业务需求，我们很多时候并不会严格地遵守三范式。

所以说，架构很多时候都是业务需求、数据一致性、系统性能、开发效率等各种因素权衡的结果，我们需要根据具体应用场景做出合理的设计选择。

4. 学习交流

如果你觉得文章有帮助，请帮忙转发给更多的好友，或关注公众号：猿java，持续输出硬核文章。

模型是：Codex+Gemini+GLM5+Kimik2.5+MiniMax2.5

先说明一下：这篇只分享我自己长期在用的公开方案，不是广告，也不是“理论推荐”。

核心标准就三个：能稳定用、能真落地、成本尽量低。

另外我现在的原则是：尽量走官方渠道，不再折腾反代。账号和接口都建议按平台规则来。

先说结论：我现在的主力分工

1）第一名：Codex（免费账号可用，但额度偏低）

这个“第一名”我给得很直接：写代码时最稳，尤其后端和复杂功能。

免费账号能用它的模型，但额度确实不高。我的观察是，不同账号之间免费额度会有差异：

• 早期注册的账号，额度通常更高一点


• Google 邮箱注册的账号，额度通常也会稍高


• 其他邮箱注册的部分账号，额度会明显低一些

所以我会准备多个免费账号轮换，但整体还是优先把主链路放在 Codex 上。

2）第二名：Gemini + Antigravity（我现在的前端主力）

Google 这套我最近重新用了起来。之前被封的一批账号后来都解封了，我自己之前的 5 个号也都恢复了。

但现在我不准备再用反代，直接走官方工具 Antigravity。我看中它的点主要是：

• 对 Chrome 控制比较顺手


• 内部集成了 Playwright MCP


• Gemini 在前端页面和交互生成上表现不错

所以我现在是：Gemini 负责前端，Codex 负责后端和大多数功能实现。

3）Cloud Code Opus 4.6：有，但不是常用位

Antigravity 里还有 Cloud Code Opus 4.6，我基本只在别的模型额度打满时才会切过去。

原因很简单：给到它的免费用量比较少，放在主流程里不太稳，适合作为兜底。

4）国内白嫖方案：白山智算 + zo computer

这两个是我现在固定会留着的国内补位方案。

白山智算（API 平台）

这个活动期挺给力：实名 + 首次调用后，能拿到 450 左右额度，日常够用。

里面我主要关注的是 GLM-5 和 MiniMax-2.5。

它本身走的是 OpenAI 兼容路由，所以能比较方便接进各种编程工具里，改个接口配置就能跑。

我之前推荐过了，注册链接：白山智算

zo computer（在线使用）

这个相对小众一点，但很省心：注册账号就能用内置免费模型，包含 GLM-5、Kimi-2.5、MiniMax-2.5。

限制也很明确：更适合在线对话和临时任务，不太适合直接塞进 IDE 作为长期开发链路。

官网：zo.computer/

OpenCode：我现在已经没咋用了

以前有 Kimi 相关模型时我还会用一下。现在免费模型能力和覆盖变化后，我基本不再用它做主力。

再加上我有更顺手的 Codex + Gemini 组合，就没有必要在后面的方案上投入太多时间了。

我自己的使用策略（很实用）

最后

以上 4 个就是我现在公开在用的白嫖 AI 方案。

如果你有更稳、更省钱、还能长期跑的组合，欢迎留言交流。

仅仅几个月狂揽 22 万 Star，经历三次改名（Clawdbot -> Moltbot -> OpenClaw）依然热度不减。它不是简单的聊天机器人，而是真正运行在你本地、接管你所有通讯软件（WhatsApp, Telegram, 飞书...）的超级私人管家。本文手把手教你部署这只“全能龙虾”！

Github：github.com/openclaw/op…

最近，GitHub 上有一个项目杀疯了。

如果你关注 AI 圈，一定被一只红色的龙虾（Lobster） 刷屏过。没错，就是 OpenClaw。

截至目前（2026 年 2 月），OpenClaw 在 GitHub 上的 Star 数已经突破了 228k！这是什么概念？即使是当年的爆款项目，也没有如此夸张的增长速度。

它到底是什么？为什么连退隐多年的技术圈大佬 Peter Steinberger（PSPDFKit 创始人）和 Mario Zechner（libGDX 之父）都要复出亲自操刀？

今天，我们就来扒一扒这个“当红炸子鸡”，并手把手教你把它装进电脑里。

什么是 OpenClaw？

简单来说，OpenClaw 是一个运行在你本地设备上的“个人 AI 代理（Agent）中枢” 。

别把它和 ChatGPT 网页版搞混了。OpenClaw 的核心逻辑是： “流水的模型，铁的管家” 。

• 它没有 App（或者说不需要 App）： 它直接寄生在你最常用的聊天软件里——WhatsApp、飞书、Slack、Discord、Signal，甚至是 iMessage。


• 它极度聪明： 它不仅能陪聊，还能执行任务。它内置了强大的工具链，可以浏览网页、操作日历、根据你的指令写代码、甚至通过 ElevenLabs 实现语音对话。


• 它绝对隐私： 所有的记忆、配置、对话历史都存储在你本地。你可以自由切换底层模型（Claude Opus, GPT-4, Llama 等），但“管家”本身是你的。

大家之所以疯狂追捧它，是因为它终于实现了我们对“贾维斯”的幻想：一个永远在线、了解你一切背景、并且听命于你的私人助理。

核心特点：为什么它能“爆”？

如何安装与使用

好消息是，经过几个版本的迭代，现在安装 OpenClaw 已经非常简单了（推荐使用 MacOS 或 Linux/WSL2）。

1. 环境准备

你需要安装 Node.js（版本 ≥ 22）。

2. 一键安装

打开终端（Terminal），输入以下命令：

npm install -g openclaw@latest

# pnpm add -g openclaw@latest

3. 启动向导（Onboarding）

OpenClaw 最人性化的地方就在于它的交互式配置向导。在终端输入：

openclaw onboard --install-daemon

接下来，你只需要像填问卷一样：

4. 开始使用

现在，拿起你的手机，打开你配置的渠道（例如：飞书），给你刚刚绑定的 Bot 发送一句：

你会发现，一个新的世界大门打开了。

一直对 MyBatis 有个刻板印象：Mapper 接口负责声明方法，Mapper.xml 负责写 SQL。

改条件就去 XML 里 <if test="">，调参数就切换不同文件，从刚开始学到现在用了很久，熟悉得不能再熟悉。

直到最近看到一个项目：我把 resources/mapper 翻了个底朝天，愣是没找到一份 XML。

我第一反应：

“这项目肯定是全用 @Select 之类的注解硬写 SQL 了吧。”

结果打开 Mapper：我人傻了。

1）去 XML：@Select

单表按主键查，注解很舒服：

@Select("select * from tb_user where id = #{id}")UserDO selectById(Long id);

但一旦要动态条件，很多人会写成这种：

@Select("" +        "select * from tb_user " +        "" +        "   and name like concat('%', #{name}, '%') " +        "   and age >= #{age} " +        "" +        "")List list(UserQuery req);

这么些的体验基本是：

• • 字符串拼接看得眼疼


• • 没有 SQL 高亮、格式化也很难受


• • 复杂一点直接维护灾难

所以绝大多数团队最终都会回到 XML——至少 XML 里写动态 SQL 还能接受。

2）去 XML：@SelectProvider

这个项目里 Mapper 长这样：

@SelectProvider(type = UserSqlProvider.class, method = "selectByCondition")List selectByCondition(UserQuery req);

我当时心里一句话：

“Provider？这是什么东东？”

点进 UserSqlProvider，看到的是这种代码：

public class UserSqlProvider {  public String selectByCondition(UserQuery req) {    return new SQL() {{      SELECT("id, name, age, status, create_time");      FROM("tb_user");      if (req.getName() != null && !req.getName().isBlank()) {        WHERE("name like concat('%', #{name}, '%')");      }      if (req.getMinAge() != null) {        WHERE("age >= #{minAge}");      }      if (req.getStatus() != null) {        WHERE("status = #{status}");      }      ORDER_BY("create_time desc");    }}.toString();  }}

当时我有点惊讶：
SQL()、SELECT()、WHERE() 这些不是自定义工具类，而是 MyBatis 自带的 SQL Builder。

这类写法的本质是：

• • XML 动态 SQL 的能力不变


• • 但“拼 SQL 的载体”从 XML 变成 Java Provider 方法


• • 最终 MyBatis 仍然执行一段 SQL 字符串（只是这段字符串由 builder 组装出来）

3）Provider

解决了什么？

动态条件 + 可读性。

不用在注解字符串里写 <script>、不用手动拼 AND、也不用在 Java/XML 之间跳来跳去。

再比如：动态排序字段（注意做白名单防注入）

public String list(UserQuery req) {  return new SQL() {{    SELECT("*");    FROM("tb_user");    if (req.getName() != null && !req.getName().isBlank()) {      WHERE("name like concat('%', #{name}, '%')");    }    // 排序字段做白名单，避免 order by 注入    if ("create_time".equals(req.getOrderBy())) {      ORDER_BY("create_time desc");    } else if ("age".equals(req.getOrderBy())) {      ORDER_BY("age desc");    } else {      ORDER_BY("id desc");    }  }}.toString();}

未能解决

复杂 SQL 的“表达力”问题。

子查询、复杂 join、窗口函数、CTE……你用 builder 也能写，但写着写着就会变成“在 Java 里造 SQL AST”，维护成本可能并不比 XML 低。

我的建议：

• • 中等复杂度动态查询：Provider 很合适


• • 复杂报表 / 多层嵌套：直接写原生 SQL（放 XML 或统一的 SQL 文件）更直观

4）Provider 最容易踩的坑：参数绑定（90% 的报错在这）

4.1 单参数对象：最舒服

List list(UserQuery req);

Provider 里直接 #{name}、#{minAge}，对应 req 的属性名即可。

4.2 多参数一定要 @Param，不然会看到奇怪的参数名

@SelectProvider(type = UserSqlProvider.class, method = "get")UserDO get(@Param("id") Long id, @Param("status") Integer status);

Provider 可以收 Map：

public String get(Map p) {  return new SQL() {{    SELECT("*");    FROM("tb_user");    WHERE("id = #{id}");    if (p.get("status") != null) {      WHERE("status = #{status}");    }  }}.toString();}

如果不写 @Param，参数名可能变成 param1/param2 或 arg0/arg1，然后你就开始“有bug，明明传了值怎么为空”。

5）再懒一下：MyBatis-Plus

如果主要场景是单表 CRUD + 条件筛选，MyBatis-Plus 的思路是：尽量别写 SQL，让 Wrapper 来表达条件。

LambdaQueryWrapper w = Wrappers.lambdaQuery();w.like(StringUtils.isNotBlank(req.getName()), UserDO::getName, req.getName()) .ge(req.getMinAge() != null, UserDO::getAge, req.getMinAge()) .eq(req.getStatus() != null, UserDO::getStatus, req.getStatus()); List list = userMapper.selectList(w);

这套东西的价值很明确：

• • 字段引用是方法引用，改字段/重构更安全


• • 大量单表查询不需要写 SQL


• • 团队统一风格之后，开发效率很高

但边界也很明确：复杂 SQL 仍然要回到原生 SQL（XML/Provider/自定义 mapper 都行），Wrapper 不适合硬扛报表类需求。

6）组装 SQL：MyBatis-Flex

如果连 join 都不想写 SQL，更希望用 Java 结构来表达，MyBatis-Flex 这类框架会提供更强的 QueryWrapper/Join 能力。

简单 join 确实很直观：

QueryWrapper q = QueryWrapper.create()    .select(ACCOUNT.ID, ACCOUNT.USER_NAME, ROLE.ROLE_NAME)    .from(ACCOUNT)    .leftJoin(ROLE).on(ACCOUNT.ROLE_ID.eq(ROLE.ID))    .where(ACCOUNT.AGE.ge(18)); List list = accountMapper.selectListByQueryAs(q, AccountDTO.class);

但当你开始写多层子查询/嵌套条件时，可读性很容易被“对象套对象”拉低。

比如“订单金额 > 用户 1 平均订单金额”这种：

// 子查询QueryWrapper sub = QueryWrapper.create()    .select(avg(ORDER.TOTAL_PRICE))    .from(ORDER)    .where(ORDER.USER_ID.eq(1)); // 主查询QueryWrapper main = QueryWrapper.create()    .select(ORDER.ALL_COLUMNS)    .from(ORDER)    .where(ORDER.TOTAL_PRICE.gt(sub)); List list = orderMapper.selectListByQuery(main);

能写、也类型更安全，但维护者往往需要在脑子里把它“还原成 SQL”再理解意图。嵌套层级越深，这个成本越高。

7）到底怎么选？

参考落地策略：

• • 固定 SQL / 简单单表：@Select 足够


• • 中等动态 SQL（条件多、拼接多，但逻辑清晰）：@SelectProvider + SQL Builder


• • 单表 CRUD 为主，追求少写 SQL：MyBatis-Plus


• • Join 多、希望 Java 化表达更强：MyBatis-Flex（嵌套复杂时要克制）


• • 复杂报表 / 多层子查询 / 强声明式：直接原生 SQL（XML/SQL 文件），通常最清晰

Provider 这条路最让我意外：不靠第三方，也不把动态 SQL 写成字符串炼狱，但它也不是用来替代所有 SQL 的。把边界定好，用起来会更舒服。

总之就是在不同场景下面选择合适的技术并确定合理的规范，然后统一按照规范执行就可以啦！

前言

今天我们来聊聊让无数开发者又爱又恨的——数据库索引。

相信不少小伙伴在工作中都遇到过这样的场景：

• 明明已经加了索引，为什么查询还是慢？


• 为什么有时候索引反而导致性能下降？


• 联合索引到底该怎么设计才合理？

别急，今天我就通过10个问题，带你彻底搞懂索引的奥秘！

希望对你会有所帮助。

最近准备面试的小伙伴，可以看一下这个宝藏网站（Java突击队）：www.susan.net.cn，里面：面试八股文、场景设计题、面试真题、7个项目实战、工作内推什么都有。

一、什么是索引？为什么需要索引？

1.1 索引的本质

简单来说，索引就是数据的目录。

就像一本书的目录能帮你快速找到内容一样，数据库索引能帮你快速定位数据。

-- 没有索引的查询（全表扫描）

SELECT * FROM users WHERE name = '苏三'; -- 需要遍历所有记录



-- 有索引的查询（索引扫描）

CREATE INDEX idx_name ON users(name);

SELECT * FROM users WHERE name = '苏三'; -- 通过索引快速定位

1.2 索引的工作原理

索引的底层结构（B+树）：

二、索引的10个常见问题

1.为什么我加了索引，查询还是慢？

场景还原：

CREATE INDEX idx_name ON users(name);

SELECT * FROM users WHERE name LIKE '%苏三%'; -- 还是很慢！

原因分析：

解决方案：

-- 方案1：避免前导通配符

SELECT * FROM users WHERE name LIKE '苏三%';



-- 方案2：使用覆盖索引

CREATE INDEX idx_name_covering ON users(name, id, email);

SELECT name, id, email FROM users WHERE name LIKE '苏三%'; -- 不需要回表



-- 方案3：使用全文索引（对于文本搜索）

CREATE FULLTEXT INDEX ft_name ON users(name);

SELECT * FROM users WHERE MATCH(name) AGAINST('苏三');

2.索引是不是越多越好？

绝对不是！ 索引需要维护代价：

-- 每个索引都会影响写性能

INSERT INTO users (name, email, age) VALUES ('苏三', 'susan@example.com', 30);

-- 需要更新: 

-- 1. 主键索引

-- 2. idx_name索引（如果存在）

-- 3. idx_email索引（如果存在）

-- 4. idx_age索引（如果存在）

索引的代价：

黄金法则：一般建议表的索引数量不超过5-7个

3.联合索引的最左前缀原则是什么？

最左前缀原则：联合索引只能从最左边的列开始使用

-- 创建联合索引

CREATE INDEX idx_name_age ON users(name, age);



-- 能使用索引的查询

SELECT * FROM users WHERE name = '苏三'; -- √ 使用索引

SELECT * FROM users WHERE name = '苏三' AND age = 30; -- √ 使用索引

SELECT * FROM users WHERE age = 30 AND name = '苏三'; -- √ 优化器会调整顺序



-- 不能使用索引的查询

SELECT * FROM users WHERE age = 30; -- × 不符合最左前缀

联合索引结构：

4.如何选择索引字段的顺序？

选择原则：

-- 计算字段选择性

SELECT 

    COUNT(DISTINCT name) / COUNT(*) as name_selectivity,

    COUNT(DISTINCT age) / COUNT(*) as age_selectivity,

    COUNT(DISTINCT city) / COUNT(*) as city_selectivity

FROM users;



-- 根据选择性决定索引顺序

CREATE INDEX idx_name_city_age ON users(name, city, age); -- name选择性最高

5.什么是覆盖索引？为什么重要？

覆盖索引：索引包含了查询需要的所有字段，不需要回表查询

-- 不是覆盖索引（需要回表）

CREATE INDEX idx_name ON users(name);

SELECT * FROM users WHERE name = '苏三'; -- 需要回表查询其他字段



-- 覆盖索引（不需要回表）

CREATE INDEX idx_name_covering ON users(name, email, age);

SELECT name, email, age FROM users WHERE name = '苏三'; -- 所有字段都在索引中

覆盖索引的优势：

6.NULL值对索引有什么影响？

NULL值的问题：

-- 创建索引

CREATE INDEX idx_email ON users(email);



-- 查询NULL值

SELECT * FROM users WHERE email IS NULL; -- 可能不使用索引

SELECT * FROM users WHERE email IS NOT NULL; -- 可能不使用索引

NULL值可能不使用索引。

解决方案：

-- 使用函数索引处理NULL值

CREATE INDEX idx_email_null ON users((COALESCE(email, '')));

SELECT * FROM users WHERE COALESCE(email, '') = '';

7.索引对排序和分组有什么影响？

索引优化排序和分组：

-- 创建索引

CREATE INDEX idx_age_name ON users(age, name);



-- 索引优化排序

SELECT * FROM users ORDER BY age, name; -- √ 使用索引避免排序



-- 索引优化分组

SELECT age, COUNT(*) FROM users GR0UP BY age; -- √ 使用索引优化分组



-- 无法使用索引排序的情况

SELECT * FROM users ORDER BY name, age; -- × 不符合最左前缀

SELECT * FROM users ORDER BY age DESC, name ASC; -- × 排序方向不一致

最近为了帮助大家找工作，专门建了一些工作内推群，各大城市都有，欢迎各位HR和找工作的小伙伴进群交流，群里目前已经收集了不少的工作内推岗位。加苏三的微信：li_su223，备注：掘金+所在城市，即可进群。

8.如何发现索引失效的场景？

常见索引失效场景：

使用EXPLAIN分析：

EXPLAIN SELECT * FROM users WHERE name = '苏三';



-- 查看关键指标：

-- type: const|ref|range|index|ALL（性能从好到坏）

-- key: 实际使用的索引

-- rows: 预估扫描行数

-- Extra: Using index（覆盖索引）| Using filesort（需要排序）| Using temporary（需要临时表）

9.如何维护和优化索引？

定期索引维护：

-- 查看索引使用情况（MySQL）

SELECT * FROM sys.schema_index_statistics 

WHERE table_schema = 'your_database' AND table_name = 'users';



-- 重建索引（优化索引碎片）

ALTER TABLE users REBUILD INDEX idx_name;



-- 分析索引使用情况

ANALYZE TABLE users;

索引监控：

-- 开启索引监控（Oracle）

ALTER INDEX idx_name MONITORING USAGE;



-- 查看索引使用情况

SELECT * FROM v$object_usage WHERE index_name = 'IDX_NAME';

10.不同数据库的索引有什么差异？

MySQL vs PostgreSQL索引差异：

PostgreSQL示例：

-- 创建包含索引（Covering Index）

CREATE INDEX idx_users_covering ON users (name) INCLUDE (email, age);



-- 创建部分索引（Partial Index）

CREATE INDEX idx_active_users ON users (name) WHERE is_active = true;



-- 创建表达式索引（Expression Index）

CREATE INDEX idx_name_lower ON users (LOWER(name));

三、索引设计最佳实践

3.1 索引设计原则

3.2 索引设计检查清单

四、实战案例：电商系统索引设计

4.1 用户表索引设计

-- 用户表结构

CREATE TABLE users (

    id BIGINT PRIMARY KEY,

    username VARCHAR(50) NOT NULL,

    email VARCHAR(100) NOT NULL,

    phone VARCHAR(20),

    age INT,

    city VARCHAR(50),

    created_at TIMESTAMP,

    is_active BOOLEAN

);



-- 推荐索引

CREATE INDEX idx_users_username ON users(username);

CREATE INDEX idx_users_email ON users(email);

CREATE INDEX idx_users_city_age ON users(city, age);

CREATE INDEX idx_users_created ON users(created_at) WHERE is_active = true;

4.2 订单表索引设计

-- 订单表结构

CREATE TABLE orders (

    id BIGINT PRIMARY KEY,

    user_id BIGINT,

    status VARCHAR(20),

    amount DECIMAL(10,2),

    created_at TIMESTAMP,

    updated_at TIMESTAMP

);



-- 推荐索引

CREATE INDEX idx_orders_user_id ON orders(user_id);

CREATE INDEX idx_orders_status_created ON orders(status, created_at);

CREATE INDEX idx_orders_created_amount ON orders(created_at, amount);

总结

好的索引设计是数据库性能的基石。

不要盲目添加索引，要基于实际查询需求和数据分布来科学设计。

最后说一句(求关注，别白嫖我)

如果这篇文章对您有所帮助，或者有所启发的话，帮忙关注一下我的同名公众号：苏三说技术，您的支持是我坚持写作最大的动力。

求一键三连：点赞、转发、在看。

关注公众号：【苏三说技术】，在公众号中回复：进大厂，可以免费获取我最近整理的10万字的面试宝典，好多小伙伴靠这个宝典拿到了多家大厂的offer。

CSS 也要支持 if 了 ！！！CSS if() 函数来了！

CSS if() 函数允许在纯 CSS 中基于条件为属性赋值，无需 JavaScript 或预处理器。该函数已在 Chrome 137 发布。

过去常用的做法包括通过 JavaScript 切换类名、使用预处理器 mixin 或编写大量媒体查询。if() 将条件逻辑引入 CSS，使写法更直接、性能稳定。

原文 CSS 也要支持 if 了 ！！！CSS if() 函数来了！

工作原理

property: if(condition-1: value-1; condition-2: value-2; condition-3: value-3; else: default-value);

函数按顺序检查条件并应用第一个匹配的值；若没有条件匹配，则使用 else 的值。这一语义与常见编程语言一致，但实现于纯 CSS。

if() 的三种能力

样式查询（Style queries）

使用 style() 可响应 CSS 自定义属性：

.card {

  --status: attr(data-status type(<custom-ident>));



  border-color: if(style(--status: pending): royalblue; style(--status: complete): seagreen; style(--status: error): crimson; else: gray);

}

一个 data-status 属性即可驱动对应样式，无需额外工具类。

媒体查询（Media queries）

使用 media() 可以在属性内联定义响应式值，无需嵌套媒体查询块：

h1 {

  font-size: if(media(width >= 1200px): 3rem; media(width >= 768px): 2.5rem; media(width >= 480px): 2rem; else: 1.75rem);

}

特性检测（Feature detection）

使用 supports() 可在属性中直接进行特性检测，并提供明确回退：

.element {

  border-color: if(supports(color: lch(0 0 0)): lch(50% 100 150) ; supports(color: lab(0 0 0)): lab(50 100 -50) ; else: rgb(200, 100, 50));

}

真实用例

暗色模式示例

body {

  --theme: 'dark'; /* 通过 JavaScript 或用户偏好切换 */



  background: if(style(--theme: 'dark'): #1a1a1a; else: white);



  color: if(style(--theme: 'dark'): #e4e4e4; else: #333);

}

设计系统状态组件

.alert {

  --type: attr(data-type type(<custom-ident>));



  background: if(style(--type: success): #d4edda; style(--type: warning): #fff3cd; style(--type: danger): #f8d7da; style(--type: info): #d1ecf1; else: #f8f9fa);



  border-left: 4px solid if(style(--type: success): #28a745; style(--type: warning): #ffc107; style(--type: danger): #dc3545; style(--type: info): #17a2b8; else: #6c757d);

}

容器尺寸示例（简化媒体查询）

.container {

  width: if(media(width >= 1400px): 1320px; media(width >= 1200px): 1140px; media(width >= 992px): 960px; media(width >= 768px): 720px; media(width >= 576px): 540px; else: 100%);



  padding-inline: if(media(width >= 768px): 2rem; else: 1rem);

}

与现代 CSS 特性结合

.element {

  /* 搭配新的 light-dark() 函数 */

  color: if(style(--high-contrast: true): black; else: light-dark(#333, #e4e4e4));



  /* 搭配 CSS 自定义函数（@function） */

  padding: if(style(--spacing: loose): --spacing-function(2) ; style(--spacing: tight): --spacing-function(0.5) ; else: --spacing-function(1));

}

浏览器支持

支持情况（截至 2025 年 8 月）：

• ✅ Chrome/Edge：自 137 版起


• ✅ Chrome Android：自 139 版起


• ❌ Firefox：开发中


• ❌ Safari：在规划中


• ❌ Opera：尚未支持

在尚未完全支持的环境中，可采用如下写法：

.button {

  /* 所有浏览器的回退 */

  padding: 1rem 2rem;

  background: #007bff;



  /* 现代浏览器会自动覆盖 */

  padding: if(style(--size: small): 0.5rem 1rem; style(--size: large): 1.5rem 3rem; else: 1rem 2rem);



  background: if(style(--variant: primary): #007bff; style(--variant: success): #28a745; style(--variant: danger): #dc3545; else: #6c757d);

}

未来展望

CSS 工作组已经在推进扩展能力：

• 范围查询：if(style(--value > 100): ...)


• 逻辑运算符：if(style(--a: true) and style(--b: false): ...)


• 容器查询集成：更强的上下文感知

在使用前建议评估目标浏览器版本，并准备相应回退方案。

在日常的软件开发工作中，存储时间是一项基础且常见的需求。无论是记录数据的操作时间、金融交易的发生时间，还是行程的出发时间、用户的下单时间等等，时间信息与我们的业务逻辑和系统功能紧密相关。因此，正确选择和使用 MySQL 的日期时间类型至关重要，其恰当与否甚至可能对业务的准确性和系统的稳定性产生显著影响。

本文旨在帮助开发者重新审视并深入理解 MySQL 中不同的时间存储方式，以便做出更合适项目业务场景的选择。

不要用字符串存储日期

和许多数据库初学者一样，笔者在早期学习阶段也曾尝试使用字符串（如 VARCHAR）类型来存储日期和时间，甚至一度认为这是一种简单直观的方法。毕竟，'YYYY-MM-DD HH:MM:SS' 这样的格式看起来清晰易懂。

但是，这是不正确的做法，主要会有下面两个问题：

DATETIME 和 TIMESTAMP 选择

DATETIME 和 TIMESTAMP 是 MySQL 中两种非常常用的、用于存储包含日期和时间信息的数据类型。它们都可以存储精确到秒（MySQL 5.6.4+ 支持更高精度的小数秒）的时间值。那么，在实际应用中，我们应该如何在这两者之间做出选择呢？

下面我们从几个关键维度对它们进行对比：

时区信息

DATETIME 类型存储的是字面量的日期和时间值，它本身不包含任何时区信息。当你插入一个 DATETIME 值时，MySQL 存储的就是你提供的那个确切的时间，不会进行任何时区转换。

这样就会有什么问题呢？ 如果你的应用需要支持多个时区，或者服务器、客户端的时区可能发生变化，那么使用 DATETIME 时，应用程序需要自行处理时区的转换和解释。如果处理不当（例如，假设所有存储的时间都属于同一个时区，但实际环境变化了），可能会导致时间显示或计算上的混乱。

TIMESTAMP 和时区有关。存储时，MySQL 会将当前会话时区下的时间值转换成 UTC（协调世界时）进行内部存储。当查询 TIMESTAMP 字段时，MySQL 又会将存储的 UTC 时间转换回当前会话所设置的时区来显示。

这意味着，对于同一条记录的 TIMESTAMP 字段，在不同的会话时区设置下查询，可能会看到不同的本地时间表示，但它们都对应着同一个绝对时间点（UTC 时间）。这对于需要全球化、多时区支持的应用来说非常有用。

下面实际演示一下！

建表 SQL 语句：

CREATE TABLE `time_zone_test` (

  `id` bigint(20) NOT NULL AUTO_INCREMENT,

  `date_time` datetime DEFAULT NULL,

  `time_stamp` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,

  PRIMARY KEY (`id`)

) ENGINE=InnoDB DEFAULT CHARSET=utf8;

插入一条数据（假设当前会话时区为系统默认，例如 UTC+0）:：

INSERT INTO time_zone_test(date_time,time_stamp) VALUES(NOW(),NOW());

查询数据（在同一时区会话下）：

SELECT date_time, time_stamp FROM time_zone_test;

结果：

+---------------------+---------------------+

| date_time           | time_stamp          |

+---------------------+---------------------+

| 2020-01-11 09:53:32 | 2020-01-11 09:53:32 |

+---------------------+---------------------+

现在，修改当前会话的时区为东八区 (UTC+8):

SET time_zone = '+8:00';

再次查询数据：

# TIMESTAMP 的值自动转换为 UTC+8 时间

+---------------------+---------------------+

| date_time           | time_stamp          |

+---------------------+---------------------+

| 2020-01-11 09:53:32 | 2020-01-11 17:53:32 |

+---------------------+---------------------+

扩展：MySQL 时区设置常用 SQL 命令

# 查看当前会话时区

SELECT @@session.time_zone;

# 设置当前会话时区

SET time_zone = 'Europe/Helsinki';

SET time_zone = "+00:00";

# 数据库全局时区设置

SELECT @@global.time_zone;

# 设置全局时区

SET GLOBAL time_zone = '+8:00';

SET GLOBAL time_zone = 'Europe/Helsinki';

占用空间

下图是 MySQL 日期类型所占的存储空间（官方文档传送门：dev.mysql.com/doc/refman/…）：

在 MySQL 5.6.4 之前，DateTime 和 TIMESTAMP 的存储空间是固定的，分别为 8 字节和 4 字节。但是从 MySQL 5.6.4 开始，它们的存储空间会根据毫秒精度的不同而变化，DateTime 的范围是 58 字节，TIMESTAMP 的范围是 47 字节。

表示范围

TIMESTAMP 表示的时间范围更小，只能到 2038 年：

• DATETIME：'1000-01-01 00:00:00.000000' 到 '9999-12-31 23:59:59.999999'


• TIMESTAMP：'1970-01-01 00:00:01.000000' UTC 到 '2038-01-19 03:14:07.999999' UTC

性能

由于 TIMESTAMP 在存储和检索时需要进行 UTC 与当前会话时区的转换，这个过程可能涉及到额外的计算开销，尤其是在需要调用操作系统底层接口获取或处理时区信息时。虽然现代数据库和操作系统对此进行了优化，但在某些极端高并发或对延迟极其敏感的场景下，DATETIME 因其不涉及时区转换，处理逻辑相对更简单直接，可能会表现出微弱的性能优势。

为了获得可预测的行为并可能减少 TIMESTAMP 的转换开销，推荐的做法是在应用程序层面统一管理时区，或者在数据库连接/会话级别显式设置 time_zone 参数，而不是依赖服务器的默认或操作系统时区。

数值时间戳是更好的选择吗？

除了上述两种类型，实践中也常用整数类型（INT 或 BIGINT）来存储所谓的“Unix 时间戳”（即从 1970 年 1 月 1 日 00:00:00 UTC 起至目标时间的总秒数，或毫秒数）。

这种存储方式的具有 TIMESTAMP 类型的所具有一些优点，并且使用它的进行日期排序以及对比等操作的效率会更高，跨系统也很方便，毕竟只是存放的数值。缺点也很明显，就是数据的可读性太差了，你无法直观的看到具体时间。

时间戳的定义如下：

时间戳的定义是从一个基准时间开始算起，这个基准时间是「1970-1-1 00:00:00 +0:00」，从这个时间开始，用整数表示，以秒计时，随着时间的流逝这个时间整数不断增加。这样一来，我只需要一个数值，就可以完美地表示时间了，而且这个数值是一个绝对数值，即无论的身处地球的任何角落，这个表示时间的时间戳，都是一样的，生成的数值都是一样的，并且没有时区的概念，所以在系统的中时间的传输中，都不需要进行额外的转换了，只有在显示给用户的时候，才转换为字符串格式的本地时间。

数据库中实际操作：

-- 将日期时间字符串转换为 Unix 时间戳 (秒)

mysql> SELECT UNIX_TIMESTAMP('2020-01-11 09:53:32');

+---------------------------------------+

| UNIX_TIMESTAMP('2020-01-11 09:53:32') |

+---------------------------------------+

|                            1578707612 |

+---------------------------------------+

1 row in set (0.00 sec)



-- 将 Unix 时间戳 (秒) 转换为日期时间格式

mysql> SELECT FROM_UNIXTIME(1578707612);

+---------------------------+

| FROM_UNIXTIME(1578707612) |

+---------------------------+

| 2020-01-11 09:53:32       |

+---------------------------+

1 row in set (0.01 sec)

PostgreSQL 中没有 DATETIME

由于有读者提到 PostgreSQL（PG） 的时间类型，因此这里拓展补充一下。PG 官方文档对时间类型的描述地址：http://www.postgresql.org/docs/curren…。

可以看到，PG 没有名为 DATETIME 的类型：

• PG 的 TIMESTAMP WITHOUT TIME ZONE在功能上最接近 MySQL 的 DATETIME。它存储日期和时间，但不包含任何时区信息，存储的是字面值。


• PG 的TIMESTAMP WITH TIME ZONE (或 TIMESTAMPTZ) 相当于 MySQL 的 TIMESTAMP。它在存储时会将输入值转换为 UTC，并在检索时根据当前会话的时区进行转换显示。

对于绝大多数需要记录精确发生时间点的应用场景，TIMESTAMPTZ是 PostgreSQL 中最推荐、最健壮的选择，因为它能最好地处理时区复杂性。

总结

MySQL 中时间到底怎么存储才好？DATETIME?TIMESTAMP?还是数值时间戳？

并没有一个银弹，很多程序员会觉得数值型时间戳是真的好，效率又高还各种兼容，但是很多人又觉得它表现的不够直观。

《高性能 MySQL 》这本神书的作者就是推荐 TIMESTAMP，原因是数值表示时间不够直观。下面是原文：

每种方式都有各自的优势，根据实际场景选择最合适的才是王道。下面再对这三种方式做一个简单的对比，以供大家实际开发中选择正确的存放时间的数据类型：

选择建议小结：

• TIMESTAMP 的核心优势在于其内建的时区处理能力。数据库负责 UTC 存储和基于会话时区的自动转换，简化了需要处理多时区应用的开发。如果应用需要处理多时区，或者希望数据库能自动管理时区转换，TIMESTAMP 是自然的选择（注意其时间范围限制，也就是 2038 年问题）。


• 如果应用场景不涉及时区转换，或者希望应用程序完全控制时区逻辑，并且需要表示 2038 年之后的时间，DATETIME 是更稳妥的选择。


• 如果极度关注比较性能，或者需要频繁跨系统传递时间数据，并且可以接受可读性的牺牲（或总是在应用层转换），数值时间戳是一个强大的选项。

大家好，我是大华！

MySQL 有很多高级但实用的功能，能让你的查询变得更简洁、更高效。

今天分享 10 个我在工作中经常使用的 SQL 技巧，不用死记硬背，掌握了就能立刻提升你的数据库操作水平！

1. CTE（WITH 子句）——让复杂查询变清晰

-- 传统子查询，难以阅读

SELECT nickname 

FROM system_users 

WHERE dept_id IN (

    SELECT id FROM system_dept WHERE `name` = 'IT部'

);



-- 使用CTE，逻辑清晰

WITH ny_depts AS (

    SELECT id FROM system_dept WHERE `name` = 'IT部'

)

SELECT u.nickname

FROM system_users u

JOIN ny_depts nd ON u.dept_id = nd.id;

解释：

• WITH ny_depts AS (...)：先创建一个临时结果集，叫 ny_depts，里面只包含“IT部”的部门名称。


• SELECT u.nickname FROM system_users u JOIN ny_depts...：再从用户表中找出那些部门ID在ny_depts里的员工昵称。

好处：把找部门和找人分成两步，逻辑更清楚，比嵌套子查询好读多了。

2. 窗口函数 —— 不分组也能统计

SELECT 

    name,

    department,

    salary,

    RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS rank_in_dept,

    AVG(salary) OVER (PARTITION BY department) AS avg_salary

FROM employees;

解释：

• PARTITION BY department：按部门“分组”，但不合并行，每行仍然保留。


• RANK() OVER (...)：在每个部门内部，按薪水从高到低排名（相同薪水并列）。


• AVG(salary) OVER (...)：计算每个部门的平均工资，并显示在每一行里。

对比 GR0UP BY：GR0UP BY 会把多行合并成一行，而窗口函数保留原始行，同时加上统计值。

3. 条件聚合 —— 一行查出多个统计

SELECT 

    YEAR(created_at) AS year,

    COUNT(*) AS total,

    COUNT(CASE WHEN status = 'completed' THEN 1 END) AS completed,

    SUM(CASE WHEN status = 'completed' THEN amount ELSE 0 END) AS revenue

FROM orders

GR0UP BY YEAR(created_at);

解释：

• YEAR(created_at)：提取订单年份。


• COUNT(*)：该年总订单数。


• COUNT(CASE WHEN status = 'completed' THEN 1 END)：
  如果状态是 'completed'，就返回 1，否则返回 NULL；


• COUNT() 只统计非 NULL 值，所以这行就是“完成的订单数”。


• SUM(CASE WHEN ... THEN amount ELSE 0 END)：只对完成的订单求金额总和。

关键：不用写多个子查询，一条语句搞定全年报表！

4. 自连接 —— 同一张表自己连自己

SELECT e1.name, e2.name

FROM employees e1

JOIN employees e2 

  ON e1.department = e2.department

  AND e1.id < e2.id  

  AND ABS(e1.salary - e2.salary) <= e1.salary * 0.1;

解释：

• employees e1 JOIN employees e2：把员工表当成两个副本（e1 和 e2）来连接。


• e1.department = e2.department：只找同一个部门的人。


• e1.id < e2.id：避免重复配对（比如 Alice-Bob 和 Bob-Alice 只保留一个）。


• ABS(...)：计算两人薪水差是否 ≤ 10%。

用途：找“相似记录”“配对关系”“上下级”等场景非常有用。

5. EXISTS 替代 IN —— 更高效的存在判断

SELECT name FROM customers c

WHERE EXISTS (

    SELECT 1 FROM orders o 

    WHERE o.customer_id = c.id AND o.amount > 1000

);

解释：

• 对每一位客户 c，检查是否存在一笔订单满足：
  
  
  
  • 订单的 customer_id 等于这个客户的 id
  
  
  • 订单金额 > 1000
  
  
  
  


• SELECT 1：这里不需要返回具体字段，只要知道“有没有”就行，所以用 1 最轻量。


• 为什么快？：一旦找到一条匹配订单，就立刻停止搜索，不像 IN 可能要加载全部订单 ID。

注意：如果子查询可能返回 NULL，IN 会失效（因为 x IN (..., NULL) 永远为 UNKNOWN），而 EXISTS 不受影响。

6. JSON 函数 —— 轻松读取 JSON 字段

SELECT 

    name,

    profile->>'$.address.city' AS city,

    JSON_EXTRACT(profile, '$.age') AS age

FROM users

WHERE profile->>'$.city' = 'Beijing';

解释：

• profile 是一个 JSON 类型字段，比如：{"address": {"city": "Beijing"}, "age": 30}


• profile->>'$.address.city'：
  
  
  
  • ->> 是简写，等价于 JSON_UNQUOTE(JSON_EXTRACT(...))
  
  
  • 返回字符串 "Beijing"（去掉引号）
  
  
  
  


• JSON_EXTRACT(profile, '$.age')：返回 30（带类型，可能是数字）


• WHERE profile->>'$.city' = 'Beijing'：筛选城市是北京的用户。

适用场景：用户偏好、动态表单、日志等结构不固定的字段。

7. 生成列 —— 数据库自动帮你算

CREATE TABLE products (

    id INT PRIMARY KEY,

    width DECIMAL(10,2),

    height DECIMAL(10,2),

    area DECIMAL(10,2) AS (width * height) STORED

);



INSERT INTO products (id, width, height) VALUES (1, 5, 10);

解释：

• area DECIMAL(...) AS (width * height) STORED：
  
  
  
  • 这是一个“存储型生成列”，数据库会自动计算 width * height 并存下来。
  
  
  • 如果不加 STORED，就是“虚拟列”（每次查询时计算，不占存储）。
  
  
  
  


• 插入时只需给 width 和 height，area 自动变成 50。

优势：避免应用层重复计算，还能给 area 加索引加速查询！

8. 多表更新 —— 一条语句更新关联数据

UPDATE customers c

JOIN (

    SELECT customer_id, SUM(amount) AS total

    FROM orders

    GR0UP BY customer_id

) o ON c.id = o.customer_id

SET c.total_spent = o.total;

解释：

• 子查询 o：先按客户 ID 统计每个人的总消费。


• UPDATE customers c JOIN o ...：把客户表和统计结果连接起来。


• SET c.total_spent = o.total：直接把统计值写回客户表。

好处：不用在程序里循环“查一个、改一个”，减少网络开销，保证原子性。

9. GR0UP_CONCAT —— 多行变一行

SELECT 

    department,

    GR0UP_CONCAT(name ORDER BY salary DESC SEPARATOR ', ') AS members

FROM employees

GR0UP BY department;

解释：

• GR0UP BY department：按部门分组。


• GR0UP_CONCAT(name ...)：把每个部门的所有员工名字拼成一个字符串。


• ORDER BY salary DESC：按薪水从高到低排序后再拼接。


• SEPARATOR ', '：用逗号加空格分隔名字。

典型用途：导出名单、展示标签、汇总明细等。

默认最多拼 1024 字符，可通过 SET SESSION group_concat_max_len = 1000000; 调大。

10. INSERT ... ON DUPLICATE KEY UPDATE —— 智能插入/更新

INSERT INTO page_views (page_url, view_date, view_count)

VALUES ('/home', CURDATE(), 1)

ON DUPLICATE KEY UPDATE 

    view_count = view_count + 1;

解释：

• 尝试插入一条新记录：页面 /home，今天日期，访问次数为 1。


• 如果因为唯一索引冲突（比如 (page_url, view_date) 是唯一键）导致插入失败：
  
  
  
  • 就执行 ON DUPLICATE KEY UPDATE 部分
  
  
  • 把原有的 view_count 加 1
  
  
  
  


• 效果：第一次访问创建记录，之后每次访问自动 +1，完美实现计数器！

前提：表必须有主键或唯一索引，否则不会触发更新。

本文首发于公众号：程序员刘大华，专注分享前后端开发的实战笔记。关注我，少走弯路，一起进步！

📌往期精彩

《async/await 到底要不要加 try-catch？异步错误处理最佳实践》

《如何查看 SpringBoot 当前线程数？3 种方法亲测有效》

《Java 开发必看：什么时候用 for，什么时候用 Stream？》

《别再乱 new ArrayList！8 大 Java 容器选型案例，一篇看懂》

实战推荐：

• 不仅免费，还开源？这个 AI Mock 神器我必须曝光它


• ⚡ 一个Vue自定义指令搞定丝滑拖拽列表，告别复杂组件封装
  


• 🔥 这才是 Vue 驱动的 Chrome 插件工程化正确打开方式


• 女朋友又给我出难题了：解锁网页禁用复制 + 一键提取图片文字

还在为每个列表页写重复的分页代码而烦恼吗？ 还在复制粘贴 currentPage、pageSize、loading 等状态吗？ 一个 Hook 帮你解决所有分页痛点，减少90%重复代码

背景与痛点

在后台管理系统开发中，分页列表查询非常常见，我们通常需要处理：

• 当前页、页大小、总数等分页状态


• 加载中、错误处理等请求状态


• 搜索、刷新、翻页等分页操作


• 数据缓存和重复请求处理

这些重复逻辑分散在各个组件中，维护起来很麻烦。

为了解决这个烦恼，我专门封装了分页数据管理 Hook。现在只需要几行代码，就能轻松实现分页查询，省时又高效，减少了大量重复劳动

使用前提 - 接口格式约定

查询接口返回的数据格式：

{

  list: [        // 当前页数据数组

    { id: 1, name: 'user1' },

    { id: 2, name: 'user2' }

  ],

  total: 100     // 数据总条数

}

先看效果：分页查询只需几行代码！

import usePageFetch from '@/hooks/usePageFetch' // 引入分页查询 Hook，封装了分页逻辑和状态管理

import { getUserList } from '@/api/user'        // 引入请求用户列表的 API 方法



// 使用 usePageFetch Hook 实现分页数据管理

const {

  currentPage,      // 当前页码

  pageSize,         // 每页条数

  total,            // 数据总数

  data,             // 当前页数据列表

  isFetching,       // 加载状态，用于控制 loading 效果

  search,           // 搜索方法

  onSizeChange,     // 页大小改变事件处理方法

  onCurrentChange   // 页码改变事件处理方法

} = usePageFetch(

  getUserList,  // 查询API

  { initFetch: false }  // 是否自动请求一次（组件挂载时自动拉取第一页数据）     

)

这样子每次分页查询只需要引入hook，然后传入查询接口就好了，减少了大量重复劳动

解决方案

我设计了两个相互配合的 Hook：

• useFetch：基础请求封装，处理请求状态和缓存


• usePageFetch：分页逻辑封装，专门处理分页相关的状态和操作

usePageFetch (分页业务层)

├── 管理 page / pageSize / total 状态

├── 处理搜索、刷新、翻页逻辑  

├── 统一错误处理和用户提示

└── 调用 useFetch (请求基础层)

    ├── 管理 loading / data / error 状态

    ├── 可选缓存机制（避免重复请求）

    └── 成功回调适配不同接口格式

核心实现

useFetch - 基础请求封装

// hooks/useFetch.js

import { ref } from 'vue'



const Cache = new Map()



/**

 * 基础请求 Hook

 * @param {Function} fn - 请求函数

 * @param {Object} options - 配置选项

 * @param {*} options.initValue - 初始值

 * @param {string|Function} options.cache - 缓存配置

 * @param {Function} options.onSuccess - 成功回调

 */

function useFetch(fn, options = {}) {

  const isFetching = ref(false)

  const data = ref()

  const error = ref()



  // 设置初始值

  if (options.initValue !== undefined) {

    data.value = options.initValue

  }



  function fetch(...args) {

    isFetching.value = true

    let promise



    if (options.cache) {

      const cacheKey = typeof options.cache === 'function'

        ? options.cache(...args)

        : options.cache || `${fn.name}_${args.join('_')}`



      promise = Cache.get(cacheKey) || fn(...args)

      Cache.set(cacheKey, promise)

    } else {

      promise = fn(...args)

    }



    // 成功回调处理

    if (options.onSuccess) {

      promise = promise.then(options.onSuccess)

    }



    return promise

      .then(res => {

        data.value = res

        isFetching.value = false

        error.value = undefined

        return res

      })

      .catch(err => {

        isFetching.value = false

        error.value = err

        return Promise.reject(err)

      })

  }



  return {

    fetch,

    isFetching,

    data,

    error

  }

}



export default useFetch

usePageFetch - 分页逻辑封装

// hooks/usePageFetch.js

import { ref, onMounted, toRaw, watch } from 'vue'

import useFetch from './useFetch' // 即上面的hook ---> useFetch 

import { ElMessage } from 'element-plus'



/**

 * 分页数据管理 Hook

 * @param {Function} fn - 请求函数

 * @param {Object} options - 配置选项

 * @param {Object} options.params - 默认参数

 * @param {boolean} options.initFetch - 是否自动初始化请求

 * @param {Ref} options.formRef - 表单引用

 */

function usePageFetch(fn, options = {}) {

  // 分页状态

  const page = ref(1)

  const pageSize = ref(10)

  const total = ref(0)

  const data = ref([])

  const params = ref()

  const pendingCount = ref(0)



  // 初始化参数

  params.value = options.params



  //  使用基础请求 Hook

  const { isFetching, fetch: fetchFn, error, data: originalData } = useFetch(fn)



  //  核心请求方法

  const fetch = async (searchParams, pageNo, size) => {

    try {

      // 更新分页状态

      page.value = pageNo

      pageSize.value = size

      params.value = searchParams



      // 发起请求

      await fetchFn({

        page: pageNo,

        pageSize: size,

        // 使用 toRaw 避免响应式对象问题

        ...(searchParams ? toRaw(searchParams) : {})

      })



      // 处理响应数据

      data.value = originalData.value?.list || []

      total.value = originalData.value?.total || 0

      pendingCount.value = originalData.value?.pendingCounts || 0

    } catch (e) {

      console.error('usePageFetch error:', e)

      ElMessage.error(e?.msg || e?.message || '请求出错')

      // 清空数据，提供更好的用户体验

      data.value = []

      total.value = 0

    }

  }



  //  搜索 - 重置到第一页

  const search = async (searchParams) => {

    await fetch(searchParams, 1, pageSize.value)

  }



  // 刷新当前页

  const refresh = async () => {

    await fetch(params.value, page.value, pageSize.value)

  }



  // 改变页大小

  const onSizeChange = async (size) => {

    await fetch(params.value, 1, size) // 重置到第一页

  }



  // 切换页码

  const onCurrentChange = async (pageNo) => {

    await fetch(params.value, pageNo, pageSize.value)

  }



  // 组件挂载时自动请求

  onMounted(() => {

    if (options.initFetch !== false) {

      search(params.value)

    }

  })



  // 监听表单引用变化（可选功能）

  watch(

    () => options.formRef,

    (formRef) => {

      if (formRef) {

        console.log('Form ref updated:', formRef)

      }

    }

  )



  return {

    // 分页状态

    currentPage: page,

    pageSize,

    total,

    pendingCount,

    

    // 数据状态

    data,

    originalData,

    isFetching,

    error,

    

    // 操作方法

    search,

    refresh,

    onSizeChange,

    onCurrentChange

  }

}



export default usePageFetch