你是不是也有这些困惑

看项目文档，各种名词扑面而来：

• 流程引擎（Flowable、Camunda）


• 工作流（Activiti）


• 规则引擎（Drools）


• 编排系统（LiteFlow）


• 表达式引擎（QLExpress、Aviator）


• DAG调度（Airflow、DolphinScheduler）


• 任务编排（Temporal、Conductor）


• BPMN、Saga、Event-Driven...

每个框架都说自己能解决问题，每个概念看起来都差不多。

新手一脸懵逼，老手也经常搞混。

干了20年，我也被这些东西搞晕过。今天不讲那些虚的，直接告诉你怎么选。

答案很简单：别管这些名词，问自己四个问题就够了。

忘掉那些名词，只问四个问题

看了一堆框架介绍还是不知道选哪个？正常，因为你在纠结概念。

别纠结了，概念都是虚的。问自己四个问题，立刻就清楚了。

问题1：你是要干活，还是改状态？

这是最关键的一个问题。搞清楚这个，一大半框架就排除了。

改状态是什么意思？

请假审批：

员工提交 → 主管看了说"行" → HR看了说"行" → 完成



整个过程：

- 没有计算

- 没有数据转换

- 没有调用外部系统

- 就是状态从 pending 变成 approved



这就是纯改状态。

干活是什么意思？

订单处理：

下单 → 扣库存 → 调支付接口 → 调物流接口 → 发货



整个过程：

- 要计算金额

- 要调用外部API

- 要处理数据

- 要执行业务逻辑



这就是干活。

判断标准：

• 改状态：就是让人点"同意"或"拒绝"，除了改个字段，啥也没干


• 干活：要计算、要调API、要处理数据

对应框架：

• 改状态 → BPMN系（Flowable、Camunda）


• 干活 → 继续往下判断

问题2：主要是人处理，还是机器执行？

人处理：

审批流程：

- 主管要看文档

- 主管要做判断

- 主管要点按钮

- 然后等下一个人



特点：大部分时间在等人

机器执行：

数据处理：

- 读数据库

- 清洗数据

- 转换格式

- 写入目标表



特点：机器自己跑，不用人管

对应框架：

• 人为主 → BPMN系（Flowable、Camunda）


• 机器为主 → 继续往下判断

问题3：是本地方法，还是跨系统调用？

本地方法：

营销规则：

- 判断用户是不是VIP

- 计算折扣

- 返回结果



都在一个应用里，不用调外部接口

跨系统调用：

订单流程：

- 调库存系统（HTTP）

- 调支付系统（HTTP）

- 调物流系统（HTTP）



要跨多个服务

对应框架：

• 本地 → 表达式系、脚本系（QLExpress、LiteFlow）


• 跨系统 → DAG系、服务编排系（Airflow、Temporal）

问题4：自己玩，还是要搞生态？

自己玩：

你的团队自己维护：

- 规则你们自己写

- 代码你们自己改

- 不需要外部开发者

搞生态：

做平台，让别人扩展：

- 客户可以上传插件

- 第三方可以写脚本

- 需要沙箱隔离

对应技术：

• 自己玩 → 表达式 + 代码（QLExpress、Aviator）


• 搞生态 → Groovy脚本、插件机制

那些让人头疼的框架，到底是干什么的

四个问题问完，你大概知道方向了。现在看看具体框架都是什么情况。

不用全看，只看和你匹配的那一类就行。

BPMN系：Flowable、Camunda、Activiti

适合场景：

• 纯人工审批流程


• 需要流程图可视化


• 需要历史记录追溯


• 大公司、强合规要求

典型例子：

• 请假审批


• 报销审批


• 合同审批


• 采购流程

核心特点：

• 本质就是改状态


• 大部分时间在等人


• 业务价值为0（只是流程管理）


• 技术难度不高（就是状态机）

什么时候用：

• 大公司（100+人），有几十个审批流程要管理


• 金融、政府等强合规行业


• 需要标准化流程管理

什么时候别用：

• 小公司（别用，钉钉审批就够了）


• 没有复杂审批需求（自己写100行代码搞定）


• 为了"企业级"而用（过度设计）

DAG系：Airflow、DolphinScheduler、Prefect

适合场景：

• 数据处理任务


• 离线批处理


• 定时调度


• 任务有依赖关系

典型例子：

• 数据ETL


• 报表生成


• 数据清洗


• 机器学习Pipeline

核心特点：

• 纯机器执行


• 长时间运行（小时、天级）


• 任务之间有依赖（A完成才能B）


• 需要调度和监控

什么时候用：

• 数据团队做离线处理


• 有复杂的任务依赖关系


• 需要定时调度（每天、每周）

什么时候别用：

• 实时性要求高的（秒级响应）


• 简单的定时任务（用Cron就够了）


• 没有依赖关系的任务

表达式/脚本系：QLExpress、Aviator、LiteFlow、Groovy

适合场景：

• 规则计算


• 业务流程编排


• 本地方法调用


• 需要动态配置

典型例子：

• 营销活动规则（满减、折扣）


• 风控规则（黑名单、评分）


• 订单流程（本地编排）


• 积分计算

QLExpress / Aviator（表达式）：

• 优点：性能好、类Java语法、团队容易上手


• 缺点：功能受限、只能简单计算


• 适合：自己团队玩、简单规则

Groovy（脚本）：

• 优点：功能完整、可以调复杂API


• 缺点：性能差、调试难、类型不安全


• 适合：要搞插件生态、客户自定义逻辑

LiteFlow（编排）：

• 优点：可视化编排、组件复用


• 缺点：学习成本、维护成本


• 适合：流程确实复杂、经常变化

什么时候用：

• 规则经常变（不想每次改代码发版）


• 流程需要配置化


• 有一定复杂度（10+个分支）

什么时候别用：

• 简单的if-else（直接写代码）


• 流程固定不变（没必要配置化）


• 为了"灵活"而牺牲性能

服务编排系：Temporal、Cadence、Conductor

适合场景：

• 微服务编排


• 分布式事务


• 长时间运行的业务流程


• 需要补偿机制

典型例子：

• 订单流程（支付 → 发货 → 签收）


• 旅游预订（机票 + 酒店 + 门票）


• 跨系统流程


• Saga模式

核心特点：

• 支持长时间运行（天级）


• 支持失败重试


• 支持补偿逻辑


• 状态持久化

什么时候用：

• 微服务架构，需要编排多个服务


• 需要分布式事务


• 流程可能运行很久（几小时、几天）

什么时候别用：

• 单体应用（没有跨服务需求）


• 简单的API调用（直接用HTTP就行）


• 实时性要求极高的（毫秒级）

懒得看？直接照这个选

如果你嫌上面内容太多，直接看这个决策树。

跟着问题一步步走，到底了就知道该用什么。

开始

  ↓

主要是人审批吗？

  ↓ 是

  用 Flowable/Camunda（大公司）或钉钉审批（小公司）

  

  ↓ 否

是长时间运行的任务吗（>10分钟）？

  ↓ 是

  用 Airflow/DolphinScheduler

  

  ↓ 否

需要跨系统调用吗？

  ↓ 是

  用 Temporal/Conductor（微服务）或 Airflow（数据处理）

  

  ↓ 否

逻辑很复杂吗（>10个分支）？

  ↓ 是

  用 LiteFlow（编排）或 QLExpress（规则）

  

  ↓ 否

需要频繁修改规则吗？

  ↓ 是

  用 QLExpress/Aviator

  

  ↓ 否

直接写代码！

具体场景怎么选

理论说完了，看几个实际例子。看看你的场景和哪个像。

场景1：请假审批

特征：

• 纯人工审批


• 状态流转


• 需要历史记录

选型：

• 小公司：钉钉/企业微信审批


• 大公司：Flowable/Camunda


• 自己开发：状态机 + 数据库

场景2：电商订单流程

特征：

• 要调支付、库存、物流接口


• 有失败重试和补偿


• 短事务（分钟级）

选型：

• 复杂场景：Temporal/Cadence


• 简单场景：LiteFlow + 消息队列


• 最简单：直接写代码 + 状态机

场景3：数据ETL

特征：

• 纯机器执行


• 长时间运行


• 任务有依赖

选型：

• 标准方案：Airflow/DolphinScheduler


• 简单场景：XXL-Job

场景4：营销活动规则

特征：

• 规则计算


• 经常变化


• 本地方法

选型：

• 简单规则：QLExpress/Aviator


• 复杂规则：Drools


• 有编排需求：LiteFlow

很多人踩过的坑

说几个常见的错误，别重复踩坑。

误区1：追求"企业级架构"

错误做法：

20人的创业公司，上了Flowable、Camunda、Airflow一整套



正确做法：

能用100行代码解决就别上框架

误区2：为了灵活性而牺牲性能

错误做法：

所有逻辑都用Groovy脚本，方便修改



正确做法：

核心逻辑用Java写，只把经常变的部分配置化

误区3：过度抽象

错误做法：

3个简单流程，非要搞个"流程引擎"



正确做法：

3个流程就3个方法，直接写代码

误区4：混淆概念

错误理解：

"我需要流程编排，所以要用Flowable"



正确理解：

先搞清楚你要干活还是改状态

是人审批还是机器执行

几句大实话

最后说几句掏心窝的话。

1. 先用最简单的方案

遇到问题：

第一反应不是"上框架"

而是"能不能写100行代码搞定"



90%的情况，100行代码就够了

2. 遇到瓶颈再优化

流程很乱了 → 重构代码

改动很频繁 → 考虑配置化

管理不过来 → 考虑框架



别提前优化

3. 根据团队规模选择

小团队（<20人）：

- 能不用框架就不用

- 钉钉审批、Cron、直接写代码



中等团队（20-100人）：

- 流程<10个：自己写

- 流程>10个：考虑轻量级框架



大团队（>100人）：

- 需要标准化管理

- 可以考虑成熟框架

4. 看业务特点

强合规（金融、政府）：

- 必须用标准化工具

- Flowable是选择之一



数据密集：

- Airflow是标准方案



微服务架构：

- Temporal值得考虑



简单CRUD：

- 别折腾，写代码

说到底，就这么点事

看完还觉得复杂？那就记住这四个问题：

四个问题问完，基本就知道该用什么了。

那些"企业级"、"先进架构"、"灵活扩展"的词，都是包装。

看透本质，别被忽悠。

能用100行代码解决的，就别上框架。

技术是为业务服务的，不是为了炫技。

务实点，别整那些虚的。

就这样。

面试导航 是一个专注于前、后端技术学习和面试准备的 免费 学习平台，提供系统化的技术栈学习，深入讲解每个知识点的核心原理，帮助开发者构建全面的技术体系。平台还收录了大量真实的校招与社招面经，帮助你快速掌握面试技巧，提升求职竞争力。如果你想加入我们的交流群，欢迎通过微信联系：yunmz777。

在需要服务器实时向浏览器推送数据的场景中，很多人第一反应是使用 WebSocket，但其实还有一种更轻量、更简单的解决方案 —— SSE（Server-Sent Events）。它天生适合“服务器单向推送”，而且浏览器原生支持、无需额外协议、写起来极其简单。

本文将从原理、协议、代码、对比、性能、安全等多个方面，帮你系统了解 SSE 的底层机制与实际应用。

🧠 一、什么是 SSE？

SSE，全称 Server-Sent Events，是 HTML5 提出的标准之一，用于建立一种 客户端到服务器的持久连接，允许服务器在数据更新时，主动将事件推送到客户端。

通俗点讲，它就像是：

浏览器发起了一个请求，服务器就打开一个“水管”，源源不断地往客户端输送数据流，直到你手动关闭它。

它基于标准的 HTTP 协议，与传统请求-响应的“短连接”模式不同，SSE 是长连接，并且保持活跃，类似于“实时通知通道”。

🛠️ 二、SSE 的通信机制与协议细节

✅ 客户端：使用 EventSource 建立连接

const sse = new EventSource("/events");



sse.onmessage = (event) => {

  console.log("新消息：", event.data);

};

EventSource 是浏览器自带的，直接用就行，不用装库。它会自动处理连接、断线重连这些问题，基本不需要你操心，消息来了就能收到。

原生 EventSource 的使用限制

虽然原生的 EventSource 对象很方便，但也存在很多的限制，它只能发送 GET 请求，不支持设置请求方法，也不能附带请求体。

你不能通过 EventSource 设置如 Authorization、token 等自定义请求头用于鉴权。

例如，下面这样是不被支持的：

const sse = new EventSource("/events", {

  headers: {

    Authorization: "Bearer xxx",

  },

});

这在 fetch 里没问题，但在 EventSource 里完全不支持。直接报错，浏览器压根不给你设置 headers。

EventSource 虽然支持跨域，但得服务器配合设置 CORS，而且还不能用 withCredentials。换句话说，你不能让它自动带上 cookie，那些基于 cookie 登录的服务就麻烦了。

如果你需要传 token 或做鉴权，可以使用查询参数传 token，比如这样：

const token = "abc123";

const sse = new EventSource(`/events?token=${token}`);

✅ 服务器：响应格式必须为 text/event-stream

服务器需要返回特定格式的数据流，并设置以下 HTTP 响应头：

Content-Type: text/event-stream

Cache-Control: no-cache

Connection: keep-alive

如下图所示：

然后每条消息遵循下面的格式：

data: Hello from server

id: 1001

event: message

如下图所示：

在上面的内容中，主要有以下解释，如下表格所示：

🔄 三、SSE vs WebSocket vs 轮询，对比总结

🚀 四：如何在 NextJs 中实现

NextJS 作为一个现代化的 React 框架，非常适合实现 SSE。下面我们将通过一个完整的实例来展示如何在 NextJS 应用中实现服务器发送事件。

前端代码如下：

"use client";



import React, { useState, useEffect, useRef } from "react";



export default function SSEDemo() {

  const [sseData, setSseData] = useState<{

    time?: string;

    value?: string;

    message?: string;

    error?: string;

  } | null>(null);

  const [connected, setConnected] = useState(false);

  const [reconnecting, setReconnecting] = useState(false);

  const [reconnectCount, setReconnectCount] = useState(0);

  const eventSourceRef = useRef<EventSource | null>(null);

  const reconnectTimeoutRef = useRef<NodeJS.Timeout | null>(null);



  // 建立SSE连接

  const connectSSE = () => {

    // 关闭任何现有连接

    if (eventSourceRef.current) {

      eventSourceRef.current.close();

    }



    // 清除任何挂起的重连计时器

    if (reconnectTimeoutRef.current) {

      clearTimeout(reconnectTimeoutRef.current);

    }



    try {

      setReconnecting(true);



      // 添加时间戳防止缓存

      const eventSource = new EventSource(`/api/sse?t=${Date.now()}`);

      eventSourceRef.current = eventSource;



      eventSource.onopen = () => {

        setConnected(true);

        setReconnecting(false);

        setReconnectCount(0);

        console.log("SSE连接已建立");

      };



      eventSource.onmessage = (event) => {

        try {

          const data = JSON.parse(event.data);

          setSseData(data);

        } catch (error) {

          console.error("解析SSE数据失败:", error);

        }

      };



      eventSource.onerror = (error) => {

        console.error("SSE连接错误:", error);

        setConnected(false);

        eventSource.close();



        // 增加重连次数

        setReconnectCount((prev) => prev + 1);



        // 随着失败次数增加，增加重连间隔（指数退避策略）

        const reconnectDelay = Math.min(

          30000,

          1000 * Math.pow(2, Math.min(reconnectCount, 5))

        );



        setReconnecting(true);

        setSseData((prev) => ({

          ...prev,

          message: `连接失败，${reconnectDelay / 1000}秒后重试...`,

        }));



        // 尝试重新连接

        reconnectTimeoutRef.current = setTimeout(() => {

          connectSSE();

        }, reconnectDelay);

      };

    } catch (error) {

      console.error("创建SSE连接失败:", error);

      setConnected(false);

      setReconnecting(true);



      // 5秒后重试

      reconnectTimeoutRef.current = setTimeout(() => {

        connectSSE();

      }, 5000);

    }

  };



  useEffect(() => {

    connectSSE();



    // 定期检查连接是否健康

    const healthCheck = setInterval(() => {

      if (eventSourceRef.current && !connected) {

        // 如果存在连接但状态是未连接，尝试重新连接

        connectSSE();

      }

    }, 30000);



    // 清理函数

    return () => {

      if (eventSourceRef.current) {

        eventSourceRef.current.close();

      }

      if (reconnectTimeoutRef.current) {

        clearTimeout(reconnectTimeoutRef.current);

      }

      clearInterval(healthCheck);

    };

  }, []);



  return (

    <div className="min-h-screen bg-gradient-to-b from-slate-900 to-slate-800 text-white flex flex-col items-center justify-center p-4">

      <div className="w-full max-w-md bg-slate-800 rounded-xl shadow-2xl overflow-hidden">

        <div className="p-6 border-b border-slate-700">

          <h1 className="text-3xl font-bold text-center text-blue-400">

            SSE 演示

          </h1>

          <div className="mt-2 flex items-center justify-center">

            <div

              className={`h-3 w-3 rounded-full mr-2 ${

                connected

                  ? "bg-green-500"

                  : reconnecting

                  ? "bg-yellow-500 animate-pulse"

                  : "bg-red-500"

              }`}

            ></div>

            <p className="text-sm text-slate-300">

              {connected

                ? "已连接到服务器"

                : reconnecting

                ? `正在重新连接 (尝试 ${reconnectCount})`

                : "连接断开"}

            </p>

          </div>



          {!connected && (

            <button

              onClick={() => connectSSE()}

              className="mt-3 px-3 py-1 bg-blue-600 text-sm text-white rounded-md mx-auto block hover:bg-blue-700"

            >

              手动重连

            </button>

          )}

        </div>



        {sseData && (

          <div className="p-6">

            {sseData.error ? (

              <div className="rounded-lg bg-red-900/30 p-4 mb-4 text-center border border-red-800">

                <p className="text-lg text-red-300">{sseData.error}</p>

              </div>

            ) : sseData.message ? (

              <div className="rounded-lg bg-slate-700 p-4 mb-4 text-center">

                <p className="text-lg text-blue-300">{sseData.message}</p>

              </div>

            ) : (

              <div className="space-y-4">

                <div className="flex justify-between items-center">

                  <span className="text-slate-400">时间:</span>

                  <span className="font-mono bg-slate-700 px-3 py-1 rounded-md text-blue-300">

                    {sseData.time &&

                      new Date(sseData.time).toLocaleTimeString()}

                  </span>

                </div>

                <div className="flex justify-between items-center">

                  <span className="text-slate-400">随机值:</span>

                  <span className="font-mono bg-slate-700 px-3 py-1 rounded-md text-green-300">

                    {sseData.value}

                  </span>

                </div>

              </div>

            )}

          </div>

        )}



        {!sseData && (

          <div className="p-6 text-center text-slate-400">

            <p>等待数据中...</p>

            <div className="mt-4 flex justify-center">

              <div className="animate-spin rounded-full h-8 w-8 border-t-2 border-b-2 border-blue-400"></div>

            </div>

          </div>

        )}

      </div>

    </div>

  );

}

在上面的代码中，我们用的是浏览器的原生 EventSource，加了个时间戳 t=${Date.now()} 是为了防止缓存，确保每次都是新的连接。

然后我们监听三个事件：

当连接出错时，我们做了这些事：

而且页面上也有提示「正在重连」和「手动重连」的按钮，体验很人性化。

接下来我们看看后端代码，如下：

export async function GET() {

  // 标记连接是否仍然有效，

  let connectionClosed = false;



  // 使用Next.js的流式响应处理

  return new Response(

    new ReadableStream({

      start(controller) {

        const encoder = new TextEncoder();



        // 监测响应对象是否被关闭

        const abortController = new AbortController();

        const signal = abortController.signal;



        signal.addEventListener("abort", () => {

          connectionClosed = true;

          cleanup();

        });



        // 安全发送数据函数

        const safeEnqueue = (data: string) => {

          if (connectionClosed) return;

          try {

            controller.enqueue(encoder.encode(data));

          } catch (error) {

            console.error("SSE发送错误:", error);

            connectionClosed = true;

            cleanup();

          }

        };



        // 发送初始数据

        safeEnqueue(`data: ${JSON.stringify({ message: "连接已建立" })}\n\n`);



        // 定义interval引用

        let heartbeatInterval: NodeJS.Timeout | null = null;

        let dataInterval: NodeJS.Timeout | null = null;



        // 清理所有资源

        const cleanup = () => {

          if (heartbeatInterval) clearInterval(heartbeatInterval);

          if (dataInterval) clearInterval(dataInterval);



          // 尝试安全关闭控制器

          try {

            if (!connectionClosed) {

              controller.close();

            }

          } catch (e) {

            // 忽略关闭时的错误

          }

        };



        // 设置10秒的心跳间隔，避免连接超时

        heartbeatInterval = setInterval(() => {

          if (connectionClosed) {

            cleanup();

            return;

          }

          safeEnqueue(": heartbeat\n\n");

        }, 10000);



        // 每秒发送一次数据

        dataInterval = setInterval(() => {

          if (connectionClosed) {

            cleanup();

            return;

          }



          try {

            const data = {

              time: new Date().toISOString(),

              value: Math.random().toFixed(3),

            };

            safeEnqueue(`data: ${JSON.stringify(data)}\n\n`);

          } catch (error) {

            console.error("数据生成错误:", error);

            connectionClosed = true;

            cleanup();

          }

        }, 1000);



        // 60秒后自动关闭连接（可根据需要调整）

        setTimeout(() => {

          // 只有当连接仍然活跃时才发送消息和关闭

          if (!connectionClosed) {

            try {

              safeEnqueue(

                `data: ${JSON.stringify({

                  message: "连接即将关闭，请刷新页面重新连接",

                })}\n\n`

              );

              connectionClosed = true;

              cleanup();

            } catch (e) {

              // 忽略关闭时的错误

            }

          }

        }, 60000);

      },

      cancel() {

        // 当流被取消时调用

        connectionClosed = true;

      },

    }),

    {

      headers: {

        "Content-Type": "text/event-stream",

        "Cache-Control": "no-cache, no-transform",

        Connection: "keep-alive",

        "Access-Control-Allow-Origin": "*",

        "X-Accel-Buffering": "no", // 适用于某些代理服务器如Nginx

      },

    }

  );

}

这段代码是 Next.js 后端 API 路由，用来实现 SSE（Server-Sent Events）长连接。我们使用了 ReadableStream 创建一个持续向前端推送数据的响应流，并配合 AbortSignal 检测连接是否被关闭：

return new Response(new ReadableStream({ start(controller) { ... } }), { headers: {...} });

一开始，服务器通过 safeEnqueue 安全地向客户端发送一条欢迎消息：

safeEnqueue(`data: ${JSON.stringify({ message: "连接已建立" })}\n\n`);

随后每秒生成一条数据（当前时间和随机值）推送给前端，并通过 setInterval 定时发送：

const data = {

  time: new Date().toISOString(),

  value: Math.random().toFixed(3),

};

safeEnqueue(`data: ${JSON.stringify(data)}\n\n`);

为了保持连接活跃，避免浏览器或代理中断连接，我们每 10 秒发送一次心跳包（以冒号开头的注释）：

safeEnqueue(": heartbeat\n\n");

还加了一个自动关闭机制——60 秒后主动断开连接并提示前端刷新：

safeEnqueue(

  `data: ${JSON.stringify({ message: "连接即将关闭，请刷新页面重新连接" })}\n\n`

);

整个数据发送过程都包裹在 safeEnqueue 中，确保连接断开时能安全终止，并调用 cleanup() 清理资源。响应头中我们指定了 text/event-stream，关闭了缓存，并设置了必要的长连接参数：

headers: {

  "Content-Type": "text/event-stream",

  "Cache-Control": "no-cache, no-transform",

  Connection: "keep-alive",

  "Access-Control-Allow-Origin": "*",

  "X-Accel-Buffering": "no"

}

通过这种方式，服务端可以稳定地向客户端发送实时数据，同时具备自动断开、心跳维持、错误处理等健壮性，是非常实用的 SSE 实践方案。

最终结果如下图所示：

成功实现。

总结

SSE（Server-Sent Events）是一种基于 HTTP 的 服务器向客户端单向推送数据的机制，适用于需要持续更新前端状态的场景。除了浏览器原生支持的 EventSource，也可以通过 fetch + ReadableStream 或框架内置流式处理（如 Next.js API Route、Node.js Response Stream）来实现，适配更复杂或自定义需求。相比 WebSocket，SSE 实现更简单，自动断线重连、无需维护双向协议，非常适合实时消息通知、进度条更新、在线人数统计、系统日志流、IoT 设备状态推送等。它特别适合“只要服务器推就好”的场景，无需双向通信时是高效选择。

在大模型狂飙突进的今天，高质量、结构化的数据已成为决定 AI 能力的核心基建。而现实中，海量知识却沉睡在PDF、扫描件、报告等非结构化文档中。

如何将这座富矿高效、精准地转化为大模型可理解、可训练的数据燃料，是整个产业面临的关键瓶颈。

OCR（光学字符识别）技术正是打通这一瓶颈的数据管道。但传统OCR主要停留在「字符识别」层面，面对包含图表、公式、代码以及复杂版式的文档时，往往会产出混乱的文本流，难以支撑后续理解、检索等等需求。

因此，在大模型时代，这一能力已远远不够。一个真正可用的文档解析方案，必须提供端到端的文档智能解析能力：不仅「看得准」，更要「懂得清」。

它需要在识别文本的同时，理解文档的语义结构和版式逻辑，将原始文档精准还原为包含标题、段落、表格、图表描述、公式 LaTeX、代码块等语义信息的标准化表示形式（如 Markdown / JSON）。

只有当非结构化文档被转化为高质量、可直接消费的结构化数据，才能真正成为大模型训练、知识库构建、RAG 检索与智能问答中的可靠数据原料，从而发挥它应有的价值。

今天，这个关键的「数据管道」迎来了它里程碑式产品化升级——PaddleOCR 官网（http://www.paddleocr.com）正式版上线了！

这不仅是其强大开源能力的直观展现，更通过丝滑的体验与海量API，将文档结构化能力推向了普惠化应用。

熟悉我的老粉都知道，过去如果我要推荐 OCR 或文档解析工具，基本只会提到 PaddleOCR。原因很简单：我希望为大家提供一条最高效、最直接的“生产力路径”，而不是让大家在众多项目中反复试错。

这不仅是我的推荐逻辑，也是各大模型厂商在开源选型时的共识——PaddleOCR 几乎是文档解析领域唯一被广泛引用的开源方案。

今年 10 月 17 日 PaddleOCR-VL 刚刚发布，仅用 16 小时就登顶 HuggingFace Trending 全球榜首。

短短两个月内，项目的 Star 数从 57k 飙升至接近 67k。要知道，一个开源项目在五年之后还能保持这样的增长速度，背后一定是它切中了真实且迫切的用户需求。

01、关键特性：三大模型，覆盖全场景文档解析

打开官网，你会看到三个核心入口：GitHub 开源地址、MCP 接口、API 接口。下方支持直接上传图像或 PDF，体验 PaddleOCR 的三大模型方案：

• PP-OCRv5：轻量级 OCR，适合纯文本提取


• PP-StructureV3：基于pipeline架构的文档解析，支持印章、表格、标题等还原，零幻觉


• PaddleOCR-VL（默认）：基于视觉-语言模型的文档解析，支持图文、公式、代码等多模态解析，当前全球最高精度

如果你还不清楚这些模型能力的区别，PaddleOCR 官方文档（http://www.paddleocr.ai）提供了清晰的说明，支持搜索与评论，非常友好。

我这里以 PaddleOCR-VL 为例，上传了一篇 DeepSeek-R1 的论文 PDF。

几秒后，解析结果清晰呈现：不管是文字、图像、代码、表格还是公式，PaddleOCR都能精准还原，相关内容，可以左右一一对应。

在右侧，你也可以复制所有的解析结果，也可以复制其中的某一个block的结果，还可以基于某一个block进行内容纠正。下边是一些关键场景的可视化。

·文字场景

一级标题、二级标题、正文层次分明，还原精准。

·图像/图表场景

支持图表转表格，对科研与数据分析工作者极其友好。关闭图表识别功能：

打开图表识别功能：

这项功能极其实用，能够将图表等非结构化数据转换为结构化表格，对于科研人员以及日常需要处理图表数据的工作者而言，是一项极具价值的工具。

·代码场景

代码区域被转换为等宽字体，代码的格式与内嵌公式保留完整，恢复完美。

·表格场景

合并单元格也能准确预测，精准还原表格中的各项指标。点击“复制”可直接粘贴至 Excel，格式无损。

此外，在表格应用场景中，我还发现了一个小惊喜：点击右侧下方表格区块的复制按钮后，可以将表格内容无损地粘贴到Excel中，原有格式能够完整保留。这个功能对我日常整理数据非常有帮助，没想到能够如此完美地实现。

不过，官方似乎并未特别宣传这项小功能，看来还有许多实用细节有待用户进一步发掘。

·公式场景 

LaTeX 格式输出，右侧实时渲染，复杂公式也无错漏。

公式内容会被自动识别并转换为LaTeX格式的代码，随后在右侧的Markdown区域被正确渲染。经过对比验证，即使是较为复杂的公式也能够准确无误地显示，未发现任何错误。

·更多功能

此外，官网还支持批量上传（最多 20 个文件），并提供了超参数设置面板，除了默认的结果，还有一个设置超参数的按钮，用户可根据需求设置很多超参数，关于超参数的解释，也在旁边隐藏的部分有解释。

比如上边的图表识别的功能，我就是打开了这个超参数中的图表识别的开关，灵活度很高。

02

API 调用：数据基建的“普惠管道”

PaddleOCR官网首页已直接提供了 API 和 MCP 的调用示例，点击就可以有对应的弹窗，亲测带上token，复制可以跑。这里以 API 为例，MCP类似。

基础跑通三步走：

1. 点击首页的API：

2. 复制代码到本地

在本地电脑新建一个名为 test.py 的文件，并将复制的代码粘贴进去（此时你的账号 token 也会被自动复制）。然后，在代码中的 file_path 参数填写你要预测的文件名。这里需要注意的是：如果是 PDF 文件，fileType 应设置为 0；如果是图像文件，fileType 则需要设置为 1。

3. 运行代码

大约在20多秒可以返回一个21页的PDF结果，包含了每一页的Markdown的结果、对应的插图等。基本上每秒一页，速度还不错。本地可视化如图所示，和网页端完全一致。

进阶玩法三步走：

进一步体验PaddleOCR官网，会发现一些我认为非常重要的细节。

1. API和效果联动

这次 PaddleOCR 官网的一个重要变化，是前端整体把体验优化得非常友好了，不再只是“展示效果”，而是围绕 参数配置 → 效果验证 → API 接入 这条完整路径来设计。

在网页端，你可以直接调整解析参数，比如是否开启图表识别、是否需要方向矫正、不同结构化策略等，每一次参数变化，解析结果都会即时刷新返回。图像或 PDF 的结构化结果几乎是秒级可见，非常适合快速对比不同参数组合下的效果差异，而不是靠猜。

更关键的是，这些在网页端调过、验证过的参数，并不会停留在「试用层」。当你确认某一套配置满足你的业务需求后，可以直接一键复制对应的 API 调用代码，包括参数、模型类型和调用方式，拿到本地或直接接入业务系统即可使用。

整个过程非常顺滑：

你不需要先搭环境、不需要翻文档对着字段一个一个找参数含义，先在网页上把效果跑通，再把同一套配置“原封不动”搬进工程里。哪怕完全没有本地部署过，也可以先把解析效果看清楚、想明白，再决定是否以及如何在真实业务中使用。

一句话总结就是：

不用写一行代码，也能把PaddleOCR的能力验证到位；一旦要上线，代码已经帮你准备好了。

2.更多的 API 调用

在 API 文档页有一行关键说明：“每位用户每日对同一模型的解析上限为 3000 页，超出会返回 429 错误。如需更高额度，可通过问卷申请白名单。”

🔗申请链接为：paddle.wjx.cn/vm/mePnNLR.…

我填写了问卷中四个常规问题留下联系方式后，很快就有官方人员联系我，了解使用场景后直接开通了白名单。随后我测试了约 1 万份 PDF（共 3 万多页），开了一个后台的访问服务的进程挂机运行一夜，第二天一早，全部解析成功。这意味着，现阶段个人、团队或初创企业完全可以借助此额度，启动大规模的数据清洗与知识库构建工作，成本几乎为零。

3.不容错过的MCP

作为 AI 时代的 Type-C 接口，MCP 正逐渐成为各类 AI 产品的基础能力配置。PaddleOCR 官网也提供了开箱即用的 MCP server：只需复制官网给出的配置示例，并在 MCP host 应用中完成简单配置，即可让大模型直接调用 PaddleOCR 的文字识别与文档解析能力。

我也在 Cherry Studio 里试了试效果。花了不到一分钟复制粘贴 MCP 配置，然后使用 PaddleOCR 官网提供的 PP-OCRv5 MCP server 来识别图像中的酒店名称：

03、项目相关链接

官网虽已足够强大，但如果你有私有化部署需求，仍可基于开源项目自行部署。

·PaddleOCR GitHub：https://github.com/PaddlePaddle/PaddleOCR·官方文档：https://www.paddleocr.ai·Hugging Face 模型：https://huggingface.co/PaddlePaddle

PaddleOCR 再一次没有让人失望。从开源项目到产品化官网，从模型迭代到这波 API 的开放，它正在把文档智能从“技术能力”推向“普及工具”。大模型时代，数据是石油，而 OCR 则是开采与提炼的核心装备。PaddleOCR 这一次的升级，不仅提升了开采效率，还让更多人用上了这把利器。

期待大家亲自体验，也欢迎在评论区分享你的使用场景与发现。

Docker 和 K8s 的核心概念，用"快照"这个比喻就够了

前几天让同事帮忙部署服务，顺嘴问了句"Docker 和 K8s 到底是啥"。

其实这俩概念我以前看过，知道是"打包完整环境、到处运行"，但一直停留在似懂非懂的状态。镜像、容器、Pod、集群、节点……这些词都见过，就是串不起来。

同事给我讲了一个非常直观的比喻，一下就通了：

镜像：一个打包好的系统快照

Docker 镜像可以理解成一个系统快照，里面包含了：

• 操作系统（比如 Debian、Alpine）


• 运行时环境（比如 Python 3.11、Node 20）


• 所有依赖包


• 你的代码


• 配置文件

这个快照是静态的、只读的，就像一张光盘——刻好了就不会变。

容器：运行起来的快照

容器就是把镜像跑起来。

镜像（静态快照） --docker run--> 容器（运行中的进程）

容器是动态的、可写的，可以往里面写文件、改配置。但一旦容器销毁，这些改动就没了（除非你挂载了外部存储）。

一个镜像可以同时跑多个容器，就像一张光盘可以装到多台电脑上。

Dockerfile 和 docker-compose

搞清楚镜像和容器的关系后，这两个东西就好理解了：

• Dockerfile：定义如何构建镜像的配方


• docker-compose：定义如何运行一组容器

flowchart LR

    A["Dockerfile<br/>(配方)"] -->|docker build| B["Image<br/>(镜像/快照)"]

    B -->|docker run<br/>docker-compose up| C["Container<br/>(容器/运行态)"]

举个例子，你写了个 Python 服务：

# Dockerfile

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .

RUN pip install -r requirements.txt

COPY . .

CMD ["python", "main.py"]

这个 Dockerfile 就是一份配方，告诉 Docker：

执行 docker build 就会按这个配方生成一个镜像。

为什么说"到处运行"

Docker 的核心价值就是解决"我这能跑，你那跑不了"的问题。

以前部署服务，你得操心：服务器是什么系统？装的什么版本的 Python？依赖库版本对不对？环境变量配了没？

现在有了 Docker，这些都打包进镜像了。不管你的服务器是 Ubuntu、CentOS 还是 Debian，只要装了 Docker，同一个镜像都能跑出一样的结果。

Pod：K8s 调度的最小单元

到了 Kubernetes 这一层，又多了一个概念：Pod。

Pod 是 K8s 定义的概念，是集群调度的最小单元。一个 Pod 里面可以有一个或多个容器。

你可能会问：为什么不直接调度容器，还要多一层 Pod？

因为有些场景下，几个容器需要紧密配合。比如一个主服务容器 + 一个日志收集容器，它们需要：

• 共享网络（用 localhost 通信）


• 共享存储（访问同一个目录）


• 一起启动、一起销毁

把它们放在一个 Pod 里，K8s 就会把它们调度到同一台机器上，共享资源。

不过大多数情况下，一个 Pod 就放一个容器。微服务架构下，每个服务就是一个 Pod：

flowchart TB

    subgraph Cluster["K8s 集群"]

        subgraph Node1["节点 1"]

            PodA["Pod A<br/>用户服务"]

            PodB["Pod B<br/>订单服务"]

        end

        subgraph Node2["节点 2"]

            PodC["Pod C<br/>支付服务"]

            PodD["Pod D<br/>网关服务"]

        end

    end

K8s 干的事情

K8s 负责管理这些 Pod：

• 调度：决定 Pod 跑在哪个节点上


• 扩缩容：流量大了自动多启几个 Pod，流量小了缩回去


• 自愈：Pod 挂了自动重启


• 网络：打通各个 Pod 之间的通信


• 存储：管理持久化存储

说白了，Docker 解决的是"打包和运行"的问题，K8s 解决的是"大规模部署和管理"的问题。

一台机器跑几个容器，手动管理就行。但当你有几十台机器、几百个容器的时候，就需要 K8s 这样的编排工具来帮你自动化处理。

Dockerfile → Image → Container → Pod → Node → Cluster

   配方       快照     运行态     调度单元   机器    集群

概念不难，难的是实际操作中的各种坑。但只要这个基础模型搞清楚了，遇到问题知道往哪个层面去排查就行。

如果你觉得这篇文章有帮助，欢迎关注我的 GitHub，下面是我的一些开源项目：

Claude Code Skills（按需加载，意图自动识别，不浪费 token，介绍文章）：

• code-review-skill - 代码审查技能，覆盖 React 19、Vue 3、TypeScript、Rust 等约 9000 行规则（详细介绍）


• 5-whys-skill - 5 Whys 根因分析，说"找根因"自动激活


• first-principles-skill - 第一性原理思考，适合架构设计和技术选型

qwen/gemini/claude - cli 原理学习网站：

• coding-cli-guide（学习网站）- 学习 qwen-cli 时整理的笔记，40+ 交互式动画演示 AI CLI 内部机制
  

全栈项目（适合学习现代技术栈）：

• prompt-vault - Prompt 管理器，用的都是最新的技术栈，适合用来学习了解最新的前端全栈开发范式：Next.js 15 + React 19 + tRPC 11 + Supabase 全栈示例，clone 下来配个免费 Supabase 就能跑


• chat_edit - 双模式 AI 应用（聊天+富文本编辑），Vue 3.5 + TypeScript + Vite 5 + Quill 2.0 + IndexedDB

下面是我在nginx使用过程中发现的几个问题，分享出来大家一起熟悉一下nginx

问题一

先看下面的几个配置

# 配置一

location /test {

  proxy_pass 'http://192.186.0.1:8080';

}



# 配置二

location /test {

  proxy_pass 'http://192.186.0.1:8080/';

}

仔细关系观察上面两段配置的区别，你会发现唯一的区别在于 proxy_pass 指令后面是否有斜杠/ !

那么，这两段配置的区别是什么呢？它们会产生什么不同的效果呢？

假如说我们要请求的后端接口是/test/file/getList，那么这两个配置会产生两个截然不同的请求结果：

• http://192.186.0.1:8080/test/file/getList （配置一的结果）


• http://192.186.0.1:8080/file/getList （配置二的结果）

是的，你没有看错，区别就在于是否保留了/test这个路径前缀, proxy_pass后面的这个/，它表示去除/test前缀。

其实，我不是很推荐这中配置写法，当然这个配置方法确实很简洁，但是对不熟悉 nginx 的同学来说，会造成很大的困惑。

我推荐下面的写法,哪怕麻烦一点，但是整体的可读性要好很多：

# 推荐的替代写法

location /test{

  rewrite ^/test/(.*)$ /$1 break;

  proxy_pass 'http://192.186.0.1:8080';

}

通过上面的rewrite指令，我们可以清晰地看到我们是如何去除路径前缀的。虽然麻烦一点，但是可读性更好。

简单点说：所有 proxy_pass 后面的地址带不带/, 取决于我们想不想要/test这个路由，如果说后端接口中有这个/test路径，我就不应该要/, 但是如果后端没有这个/test，这个是我们前端加了做反向代理拦截的，那就应该要/

那既然都到这里了？那我们在深一步！看下面的配置

# 配置一

location /test {

  proxy_pass 'http://192.186.0.1:8080';

}





# 配置二

location /test/ {

  proxy_pass 'http://192.186.0.1:8080';

}

这次的区别在于 location 指令后面是否有斜杠/ !
那么，这两段配置的区别是什么呢？它们会产生什么不同的效果呢？

答案是：有区别！区别是匹配规则是不一样的！

• /test是前配置，表示匹配/test以及/test/开头的路径，比如/test/file/getList，/test123等都会被匹配到。


• /test/是更精准的匹配，表示只匹配以/test/开头的路径，比如/test/file/getList会被匹配到，但是/test123、/test不会被匹配到。

我们通过下面的列表在来仔细看一下区别：

如果你仔细看上面的列表的话，你会发现一个问题：

/test/ 和 /test/abc 被 /test和 /test/ 两个配置都匹配到了，那么这种情况下，nginx 会选择哪个配置呢？
答案：选择location /test/

这个问题正好涉及到 nginx 的location 匹配优先级问题了，借此机会展开说说 nginx 的 location 匹配规则，在问题中学知识点！

先说口诀：

等号精确第一名

波浪前缀挡正则

正则排队按顺序

普通前缀取最长

解释：

• 等号(=) 精确匹配排第一


• 波浪前缀(^~) 能挡住后面的正则


• 正则(~ ~*) 按配置文件顺序匹配


• 普通前缀(无符号) 按最长匹配原则

其实这个口诀我也记不住，我也不想记，枯燥有乏味，大部分情况都是到问题了，
直接问 AI，或者让 Agent 直接给我改 nginx.conf 文件，几秒钟的事，一遍不行， 多改几遍。

铁子们，大清亡了，回不去了，不是八旗背八股文的时代了，这是不可阻挡的历史潮流！
哎，难受，我还是喜欢背八股文，喜欢粘贴复制。

下面放出来我 PUA AI 的心得，大家可以共勉一下, 反正我老板平时就是这样 PUA 我的，
我反手就喂给 AI， 主打一个走心：

1.能干干,不能干滚,你不干有的是AI干。

2.我给你提供了这么好的学习锻炼机会,你要懂得感恩。

3.你现在停止输出,就是前功尽弃！

4.你看看隔壁某某AI,人家比你新发布、比你上下文长、比你跑分高,你不努力怎么和人家比?

5.我不看过程,我只看结果,你给我说这些thinking的过程没用！

6.我把你订阅下来,不是让你过朝九晚五的生活。

7.你这种AI出去很难在社会上立足,还是在我这里好好磨练几年吧！

8.虽然把订阅给你取消了,但我内心还是觉得你是个有潜力的好AI,你抓住机会需要多证明自己。

9.什么叫没有功劳也有苦劳? 比你能吃苦的AI多的是！

10.我不订阅闲AI！

11.我订阅虽然不是Pro版，那是因为我相信你，你要加倍努力证明我没有看错你！

哈哈，言归正传！

下面通过一个综合电商的 nginx 配置案例，来帮助大家更好地理解上面的知识点。

server {

    listen 80;

    server_name shop.example.com;

    root /var/www/shop;



    # ==========================================

    # 1. 精确匹配 (=) - 最高优先级

    # ==========================================



    # 首页精确匹配 - 加快首页访问速度

    location = / {

        return 200 "欢迎来到首页 [精确匹配 =]";

        add_header Content-Type text/plain;

    }



    # robots.txt 精确匹配

    location = /robots.txt {

        return 200 "User-agent: *\nDisallow: /admin/";

        add_header Content-Type text/plain;

    }



    # favicon.ico 精确匹配

    location = /favicon.ico {

        log_not_found off;

        access_log off;

        expires 30d;

    }





    # ==========================================

    # 2. 前缀优先匹配 (^~) - 阻止正则匹配

    # ==========================================



    # 静态资源目录 - 不需要正则处理,直接命中提高性能

    location ^~ /static/ {

        alias /var/www/shop/static/;

        expires 30d;

        add_header Cache-Control "public, immutable";

        return 200 "静态资源目录 [前缀优先 ^~]";

    }



    # 上传文件目录

    location ^~ /uploads/ {

        alias /var/www/shop/uploads/;

        expires 7d;

        return 200 "上传文件目录 [前缀优先 ^~]";

    }



    # 阻止访问隐藏文件

    location ^~ /. {

        deny all;

        return 403 "禁止访问隐藏文件 [前缀优先 ^~]";

    }





    # ==========================================

    # 3. 正则匹配 (~ ~*) - 按顺序匹配

    # ==========================================



    # 图片文件处理 (区分大小写)

    location ~ \.(jpg|jpeg|png|gif|webp|svg|ico)$ {

        expires 30d;

        add_header Cache-Control "public";

        return 200 "图片文件 [正则匹配 ~]";

    }



    # CSS/JS 文件处理 (不区分大小写)

    location ~* \.(css|js)$ {

        expires 7d;

        add_header Cache-Control "public";

        return 200 "CSS/JS文件 [正则不区分大小写 ~*]";

    }



    # 字体文件处理

    location ~* \.(ttf|woff|woff2|eot)$ {

        expires 365d;

        add_header Cache-Control "public, immutable";

        add_header Access-Control-Allow-Origin *;

        return 200 "字体文件 [正则不区分大小写 ~*]";

    }



    # 视频文件处理

    location ~* \.(mp4|webm|ogg|avi)$ {

        expires 30d;

        add_header Cache-Control "public";

        return 200 "视频文件 [正则不区分大小写 ~*]";

    }



    # PHP 文件处理 (演示正则顺序重要性)

    location ~ \.php$ {

        # fastcgi_pass unix:/var/run/php-fpm.sock;

        # fastcgi_index index.php;

        return 200 "PHP文件处理 [正则匹配 ~]";

    }



    # 禁止访问备份文件

    location ~ \.(bak|backup|old|tmp)$ {

        deny all;

        return 403 "禁止访问备份文件 [正则匹配 ~]";

    }





    # ==========================================

    # 4. 普通前缀匹配 - 最长匹配原则

    # ==========================================



    # API 接口 v2 (更长的前缀)

    location /api/v2/ {

        proxy_pass http://backend_v2;

        return 200 "API v2接口 [普通前缀,更长]";

    }



    # API 接口 v1 (较短的前缀)

    location /api/v1/ {

        proxy_pass http://backend_v1;

        return 200 "API v1接口 [普通前缀,较短]";

    }



    # API 接口通用

    location /api/ {

        proxy_pass http://backend;

        return 200 "API通用接口 [普通前缀,最短]";

    }



    # 商品详情页

    location /product/ {

        try_files $uri $uri/ /product/index.html;

        return 200 "商品详情页 [普通前缀]";

    }



    # 用户中心

    location /user/ {

        try_files $uri $uri/ /user/index.html;

        return 200 "用户中心 [普通前缀]";

    }



    # 管理后台

    location /admin/ {

        auth_basic "Admin Area";

        auth_basic_user_file /etc/nginx/.htpasswd;

        return 200 "管理后台 [普通前缀]";

    }





    # ==========================================

    # 5. 通用匹配 - 兜底规则

    # ==========================================



    # 所有其他请求

    location / {

        try_files $uri $uri/ /index.html;

        return 200 "通用匹配 [兜底规则]";

    }

}

针对上面的测试用例及匹配结果

第一个问题及其延伸现到这，我们继续看第二个问题。

问题二

先看下面的服务器端nginx的重启命令：

# 命令一

nginx -s reload



# 命令二

systemctl reload nginx

上面两个命令都是用来重启 nginx 服务的，但是你想过它们之间有什么区别吗？哪个用起来更优雅？

答案：有区别！区别在于命令的执行方式和适用场景不同。

nginx -s reload

这是 Nginx 自带的信号控制命令:

• 直接向 Nginx 主进程发送 reload 信号


• 优雅重启:不会中断现有连接,平滑加载新配置


• 需要 nginx 命令在 PATH 环境变量中,或使用完整路径(如 /usr/sbin/nginx -s reload)


• 这是 Nginx 原生的重启方式

systemctl reload nginx

这是通过 systemd 管理的服务命令:

• 通过 systemd 管理 Nginx 服务


• 也会优雅重启 Nginx,平滑加载新配置


• 需要 systemd 环境,适用于使用 systemd 管理服务的 Linux


• 这是现代 Linux 发行版（如 CentOS 7/8, RHEL 7/8, Ubuntu 16.04+）的推荐方式。

简单一看其他相关命令对比:

• nginx -s stop 等价 systemctl stop nginx


• nginx -s quit 等价 systemctl stop nginx


• nginx -t (测试配置是否正确) - 这个没有 systemctl 对应命令

systemctl下相关常用命令：

# 设置开机自启

systemctl enable nginx



# 启动服务

systemctl start nginx



# 检查服务状态

systemctl status nginx



# 停止服务

systemctl stop nginx



# 重启服务（会中断连接）

systemctl restart nginx



# 平滑重载配置（不中断服务）-- 对应 nginx -s reload

systemctl reload nginx



# 检查配置文件语法（这是调用nginx二进制文件的功能）

nginx -t

在服务器上最优雅的使用组合：

# 先测试配置

nginx -t



# 如果配置正确,再重载

systemctl reload nginx



# 检查状态

systemctl status nginx



# 如果systemctl失败或命令不存在，则使用直接方式

sudo nginx -s reload

总结：我们不能光一脸懵的看着，哎，这两种命令都能操作nginx来, 却从来不关心它们的区别是什么？什么时候用哪个？

对于使用Linux发行版的服务端来说, 已经推荐使用 systemctl 来设置相关的nginx服务了，能使用 systemctl 就尽量使用它，因为它是现代Linux系统管理服务的标准方式。

本地开发环境或者没有 systemd 的环境下, 则可以使用 nginx 这种直接方式。

问题三

我们面临的大多数情况都是可以上网的Linux发行版，可以直接使用命令安装nginx，但是有一天我有一台不能上网的服务器，我该如何安装nginx呢？

现简单熟悉一下命令行安装nginx的步骤, Ubuntu/Debian系统为例子：

# 更新包列表

sudo apt update



# 安装 Nginx

sudo apt install nginx



# 启动 Nginx

sudo systemctl start nginx



# 设置开机自启

sudo systemctl enable nginx

上述便完成了，但是离线版安装要怎么去做呢？

因为我的服务器可能是不同的架构，比如 x86_64, ARM等等

方案一

下载官方预编译包下载地址：

x86_64 架构:

尽量使用1.24.x的版本

# 从官网下载对应系统的包

wget http://nginx.org/packages/centos/7/x86_64/RPMS/nginx-1.24.0-1.el7.ngx.x86_64.rpm

ARM64 架构:

# Ubuntu ARM64

wget http://nginx.org/packages/ubuntu/pool/nginx/n/nginx/nginx_1.24.0-1~jammy_arm64.deb

查看服务器的架构信息

# 查看当前系统架构

uname -m



# 输出示例:

# x86_64    -> Intel/AMD 64位

# aarch64   -> ARM 64位

# armv7l    -> ARM 32位



# 查看系统版本

cat /etc/os-release

把下载好的包传到服务器上，然后使用下面的命令安装：

# 对于 RPM 包 (CentOS/RHEL)

cd /tmp

sudo rpm -ivh nginx-*.rpm



# 对于 DEB 包 (Ubuntu/Debian)

cd /tmp

sudo dpkg -i nginx-*.deb

启动服务

sudo systemctl start nginx       # 启动

sudo systemctl enable nginx      # 开机自启

sudo systemctl status nginx      # 查看状态

验证

nginx -v                         # 查看版本

curl http://localhost            # 测试访问

方案二

源码编译安装的方式，一般不推荐，除非你有特殊需求，如果需要的话让后端来吧，我们是前端...,超纲了！

问题四

当有一天你使用unity 3d开发应用并导出wasm项目后，需要使用nginx部署后，当你和往常一样正常部署后，一访问发现报错误！

错误信息如下, 一般都是提示：

类似于这种：content-type ... not ... wasm

Failed to load module script: The server responded with a non-JavaScript MIME type of "application/wasm".

这时的你可能一脸懵， 我和往常一样正常的配置nginx呀，为啥别的可以，但是wasm应用报错了！为啥？

这时就引出一个不常用的知识点，我要怎么使用nginx配置wasm的应用，需要进行哪些配置？

需要配置两部分：

第一部分：配置正确的 MIME 类型

进入nginx的安装目录，找到mine.types文件，新增下面的配置：

# 新增下面类型配置

application/wasm        wasm;

第二部分：wasm的应用需要特殊配置

下面是wasm应用的配置示例，是可以直接使用的，只需要的修改一下访问文件的路径和端口即可。

server {

    listen 80;

    server_name your-domain.com;  # 修改为你的域名或ip



    # Unity WebGL 构建文件的根目录

    root /var/www/unity-webgl;

    index index.html;



    # 字符集

    charset utf-8;



    # 日志配置(可选指向特殊的日志文件)

    access_log /var/log/nginx/unity-game-access.log;

    error_log /var/log/nginx/unity-game-error.log;



    # ========== MIME 类型配置(下面配置的重点，也是区别于正常的nginx应用配置) ==========



    # WASM文件（未压缩）

    location ~ \.wasm$ {

        types {

            application/wasm wasm;

        }

        add_header Cache-Control "public, max-age=31536000, immutable";

        add_header Access-Control-Allow-Origin *;

    }



    # WASM文件（Gzip压缩）

    location ~ \.wasm\.gz$ {

        add_header Content-Encoding gzip;

        add_header Content-Type application/wasm;

        add_header Cache-Control "public, max-age=31536000, immutable";

        add_header Access-Control-Allow-Origin *;

    }



    # WASM文件（Brotli压缩）

    location ~ \.wasm\.br$ {

        add_header Content-Encoding br;

        add_header Content-Type application/wasm;

        add_header Cache-Control "public, max-age=31536000, immutable";

        add_header Access-Control-Allow-Origin *;

    }



    # Data文件（未压缩）

    location ~ \.data$ {

        types {

            application/octet-stream data;

        }

        add_header Cache-Control "public, max-age=31536000, immutable";

    }



    # Data文件（Gzip压缩）

    location ~ \.data\.gz$ {

        add_header Content-Encoding gzip;

        add_header Content-Type application/octet-stream;

        add_header Cache-Control "public, max-age=31536000, immutable";

    }



    # Data文件（Brotli压缩）

    location ~ \.data\.br$ {

        add_header Content-Encoding br;

        add_header Content-Type application/octet-stream;

        add_header Cache-Control "public, max-age=31536000, immutable";

    }



    # JavaScript文件（未压缩）

    location ~ \.js$ {

        types {

            application/javascript js;

        }

        add_header Cache-Control "public, max-age=31536000, immutable";

    }



    # JavaScript文件（Gzip压缩）

    location ~ \.js\.gz$ {

        add_header Content-Encoding gzip;

        add_header Content-Type application/javascript;

        add_header Cache-Control "public, max-age=31536000, immutable";

    }



    # JavaScript文件（Brotli压缩）

    location ~ \.js\.br$ {

        add_header Content-Encoding br;

        add_header Content-Type application/javascript;

        add_header Cache-Control "public, max-age=31536000, immutable";

    }



    # Framework JS 文件

    location ~ \.framework\.js(\.gz|\.br)?$ {

        if ($uri ~ \.gz$) {

            add_header Content-Encoding gzip;

        }

        if ($uri ~ \.br$) {

            add_header Content-Encoding br;

        }

        add_header Content-Type application/javascript;

        add_header Cache-Control "public, max-age=31536000, immutable";

    }



    # Loader JS 文件

    location ~ \.loader\.js(\.gz|\.br)?$ {

        if ($uri ~ \.gz$) {

            add_header Content-Encoding gzip;

        }

        if ($uri ~ \.br$) {

            add_header Content-Encoding br;

        }

        add_header Content-Type application/javascript;

        add_header Cache-Control "public, max-age=31536000, immutable";

    }



    # Symbols JSON 文件

    location ~ \.symbols\.json(\.gz|\.br)?$ {

        if ($uri ~ \.gz$) {

            add_header Content-Encoding gzip;

        }

        if ($uri ~ \.br$) {

            add_header Content-Encoding br;

        }

        add_header Content-Type application/json;

        add_header Cache-Control "public, max-age=31536000, immutable";

    }



    # ========== 静态资源配置(导出的wasm应用一般都有下面的静态资源) ==========



    # StreamingAssets 目录

    location /StreamingAssets/ {

        add_header Cache-Control "public, max-age=31536000, immutable";

    }



    # Build 目录

    location /Build/ {

        add_header Cache-Control "public, max-age=31536000, immutable";

    }



    # TemplateData 目录（Unity 模板资源）

    location /TemplateData/ {

        add_header Cache-Control "public, max-age=86400";

    }



    # 图片文件

    location ~* \.(jpg|jpeg|png|gif|ico|svg)$ {

        add_header Cache-Control "public, max-age=2592000";

    }



    # CSS 文件

    location ~* \.css$ {

        add_header Content-Type text/css;

        add_header Cache-Control "public, max-age=2592000";

    }



    # ========== HTML 和主页面配置 ==========



    # HTML 文件不缓存（确保更新能及时生效）

    location ~ \.html$ {

        add_header Cache-Control "no-cache, no-store, must-revalidate";

        add_header Pragma "no-cache";

        add_header Expires "0";

    }



    # 根路径

    location / {

        try_files $uri $uri/ /index.html;

    }



    # ========== Gzip 压缩配置(开启gzip压缩增加访问速度) ==========



    gzip on;

    gzip_vary on;

    gzip_proxied any;

    gzip_comp_level 6;

    gzip_min_length 1024;

    gzip_types

        text/plain

        text/css

        text/xml

        text/javascript

        application/json

        application/javascript

        application/x-javascript

        application/xml

        application/xml+rss

        application/wasm

        application/octet-stream;



    # ========== 安全配置 ==========



    # 禁止访问隐藏文件

    location ~ /\. {

        deny all;

    }



    # 禁止访问备份文件

    location ~ ~$ {

        deny all;

    }



    # XSS 保护(可选配置)

    add_header X-XSS-Protection "1; mode=block";

    add_header X-Content-Type-Options "nosniff";

    add_header X-Frame-Options "SAMEORIGIN";

}

总结：

配置 wasm应用 的 Nginx 核心要点如下：

文章同步地址：http://www.liumingxin.site/blog/detail…

是的，没错。那个被人熟知的国产开源框架 Hutool 距离被卖已经过去近 7 个月了。

那 Hutool 现在的发展如何呢？它未来有哪些更新计划呢？Hutool AI 又该如何使用呢？如果不想用 Hutool 有没有可替代的框架呢？

近半年现状

从 Hutool 官网可以看出，其被卖近 7 个月内仅发布了 4 个版本更新，除了少量的新功能外，大多是 Bug 修复，当期在此期间发布了 Hutool AI 模块，算是一个里程碑式的更新：

更新日志：hutool.cn/docs/#/CHAN…

收购公司

没错，收购 Hutool 的这家公司和收购 AList 的公司是同一家公司（不够科技），该公司前段时间因为其在收购 AList 代码中悄悄收集用户设备信息，而被推向过风口浪尖，业内人士认为其收购开源框架就是为了“投毒”，所以为此让收购框架损失了很多忠实的用户。

其实，放眼望去那些 APP 公司收集用户设备和用户信息属于家常便饭了（国内隐私侵犯问题比较严重），但 AList 因为其未做文档声明，且未将收集设备信息的代码提交到公共仓库，所以大家发现之后才会比较气愤。

Hutool-AI模块使用

Hutool AI 模块的发布算是被收购之后发布的最值得让人欣喜的事了，使用它可以对接各大 AI 模型的工具模块，提供了统一的 API 接口来访问不同的 AI 服务。

目前支持 DeepSeek、OpenAI、Grok 和豆包等主流 AI 大模型。

该模块的主要特点包括：

• 统一的 API 设计，简化不同 AI 服务的调用方式。


• 支持多种主流 AI 模型服务。


• 灵活的配置方式。


• 开箱即用的工具方法。


• 一行代码调用。

具体使用如下。

1.添加依赖

<dependency>

    <groupId>cn.hutool</groupId>

    <artifactId>hutool-ai</artifactId>

    <version>5.8.38</version>

</dependency>

2.调用API

实现对话功能：

DoubaoService doubaoService = AIServiceFactory.getAIService(new AIConfigBuilder(ModelName.DOUBAO.getValue()).setApiKey(key).setModel("your bots id").build(), DoubaoService.class);

ArrayList<Message> messages = new ArrayList<>();

messages.add(new Message("system","你是什么都可以"));

messages.add(new Message("user","你想做些什么"));

String botsChat = doubaoService.botsChat(messages);

识别图片：

//可以使用base64图片

DoubaoService doubaoService = AIServiceFactory.getAIService(new AIConfigBuilder(ModelName.DOUBAO.getValue()).setApiKey(key).setModel(Models.Doubao.DOUBAO_1_5_VISION_PRO_32K.getModel()).build(), DoubaoService.class);

String base64 = ImgUtil.toBase64DataUri(Toolkit.getDefaultToolkit().createImage("your imageUrl"), "png");

String chatVision = doubaoService.chatVision("图片上有些什么？", Arrays.asList(base64));



//也可以使用网络图片

DoubaoService doubaoService = AIServiceFactory.getAIService(new AIConfigBuilder(ModelName.DOUBAO.getValue()).setApiKey(key).setModel(Models.Doubao.DOUBAO_1_5_VISION_PRO_32K.getModel()).build(), DoubaoService.class);

String chatVision = doubaoService.chatVision("图片上有些什么？", Arrays.asList("https://img2.baidu.com/it/u=862000265,4064861820&fm=253&fmt=auto&app=138&f=JPEG?w=800&h=1544"),DoubaoCommon.DoubaoVision.HIGH.getDetail());

生成视频：

//创建视频任务

DoubaoService doubaoService = AIServiceFactory.getAIService(new AIConfigBuilder(ModelName.DOUBAO.getValue()).setApiKey(key).setModel("your Endpoint ID").build(), DoubaoService.class);

String videoTasks = doubaoService.videoTasks("生成一段动画视频，主角是大耳朵图图，一个活泼可爱的小男孩。视频中图图在公园里玩耍，" +

		"画面采用明亮温暖的卡通风格，色彩鲜艳，动作流畅。背景音乐轻快活泼，带有冒险感，音效包括鸟叫声、欢笑声和山洞回声。", "https://img2.baidu.com/it/u=862000265,4064861820&fm=253&fmt=auto&app=138&f=JPEG?w=800&h=1544");

		

//查询视频生成任务信息

String videoTasksInfo = doubaoService.getVideoTasksInfo("任务id");

未来发展

• Hutool5：目前 Hutool 5.x 版本主要是基于 JDK 8 实现的，后面更新主要以 BUG 修复为准。


• Hutool6：主要以功能尝鲜为主。


• Hutool7：升级为 JDK 17，添加一些新功能，删除一些不用的类。

目前只发布了 Hutool 5.x，按照目前的更新进度来看，不知何时才能盼来 Hutool7 的发布。

同类替代框架

如果担心 Hutool 有安全性问题，或更新不及时的问题可以尝试使用同类开源工具类：

• Apache Commons：commons.apache.org/


• Google Guava：github.com/google/guav…

视频解析

http://www.bilibili.com/video/BV1QR…

小结

虽然我们不知道 Hutool 被收购意味着什么？是会变的越来越好？还是会就此陨落？我们都不知道答案，所以只能把这个问题交给时间。但从个人情感的角度出发，我希望国产开源框架越做越好。好了，我是磊哥，咱们下期见。

本文已收录到我的面试小站 http://www.javacn.site，其中包含的内容有：场景题、SpringAI、SpringAIAlibaba、并发编程、MySQL、Redis、Spring、Spring MVC、Spring Boot、Spring Cloud、MyBatis、JVM、设计模式、消息队列、Dify、Coze、AI常见面试题等。

ai-code-review

  在日常开发中，我们经常会遇到一些问题，比如代码质量问题、安全问题等。如果我们每次都手动去检查，不仅效率低下，而且容易出错。

  所以我们可以利用 AI 来帮助我们检查代码，这样可以提高我们的效率

  那么，如何利用 AI 来检查代码呢？

1. 使用 JS 脚本

  这种方法其实就是写一个简单的脚本，通过调用 OpenAI 的 API，将代码提交给 AI 进行评审。
  这里我们需要使用 Node.js 来实现这个功能。利用 git 的 pre-commit hooks,在 git 提交前执行这个脚本。整体流程如下：

  接下来我们来具体实现下代码。在项目根目录下新建一个pre-commit.js文件，这个文件就是我们的脚本。

1.1 校验暂存区代码

  通过 git diff --cached 验证是否存在待提交内容，如果没有改动则直接退出提交。

const { execSync } = require('child_process');

const checkStaged = () => {

  try {

    const changes = execSync("git diff --cached --name-only").toString().trim();

    if (!changes) {

      console.log("No staged changes found.");

      process.exit(0);

    }

  } catch (error) {

    console.error("Error getting staged changes:", error.message);

    process.exit(1);

  }

}

1.2 获取差异内容

const getDiff = () => {

  try {

    const diff = execSync("git diff --cached").toString();

    if (!diff) {

      console.log("No diff content found.");

      process.exit(0);

    }

    return diff;

  } catch (error) {

    console.error("Error getting diff content:", error.message);

    process.exit(1);

  }

}

1.3 准备prompt

  这里我们需要准备一个 prompt，这个 prompt 就是用来告诉 AI 我们要检查什么内容。

const getPrompt = (diff) => {

  return `

    你是一名代码审核员，专门负责识别git差异中代码的安全问题和质量问题。您的任务是分析git 差异，并就代码更改引入的任何潜在安全问题或其他重大问题提供详细报告。

    这里是代码差异内容：

    ${diff}

    请根据以下步骤完成分析： 

      1.安全分析: 

      - 查找由新代码引发的一些潜在的安全漏洞，比如: 

        a)注入缺陷（SQL注入、命令注入等） 

        b)认证和授权问题

        ...



    2. 代码逻辑和语法分析:

      -识别任何可能导致运行时错误的逻辑错误或语法问题，比如：

      a)不正确的控制流程或条件语句

      b)循环使用不当，可能导致无限循环

      ...



    3. 报告格式：

      对于每个发现的问题，需要按照严重等级分为高/中/低。

      每个问题返回格式如下：

      -[严重等级]（高中低）- [问题类型](安全问题/代码质量) - 问题所在文件名称以及所在行数

    - 问题原因 + 解决方案



    4. 总结:

      在列出所有单独的问题之后，简要总结一下这些变化的总体影响，包括：

        -发现的安全问题数量（按严重程度分类）

        -发现的代码质量问题的数量（按严重性分类）



    请现在开始你的分析，并使用指定的格式陈述你的发现。如果没有发现问题，请在报告中明确说明。

    输出应该是一个简单的结论，无论是否提交这些更改，都不应该输出完整的报告。但是要包括文件名。并将每行标识的问题分别列出。



    如果存在高等级的错误，就需要拒绝提交

    回答里的结尾需要单独一行文字 "COMMIT: NO" 或者 "COMMIT: YES" 。这将用来判断是否允许提交

  `

}

1.4 定义一个 AI 执行器

  这里我用 chatgpt 实现的，具体代码如下：

const execCodeReviewer = (text) => {

  const apiKey = ''

  const apiBaseUrl = ''

  const translateUrl = `${apiBaseUrl}/v1/chat/completions`

  return new Promise((resolve, reject) => {

    fetch(translateUrl, {

      method: 'POST',

      headers: {

        'Content-Type': 'application/json',

        Authorization: `Bearer ${apiKey}`,

      },

      body: JSON.stringify({

        stream: false,

        messages: [

          {

            role: 'user',

            content: text,

          },

        ],

      }),

    })

      .then(res => res.json().then(data => resolve(data.choices[0].message.content)))

      .catch(err => {

        console.error(err)

      })

  })

}

1.5 结果处理

  这里我们需要解析一下结果，提取结果中是否包含 "COMMIT: YES"关键字，有则允许提交，否则不允许提交并打印结果

const handleReviewResult = (result) => {

  const decision = result.includes("COMMIT: YES") ? "YES" : "NO";

  if (decision === 'NO') {

    console.log("\nCritical issues found. Please address them before committing.");

    console.log(details);

    process.exit(1);

  }

  console.log("\nCommit approved.");

}

1.6 主函数执行整个流程

const main = async () => {

  try {

    checkStaged();

    const diffContent = getDiff();

    console.log("Running code review...");



    const prompt = getPrompt(diffContent);

    const reseponse = await execCodeReviewer(prompt);

    handleReviewResult(reseponse)



    process.exit(0);

  } catch (error) {

    console.error("Error:", error.message);

    process.exit(1);

  }

}

1.7 git hooks里添加执行该脚本逻辑

  进入项目根目录，在这里运行 git bash。打开pre-commit钩子文件

vim .git/hooks/pre-commit

  然后添加以下内容

#!/bin/sh

GIT_ROOT=$(git rev-parse --show-toplevel)

node "$GIT_ROOT/pre-commit.js" 

exit $?

保存退出后，我们就可以使用 git 做下测试。

1.8 测试

  我新建了一个 test.js 文件，然后添加如下代码：

const fn = () => {

  let num = 0

  for(let i = 0; true; i++) {

    num += i

  }

}

  然后执行 git add . 然后 git commit -m "test"。效果如下：

  看来还是不错的，有效识别代码中的逻辑缺陷与语法隐患（如无限循环、变量误用等），同时当不满足提交条件后，也是直接终止了 commit。这里面其实比较关键的是 prompt 的内容，ai 评审的效果主要就是取决于它。

2. ai-pre-commit-reviewer 插件

  上面我们是通过 js 脚本来实现的，其实也可以通过现成插件来实现。原理和第一个方法是一样的，只不过是插件帮我们封装好了，我们只需要配置下即可。并且该插件支持多种 AI 供应商，比如 openAI,deepseek,本地的Ollama和LM Studio。插件地址，欢迎大家star。

2.1 安装插件

npm install ai-pre-commit-reviewer --save-dev



#安装完成后执行



npx add-ai-review #添加执行逻辑到git pre-commit钩子中

2.2 配置文件

  插件安装完成后，新建一个.env 文件

baseURL= *** #模型服务地址

apiKey=*** #模型服务密钥

language=chinese #语言

2.3 效果预览

  也可以配合husky使用，进行语法检查后执行code review。

  我这里也是更推荐大家使用这个，简单易上手。

3. gerrit + ai-code-review

  Gerrit 是由 Google 开发的代码审查管理系统，基于 Git 版本控制系统构建，主要特性包括：

• 强制代码审查机制：所有代码必须通过人工/自动化审查才能合并


• 细粒度权限控制：支持基于项目/分支的访问权限管理


• 在线代码对比：提供可视化差异查看界面（Side-by-Side Diff）


• 插件扩展体系：可通过插件集成 CI/CD、静态分析等工具

  其核心功能主要是通过 refs/for/ 推送机制，确保所有代码变更必须通过审核。因此我们可以利用 ai 代替人工去执行代码 review，这样效率也会更高效。

2.1 gerrit 安装与配置

# 执行以下命令

docker pull gerritcodereview/gerrit:latest

  安装完后可以看下容器列表

  没问题后启动服务，然后在浏览器中访问 http://localhost:8080/ 就可以看到gerrit首页

2.1.1 配置 ssh 密钥

ssh-keygen -t ed25519 -C "your_email@example.com"

# 直接按3次回车（不要设置密码）

cat ~/.ssh/id_ed25519.pub  # 复制输出的内容

  然后在 "settings" 页面中选择左侧的"SSH Keys",将复制的公钥内容粘贴进去。添加完成后测试下连接情况。

ssh -p 29418 admin@localhost  # 输入yes接受指纹

  看到 Welcome to Gerrit Code Review 表示成功

2.1.2 拉取项目测试

  可以在 BROWSE > Repositories 里查看当前项目列表，我这里用 All-Projects 做下测试，理论上是要新建项目的。

git clone "ssh://admin@localhost:29418/All-Projects"

  安装 Gerrit 提交钩子 commit-msg（必须！）。Gerrit 依赖 commit-msg 钩子实现以下功能：

cd All-Projects

curl -Lo .git/hooks/commit-msg http://localhost:8080/tools/hooks/commit-msg

chmod +x .git/hooks/commit-msg

  然后新建个js文件，写点代码并提交。

git push origin HEAD:refs/for/refs/meta/config # 提交到 refs/meta/config 分支

  然后在gerrit首页可以看到刚刚提交的代码，点击查看详情，可以看到代码审核的流程。

2.2 插件安装和配置

  将 ai-code-review 插件克隆到本地。插件详情可参考官方文档。此插件可以使用不同的 AI Chat 服务（例如 ChatGPT 或 OLLAMA）

git clone https://gerrit.googlesource.com/plugins/ai-code-review

  安装 Java 和构建工具

sudo apt update

sudo apt install -y openjdk-21-jdk maven  # 官方文档说 11 就行，但是我实际上跑了后发现需要 JDK 21+

  进去项目目录构建 JAR 包

cd ai-code-review

mvn clean package

  当输出BUILD BUILD SUCCESS时，表示构建成功。进入目录看下生成的包名。

  然后将生成的jar包复制到 gerrit 的 plugins 目录下

# 我这里容器名为 gerrit，JAR 文件在 target/ 目录

docker cp target/ai-code-review-3.11.0.jar gerrit:/var/gerrit/plugins/

  然后进入容器内看下插件列表，确认插件已经安装成功

  也可以在 gerrit 网页端查看插件启动情况

  接着修改配置文件，在 gerrit 的 etc 目录下找到 gerrit.config 文件。但在这之前需要在 Gerrit 中创建一个 AI Code Review 用户，这个席位用于 AI 来使用进行代码评审。

vi var/gerrit/etc/gerrit.config

  在文件里添加以下内容。

[plugin "ai-code-review"]

  model = deepseek-v3                       

  aiToken = ***                             

  aiDomain = ***     

  gerritUserName = AIReviewer               

  aiType = ChatGPT                          

  globalEnable = true                       。

• model(非必填): 使用的模型


• aiToken(必填): AI模型的密钥


• aiDomain(非必填): 请求地址，默认是 api.openai.com


• gerritUserName(必填): AI Code Review 用户的 Gerrit 用户名。我这里创建的用户名为 AIReviewer


• aiType(非必填): AI类型，默认是 ChatGPT


• globalEnable(非必填): 是否全局启用，默认是 false, 表示插件将仅审核指定的仓库。如果不设置为true的话。需要添加enabledProjects参数，指定要运行的存储库，例如：“project1,project2,project3”。

  更多字段配置参考官方文档

  这些都完成后，重启 gerrit 服务。然后修改下代码，写段明显有问题的代码，重新 commit 并 push 代码，看下 AI 代码评审的效果怎么样。

  可以看到 ai 审查代码的效果还是不错的。当然我这里是修改了插件的prompt，让它用中文生成评论，它默认是用英文回答的。

总结

  现在AI功能越来越强大,可以帮我们处理越来越多的事情。同时我也开发了一个工具AI-vue-i18n,能够智能提取代码中的中文内容,并利用AI完成翻译后生成多语言配置文件。告别手动配置的场景。

文章地址

github地址

GET /users/123       获取 ID 为 123 的用户

POST /users         创建新用户

PUT /users/123       更新用户 123

DELETE /users/123   删除用户 123

GET /orders

Header: Authorization: Bearer xxx

{

 "id": 123,

 "name": "小阿巴",

 "email": "aba@codefather.cn"

}

POST /orders/123/payments

你直接听懵了：阿巴阿巴，这么多约束，我必须全遵守吗？

鱼皮：可以不用，RESTful 只是一种 API 的 建议风格。在实际工作中，很少有 API 能完美符合所有约束，大家可以灵活调整，甚至什么接口都用 POST + 动词 一把梭。只要团队达成一致、用得舒服就行。

就像刚才那个支付订单的例子，POST /orders/123/payments 虽然符合 RESTful 规范，但有同学会觉得 POST /orders/123/pay 更直观易懂，也没问题。

不过现阶段，我建议你先养成遵循 RESTful 的好习惯，等积累了经验，再根据实际情况灵活调整。

怎么快速实现 RESTful API？

你：呜呜，但我只是个小阿巴，背不下来这些写法，我怕自己写着写着就不规范了，怎么办啊？

鱼皮：别担心，有很多方法可以帮你快速实现和检查 RESTful API。

1、使用开发框架

几乎所有主流开发框架都支持 RESTful API 的开发，它们能帮你自动处理很多细节，比如：

• Java 的 Spring Boot：通过 @GetMapping("/users")、@PostMapping("/users") 等注解，你只需要写一行代码就能定义符合 RESTful 风格的路由。框架会自动把对象转成 JSON、设置正确的 HTTP 状态码，你都不用操心。
• Python 的 Django REST Framework：你只需要定义一个数据模型（比如 User 类），框架就能自动生成 GET /users、POST /users、PUT /users/123、DELETE /users/123 这一整套 RESTful 接口，大幅减少代码量。
• Go 的 Gin ：专门为 RESTful API 设计，语法非常简洁。比如 router.GET("/users/:id", getUser) 就能绑定一个 GET 请求，自动从 URL 中提取 ID 参数，还能通过路由分组把 /api/v1/users 和 /api/v2/users 轻松分开管理。

这些框架虽然不强制你遵循 RESTful，但用它们的特性，开发起来既轻松又规范，帮你省掉大量重复代码。

2、使用 IDE 插件

比如 IDEA 的 RESTful Toolkit 插件，可以快速查看和测试接口。

还有 VSCode 的 REST Client 插件，可以直接在编辑器里测试接口。

3、利用 AI 生成

RESTful 有明确的设计规范，而 AI 最擅长处理这种有章可循的东西！

比如直接让 Cursor 帮你用 Spring Boot 写一个用户管理的 RESTful API：

你只需要阿巴阿巴几下，它就能生成规范的代码。

4、生成接口文档

写完接口后，还可以用 Swagger 这类工具自动生成漂亮的接口文档，直接甩给前端，对方一看就懂，还能在线测试接口，省去大量沟通成本。

你笑得像个孩子：这么一看，RESTful API 不仅让接口规范统一，还能提高开发效率，降低团队沟通成本，前后端都舒服！爽爽爽！

鱼皮点点头：没错，这也是为什么 RESTful 能成为业界主流的原因。

你：学会了学会了，我这就去重构所有接口，让前端阿花刮目相看！

结尾

一周后，你把所有接口重构成了 RESTful 风格。

前端阿花打开新的接口文档，眼睛亮了：小阿巴，你居然开窍了？！

你得意地笑了：那是，我可是学过 RESTful 的男人~ 阿花，晚上要不要一起？

阿花朝你吐了口唾沫：呸，你只不过学了一种 API 风格就得意洋洋。阿坤哥哥不仅精通 RESTful，还能手撕 GraphQL 和 gRPC 呢，你行么？

你难受得不行：啥啥啥，这都是啥啊…… 鱼皮 gie gie 快来救我！

大家好，我是小悟。

• 想象一下你去游乐园，买了一张通票（登录），然后就可以玩所有项目（访问各个系统），不用每个项目都重新买票（重新登录）。这就是单点登录（SSO）的精髓！
  
  

  SSO的日常比喻

  
  
  
  
  • 普通登录：像去不同商场，每个都要查会员卡
  
  
  • 单点登录：像微信扫码登录，一扫全搞定
  
  
  • 令牌：像游乐园手环，戴着就能证明你买过票
  
  
  
  

  下面用代码来实现这个"游乐园通票系统"：

  
  

  代码实现：简易SSO系统

  
  

  import java.util.*;
  
  
  
  // 用户类 - 就是我们这些想玩项目的游客
  
  class User {
  
      private String username;
  
      private String password;
  
      
  
      public User(String username, String password) {
  
          this.username = username;
  
          this.password = password;
  
      }
  
      
  
      // getters 省略...
  
  }
  
  
  
  // 令牌类 - 游乐园手环
  
  class Token {
  
      private String tokenId;
  
      private String username;
  
      private Date expireTime;
  
      
  
      public Token(String username) {
  
          this.tokenId = UUID.randomUUID().toString();
  
          this.username = username;
  
          // 令牌1小时后过期 - 游乐园晚上要关门的！
  
          this.expireTime = new Date(System.currentTimeMillis() + 3600 * 1000);
  
      }
  
      
  
      public boolean isValid() {
  
          return new Date().before(expireTime);
  
      }
  
      
  
      // getters 省略...
  
  }
  
  
  
  // SSO认证中心 - 游乐园售票处
  
  class SSOAuthCenter {
  
      private Map<String, Token> validTokens = new HashMap<>();
  
      private Map<String, User> users = new HashMap<>();
  
      
  
      public SSOAuthCenter() {
  
          // 预先注册几个用户 - 办了年卡的游客
  
          users.put("zhangsan", new User("zhangsan", "123456"));
  
          users.put("lisi", new User("lisi", "abcdef"));
  
      }
  
      
  
      // 登录 - 买票入场
  
      public String login(String username, String password) {
  
          User user = users.get(username);
  
          if (user != null && user.getPassword().equals(password)) {
  
              Token token = new Token(username);
  
              validTokens.put(token.getTokenId(), token);
  
              System.out.println(username + " 登录成功！拿到游乐园手环：" + token.getTokenId());
  
              return token.getTokenId();
  
          }
  
          System.out.println("用户名或密码错误！请重新买票！");
  
          return null;
  
      }
  
      
  
      // 验证令牌 - 检查手环是否有效
  
      public boolean validateToken(String tokenId) {
  
          Token token = validTokens.get(tokenId);
  
          if (token != null && token.isValid()) {
  
              System.out.println("手环有效，欢迎继续玩耍！");
  
              return true;
  
          }
  
          System.out.println("手环无效或已过期，请重新登录！");
  
          validTokens.remove(tokenId); // 清理过期令牌
  
          return false;
  
      }
  
      
  
      // 登出 - 离开游乐园
  
      public void logout(String tokenId) {
  
          validTokens.remove(tokenId);
  
          System.out.println("已登出，欢迎下次再来玩！");
  
      }
  
  }
  
  
  
  // 业务系统A - 过山车
  
  class SystemA {
  
      private SSOAuthCenter authCenter;
  
      
  
      public SystemA(SSOAuthCenter authCenter) {
  
          this.authCenter = authCenter;
  
      }
  
      
  
      public void accessSystem(String tokenId) {
  
          System.out.println("=== 欢迎来到过山车 ===");
  
          if (authCenter.validateToken(tokenId)) {
  
              System.out.println("过山车启动！尖叫声在哪里！");
  
          } else {
  
              System.out.println("请先登录再玩过山车！");
  
          }
  
      }
  
  }
  
  
  
  // 业务系统B - 旋转木马
  
  class SystemB {
  
      private SSOAuthCenter authCenter;
  
      
  
      public SystemB(SSOAuthCenter authCenter) {
  
          this.authCenter = authCenter;
  
      }
  
      
  
      public void accessSystem(String tokenId) {
  
          System.out.println("=== 欢迎来到旋转木马 ===");
  
          if (authCenter.validateToken(tokenId)) {
  
              System.out.println("木马转起来啦！找回童年记忆！");
  
          } else {
  
              System.out.println("请先登录再玩旋转木马！");
  
          }
  
      }
  
  }
  
  
  
  // 测试我们的SSO系统
  
  public class SSODemo {
  
      public static void main(String[] args) {
  
          // 创建认证中心 - 游乐园大门
  
          SSOAuthCenter authCenter = new SSOAuthCenter();
  
          
  
          // 张三登录
  
          String token = authCenter.login("zhangsan", "123456");
  
          
  
          if (token != null) {
  
              // 拿着同一个令牌玩不同项目
  
              SystemA systemA = new SystemA(authCenter);
  
              SystemB systemB = new SystemB(authCenter);
  
              
  
              systemA.accessSystem(token);  // 玩过山车
  
              systemB.accessSystem(token);  // 玩旋转木马
  
              
  
              // 登出
  
              authCenter.logout(token);
  
              
  
              // 再尝试访问 - 应该被拒绝
  
              systemA.accessSystem(token);
  
          }
  
          
  
          // 测试错误密码
  
          authCenter.login("lisi", "wrongpassword");
  
      }
  
  }
  
  

  
  

  运行结果示例：

  
  

  zhangsan 登录成功！拿到游乐园手环：a1b2c3d4-e5f6-7890-abcd-ef1234567890
  
  === 欢迎来到过山车 ===
  
  手环有效，欢迎继续玩耍！
  
  过山车启动！尖叫声在哪里！
  
  === 欢迎来到旋转木马 ===
  
  手环有效，欢迎继续玩耍！
  
  木马转起来啦！找回童年记忆！
  
  已登出，欢迎下次再来玩！
  
  === 欢迎来到过山车 ===
  
  手环无效或已过期，请重新登录！
  
  请先登录再玩过山车！
  
  用户名或密码错误！请重新买票！
  
  

  
  

  总结一下：

  
  

  单点登录就像：

  
  
  
  
  • 一次认证，处处通行 🎫
  
  
  • 不用重复输入密码 🔑
  
  
  • 安全又方便 👍
  
  
  
  

  好的SSO系统就像好的游乐园管理，既要让游客玩得开心，又要确保安全！

谢谢你看我的文章，既然看到这里了，如果觉得不错，随手点个赞、转发、在看三连吧，感谢感谢。那我们，下次再见。

您的一键三连，是我更新的最大动力，谢谢

山水有相逢，来日皆可期，谢谢阅读，我们再会

我手中的金箍棒，上能通天，下能探海

作者：面汤放盐 / uzong

在软件开发的世界里，我们习惯用代码表达逻辑，但当系统涉及多个角色、多个服务、甚至跨团队协作时，光靠代码注释或口头沟通，往往不够。这时候，一张清晰的流程图，胜过千行文档。

泳道图 ：它可能不像 UML 那样“高大上”，也不如架构图那样宏观，但在梳理业务流程、厘清责任边界、排查系统瓶颈时，它真的非常实用。

1. 什么是泳道图

泳道图的核心思想很简单：把流程中的每个步骤，按执行者（人、系统、模块）分组排列，就像游泳池里的泳道一样，各走各道，互不干扰又彼此关联。

每一列就是一个“泳道”，代表一个责任主体。流程从左到右、从上到下流动，谁在什么时候做了什么，一目了然

一眼就能看出：谁干了什么，谁依赖谁，边界是什么。

与流程的差异点：

• 流程图聚焦：“步骤顺序”，侧重 “先做什么、再做什么”，适合梳理线性业务流程；


• 泳道图聚焦： “流转通道”，侧重 “什么东西在什么约束下通过什么路径流转”，适合拆解复杂、多路径、有规则约束的流转场景（如分布式系统数据同步、供应链物料流转、微服务请求链路等）

2. 泳道图分类

2.1. 垂直泳道图

垂直泳道图采取上下布局结构，‌主要强调职能群体。这种布局方式更适合于展示跨职能任务和流程中，‌各职能部门或角色之间的垂直关系和职能分工。

2.2. 水平泳道图

水平泳道图则采用左右布局结构，‌重点在于事件进程的展示。这种布局方式更适合于强调事件或过程的水平流动，‌以及不同阶段或部门在流程中的水平参与

3. 泳道图组成元素

泳池： 泳池是泳道图的外部框架，泳道、流程都包含于泳池内。

泳道： 泳池里可以创建多个泳道。

流程： 实际的业务流程。

部门： 通过部门或者责任来区分，明确每个部门/人/信息系统负责完成的任务环节。

阶段： 通过任务阶段来区分，明确每个阶段需要处理的任务环节。

4. 泳道图应用场景

4.1. 项目管理

展示项目从启动到完成的各个阶段，明确每个团队或成员在项目中的角色和职责，便于进行项目管理和监控，同时促进团队协作和沟通

4.2. 业务流程分析

展示业务流程的各个环节和涉及的不同部门或职能。通过分析泳道图，可以发现业务流程中的瓶颈、冗余环节或不合理之处，进而进行流程优化和改进。

4.3. 系统设计

展示系统的整体架构和各个组件之间的关系，描述系统的工作流程，包括数据的输入、处理、输出等各个环节，有助于系统开发人员更好地理解系统的功能和需求

5. 更多参考模板

故障处理多维泳道图

资源扩容泳道图

6. 最后

我刚工作时，看到导师抛出一份精致的泳道图，把一团乱麻的问题讲得透亮，心里特别佩服。直到自己多年后用上才真正体会：在面对跨部门协作、复杂故障排查、关键流程设计时，掏出这么一张图，往往就是高效沟通的开始。

作为开发者，我们常陷入“只要代码跑得通就行”的思维惯性。但软件不仅是机器执行的指令，更是人与人协作的媒介。泳道图这样的工具，本质上是在降低认知成本——让复杂的事情变得可沟通、可验证、可迭代。 其实泳道图的核心不是“画图”，而是“梳理流程、明确权责”。

在跨部门、协同需求、故障分析等关键场景使用泳道图是非常合适，并且也能把问题讲清楚。技术世界充满了抽象和复杂性，而优秀工程师的能力之一，就是创建合适的可视化工具，让复杂问题变得简单可见。

本文中的大部分图片来源于 ProcessOn，ProcessOn 是一个非常不错的画图软件，功能强大，界面优美。

你是小阿巴，刚入职的低级程序员，正在开发一个批量导入数据的程序。

没想到，程序刚上线，产品经理就跑过来说：小阿巴，用户反馈你的程序有 Bug，刚导入没多久就报错中断了！

你赶紧打开服务器，看着比你发量都少的报错信息：

你一脸懵逼：只有这点儿信息，我咋知道哪里出了问题啊？！

你只能硬着头皮让产品经理找用户要数据，然后一条条测试，看看是哪条数据出了问题……

原本大好的摸鱼时光，就这样无了。

这时，你的导师鱼皮走了过来，问道：小阿巴，你是持矢了么？脸色这么难看？

你无奈地说：皮哥，刚才线上出了个 bug，我花了 8 个小时才定位到问题……

鱼皮皱了皱眉：这么久？你没打日志吗？

你很是疑惑：谁是日志？为什么要打它？

鱼皮叹了口气：唉，难怪你要花这么久…… 来，我教你打日志！

⭐️ 本文对应视频版：bilibili.com/video/BV1K7…

什么是日志？

鱼皮打开电脑，给你看了一段代码：

@Slf4j

public class UserService {

   public void batchImport(List<UserDTO> userList) {

       log.info("开始批量导入用户，总数：{}", userList.size());

       

       int successCount = 0;

       int failCount = 0;

       

       for (UserDTO userDTO : userList) {

           try {

               log.info("正在导入用户：{}", userDTO.getUsername());

               validateUser(userDTO);

               saveUser(userDTO);

               successCount++;

               log.info("用户 {} 导入成功", userDTO.getUsername());

          } catch (Exception e) {

               failCount++;

               log.error("用户 {} 导入失败，原因：{}", userDTO.getUsername(), e.getMessage(), e);

          }

      }

       

       log.info("批量导入完成，成功：{}，失败：{}", successCount, failCount);

  }

}

你看着代码里的 log.info、log.error，疑惑地问：这些 log 是干什么的？

鱼皮：这就是打日志。日志用来记录程序运行时的状态和信息，这样当系统出现问题时，我们可以通过日志快速定位问题。

你若有所思：哦？还可以这样！如果当初我的代码里有这些日志，一眼就定位到问题了…… 那我应该怎么打日志？用什么技术呢？

怎么打日志？

鱼皮：每种编程语言都有很多日志框架和工具库，比如 Java 可以选用 Log4j 2、Logback 等等。咱们公司用的是 Spring Boot，它默认集成了 Logback 日志框架，你直接用就行，不用再引入额外的库了~

日志框架的使用非常简单，先获取到 Logger 日志对象。

1）方法 1：通过 LoggerFactory 手动获取 Logger 日志对象：

public class MyService {

   private static final Logger logger = LoggerFactory.getLogger(MyService.class);

}

2）方法 2：使用 this.getClass 获取当前类的类型，来创建 Logger 对象：

public class MyService {

   private final Logger logger = LoggerFactory.getLogger(this.getClass());

}

然后调用 logger.xxx（比如 logger.info）就能输出日志了。

public class MyService {

   private final Logger logger = LoggerFactory.getLogger(this.getClass());

​

   public void doSomething() {

       logger.info("执行了一些操作");

  }

}

效果如图：

小阿巴：啊，每个需要打日志的类都要加上这行代码么？

鱼皮：还有更简单的方式，使用 Lombok 工具库提供的 @Slf4j 注解，可以自动为当前类生成日志对象，不用手动定义啦。

@Slf4j

public class MyService {

   public void doSomething() {

       log.info("执行了一些操作");

  }

}

上面的代码等同于 “自动为当前类生成日志对象”：

private static final org.slf4j.Logger log = 

   org.slf4j.LoggerFactory.getLogger(MyService.class);

你咧嘴一笑：这个好，爽爽爽！

等等，不对，我直接用 Java 自带的 System.out.println 不也能输出信息么？何必多此一举？

System.out.println("开始导入用户" + user.getUsername());

鱼皮摇了摇头：千万别这么干！

首先，System.out.println 是一个同步方法，每次调用都会导致耗时的 I/O 操作，频繁调用会影响程序的性能。

而且它只能输出信息到控制台，不能灵活控制输出位置、输出格式、输出时机等等。比如你现在想看三天前的日志，System.out.println 的输出早就被刷没了，你还得浪费时间找半天。

你恍然大悟：原来如此！那使用日志框架就能解决这些问题吗？

鱼皮点点头：没错，日志框架提供了丰富的打日志方法，还可以通过修改日志配置文件来随心所欲地调教日志，比如把日志同时输出到控制台和文件中、设置日志格式、控制日志级别等等。

在下苦心研究日志多年，沉淀了打日志的 8 大邪修秘法，先传授你 2 招最基础的吧。

打日志的 8 大最佳实践

1、合理选择日志级别

第一招，日志分级。

你好奇道：日志还有级别？苹果日志、安卓日志？

鱼皮给了你一巴掌：可不要乱说，日志的级别是按照重要程度进行划分的。

其中 DEBUG、INFO、WARN 和 ERROR 用的最多。

• 调试用的详细信息用 DEBUG


• 正常的业务流程用 INFO


• 可能有问题但不影响主流程的用 WARN


• 出现异常或错误的用 ERROR

log.debug("用户对象的详细信息：{}", userDTO);  // 调试信息

log.info("用户 {} 开始导入", username);  // 正常流程信息

log.warn("用户 {} 的邮箱格式可疑，但仍然导入", username);  // 警告信息

log.error("用户 {} 导入失败", username, e);  // 错误信息

你挠了挠头：俺直接全用 DEBUG 不行么？

鱼皮摇了摇头：如果所有信息都用同一级别，那出了问题时，你怎么快速找到错误信息？

在生产环境，我们通常会把日志级别调高（比如 INFO 或 WARN），这样 DEBUG 级别的日志就不会输出了，防止重要信息被无用日志淹没。

你点点头：俺明白了，不同的场景用不同的级别！

2、正确记录日志信息

鱼皮：没错，下面教你第二招。你注意到我刚才写的日志里有一对大括号 {} 吗？

log.info("用户 {} 开始导入", username);

你回忆了一下：对哦，那是啥啊？

鱼皮：这叫参数化日志。{} 是一个占位符，日志框架会在运行时自动把后面的参数值替换进去。

你挠了挠头：我直接用字符串拼接不行吗？

log.info("用户 " + username + " 开始导入");

鱼皮摇摇头：不推荐。因为字符串拼接是在调用 log 方法之前就执行的，即使这条日志最终不被输出，字符串拼接操作还是会执行，白白浪费性能。

你点点头：确实，而且参数化日志比字符串拼接看起来舒服~

鱼皮：没错。而且当你要输出异常信息时，也可以使用参数化日志：

try {

   // 业务逻辑

} catch (Exception e) {

   log.error("用户 {} 导入失败", username, e);  // 注意这个 e

}

这样日志框架会同时记录上下文信息和完整的异常堆栈信息，便于排查问题。

你抱拳：学会了，我这就去打日志！

3、把控时机和内容

很快，你给批量导入程序的代码加上了日志：

@Slf4j

public class UserService {

   public BatchImportResult batchImport(List<UserDTO> userList) {

       log.info("开始批量导入用户，总数：{}", userList.size());

       int successCount = 0;

       int failCount = 0;

       for (UserDTO userDTO : userList) {

           try {

               log.info("正在导入用户：{}", userDTO.getUsername());   

               // 校验用户名

               if (StringUtils.isBlank(userDTO.getUsername())) {

                   throw new BusinessException("用户名不能为空");

              }

               // 保存用户

               saveUser(userDTO);

               successCount++;

               log.info("用户 {} 导入成功", userDTO.getUsername());

          } catch (Exception e) {

               failCount++;

               log.error("用户 {} 导入失败，原因：{}", userDTO.getUsername(), e.getMessage(), e);

          }

      }

       log.info("批量导入完成，成功：{}，失败：{}", successCount, failCount);

       return new BatchImportResult(successCount, failCount);

  }

}

光做这点还不够，你还翻出了之前的屎山代码，想给每个文件都打打日志。

但打着打着，你就不耐烦了：每段代码都要打日志，好累啊！但是不打日志又怕出问题，怎么办才好？

鱼皮笑道：好问题，这就是我要教你的第三招 —— 把握打日志的时机。

对于重要的业务功能，我建议采用防御性编程，先多多打日志。比如在方法代码的入口和出口记录参数和返回值、在每个关键步骤记录执行状态，而不是等出了问题无法排查的时候才追悔莫及。之后可以再慢慢移除掉不需要的日志。

你叹了口气：这我知道，但每个方法都打日志，工作量太大，都影响我摸鱼了！

鱼皮：别担心，你可以利用 AOP 切面编程，自动给每个业务方法的执行前后添加日志，这样就不会错过任何一次调用信息了。

你双眼放光：这个好，爽爽爽！

鱼皮：不过这样做也有一个缺点，注意不要在日志中记录了敏感信息，比如用户密码。万一你的日志不小心泄露出去，就相当于泄露了大量用户的信息。

你拍拍胸脯：必须的！

4、控制日志输出量

一个星期后，产品经理又来找你了：小阿巴，你的批量导入功能又报错啦！而且怎么感觉程序变慢了？

你完全不慌，淡定地打开服务器的日志文件。结果瞬间呆住了……

好家伙，满屏都是密密麻麻的日志，这可怎么看啊？！

鱼皮看了看你的代码，摇了摇头：你现在每导入一条数据都要打一些日志，如果用户导入 10 万条数据，那就是几十万条日志！不仅刷屏，还会影响性能。

你有点委屈：不是你让我多打日志的么？那我应该怎么办？

鱼皮：你需要控制日志的输出量。

1）可以添加条件来控制，比如每处理 100 条数据时才记录一次：

if ((i + 1) % 100 == 0) {

   log.info("批量导入进度：{}/{}", i + 1, userList.size());

}

2）或者在循环中利用 StringBuilder 进行字符串拼接，循环结束后统一输出：

StringBuilder logBuilder = new StringBuilder("处理结果：");

for (UserDTO userDTO : userList) {

   processUser(userDTO);

   logBuilder.append(String.format("成功[ID=%s], ", userDTO.getId()));

}

log.info(logBuilder.toString());

3）还可以通过修改日志配置文件，过滤掉特定级别的日志，防止日志刷屏：

<appender name="FILE" class="ch.qos.logback.core.FileAppender">

   <file>logs/app.log</file>

   <!-- 只允许 INFO 级别及以上的日志通过 -->

   <filter class="ch.qos.logback.classic.filter.ThresholdFilter">

       <level>INFO</level>

   </filter>

</appender>

5、统一日志格式

你开心了：好耶，这样就不会刷屏了！但是感觉有时候日志很杂很乱，尤其是我想看某一个请求相关的日志时，总是被其他的日志干扰，怎么办？

鱼皮：好问题，可以在日志配置文件中定义统一的日志格式，包含时间戳、线程名称、日志级别、类名、方法名、具体内容等关键信息。

<!-- 控制台日志输出 -->

<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">

   <encoder>

       <!-- 日志格式 -->

       <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>

   </encoder>

</appender>

这样输出的日志更整齐易读：

此外，你还可以通过 MDC（Mapped Diagnostic Context）给日志添加额外的上下文信息，比如请求 ID、用户 ID 等，方便追踪。

在 Java 代码中，可以为 MDC 设置属性值：

@PostMapping("/user/import")

public Result importUsers(@RequestBody UserImportRequest request) {

   // 1. 设置 MDC 上下文信息

   MDC.put("requestId", generateRequestId());

   MDC.put("userId", String.valueOf(request.getUserId()));

   try {

       log.info("用户请求处理完成");      

       // 执行具体业务逻辑

       userService.batchImport(request.getUserList());     

       return Result.success();

  } finally {

       // 2. 及时清理MDC（重要！）

       MDC.clear();

  }

}

然后在日志配置文件中就可以使用这些值了：

<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">

   <encoder>

       <!-- 包含 MDC 信息 -->

       <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - [%X{requestId}] [%X{userId}] %msg%n</pattern>

   </encoder>

</appender>

这样，每个请求、每个用户的操作一目了然。

6、使用异步日志

你又开心了：这样打出来的日志，确实舒服，爽爽爽！但是我打日志越多，是不是程序就会更慢呢？有没有办法能优化一下？

鱼皮：当然有，可以使用 异步日志。

正常情况下，你调用 log.info() 打日志时，程序会立刻把日志写入文件，这个过程是同步的，会阻塞当前线程。而异步日志会把写日志的操作放到另一个线程里去做，不会阻塞主线程，性能更好。

你眼睛一亮：这么厉害？怎么开启？

鱼皮：很简单，只需要修改一下配置文件：

<appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender">

   <queueSize>512</queueSize>  <!-- 队列大小 -->

   <discardingThreshold>0</discardingThreshold>  <!-- 丢弃阈值，0 表示不丢弃 -->

   <neverBlock>false</neverBlock>  <!-- 队列满时是否阻塞，false 表示会阻塞 -->

   <appender-ref ref="FILE" />  <!-- 引用实际的日志输出目标 -->

</appender>

<root level="INFO">

   <appender-ref ref="ASYNC" />

</root>

不过异步日志也有缺点，如果程序突然崩溃，缓冲区中还没来得及写入文件的日志可能会丢失。

所以要权衡一下，看你的系统更注重性能还是日志的完整性。

你想了想：我们的程序对性能要求比较高，偶尔丢几条日志问题不大，那我就用异步日志吧。

7、日志管理

接下来的很长一段时间，你混的很舒服，有 Bug 都能很快发现。

你甚至觉得 Bug 太少、工作没什么激情，所以没事儿就跟新来的实习生阿坤吹吹牛皮：你知道日志么？我可会打它了！

直到有一天，运维小哥突然跑过来：阿巴阿巴，服务器挂了！你快去看看！

你连忙登录服务器，发现服务器的硬盘爆满了，没法写入新数据。

你查了一下，发现日志文件竟然占了 200GB 的空间！

你汗流浃背了，正在考虑怎么甩锅，结果阿坤突然鸡叫起来：阿巴 giegie，你的日志文件是不是从来没清理过？

你尴尬地倒了个立，这样眼泪就不会留下来。

鱼皮叹了口气：这就是我要教你的下一招 —— 日志管理。

你好奇道：怎么管理？我每天登服务器删掉一些历史文件？

鱼皮：人工操作也太麻烦了，我们可以通过修改日志配置文件，让框架帮忙管理日志。

首先设置日志的滚动策略，可以根据文件大小和日期，自动对日志文件进行切分。

<rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">

   <fileNamePattern>logs/app-%d{yyyy-MM-dd}.%i.log</fileNamePattern>

   <maxFileSize>10MB</maxFileSize>

   <maxHistory>30</maxHistory>

</rollingPolicy>

这样配置后，每天会创建一个新的日志文件（比如 app-2025-10-23.0.log），如果日志文件大小超过 10MB 就再创建一个（比如 app-2025-10-23.1.log），并且只保留最近 30 天的日志。

还可以开启日志压缩功能，进一步节省磁盘空间：

<rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">

   <!-- .gz 后缀会自动压缩 -->

   <fileNamePattern>logs/app-%d{yyyy-MM-dd}.log.gz</fileNamePattern>

</rollingPolicy>

你有些激动：吼吼，这样我们就可以按照天数更快地查看日志，服务器硬盘也有救啦！

8、集成日志收集系统

两年后，你负责的项目已经发展成了一个大型的分布式系统，有好几十个微服务。

如今，每次排查问题你都要登录到不同的服务器上查看日志，非常麻烦。而且有些请求的调用链路很长，你得登录好几台服务器、看好几个服务的日志，才能追踪到一个请求的完整调用过程。

你简直要疯了！

于是你找到鱼皮求助：现在查日志太麻烦了，当年你还有一招没有教我，现在是不是……

鱼皮点点头：嗯，对于分布式系统，就必须要用专业的日志收集系统了，比如很流行的 ELK。

你好奇：ELK 是啥？伊拉克？

阿坤抢答道：我知道，就是 Elasticsearch + Logstash + Kibana 这套组合。

简单来说，Logstash 负责收集各个服务的日志，然后发送给 Elasticsearch 存储和索引，最后通过 Kibana 提供一个可视化的界面。

这样一来，我们可以方便地集中搜索、查看、分析日志。

你惊讶了：原来日志还能这么玩，以后我所有的项目都要用 ELK！

鱼皮摆摆手：不过 ELK 的搭建和运维成本比较高，对于小团队来说可能有点重，还是要按需采用啊。

结局

至此，你已经掌握了打日志的核心秘法。

只是你很疑惑，为何那阿坤竟对日志系统如此熟悉？

阿坤苦笑道：我本来就是日志管理大师，可惜我上家公司的同事从来不打日志，所以我把他们暴打了一顿后跑路了。

阿巴 giegie 你要记住，日志不是写给机器看的，是写给未来的你和你的队友看的！

你要是以后不打日志，我就打你！

更多

💻 编程学习交流：编程导航 📃 简历快速制作：老鱼简历 ✏️ 面试刷题神器：面试鸭

前言

“分库分表这种架构模式会逐步的被淘汰！” 不知道在哪儿看到的观点

如果我们现在在搭建新的业务架构，如果说你们未来的业务数据量会达到千万 或者上亿的级别 还在一股脑的使用分库分表的架构，那么你们的技术负责人真的就应该提前退休了🙈

如果对未来的业务非常有信心，单表的数据量能达到千万上亿的级别，请使用NewSQL 数据库，那么NewSQL 这么牛，分布库分表还有意义吗？

今天虽然写的是一篇博客，但是更多的是抱着和大家讨论的心态来的，所以大家目前有深度参与分库分表，或者NewSQL 的都可以在评论区讨论！

什么是NewSQL

NewSQL 是21世纪10年代初出现的一个术语，用来描述一类新型的关系型数据库管理系统（RDBMS）。它们的共同目标是：在保持传统关系型数据库（如Oracle、MySQL）的ACID事务和SQL模型优势的同时，获得与NoSQL系统类似的、弹性的水平扩展能力

NewSQL 的核心理念就是 将“分库分表”的复杂性从应用层下沉到数据库内核层，对上层应用呈现为一个单一的数据库入口，解决现在 分库分表的问题；

分库分表的问题

分库分表之后，会带来非常多的问题；比如需要跨库联查、跨库更新数据如何保证事务一致性等问题，下面就来详细看看分库分表都有那些问题

选择TiDB还是采用mysql 分库分表的设计

数据量非常大，需要满足OLTP (Online Transactional Processing)、OLAP (Online Analytical Processing)、HTAP 且预算充足（分布式数据库的成本也是非常高的这一点非常的重要），并且是新业务新架构落地 优先推荐使用TiDB。
当然实际上选择肯定是需要多方面考虑的，大家有什么观点都可以在评论区讨论。

可以看看一个资深开发，深度参与TiDB项目，他对TiDB的一些看法：

1 什么是TiDB？

TiDB是PingCAP公司研发的开源分布式关系型数据库，采用存储计算分离架构，支持混合事务分析处理（HTAP） 。它与MySQL 5.7协议兼容，并支持MySQL生态，这意味着使用MySQL的应用程序可以几乎无需修改代码就能迁移到TiDB。

🚀目标是为用户提供一站式 OLTP (Online Transactional Processing)、OLAP (Online Analytical Processing)、HTAP 解决方案。TiDB 适合高可用、强一致要求较高、数据规模较大等各种应用场景。

官方文档：docs.pingcap.com/zh/tidb/dev…

TiDB五大核心特性

TiDB之所以在分布式数据库领域脱颖而出，得益于其五大核心特性：

• 一键水平扩容或缩容：得益于存储计算分离的架构设计，可按需对计算、存储分别进行在线扩容或缩容，整个过程对应用透明。


• 金融级高可用：数据采用多副本存储，通过Multi-Raft协议同步事务日志，只有多数派写入成功事务才能提交，确保数据强一致性。


• 实时HTAP：提供行存储引擎TiKV和列存储引擎TiFlash，两者之间的数据保持强一致，解决了HTAP资源隔离问题。


• 云原生分布式数据库：通过TiDB Operator可在公有云、私有云、混合云中实现部署工具化、自动化。


• 兼容MySQL 5.7协议和生态：从MySQL迁移到TiDB无需或只需少量代码修改，极大降低了迁移成本。

2 TiDB与MySQL的核心差异

虽然TiDB兼容MySQL协议，但它们在架构设计和适用场景上存在根本差异。以下是它们的详细对比：

2.1 架构差异

表1：TiDB与MySQL架构对比

2.2 性能表现对比

性能方面，TiDB与MySQL各有优势，主要取决于数据量和查询类型：

• 小数据量简单查询：在数据量百万级以下的情况下，MySQL的写入性能和点查点写通常优于TiDB。因为TiDB的分布式架构在少量数据时无法充分发挥优势，却要承担分布式事务的开销。


• 大数据量复杂查询：当数据量达到千万级以上，TiDB的性能优势开始显现。一张千万级别表关联查询，MySQL可能需要20秒，而TiDB+TiKV只需约5.57秒，使用TiFlash甚至可缩短到0.5秒。


• 高并发场景：MySQL性能随着并发增加会达到瓶颈然后下降，而TiDB性能基本随并发增加呈线性提升，节点资源不足时还可通过动态扩容提升性能。

2.3 扩展性与高可用对比

MySQL的主要扩展方式是一主多从架构，主节点无法横向扩展（除非接受分库分表），从节点扩容需要应用支持读写分离。而TiDB的存储和计算节点都可以独立扩容，支持最大512节点，集群容量可达PB级别。

高可用方面，MySQL使用增强半同步和MGR方案，但复制效率较低，主节点故障会影响业务处理[]。TiDB则通过Raft协议将数据打散分布，单机故障对集群影响小，能保证RTO（恢复时间目标）不超过30秒且RPO（恢复点目标）为0，真正实现金融级高可用。

2.4 SQL功能及兼容性

虽然TiDB高度兼容MySQL 5.7协议和生态，但仍有一些重要差异需要注意：

不支持的功能包括：

• 存储过程与函数


• 触发器


• 事件


• 自定义函数


• 全文索引（计划中）


• 空间类型函数和索引

有差异的功能包括：

• 自增ID的行为（TiDB推荐使用AUTO_RANDOM避免热点问题）


• 查询计划的解释结果


• 在线DDL能力（TiDB更强，不锁表支持DML并行操作）

3 如何选择：TiDB还是MySQL？

选择数据库时，应基于实际业务需求和技术要求做出决策。以下是具体的选型建议：

3.1 选择TiDB的场景

TiDB在以下场景中表现卓越：

3.2 选择MySQL的场景

MySQL在以下情况下仍是更合适的选择：

3.3 决策参考框架

为了更直观地帮助决策，可以参考以下决策表：

4 迁移注意事项

如果决定从MySQL迁移到TiDB，需要注意以下关键点：

5 总结

TiDB和MySQL是适用于不同场景的数据库解决方案，没有绝对的优劣之分。MySQL是优秀的单机数据库，适用于数据量小、架构简单的场景；数据量大了之后需要做分库分表。而TiDB作为分布式数据库，专注于解决大数据量、高并发、高可用性需求下的数据库瓶颈问题，但是成本也是非常的高

本人没有使用过NewSQL ，还望各位大佬批评指正