从 SkyWalking 专用实现迁移到 OpenTelemetry：搭建可复刻的分布式 Trace、日志中心与异步访问日志系统

本文记录一次真实 Java 微服务项目的可观测性改造：使用 OpenTelemetry Java Agent 自动采集 Trace 和
SLF4J/Logback 日志，经 OpenTelemetry Collector 写入 Elasticsearch 9.x，再用 Kibana 按 Trace ID
串联一次请求涉及的 HTTP、Feign、JDBC、RocketMQ 和业务日志；同时将数据库 API 访问日志从同步
Feign 调用改为 RocketMQ 异步、幂等落库。

文中的代码、配置和验证结果来自一个 Spring Boot 4.1、JDK 25、Spring Cloud 微服务项目。版本基线
截至 2026-08-23。中间件升级很快，复制到新项目时应再次核对官方发布页。

本文对应的核心文件

如果读者正在查看配套仓库，可以用下面的索引快速定位完整实现：

一、为什么要重做分布式日志方案

微服务系统出现线上问题时，我们通常需要回答下面几个问题：

1. 用户的这次请求经过了哪些服务？
2. 每一跳分别耗时多久？慢在网关、数据库、远程调用还是消息队列？
3. 某一条异常日志属于哪一次请求？
4. 请求返回给前端的 Trace ID，能否直接检索出完整调用链和相关日志？
5. API 访问日志落库是否会增加业务接口延迟？
6. 消息重复投递时，数据库是否会出现重复访问日志？

旧实现存在两个典型问题。

第一，业务代码直接依赖 SkyWalking Toolkit，并在网关、异常处理器等位置调用专有 API。这样做会让
业务代码与具体 APM 产品绑定，后续切换后端或采集方案时改动面很大。

第二，API 访问日志通过 Feign 同步调用 infra 服务落库。访问日志本质上属于旁路审计数据，业务线程
不应该等待日志服务和数据库；一旦 infra 服务抖动，日志链路还可能反向拖慢甚至影响业务请求。

本次改造确立了以下目标：

• 使用厂商中立的 OpenTelemetry 标准；
• 尽量通过 Java Agent 零侵入采集，减少手工埋点；
• Trace 与 SLF4J 日志通过同一个 trace_id 关联；
• 应用只连接 Collector，不直接连接 Elasticsearch；
• API 访问日志通过 RocketMQ 异步落库；
• 考虑 RocketMQ 至少一次投递，实现消费者幂等；
• 保留多租户上下文；
• 本地、IDE、Docker 和生产环境使用同一套协议和拓扑；
• Elasticsearch 使用 9.x 原生 OTLP Endpoint，不再额外维护自定义日志索引映射。

二、先区分三类“日志”

在开始搭建之前，必须先区分下面三类数据。很多方案的问题，正是因为把它们混为一谈。

2.1 Trace 与 Span

Trace 表示一次端到端请求，Trace 内部由多个 Span 组成。例如：

Browser
  -> Gateway HTTP Server Span
  -> System HTTP Server Span
  -> Feign Client Span
  -> Infra HTTP Server Span
  -> JDBC Client Span

整个调用链共享一个 32 位十六进制 Trace ID，每个 Span 有自己的 16 位 Span ID。

2.2 应用日志

应用日志是代码通过 SLF4J 输出的内容：

log.info("[getPermissionInfo][OpenTelemetry 链路验证，userId({})]", userId);

Java Agent 会捕获 Logback 日志事件，并在事件发生时附加当前 trace_id、span_id。因此同一请求中的
业务日志可以和 Trace 关联。

2.3 API 访问日志

API 访问日志是结构化审计记录，通常包含：

• 用户与租户；
• 应用名；
• URL、HTTP Method、IP、User-Agent；
• 脱敏后的请求参数；
• 返回码、错误信息；
• 开始时间、结束时间、耗时；
• Trace ID。

它需要分页查询、合规留存和业务报表，所以仍然落在关系型数据库中。但落库不应该阻塞业务线程，
因此改为 RocketMQ 异步处理。

最终形成两条互相独立、又通过 Trace ID 关联的数据链路：

三、技术选型

3.1 组件与版本

本次实现采用以下版本：

版本资料：

• OpenTelemetry Java Agent 官方文档
• OpenTelemetry Java Agent Releases
• OpenTelemetry Java Releases
• OpenTelemetry Collector Releases
• Elastic 原生 OTLP Endpoint
• Elasticsearch Release Notes
• RocketMQ Release Notes
• W3C Trace Context

3.2 为什么选择 Java Agent，而不是在应用里初始化完整 SDK

Java Agent 的优势是：

• 在应用 main 方法前加载；
• 自动创建 HTTP Server/Client Span；
• 自动处理 Feign、JDBC、RocketMQ 等常用组件；
• 自动注入和提取 W3C traceparent、baggage；
• 自动捕获 Logback 日志；
• 不需要每个服务重复编写 SDK、Exporter、Processor 初始化代码；
• 采集配置可以通过环境变量统一管理。

应用代码只保留 opentelemetry-api，用于读取当前 Trace ID 或创建少量业务 Span：

<properties>
    <opentelemetry.version>1.64.0</opentelemetry.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-api</artifactId>
            <version>${opentelemetry.version}</version>
        </dependency>
    </dependencies>
</dependencyManagement>

不要同时在应用中初始化一套 OpenTelemetry SDK，又加载 Java Agent。两套 SDK/Exporter 并存容易导致：

• 重复 Span；
• 重复日志；
• GlobalOpenTelemetry 注册冲突；
• 版本依赖复杂；
• 资源属性和采样策略不一致。

3.3 为什么必须保留 Collector

应用理论上可以直接把 OTLP 发给 Elasticsearch，但生产环境不建议这么做。Collector 提供了应用与存储
后端之间的隔离层：

• 批量发送，降低后端请求数；
• 内存保护；
• 发送队列；
• 失败重试；
• 统一认证和 TLS；
• 数据过滤、脱敏和属性补充；
• 后续替换或并行导出到其他后端时，不需要修改所有应用。

应用只知道 Collector 的 OTLP 地址，不需要知道 Elasticsearch 的地址和凭证。

3.4 为什么访问日志选 RocketMQ，而不是线程池异步

@Async 或本地线程池只能把数据库操作移出请求线程，但无法解决：

• 应用进程崩溃导致内存任务丢失；
• infra 服务临时不可用；
• 消费速度低于生产速度；
• 跨服务削峰；
• 重试和死信管理。

RocketMQ 提供持久化、消费组、重试和死信队列，更适合审计日志事件。但 RocketMQ 是至少一次投递，
所以必须额外设计幂等。

四、总体调用过程

下面是一条用户请求从前端到 ES 和访问日志数据库的完整时序。

五、应用侧接入 OpenTelemetry

5.1 下载并校验 Java Agent

不要在构建时下载一个不固定版本的 latest 文件。应固定版本，并校验 SHA-256：

mkdir -p .local/otel

curl -fL \
  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.28.1/opentelemetry-javaagent.jar \
  -o .local/otel/opentelemetry-javaagent.jar

echo "faa89bdeebf9b1f52be4a4374689176717b02a59df2d8f8b6eb9aa39f9292589  .local/otel/opentelemetry-javaagent.jar" \
  | sha256sum -c -

校验成功应输出：

.local/otel/opentelemetry-javaagent.jar: OK

5.2 IDE 启动参数

System 服务的 VM options：

-javaagent:/absolute/path/opentelemetry-javaagent.jar
-Dotel.service.name=system-server
-Dotel.exporter.otlp.endpoint=http://127.0.0.1:4318
-Dotel.exporter.otlp.protocol=http/protobuf
-Dotel.propagators=tracecontext,baggage
-Dotel.traces.exporter=otlp
-Dotel.logs.exporter=otlp
-Dotel.metrics.exporter=none

Infra 服务只需要修改服务名：

-Dotel.service.name=infra-server

Gateway 服务使用：

-Dotel.service.name=gateway-server

几个关键配置的含义：

启动日志中应出现类似内容：

[otel.javaagent] opentelemetry-javaagent - version: 2.28.1

如果完全看不到 Agent 启动信息，后续所有 Trace ID 问题都应先检查 -javaagent 路径，而不是检查业务代码。

5.3 Docker 镜像内置 Agent

容器镜像使用多阶段构建，构建阶段下载并校验 Agent，运行阶段只复制最终 JAR：

FROM alpine:3.22 AS otel-agent
ARG OTEL_JAVA_AGENT_VERSION=2.28.1
ARG OTEL_JAVA_AGENT_SHA256=faa89bdeebf9b1f52be4a4374689176717b02a59df2d8f8b6eb9aa39f9292589

RUN wget -q -O /opentelemetry-javaagent.jar \
    "https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v${OTEL_JAVA_AGENT_VERSION}/opentelemetry-javaagent.jar" \
    && echo "${OTEL_JAVA_AGENT_SHA256}  /opentelemetry-javaagent.jar" | sha256sum -c -

FROM eclipse-temurin:25-jre
WORKDIR /app
COPY ./target/application.jar app.jar
COPY --from=otel-agent /opentelemetry-javaagent.jar /opt/opentelemetry-javaagent.jar

ENV JAVA_TOOL_OPTIONS="-javaagent:/opt/opentelemetry-javaagent.jar" \
    OTEL_SERVICE_NAME="system-server" \
    OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318" \
    OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf" \
    OTEL_PROPAGATORS="tracecontext,baggage" \
    OTEL_TRACES_EXPORTER="otlp" \
    OTEL_LOGS_EXPORTER="otlp" \
    OTEL_METRICS_EXPORTER="none"

CMD java ${JAVA_OPTS} -jar app.jar

这里使用 JAVA_TOOL_OPTIONS，JVM 会自动读取它，因此不依赖启动脚本是否把 -javaagent 拼进命令行。

5.4 读取当前 Trace ID

业务代码不要再调用 SkyWalking Toolkit，统一通过稳定的 OpenTelemetry API 读取当前上下文：

public final class TracerUtils {

    public static final String HEADER_TRACE_ID = "trace-id";

    private TracerUtils() {
    }

    public static String getTraceId() {
        SpanContext context = Span.current().getSpanContext();
        return context.isValid() ? context.getTraceId() : "";
    }
}

必须检查 SpanContext#isValid()。如果 Agent 未加载，Span.current() 仍然可以调用，但得到的是无效上下文；
此时不能把全零 Trace ID 或其他占位值返回给前端。

5.5 把 Trace ID 返回给前端

Agent 在 Servlet Filter 之前创建 HTTP Server Span，所以 Filter 中可以读取当前 Trace ID：

public class TraceFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain chain)
            throws IOException, ServletException {
        String traceId = TracerUtils.getTraceId();
        if (!traceId.isEmpty()) {
            response.setHeader(TracerUtils.HEADER_TRACE_ID, traceId);
        }
        chain.doFilter(request, response);
    }
}

注册 Filter，并保证它早于访问日志 Filter：

@Bean
public FilterRegistrationBean<TraceFilter> traceFilter() {
    FilterRegistrationBean<TraceFilter> bean = new FilterRegistrationBean<>();
    bean.setFilter(new TraceFilter());
    bean.setOrder(WebFilterOrderEnum.TRACE_FILTER);
    return bean;
}

响应示例：

HTTP/1.1 200
trace-id: 8a7c479d422fa7bc0fe1aade0d703a24
Content-Type: application/json;charset=UTF-8

5.6 不要忘记 CORS Expose Headers

这是一个很隐蔽的问题：浏览器开发者工具可能看到 trace-id，但前端 JavaScript 读取不到，因为
trace-id 不是 CORS safelisted response header。

需要显式暴露：

CorsConfiguration config = new CorsConfiguration();
config.setAllowCredentials(true);
config.addAllowedOriginPattern("*");
config.addAllowedHeader("*");
config.addAllowedMethod("*");
config.addExposedHeader(TracerUtils.HEADER_TRACE_ID);

响应中会增加：

Access-Control-Expose-Headers: trace-id

前端读取方式：

// Axios
const traceId = response.headers['trace-id']

// Fetch
const traceId = response.headers.get('trace-id')

HTTP Header 名不区分大小写，但 Axios 通常会把 Header key 规范化成小写，因此读取时使用
response.headers['trace-id']。

5.7 Logback 中打印 Trace ID 和 Span ID

Java Agent 会在 Logback 事件快照中注入 MDC 字段。日志格式直接读取这些字段：

<property name="CONSOLE_LOG_PATTERN"
          value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [trace_id=%X{trace_id:-} span_id=%X{span_id:-}] %highlight(%-5level) %cyan(%logger{50}:%L) - %msg%n"/>

<property name="FILE_LOG_PATTERN"
          value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [trace_id=%X{trace_id:-} span_id=%X{span_id:-}] %-5level %logger{50}:%L - %msg%n"/>

业务代码不需要手动向 MDC 写入 Trace ID：

log.info("[getPermissionInfo][OpenTelemetry 链路验证，userId({})]", userId);

输出类似：

2026-08-23 12:47:10.123 [http-nio-48081-exec-4]
[trace_id=8a7c479d422fa7bc0fe1aade0d703a24 span_id=12b91feec45048af]
INFO  c.h.h.m.s.c.a.a.AuthController:104 -
[getPermissionInfo][OpenTelemetry 链路验证，userId(1)]

Logback 仍然保留控制台和滚动文件 Appender，Java Agent 额外捕获日志事件并通过 OTLP 批量发送。
不需要再配置一个自定义 Elasticsearch Appender，也不建议让每个应用直接写 ES。

5.8 少量业务 Span

自动埋点负责基础设施 Span，业务关键动作可以使用注解和 AOP 创建业务 Span：

@Around("@annotation(trace)")
public Object around(ProceedingJoinPoint joinPoint, BizTrace trace) throws Throwable {
    Span span = tracer.spanBuilder(buildOperationName(joinPoint, trace))
            .setAttribute("component", "biz")
            .startSpan();
    try (Scope ignored = span.makeCurrent()) {
        return joinPoint.proceed();
    } catch (Throwable throwable) {
        span.recordException(throwable);
        span.setStatus(StatusCode.ERROR, throwable.getMessage());
        throw throwable;
    } finally {
        span.end();
    }
}

不要把完整异常堆栈再作为一个字符串 Attribute 写入 Span。recordException 已经使用标准事件表示异常；
额外写大字符串会显著增加 Span 体积和 ES 存储成本。

六、OpenTelemetry Collector 配置

6.1 完整的开发环境配置

extensions:
  health_check:
    endpoint: 0.0.0.0:13133

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 384
    spike_limit_mib: 64
  batch:
    timeout: 1s
    send_batch_size: 8192
    send_batch_max_size: 10000

exporters:
  otlphttp/elasticsearch:
    endpoint: http://elasticsearch:9200/_otlp
    compression: gzip
    timeout: 30s
    sending_queue:
      enabled: true
      sizer: bytes
      queue_size: 50000000
      block_on_overflow: true
      batch:
        flush_timeout: 1s
        min_size: 1000000
        max_size: 4000000
    retry_on_failure:
      enabled: true
      initial_interval: 1s
      max_interval: 30s
      max_elapsed_time: 300s

service:
  extensions: [health_check]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlphttp/elasticsearch]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlphttp/elasticsearch]

6.2 配置解释

otlp Receiver 同时开放：

• 4317：OTLP/gRPC；
• 4318：OTLP/HTTP。

本项目 Java Agent 使用 http/protobuf，因此主要使用 4318。

memory_limiter 必须放在处理链前面。当 Collector 内存达到阈值时，它会施加反压，避免进程因 OOM
直接退出。

batch 将小批数据合并后再导出，降低网络请求和 ES 写入开销。

sending_queue 与 retry_on_failure 用于处理 Elasticsearch 短暂不可用。但开发配置中的队列仍然是
内存队列，Collector 进程退出后数据会丢失；生产环境应使用持久队列，后文会说明。

Elasticsearch OTLP Endpoint 的基础地址是：

http://elasticsearch:9200/_otlp

Collector 的 otlphttp Exporter 会在其后追加标准 signal path：

/_otlp/v1/traces
/_otlp/v1/logs

6.3 用官方二进制验证 Collector 配置

不要只依靠 YAML 解析器。YAML 语法正确，不代表 Collector 组件配置正确。应使用目标版本执行：

otelcol-contrib validate --config script/docker/otel-collector-config.yaml

命令退出码为 0 且没有错误输出，才表示该版本 Collector 接受配置。

七、Elasticsearch 9.x 原生 OTLP 存储

7.1 为什么使用原生 Endpoint

Elasticsearch 9.x 可以直接接收 OTLP/HTTP。这样不需要：

• 在 Collector 中把 OTel 字段手工转换成自定义 JSON；
• 自己维护 Trace 和 Log index template；
• 自己定义 trace_id、span_id 等字段类型；
• 使用老旧或非标准的日志 Appender 直写 ES。

Elasticsearch 会自动创建 OTel Data Stream 和映射。

7.2 实际生成的数据流

本次环境实际生成了：

logs-generic.otel-default
traces-generic.otel-default

查询数据流：

curl 'http://127.0.0.1:9200/_data_stream?pretty'

7.3 字段名与常见误区

在本方案的 Elastic 原生 OTLP Data Stream 中，实际字段是：

特别注意：这里查询的是 trace_id，不是很多 ECS/APM 教程里的 trace.id。不同接入路径使用的模板不同，
不要凭经验猜字段名，应该先查看实际 _source 和 mapping。

查看最新一条日志：

curl -H 'Content-Type: application/json' \
  'http://127.0.0.1:9200/logs-generic.otel-default/_search?pretty' \
  -d '{
    "size": 1,
    "sort": [{"@timestamp": "desc"}],
    "query": {"match_all": {}}
  }'

八、将 API 访问日志改成 RocketMQ 异步落库

8.1 改造前后的区别

改造前：

只要 Infra、网络或数据库慢，业务响应就会等待。

改造后：

8.2 添加 RocketMQ 依赖

Web Starter 将 RocketMQ 依赖标记为 optional，未使用 MQ 的应用不会被强制传递：

<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-spring-boot-starter</artifactId>
    <optional>true</optional>
</dependency>

真正发送或消费访问日志的服务显式引入该 Starter。

8.3 自动配置条件

只有同时满足以下条件才创建 Producer 和访问日志 Filter：

• classpath 中存在 RocketMQTemplate；
• handao.access-log.enable=true；
• 配置了 rocketmq.name-server；
• 配置了 rocketmq.producer.group。

@Bean
@ConditionalOnMissingBean
@ConditionalOnProperty(
        prefix = "handao.access-log",
        name = "enable",
        havingValue = "true",
        matchIfMissing = true)
@ConditionalOnProperty(
        prefix = "rocketmq",
        name = {"name-server", "producer.group"})
public ApiAccessLogProducer apiAccessLogProducer(
        RocketMQTemplate rocketMQTemplate,
        @Value("${handao.access-log.rocketmq.topic:api-access-log}") String topic) {
    return new ApiAccessLogProducer(rocketMQTemplate, topic);
}

这样可以避免未配置 RocketMQ 的轻量应用在启动时失败。

8.4 生产端异步发送

@Slf4j
public class ApiAccessLogProducer {

    private final RocketMQTemplate rocketMQTemplate;
    private final String topic;

    public void send(ApiAccessLogCreateReqDTO dto) {
        String message = null;
        try {
            message = JsonUtils.toJsonString(dto);
            String finalMessage = message;
            rocketMQTemplate.asyncSend(topic, message, new SendCallback() {
                @Override
                public void onSuccess(SendResult result) {
                    // 旁路日志成功时不再打印日志，避免日志放大
                }

                @Override
                public void onException(Throwable throwable) {
                    log.error("[send][访问日志异步发送失败，topic({}) message({})]",
                            topic, StrUtils.maxLength(finalMessage, 500), throwable);
                }
            });
        } catch (Throwable throwable) {
            log.error("[send][访问日志提交发送失败，topic({}) message({})]",
                    topic, StrUtils.maxLength(message, 500), throwable);
        }
    }
}

这里有两个设计点：

1. 使用 asyncSend，业务线程不等待 Broker 返回；
2. 访问日志属于旁路数据，发送失败只记录错误，不影响业务响应。

第二点是业务取舍。如果访问日志属于强合规数据、要求绝不丢失，就不能只使用 best-effort 异步发送，
应改为本地事务 Outbox、CDC 或其他可靠事件方案。

8.5 在生产端预生成日志 ID

RocketMQ 是至少一次投递。消费者处理成功但 ACK 丢失时，同一消息可能再次到达。如果数据库继续使用
自增 ID，每次消费都会生成新行，无法识别重复消息。

解决方法是在生产端生成稳定 ID，并把它放进消息：

// 生产端预生成主键，同一消息无论消费多少次，ID 都不变
accessLog.setId(IdUtil.getSnowflakeNextId());
accessLog.setTraceId(TracerUtils.getTraceId());

DTO 中把 ID 设为必填：

@NotNull(message = "日志编号不能为空")
private Long id;

8.6 消费者落库与重试

@Component
@ConditionalOnProperty(
        prefix = "handao.access-log",
        name = "enable",
        havingValue = "true",
        matchIfMissing = true)
@ConditionalOnProperty(prefix = "rocketmq", name = "name-server")
@RocketMQMessageListener(
        topic = "${handao.access-log.rocketmq.topic:api-access-log}",
        consumerGroup = "${handao.access-log.rocketmq.consumer-group:api-access-log-consumer}")
public class ApiAccessLogMessageConsumer implements RocketMQListener<String> {

    @Resource
    private ApiAccessLogService apiAccessLogService;

    @Override
    public void onMessage(String message) {
        try {
            ApiAccessLogCreateReqDTO dto =
                    JsonUtils.parseObject(message, ApiAccessLogCreateReqDTO.class);
            apiAccessLogService.createApiAccessLog(dto);
        } catch (RuntimeException exception) {
            log.error("[onMessage][API 访问日志落库失败，message({})]", message, exception);
            throw exception;
        }
    }
}

消费者异常必须继续抛出。吞掉异常会让 RocketMQ 误以为消费成功，失去自动重试和死信能力。

8.7 数据库幂等

重复消息第二次插入时会命中相同主键。确认数据库中确实已有该 ID 后，将其视为成功：

try {
    apiAccessLogMapper.insert(apiAccessLog);
} catch (DuplicateKeyException exception) {
    ApiAccessLogDO existing = TenantUtils.executeIgnore(
            () -> apiAccessLogMapper.selectById(apiAccessLog.getId()));
    if (existing == null) {
        // 可能是其他唯一约束冲突，不能错误地吞掉
        throw exception;
    }
    log.debug("[createApiAccessLog][访问日志({}) 已存在，忽略重复消息]",
            apiAccessLog.getId());
}

为什么捕获异常后还要查询一次？因为 DuplicateKeyException 不一定来自主键，也可能来自其他唯一索引。
只有相同访问日志 ID 已经存在时，才能确认这是同一消息的重复投递。

8.8 多租户上下文跨 MQ 传播

HTTP 请求中的租户 ID 通常保存在 ThreadLocal 中。消息进入 RocketMQ 后切换了线程和进程，ThreadLocal
不会自动存在。

生产 Hook 把租户 ID 写入消息属性：

public void sendMessageBefore(SendMessageContext context) {
    Long tenantId = TenantContextHolder.getTenantId();
    if (tenantId != null) {
        context.getMessage().putUserProperty("tenant-id", tenantId.toString());
    }
}

消费 Hook 在执行监听器之前恢复，之后必须清理：

public void consumeMessageBefore(ConsumeMessageContext context) {
    String tenantId = context.getMsgList().getFirst().getUserProperty("tenant-id");
    if (StrUtil.isNotEmpty(tenantId)) {
        TenantContextHolder.setTenantId(Long.parseLong(tenantId));
    }
}

public void consumeMessageAfter(ConsumeMessageContext context) {
    TenantContextHolder.clear();
}

如果不在 after 中清理，线程池复用时可能发生严重的跨租户数据污染。

8.9 配置项

rocketmq:
  name-server: 192.168.1.117:9876
  producer:
    group: ${spring.application.name}_PRODUCER

handao:
  access-log:
    enable: true
    rocketmq:
      topic: api-access-log
      consumer-group: api-access-log-consumer

Topic 和 Consumer Group 应保持稳定，不要把随机实例 ID 放入 Consumer Group，否则每个实例都会收到一份
消息，导致重复消费压力。

九、Docker Compose 部署中间件

下面是核心编排的精简版本：

services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:9.5.2
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
      - ES_JAVA_OPTS=-Xms1g -Xmx1g
    ports:
      - "9200:9200"
    volumes:
      - elasticsearch-data:/usr/share/elasticsearch/data

  kibana:
    image: docker.elastic.co/kibana/kibana:9.5.2
    environment:
      - ELASTICSEARCH_HOSTS=http://elasticsearch:9200
    ports:
      - "5601:5601"
    depends_on:
      elasticsearch:
        condition: service_healthy

  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.159.0
    command: ["--config=/etc/otelcol-contrib/config.yaml"]
    volumes:
      - ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml:ro
    ports:
      - "4317:4317"
      - "4318:4318"
      - "13133:13133"

  rocketmq-namesrv:
    image: apache/rocketmq:5.5.0
    command: sh mqnamesrv
    ports:
      - "9876:9876"

  rocketmq-broker:
    image: apache/rocketmq:5.5.0
    command: sh mqbroker -c /home/rocketmq/conf/broker.conf --enable-proxy
    environment:
      - NAMESRV_ADDR=rocketmq-namesrv:9876
    ports:
      - "8080:8080"
      - "8081:8081"
      - "10909:10909"
      - "10911:10911"
      - "10912:10912"

本地启动：

cd script/docker
docker compose up -d \
  elasticsearch kibana otel-collector rocketmq-namesrv rocketmq-broker

使用 Podman 时：

podman compose up -d \
  elasticsearch kibana otel-collector rocketmq-namesrv rocketmq-broker

9.1 RocketMQ 的 brokerIP1 陷阱

Broker 向 NameServer 注册的不只是名字，还包含客户端后续连接的 Broker 地址。

如果所有应用和 Broker 都在同一台机器，可以使用：

brokerIP1=127.0.0.1

如果应用在另一台机器，而 Broker 部署在 192.168.1.117，必须使用：

brokerIP1=192.168.1.117

否则会出现非常迷惑的现象：

• NameServer 9876 可连接；
• 应用能查到 Topic 路由；
• 但路由返回 127.0.0.1:10911；
• 应用最终连接的是自己的本机 10911，发送失败。

因此远程排查 RocketMQ 时，不要只测试 9876，还要测试 10911，并确认 Broker 广播地址。

十、本地应用连接远程中间件

假设中间件统一位于：

MIDDLEWARE_HOST=192.168.1.117

推荐先检查端口：

for port in 3306 6379 8848 9876 10911 4318 13133 9200 5601; do
  nc -z -w 2 192.168.1.117 "$port" \
    && echo "OPEN $port" \
    || echo "CLOSED $port"
done

常用端口：

10.1 远端只有 ES，本机启动 Collector

复制一份临时配置，把 Docker DNS 名 elasticsearch 替换为远端 IP：

sed 's#http://elasticsearch:9200#http://192.168.1.117:9200#' \
  script/docker/otel-collector-config.yaml \
  > /tmp/handao-otel-collector.yaml

运行 Collector：

podman run --rm \
  --name handao-otel-collector \
  --network host \
  -v /tmp/handao-otel-collector.yaml:/etc/otelcol-contrib/config.yaml:ro,Z \
  otel/opentelemetry-collector-contrib:0.159.0 \
  --config=/etc/otelcol-contrib/config.yaml

验证：

curl http://127.0.0.1:13133

10.2 启动顺序

微服务模式推荐：

1. Elasticsearch；
2. OpenTelemetry Collector；
3. RocketMQ NameServer 和 Broker；
4. Nacos、MySQL、Redis；
5. Infra；
6. System；
7. Gateway；
8. 前端。

Infra 先启动，是因为它包含 API 访问日志消费者。System 即使先启动也不会影响业务启动，但早期产生的
访问日志需要等待消费者上线后才能落库。

十一、端到端验证

11.1 增加一条唯一的 SLF4J 验证日志

选择登录后前端稳定调用的接口：

GET /admin-api/system/auth/get-permission-info

在 Controller 中添加：

public CommonResult<AuthPermissionInfoRespVO> getPermissionInfo() {
    Long userId = getLoginUserId();
    log.info("[getPermissionInfo][OpenTelemetry 链路验证，userId({})]", userId);
    // ...
}

重启 System，登录或刷新前端页面。

11.2 获取 Trace ID

浏览器 Network 面板或 curl 查看响应头：

curl -i \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  http://127.0.0.1:48081/admin-api/system/auth/get-permission-info

记录：

trace-id: 8a7c479d422fa7bc0fe1aade0d703a24

11.3 Kibana 查询

为下面两个 Data Stream 创建 Data View：

logs-generic.otel-*
traces-generic.otel-*

KQL：

trace_id : "8a7c479d422fa7bc0fe1aade0d703a24"

查验证日志：

body.text : "*OpenTelemetry 链路验证*"

11.4 直接使用 Elasticsearch API 查询

同时查询日志和 Trace：

curl -H 'Content-Type: application/json' \
  'http://192.168.1.117:9200/logs-generic.otel-default,traces-generic.otel-default/_search?pretty' \
  -d '{
    "size": 100,
    "sort": [{"@timestamp": "asc"}],
    "query": {
      "term": {
        "trace_id": "8a7c479d422fa7bc0fe1aade0d703a24"
      }
    }
  }'

先按日志内容反查 Trace ID：

curl -H 'Content-Type: application/json' \
  'http://192.168.1.117:9200/logs-generic.otel-default/_search?pretty' \
  -d '{
    "size": 20,
    "sort": [{"@timestamp": "desc"}],
    "query": {
      "match_phrase": {
        "body.text": "OpenTelemetry 链路验证"
      }
    }
  }'

一个成功的日志文档应同时包含：

{
  "trace_id": "8a7c479d422fa7bc0fe1aade0d703a24",
  "span_id": "12b91feec45048af",
  "severity_text": "INFO",
  "resource": {
    "attributes": {
      "service.name": "system-server"
    }
  },
  "scope": {
    "name": "com.example.system.AuthController"
  },
  "body": {
    "text": "[getPermissionInfo][OpenTelemetry 链路验证，userId(1)]"
  }
}

11.5 验证访问日志异步落库

接口调用后查询：

SELECT id,
       trace_id,
       application_name,
       request_method,
       request_url,
       duration,
       result_code,
       begin_time
FROM infra_api_access_log
ORDER BY id DESC
LIMIT 20;

表中的 trace_id 应与响应头和 ES 中的 trace_id 一致。

11.6 如何判断整个链路真正成功

不要只看“ES 有数据”。完整验收应该同时满足：

• 响应头存在有效 trace-id；
• 跨域前端能读取 trace-id；
• Logback 控制台日志含相同 trace_id；
• logs-generic.otel-default 能按该 ID 查到业务日志；
• traces-generic.otel-default 能查到 HTTP、JDBC、Feign 等 Span；
• 多服务 Span 共享同一 Trace ID；
• RocketMQ 消费 Span 能与生产端上下文关联；
• infra_api_access_log.trace_id 一致；
• 重复消费同一访问日志消息不会产生第二行数据库记录。

十二、自动化测试与配置验证

12.1 Trace ID 工具测试

@Test
void getTraceIdReturnsCurrentOpenTelemetryTraceId() {
    SpanContext context = SpanContext.create(
            "0123456789abcdef0123456789abcdef",
            "0123456789abcdef",
            TraceFlags.getSampled(),
            TraceState.getDefault());

    try (Scope ignored = Span.wrap(context).makeCurrent()) {
        assertEquals(
                "0123456789abcdef0123456789abcdef",
                TracerUtils.getTraceId());
    }
}

还应验证没有当前 Span 时返回空字符串。

12.2 CORS 测试

@Test
void corsFilterExposesTraceIdHeader() throws Exception {
    MockHttpServletRequest request =
            new MockHttpServletRequest("GET", "/admin-api/test");
    request.addHeader(HttpHeaders.ORIGIN, "http://localhost:3000");
    MockHttpServletResponse response = new MockHttpServletResponse();

    CorsFilter filter = new HandaoWebAutoConfiguration()
            .corsFilterBean().getFilter();

    filter.doFilter(request, response,
            (req, resp) -> ((HttpServletResponse) resp)
                    .setHeader("trace-id", "0123456789abcdef0123456789abcdef"));

    assertEquals("trace-id",
            response.getHeader(HttpHeaders.ACCESS_CONTROL_EXPOSE_HEADERS));
}

12.3 MQ 幂等测试

用同一个 DTO 连续调用两次：

apiAccessLogService.createApiAccessLog(createDTO);
apiAccessLogService.createApiAccessLog(createDTO);

assertEquals(1L, apiAccessLogMapper.selectCount());

12.4 构建验证

mvn -pl \
  handao-gateway,\
  handao-module-system/handao-module-system-server,\
  handao-module-infra/handao-module-infra-server,\
  handao-server \
  -am -DskipTests compile

12.5 Compose 与 Collector 验证

docker compose -f script/docker/docker-compose.yml config

otelcol-contrib validate \
  --config script/docker/otel-collector-config.yaml

两种验证解决不同问题：Compose 验证编排，Collector 验证组件配置。

十三、常见故障排查

13.1 响应没有 trace-id

检查顺序：

1. JVM 命令行是否真的包含 -javaagent:/.../opentelemetry-javaagent.jar；
2. 启动日志是否打印 Agent 版本；
3. Agent 文件路径是否存在；
4. handao.tracer.enable 是否被关闭；
5. TraceFilter 自动配置是否加载；
6. 请求是否经过应用，而不是被前置代理直接返回。

快速检查进程：

ps -ef | grep opentelemetry-javaagent

13.2 浏览器 Network 能看到 trace-id，但 Axios 读不到

原因几乎一定是缺少：

Access-Control-Expose-Headers: trace-id

后端 CORS 配置增加 addExposedHeader("trace-id")，重启应用。

13.3 控制台有日志，但 ES 没有日志

检查：

• otel.logs.exporter=otlp；
• Agent 是否加载；
• Collector 4318 是否可达；
• Collector 是否启用了 logs pipeline；
• otlp Receiver、batch Processor、Exporter 是否都在 logs pipeline 中；
• Collector 日志是否出现 401、403、404、429 或连接超时；
• Elasticsearch /_otlp/v1/logs 是否可用。

13.4 Trace 有数据，但日志没有 trace_id

可能原因：

• 日志发生在 HTTP Span 建立前，例如应用启动日志；
• 日志发生在 Span 结束后的异步线程，且上下文未传播；
• 手工创建 Span 后没有 makeCurrent()；
• 线程池被不兼容的包装器绕过 Agent；
• 日志采集配置被关闭。

并不是所有日志都应该有 Trace ID。启动日志、定时任务全局日志没有当前 Trace 时，trace_id 为空是正常的。

13.5 Kibana 用 trace.id 查不到

检查实际 _source。本方案使用 Elastic 原生 OTLP Data Stream，字段是：

trace_id

不是：

trace.id

13.6 Collector 启动失败

典型原因是拿新版本文档配置旧版本 Collector，或反过来。必须使用和容器完全相同版本的二进制执行：

otelcol-contrib validate --config config.yaml

13.7 RocketMQ NameServer 能连接但消息发送失败

检查 Broker 返回的地址。远程 Broker 的 brokerIP1 不能是 127.0.0.1。同时检查防火墙是否开放：

9876
10909
10911
10912

13.8 访问日志出现重复数据

检查：

• ID 是否在生产端生成；
• 消息重试时是否复用了相同消息体；
• DTO 到 DO 的转换是否保留 ID；
• 数据库是否真的以该 ID 为主键；
• 消费者是否错误地重新生成 ID。

13.9 访问日志不落库

检查：

• handao.access-log.enable=true；
• rocketmq.name-server 和 rocketmq.producer.group 是否存在；
• Topic 是否自动创建或已经预创建；
• Infra Consumer Group 是否启动；
• Broker 是否返回正确 IP；
• 消息是否进入重试或死信队列；
• 租户上下文是否恢复；
• 数据库表和主键类型是否匹配 Snowflake Long。

十四、生产环境必须补齐的能力

开发环境跑通不等于可以直接上线。至少应处理以下事项。

14.1 Elasticsearch 安全

开发 Compose 中为了快速验证使用：

xpack.security.enabled=false

生产环境必须启用 TLS 和认证。Collector 可以集中持有 API Key：

exporters:
  otlphttp/elasticsearch:
    endpoint: https://elasticsearch.example.com:9200/_otlp
    headers:
      Authorization: "ApiKey ${env:ELASTICSEARCH_API_KEY}"
    tls:
      ca_file: /etc/otelcol/certs/ca.crt

API Key 不应写进 Git，也不应下发给所有业务应用。

14.2 Collector 持久队列

内存队列在 Collector 重启时会丢失。生产环境可以启用 file_storage：

extensions:
  health_check:
  file_storage:
    directory: /var/lib/otelcol/storage

exporters:
  otlphttp/elasticsearch:
    sending_queue:
      enabled: true
      storage: file_storage

service:
  extensions: [health_check, file_storage]

对应目录必须挂载持久卷，并监控磁盘容量。

14.3 Collector 高可用

生产环境应运行多个 Collector Gateway 实例，通过 Service 或负载均衡器提供统一 OTLP 地址。

需要监控：

• Receiver 接收速率；
• Exporter 成功和失败数量；
• Queue 容量和使用量；
• Retry 次数；
• Dropped spans/log records；
• Collector 内存、CPU、GC；
• Elasticsearch 429 和 ingest latency。

14.4 Trace 采样

开发环境通常 100% 采样：

OTEL_TRACES_SAMPLER=always_on

高流量生产环境可以使用比例采样：

OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

但头部采样无法提前知道请求是否会失败。若希望保留全部错误和慢请求，可在 Collector 中使用 tail
sampling。Tail sampling 必须看到一条 Trace 的所有 Span，因此通常要求相同 Trace 路由到同一 Collector，
并评估等待窗口带来的内存开销。

14.5 日志保留与 ILM

Trace、应用日志和访问日志的保留周期应分别设计：

不要直接修改 Elastic 内置的 OTel 模板。应通过 logs-otel@custom、traces-otel@custom 等官方扩展点
定制生命周期和映射。

14.6 敏感数据与成本控制

禁止采集或输出：

• 密码；
• Access Token、Refresh Token；
• Cookie、Authorization Header；
• 身份证号、银行卡号等敏感信息；
• 完整大请求体和大响应体；
• 无限制 SQL 参数；
• 完整异常对象的重复字符串副本。

API 访问日志应在进入 MQ 前脱敏和截断，否则超大消息不仅增加 Broker 压力，还可能超过 RocketMQ 消息
大小限制。现有脱敏逻辑如果解析失败后选择保留原字符串，属于 fail-open 策略；强合规场景应改成解析失败
直接丢弃请求体或仅记录摘要。

14.7 访问日志可靠性等级

本方案的语义是：

• 请求线程不等待 Broker ACK；
• Broker 接受消息后，依赖 RocketMQ 至少一次投递；
• 消费端通过预生成主键幂等；
• 发送失败只记录错误，不影响业务请求。

它适合大多数运营和排障访问日志，但不是严格“零丢失”审计。如果业务要求日志和业务事务原子一致，
推荐：

14.8 时间同步

跨服务 Trace 高度依赖时间。所有宿主机、容器节点应启用 NTP/chrony。时钟漂移会导致：

• Span 时间线顺序混乱；
• 负耗时或异常耗时；
• 日志与 Trace 在时间窗口中看似不相关；
• Kibana 查询遗漏。

14.9 版本升级策略

不要盲目使用浮动标签。推荐：

1. 固定 Agent、Collector、Elasticsearch、Kibana、RocketMQ 版本；
2. Agent JAR 固定 SHA-256；
3. Elasticsearch 与 Kibana 保持相同版本；
4. Collector 升级前运行 validate；
5. 阅读版本 Breaking Changes；
6. 在测试环境回放真实 Trace/Log 流量；
7. 检查 Data Stream、模板、ILM 和字段变化；
8. 灰度升级 Collector，再升级 Agent；
9. 保留快速回滚镜像。

十五、最终验收清单

上线前可以直接按下面的清单逐项确认。

应用

• 所有服务加载相同基线的 OpenTelemetry Java Agent；
• 每个服务有唯一且稳定的 service.name；
• 使用 tracecontext,baggage；
• Trace 和 Log 均导出到 Collector；
• Logback Pattern 包含 trace_id、span_id；
• 响应 Header 返回有效 trace-id；
• CORS 暴露 trace-id；
• 前端能够读取并展示/上报 Trace ID。

Collector 与 Elasticsearch

• Collector 配置通过目标版本 validate；
• 4318 和 13133 健康可达；
• logs-generic.otel-default 有数据；
• traces-generic.otel-default 有数据；
• 同一请求的日志和 Span 使用相同 trace_id；
• Collector 配置队列、重试和内存限制；
• 生产环境启用 TLS、API Key、持久队列；
• 配置 ILM 和容量告警。

RocketMQ 访问日志

• 生产端使用 asyncSend；
• Topic 和 Consumer Group 稳定；
• Broker 广播地址对客户端可达；
• 生产端生成访问日志 ID；
• 消费端主键幂等；
• 消费异常继续抛出；
• 已验证重试与死信；
• 租户 ID 能传播且消费后清理；
• 请求参数已经脱敏和截断；
• 明确 best-effort 与强审计可靠性边界。

十六、总结

这套方案最重要的不是“把日志写进 Elasticsearch”，而是建立清晰的职责边界：

• OpenTelemetry Java Agent 负责自动埋点、上下文传播和 Logback 捕获；
• 业务代码只依赖稳定的 OpenTelemetry API，避免绑定具体 APM 产品；
• Collector 负责接收、保护、批处理、重试和统一导出；
• Elasticsearch 9.x 原生 OTLP Endpoint 负责标准化存储；
• Kibana 通过 trace_id 把 Trace 与 SLF4J 日志串起来；
• RocketMQ 负责将 API 访问审计从业务请求线程解耦；
• 生产端预生成主键、消费端检查重复主键，实现至少一次投递下的幂等；
• Trace ID 同时出现在响应 Header、应用日志、Trace Data Stream 和访问日志表中，成为排障的统一入口。

最终，排查一次请求只需要一个动作：复制前端响应中的 trace-id，在 Kibana 中查询同值的 trace_id。
从用户请求、跨服务调用、SQL、消息队列到业务日志，都可以沿着同一条链路还原。

深入理解 AI Agent · 第 1 章学习笔记:AI Agent 入门

📖 原书:《深入理解 AI Agent:设计原理与工程实践》(李博杰 著,v2.0)
📌 本章定位:全书的概念地图——快速引入 Agent 的核心公式、运行循环、工程框架和设计模式
🎯 一句话总结:Agent = 大脑 + 眼睛 + 手脚;模型正在商品化,真正的竞争力在 Harness 工程。

一、核心公式:现代 Agent = LLM + 上下文 + 工具

这是全书的基石公式,可以从三个层次理解它:

两个重要补充:

1. 公式只描述 Agent 边界内部,不包含环境(Environment)。Agent 与环境是闭环交互的两方:环境给观察 → Agent 行动 → 环境状态改变 → 新的观察……
2. 生产形态下,公式展开为 Agent = Model + Harness,其中 Harness = 上下文管理 + 工具接口 + 约束 + 验证 + 纠正。

最关键的一个洞察:扩展接口 > 换更强的模型

在底层模型固定时,提升 Agent 任务表现最主要的系统工程手段,往往就是重新定义或扩展观察空间与动作空间。许多看似需要"更聪明模型"的问题,其实只是接口问题。

书中用两个产品证明这一点:

• Manus:率先把 Deep Research、Coding、Computer Use 三条独立路线放进同一个 Agent——虚拟浏览器扩大观察空间,文件系统/代码执行扩大动作空间。它没有靠换更强的模型成为通用 Agent,而是取了三个空间并集。
• OpenClaw:把接口延伸到用户的数字生活——通过 WhatsApp、Telegram、iMessage 等消息渠道接收任务,通过本地 Gateway 连接 Google Drive、Notion 和本地文件系统。分散在各处的数据都进入同一个 Agent 的观察空间。

二、三大组件逐一拆解

1. 工具:Agent 的手脚

按交互方向分五类:

工具调用四步流程:① 在上下文声明工具 → ② 模型自主决定调不调、调哪个、传什么参 → ③ 结果追加回上下文 → ④ 模型决定下一步。这就是 ReAct 的基础。

工具设计的核心原则:

• 通用基础能力用于组合与探索(如代码解释器——任务升级时不用堆专用工具)
• 专用工具用于约束高风险和强业务规则操作(支付、删数据、发邮件——参数明确、权限受限、全程可审计)
• 通用性扩大出错面 → 代码必须跑在沙盒里,默认无网络、限路径、限资源

2. LLM:Agent 的大脑

• LLM 的能力 = 预训练积累的世界知识 + 后训练固化的决策策略
• 独特能力:内部思考——行动前先规划推演,不改变环境却显著提升行动质量
• "模型即 Agent"范式:Kimi K3、GPT-5.6 通过 RL 把工具调用决策内化为原生能力(何时调用、调哪个、传什么参数),编排循环从客户端移到了服务端
• ⚠️ 澄清一个常见误解:RL 内化的是"决策策略",不是"工具执行机制"——web_search、code_runner 的真实实现仍在模型之外的 Harness/基础设施里

值得反复品味的观点:Harness 会被模型"吃掉"吗?

书中的立场:方向认同,节奏务实。

方向:不怀疑模型会持续吃掉 Harness(工具调用、长程规划都曾靠外部编排,如今已是模型原生能力)。但这个过程远比想象中慢——模型此刻的能力边界,就是 Harness 此刻的价值所在。模型每内化一层,Harness 就卸下一层,转而兜底新的能力前沿。

Harness 原指马具(缰绳与挽具)——不是限制马奔跑,而是把力量引导到正确方向。

Agent 行为改变的三条路径

三者协同:临场适应 + 可控积累 + 能力内化。

3. 上下文:Agent 的眼睛

每次调用 LLM 的上下文由五部分组成:

┌─ 静态前缀 ─────────────┐
│ ① 系统提示词(岗位说明书)  │
│ ② 工具定义(可用的手脚清单)│
└────────────────────────┘
┌─ 动态轨迹 ─────────────┐
│ ③ 用户消息(含 RAG 注入知识)│
│ ④ 模型回复(reasoning + content + tool_calls)│
│ ⑤ 工具执行结果           │
└────────────────────────┘

消融实验(实验 1-1)的结果——每个组件都不可替代:

核心洞察:上下文决定了 Agent 能看到什么,而 Agent 只能基于它看到的信息做决策。 就像人蒙住眼睛就无法做出合理判断。

三、ReAct 循环:想 → 做 → 看

Agent 执行任务的核心模式。名字只含 Reasoning + Acting,实际是三环节:

思考(下一步做什么)→ 行动(调用工具)→ 观察(工具结果)→ 思考 → …直到任务完成

关键事实:Agent 的上下文 = 静态前缀 + 轨迹(trajectory)

• 轨迹 = 不断追加的消息历史(用户消息 + 模型回复 + 工具结果)
• 每轮 LLM 调用都能看到完整轨迹 → 清楚任务进行到哪一步
• 结构化轨迹带来三个好处:易解释调试、可分析行为模式、可沉淀为训练数据(形成从经验中学习的闭环)

书中用"多币种收入汇总"的例子展示了完整轨迹:汇率转换 → 代码汇总 → 最终回答,3 次迭代、4 次工具调用。

四、Harness 工程:模型之外的竞争力

一个能跑的 Demo 和一个可靠的产品之间还有巨大的鸿沟——模型会幻觉(编造不存在的工具)、选错工具、出错后无法自我恢复。这些脆弱点正是 Harness 工程要解决的。

Harness 五要素

Agent = Model + Harness
Harness = 上下文管理 + 工具接口 + 约束 + 验证 + 纠正

"能做事"(上下文+工具)与"不做错事"(约束+验证+纠正)的重要性是不对称的:Claude Code 的 Harness 中绝大部分代码是约束、验证与纠正——工具本身只是一小部分,围绕工具的保障机制才是核心。

工程范式的演进(层层包含,不是替代)

提示工程 ⊂ 上下文工程 ⊂ Harness 工程 ⊂ Loop 工程 ⊂ Graph 工程

一个有力例证:LangChain 在 Terminal Bench 2.0 上得分从 52.8% → 66.5%(30 名开外 → 前 5),改变的不是模型,而是 Harness(自动检查执行结果、检测重复循环、优化思考策略)。

构建 Agent 的三大原则(Anthropic 经验)

1. 保持简单——直接的 API 调用优于复杂框架;每多一层抽象都是调试时新的盲区
2. 保持透明——显示规划步骤、执行日志、决策轨迹;黑箱里的错误无法定位也无法纠正
3. 设计好工具接口(ACI)——从 Agent 视角设计接口而非程序员视角;用"防呆"(Poka-yoke)思路让错误无法发生(如 SIM 卡缺角设计)。模型与工具之间唯一的沟通通道就是接口本身,模糊的接口会被模型放大成系统性错误。

编排模式:工作流 vs 自主 Agent

决策顺序(从简单到复杂):单次 LLM 调用 → 工作流 → 自主 Agent

• 自主 Agent 的本质 = 在循环中使用工具的 LLM(即 ReAct),必须设计明确的停止条件
• 实践中常混合使用:关键流程用工作流,灵活部分用自主模式(如 n8n)

护栏与安全性:三层防线

按被绕过的难度分层(越往下越不依赖模型自己的判断):

关键区分:越狱 = 用户自己绕过限制;提示注入 = 攻击者通过外部数据(网页、文档)间接操纵模型。

**人工干预(人在回路)**的两种触发:超过失败阈值(重试/操作次数上限)、高风险操作(大额退款、付款)。

五、贯穿全书的五个设计模式

六、本章小结(核心要点回顾)

1. Agent = 大脑 + 眼睛 + 手脚,三者缺一不可
2. 扩展眼睛和手脚是最主要的能力杠杆——接口问题常被误认为模型问题
3. 眼睛(上下文)是决定性因素——静态前缀 + 动态轨迹,消融任何组件都会显著退化
4. Harness 是竞争力所在——模型商品化时代,约束/验证/纠正决定"可靠地做事"
5. 从简单到复杂:先提示词 → 再工作流 → 最后自主 Agent
6. 五个设计模式贯穿全书:提议者—审核者、渐进式披露、只增不改、边界集+保留集、最小 diff+可回滚
7. 安全是架构问题——从第一行代码考虑,三层护栏(上下文/执行/数据层)

七、我的思考

• 💡 "模型此刻的能力边界,就是 Harness 此刻的价值所在" 这句是我认为全章最有分量的话——它同时回答了两个问题:为什么 Harness 不会消失(模型内化是慢变量),以及 Harness 工程师该做什么(盯住能力前沿,持续"兜底")
• 💡 消融实验的方法论值得学:怀疑某个组件没用,不要猜,做对照实验。这比任何经验讨论都有说服力
• 💡 "产品能力的演进往往就是观察空间和动作空间的演进"——用这个视角重新看任何 Agent 产品的版本更新,都能看懂它到底在扩张什么接口

八、遗留问题(书中思考题摘选)

1. 只能增强一项:更强的模型 / 更丰富的上下文 / 更多的工具,你选哪个?什么条件下会改变?
2. "模型即 Agent"与 Harness 重要性上升,这两个趋势如何共存?框架未来的核心价值在哪?
3. 除了工具结果缺失,还有哪些情况会导致 Agent 无限循环?如何设计检测和终止机制?
4. 一个低风险工具在特定参数组合下变为高风险(如 delete_file 删系统文件),如何做动态风险评估?

下一章预告:第二章《上下文工程》——全书最关键的一章,深入 KV Cache 原理、提示工程、Agent Skills 与上下文压缩。

移除哪块"上下文"最致命？—— 一次 AI Agent 上下文消融实验实录

我们用一个真实的跨国预算分析任务，把 Agent 上下文中的四个组件逐一"摘除"，
观察它何时崩溃、何时变慢、以及最可怕的一种情况——看起来成功了，答案却是错的。

一、引言：为什么上下文是 Agent 的生命线

和传统的一次性问答不同，AI Agent 是在一个循环里工作的：理解任务 → 调用工具 → 观察结果 → 再决策 → 再调用……直到产出最终答案。驱动这个循环的，不只是模型本身，更是喂给模型的那一长串上下文：

• 历史工具调用（我做过什么）
• 推理过程（我当时的思考）
• 工具调用命令（我要调用哪个工具、传什么参数）
• 工具返回结果（刚才那一调用回传了什么）

这些组件各自值多少钱？哪个是"命根子"、哪个是"可选项"？回答这个问题不能靠猜，要靠消融实验（Ablation Study）——把组件一个一个拿掉，看 Agent 的表现如何变化。

本文基于《深入理解 AI Agent》第 1 章"实验 1-1 ★★：上下文的关键作用"的代码与思路，在 DeepSeek 模型上跑了一轮完整消融实验，下面是全部数据与解读。

二、实验设计

2.1 任务

一个跨国预算分析任务（"Multinational Budget"），要求 Agent：

1. 解析一份 PDF 财务报告；
2. 通过货币换算工具把多币种数据统一为美元；
3. 计算全球总支出、各区域占比；
4. 按 8% 的比例做全员预算削减后，重新计算各项数字。

这是一个典型的多步 Agent 任务：外部数据获取（PDF）+ 工具计算 + 顺序依赖的推导，任何一步断掉都会影响最终结果。

2.2 模型与配置

• 模型：DeepSeek（默认模型）
• 基线与四个消融臂共 5 种上下文配置：

2.3 观察指标

• 执行时间（execution_time）：跑完（或放弃）花了多少秒
• 迭代轮数（iterations）：Agent 与模型来回了几轮
• 工具调用次数（num_tool_calls）：实际调用了多少次工具
• 是否产出终态回答（has_final_answer / completed）：有没有给出最终答案

⚠️ 一个重要的方法论提醒：本套件的 success 字段只表示"Agent 给出了一个终态回复"，并不代表任务做对了。任务正确性必须用任务级的评分标准（rubric）单独核对。这一点在第四组实验里会变成血淋淋的教训。

三、结果一览

（完整原始数据见文末仓库中的 ablation_results.json）

四、逐臂解读

4.1 ① 无历史记录：失忆症的代价是"重复劳动"

去掉历史工具调用后，Agent 变成了一个失忆症患者：它不记得自己刚刚解析过 PDF、也不记得已经查过汇率，于是：

• 工具调用从基线的 6 次暴涨到 50 次（超过 8 倍）；
• 迭代了 10 轮仍然没有跑完，最终没有产出任何终态回答；
• 用时从 23.74s 膨胀到 41.69s。

解读：历史记录的价值不在"聪明"，而在"不犯蠢"。没有它，Agent 每一步都从零开始，多步依赖任务（先用 PDF 结果、再算汇率、再汇总）会陷入无休止的重做循环。它是多步任务的连贯性保障。

4.2 ② 无推理过程：本任务上几乎零影响

去掉推理过程后，Agent 表现与基线几乎完全一致：

• 用时 23.49s（基线 23.74s）；
• 工具调用同为 6 次；
• 最终答案与基线一字不差（$11,990,955.43）。

解读：对这个任务来说，模型的"推理文本"是冗余的——不写思考过程，答案照样对，速度还略快。这提示我们：推理过程不是免费的午餐，也不是万灵药。当然，这只是一个任务、一个模型上的结论；在数学证明、长链条规划等复杂推理任务上，推理过程的价值可能会完全不同。

4.3 ③ 无工具调用命令：直接瘫痪

拿掉工具调用后，Agent 变成了一个"只能空谈的咨询师"：0 次工具调用，只迭代了 1 轮就结束了，没有产出任何答案（用时 62.67s 主要耗在了单轮的长回复上）。

解读：这是最不意外的一组。这类任务的数据（PDF 内容、汇率）完全来自外部工具，砍掉工具等于砍掉了任务的地基。工具是硬依赖，没有商量的余地。

4.4 ④ 无工具返回结果：最危险的"成功" ⚠️

这是整场实验里最值得警惕的一组。Agent 可以发出工具调用，但看不到任何返回值——像一个蒙着眼睛开车的人：

• 它花了 83.03s（全场最慢），迭代 6 轮、调用 10 次工具；
• 协议层面它"完成了"：completed=true、success=true、有终态回答；
• 但答案错了：它给出总支出 ​11,951,000，而正确答案是 **11,990,955.43**，少了约 4 万美元（相对误差约 0.33%）；
• 各地区占比也全部跑偏（如美国 20.92% vs 正确的 20.85%，日本 20.99% vs 正确的 21.20%）。

解读：看不见结果，Agent 就会用"猜"来填补空白——它甚至会在盲区里重复调用（10 次 vs 基线的 6 次）来试图"蒙对"。最可怕的地方在于：这是一个表面健康的失败。如果你只看 success 标志，你会以为一切正常，然后把这个差 4 万美元的数字写进预算报告。

这正是实验报告里那句警告的含义：

"A terminal response is not evidence that the financial task was completed. Task-level claims require a separate evaluator."

协议完成 ≠ 任务完成。success 会撒谎，rubric 不会。

五、关键启示

启示 1：验收 Agent，必须用任务级评分标准

success=true 只证明"Agent 说了句结束语"。要判断它到底做没做对，必须有一个任务特定的 rubric——例如把最终答案与预期数值比对（本仓库的 run_experiment_1_1.py 就是这么做的：它把模型的回答与预计算的标准答案做数值核对）。第四组实验就是"无 rubric 验收"的完美反面教材。

启示 2：上下文裁剪的经济学——要省钱，先砍谁？

上下文越长越贵，生产环境里大家总想"裁剪"上下文省 token。这组实验给出的优先级建议是：

1. 最不能砍：工具调用 + 工具返回结果。砍前者直接瘫痪，砍后者产出错误答案——省下的钱不够一次错误决策的损失。
2. 谨慎保留：历史工具调用。砍掉它不会马上出错，但会让成本失控（50 次调用 vs 6 次），效率损失本身就是成本。
3. 优先候选：推理过程。在本任务上几乎零损耗。若真要做上下文压缩，考虑对推理文本做摘要/截断，而不是直接删除历史与工具结果——删除是"截肢"，摘要才是"减肥"。

启示 3：正确性比"跑完"更难测量，也更值钱

四组消融里，最贵的一组（83s、10 次调用）反而是错误的一组。"慢但错"比"快但没做完"危害更大，因为它会混入正常结果、污染下游决策。评估体系必须把"正确性"和"完成度"分开统计。

六、局限与后续工作

这份实验必须诚实地标注边界：

1. 单任务、单模型、单次运行：结论来自一个任务（跨国预算）和一个模型（DeepSeek）的一次运行。LLM 输出有随机性，严谨起见应当多次重复取均值；
2. 推理过程"无用"的结论不能外推：本任务的推理依赖较浅；在复杂推理任务上，no_reasoning 可能表现出完全不同的结果；
3. 缺少任务级 rubric 的自动评判：本套件记录了行为数据，但正确性核对目前依赖人工/独立脚本（run_experiment_1_1.py 提供了数值 rubric 的参考实现）。

后续可以做的方向：多模型横向对比、多任务重复实验、推理文本压缩（摘要 vs 截断）的消融、以及把 rubric 自动评分接入主流程。

七、复现指南

想亲手跑一遍？三步即可：

# 1. 获取代码
git clone https://github.com/Hanserwei/ai-agent-context-ablation.git
cd ai-agent-context-ablation

# 2. 配置 API Key
pip install -r requirements.txt
cp env.example .env
# 编辑 .env，填入任一 provider 的 API Key（如 DEEPSEEK_API_KEY）

# 3. 运行消融实验
python main.py --mode ablation

运行后会在当前目录生成：

• ablation_results.json —— 每组配置的原始数据（时间、迭代、调用次数、终态回答）
• ablation_study_report.md —— 自动生成的英文实验报告
• ablation_study_results.png —— 可视化对比图

用 run_experiment_1_1.py 可以跑带任务级数值 rubric 的严谨版本（它会持久化每一次请求/响应，并核对最终答案是否正确）。

八、结语

一个看似简单的消融实验，暴露了 Agent 工程里最容易被忽视的真相：上下文组件之间是不平等的。工具调用与工具结果决定 Agent"能不能做对"，历史记录决定"做得贵不贵"，而推理过程在某些任务上只是锦上添花。

以及那条最值得写进团队检查清单的教训：永远不要用"它跑完了"替代"它做对了"来验收一个 Agent。

代码仓库

本文所有实验代码与完整结果数据均已开源：

📦 https://github.com/Hanserwei/ai-agent-context-ablation

（代码来源：https://github.com/bojieli/ai-agent-book/tree/main ，chapter1/context 目录，实验 1-1：上下文的关键作用）

React 对照速成文档

目标：能看懂已有的 React 项目代码。本文假设你已掌握上面的《Vue3 学习笔记》，每节都会标注"对照 Vue3"，帮你快速建立映射。

阅读技巧：React 代码的核心心智模型只有一句话——UI = f(state)，组件就是一个"状态 → 界面"的纯函数。

1. React 简介

• 由 Facebook（Meta）于 2013 年开源，用于构建用户界面的 JavaScript 库（注意：是"库"，不是"框架"，路由、状态管理等需要第三方配合）。
• 当前主流写法是 函数组件 + Hooks（2019 年 React 16.8 引入），老项目里可能残留 Class 组件，两者要都会"读"。
• 与 Vue 最大的理念差异：
  • Vue：模板 + 响应式（数据变了，视图自动更新，靠 ref/reactive 代理）。
  • React：没有响应式，数据变了 React 会重新执行整个组件函数，重新算出新的 JSX 与旧的对比（虚拟 DOM diff），只更新变化的部分。

对照 Vue3：Vue 的"数据变化驱动视图"是细粒度的（哪个 ref 变了只更新相关的地方）；React 是"重跑函数 + diff"的粗粒度模型。读代码时看到组件函数体里大量普通变量、return 的 JSX，就是整个组件会反复执行。

2. 创建 React 工程

2.1. 基于 Vite 创建（推荐）

npm create vite@latest
# Project name: react_test
# Framework: React
# Variant: TypeScript (推荐) / JavaScript
cd react_test
npm install
npm run dev

2.2. 项目入口与结构

react_test/
├── index.html          # 入口 HTML，里面有 <div id="root"></div>
├── src/
│   ├── main.tsx        # 应用入口：把 App 组件渲染到 #root
│   ├── App.tsx         # 根组件
│   └── ...

src/main.tsx（React 版的 main.ts）：

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'

// Vue3: createApp(App).mount('#app')
// React: 把 <App /> 挂载到 id 为 root 的 DOM 节点
ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
)

对照 Vue3：ReactDOM.createRoot(...).render(...) ≈ createApp(App).mount('#app')。
React.StrictMode 是开发模式下的"严格模式"，会让组件在开发时多执行一遍用于暴露副作用问题，读代码时忽略即可。

3. React 核心语法

3.1. 函数组件与 JSX

React 组件就是一个返回 JSX 的函数。JSX 是"在 JS 里写 HTML"，本质上会被编译成 React.createElement 调用。

// App.tsx
export default function App() {
  const name = '张三'

  // 返回的这段"HTML"就是 JSX
  return (
    <div className="person">
      <h2>姓名：{name}</h2>
      <button>按钮</button>
    </div>
  )
}

读 JSX 必须记住的规则（与 Vue 模板的差异点）：

3.2. 条件渲染（对照 v-if / v-show）

React 里条件渲染就是普通的 JS 逻辑，因为 JSX 就在 JS 里。

function Demo({ flag, age }: { flag: boolean; age: number }) {
  return (
    <div>
      {/* v-if / v-else-if：用三元表达式 */}
      {age >= 18 ? <p>成年人</p> : <p>未成年人</p>}

      {/* 只有 if 没有 else：用 && 短路 */}
      {flag && <p>flag 为真才显示</p>}

      {/* v-show：切换 style.display */}
      <p style={{ display: flag ? 'block' : 'none' }}>相当于 v-show</p>
    </div>
  )
}

对照：v-if="x" → {x && <div/>}；v-else → 三元表达式的后半段；v-show → 自己控制 display。

3.3. 列表渲染（对照 v-for）

React 用数组的 .map() 方法，且 key 直接写在 JSX 属性上，必须传。

const games = [
  { id: 'a01', name: '英雄联盟' },
  { id: 'a02', name: '王者荣耀' },
  { id: 'a03', name: '原神' },
]

function GameList() {
  return (
    <ul>
      {/* v-for="g in games" :key="g.id" 的 React 写法 */}
      {games.map((g) => (
        <li key={g.id}>{g.name}</li>
      ))}
    </ul>
  )
}

对照：Vue 的 v-for="(item, index) in list" → React 的 list.map((item, index) => (...))。注意 key 在 React 里是 JSX 属性（key={g.id}），Vue 里是绑定指令（:key="g.id"）。

3.4. 事件处理（对照 v-on）

React 事件名是驼峰式，直接传函数引用（不加括号），事件对象就是原生的，没有 $event 特殊语法。

function Demo() {
  function handleClick(e: React.MouseEvent) {
    console.log('点击了', e.target)
  }
  function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
    console.log('输入了', e.target.value)
  }

  return (
    <div>
      <button onClick={handleClick}>点我</button>
      {/* 需要传参时用箭头函数包裹 */}
      <button onClick={() => handleClick2('参数')}>带参</button>
      <input onChange={handleChange} />
    </div>
  )
}

对照：@click="fn" → onClick={fn}；@click="fn(1)" → onClick={() => fn(1)}。React 没有事件修饰符（.stop、.prevent），要手动写 e.stopPropagation()、e.preventDefault()。

3.5. 表单与受控组件（对照 v-model）

React 没有 v-model。表单输入的值要手动绑定 value + 手动监听 onChange 去更新状态，这种"值由 React state 完全控制"的输入框叫受控组件。

import { useState } from 'react'

function InputDemo() {
  const [text, setText] = useState('')

  return (
    <input
      value={text}                          // 数据 → 页面
      onChange={(e) => setText(e.target.value)}  // 页面 → 数据
    />
  )
}

对照：v-model="text" ≈ value={text} + onChange={(e) => setText(e.target.value)}。
这正是 Vue 里 v-model 拆开后的底层形式（:value + @input）。

3.6. useState（对照 ref / reactive）

useState 是 React 最核心的 Hook，用于定义"组件的状态"。状态变了，组件函数重新执行。

import { useState } from 'react'

function Counter() {
  // 对照：let count = ref(0)
  // useState 返回 [当前值, 修改函数]，通常用数组解构接收
  const [count, setCount] = useState(0)
  const [user, setUser] = useState({ name: '张三', age: 18 })

  function add() {
    setCount(count + 1)        // 对照 count.value += 1
    // 注意：不能写成 count = count + 1，普通变量改了不会触发重渲染
  }
  function changeAge() {
    // 对象类型必须"整体替换"，不能原地修改（与 reactive 完全不同！）
    setUser({ ...user, age: user.age + 1 })  // 展开旧对象 + 覆盖要改的属性
  }

  return (
    <div>
      <h2>计数：{count}</h2>
      <h2>姓名：{user.name}，年龄：{user.age}</h2>
      <button onClick={add}>+1</button>
      <button onClick={changeAge}>年龄+1</button>
    </div>
  )
}

读 React 代码时最重要的规则：state 不可变（immutable）

• 基本类型：setCount(count + 1)。
• 对象/数组：永远不要原地改（如 user.age++、arr.push()），要新建一份再 set。因为 React 靠"引用是否变了"来判断要不要重渲染。
  • 对象：setUser({ ...user, age: 18 })
  • 数组：setList([...list, newItem])、setList(list.filter(...))

对照 Vue3：

• ref(0) ≈ useState(0)（返回值 .value 变成了解构出的 [值, set函数]）。
• reactive({...}) 没有直接对应，React 对象状态也必须整体替换，这跟 Vue reactive 可以 car.price += 1 直接改的体验完全不同。
• 没有 .value 这一层，直接读 count，改要调 setCount。

3.7. useRef（对照 ref 的两种用法）

useRef 同时对应 Vue 里的 DOM 引用 和 "不改触发渲染的变量"。

import { useRef } from 'react'

function Demo() {
  // 1. 拿到 DOM 节点（对照 <h1 ref="title">）
  const titleRef = useRef<HTMLHeadingElement>(null)

  // 2. 存放一个不触发渲染的变量（对照普通 let 变量，但跨渲染保留）
  const timerRef = useRef<number>()

  function show() {
    console.log(titleRef.current)  // 通过 .current 访问 DOM 节点
  }

  return (
    <div>
      <h1 ref={titleRef}>标题</h1>
      <button onClick={show}>打印</button>
    </div>
  )
}

对照 Vue3：

• 获取 DOM：Vue 用 let title = ref() + ref="title"，读 title.value；React 用 useRef(null) + ref={titleRef}，读 titleRef.current。
• useRef 的 current 改了不会触发重渲染，这点和 Vue 的普通变量类似，但普通变量每次渲染会被重置，useRef 则跨渲染保留。

3.8. useEffect（对照 watch / watchEffect / 生命周期）

useEffect 是 React 里最"重"的 Hook，同时承担了 Vue 的 watch、watchEffect、onMounted、onUnmounted 职责。

基本结构：

useEffect(() => {
  // 副作用逻辑：发请求、订阅、操作 DOM、设置定时器...

  return () => {
    // 可选：清理函数，组件卸载 / 依赖变化前执行（对照 onUnmounted）
  }
}, [依赖数组])

情况一：不传依赖数组 → 每次渲染都执行（对照 watchEffect 的某种用法）

useEffect(() => {
  console.log('组件每次渲染后都执行')
})

情况二：传空数组 [] → 只在挂载时执行一次（对照 onMounted）

import { useEffect, useState } from 'react'

function UserList() {
  const [list, setList] = useState([])

  useEffect(() => {
    // 对照 onMounted(() => { getData() })
    fetch('/api/users')
      .then((res) => res.json())
      .then((data) => setList(data))
  }, [])  // 空数组 = 只执行一次

  return <ul>{list.map((u) => <li key={u.id}>{u.name}</li>)}</ul>
}

情况三：依赖数组里写状态 → 状态变化才执行（对照 watch）

const [count, setCount] = useState(0)

useEffect(() => {
  // 对照 watch(count, (newV) => {...})
  console.log('count 变成了', count)
}, [count])  // 只有 count 变化才执行

情况四：带清理函数（对照 onUnmounted）

useEffect(() => {
  const timer = setInterval(() => console.log('tick'), 1000)

  return () => {
    clearInterval(timer)  // 对照 onUnmounted 里清定时器
  }
}, [])

对照 Vue3 总结表：

Vue3	React
onMounted(fn)	useEffect(fn, [])
onUnmounted(fn)	useEffect(() => fn, []) 的清理函数
watch(x, fn)	useEffect(fn, [x])
watchEffect(fn)	不传依赖数组，或手动罗列依赖
onUpdated	无直接对应，较少用

读代码提示：useEffect 第二个参数（依赖数组）是关键，先看 [] 是"只跑一次"，还是有具体依赖"跟着某个值跑"。

3.9. useMemo（对照 computed）

useMemo 用于"根据已有数据计算出新数据并缓存"，等价于 Vue 的 computed。

import { useMemo, useState } from 'react'

function Demo() {
  const [firstName, setFirstName] = useState('zhang')
  const [lastName, setLastName] = useState('san')

  // 对照 computed(() => firstName + '-' + lastName)
  const fullName = useMemo(
    () => `${firstName}-${lastName}`,
    [firstName, lastName]  // 依赖变化才重新计算
  )

  return <p>全名：{fullName}</p>
}

对照：computed(() => ...) ≈ useMemo(() => ..., [依赖])。区别是 Vue 自动追踪依赖，React 要手动在第二个参数里列出依赖。

3.10. useCallback（缓存函数）

useCallback 用来"缓存一个函数"，避免子组件因父组件每次渲染都新建函数而多余地重渲染。读代码时先认识它即可。

import { useCallback, useState } from 'react'

function Parent() {
  const [count, setCount] = useState(0)

  // 这个函数在 count 不变时，引用保持不变
  const handleClick = useCallback(() => {
    setCount((c) => c + 1)
  }, [])

  return <Child onClick={handleClick} />
}

常见于配合 React.memo（见 3.11）使用，用于性能优化。读代码时无需深究原理，知道"它是用来缓存函数的"即可。

3.11. React.memo（对照组件缓存）

React.memo 包装一个组件，让它在 props 没变时跳过重渲染。Vue 中组件默认就有类似优化，React 需要手动加。

import { memo } from 'react'

function Child({ name }: { name: string }) {
  console.log('Child 渲染了')
  return <p>{name}</p>
}

// 默认导出时包一层 memo
export default memo(Child)

3.12. 自定义 Hook（对照自定义 hook）

概念与 Vue3 的自定义 hook 完全一致：把复用逻辑封装成函数，函数名必须以 use 开头。这是两边最像的概念。

// hooks/useSum.ts
import { useState, useCallback } from 'react'

export function useSum(initial = 0) {
  const [sum, setSum] = useState(initial)

  const increment = useCallback(() => setSum((s) => s + 1), [])
  const decrement = useCallback(() => setSum((s) => s - 1), [])

  return { sum, increment, decrement }
}

// 组件中使用
import { useSum } from './hooks/useSum'

function App() {
  const { sum, increment, decrement } = useSum()
  return (
    <div>
      <h2>求和：{sum}</h2>
      <button onClick={increment}>+1</button>
      <button onClick={decrement}>-1</button>
    </div>
  )
}

对照：Vue 的自定义 hook 是 export default function() {...}，React 是 export function useXxx() {...}，使用方式（在组件里解构调用）完全一样。

3.13. 组件定义与 props（对照 props / defineProps）

React 组件通过函数参数接收 props，没有 defineProps，TypeScript 用接口约束类型。

// 定义 props 类型（对照 interface + defineProps）
interface PersonProps {
  name: string
  age?: number        // ? 表示可选
  onGetToy: (value: string) => void   // 函数类型 props
}

// 子组件：props 通过函数参数传入
function Child({ name, age = 18, onGetToy }: PersonProps) {
  return (
    <div>
      <h2>姓名：{name}，年龄：{age}</h2>
      <button onClick={() => onGetToy('奥特曼')}>把玩具给爸爸</button>
    </div>
  )
}

// 父组件：像写 HTML 属性一样传 props
function Father() {
  return <Child name="张三" onGetToy={(toy) => console.log(toy)} />
}

对照 Vue3：

• defineProps(['name','age']) → React 直接在函数参数里解构 { name, age }。
• 默认值：Vue 用 withDefaults，React 直接在解构时写 age = 18。
• 子传父：Vue 用 defineEmits 自定义事件；React 直接传一个回调函数作为 prop（onGetToy），子组件调用它即可。React 没有"事件"这一层抽象。

3.14. 生命周期对照总表

React 函数组件没有 onMounted 等命名钩子，全部用 useEffect 表达：

4. 路由（React Router）

React 路由最常用的是 react-router-dom，目前是 v6 版本。与 Vue Router 概念一一对应。

4.1. 安装与配置

npm install react-router-dom

src/main.tsx（React 版的路由挂载）：

import { BrowserRouter } from 'react-router-dom'

ReactDOM.createRoot(document.getElementById('root')!).render(
  // BrowserRouter = Vue 的 history 模式（createWebHistory）
  <BrowserRouter>
    <App />
  </BrowserRouter>
)

4.2. 定义路由（对照 createRouter 的 routes）

// App.tsx
import { Routes, Route, Link, Outlet } from 'react-router-dom'
import Home from './pages/Home'
import About from './pages/About'

function App() {
  return (
    <div>
      {/* 导航区：Link = RouterLink */}
      <nav>
        <Link to="/home">首页</Link>
        <Link to="/about">关于</Link>
      </nav>

      {/* 展示区：Routes + Route = RouterView + 路由规则 */}
      <Routes>
        <Route path="/home" element={<Home />} />
        <Route path="/about" element={<About />} />
      </Routes>
    </div>
  )
}

对照 Vue3 路由：

Vue Router	React Router v6
<RouterLink to="/home">	<Link to="/home">
<RouterView />	<Routes>...<Route .../></Routes> 或 <Outlet />
{ path, component }	<Route path element={<组件/>} />
useRouter().push()	useNavigate()
useRoute().query/params	useParams() / useSearchParams()

4.3. 嵌套路由（对照 children）

function App() {
  return (
    <Routes>
      <Route path="/news" element={<News />}>
        {/* 子路由：path 不用写全，element 里写子组件 */}
        <Route path="detail" element={<Detail />} />
      </Route>
    </Routes>
  )
}

// News.tsx 里用 Outlet 占位（对照 <RouterView />）
function News() {
  return (
    <div>
      <h2>新闻列表</h2>
      <Outlet />   {/* 子路由组件渲染到这里 */}
    </div>
  )
}

4.4. 路由传参

params（路径参数，对照 Vue 的 params）

// 定义时用 :id 占位
<Route path="/user/:id" element={<User />} />

// 跳转
<Link to="/user/123">用户 123</Link>

// 接收：useParams
import { useParams } from 'react-router-dom'
function User() {
  const { id } = useParams()   // 对照 route.params.id
  return <h1>用户 ID：{id}</h1>
}

query（搜索参数，对照 Vue 的 query）

// 跳转
<Link to="/search?keyword=react&page=1">搜索</Link>

// 接收：useSearchParams（比 Vue 麻烦一点）
import { useSearchParams } from 'react-router-dom'
function Search() {
  const [searchParams] = useSearchParams()
  const keyword = searchParams.get('keyword')  // 对照 route.query.keyword
  return <h1>关键词：{keyword}</h1>
}

4.5. 编程式导航（对照 useRouter）

import { useNavigate } from 'react-router-dom'

function Demo() {
  const navigate = useNavigate()

  function goHome() {
    navigate('/home')                     // 对照 router.push('/home')
  }
  function goBack() {
    navigate(-1)                          // 对照 router.back()
  }
  function replaceTo() {
    navigate('/login', { replace: true }) // 对照 router.replace()
  }
  function goWithParams() {
    navigate('/user/123')                 // params 直接拼在路径里
  }
  function goWithQuery() {
    navigate('/search?keyword=react')     // query 拼在路径后
  }

  return <button onClick={goHome}>去首页</button>
}

4.6. 两种模式（对照 history / hash）

5. 状态管理（对照 Pinia）

React 状态管理方案很多，已有项目中最常见的是 Redux Toolkit（RTK），其次是 Context + useReducer、Zustand。下面重点讲最可能遇到的 RTK，再简单介绍 Context。

5.1. Redux Toolkit（对照 Pinia）

核心概念对照

搭建与使用

npm install @reduxjs/toolkit react-redux

第一步：创建 store（对照 store/count.ts）

// store/counterSlice.ts —— 一个"切片"，对应一个 Pinia 的 store
import { createSlice } from '@reduxjs/toolkit'

const counterSlice = createSlice({
  name: 'counter',            // 对照 defineStore('count', {...})
  initialState: {             // 对照 state()
    sum: 0,
  },
  reducers: {                 // 对照 actions
    increment(state, action) {
      state.sum += action.payload   // 注意：RTK 内部用 immer，允许"看似原地修改"
    },
    decrement(state, action) {
      state.sum -= action.payload
    },
  },
})

export const { increment, decrement } = counterSlice.actions
export default counterSlice.reducer

第二步：汇总成 store（对照 createPinia）

// store/index.ts
import { configureStore } from '@reduxjs/toolkit'
import counterReducer from './counterSlice'

export const store = configureStore({
  reducer: {
    counter: counterReducer,   // 多个 slice 都挂在这里
  },
})

export type RootState = ReturnType<typeof store.getState>
export type AppDispatch = typeof store.dispatch

第三步：注入 Provider（对照 app.use(pinia)）

// main.tsx
import { Provider } from 'react-redux'
import { store } from './store'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <Provider store={store}>
    <App />
  </Provider>
)

第四步：组件中使用（对照 useXxxStore）

import { useSelector, useDispatch } from 'react-redux'
import { increment, decrement } from './store/counterSlice'
import type { RootState } from './store'

function Counter() {
  // 读数据：useSelector，对照 useSumStore().sum
  const sum = useSelector((state: RootState) => state.counter.sum)

  // 修改数据：dispatch(action)
  const dispatch = useDispatch()

  return (
    <div>
      <h2>求和：{sum}</h2>
      <button onClick={() => dispatch(increment(1))}>+1</button>
      <button onClick={() => dispatch(decrement(1))}>-1</button>
    </div>
  )
}

对照 Pinia：

• useSumStore().sum ≈ useSelector((s) => s.counter.sum)
• countStore.increment(n) ≈ dispatch(increment(n))
• Pinia 的 action 里可以写业务逻辑，RTK 里业务逻辑通常写在 createAsyncThunk 或组件里。

5.2. Context（对照 provide / inject）

Context 是 React 内置的跨层级通信方案，对应 Vue 的 provide / inject，也常被用作轻量状态管理。

import { createContext, useContext, useState } from 'react'

// 1. 创建 Context（对照 provide 的 key）
const ThemeContext = createContext('light')

function App() {
  const [theme, setTheme] = useState('light')
  return (
    // 2. Provider 提供数据（对照 provide('theme', value)）
    <ThemeContext.Provider value={theme}>
      <Child />
    </ThemeContext.Provider>
  )
}

function Child() {
  return <GrandChild />
}

function GrandChild() {
  // 3. useContext 消费数据（对照 inject('theme')）
  const theme = useContext(ThemeContext)
  return <p>当前主题：{theme}</p>
}

对照：provide/inject ≈ Context.Provider + useContext。区别是 React 的 Context 值变化会触发所有消费它的组件重渲染，所以常配合 useMemo 缓存。

6. 组件通信对照总表

6.1. 插槽（对照 slot）

React 没有 slot 指令，默认插槽就是 children，具名插槽就是普通 prop，作用域插槽就是 render props。

// 默认插槽（对照 <slot></slot>）
function Card({ children }: { children: React.ReactNode }) {
  return <div className="card">{children}</div>
}

// 使用
<Card>
  <ul><li>内容</li></ul>
</Card>

// 具名插槽（对照 <slot name="header">）
function Layout({ header, footer, children }: { header: React.ReactNode; footer: React.ReactNode; children: React.ReactNode }) {
  return (
    <div>
      <header>{header}</header>
      <main>{children}</main>
      <footer>{footer}</footer>
    </div>
  )
}

// 使用
<Layout
  header={<h1>页头</h1>}
  footer={<p>页脚</p>}
>
  <p>主体内容</p>
</Layout>

// 作用域插槽（对照 v-slot="params"）：用 render props 实现
function GameList({ render }: { render: (games: Game[]) => React.ReactNode }) {
  const games = [{ id: 'a01', name: '英雄联盟' }]
  return <div>{render(games)}</div>
}

// 使用：传一个函数，函数参数就是子组件暴露的数据
<GameList render={(games) => (
  <ul>{games.map((g) => <li key={g.id}>{g.name}</li>)}</ul>
)} />

对照：<slot> → children；<slot name="x"> → 具名 prop；v-slot="params" → render props（传函数）。

7. 其它常见 API

7.1. useReducer（对照复杂状态管理）

当状态逻辑复杂（多个子状态相互关联）时，用 useReducer，它类似 Redux 的迷你版。

import { useReducer } from 'react'

interface State { count: number }
type Action = { type: 'increment' } | { type: 'decrement' } | { type: 'reset' }

function reducer(state: State, action: Action): State {
  switch (action.type) {
    case 'increment':
      return { count: state.count + 1 }
    case 'decrement':
      return { count: state.count - 1 }
    case 'reset':
      return { count: 0 }
  }
}

function Demo() {
  const [state, dispatch] = useReducer(reducer, { count: 0 })
  return (
    <div>
      <h2>计数：{state.count}</h2>
      <button onClick={() => dispatch({ type: 'increment' })}>+1</button>
    </div>
  )
}

7.2. Fragment（对照模板多根节点）

Vue3 模板可以直接写多个根标签，React 的 JSX 必须有一个根元素，用 <></>（Fragment）占位即可，不会渲染出真实 DOM。

function Demo() {
  return (
    <>
      <h1>标题1</h1>
      <h2>标题2</h2>
    </>
  )
}
// 等价于 <React.Fragment>...</React.Fragment>

7.3. createPortal（对照 Teleport）

import { createPortal } from 'react-dom'

function Modal({ isShow }: { isShow: boolean }) {
  if (!isShow) return null
  // 把弹窗 DOM 渲染到 body 下（对照 <Teleport to="body">）
  return createPortal(
    <div className="modal">
      <h2>我是一个弹窗</h2>
    </div>,
    document.body
  )
}

对照：<Teleport to="body"> ≈ createPortal(jsx, document.body)。

7.4. lazy + Suspense（对照 defineAsyncComponent + Suspense）

import { lazy, Suspense } from 'react'

// 异步引入组件（对照 defineAsyncComponent(() => import(...))）
const Child = lazy(() => import('./Child'))

function App() {
  return (
    // Suspense 的 fallback 对照 Vue 的 v-slot:fallback
    <Suspense fallback={<h3>加载中......</h3>}>
      <Child />
    </Suspense>
  )
}

对照：Vue 的 <Suspense> 需要 <template #default> / <template #fallback>；React 直接用 fallback 属性 + 子组件就是 default。

7.5. Class 组件（老项目遗留代码）

老 React 项目会用 Class 组件，读代码时认识即可，现代写法已全面转向函数组件 + Hooks。

import { Component } from 'react'

interface Props { name: string }
interface State { count: number }

class Counter extends Component<Props, State> {
  state: State = { count: 0 }          // 对照 data()

  handleClick = () => {                 // 对照 methods
    this.setState({ count: this.state.count + 1 })  // 对照修改 data
  }

  componentDidMount() {                 // 对照 onMounted
    console.log('挂载了')
  }

  componentWillUnmount() {              // 对照 onUnmounted
    console.log('卸载了')
  }

  render() {                            // 对照 <template>
    return (
      <div>
        <h1>{this.props.name}</h1>      {/* 对照 this.xxx 访问 props */}
        <h2>计数：{this.state.count}</h2>
        <button onClick={this.handleClick}>+1</button>
      </div>
    )
  }
}

Class 组件生命周期对照：componentDidMount = onMounted；componentDidUpdate = onUpdated；componentWillUnmount = onUnmounted。

8. 读 React 代码的速查清单

读一个陌生 React 文件时，按以下顺序快速理解：

1. 看组件签名：function Xxx(props) 是函数组件，class Xxx extends Component 是类组件。
2. 看 import：useState（状态）、useEffect（副作用/请求）、useRef（DOM/持久变量）、useMemo（计算属性）、useCallback（缓存函数）、useContext（跨层数据）。
3. 看 useState 返回的解构：const [xxx, setXxx] = useState(...)，xxx 是数据，setXxx 是唯一修改入口。
4. 看 useEffect 第二参数：[] 只跑一次，[a, b] 跟着 a/b 跑，不写则每次渲染都跑。
5. 看 JSX 里的 { }：花括号里都是 JS 表达式，{list.map(...)} 是循环，{cond && ...} 或三元是条件。
6. 看数据流向：数据永远是"从上往下"通过 props 传，子改父靠回调函数，跨层靠 Context 或状态库。
7. 遇到不认识的 useXxx：大概率是自定义 Hook 或第三方 Hook（如 useNavigate、useSelector），按名字猜用途即可。

8.1. 一张对照速查总表

结语：React 相比 Vue3，少了"响应式魔法"（ref/reactive/computed/watch 的自动依赖追踪），换来的是"一切皆函数、一切皆显式"的简单心智模型。读代码时抓住两条主线即可：① 状态在哪定义、怎么改（useState）；② 状态变化后组件会整体重新执行（JSX 重新计算）。其余 API 都是围绕这两点的补充。

用 Project Reactor 的 bufferTimeout 代替 BufferTrigger 做高并发计数聚合

记录一次在计数服务里做「粉丝数聚合写」的实现。原教程用快手的 BufferTrigger，我改用了 Spring Boot 自带的 Project Reactor，零新增依赖。

背景：为什么要聚合

粉丝数是典型的高并发写场景——某个用户突然爆火，短时间涌入大量关注。如果每来一条 MQ 就 HINCRBY Redis + 写一次库，Redis 和数据库都顶不住。

聚合的本质是：把一个时间窗口内的大量 +1/-1 先在内存里合并，只对 Redis/DB 做一次净增量操作。

比如同一秒内，对用户 27 的粉丝数操作是：

+1  +1  -1  +1

无论顺序如何，聚合到一起就是净 +2，只需操作一次 Redis 与数据库。这就是关注/取关这类计数天然适合聚合的原因——它满足交换律，聚合无需关心顺序，最终一致即可。

聚合需要两个触发条件（谁先到谁触发）：

• 数量阈值：攒够 1000 条，聚合一次；
• 时间窗口：即使 1 秒内不足 1000 条，为了数据及时性，到点也触发一次。

原方案：快手 BufferTrigger

原教程用的是快手开源的 com.github.phantomthief:buffer-trigger：

private BufferTrigger<String> bufferTrigger = BufferTrigger.<String>batchBlocking()
        .bufferSize(50000)              // 缓存队列最大容量
        .batchSize(1000)                // 一批最多聚合 1000 条
        .linger(Duration.ofSeconds(1))  // 多久聚合一次
        .setConsumerEx(this::consumeMessage)
        .build();

// onMessage 里：
bufferTrigger.enqueue(body);

它内部就是一个带「数量阈值 + 时间窗口」双触发的缓冲队列。功能没问题，但这个库 2021 年（0.2.21）后就停更了，是单维护者项目。给一个全新模块引入一个多年不更新的第三方依赖不太理想，所以我换掉了它。

替代方案：Project Reactor 的 Sinks + bufferTimeout

Reactor 随 Spring Boot 传递依赖，已经在 classpath 上，零新增依赖，且由 Spring 团队活跃维护，原生支持背压。核心是三件套。

① 一个 Sink 当入口缓冲

private final Sinks.Many<String> sink = Sinks.many().unicast().onBackpressureBuffer();

Sinks.Many 是 Reactor 里「手动往响应式流里塞元素」的入口。unicast() = 单订阅者，onBackpressureBuffer() = 下游处理不过来时把元素缓存在内部队列里（而不是丢弃或报错）。

② 启动时订阅，挂上 bufferTimeout

@PostConstruct
public void init() {
    subscription = sink.asFlux()
            .bufferTimeout(1000, Duration.ofSeconds(1))   // ← BufferTrigger 的双触发等价物
            .subscribe(this::consumeBatch);
}

bufferTimeout(1000, 1s) 就是等价物：攒够 1000 个元素，或距上批满 1 秒，谁先到就把这一批 List 推给下游。

发 3200 条就会切成 1000 + 1000 + 1000 + 200 四批——前三批靠「满 1000」触发，最后 200 条靠「1 秒超时」触发。

③ RocketMQ 消费回调只负责入队

@Override
public void onMessage(String body) {
    sink.emitNext(body, Sinks.EmitFailureHandler.busyLooping(Duration.ofSeconds(1)));
}

onMessage 不做任何业务，只把消息塞进 sink 后立刻返回。聚合和落库在 Reactor 的另一条线程上异步进行。

关键坑：并发 emit 不安全

这是整个替代方案里最容易踩错的地方。

RocketMQ 是多线程回调 onMessage 的（日志里 ConsumeMessageThread_..._3 那个 _3 就是线程编号），但 Reactor 的 Sinks emit 并不是并发安全的。如果用 tryEmitNext，多个线程同时 emit 会返回 FAIL_NON_SERIALIZED 失败，消息就丢了。

所以这里不能用 tryEmitNext，要用带失败处理器的 emitNext：

sink.emitNext(body, Sinks.EmitFailureHandler.busyLooping(Duration.ofSeconds(1)));

busyLooping 的语义是：遇到并发竞争失败（FAIL_NON_SERIALIZED）时，自旋重试最多 1 秒，直到成功塞进去。这样多线程回调下也不会丢消息。

这一条是相比 BufferTrigger 唯一需要额外操心的地方——BufferTrigger 的 enqueue 内部自己处理了并发。

聚合触发后做什么

拿到一批 List<String> 后的处理流程：

1. 逐条 JsonUtils.parseObject → List<CountFollowUnfollowMqDTO>（过滤 null）
2. FansCountAggregator.aggregate(dtoList)
      → 按 targetUserId 分组，FOLLOW +1 / UNFOLLOW -1 净算
      → Map<Long, Integer>，如 {68001: 1, 27: 3200}
3. 遍历 Map：仅当 redisTemplate.hasKey(key) 时才 HINCRBY fansTotal（不初始化缓存）
4. 把整个 countMap 的 JSON 再发一条 MQ 到 CountFans2DBTopic
      → 由落库消费者用 Guava 令牌桶（5000/s）削峰后 upsert 落库

聚合消费者主体代码：

private void doConsumeBatch(List<String> bodyList) {
    log.info("## 聚合粉丝数消息, size: {}", bodyList.size());

    // List<String> → List<CountFollowUnfollowMqDTO>
    List<CountFollowUnfollowMqDTO> dtoList = bodyList.stream()
            .map(body -> JsonUtils.parseObject(body, CountFollowUnfollowMqDTO.class))
            .filter(Objects::nonNull)
            .toList();

    // 按目标用户分组净算增量
    Map<Long, Integer> countMap = FansCountAggregator.aggregate(dtoList);
    if (countMap.isEmpty()) {
        return;
    }

    // 更新 Redis（仅当 Hash key 已存在，不初始化缓存）
    countMap.forEach((targetUserId, delta) -> {
        String redisKey = RedisKeyConstants.buildCountUserKey(targetUserId);
        if (Boolean.TRUE.equals(redisTemplate.hasKey(redisKey))) {
            redisTemplate.opsForHash().increment(redisKey, RedisKeyConstants.FIELD_FANS_TOTAL, delta);
        }
    });

    // 转发落库 MQ，payload 为聚合后的 countMap JSON
    Message<String> message = MessageBuilder.withPayload(JsonUtils.toJsonString(countMap)).build();
    rocketMQTemplate.asyncSend(MQConstants.TOPIC_COUNT_FANS_2_DB, message, /* SendCallback */);
}

一个可测性改进：第 2 步「分组净算」的逻辑我特意抽成了独立的纯函数 FansCountAggregator.aggregate()，它不依赖 Reactor / MQ / Spring，输入 List<DTO>、输出 Map<Long,Integer>，可以直接单元测试。原教程是把这段逻辑塞在消费者内部的，不好测。

public static Map<Long, Integer> aggregate(List<CountFollowUnfollowMqDTO> dtoList) {
    Map<Long, Integer> countMap = new HashMap<>();
    if (dtoList == null || dtoList.isEmpty()) {
        return countMap;
    }
    for (CountFollowUnfollowMqDTO dto : dtoList) {
        FollowUnfollowTypeEnum typeEnum = FollowUnfollowTypeEnum.valueOf(dto.getType());
        if (Objects.isNull(typeEnum)) {
            continue;   // 非法 type，跳过
        }
        int delta = switch (typeEnum) {
            case FOLLOW -> 1;
            case UNFOLLOW -> -1;
        };
        countMap.merge(dto.getTargetUserId(), delta, Integer::sum);
    }
    return countMap;
}

两个可靠性设计

① consumeBatch 整体 try/catch —— 别让管道断流

private void consumeBatch(List<String> bodyList) {
    try {
        doConsumeBatch(bodyList);
    } catch (Exception e) {
        log.error("## 聚合粉丝数批处理失败（已吞掉，避免终止订阅）, size: {}", bodyList.size(), e);
    }
}

consumeBatch 是 subscribe 的 onNext 回调。如果异常外溢，Reactor 会触发 onError 让整个订阅永久终止——之后所有粉丝数消息都没人处理，只能重启进程恢复。所以这里宁可丢掉出错的这一批（记 error 日志，由计数对账兜底），也绝不能让管道断流。

实测踩过一次：预热 Redis 时手误把值写成了 "0;"（带分号），HINCRBY 要求字段是纯整数，于是抛 ERR hash value is not an integer。正是这层 try/catch 兜住了，订阅没死，其他用户的计数照常处理。

② @PreDestroy 优雅关闭 —— 别丢缓冲区

@PreDestroy
public void shutdown() {
    // 补发完成信号，触发 bufferTimeout 同步 flush 最后一批
    sink.emitComplete(Sinks.EmitFailureHandler.busyLooping(Duration.ofSeconds(1)));
    if (subscription != null) {
        subscription.dispose();
    }
}

停机时补发完成信号，让 bufferTimeout 把缓冲区里还没满 1000 条 / 未到 1s 的最后一批同步 flush 出去（unicast sink 的完成信号在调用线程上同步传播），再释放订阅。避免正常重启 / 发版时丢掉缓冲中的计数。

方案对比

一个共同的固有局限

两种方案都是「先 ack MQ，再异步聚合」——onMessage 把消息塞进缓冲后就返回，RocketMQ 随即提交 offset。如果进程在缓冲的这批消息落到 Redis/DB 之前硬崩，这批消息会永久丢失（无重投），也就是「至多一次」语义。

@PreDestroy 只能覆盖优雅停机（重启、发版），覆盖不了 kill -9 / OOM / 断电这类硬崩。要彻底兜底，需要一个计数对账任务——定期用关系表（t_following / t_fans）重算真实计数，校正计数表。这一点无论用 BufferTrigger 还是 Reactor 都一样，是聚合写这个模式本身的取舍。

一个待优化点

onBackpressureBuffer() 默认是无界队列。极端情况下（下游 Redis/DB 卡死、消息暴涌），可能堆积占内存。BufferTrigger 的 bufferSize(50000) 是有上限的。如果要更贴近有界行为，可以给 sink 配一个容量上限。生产环境值得关注这一点。

小结

• 用 Sinks.many().unicast().onBackpressureBuffer() + bufferTimeout(1000, 1s) 就能等价替代 BufferTrigger 的「数量/时间双触发聚合」，零新增依赖。
• 务必用 emitNext + busyLooping，不能用 tryEmitNext——RocketMQ 多线程回调下 Sinks emit 非并发安全。
• consumeBatch 要整体 try/catch，否则一次异常会终止整个订阅、管道断流。
• 用 @PreDestroy + emitComplete 优雅关闭，flush 掉缓冲区最后一批。
• 聚合的净算逻辑抽成纯函数，方便单测。
• 记住聚合写是「至多一次」，硬崩会丢缓冲——生产上要有对账兜底。

Spring Boot 4.x 整合 Logback 日志框架（支持异步写入）

在构建任何应用程序时，良好的日志管理都是必不可少的。日志可以帮助我们监控、调试和跟踪代码的运行情况。 本小节中，我们继续完善 hannote-auth 认证服务的项目骨架，为其整合 Logback 日志框架，并将配置日志的异步写入文件，以提升应用性能。

1. 添加日志配置文件

编辑 hannote-auth 认证服务，在 /resources 资源目录下，创建名为 logback-spring.xml 日志配置文件：

文件内容如下：

<configuration>
    <!-- 引用 Spring Boot 的 logback 基础配置 -->
    <include resource="org/springframework/boot/logging/logback/defaults.xml" />

    <!-- 应用名称 -->
    <property scope="context" name="appName" value="auth"/>
    <!-- 自定义日志输出路径，以及日志名称前缀 -->
    <property name="LOG_FILE" value="./logs/${appName}.%d{yyyy-MM-dd}"/>
    <!-- 每行日志输出的格式 -->
    <property name="LOG_PATTERN" value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n"/>

    <!-- 文件输出 -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <!-- 日志文件的命名格式 -->
            <fileNamePattern>${LOG_FILE}-%i.log</fileNamePattern>
            <!-- 保留 30 天的日志文件 -->
            <maxHistory>30</maxHistory>
            <!-- 单个日志文件最大大小 -->
            <maxFileSize>10MB</maxFileSize>
            <!-- 日志文件的总大小，0 表示不限制 -->
            <totalSizeCap>0</totalSizeCap>
            <!-- 重启服务时，是否清除历史日志，不推荐清理 -->
            <cleanHistoryOnStart>false</cleanHistoryOnStart>
        </rollingPolicy>
        <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <pattern>${LOG_PATTERN}</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>

    <!-- 本地 dev 开发环境 -->
    <springProfile name="dev">
        <include resource="org/springframework/boot/logging/logback/console-appender.xml" />
        <root level="INFO">
            <appender-ref ref="CONSOLE"/> <!-- 输出控制台日志 -->
            <appender-ref ref="FILE"/> <!-- 打印日志到文件中。PS: 本地环境下，如果不想打印日志到文件，可注释掉此行 -->
        </root>
    </springProfile>

    <!-- 其它环境 -->
    <springProfile name="prod">
        <include resource="org/springframework/boot/logging/logback/console-appender.xml" />
        <root level="INFO">
            <appender-ref ref="FILE"/> <!-- 生产环境下，仅打印日志到文件中 -->
        </root>
    </springProfile>

</configuration>

说一下日志配置文件中，每项配置都是干啥的：

• 基础配置和属性定义：

<include resource="org/springframework/boot/logging/logback/defaults.xml" />

上述配置用于引用 Spring Boot 的默认 Logback 基础配置。

<property scope="context" name="appName" value="auth"/>
<property name="LOG_FILE" value="./logs/${appName}.%d{yyyy-MM-dd}"/>
<property name="LOG_PATTERN" value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n"/>

• 定义了一些全局属性：
  • appName：应用名称，这里值填写为 auth ，表示认证服务。
  • LOG_FILE：日志文件的路径和文件名模板， ./logs 表示输出到项目的同级目录下的 /logs 文件夹下。
  • LOG_PATTERN：日志输出格式。
• 日志文件 Appender 配置：

<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
        <fileNamePattern>${LOG_FILE}-%i.log</fileNamePattern>
        <maxHistory>30</maxHistory>
        <maxFileSize>10MB</maxFileSize>
        <totalSizeCap>0</totalSizeCap>
        <cleanHistoryOnStart>false</cleanHistoryOnStart>
    </rollingPolicy>
    <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
        <pattern>${LOG_PATTERN}</pattern>
        <charset>UTF-8</charset>
    </encoder>
</appender>

• appender：用于将日志输出到文件，并且使用滚动策略来管理日志文件。
• rollingPolicy：定义了日志滚动策略，使用 SizeAndTimeBasedRollingPolicy 以时间和大小为基准进行滚动。
• fileNamePattern：定义了日志文件的命名模式。
• maxHistory：保留 30 天的日志文件。
• maxFileSize：每个日志文件最大 10MB。
• totalSizeCap：总日志文件大小没有限制。
• cleanHistoryOnStart：项目启动时不清理历史日志文件。
• encoder：定义了日志的输出格式，以及文件编码格式。
• Spring Profile 配置：用于配置各环境的日志行为。这里主要定义了 dev 和 prod 两个环境：

<springProfile name="dev">
   <include resource="org/springframework/boot/logging/logback/console-appender.xml" />
    <root level="INFO">
       <appender-ref ref="CONSOLE"/>
        <appender-ref ref="FILE"/> 
    </root>
</springProfile>

dev 本地开发环境中，包含控制台输出 CONSOLE 和文件输出 FILE。CONSOLE 配置通过包含 Spring Boot 默认的 console-appender.xml 实现。

<springProfile name="prod">
   <include resource="org/springframework/boot/logging/logback/console-appender.xml" />
    <root level="INFO">
       <appender-ref ref="FILE"/> 
    </root>
</springProfile>

prod 生产环境中，仅包含文件输出 FILE，不输出到控制台。这是为了生产环境中减少控制台日志输出，避免影响性能。

拓展小知识 : 如果你想同时设置多个环境，假设咱们除了本地开发环境、生产环境外，还有个 test 测试环境， 也仅需要输出日志到文件。则可以配置如下，通过逗号 , 分隔开来就行：

<springProfile name="test,prod">
    // 省略...
</springProfile>

2. 测试看看效果

因为我们上面通过 springProfile , 配置了 dev 开发环境中，打印日志到文件中。接下来，重启项目，实测一下看看功能是否正常：

项目启动成功后，如上图所示，进入到项目的 /logs 文件夹下，可以看到日志输出是 ok 的。

3. 异步日志

异步打印日志（Asynchronous Logging）是一种日志记录方式，它将日志写入操作放在一个单独的线程中执行，而不是在主线程中进行。这意味着日志写入的过程不会阻塞主线程的执行，主线程可以继续执行其余的业务逻辑，增强了应用的性能和响应速度。

3.1 为什么需要异步打印日志

• 性能提升：同步日志记录在高并发情况下会显著影响应用性能，因为每一次日志写入操作都可能导致磁盘 I/O 操作，主线程必须等待这些操作完成才能继续执行。异步日志记录将这些操作放在单独的线程中进行，避免了主线程的阻塞，提高了整体性能。
• 响应时间：异步日志记录可以减少应用的响应时间，尤其是在需要记录大量日志信息的时候。用户请求得到快速响应，而日志记录在后台处理。
• 资源利用：通过异步日志记录，应用可以更有效地利用 CPU 资源。同步日志记录可能导致线程频繁等待 I/O 操作完成，而异步记录可以让这些线程去执行其他任务，提高资源利用率。
• 系统稳定性：在极端情况下（例如，日志量非常大时），同步日志记录可能会导致应用出现性能瓶颈甚至崩溃。异步日志记录通过缓冲和队列机制，能够更好地应对突发的大量日志请求，增强系统稳定性。

3.2 Logback 配置异步日志

Logback 提供了 AsyncAppender 来支持异步日志记录。通过 AsyncAppender 可以将日志事件发送到一个队列中，并由一个独立的线程池来处理这些日志事件。编辑 logback-spring.xml 文件，添加配置如下：

<!-- 异步写入日志，提升性能 -->
<appender name="ASYNC_FILE" class="ch.qos.logback.classic.AsyncAppender">
    <!-- 是否丢弃日志, 0 表示不丢弃。默认情况下，如果队列满 80%, 会丢弃 TRACE、DEBUG、INFO 级别的日志 -->
    <discardingThreshold>0</discardingThreshold>
    <!-- 队列大小。默认值为 256 -->
    <queueSize>256</queueSize>
    <appender-ref ref="FILE"/>
</appender>

解释一下修改的地方，主要添加了一个名称为 ASYNC_FILE 异步输出日志的 Appender：

• AsyncAppender 使用内部队列来异步处理日志事件。
• queueSize：队列的大小。
• discardingThreshold：是否丢弃日志, 0 表示不丢弃。

最后，将各个环境中的 FILE 更改为 ASYNC_FILE 异步写入日志。别忘了，再次重启一下项目，自测一波日志功能是否好使~

自定义 Jackson 配置：支持 LocalDateTime 日期 API

本小节中，我们将为认证服务自定义 Jackson 配置，以支持 Java 8 中新的日期 API 。

1. 不支持 LocalDateTime 问题演示

注意这里返回的时间类型并不是我们在前面设置的时间日期格式，其次如果我们按照我们先前设置的格式作为入参，同样也无法反序列化，这个我们可以做一下实验！

假设我们想让 /test3 接口支持传入参数 User 实体类，代码如下：

@PostMapping("/test3")
@ApiOperationLog(description = "测试接口3")
public Response<User> test2(@RequestBody User user) {
    return Response.success(user);
}

然后发送请求：

再来看看后端控制台信息，有如下一行警告信息：

JSON parse error: Cannot deserialize value of type `java.time.LocalDateTime` from String "2026-02-04 12:00:00": Failed to deserialize `java.time.LocalDateTime` (with format 'ParseCaseSensitive(false)(Value(Year,4,10,EXCEEDS_PAD)'-'Value(MonthOfYear,2)'-'Value(DayOfMonth,2))'T'(Value(HourOfDay,2)':'Value(MinuteOfHour,2)[':'Value(SecondOfMinute,2)[Fraction(NanoOfSecond,0,9,DecimalPoint)]])'): (java.time.format.DateTimeParseException) Text '2026-02-04 12:00:00' could not be parsed at index 10]

提示我们 JSON 解析错误，无法将 2026-02-04 12:00:00 字符串解析为 java.time.LocalDateTime 日期类。

2. 自定义 Jackson 配置

这个我们直接把这个 Jackson的配置类封装为一个starter，这样方便我们在不同的服务中引入！首先我某地 hanserwei-framework下新建 hanserwei-spring-boot-starter-jackson模块：

pom文件如下：

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <!-- 父项目配置 -->
    <parent>
        <!-- 组织ID -->
        <groupId>com.hanserwei</groupId>
        <!-- 父项目artifactId -->
        <artifactId>hanserwei-framework</artifactId>
        <!-- 版本号，使用变量引用 -->
        <version>${revision}</version>
    </parent>

    <!-- 当前模块的artifactId -->
    <artifactId>hanserwei-spring-boot-starter-jackson</artifactId>
    <!-- 打包方式为jar包 -->
    <packaging>jar</packaging>

    <!-- 项目名称，引用artifactId -->
    <name>${project.artifactId}</name>
    <!-- 项目描述 -->
    <description>自定义JacksonStarter</description>

    <!-- 项目属性配置 -->
    <properties>
        <!-- 源代码编码格式 -->
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <!-- 依赖管理 -->
    <dependencies>
        <!-- hanserwei通用模块依赖 -->
        <dependency>
            <groupId>com.hanserwei</groupId>
            <artifactId>hanserwei-common</artifactId>
        </dependency>
        <!-- Spring Boot自动配置依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-autoconfigure</artifactId>
        </dependency>
    </dependencies>
</project>

我们先在 hanserwei-common的 constant包下定义一下我们常用的几个日期格式：

package com.hanserwei.framework.common.constant;

import java.time.format.DateTimeFormatter;

/**
 * @author hanser
 */
public interface DateConstants {

    /**
     * DateTimeFormatter：年-月-日 时：分：秒
     */
    DateTimeFormatter DATE_FORMAT_Y_M_D_H_M_S = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");

    /**
     * DateTimeFormatter：年-月-日
     */
    DateTimeFormatter DATE_FORMAT_Y_M_D = DateTimeFormatter.ofPattern("yyyy-MM-dd");

    /**
     * DateTimeFormatter：时：分：秒
     */
    DateTimeFormatter DATE_FORMAT_H_M_S = DateTimeFormatter.ofPattern("HH:mm:ss");

    /**
     * DateTimeFormatter：年-月
     */
    DateTimeFormatter DATE_FORMAT_Y_M = DateTimeFormatter.ofPattern("yyyy-MM");
}

然后回到我们的 CustomJacksonConfiguration 类中，Jackson3的配置方式和 Jackson2有些许不同，直接看我的代码，我代码中会有详细的注释：

package com.hanserwei.jackson.config;

import com.hanserwei.framework.common.constant.DateConstants;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.context.annotation.Bean;
import tools.jackson.databind.DeserializationFeature;
import tools.jackson.databind.SerializationFeature;
import tools.jackson.databind.ext.javatime.deser.LocalDateDeserializer;
import tools.jackson.databind.ext.javatime.deser.LocalDateTimeDeserializer;
import tools.jackson.databind.ext.javatime.deser.LocalTimeDeserializer;
import tools.jackson.databind.ext.javatime.deser.YearMonthDeserializer;
import tools.jackson.databind.ext.javatime.ser.LocalDateSerializer;
import tools.jackson.databind.ext.javatime.ser.LocalDateTimeSerializer;
import tools.jackson.databind.ext.javatime.ser.LocalTimeSerializer;
import tools.jackson.databind.ext.javatime.ser.YearMonthSerializer;
import tools.jackson.databind.json.JsonMapper;
import tools.jackson.databind.module.SimpleModule;

import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.LocalTime;
import java.time.YearMonth;
import java.util.TimeZone;

/**
 * @author hanser
 */
@AutoConfiguration
public class CustomJacksonConfiguration {

    @Bean
    public JsonMapper jsonMapper() {
        SimpleModule customModule = new SimpleModule();
        // 支持 LocalDateTime、LocalDate、LocalTime
        customModule.addSerializer(LocalDateTime.class, new LocalDateTimeSerializer(DateConstants.DATE_FORMAT_Y_M_D_H_M_S));
        customModule.addDeserializer(LocalDateTime.class, new LocalDateTimeDeserializer(DateConstants.DATE_FORMAT_Y_M_D_H_M_S));
        customModule.addSerializer(LocalDate.class, new LocalDateSerializer(DateConstants.DATE_FORMAT_Y_M_D));
        customModule.addDeserializer(LocalDate.class, new LocalDateDeserializer(DateConstants.DATE_FORMAT_Y_M_D));
        customModule.addSerializer(LocalTime.class, new LocalTimeSerializer(DateConstants.DATE_FORMAT_H_M_S));
        customModule.addDeserializer(LocalTime.class, new LocalTimeDeserializer(DateConstants.DATE_FORMAT_H_M_S));
        // 支持 YearMonth
        customModule.addSerializer(YearMonth.class, new YearMonthSerializer(DateConstants.DATE_FORMAT_Y_M));
        customModule.addDeserializer(YearMonth.class, new YearMonthDeserializer(DateConstants.DATE_FORMAT_Y_M));


        return JsonMapper.builder()
                // 在反序列化时，忽略在 JSON 中存在但 Java 对象中不存在的属性，防止报错
                .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
                // 在序列化时，允许序列化空的 POJO 类（没有属性的类），防止报错
                .disable(SerializationFeature.FAIL_ON_EMPTY_BEANS)
                // 设置默认时区为东八区（北京时间）
                .defaultTimeZone(TimeZone.getTimeZone("GMT+8"))
                // 添加自定义模块
                .addModule(customModule)
                // 自动查找并添加所有可用的 Jackson 模块
                .findAndAddModules()
                .build();
    }
}

但是，现在有个问题，在之前 hanserwei-common 公共模块中，我们封装了一个 JsonUtils 工具类，里面的序列化、反序列是有重复定义的，怎么能统一复用上面的呢？ 这样就不用适配多处了，代码看起来也优雅很多。

为了解决上面提到的问题，我们可以在 JsonUtils 工具类中，定义一个 init() 初始化方法，代码如下：

package com.hanserwei.framework.common.util;

import tools.jackson.databind.json.JsonMapper;

/**
 * JSON 工具类，提供对象与 JSON 字符串之间的转换功能
 *
 * @author hanser
 */
public class JsonUtils {

    /**
     * 初始化 Jackson 的 JsonMapper 实例
     */
    private static JsonMapper JSON_MAPPER = new JsonMapper();
  
    /**
     * 初始化：统一使用 Spring Boot 个性化配置的 ObjectMapper
     *
     * @param jsonMapper 自定义的 JsonMapper 实例
     */
    public static void init(JsonMapper jsonMapper) {
        JSON_MAPPER = jsonMapper;
    }

    /**
     * 将对象序列化为 JSON 字符串
     *
     * @param object 需要转换的对象
     * @return 转换后的 JSON 字符串
     */
    public static String toJsonString(Object object) {
        return JSON_MAPPER.writeValueAsString(object);
    }
}

然后在 CustomJacksonConfiguration注入bean的时候调用一下 init方法：

最后一步，在 org.springframework.boot.autoconfigure.AutoConfiguration.imports里面导入自动配置类的全类名：

为了方便在其他模块导入这个starter，我们在最外层的pom文件中定义这个starter的版本！

<dependency>
    <groupId>com.hanserwei</groupId>
    <artifactId>hanserwei-spring-boot-starter-jackson</artifactId>
    <version>${revision}</version>
</dependency>

然后在 hannote-auth服务中导入我们定义的starter：

这个时候我们重启一下项目，试验一下！

入参也没问题：

AOP切面日志也没问题：

添加 framework 平台基础设施模块

本小节中，我们继续完善后端项目骨架 —— 抽取一个 framework 平台基础设施模块。如下图所示：

为什么要抽取一个 framework 基础设施模块？

在微服务架构中，如果每个服务都像一个独立的“孤岛”，虽然实现了业务解耦，但会导致大量重复的底层代码和架构标准的不统一。

抽取一个 Framework（基础设施/底座）模块，本质上是为了解决“微服务治理的复杂度”问题。

1. 减少重复造轮子 (DRY原则)

在微服务开发中，很多功能是跨业务通用的。如果没有统一的基础设施模块，每个微服务都要手动配置：

• 异常处理：统一的全局异常拦截与错误码定义。
• 日志记录：统一的日志格式（如：链路追踪 TraceID、请求 ID）。
• 安全校验：JWT 解析、权限拦截、敏感词过滤。
• 工具类：对象拷贝（BeanUtils）、JSON 处理、日期工具等。

核心价值：让开发者专注于业务逻辑（Business Logic），而不是反复配置基础设施。

2. 统一技术标准与版本管理

当项目规模扩大时，最头疼的就是“版本冲突”。

• 依赖控制：在 Framework 中统一管理 Spring Boot、MyBatis、Swagger 等第三方库的版本，避免 A 服务用 2.x，B 服务用 3.x 导致的兼容性灾难。

• 规范落地：比如强制要求所有接口返回统一的 JSON 格式：

  JSON

  { "code": 200, "data": {}, "msg": "success" }
  

3. 提升运维与监控效率

微服务越多，治理难度越大。Framework 模块可以集成以下监控切面：

• 链路追踪：自动集成 SkyWalking 或 Zipkin。
• 指标采集：预装 Prometheus 指标，自动暴露健康检查端点。
• 限流降级：预置 Sentinel 或 Resilience4j 的默认配置。

4. 降低维护成本

假设公司决定从 Redis 切换到另一个缓存中间件，或者需要对敏感信息进行脱敏处理：

• 有 Framework：只需修改一次 Framework 中的 common-redis 启动器，所有微服务升级依赖即可。
• 无 Framework：你需要手动修改几十个微服务的代码，出错概率呈几何倍数增加。

新建 framework 模块

在项目上右键 | New | Module... , 新建一个子模块：

解释一下标注的部分：

• ①：选择 Maven Archetype 来创建一个 Maven 子模块;
• ②：项目名称填写 hanserwei-framework；
• ③：项目使用的 JDK 版本，本项目使用的是 JDK 25 ；
• ④：父模块选择 hannote ；
• ⑤：选择 Internal 。
• ⑥：选择 maven-archetype-quickstart。
• ⑦：填写 Group 组织名称，通常为公司域名倒写，如 com.hanserwei；
• ⑧：项目的唯一标识符；

点击 Create 按钮开始创建 framework 子模块, 成功创建后，查看父模块的 pom.xml 文件，内容如下，可以看到 <modules> 节点中，自动添加上了该模块：

编辑 hanserwei-framework 模块中的 pom.xml , 内容如下：

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- 父项目配置 -->
    <parent>
        <!-- 组织ID -->
        <groupId>com.hanserwei</groupId>
        <!-- 父项目工件ID -->
        <artifactId>hannote</artifactId>
        <!-- 版本号，使用变量引用 -->
        <version>${revision}</version>
    </parent>

    <!-- 当前模块工件ID -->
    <artifactId>hanserwei-framework</artifactId>
    <!-- 打包方式为pom，表示这是一个父模块 -->
    <packaging>pom</packaging>

    <!-- 项目名称 -->
    <name>${project.artifactId}</name>
    <!-- 项目描述 -->
    <description>平台基础设施层：封装一些常用功能，供各个业务线拿来即用</description>

    <!-- 项目属性配置 -->
    <properties>
        <!-- 项目源码编码格式 -->
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <!-- 子模块列表 -->
    <modules>

    </modules>

</project>

• 指定了父项目是谁；
• 打包方式和父模块一样，都是 pom 形式, 因为后续要在 framework 基础设施层中，添加很多个子模（封装各种业务组件）。

项目结构如下图所示：

注意 : 如果自动生成了 /src 目录，需要删除掉。

添加 common 通用子模块

在 hanserwei-framewrok 模块上，继续右键 | New | Module... , 为基础设施层添加第一个子模块 —— hanserwei-common , 此模块为平台通用模块，主要放置一些通用枚举、工具类等等：

填写相关选项，如下图所示：

解释一下标注的部分：

• ①：选择 Maven Archetype 来创建一个 Maven 子模块;
• ②：项目名称填写 hanserwei-common；
• ③：项目使用的 JDK 版本，本项目使用的是 JDK 25 ；
• ④：父模块选择 hanserwei-framework ；
• ⑤：选择 Internal 。
• ⑥：选择 maven-archetype-quickstart。
• ⑦：组织 ID : com.hanserwei.framework.common；
• ⑧：项目的唯一标识符；

点击 Create 按钮创建子模块。同样的，创建完成以后，查看 hanserwei-framework 模块的 pom.xml 文件，确认一下 <modules> 节点是否有自动添加该通用工具组件：

接着，编辑 hanserwei-common 模块的 pom.xml , 内容如下：

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- 父项目配置 -->
    <parent>
        <!-- 组织ID -->
        <groupId>com.hanserwei</groupId>
        <!-- 父项目名称 -->
        <artifactId>hanserwei-framework</artifactId>
        <!-- 版本号，使用变量引用 -->
        <version>${revision}</version>
    </parent>

    <!-- 当前模块的组织ID -->
    <groupId>com.hanserwei.framework.common</groupId>
    <!-- 当前模块的项目ID -->
    <artifactId>hanserwei-common</artifactId>
    <!-- 打包方式：jar包 -->
    <packaging>jar</packaging>

    <!-- 项目名称，引用项目ID -->
    <name>${project.artifactId}</name>
    <!-- 项目描述 -->
    <description>平台通用模块，如一些通用枚举、工具类等等</description>

    <!-- 项目属性配置 -->
    <properties>
        <!-- 项目源码编码格式 -->
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <!-- 项目依赖配置 -->
    <dependencies>
        <!-- Lombok依赖：用于简化Java代码，自动生成getter/setter等方法 -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
    </dependencies>
</project>

• 注意，这里指定了父项目为 hanserwei-framework， 打包方式为 Jar 包，添加一些模块描述性文字；
• 然后添加了 Lombok 依赖。

删掉图中所示的部分：

添加 Response 工具类

在 com.hanserwei.framework.common 包下，添加一个封装好的 Response 响参工具类，以及相关异常类：

package com.hanserwei.framework.common.exception;

/**
 * @author hanser
 */
public interface BaseExceptionInterface {


    /**
     * 获取异常码
     *
     * @return 异常码
     */
    String getErrorCode();

    /**
     * 获取异常信息
     *
     * @return 异常信息
     */
    String getErrorMessage();
}

定义业务异常类：

TIP : Biz 是 Business 英文的缩写，代表业务的意思。

package com.hanserwei.framework.common.exception;

import lombok.Getter;
import lombok.Setter;

/**
 * @author hanser
 */
@Getter
@Setter
public class BizException extends RuntimeException {

    /**
     * 异常码
     */
    private String errorCode;
    /**
     * 错误信息
     */
    private String errorMessage;

    public BizException(BaseExceptionInterface baseExceptionInterface) {
        this.errorCode = baseExceptionInterface.getErrorCode();
        this.errorMessage = baseExceptionInterface.getErrorMessage();
    }
}

封装响参工具类：

package com.hanserwei.framework.common.response;

import com.hanserwei.framework.common.exception.BaseExceptionInterface;
import com.hanserwei.framework.common.exception.BizException;
import lombok.Data;

import java.io.Serializable;

/**
 * 统一响应结果封装类
 *
 * @param <T> 响应数据类型
 * @author hanser
 */
@Data
public class Response<T> implements Serializable {

    /**
     * 是否成功，默认为 true
     */
    private boolean success = true;

    /**
     * 响应消息
     */
    private String message;

    /**
     * 异常码
     */
    private String errorCode;

    /**
     * 响应数据
     */
    private T data;

    /**
     * 成功响应（无数据）
     *
     * @param <T> 响应数据类型
     * @return 成功响应对象
     */
    public static <T> Response<T> success() {
        return new Response<>();
    }

    /**
     * 成功响应（带数据）
     *
     * @param data 响应数据
     * @param <T>  响应数据类型
     * @return 成功响应对象
     */
    public static <T> Response<T> success(T data) {
        Response<T> response = new Response<>();
        response.setData(data);
        return response;
    }

    /**
     * 失败响应（无错误信息）
     *
     * @param <T> 响应数据类型
     * @return 失败响应对象
     */
    public static <T> Response<T> fail() {
        Response<T> response = new Response<>();
        response.setSuccess(false);
        return response;
    }

    /**
     * 失败响应（带错误消息）
     *
     * @param errorMessage 错误消息
     * @param <T>          响应数据类型
     * @return 失败响应对象
     */
    public static <T> Response<T> fail(String errorMessage) {
        Response<T> response = new Response<>();
        response.setSuccess(false);
        response.setMessage(errorMessage);
        return response;
    }

    /**
     * 失败响应（带错误码和错误消息）
     *
     * @param errorCode    错误码
     * @param errorMessage 错误消息
     * @param <T>          响应数据类型
     * @return 失败响应对象
     */
    public static <T> Response<T> fail(String errorCode, String errorMessage) {
        Response<T> response = new Response<>();
        response.setSuccess(false);
        response.setErrorCode(errorCode);
        response.setMessage(errorMessage);
        return response;
    }

    /**
     * 失败响应（基于业务异常）
     *
     * @param bizException 业务异常对象
     * @param <T>          响应数据类型
     * @return 失败响应对象
     */
    public static <T> Response<T> fail(BizException bizException) {
        Response<T> response = new Response<>();
        response.setSuccess(false);
        response.setErrorCode(bizException.getErrorCode());
        response.setMessage(bizException.getErrorMessage());
        return response;
    }

    /**
     * 失败响应（基于异常接口）
     *
     * @param baseExceptionInterface 异常接口对象
     * @param <T>                    响应数据类型
     * @return 失败响应对象
     */
    public static <T> Response<T> fail(BaseExceptionInterface baseExceptionInterface) {
        Response<T> response = new Response<>();
        response.setSuccess(false);
        response.setErrorCode(baseExceptionInterface.getErrorCode());
        response.setMessage(baseExceptionInterface.getErrorMessage());
        return response;
    }

}

至此，我们已经在 hanserwei-common 通用模块中，成功添加了响参工具类。这个功能是后续各个服务中，都需要用到的。

父模块中管理 common 模块版本号

接下来，我们将在 hannote-auth 认证服务中，引入 hanserwei-common 模块，并测试一下是否能够正常使用 Response 响参工具类。首先，需要在最外层的 pom 文件中，声明一下 hanserwei-common 依赖以及其版本号，如下：

然后，编辑 hannote-auth 认证服务的 pom.xml 文件，引入该依赖：

添加一个测试接口

将认证服务中添加一个 controller 包，并创建一个 TestController 用于测试：

添加一个 /test 接口，并使用 Response 响参工具类进行成功响应，代码如下：

package com.hanserwei.hannote.auth.controller;

import com.hanserwei.framework.common.response.Response;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author hanser
 */
@RestController
public class TestController {

    @GetMapping("/test")
    public Response<String> test() {
        return Response.success("Hello, Hanserwei!");
    }
}

重启认证服务，打开浏览器，访问 localhost:8080/test 接口，可以看到响应参数都是 OK 的：

结语

本小节中，我们继续完善了小憨书的工程骨架，添加了 framework 基础设施模块，接着，在该模块中添加了 hanserwei-common通用模块，后续如一些业务上通用的枚举、工具类等等，都可以放置此模块中。最后，我们在认证服务的 pom.xml 中，引入了 common 模块，并创建了一个测试接口，通过 Response 工具类，对前端成功返回了响应参数。

自定义 Spring Boot Starter: 封装 API 请求日志切面业务组件

本小节中，我们将自定义一个 Spring Boot Starter 组件，将 API 请求日志切面功能封装进去，后续新建新的服务时，只需添加这个 starter , 即可拿来即用。

1. 什么是 Spring Boot Starter ?

Spring Boot Starter 就像是一个“工具包”，里面已经包含了你所需要的东西。它们把一些常用的功能和技术打包好了，比如处理数据库、处理 Web 请求等等。你只需要在你的项目中引入这些 Starter，它们就会自动帮你配置好所需的依赖项和参数。这样，你就可以省去很多繁琐的配置工作。

举个栗子，当你想要使用 Spring Boot 开发一个 Web 应用时，只需要引入 spring-boot-starter-web Starter。这个 Starter 包含了一系列依赖项和配置，使得开发 Web 应用变得更加简单。

具体来说，引入 spring-boot-starter-web Starter 后，你可以享受到以下好处：

• 内嵌的 Web 服务器支持：Spring Boot 内置了多种 Web 服务器支持，比如 Tomcat、Jetty、Undertow。spring-boot-starter-web 会自动配置一个默认的 Web 服务器，你无需手动配置即可启动你的应用。
• Spring MVC 框架支持：Spring Boot 基于 Spring MVC 构建了强大的 Web 开发框架，包括了控制器、视图解析器等。引入 spring-boot-starter-web 后，你可以直接使用 Spring MVC 来处理 Web 请求。
• 静态资源支持：spring-boot-starter-web Starter 自动配置了对静态资源（如 HTML、CSS、JavaScript 文件）的处理，你可以直接在项目中放置这些文件，Spring Boot 就能够正确地访问它们。
• 自动配置：Spring Boot 会根据你的 classpath 自动配置应用程序。比如，如果你引入了 spring-boot-starter-web，Spring Boot 就会自动配置 DispatcherServlet、ViewResolver 等关键组件，从而让你的 Web 应用能够顺利地工作起来。

简而言之，Spring Boot Starter 是一种方便的方式，让你能够更快、更轻松地开始使用 Spring Boot 框架，并集成各种常用功能和技术。

2. 自定义 Spring Boot Starter

在 hanserwei-framewrok 模块上，继续右键 | New | Module... , 为基础设施层添加新的子模块 —— 业务日志切面组件：

填写相关选项，如下图所示：

点击 Create 按钮，开始创建子模块，创建完成后，查看 hanserwei-framework 模块的 pom.xml 文件，可以看到 <modules> 节点下自动添加好了该子模块：

编辑切面日志组件的 pom.xml 文件，内容如下：

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- 父项目配置 -->
    <parent>
        <groupId>com.hanserwei</groupId>
        <artifactId>hanserwei-framework</artifactId>
        <version>${revision}</version>
    </parent>

    <!-- 当前模块的artifactId -->
    <artifactId>hanserwei-spring-boot-starter-biz-operationlog</artifactId>
    <!-- 打包方式：jar包 -->
    <packaging>jar</packaging>

    <!-- 项目名称 -->
    <name>hanserwei-spring-boot-starter-biz-operationlog</name>
    <!-- 项目描述：接口日志组件 -->
    <description>接口日志组件</description>

    <!-- 项目属性配置 -->
    <properties>
        <!-- 项目构建时的源码编码格式 -->
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <!-- 项目依赖 -->
    <dependencies>
        <!-- 公共工具依赖 -->
        <dependency>
            <groupId>com.hanserwei</groupId>
            <artifactId>hanserwei-common</artifactId>
        </dependency>

        <!-- Spring Boot AOP切面支持，用于实现操作日志的切面拦截 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-aspectj</artifactId>
        </dependency>
    </dependencies>
</project>

注意：在Spring Boot 4中AOP的Starter名称变了！

接着，将一些不需要的类删除掉：

3. 添加 JSON 工具类

由于在日志切面 starter 组件中，需要以 json 的格式打印出参，所以，我们需要先封装一个 Json 工具类。由于我们在最外层已经导入了pom文件，里面已经定义了Jackson的版本信息。所有我们不用再显示指定！

编辑 hanserwei-common 公共模块的 pom.xml, 添加 Jackson 相关依赖：

注意：Jackson3的包名变了而且有关Java8的新日期API也已经合并到Jackson3中了，不用再额外引入了！

在 hanserwei-common 模块中，新建一个 util 工具包，用于统一放置相关工具类，并创建 JsonUtils , 如下图所示:

代码如下：

package com.hanserwei.framework.common.util;

import tools.jackson.databind.DeserializationFeature;
import tools.jackson.databind.SerializationFeature;
import tools.jackson.databind.json.JsonMapper;

/**
 * JSON 工具类，提供对象与 JSON 字符串之间的转换功能
 *
 * @author hanser
 */
public class JsonUtils {

    /**
     * 初始化 Jackson 的 JsonMapper 实例
     */
    private static final JsonMapper JSON_MAPPER = JsonMapper.builder()
            // 在反序列化时，忽略在 JSON 中存在但 Java 对象中不存在的属性，防止报错
            .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false)
            // 在序列化时，允许序列化空的 POJO 类（没有属性的类），防止报错
            .configure(SerializationFeature.FAIL_ON_EMPTY_BEANS, false)
            // 自动查找并注册所有的 Jackson 模块（如 Java 8 时间模块等）
            .findAndAddModules()
            .build();

    /**
     * 将对象序列化为 JSON 字符串
     *
     * @param object 需要转换的对象
     * @return 转换后的 JSON 字符串
     */
    public static String toJsonString(Object object) {
        return JSON_MAPPER.writeValueAsString(object);
    }
}

4. 添加日志切面

Json 工具类编写完成后，回到日志切面 starter 组件中，创建 /aspect 包，用于放置切面相关的类，在里面添加自定义注解以及切面，这块的代码就是很经典的AOP的代码，不做赘述，直接拿过用就行:

package com.hanserwei.framework.biz.operationlog.aspect;

import java.lang.annotation.*;

/**
 * @author hanser
 */
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
@Documented
public @interface ApiOperationLog {
    /**
     * API 功能描述
     *
     */
    String description() default "";

}

package com.hanserwei.framework.biz.operationlog.aspect;

import com.hanserwei.framework.common.util.JsonUtils;
import lombok.extern.slf4j.Slf4j;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Pointcut;
import org.aspectj.lang.reflect.MethodSignature;

import java.lang.reflect.Method;
import java.util.Arrays;
import java.util.function.Function;
import java.util.stream.Collectors;

/**
 * API操作日志切面
 *
 * @author hanser
 */
@Aspect
@Slf4j
public class ApiOperationLogAspect {

    /**
     * 定义切点：以自定义 @ApiOperationLog 注解为切点，凡是添加 @ApiOperationLog 的方法，都会执行环绕中的代码
     */
    @Pointcut("@annotation(com.hanserwei.framework.biz.operationlog.aspect.ApiOperationLog)")
    public void apiOperationLog() {}

    /**
     * 环绕通知：记录API操作日志
     *
     * @param joinPoint 连接点
     * @return 方法执行结果
     * @throws Throwable 方法执行异常
     */
    @Around("apiOperationLog()")
    public Object doAround(ProceedingJoinPoint joinPoint) throws Throwable {
        // 请求开始时间
        long startTime = System.currentTimeMillis();

        // 获取被请求的类和方法
        String className = joinPoint.getTarget().getClass().getSimpleName();
        String methodName = joinPoint.getSignature().getName();

        // 请求入参
        Object[] args = joinPoint.getArgs();
        // 入参转 JSON 字符串
        String argsJsonStr = Arrays.stream(args).map(toJsonStr()).collect(Collectors.joining(", "));

        // 功能描述信息
        String description = getApiOperationLogDescription(joinPoint);

        // 打印请求相关参数
        log.info("====== 请求开始: [{}], 入参: {}, 请求类: {}, 请求方法: {} =================================== ",
                description, argsJsonStr, className, methodName);

        // 执行切点方法
        Object result = joinPoint.proceed();

        // 执行耗时
        long executionTime = System.currentTimeMillis() - startTime;

        // 打印出参等相关信息
        log.info("====== 请求结束: [{}], 耗时: {}ms, 出参: {} =================================== ",
                description, executionTime, JsonUtils.toJsonString(result));

        return result;
    }

    /**
     * 获取注解的描述信息
     *
     * @param joinPoint 连接点
     * @return 注解描述信息
     */
    private String getApiOperationLogDescription(ProceedingJoinPoint joinPoint) {
        // 1. 从 ProceedingJoinPoint 获取 MethodSignature
        MethodSignature signature = (MethodSignature) joinPoint.getSignature();

        // 2. 使用 MethodSignature 获取当前被注解的 Method
        Method method = signature.getMethod();

        // 3. 从 Method 中提取 ApiOperationLog 注解
        ApiOperationLog apiOperationLog = method.getAnnotation(ApiOperationLog.class);

        // 4. 从 ApiOperationLog 注解中获取 description 属性
        return apiOperationLog.description();
    }

    /**
     * 转换为 JSON 字符串
     *
     * @return 转换函数
     */
    private Function<Object, String> toJsonStr() {
        return JsonUtils::toJsonString;
    }

}

5. starter 自动配置

接下来，就是自定义 starter 的重头戏 —— 自动配置。新建一个 /config 包，并创建日志切面自动配置类，如下图所示：

package com.hanserwei.framework.biz.operationlog.config;

import com.hanserwei.framework.biz.operationlog.aspect.ApiOperationLogAspect;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.context.annotation.Bean;

/**
 * @author hanser
 */
@AutoConfiguration
public class ApiOperationLogAutoConfiguration {

    @Bean
    public ApiOperationLogAspect apiOperationLogAspect() {
        return new ApiOperationLogAspect();
    }
}

这是一个自动配置类，用于配置 API 操作日志记录功能，并且通过 @Bean 注解的 apiOperationLogAspect() 方法来创建一个 ApiOperationLogAspect 实例，以实现注入到 Spring 容器中。

接着，在 /main 文件夹下，创建 /resources 包，再创建 /META-INF 文件夹，再在里面创建 /spring 文件夹 , 以及 org.springframework.boot.autoconfigure.AutoConfiguration.imports 文件，注意，这是自定义 starter 固定步骤，需要严格按照此格式来书写，如下图所示：

注意在创建多级目录的时候要使用 /而不是 .

imports 文件中内容如下，填写 ApiOperationLogAutoConfiguration 配置类的完整包路径：

com.hanserwei.framework.biz.operationlog.config.ApiOperationLogAutoConfiguration

至此，自定义 starter 步骤就完成了。

6. 统一版本控制

接下来，我们想在 hannote-auth 认证服务中使用刚刚封装好的 starter 组件。回到最外层的 pom.xml , 声明该组件依赖以及版本号：

7. 使用 starter

接着，编辑 hanserwei-auth 认证服务的 pom.xml , 添加日志切面 starter 的依赖, 代码如下：

若出现爆红问题，点击右侧 Reload 按钮，重新刷新一下 Maven 依赖。最后，为 /test 接口添加 @ApiOperationLog 日志切面注解：

package com.hanserwei.hannote.auth.controller;

import com.hanserwei.framework.biz.operationlog.aspect.ApiOperationLog;
import com.hanserwei.framework.common.response.Response;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author hanser
 */
@RestController
public class TestController {

    @GetMapping("/test")
    @ApiOperationLog
    public Response<String> test() {
        return Response.success("Hello, Hanserwei!");
    }
}

重启项目， 浏览器访问 localhost:8080/test 接口，自测一波，看看日志切面是否能够正常工作：

OK , 没有任何问题，自定义的日志切面 starter 工作良好！

8. 测试一下，切面打印出参中包含 Java 8 新日期 API

上面我们讲到，Jackson3已经支持 Java 8 新日志 API 问题。这块也需要单独测试一下：

创建一个 User 用户实体类，并添加两个字段，包含一个 LocalDateTime 日期字段，代码如下：

package com.hanserwei.hannote.auth.controller;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.time.LocalDateTime;

/**
 * @author hanser
 */
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class User {
    /**
     * 昵称
     */
    private String nickName;

    /**
     * 创建时间
     */
    private LocalDateTime createTime;
}

编辑 TestController 控制器，新增一个 /test2 接口，代码如下：

@GetMapping("/test2")
@ApiOperationLog(description = "测试接口2")
public Response<User> test2() {
    return Response.success(User.builder()
            .nickName("Hanserwei")
            .createTime(LocalDateTime.now())
            .build());
}

重启项目，浏览器访问: http://localhost:8080/test2 , 观察控制台日志，如下：

可以看到，即使出参对象中包含 Java 8 新日期 API 字段, 也是正常的，没有出现报异常情况。就是日期序列化格式不太友好，如上图所示。

9. 适配日期序列化格式

为了解决上述问题，我们需要手动指定 Jackson 日期的序列化和反序列化规则。在 hanserwei-common 通用模块中，新建包 /constant 全局常量包, 并创建 DateConstants 日期常量接口，代码如下：

代码如下：

package com.hanserwei.framework.common.constant;

/**
 * @author hanser
 */
public interface DateConstants {
    /**
     * 年-月-日 时：分：秒
     */
    String Y_M_D_H_M_S_FORMAT = "yyyy-MM-dd HH:mm:ss";
}

接着，编辑 JsonUtils 工具类，手动配置 LocalDateTime 日期格式化规则，注意，Jackson3的配置方法和 Jackson2的配置方式有点区别：

package com.hanserwei.framework.common.util;

import com.hanserwei.framework.common.constant.DateConstants;
import tools.jackson.databind.DeserializationFeature;
import tools.jackson.databind.SerializationFeature;
import tools.jackson.databind.ext.javatime.deser.LocalDateTimeDeserializer;
import tools.jackson.databind.ext.javatime.ser.LocalDateTimeSerializer;
import tools.jackson.databind.json.JsonMapper;
import tools.jackson.databind.module.SimpleModule;

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.TimeZone;

/**
 * JSON 工具类，提供对象与 JSON 字符串之间的转换功能
 *
 * @author hanser
 */
public class JsonUtils {

    /**
     * 初始化 Jackson 的 JsonMapper 实例
     */
    private static final JsonMapper JSON_MAPPER;


    static {
        // 创建日期时间格式化器，使用 yyyy-MM-dd HH:mm:ss 格式
        DateTimeFormatter dateTimeFormatter = DateTimeFormatter.ofPattern(DateConstants.Y_M_D_H_M_S_FORMAT);

        // 创建自定义模块，用于注册 LocalDateTime 的序列化和反序列化器
        SimpleModule customizeModule = new SimpleModule();
        // 注册 LocalDateTime 反序列化器，将 JSON 字符串转换为 LocalDateTime 对象
        customizeModule.addDeserializer(LocalDateTime.class, new LocalDateTimeDeserializer(dateTimeFormatter));
        // 注册 LocalDateTime 序列化器，将 LocalDateTime 对象转换为 JSON 字符串
        customizeModule.addSerializer(LocalDateTime.class, new LocalDateTimeSerializer(dateTimeFormatter));

        // 构建 JsonMapper 实例
        JSON_MAPPER = JsonMapper.builder()
                // 在反序列化时，忽略在 JSON 中存在但 Java 对象中不存在的属性，防止报错
                .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
                // 在序列化时，允许序列化空的 POJO 类（没有属性的类），防止报错
                .disable(SerializationFeature.FAIL_ON_EMPTY_BEANS)
                // 设置默认时区为东八区（北京时间）
                .defaultTimeZone(TimeZone.getTimeZone("GMT+8"))
                // 添加自定义模块
                .addModule(customizeModule)
                // 自动查找并添加所有可用的 Jackson 模块
                .findAndAddModules()
                .build();
    }

    /**
     * 将对象序列化为 JSON 字符串
     *
     * @param object 需要转换的对象
     * @return 转换后的 JSON 字符串
     */
    public static String toJsonString(Object object) {
        return JSON_MAPPER.writeValueAsString(object);
    }
}

再次重启项目，测试 /test2 接口，观察控制台日志，现在看到日期打印格式就友好多了~

10. 结语

本小节中，我们了解了什么是 Spring Boot Starter , 并自己动手实现了一个日志切面 starter 组件，后续创建新的服务时，只需添加该 starter 组件, 然后，为想要打印接口出入参的接口，添加 @ApiOperationLog 注解，即可快速使用上日志切面功能了，非常方便，有木有！

Spring Boot 4.x 整合 MyBatis-Plus

本小节中，我们来为后端服务整合数据库持久层框架 —— MyBatis-Plus ，实现对数据库的增删改查。

1. 什么是 MyBatis ？

MyBatis 是一个用 Java 编写的持久层框架，它简化了数据库交互的过程，将 SQL 语句与 Java 方法相映射，从而使得开发者能够更轻松地操作数据库。

MyBatis 的优点包括：

• 简化的 SQL 语句： MyBatis 允许开发者使用简单的 XML 文件或者注解来编写 SQL 语句，而不需要手动拼接 SQL 语句，大大简化了数据库操作的流程。
• 灵活性： MyBatis 提供了丰富的配置选项和灵活的映射方式，开发者可以根据需求自定义映射关系，适应各种复杂的业务场景。
• 与 SQL 的紧密结合： MyBatis 将 SQL 语句与 Java 代码紧密结合，开发者可以直观地理解代码的执行逻辑，同时也方便了 SQL 优化和调试。
• 良好的性能： MyBatis 通过预编译 SQL 语句和数据库连接池等机制，提升了数据库操作的性能，使得系统能够更高效地处理大量数据。
• 与现有项目的兼容性： MyBatis 不会对现有的项目结构和代码产生太大的影响，易于集成到已有的项目中，并且可以与其他框架（如 Spring）无缝整合，提高了开发效率。

总的来说，MyBatis 是一个功能强大且易于使用的持久层框架，适用于各种规模的项目，能够帮助开发者简化数据库操作，提高开发效率。

2. 什么是 MyBatis-Plus ？

简单来说，MyBatis-Plus (MP) 是 MyBatis 的一个增强工具。它在 MyBatis 的基础上只做增强不做改变，目的是简化开发、提高效率。

如果把 MyBatis 比作一把需要手动打磨的宝剑，MyBatis-Plus 就是给这把剑装上了“自动化刀架”和“倍镜”。

1. 无侵入与损耗小

MP 完全兼容 MyBatis，引入它不会影响你现有的 MyBatis 代码。它在启动时进行预处理，基本不影响运行性能。

2. 强大的 CRUD 操作

这是 MP 最受欢迎的功能。它内置了通用 Mapper 和 Service，仅通过少量配置即可实现单表的增、删、改、查。

• 以前（MyBatis）： 你需要手写 SQL 或使用逆向工程生成 XML 文件。
• 现在（MP）： 你的 Mapper 接口只需继承 BaseMapper<T>，一行代码不写就能拥有数十种基础查询方法。

3. 条件构造器 (Wrapper)

MP 提供了强大的条件构造器，允许你通过链式调用（Java 代码）来编写复杂的查询逻辑，而不需要在 XML 里拼接繁琐的 <if> 标签。

// 示例：查询年龄大于18且名字包含"张"的用户
userMapper.selectList(new QueryWrapper<User>()
    .gt("age", 18)
    .like("name", "张"));

4. 自动分页

内置分页插件，你只需要简单的配置，查询时传入一个 Page 对象，MP 就会自动帮你处理不同数据库（MySQL, Oracle, PostgreSQL 等）的分页语法差异。

5. 其他进阶功能

   • 逻辑删除： 只需加个注解，delete 语句会自动变成 update 状态字段。
   • 自动填充： 比如 create_time 和 update_time，可以设置在插入或更新时自动赋值，不需要手动 set。
   • 代码生成器： 快速生成 Entity、Mapper、Service、Controller 代码。

MyBatis-Plus 并不是要取代 MyBatis，而是为了让你从繁琐的单表重复劳动中解脱出来。

3. 整合 MyBatis-Plus

一切准备就绪之后，我们先在最外层的 pom文件里导入一下 MyBatis-plus有关的版本声明！

        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-bom</artifactId>
            <version>3.5.16</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>

接着，编辑 hanserwei-auth 服务的 pom.xml ， 引入相关的依赖：

        <!-- MySQL数据库驱动：用于连接MySQL数据库 -->
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <scope>runtime</scope>
        </dependency>

        <!-- MyBatis Plus启动器：用于简化MyBatis的配置和使用 -->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-spring-boot4-starter</artifactId>
        </dependency>

4. 项目多环境配置

为了区分不同的环境，Spring Boot项目可以有多个配置文件，如下图所示：

注意：也可以在这里在 /resources 目录下，新建一个 /config 配置文件夹，统一放置 applicaiton 多环境配置文件。

编辑 application.yml 父配置，内容如下:

spring:
  application:
    name: han-note-auth
  banner:
    location: banner.txt
  threads:
    virtual:
      enabled: true
  # 默认激活 dev 本地开发环境
  profiles:
    active: dev
server:
  port: 8080

编辑 application-dev.yml 本地开发环境配置文件，配置本地的数据库链接相关信息，如下：

TIP : 数据库连接池暂时不做配置，直接用默认的，后续单独开一小节讲这一块，届时我会把分库分表也一并引入进来！

5. 新建相关包

编辑 hannote-auth 服务，创建以下文件夹：

• /domain/dataobject : 用于统一放置 DO 类，对应数据库表；
• /domain/mapper : 用于放置 Mapper 接口；
• /resources/mapper : 用于放置 MyBatis XML 文件；

6. 配置 MyBatis-Plus

接着，在 Application 启动类的头部，添加 @MapperScan 注解，值填写 mapper 接口所处的包路径，如下图所示：

package com.hanserwei.hannote.auth;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * @author hanser
 */
@SpringBootApplication
@MapperScan("com.hanserwei.hannote.auth.domain.mapper")
public class HannoteAuthApplication {
    static void main() {
        SpringApplication.run(HannoteAuthApplication.class);
    }
}

另外，编辑 application.yml , 为 MyBatis-plus 配置相关配置：

mybatis-plus:
  # MyBatis xml 配置文件路径
  mapper-locations: classpath:/mapper/**/*.xml
  # 实体类包路径
  type-aliases-package: com.hannote.auth.domain.entity
  # MyBatis 原生配置
  configuration:
    # 是否开启自动驼峰命名规则映射
    map-underscore-to-camel-case: true
    # 开启 MyBatis 二级缓存，默认为 true
    cache-enabled: false
    # 日志实现
    log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl

解释：classpath: 表示 /resources 目录; /mapper/**/*.xml 表示在 mapper 目录及其所有子目录下查找以 .xml 结尾的文件。这种表达式允许你指定一个包含通配符的路径模式，以方便地匹配多个文件。

7. 配置 SQL 日志打印

开发中为了方便调试，想要打印实际执行的 SQL 语句, 可编辑 application-dev.yml 配置文件，配置 mapper 接口所在包的日志级别为 debug , 即可实现此功能：

logging:
  level:
    com.hanserwei.hannote.auth.domain.mapper: debug

搭建微服务项目骨架：通过 Maven 多模块方式

相关概念

在搭建项目之前，先了解一下相关概念。

什么是单体架构

单体架构是一种传统的软件架构模式，通常将整个应用作为一个单一的、独立部署的单元来开发、构建和部署。在单体架构中，所有的功能模块和业务逻辑都打包在同一个应用程序中，比如 weblog 项目，最终是打包成一个 Jar 包来部署。这包括业务逻辑、数据访问和数据存储等。整个应用程序通常部署在一个应用服务器上，与外部系统通过接口进行通信。

单体架构开发简单，部署方便，适合流量不大的应用。但随着应用规模的增长，往往会遇到可扩展性差、维护困难、部署风险高等问题。

微服务架构是一种将应用程序拆分为多个小型、自治的服务的架构模式。可以通过上图本项目的架构图来理解。每个服务都专注于实现一个特定的业务功能，并通过轻量级的通信机制（如 HTTP 或 RPC）与其他服务进行通信。微服务架构将整个应用程序拆分成多个松耦合的服务单元，每个服务单元都可以独立开发、测试、部署和扩展。微服务架构有助于提高灵活性、可扩展性和可维护性，适合大流量型应用。但也增加了部署和运维的复杂性，需要考虑服务间通信、服务注册与发现、服务监控等方面的问题。

Spring Cloud

Spring Cloud 是基于 Spring Boot 的微服务架构开发工具包，提供了一系列开发工具和库，用于快速构建、部署和管理分布式系统中的微服务应用。Spring Cloud提供了诸如服务发现、服务注册、负载均衡、断路器、配置管理、消息总线等功能，帮助开发人员解决了微服务架构中的常见问题，简化了微服务应用的开发和部署流程。

Spring Cloud Alibaba

Spring Cloud Alibaba 是 Spring Cloud 生态的一部分，提供了一系列基于阿里巴巴开源产品的分布式解决方案和工具，用于构建和管理基于 Spring Cloud 的微服务应用。Spring Cloud Alibaba 集成了阿里巴巴开源的服务，如 Nacos（服务注册与发现）、Sentinel（流量控制和熔断降级）、Dubbo（远程服务调用）、RocketMQ（消息队列）等，为开发人员提供了一站式的微服务解决方案。Spring Cloud Alibaba 与 Spring Cloud 兼容，并且提供了额外的功能和工具，帮助开发人员更轻松地构建、部署和管理微服务应用。

多模块项目

什么是多模块项目？

多模块项目是项目构建中的概念。拿 Maven 来说，多模块项目（Multi-Module Project）是其一个重要特性，它允许我们在一个项目中管理多个子模块。

在一个 Maven 多模块项目中，每个模块都是一个独立的项目，拥有自己的 POM 文件（Project Object Model，项目对象模型）。这些模块可以互相依赖，也可以被其他项目依赖。但是，所有的模块都会被统一管理，它们共享同一套构建系统和依赖管理。

Maven 多模块项目的结构大概是下面这样的：

my-app/  (父项目)
  |- pom.xml
  |- my-module1/  (子模块1)
  |    |- pom.xml
  |- my-module2/  (子模块2)
       |- pom.xml
  | ... (实际企业级项目中，会分非常多的模块)   

在这个例子中，my-app 是父项目，my-module1 和 my-module2 是它的子模块。每个模块都有自己的 pom.xml 文件。

为什么需要多模块项目？

主要有以下几个原因：

• 代码组织：在大型项目中，我们经常需要把代码分成多个模块，以便更好地组织代码。每个模块可以聚焦于一个特定的功能或领域，这样可以提高代码的可读性和可维护性。
• 依赖管理：Maven 多模块项目可以帮助我们更好地管理项目的依赖。在父项目的 POM 文件中，我们可以定义所有模块共享的依赖，这样可以避免重复的依赖定义，也方便我们管理和升级依赖。
• 构建和部署：Maven 多模块项目的另一个优点是它可以统一管理项目的构建和部署。我们只需要在父项目中执行 Maven 命令，就可以对所有模块进行构建和部署。这大大简化了开发者的工作。

IDEA 搭建微服务多模块工程骨架

创建父模块

打开 IDEA, 这里我使用的是 2025 版本，即最新的IDEA不同版本的IDEA操作类似。依次点击左上角菜单 File | New | Project , 开始创建项目：

解释一下标注的地方:

• ①：选择 Maven Archetype 来创建一个 Maven 项目;
• ②：项目名称，hannote；
• ③：项目创建的位置；
• ④：项目使用的 JDK 版本，本项目使用的是 JDK 25 ,因为有虚拟线程这一大杀器；
• ⑤：IDEA 需要知道 Maven Archetype Catalog 的位置，以便从中获取可用的 Archetype 列表。这个 Catalog 文件通常包含了 Maven 官方仓库或其他远程仓库中可用的 Archetype 信息。选择 Internal 即可。
• ⑥：通过使用 Archetype，你可以基于已有的项目模板创建一个新项目。这里选择 maven-archetype-quickstart。
• ⑦：填写 Group 组织名称，通常为公司域名倒写，如 com.hanserwei；
• ⑧：项目的唯一标识符；
• ⑨：项目版本号，默认就行；

创建完毕之后，第一步删除掉src目录：

父模块仅需要保留一个 pom.xml 文件，用于统一管理依赖、插件等。如下图所示：

截至目前：2026年2月2日，Spring Cloud Alibaba 2025.1.0的正式版还没发布，我目前先使用快照版本，正式版据issue说，一个星期内发布！

  <servers>
    <server>
      <id>github</id>
      <username>${env.GITHUB_ACTOR}</username>
      <password>${env.GITHUB_TOKEN}</password>
    </server>
  </servers>

创建 GitHub Token 地址：https://github.com/settings/tokens。然后替换掉上面的两个为你自己的token和名字。

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/alibaba/spring-cloud-alibaba</url>
        <releases>
            <enabled>false</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

以下是我的settings.xml文件：

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0 https://maven.apache.org/xsd/settings-1.2.0.xsd">

  <servers>
    <server>
      <id>github</id>
      <username>替换为你自己的</username>
      <password>替换为你自己的</password>
    </server>
  </servers>

  <mirrors>
    <mirror>
      <id>maven-default-http-blocker</id>
      <mirrorOf>external:http:*</mirrorOf>
      <name>Pseudo repository to mirror external repositories initially using HTTP.</name>
      <url>http://0.0.0.0/</url>
      <blocked>true</blocked>
    </mirror>
  </mirrors>

  <profiles>
    <profile>
      <id>github-repo</id>
      <repositories>
        <repository>
          <id>github</id>
          <url>https://maven.pkg.github.com/alibaba/spring-cloud-alibaba</url>
          <releases>
            <enabled>false</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
      </repositories>
    </profile>
  </profiles>

  <activeProfiles>
    <activeProfile>github-repo</activeProfile>
  </activeProfiles>
</settings>

然后修改顶层的pom文件如下所示：

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <!-- Maven 项目对象模型版本 -->
    <modelVersion>4.0.0</modelVersion>

    <!-- 项目坐标信息 -->
    <groupId>com.hanserwei</groupId>
    <artifactId>hannote</artifactId>
    <version>${revision}</version>
    <name>${project.artifactId}</name>
    <description>小憨书（仿小红书），基于 Spring Cloud Alibaba 2025.1.0 微服务架构</description>

    <!-- 打包方式：pom 表示这是一个父项目 -->
    <packaging>pom</packaging>

    <!-- 子模块列表 -->
    <modules>
    </modules>

    <!-- 项目属性配置 -->
    <properties>
        <!-- 项目版本号 -->
        <revision>0.0.1-SNAPSHOT</revision>

        <!-- Java 版本配置 -->
        <java.version>25</java.version>
        <maven.compiler.source>${java.version}</maven.compiler.source>
        <maven.compiler.target>${java.version}</maven.compiler.target>

        <!-- 项目编码配置 -->
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

        <!-- Spring Boot 版本 -->
        <spring-boot.version>4.0.2</spring-boot.version>

        <!-- Spring Cloud 版本 -->
        <spring-cloud.version>2025.1.1</spring-cloud.version>

        <!-- Spring Cloud Alibaba 版本 -->
        <spring-cloud-alibaba.version>2025.1.0.0-SNAPSHOT</spring-cloud-alibaba.version>

        <!-- Maven 编译插件版本 -->
        <maven-compiler-plugin.version>3.11.0</maven-compiler-plugin.version>

        <!-- Lombok 版本 -->
        <lombok.version>1.18.38</lombok.version>
    </properties>

    <!-- 依赖管理：统一管理项目依赖版本 -->
    <dependencyManagement>
        <dependencies>
            <!-- Spring Boot 依赖 -->
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring-boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>

            <!-- Spring Cloud 依赖 -->
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>

            <!-- Spring Cloud Alibaba 依赖 -->
            <dependency>
                <groupId>com.alibaba.cloud</groupId>
                <artifactId>spring-cloud-alibaba-dependencies</artifactId>
                <version>${spring-cloud-alibaba.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>

            <!-- Lombok 依赖：用于简化 Java 代码 -->
            <dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>${lombok.version}</version>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <!-- 构建配置 -->
    <build>
        <!-- 插件管理：统一管理构建插件 -->
        <pluginManagement>
            <plugins>
                <!-- Spring Boot Maven 插件：用于打包 Spring Boot 应用 -->
                <plugin>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-maven-plugin</artifactId>
                    <version>${spring-boot.version}</version>
                    <executions>
                        <execution>
                            <id>repackage</id>
                            <goals>
                                <!-- 重新打包为可执行的 jar 文件 -->
                                <goal>repackage</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>

                <!-- Maven 编译插件：配置 Java 编译参数 -->
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <version>${maven-compiler-plugin.version}</version>
                    <configuration>
                        <!-- 源码版本 -->
                        <source>${java.version}</source>
                        <!-- 目标版本 -->
                        <target>${java.version}</target>
                        <!-- 编码格式 -->
                        <encoding>${project.build.sourceEncoding}</encoding>
                        <!-- 注解处理器路径：配置 Lombok 注解处理器 -->
                        <annotationProcessorPaths>
                            <path>
                                <groupId>org.projectlombok</groupId>
                                <artifactId>lombok</artifactId>
                                <version>${lombok.version}</version>
                            </path>
                        </annotationProcessorPaths>
                    </configuration>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>
</project>

非常完美，到此为止，我们已经把多模块的maven项目的骨架搭建起来了，现在我们来引入第一个模块，用户认证微服务。

在父项目右键 | New | Module... ， 来创建一个子模块：

我这里使用maven骨架来创建Spring Boot项目，这样我可以按需导入锁需要的依赖，这样整个工程看起来要更加清爽一些！如果你使用Spring Boot来创建，当然也是可以的。

auth服务的pom文件如下：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- 父项目配置 -->
    <parent>
        <!-- 父项目的组织标识 -->
        <groupId>com.hanserwei</groupId>
        <!-- 父项目的唯一标识 -->
        <artifactId>hannote</artifactId>
        <!-- 父项目版本号，使用变量${revision}便于统一管理 -->
        <version>${revision}</version>
    </parent>

    <!-- 当前模块的唯一标识 -->
    <artifactId>hannote-auth</artifactId>
    <!-- 打包方式：jar包 -->
    <packaging>jar</packaging>

    <!-- 项目名称，使用Maven内置变量 -->
    <name>${project.artifactId}</name>
    <!-- 项目描述信息 -->
    <description>小憨书：认证服务（负责处理用户登录、注册、账号注销等）</description>

    <!-- 项目属性配置 -->
    <properties>
        <!-- 项目源代码和编译输出使用UTF-8编码 -->
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <!-- 项目依赖配置 -->
    <dependencies>
        <!-- Spring Boot Web启动器：用于构建Web应用，包含RESTful、Spring MVC等功能 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- Spring Boot测试启动器：用于单元测试和集成测试 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <!-- 作用域：仅在测试阶段使用，不会打包到最终的jar中 -->
            <scope>test</scope>
        </dependency>
    </dependencies>

    <!-- 项目构建配置 -->
    <build>
        <!-- 插件配置 -->
        <plugins>
            <!-- Spring Boot Maven插件：用于将应用打包成可执行的jar包 -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

完善一下启动类：

package com.hanserwei.hannote.auth;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * @author hanser
 */
@SpringBootApplication
public class HannoteAuthApplication {
    static void main() {
        SpringApplication.run(HannoteAuthApplication.class);
    }
}

添加一下配置文件：

测试打包是否正常

接下来，我们测试一下多模块项目打包是否正常。对右侧栏中的父项目进行 clean package , 观察控制台日志，确认一下项目打包是否正常：

启动认证服务

打包没问题后，再来测试一下认证服务是否能够正常运行。点击 XiaohashuAuthApplication 启动类的 main 方法左侧的运行按钮，来启动服务：

若看到控制台输出 Tomcat started on port(s): 8080 信息，则表示服务成功运行在了 8080 端口上。打开浏览器，访问地址 localhost:8080 ，即可看到 Spring Boot 项目的页面提示信息了，如下图所示：

看到这个就说明我们已经成功了。

结语

本小结中，我们了解了什么是单体架构、微服务架构，以及 Spring Cloud 、Spring Cloud Alibaba 之间的关系。然后，上手搭建了一个 Maven 多模块项目，并引入了 Spring Cloud Alibaba 2025.1.0 依赖， 还创建了一个子模块 —— 认证服务，并成功运行了起来。但是，目前还只是简单的多模块的项目，还没实际使用到微服务，后续小节中，将一点一点引入 Spring Cloud Alibaba 相关组件，将整个微服务体系渐进式的搭建起来。

扩展

众所周知，Java21开始引入了一个叫做虚拟虚拟线程的东西，这个玩意可以说是Java跨时代的东西，那么我们Spring Boot4对它支持如何呢，答案是支持非常的完美！现在我们来看看如何在Spring Boot4中开启虚拟线程的功能！

写一个测试接口来看一下是否生效：

package com.hanserwei.hannote.auth.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author hanser
 */
@RestController
public class ThreadCheckController {

    @GetMapping("/check")
    public String check() {
        Thread thread = Thread.currentThread();
        return "Current Thread: " + thread.toString();
    }
}

访问这个接口：

完美，可以看到tomcat已经由原来的平台线程池变成了虚拟线程。完美的蜕变！如果上述方式不起作用，可以尝试配置类的方式：

package com.hanserwei.hannote.auth.config;

import org.springframework.boot.tomcat.TomcatProtocolHandlerCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.concurrent.Executors;

/**
 * @author hanser
 */
@Configuration
public class TomcatConfiguration {


    /**
     * 配置Tomcat协议处理器使用虚拟线程执行器
     * 虚拟线程是Java 21引入的轻量级线程，可以大幅提升并发处理能力
     * 
     * @return Tomcat协议处理器自定义器
     */
    @Bean
    public TomcatProtocolHandlerCustomizer<?> protocolHandlerVirtualThreadExecutorCustomizer() {
        return protocolHandler -> {
            // 为Tomcat的协议处理器设置虚拟线程执行器，每个任务创建一个新的虚拟线程
            protocolHandler.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
        };
    }
}

这样也可以达到同样的效果！

当然，虚拟线程的作用远不止于此，在后续的章节我会给大家带来更多的它的用法。

Spring Cloud Alibaba 小憨书（仿小红书）微服务项目实战：专栏介绍

项目介绍

先来看一下小红书官网的对自己的介绍：

小红书是一个年轻生活方式分享平台，由毛文超和瞿芳创立于2013年。

截止2019年1月，小红书用户数超过2亿，其中90后和95后是最活跃的用户群体。

在小红书，用户通过短视频、图文等形式记录生活的点滴。

社区每天产生数十亿次的笔记曝光，内容覆盖时尚、护肤、彩妆、美食、旅行、影视、读书、健身等各个生活方式领域。

架构图

本项目不是单体架构，而是采用企业主流的 Spring Cloud Alibaba 技术栈，微服务分布式项目搞起，并且技术我一律使用最新的技术，目的就是为了让大家感受一下目前最先进的Java生态是如何的！整体架构图如下：

PS : 本专栏主要讲解后端部分。前端工程后续看情况，我大概率也是Vibe Coding，需要等后端相关接口开发完成后。（uni-app 暂不做实现，等后面再说）

特别注意：该项目部分代码借鉴了知识星期博主犬小哈。该博主教学十分细致，建议有条件的伙伴支持一波。

Java21的虚拟线程真的完美吗？

锁不是不在了，只是没人能去拿。你看着它，等着它，却永远不能碰到它。这就是虚拟线程的浪漫。

我最近的项目一律使用的 Java 21，其中一个重要原因是看中了 虚拟线程（Virtual Threads） 这一新特性。Java 21 将虚拟线程从预览阶段带入正式版，提供了一种更轻量的线程实现。据官方描述，虚拟线程是“极轻量的线程，实现高吞吐并发应用所需的编写、维护和监控成本都大幅降低”，其关键在于当发生阻塞时线程可以自动挂起并让出底层操作系统线程去执行其它任务。利用虚拟线程，我们希望既简化并发编程模型（避免繁琐的回调地狱或 Reactor 流水线），又提升系统在高并发场景下的吞吐性能。

我在重构我的一个Task Managment System基于的是最新的Spring Boot3，（写这个文章的时候，Spring Boot 4.0.1已经在两周前发布了）。该服务使用的是内嵌的Tomcat提供REST风格的接口。在Java21环境下，我手动在配置文件中开启了虚拟线程的支持，随后我直接对系统进行了一波高并发压力的测试。本以为可以看到一条完美的直线，可惜理想和现实汪往往差距很远！在有一次测试中，我发现系统吞吐量突然归零的诡异问题。

问题复现

当时压测跑着跑着，系统突然就“停跳”了。最诡异的是，应用既没报错也没宕机，但吞吐量直接掉到了零，整个 Tomcat 就像被点穴了一样，旧请求卡死不动，新请求死活进不来。

翻看后台，连一条异常日志都刷不出来，安静得让人发毛。但一查监控，我发现 CLOSE_WAIT 的连接数正疯狂往上涨。这意味着客户端早就等不及断开了，可服务器这边还死死拽着连接不撒手，根本腾不出手来去处理新任务。简单说，系统还没彻底“断气”，但已经成了无法对外服务的“植物人”状态。

看着监控面板上这两根走势极其离谱的曲线，我当时心里就凉了大半截。

大约到晚上 23:30 那会儿，本来跑得稳稳的吞吐量（就是那根蓝线）跟蹦极一样，直接来了个 90 度大跳水，瞬间躺平变 0 了。 与此同时，旁边的 CLOSE_WAIT 连接数（那根棕线）却像坐了火箭一样疯涨，把右侧纵轴都快撑爆了。

这画面太诡异了：系统还没挂，但已经完全“石化”了，所有请求都被死死卡在喉咙里出不来。看着这满屏的 CLOSE_WAIT，我知道系统肯定是卡在了某个环节，导致连接断不开也挪不动。没辙，只能硬着头皮赶紧上线开搞，看看这黑盒子里到底藏了什么鬼。

排查与诊断

既然服务没挂但又不理人，我的第一反应就是：坏了，肯定是有线程被锁死了，或者是哪里在大面积阻塞。

我二话没说，反手就打了一个 jstack 想看看线程栈。可等我把 Dump 文件打开一看，整个人都懵了——“一片风平浪静”。所有的工作线程都老老实实地待在空闲状态，既没有死锁报错，也没有哪里在疯狂竞争资源。看起来 JVM 就像是在优雅地“空转”，好像完全没活干一样。

那种感觉特别无力，就像你明明看到病人已经快不行了，但心电图居然显示一切正常。我当时就在那儿犯嘀咕：难不成这系统还学会“隐身”了？

冷静下来反复推敲，我才猛地拍了一下大腿：坏了，这项目可是开了虚拟线程（Virtual Threads）的！

这时候我才反应过来，传统的 jstack 工具根本抓不到虚拟线程的踪迹。在它眼里，那些真正在跑业务、被卡住的虚拟线程全都是“透明”的，我看到的那些空闲线程不过是承载它们的“搬运工”而已。

发现了这个盲区，我赶紧换了招式，改用 jcmd Thread.dump_to_file。这命令才是专门对付虚拟线程的“照妖镜”，能把那些藏在暗处的调用栈全部揪出来。顺带手，我也把堆内存（Heap Dump）给导了出来，双管齐下。

手里攥着这份“完整版”的数据，我深吸了一口气：行了，这回我看你往哪儿躲。

深入分析

首先，新的线程Dump里揭示了一个耐人寻味的现象：存在成千上百个所谓“空白”的虚拟线程，它们被创建出来后从未真正执行过任何任务，因此没有任何堆栈信息。这些虚拟线程对象大量堆积，其数量和系统中 CLOSE_WAIT 连接的数量惊人地接近。也就是说，每一个未曾运行的虚拟线程，很可能对应着一个悬而未决的 socket 连接。这暗示问题出在虚拟线程被创建后没有得到调度执行，从而请求卡住、连接未关闭。

为什么虚拟线程全“集体罢工”了？

要搞清楚这背后的鬼天气，得先聊聊虚拟线程的“潜规则”。

大家都知道，虚拟线程不是真的操作系统线程，它更像是一堆“小零件”，由 JVM 的调度器（Fork-Join Pool）负责把它们安装到几个真正的 载体线程（Carrier Thread） 上去跑。在我的 Spring Boot 应用里，开启虚拟线程后，Tomcat 确实变猛了——来一个请求就造一个虚拟线程。按理说，虚拟线程随勾随用，遇到阻塞就该自己“闪开”，把底下的载体线程让给别人。

可理想很丰满，现实直接给我开了个大玩笑。

当我翻开那份完整的 jcmd Dump 文件时，真相简直让我大跌眼镜：我的载体线程被“绑架”了！

虽然我用的是虚拟线程，但在代码的某个角落，有人用了 synchronized 同步块。JDK 有个著名的坑：如果虚拟线程在 synchronized 块里卡住了，它就不会“礼让”出底下的载体线程，而是会死死地“钉”在上面。 这种现象官方叫“线程固定（Pinning）”。

更倒霉的是，我的服务器是 4 核的，默认也就 4 个载体线程。Dump 显示，正好有 4 个虚拟线程在竞争同一把锁时被 Pin 住了。这就好比一共就 4 个工位，被 4 个人占着位置干等，剩下的成千上万个虚拟线程只能在外面排队。 Tomcat 还在不断地接新客、造新线程，但这些线程连个落脚的工位都没有，只能在队列里“活活饿死”，直到客户端等不及把连接断了，留下满地的 CLOSE_WAIT。

到底谁拿着那把锁？

最让我头大的是，Java 21 的 jcmd Dump 有个硬伤：它不标注锁到底在谁手里。 我只看到一堆线程在排队：

• 4 个被 Pin 住的虚拟线程：霸占了所有 CPU 资源（载体线程）。
• 编号为 #42 的虚拟线程：虽然也在排队，但它还没抢到工位，正处于挂起状态。
• 一个普通平台线程（#7）：这货是负责后台日志异步刷新的。

这个 #7 线程的行为最诡异。它之前拿着锁去执行了一个 awaitNanos()（等待队列刷新），按理说等完了应该重新拿回锁继续干活。可当时的情况是：它想回也回不来了。

为了破案，我不得不祭出 Eclipse MAT 去翻堆内存 Dump，直接查锁对象的底层状态。

这一查，更有意思的事情发生了：锁其实是空的！ 内存显示锁的 state 是 0，exclusiveOwnerThread 也是 null。也就是说，压根没人占着锁！而排在队列最前面的正是那个挂起的虚拟线程 #42。

按逻辑，#42 已经被唤醒准备去拿锁了，但问题就在这里：#42 要想去拿锁，它得先被调度到一个载体线程上运行。可现在所有的载体线程都被那 4 个 Pin 住的倒霉蛋给占满了！

破案了：这成了一个死循环。 #42 等着载体线程去拿锁，而载体线程被另外几个等锁的家伙死死占着不放（因为他们被 synchronized 固定住了）。大家谁也别想动，系统就这么在沉默中彻底“石化”了。

这一通分析下来，我总算抓住了这个“幕后黑手”。

说实话，理论上锁从释放到被下一个线程接手，也就那么一瞬间的事。可偏偏在那个节骨眼上，事情卡在了一个极度尴尬的闭环里：线程 #42 虽然收到了“锁已释放”的信号，但因为它是个虚拟线程，它得先找个“工位”（载体线程）坐下来才能去伸手拿锁。

可这时候，全公司仅有的 4 个工位，全被那 4 个卡在 synchronized 里的兄弟给占死了。这 4 位仁兄也在等锁释放，好赶紧干完活儿走人腾位置。

这就是最诡异的地方：锁是空的，没人拿；想拿锁的人（#42）没位子坐，动不了；占着位子的人（那 4 个被 Pin 住的线程）又在等锁。

大家大眼瞪小眼，谁也动弹不得。这哪是普通的死锁啊？这简直是**“一把空锁 + 四个坑位”**诱发的另类死锁。平时我们防着两个锁互相等，这次倒好，锁在等线程，线程在等锁，活生生把系统憋成了“植物人”。

解决措施：给虚拟线程“松绑”

既然找到了症结，剩下的就是动刀子了。既然 synchronized 会把虚拟线程钉死在载体线程上，那我就得让它“解绑”。

我的方案其实很简单，但很管用：

1. 全面“拆迁” synchronized：我把代码里所有涉及长时间阻塞、I/O 操作或者等待条件的 synchronized 块全部铲掉。
2. 换上 ReentrantLock：改用 java.util.concurrent.Lock 系列的显式锁。
   • 为什么这么做？ 因为 ReentrantLock 底层用的是 LockSupport 挂起机制，它对虚拟线程非常友好。当虚拟线程在等待 ReentrantLock 时，它会很自觉地把底下的载体线程让出来，绝不“占着茅坑不拉屎”。
3. 优化临界区：确保所有可能磨叽的调用（比如网络请求、休眠等）都尽量挪到锁范围之外。

重构完代码重新部署后，我心里其实也有点打鼓。但随后的压测数据说明了一切：那根代表吞吐量的蓝线再也没有“蹦极”过，CLOSE_WAIT 也不再乱窜。 这次经历也算给我提了个醒：虚拟线程虽然是个好东西，但要是带着旧时代的 synchronized 思维去玩，它真的会分分钟教你做人。

反思与展望

这次压测翻车也算是给我上了一课：Java 21 的虚拟线程虽然香，但它和老牌的 synchronized 锁之间确实存在“先天性八字不合”。

虚拟线程的设计初衷是让我们能用写同步代码的方式，跑出异步的高性能，但这玩意儿就像一把双刃剑——如果你还没搞清楚什么是 Pinning（线程固定） 就盲目上线，它能让系统陷入比以前更隐蔽、更难排查的死锁泥潭。

不过，大家也别因为这一个坑就对虚拟线程失去信心。作为一项新技术，它的生态确实还在“打补丁”的过程中。我们在享受它带来的高并发红利时，确实得对现阶段的局限性保持警惕，老老实实按照官方建议把那些老旧的锁机制改一改。

往长远了看，这个锅终究得 JVM 自己来背。好消息是，社区已经意识到了这个问题，并开始在底层动手术了。

据说即将到来的 Java 24（通过 JEP 491）将彻底重构虚拟线程对同步锁的处理机制。到那时候，就算虚拟线程进了 synchronized 块被卡住，它也能像处理其他阻塞一样，大大方方地把底下的载体线程释放出来。这意味着，像我们这次遇到的这种“另类死锁”将从底层被彻底杜绝。

虚拟线程的完全体依然值得期待。但在那一天到来之前，答应我，先把代码里的 synchronized 搜一搜，能换的就先换了吧！

附录：

示例代码：

import java.time.Duration;
import java.util.concurrent.Executors;

public class VirtualThreadPinningDemo {
    // 一个共享资源，我们将使用 synchronized 来保护它
    private static final Object sharedLock = new Object();

    public static void main(String[] args) {
        // 使用虚拟线程执行器创建大量虚拟线程
        try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
            for (int i = 0; i < 100; i++) {
                int taskId = i;
                executor.submit(() -> performTask(taskId));
            }
        }
        System.out.println("All tasks completed.");
    }

    private static void performTask(int id) {
        System.out.printf("Task %d started on thread: %s%n", id, Thread.currentThread());

        // 情况1：在 synchronized 块内进行阻塞操作 -> 会导致 PINNED
        synchronized (sharedLock) {
            System.out.printf("Task %d acquired lock. Thread: %s%n", id, Thread.currentThread());
            try {
                // 模拟一个阻塞操作，比如睡眠或I/O
                // 在 synchronized 块内睡眠，虚拟线程无法被卸载，平台线程被占用！
                Thread.sleep(Duration.ofSeconds(2));
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
            System.out.printf("Task %d released lock.%n", id);
        }
        System.out.printf("Task %d finished.%n", id);
    }
}

Task 0 started on thread: VirtualThread[#30]/runnable@ForkJoinPool-1-worker-1
Task 0 acquired lock. Thread: VirtualThread[#30]/runnable@ForkJoinPool-1-worker-1
Task 1 started on thread: VirtualThread[#32]/runnable@ForkJoinPool-1-worker-10
Task 4 started on thread: VirtualThread[#35]/runnable@ForkJoinPool-1-worker-9
Task 5 started on thread: VirtualThread[#36]/runnable@ForkJoinPool-1-worker-5
Task 6 started on thread: VirtualThread[#37]/runnable@ForkJoinPool-1-worker-6
Task 7 started on thread: VirtualThread[#38]/runnable@ForkJoinPool-1-worker-8
Task 2 started on thread: VirtualThread[#33]/runnable@ForkJoinPool-1-worker-3
Task 8 started on thread: VirtualThread[#39]/runnable@ForkJoinPool-1-worker-7
Task 9 started on thread: VirtualThread[#40]/runnable@ForkJoinPool-1-worker-2
Task 10 started on thread: VirtualThread[#41]/runnable@ForkJoinPool-1-worker-4
Task 11 started on thread: VirtualThread[#42]/runnable@ForkJoinPool-1-worker-11
Task 12 started on thread: VirtualThread[#43]/runnable@ForkJoinPool-1-worker-13
Task 14 started on thread: VirtualThread[#45]/runnable@ForkJoinPool-1-worker-14
Task 13 started on thread: VirtualThread[#44]/runnable@ForkJoinPool-1-worker-12
Task 15 started on thread: VirtualThread[#46]/runnable@ForkJoinPool-1-worker-15
Task 16 started on thread: VirtualThread[#47]/runnable@ForkJoinPool-1-worker-16
Task 0 released lock.
Task 0 finished.
Task 17 started on thread: VirtualThread[#48]/runnable@ForkJoinPool-1-worker-1
这里就卡住不向下走了

但是同样的代码，在JDK 25下，运行正常：

Task 2 started on thread: VirtualThread[#42]/runnable@ForkJoinPool-1-worker-3
Task 2 acquired lock. Thread: VirtualThread[#42]/runnable@ForkJoinPool-1-worker-3
Task 0 started on thread: VirtualThread[#37]/runnable@ForkJoinPool-1-worker-6
Task 3 started on thread: VirtualThread[#45]/runnable@ForkJoinPool-1-worker-6
Task 1 started on thread: VirtualThread[#39]/runnable@ForkJoinPool-1-worker-6
Task 4 started on thread: VirtualThread[#47]/runnable@ForkJoinPool-1-worker-6
Task 5 started on thread: VirtualThread[#48]/runnable@ForkJoinPool-1-worker-6
Task 7 started on thread: VirtualThread[#50]/runnable@ForkJoinPool-1-worker-6
Task 8 started on thread: VirtualThread[#53]/runnable@ForkJoinPool-1-worker-6
Task 9 started on thread: VirtualThread[#54]/runnable@ForkJoinPool-1-worker-6
Task 10 started on thread: VirtualThread[#55]/runnable@ForkJoinPool-1-worker-6
Task 11 started on thread: VirtualThread[#56]/runnable@ForkJoinPool-1-worker-6
Task 12 started on thread: VirtualThread[#57]/runnable@ForkJoinPool-1-worker-6
Task 13 started on thread: VirtualThread[#58]/runnable@ForkJoinPool-1-worker-6
Task 15 started on thread: VirtualThread[#60]/runnable@ForkJoinPool-1-worker-6
Task 16 started on thread: VirtualThread[#61]/runnable@ForkJoinPool-1-worker-6
Task 14 started on thread: VirtualThread[#59]/runnable@ForkJoinPool-1-worker-6
Task 17 started on thread: VirtualThread[#62]/runnable@ForkJoinPool-1-worker-6
Task 19 started on thread: VirtualThread[#64]/runnable@ForkJoinPool-1-worker-6
Task 18 started on thread: VirtualThread[#63]/runnable@ForkJoinPool-1-worker-6
Task 6 started on thread: VirtualThread[#49]/runnable@ForkJoinPool-1-worker-6
Task 21 started on thread: VirtualThread[#67]/runnable@ForkJoinPool-1-worker-6
Task 20 started on thread: VirtualThread[#66]/runnable@ForkJoinPool-1-worker-6
Task 22 started on thread: VirtualThread[#68]/runnable@ForkJoinPool-1-worker-6
Task 23 started on thread: VirtualThread[#69]/runnable@ForkJoinPool-1-worker-6
Task 24 started on thread: VirtualThread[#70]/runnable@ForkJoinPool-1-worker-6
Task 26 started on thread: VirtualThread[#72]/runnable@ForkJoinPool-1-worker-6
Task 25 started on thread: VirtualThread[#71]/runnable@ForkJoinPool-1-worker-6
Task 27 started on thread: VirtualThread[#73]/runnable@ForkJoinPool-1-worker-6
Task 28 started on thread: VirtualThread[#74]/runnable@ForkJoinPool-1-worker-3
Task 31 started on thread: VirtualThread[#77]/runnable@ForkJoinPool-1-worker-7
Task 30 started on thread: VirtualThread[#76]/runnable@ForkJoinPool-1-worker-7
Task 32 started on thread: VirtualThread[#78]/runnable@ForkJoinPool-1-worker-7
Task 29 started on thread: VirtualThread[#75]/runnable@ForkJoinPool-1-worker-7
Task 33 started on thread: VirtualThread[#79]/runnable@ForkJoinPool-1-worker-7
Task 34 started on thread: VirtualThread[#80]/runnable@ForkJoinPool-1-worker-7
Task 35 started on thread: VirtualThread[#81]/runnable@ForkJoinPool-1-worker-7
Task 36 started on thread: VirtualThread[#82]/runnable@ForkJoinPool-1-worker-7
Task 37 started on thread: VirtualThread[#83]/runnable@ForkJoinPool-1-worker-7
Task 38 started on thread: VirtualThread[#84]/runnable@ForkJoinPool-1-worker-7
Task 39 started on thread: VirtualThread[#85]/runnable@ForkJoinPool-1-worker-7
Task 41 started on thread: VirtualThread[#87]/runnable@ForkJoinPool-1-worker-7
Task 42 started on thread: VirtualThread[#88]/runnable@ForkJoinPool-1-worker-7
Task 40 started on thread: VirtualThread[#86]/runnable@ForkJoinPool-1-worker-7
Task 43 started on thread: VirtualThread[#89]/runnable@ForkJoinPool-1-worker-7
Task 44 started on thread: VirtualThread[#90]/runnable@ForkJoinPool-1-worker-7
Task 45 started on thread: VirtualThread[#91]/runnable@ForkJoinPool-1-worker-7
Task 46 started on thread: VirtualThread[#92]/runnable@ForkJoinPool-1-worker-7
Task 47 started on thread: VirtualThread[#93]/runnable@ForkJoinPool-1-worker-7
Task 48 started on thread: VirtualThread[#94]/runnable@ForkJoinPool-1-worker-7
Task 49 started on thread: VirtualThread[#95]/runnable@ForkJoinPool-1-worker-7
Task 50 started on thread: VirtualThread[#96]/runnable@ForkJoinPool-1-worker-7
Task 51 started on thread: VirtualThread[#97]/runnable@ForkJoinPool-1-worker-7
Task 52 started on thread: VirtualThread[#98]/runnable@ForkJoinPool-1-worker-7
Task 53 started on thread: VirtualThread[#99]/runnable@ForkJoinPool-1-worker-7
Task 54 started on thread: VirtualThread[#100]/runnable@ForkJoinPool-1-worker-7
Task 55 started on thread: VirtualThread[#101]/runnable@ForkJoinPool-1-worker-7
Task 56 started on thread: VirtualThread[#102]/runnable@ForkJoinPool-1-worker-7
Task 58 started on thread: VirtualThread[#104]/runnable@ForkJoinPool-1-worker-7
Task 59 started on thread: VirtualThread[#105]/runnable@ForkJoinPool-1-worker-7
Task 57 started on thread: VirtualThread[#103]/runnable@ForkJoinPool-1-worker-7
Task 60 started on thread: VirtualThread[#106]/runnable@ForkJoinPool-1-worker-7
Task 62 started on thread: VirtualThread[#108]/runnable@ForkJoinPool-1-worker-7
Task 63 started on thread: VirtualThread[#109]/runnable@ForkJoinPool-1-worker-7
Task 61 started on thread: VirtualThread[#107]/runnable@ForkJoinPool-1-worker-7
Task 64 started on thread: VirtualThread[#110]/runnable@ForkJoinPool-1-worker-7
Task 66 started on thread: VirtualThread[#112]/runnable@ForkJoinPool-1-worker-7
Task 65 started on thread: VirtualThread[#111]/runnable@ForkJoinPool-1-worker-7
Task 67 started on thread: VirtualThread[#113]/runnable@ForkJoinPool-1-worker-7
Task 68 started on thread: VirtualThread[#114]/runnable@ForkJoinPool-1-worker-7
Task 69 started on thread: VirtualThread[#115]/runnable@ForkJoinPool-1-worker-7
Task 70 started on thread: VirtualThread[#116]/runnable@ForkJoinPool-1-worker-7
Task 71 started on thread: VirtualThread[#117]/runnable@ForkJoinPool-1-worker-7
Task 72 started on thread: VirtualThread[#118]/runnable@ForkJoinPool-1-worker-7
Task 73 started on thread: VirtualThread[#119]/runnable@ForkJoinPool-1-worker-7
Task 74 started on thread: VirtualThread[#120]/runnable@ForkJoinPool-1-worker-7
Task 75 started on thread: VirtualThread[#121]/runnable@ForkJoinPool-1-worker-7
Task 76 started on thread: VirtualThread[#122]/runnable@ForkJoinPool-1-worker-7
Task 77 started on thread: VirtualThread[#123]/runnable@ForkJoinPool-1-worker-7
Task 78 started on thread: VirtualThread[#124]/runnable@ForkJoinPool-1-worker-7
Task 79 started on thread: VirtualThread[#125]/runnable@ForkJoinPool-1-worker-7
Task 80 started on thread: VirtualThread[#126]/runnable@ForkJoinPool-1-worker-7
Task 81 started on thread: VirtualThread[#127]/runnable@ForkJoinPool-1-worker-7
Task 82 started on thread: VirtualThread[#128]/runnable@ForkJoinPool-1-worker-7
Task 83 started on thread: VirtualThread[#129]/runnable@ForkJoinPool-1-worker-7
Task 84 started on thread: VirtualThread[#130]/runnable@ForkJoinPool-1-worker-7
Task 85 started on thread: VirtualThread[#131]/runnable@ForkJoinPool-1-worker-7
Task 86 started on thread: VirtualThread[#132]/runnable@ForkJoinPool-1-worker-7
Task 88 started on thread: VirtualThread[#134]/runnable@ForkJoinPool-1-worker-7
Task 87 started on thread: VirtualThread[#133]/runnable@ForkJoinPool-1-worker-7
Task 89 started on thread: VirtualThread[#135]/runnable@ForkJoinPool-1-worker-7
Task 90 started on thread: VirtualThread[#136]/runnable@ForkJoinPool-1-worker-7
Task 91 started on thread: VirtualThread[#137]/runnable@ForkJoinPool-1-worker-7
Task 92 started on thread: VirtualThread[#138]/runnable@ForkJoinPool-1-worker-7
Task 93 started on thread: VirtualThread[#139]/runnable@ForkJoinPool-1-worker-7
Task 94 started on thread: VirtualThread[#140]/runnable@ForkJoinPool-1-worker-7
Task 95 started on thread: VirtualThread[#141]/runnable@ForkJoinPool-1-worker-8
Task 97 started on thread: VirtualThread[#143]/runnable@ForkJoinPool-1-worker-8
Task 96 started on thread: VirtualThread[#142]/runnable@ForkJoinPool-1-worker-8
Task 98 started on thread: VirtualThread[#144]/runnable@ForkJoinPool-1-worker-3
Task 99 started on thread: VirtualThread[#145]/runnable@ForkJoinPool-1-worker-3
Task 2 released lock.
Task 2 finished.
Task 0 acquired lock. Thread: VirtualThread[#37]/runnable@ForkJoinPool-1-worker-7
Task 0 released lock.
Task 0 finished.
Task 3 acquired lock. Thread: VirtualThread[#45]/runnable@ForkJoinPool-1-worker-5
Task 3 released lock.
Task 3 finished.
Task 1 acquired lock. Thread: VirtualThread[#39]/runnable@ForkJoinPool-1-worker-7
Task 1 released lock.
Task 1 finished.
Task 4 acquired lock. Thread: VirtualThread[#47]/runnable@ForkJoinPool-1-worker-5
Task 4 released lock.
Task 4 finished.
Task 5 acquired lock. Thread: VirtualThread[#48]/runnable@ForkJoinPool-1-worker-7
Task 5 released lock.
Task 5 finished.
Task 7 acquired lock. Thread: VirtualThread[#50]/runnable@ForkJoinPool-1-worker-8
Task 7 released lock.
Task 7 finished.
Task 8 acquired lock. Thread: VirtualThread[#53]/runnable@ForkJoinPool-1-worker-8
Task 8 released lock.
Task 8 finished.
Task 9 acquired lock. Thread: VirtualThread[#54]/runnable@ForkJoinPool-1-worker-6
Task 9 released lock.
Task 9 finished.
Task 10 acquired lock. Thread: VirtualThread[#55]/runnable@ForkJoinPool-1-worker-8
Task 10 released lock.
Task 10 finished.
Task 11 acquired lock. Thread: VirtualThread[#56]/runnable@ForkJoinPool-1-worker-2
Task 11 released lock.
Task 11 finished.
Task 12 acquired lock. Thread: VirtualThread[#57]/runnable@ForkJoinPool-1-worker-8
Task 12 released lock.
Task 12 finished.
Task 13 acquired lock. Thread: VirtualThread[#58]/runnable@ForkJoinPool-1-worker-7
Task 13 released lock.
Task 13 finished.
Task 15 acquired lock. Thread: VirtualThread[#60]/runnable@ForkJoinPool-1-worker-7
Task 15 released lock.
Task 15 finished.
Task 16 acquired lock. Thread: VirtualThread[#61]/runnable@ForkJoinPool-1-worker-5
Task 16 released lock.
Task 16 finished.
Task 14 acquired lock. Thread: VirtualThread[#59]/runnable@ForkJoinPool-1-worker-2
Task 14 released lock.
Task 14 finished.
Task 17 acquired lock. Thread: VirtualThread[#62]/runnable@ForkJoinPool-1-worker-8
Task 17 released lock.
Task 17 finished.
Task 19 acquired lock. Thread: VirtualThread[#64]/runnable@ForkJoinPool-1-worker-8
Task 19 released lock.
Task 19 finished.
Task 18 acquired lock. Thread: VirtualThread[#63]/runnable@ForkJoinPool-1-worker-2
Task 18 released lock.
Task 18 finished.
... 会一直正常执行，直到运行结束

Kafka常见面试题

如何保证Kafka消息不丢失

和RabbitMQ相似，在Kafka里面如果有防止消息不丢失，还是从以下3个方面入手解决。

• 防止生产者发送消息到Broker导致的消息丢失

  1. 设置异步发送

     // 同步发送
     RecordMetadata recordMetadata = kafkaProducer.send(record).get();
     // 异步发送
     kafkaProducer.send(record, new Callback() {
         @Override
         public void onCompletion(RecordMetadata recordMetadata, Exception e) {
             if (e != null) {
                 System.out.println("消息发送失败 | 记录日志");
             }
             long offset = recordMetadata.offset();
             int partition = recordMetadata.partition();
             String topic = recordMetadata.topic();
         }
     });
     

     如果消息成功发送，那么回调里面就不会有异常，如果出现了异常，那么就可以在回调函数里面进行兜底操作。

  2. 如果是由于网络波动，也可以利用kafka自己的重试机制

     // 设置重试次数
     prop.put(ProducerConfig.RETRIES_CONFIG, 10);
     

• 在Broker中解决消息不丢失

  

  • 发送确认机制ACK

    确认机制	说明
    acks=0	生产者在成功写入消息之前不会等待任何来自服务器的响应，消息有丢失的风险，但是速度最快
    acks=1（默认值）	只要集群首领节点收到消息，生产者就会收到一个来自服务器的成功响应
    acks=all	只有当所有参与赋值的节点全部收到消息时，生产者才会收到一个来自服务器的成功响应

• 消费者冲Broker接受消息防止消息丢失

  

  • Kafka中的分区机制是将每个主题划分为多个分区（Partition）
  • topic分区中的消息只能由消费者组中的唯一一个消费者处理，不同的分区分配给不同的消费者（同一个消费组）
  • 不同的分区是按偏移量来存储消息的

  如图：

  

  在 Kafka 消费过程中，由于定期自动提交（enable.auto.commit=true）是基于固定时间间隔执行的，它与实际消息处理的进度并不同步，这正是导致消息丢失或重复消费的根本原因。

  • 为什么会导致消息丢失？

    消息丢失通常发生在**“先提交，后处理失败”**的情况下。

    原理： 假设你设置每 5 秒自动提交一次。在第 3 秒时，消费者拉取了一批消息（如偏移量 5-10）。

    触发丢失： 刚好在第 5 秒，Kafka 客户端自动将偏移量 10 提交到了服务端。然而，此时你的业务代码可能刚处理完偏移量 7，在处理偏移量 8 时程序崩溃（Crash）或重启。

    后果： 当消费者恢复后，它会从上次提交的偏移量 10 开始拉取。这意味着 8、9、10 这几条消息虽然从未被成功处理，但在 Kafka 看来已经“消费完成”了，从而导致消息丢失。

  • 为什么会导致重复消费？

    重复消费通常发生在**“已处理，未提交”**的情况下。

    原理： 同样假设 5 秒提交一次。消费者拉取了偏移量 5-10 的消息。

    触发重复： 在第 4 秒时，你的业务代码已经成功处理了所有消息（5-10）。但在第 5 秒自动提交动作发生之前，消费者突然断开连接或触发了再均衡（Rebalance）。

    后果： 由于偏移量 10 还没来得及提交，Kafka 服务端记录的最新偏移量仍是 5。当新的消费者接管该分区（如图片中的 P1、P2 或 P3）后，它会再次从偏移量 5 开始拉取，导致 5-10 的消息被业务系统重新处理一遍。

  • 解决办法：

    1. 禁用自动提交偏移量，改为手动，采用异步和同步提交的组合。

    try {
        while (true) {
            ConsumerRecords<String, String> records = consumer.poll(Duration.ofMillis(1000));
            for (ConsumerRecord<String, String> record : records) {
                System.out.println(record.value());
                System.out.println(record.key());
            }
            // 异步提交：在循环中为了效率使用异步提交
            consumer.commitAsync();
        }
    } catch (Exception e) {
        e.printStackTrace();
        System.out.println("记录错误信息: " + e);
    } finally {
        try {
            // 同步提交：在消费者关闭前，确保最后一次偏移量提交成功
            consumer.commitSync();
        } finally {
            consumer.close();
        }
    }
    

Kafka保证消息顺序性

应用场景：

• 即时单对单聊天和群聊，保证发送方消息发送顺序和接受方的顺序是一致的
• 充值转账两个渠道在同一个时间进行余额变更，短信通知必须有顺序

topic分区中消息只能由消费者组中的唯一一个处理，所以消息肯定是按照先后顺序进行处理的。但是它仅仅是保证Topic的一个分区顺序处理，不能保证跨分区的消息先后处理顺序。所以，如果需要顺序处理Topic的所有消息，那就只能提供一个分区。

// 指定分区发送
kafkaTemplate.send("springboot-kafka-topic", 0, "key-001", "value-0001");

// 使用相同的业务key发送
kafkaTemplate.send("springboot-kafka-topic", "key-001", "value-0001");

在 Kafka 中，如果你没有在发送时手动指定分区号（即上面代码的第一种方式），Kafka 会使用 分区策略（Partitioner） 来决定消息去往哪个分区。

当消息包含 Key 时，Kafka 默认的分区器会执行以下操作：

1. 计算哈希值：对 Key（如 "key-001"）进行哈希运算（通常是 murmur2 算法）。
2. 取模运算：用计算出的哈希值对该 Topic 的分区总数进行取模。
   • 公式： ​partition = hash(key) \pmod{numPartitions}

Kafka高可用机制

• 集群模式

• Kafka的服务器端由被称为Broker的服务进程构成，即一个Kafka集群由多个Broker组成
• 这样如果集群中某一台机器岩机，其他机器上的Broker也依然能够对外提供服务。这其实就是Kafka提供高可用的手段之一

分区备份机制

某一个topic中有三个分区P0、P1、P2

• 一个topic有多个分区，每个分区有多个副本，其中有一个leader，其余的是follower，副本存储在不同的broker中
• 所有的分区副本的内容是都是相同的，如果leader发生故障时，会自动将其中一个follower提升为leader

当producer发送消息的时候，Leader分区会往ISR分区和普通分区发送消息，如图所示：

ISR (in-sync replica) 需要同步复制保存的follower

如果leader失效后，需要选出新的leader，选举的原则如下：

• 第一： 选举时优先从ISR中选定，因为这个列表中follower的数据是与leader同步的
• 第二： 如果ISR列表中的follower都不行了，就只能从其他follower中选取

//一个topic默认分区的replication个数，不能大于集群中broker的个数。默认为1
default.replication.factor=3

//最小的ISR副本个数
min.insync.replicas=2

Kafka数据清理机制

Kafka文件存储机制

存储结构：

Kafka 的数据存储遵循“由大到小”的逻辑拆分，确保了系统的高伸缩性和读写效率：

• Topic（主题层）： 如图中顶层的 hanserwei 。这是一个逻辑上的分类。
• Partition（分区层）： 一个 Topic 可以分为多个 Partition（如 hanserwei-0, hanserwei-1, hanserwei-2）。在物理磁盘上，每个 Partition 对应一个单独的文件夹。
• Segment（日志分段层）： 每个 Partition 文件夹下又被切分为多个 Segment（如 Segment 0, Segment 1）。

为什么要引入 Segment（分段机制）？

根据图中的描述，将 Partition 进一步切分为 Segment 主要有两个核心目的：

• 删除无用文件方便，提高磁盘利用率： Kafka 的数据是有过期时间的。通过分段，可以更轻松地删除旧的 Segment 文件，而不会影响正在写入的活跃文件。
• 查找数据便捷： 较小的文件配合索引，可以大幅提高定位特定偏移量（Offset）数据的速度。

Segment 的物理组成

每个 Segment 并不是单一的文件，而是由一组具有相同文件名的不同后缀文件组成：

数据清理机制

日志的清理策略有两个

1. 根据消息的保留时间

当消息在 Kafka 中保存的时间超过了指定的时间，就会触发清理过程。

# The minimum age of a log file to be eligible for deletion due to age
# 默认保留时间（示例为 168 小时，即 7 天）
log.retention.hours=168

2.根据 Topic 存储的数据大小

当 Topic 所占的日志文件大小大于一定的阈值，则开始删除最久的消息。需手动开启。

# A size-based retention policy for logs. Segments are pruned from the log 
# unless the remaining segments drop below log.retention.bytes. 
# Functions independently of log.retention.hours.
# 示例阈值为 1073741824 字节（即 1GB）
#log.retention.bytes=1073741824

Kafka为什么快

消息分区（Partitioning）

• 提取： 不受单台服务器的限制，可以不受限的处理更多的数据。
• 补充： 分区是 Kafka 横向扩展（Scalability） 的基础。通过将一个 Topic 分成多个 Partition 分布在不同的 Broker（服务器）上，实现了并发读写。这也是负载均衡的关键。

顺序读写（Sequential I/O）

• 提取： 磁盘顺序读写，提升读写效率。
• 补充： 磁盘随机读写速度很慢，但顺序读写的性能接近内存。Kafka 采用 Append-only（只追加） 模式写入日志文件，避免了磁盘机械臂的频繁寻道，极大地提升了 I/O 吞吐。

页缓存（Page Cache）

• 提取： 把磁盘中的数据缓存到内存中，把对磁盘的访问变为对内存的访问。
• 补充： Kafka 并不在 JVM 堆内存中缓存数据，而是利用 操作系统层面的 Page Cache。这样做避免了 JVM GC（垃圾回收）带来的性能开销，即使服务重启，缓存依然存在。

零拷贝（Zero Copy）

• 提取： 减少上下文切换及数据拷贝。
• 补充： 主要通过 Linux 的 sendfile 系统调用实现。数据直接从“页缓存”传输到“网卡接口”，无需经过“用户态”内存，减少了 CPU 在内核态与用户态之间的切换次数。

消息压缩（Message Compression）

• 提取： 减少磁盘 IO 和网络 IO。
• 补充： 支持 Snappy、Gzip、LZ4 和 Zstd 等算法。压缩通常在生产者端完成，在消费者端解压，能显著降低网络带宽占用并节省磁盘存储空间。

分批发送（Batching）

• 提取： 将消息打包批量发送，减少网络开销。
• 补充： 通过攒够一定数量的消息或达到设定时间后再统一发送，大幅减少了网络请求的次数（RTT）和 TCP 报文头的比例，提高了整体的有效载荷。

零拷贝

如果不使用零拷贝技术，那么Kafka发送一条消息的过程如下：

拷贝次数：磁盘文件-->页缓存-->Kafka-->Socket缓存区-->网卡，一共四次拷贝

如果使用零拷贝，那么流程如下：

拷贝次数：磁盘文件-->页缓存-->网卡，就只需要两次拷贝即可。

RabbitMQ常见面试题

RabbitMQ如何保证消息不丢失

RabbitMQ消息丢失的三种情况

消息丢失的三种情况：

1. 消息未到达交换机
2. 消息到达交换机但是未到达队列，或到达队列但是未莱得及消费
3. 消费者未接收到消息

解决以上问题，可以从以下三个方面解决

生产者确认机制

RabbitMQ提供了publisher confirm机制来避免消息发送到MQ过程中丢失。消息发送到MQ以后，会返回一个结果给发送者，表示消息是否处理成功。

消息失败之后如何处理？

• 回调方法即时重发
• 记录日志
• 保留数据到数据库，定时重发，成功后删除表中数据

消息持久化

MQ默认是内存存储的，开启持久化功能可以确保缓存到MQ中的消息不丢失。

1. 交换机持久化 (Exchange Persistence)

   @Bean
   public DirectExchange simpleExchange() {
       // 三个参数：交换机名称、是否持久化、当没有 queue 与其绑定时是否自动删除
       return new DirectExchange("simple.direct", true, false);
   }
   

2. 队列持久化 (Queue Persistence)

   @Bean
   public Queue simpleQueue() {
       // 使用 QueueBuilder 构建队列，durable 就是持久化的
       return QueueBuilder.durable("simple.queue").build();
   }
   

3. 消息持久化 (Message Persistence)

   SpringAMQP 中的消息默认是持久化的，可以通过 MessageProperties 中的 DeliveryMode 来指定。

   Message msg = MessageBuilder
       .withBody(message.getBytes(StandardCharsets.UTF_8)) // 消息体
       .setDeliveryMode(MessageDeliveryMode.PERSISTENT) // 持久化
       .build();
   

说明：

• 交换机持久化：确保 MQ 重启后交换机依然存在。
• 队列持久化：确保 MQ 重启后队列依然存在。
• 消息持久化：确保 MQ 重启后，队列中的消息依然存在（前提是交换机和队列也必须持久化）。

消费者确认

RabbitMQ支持消费者确认机制，即：消费者处理消息之后可以想MQ发送ACK回执。MQ收到ACK回执之后才删除该消息。而SpingAMQP则允许配置三种确认方式：

• manual: 手动ack，需要在业务代码结束后，调用api发送ack。
• auto: 自动ack，由spring监测listener代码是否出现异常，没有异常则返回ack；抛出异常则返回nack
• none: 关闭ack，MQ假定消费者获取消息后会成功处理，因此消息投递后立即被删除

我们可以使用Spring的retry机制，在消费者出现异常的时候利用本地重试，设置重试次数，当次数达到上限之后，如果消息依然没有成功被消费，那么就把消息投递到异常交换机，然后交由人工处理。

RabbitMQ如何防止消息重复消费

1. 利用数据库唯一索引（Unique Index）

这是最简单直接的方法。如果你的业务是将数据写入数据库，可以利用数据库的强一致性。

• 做法：在表中设置一个业务相关的唯一键（如 order_id）。
• 效果：当重复的消息到达时，执行 INSERT 操作会触发唯一索引冲突，数据库报错。你只需要捕获异常并忽略即可。

2. 利用 Redis 的原子性操作（去重表机制）

如果你的业务不是简单的数据库写入（比如调用第三方 API 或发送邮件），可以使用 Redis 来做拦截。

• 流程：
  1. 每条消息在生产者发送时，附带一个全局唯一 ID（如 UUID 或雪花 ID）。
  2. 消费者接收到消息后，先去 Redis 查一下这个 ID 是否存在：
     • 不存在：说明没消费过。将 ID 存入 Redis（可设置过期时间），然后执行业务逻辑。
     • 存在：说明是重复消息，直接丢弃。
• 注意：为了防止“逻辑执行了一半挂掉”导致后续无法重试，建议结合 Lua 脚本 或 分布式锁 来保证查重与写入的原子性。

3. 状态机幂等（Status Machine）

适用于有明显状态流转的业务（如订单系统）。

• 做法：在更新数据时，带上状态条件。

  UPDATE orders SET status = 'PAID' WHERE id = 123 AND status = 'UNPAID';

• 效果：如果消息重复触发，第二次执行时 status 已经是 PAID 了，SQL 不会更新任何行，从而保证了业务正确性。

4. RabbitMQ 的 redelivered 标志位

RabbitMQ 协议层面提供了一个辅助工具。

• 原理：当消息是第二次及以上投递给消费者时，RabbitMQ 会在消息头中将 redelivered 字段设为 true。
• 策略：
  • 如果 redelivered 为 false：直接消费。
  • 如果 redelivered 为 true：进入“去重检查”逻辑（如查 Redis），这样可以减少对外部缓存的压力。

实际业务当中，一般都是采用的数据库唯一索引来保证的，无论咋操作，你的数据最后都是落库。

RabbitMQ中死信交换机（延时队列）

死信交换机

当一个队列中的消息满足下列情况之一时，可以成为死信：

• 消息被拒绝：消费者使用了 basic.reject 或 basic.nack，且设置 requeue=false。
• 消息过期：消息达到了存活时间（TTL）。
• 队列达到最大长度：最早的消息会被丢弃或变成死信。

如果该队列配置了dead-letter-exchange属性，指定了一个交换机，那么队列中的死信就会投递到这个交换机中，而这个交换机就被称为死信交换机（Dead Letter Exchange，简称DLX）。

代码示例：

@Bean
public Queue ttlQueue(){
    return QueueBuilder.durable("simple.queue") // 指定队列名称，并持久化
            .ttl(10000) // 设置队列的超时时间，10秒
            .deadLetterExchange("dl.direct") // 指定死信交换机
            .build();
}

TTL

TTL，也就是 Time-To-Live。如果一个队列中的消息 TTL 结束仍未消费，则会变为死信，TTL 超时分为两种情况：

• 消息所在的队列设置了存活时间
• 消息本身设置了存活时间

发信的时候可以携带一个过期时间，队列本身也可以设置一个过期时间，两者以较小的为准。到时间就自动成为死信。

// 创建消息
Message message = MessageBuilder
        .withBody("hello, ttl message".getBytes(StandardCharsets.UTF_8))
        .setExpiration("5000")
        .build();

// 消息ID，需要封装到CorrelationData中
CorrelationData correlationData = new CorrelationData(UUID.randomUUID().toString());

// 发送消息
rabbitTemplate.convertAndSend("ttl.direct", "ttl", message, correlationData);

延迟队列插件

DelayExchange插件，需要安装在 RabbitMQ 中

RabbitMQ 有一个官方的插件社区，地址为：https://www.rabbitmq.com/community-plugins.html

rabbitmq_delayed_message_exchange

A plugin that adds delayed-messaging (or scheduled-messaging) to RabbitMQ.

• Releases
• Author: Alvaro Videla
• GitHub: rabbitmq/rabbitmq-delayed-message-exchange

DelayExchange 的本质还是官方的三种交换机，只是添加了延迟功能。 因此使用时只需要声明一个交换机，交换机的类型可以是任意类型，然后设定 delayed 属性为 true 即可。

@RabbitListener(bindings = @QueueBinding(
    value = @Queue(name = "delay.queue", durable = "true"),
    exchange = @Exchange(name = "delay.direct", delayed = "true"),
    key = "delay"
))
public void listenDelayedQueue(String msg){
    log.info("接收到 delay.queue 的延迟消息：{}", msg);
}

RabbitMQ如果有100万消息积压如何解决

当生产者发送消息的速度超过了消费者处理消息的速度，就会导致队列中消息积压，直到队列存储的消息达到上限。之后发送的消息就会成为死信，可能被丢弃，这就是消息堆积的问题。

解决消息堆积一般有三种思路:

1. 增加更多消费者，提高消费速度
2. 在消费者内开启线程池来消费加快处理速度
3. 扩大队列容量，提高堆积上限

惰性队列

文字内容： 惰性队列的特征如下：

• 接收到消息后直接存入磁盘而非内存
• 消费者要消费消息时才会从磁盘中读取并加载到内存
• 支持数百万条的消息存储

1. 通过 Bean 声明惰性队列：

   @Bean
   public Queue lazyQueue(){
       return QueueBuilder
               .durable("lazy.queue")
               .lazy() // 开启 x-queue-mode 为 lazy
               .build();
   }
   

2. 通过注解声明并监听惰性队列：

   @RabbitListener(queuesToDeclare = @Queue(
       name = "lazy.queue",
       durable = "true",
       arguments = @Argument(name = "x-queue-mode", value = "lazy")
   ))
   public void listenLazyQueue(String msg){
       log.info("接收到 lazy.queue 的消息：{}", msg);
   }
   

RabbitMQ的高可用机制

• 在生产环境下，使用集群来保证高可用性
• 普通集群、镜像集群、仲裁集群

普通集群

普通集群，或者叫标准集群（classic cluster），具备下列特征：

• 会在集群的各个节点间共享部分数据，包括：交换机、队列元信息。不包含队列中的消息。
• 当访问集群某节点时，如果队列不在该节点，会从数据所在节点传递到当前节点并返回
• 队列所在节点宕机，队列中的消息就会丢失

一般不使用这个集群方式

镜像集群

镜像集群：本质是主从模式，具备下面的特征：

• 交换机、队列、队列中的消息会在各个 mq 的镜像节点之间同步备份。
• 创建队列的节点被称为该队列的主节点，备份到的其它节点叫做该队列的镜像节点。
• 一个队列的主节点可能是另一个队列的镜像节点。
• 所有操作都是主节点完成，然后同步给镜像节点。
• 主宕机后，镜像节点会替代成新的主。

仲裁队列

仲裁队列：仲裁队列是 3.8 版本以后才有新功能，用来替代镜像队列，具备下列特征：

• 与镜像队列一样，都是主从模式，支持主从数据同步
• 使用非常简单，没有复杂的配置
• 主从同步基于 Raft 协议，强一致

Java (Spring AMQP) 中声明仲裁队列的代码示例：

@Bean
public Queue quorumQueue() {
    return QueueBuilder
            .durable("quorum.queue") // 持久化
            .quorum() // 仲裁队列
            .build();
}

Spring框架常见面试题

Spring框架中的单例bean是线程安全的吗？

答案显然是否，但是为啥我们平时使用的是并没刻意去注意线程安全问题呢？其实最主要的原因是在于我们平时使用的时候大多注入的是无状态的Bean对象，无状态的Bean对象天然就是线程安全的。

无状态和有状态

简单来说：无状态 Bean 像自动售货机（谁来都一样），有状态 Bean 像私人理发师（记得你的具体偏好）。

1. 核心区别对比表

2. 无状态 Bean (Stateless Bean)

定义： 一个 Bean 如果不包含任何可变的成员变量（Instance Variable），或者虽然有成员变量但它们是不可变的（如注入的 Service 或 DAO），那么它就是无状态的。

特点：

• 一次性逻辑：它的方法执行只依赖于传入的参数，不依赖于上一次调用的结果。
• 高并发友好：因为没有“私有数据”，所以在 Spring 中，默认的 Bean（Singleton）都是无状态的。Spring 容器只需要创建一个实例，就可以服务成千上万个并发请求。

// 这是一个典型的无状态 Bean
@Service
public class UserService {

    // 这是一个依赖，通常是单例且不可变的，不属于"用户状态"
    @Autowired
    private UserRepository userRepository;

    public User findUser(Long id) {
        // 方法内的局部变量是线程安全的（栈内存），不会影响 Bean 的状态
        return userRepository.findById(id);
    }
}

3. 有状态 Bean (Stateful Bean)

   定义： 一个 Bean 如果包含成员变量，并且这些变量用于存储特定客户端在多次调用之间产生的数据，那么它就是有状态的。

   特点：

   • 记忆能力：它“记得”你上一次调用做了什么。
   • 独占性：张三的 Bean 不能给李四用，否则李四会看到张三的数据。因此，通常需要为每个用户创建一个新的 Bean 实例（@Scope("prototype")）。

   // 这是一个有状态的 Bean
   // 注意：在 Spring 单例模式下直接这样写会导致严重的线程安全问题！
   // 除非将其 Scope 设置为 prototype 或 session
   @Component
   @Scope("prototype") 
   public class ShoppingCart {
   
       // 这是一个状态！每个用户的购物车内容不同
       private List<String> items = new ArrayList<>();
   
       public void addItem(String item) {
           this.items.add(item);
       }
   
       public List<String> getItems() {
           return this.items;
       }
   }
   

注意一下：在日常开发过程中，一般都是直接使用无状态的Bean即可，有状态的Bean很少使用，至少我还没用过。

AOP

概念：AOP称为面向切面编程，用于将那些与业务无关，但却对多个对象产生影响的公共行为和逻辑，抽取并封装为一个可重用的模块，这个模块被命名为“切面”（Aspect），减少系统中的重复代码，降低了模块间的耦合度，同时提高了系统的可维护性。

• 常见的AOP使用场景：
  • 记录操作日志
  • 缓存处理
  • Spring中内置的事务处理

示例：

第一步：引入依赖

如果你使用的是 Spring Boot，只需要引入 AOP 的 Starter，它会自动配置好 AspectJ 相关的库。

maven：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-aop</artifactId>
</dependency>

gradle：

implementation 'org.springframework.boot:spring-boot-starter-aop'

第二步：定义切面类 (Aspect)

创建一个普通的 Java 类，加上 @Aspect 和 @Component 注解。

• @Aspect：告诉 Spring 这是一个切面类。
• @Component：将其注册为 Spring 容器中的一个 Bean。

import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.*;
import org.springframework.stereotype.Component;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

@Aspect
@Component
public class LogAspect {

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

    /**
     * 1. 定义切点 (Pointcut)
     * 表达式含义：execution(修饰符 返回值 包名.类名.方法名(参数))
     * 这里表示：拦截 com.example.service 包下所有类的所有方法
     */
    @Pointcut("execution(* com.example.service..*.*(..))")
    public void serviceLayer() {}

    /**
     * 2. 前置通知 (Before Advice)
     * 在目标方法执行之前执行
     */
    @Before("serviceLayer()")
    public void doBefore() {
        logger.info("========== 开始执行 Service 方法 ==========");
    }

    /**
     * 3. 环绕通知 (Around Advice) - 最常用，功能最强
     * 它可以控制目标方法是否执行，还能修改返回值，计算时间等
     */
    @Around("serviceLayer()")
    public Object doAround(ProceedingJoinPoint joinPoint) throws Throwable {
        long start = System.currentTimeMillis();
        
        // 获取方法签名
        String methodName = joinPoint.getSignature().getName();
        // 获取参数
        Object[] args = joinPoint.getArgs();

        try {
            // *** 核心：执行目标方法 ***
            Object result = joinPoint.proceed(); 
            
            long end = System.currentTimeMillis();
            logger.info("方法 [{}] 执行耗时: {} ms", methodName, (end - start));
            
            return result; // 返回目标方法的执行结果
        } catch (Throwable e) {
            logger.error("方法 [{}] 执行出错: {}", methodName, e.getMessage());
            throw e; // 抛出异常，否则调用方以为执行成功了
        }
    }
}

第三步：理解核心概念 (关键词)

为了能灵活使用，你需要理解上面代码中的几个关键术语：

1. 切面 (Aspect)：也就是上面的 LogAspect 类，是包含切点和通知的模块。
2. 切点 (Pointcut)：定义“在哪里”执行切面逻辑。
   • 常用表达式：execution(* com.service.*.*(..))
   • 另一种常用方式：@annotation(com.example.MyLog) (只拦截加了特定注解的方法)。
3. 通知 (Advice)：定义“做什么”以及“什么时候做”。
   • @Before：方法前。
   • @AfterReturning：方法成功返回后。
   • @AfterThrowing：抛出异常后。
   • @After：无论成功失败，最终都会执行（类似 finally）。
   • @Around：最强大，包围整个方法，能决定是否执行目标方法。
4. 连接点 (JoinPoint)：程序执行的某个具体位置。在 Spring AOP 中，总是指方法的执行。

实际开发中我一般还是会配合注解来是先AOP。步骤也很简单：

第一步定义注解：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface AutoLog {
    String value() default "";
}

第二步修改切点表达式：

// 只要方法上加了 @AutoLog 注解，就会被拦截
@Pointcut("@annotation(com.example.annotation.AutoLog)")
public void annotationPointcut() {}

第三步使用：

@Service
public class UserService {
    
    @AutoLog("查询用户详情") // 只有加了这个注解的方法才会被 AOP 处理
    public User getUser(Long id) {
        return userRepository.findById(id);
    }
}

注意事项 (非常重要！)

1. AOP 失效问题（自调用）： Spring AOP 是基于代理 (Proxy) 实现的。如果在同一个类中，方法 A 调用了方法 B，而方法 B 上配了 AOP，AOP 是不会生效的。
   • 原因：this.methodB() 是直接调用对象内部方法，绕过了 Spring 生成的代理对象。
2. 访问权限： AOP 通常只能拦截 public 方法。虽然通过配置可以拦截 protected/private，但不推荐。

Spring事务管理以及事务失效场景

详情见：聊聊@Transactional注解和事务的使用

Spring中Bean的生命周期

这个问题是牢中牢，太夸张了。我在这里梳理一下这个问题的答案。

我们先看一个Bean的生命周期主要包括哪些部分：

但是你觉得spring的bean就这么简单几步？其实主要的就这么几步，还有一些细节的操作。完整的流程图如图所示：

注意一下，两幅图有对应关系的哦。

Spring Bean 生命周期详细步骤

1. 实例化阶段：

• Bean 的实例化是通过反射机制创建的。Spring 根据 @Component、@Bean 或者 XML 中的 <bean> 元素配置，来确定要创建的 Bean。

2. 属性赋值阶段：

• 在实例化完成后，Spring 会进行依赖注入。这包括将属性值注入到 Bean 的字段中，可能是通过 setter 方法注入，或者直接字段注入。

3. 初始化前的扩展机制：

• Bean 可以实现 BeanNameAware、BeanFactoryAware 等 Aware 接口，从而在初始化之前获取 Bean 的名称、BeanFactory、ApplicationContext 等容器资源。例如，ApplicationContextAware 接口允许 Bean 获取 ApplicationContext，以便进一步与 Spring 容器交互。

4. BeanPostProcessor 的作用：

• BeanPostProcessor 接口允许开发者在 Bean 初始化前后添加自定义逻辑。例如，可以在 postProcessBeforeInitialization 方法中执行某些前置操作，如代理包装、AOP 切面等。在 postProcessAfterInitialization 中，可以进一步修改或替换 Bean 实例。

5. 初始化的细节：

• InitializingBean 接口提供了一个 afterPropertiesSet 方法，用于在 Bean 的所有属性设置完成后执行一些自定义初始化逻辑。开发者也可以通过 @PostConstruct 注解或者 XML/Java 配置中的 init-method 属性，来指定初始化方法。

6. Bean 的就绪状态：

• Bean 完成初始化后，即进入就绪状态，可以供应用程序使用。在此状态下，Bean 已经完成了所有的属性设置和初始化步骤，处于可用状态。

7. 销毁阶段的清理：

• Bean 的销毁通常在容器关闭时进行。DisposableBean 接口提供了 destroy 方法，用于清理资源。开发者也可以通过 @PreDestroy 注解或配置中的 destroy-method 属性，指定清理逻辑。

Bean 的生命周期扩展点汇总

Spring 提供了多个扩展点，让开发者可以自定义和控制 Bean 的生命周期：

1. BeanPostProcessor：

• 通过实现 BeanPostProcessor 接口，开发者可以在 Bean 初始化前后添加自定义逻辑，如动态代理、AOP 增强等。

2.BeanFactoryPostProcessor：

• BeanFactoryPostProcessor 允许开发者在 Bean 实例化之前，修改 Bean 的定义信息（如属性值），它在所有 Bean 实例化之前执行。

3.Aware 接口：

• Spring 提供了多个 Aware 接口，如 BeanNameAware、BeanFactoryAware、ApplicationContextAware 等，允许 Bean 获取 Spring 容器的相关信息，进一步定制生命周期。

4.@PostConstruct 和 @PreDestroy：

• 这些注解提供了一种声明式的方法来定义初始化和销毁逻辑，通常用于替代 XML 或 Java 配置中的 init-method 和 destroy-method。

Spring三级缓存解决循环依赖

一级缓存

• singletonObjects，单例池，缓存已经经历了完整的生命周期，已经初始化完成的bean对象
• 作用：限制bean在beanFactory中只存一份，即实现singleton scope，解决不了循环依赖

二级缓存

• earlySingletonObject，缓存早期的bean对象（生命周期还没走完）
• 作用：配合一级缓存实现普通对象的循环依赖，代理对象的循环依赖还不能解决

三级缓存

• singletonFactories，缓存的是ObjectFactory，表示对象工厂，用来创建某个对象的
• 作用：实例化对象，如果对象是代理对象，则生成代理对象，如果不是则生成普通对象

//单实例对象注册器 
public class DefaultSingletonBeanRegistry extends SimpleAliasRegistry implements SingletonBeanRegistry {     
    private static final int SUPPRESSED_EXCEPTIONS_LIMIT = 100;     
    private final Map<String, Object> singletonObjects = new ConcurrentHashMap(256);     
    private final Map<String, ObjectFactory<?>> singletonFactories = new HashMap(16);     
    private final Map<String, Object> earlySingletonObjects = new ConcurrentHashMap(16);
 }

二级缓存辅助解决普通对象循环依赖图示：

三级缓存解决代理对象循环依赖

• 构造方法注入出现循环依赖

  • 解决：加@Lazy注解

    @Component public class A {      
    // B成员变量   
        private B b;      
        public A(@Lazy B b){         
            System.out.println("A的构造方法执行了...");         
            this.b = b ;
         }
     }
     
    @Component public class B {  
        // A成员变量   
        private A a;      
        public B(A a){
             System.out.println("B的构造方法执行了...");
             this.a = a ;     
        }
     }
    

SpringMVC的执行流程

这里有两种，一种是前后端不分离的，我不写，如果你面试的还是前后端不分离的，我建议你换一家，没有意义。纯傻逼。

• 用户发送出请求到前端控制器DispatcherServlet
• DispatcherServlet收到请求调用HandlerMapping（处理器映射器）
• HandlerMapping找到具体的处理器，生成处理器对象及处理器拦截器(如果有)，再一起返回给DispatcherServlet。
• DispatcherServlet调用HandlerAdapter（处理器适配器）
• HandlerAdapter经过适配调用具体的处理器（Handler/Controller）
• 方法上添加了@ResponseBody
• 通过HttpMessageConverter来返回结果转换为JSON并响应

Spring Boot自动装配的原理

我这里只说Spring Boot3的，毕竟现在Spring Boot3是主流的开发技术。

Spring Boot 3 的自动装配（Auto-configuration）是其“约定大于配置”核心理念的基石。简单来说，它能根据你项目中引入的依赖（Jar包），自动将需要的 Bean 配置到 Spring 容器中，省去了大量手动编写配置文件的麻烦。

其核心原理可以概括为：通过 SPI 机制，加载 META-INF/spring 下的配置文件，并根据条件注解按需注入。

1. 核心注解：@SpringBootApplication

自动装配的入口在于启动类上的 @SpringBootApplication 注解，它实际上是一个复合注解，其中最关键的是 @EnableAutoConfiguration。

• @SpringBootConfiguration: 标记这是一个配置类。
• @ComponentScan: 扫描当前包及其子包下的组件（@Component, @Service等）。
• @EnableAutoConfiguration: 真正开启自动装配的开关。

2. 执行流程：从注解到 Bean

Spring Boot 启动时，自动装配遵循以下关键步骤：

第一步：引入选择器

@EnableAutoConfiguration 注解通过 @Import 引入了 AutoConfigurationImportSelector 类。这个类的作用是帮助 Spring 寻找并筛选出需要自动配置的类。

第二步：读取配置文件 (SPI 机制)

在 Spring Boot 3 中，传统的 spring.factories 文件已被弃用（虽然目前版本仍做兼容，但已不是主流）。

• 新位置：Spring Boot 3 优先读取资源目录下 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 文件。
• 内容：该文件中列出了所有可选的自动配置全限定类名（例如 JdbcTemplateAutoConfiguration）。

第三步：按需过滤 (Condition 机制)

并不是配置文件里所有的类都会被加载。Spring Boot 会利用 Conditional 注解（条件装配）进行过滤：

• @ConditionalOnClass：classpath下有指定的类才装配。
• @ConditionalOnMissingBean：容器中没有这个 Bean 时才装配（方便用户自定义覆盖）。
• @ConditionalOnProperty：配置文件中指定的属性为特定值时才装配。

MySQL常见面试题

:泡泡_滑稽::泡泡_啊:

如何定位慢查询

解决方案

使用成熟的开源工具：

1. 调试工具：Arthas
2. 运维工具：Prometheus 、Skywalking

MySQL自带的慢日志（调试阶段开启，生产阶段关闭）

1. 慢查询日志记录了所有执行时间超过指定参数（long_query_time，单位：秒，默认10秒）的所有SQL语句的日志
2. 如果要开启慢查询日志，需要在MySQL的配置文件（/etc/my.cnf）中配置

# 开启MySQL的慢日志查询开关
slow_query_log=1
# 设置慢日志的时间为2秒，SQL语句的执行时间超过2秒，就会视作为慢查询，记录慢查询日志
long_query_time=2

分析SQL

• 方法：可以采用EXPLAIN 或者 DESC命令获取 MySQL 如何执行 SELECT 语句的信息
• 信息:
  • possible_key 当前sql可能会使用到的索引
  • key 当前sql实际命中的索引
  • key_len 索引占用的大小
  • Extra 额外的优化建议
  • type 这条sql的连接的类型，性能由好到差为NULL、system、const、eq_ref、ref、range、 index、all
    • system：查询系统中的表
    • const：根据主键查询
    • eq_ref：主键索引查询或唯一索引查询
    • ref：索引查询
    • range：范围查询
    • index：索引树扫描
    • all：全盘扫描

索引

概念：索引（index）是帮助MySQL高效获取数据的数据结构(有序)。在数据之外，数据库系统还维护着满足特定查找算法的数据结构（B+树），这些数据结构以某种方式引用（指向）数据， 这样就可以在这些数据结构上实现高级查找算法，这种数据结构就是索引。

数据结构比较：

在数据库（尤其是 MySQL 的 InnoDB 引擎）的设计中，核心目标是在海量数据中实现极速的查找，并尽量减少磁盘 I/O 操作。注意：磁盘IO次数是首要条件！！

为什么不选二叉树（BST / AVL / 红黑树）？

无论是普通的二叉搜索树（BST），还是自平衡的 AVL 树或红黑树，它们在数据库索引场景中都有一个致命伤：“树太高了”。

• 磁盘 I/O 瓶颈： 磁盘寻道是非常耗时的操作。在数据库索引中，每个节点通常对应一个磁盘页（Page，InnoDB 默认为 16KB）。
• 高度失控： 二叉树的每个节点只能有两个子节点（阶数为 2）。如果存储 1000 万行数据，二叉树的高度大约为 log_2(10^7) \approx 24。这意味着查找一条数据可能需要进行 24 次磁盘 I/O。
• 逻辑： 这种“瘦高”的结构在内存中运行很快，但在涉及磁盘读写时，过多的 I/O 会导致性能崩塌。

为什么不选 B 树（B-Tree）？

B 树是对二叉树的改良，它变成了“多叉树”，大大降低了树的高度。但相比 B+ 树，它有三个主要劣势：

一、内部节点存储数据导致“扇出”降低

• B 树： 每个节点（无论是根节点还是叶子节点）都存储完整的 Data。
• B+ 树： 非叶子节点（索引节点）只存储 Key 和 Pointer，不存储具体的 Data。
• 结论： 同样是 16KB 的磁盘页，B+ 树的非叶子节点能存储更多的索引项，这意味着它的**扇出（Fan-out）**更大，树的高度更低（通常 3 到 4 层即可支撑千万级数据）。

二、范围查询（Range Query）性能差

• B 树： 如果要查 ID 在 10 到 100 之间的数据，B 树需要进行中序遍历，不断在不同层级的父子节点间“反复横跳”。
• B+ 树： 所有数据都存在叶子节点，并且叶子节点之间用双向链表连接。查找范围时，只需先找到起始点，然后在叶子节点层进行顺序扫描即可。

三、查询稳定性

• B 树： 查找性能不稳定，运气好在根节点就找到了，运气差要到叶子节点。
• B+ 树： 任何查找都要最终落到叶子节点，查询路径长度固定，性能非常稳定。

为啥选择了B+树？

B+ 树之所以成为 InnoDB 的首选，主要得益于以下设计：

索引类型

聚集索引（聚簇索引）

将数据存储与索引放到了一块，索引结构的叶子节点保存了行数据。必须有，且只有一个。

聚簇索引并不是一种单独的索引类型，而是一种数据存储方式。

• 核心逻辑： 将数据行与索引 B+ 树的叶子节点存放在一起。也就是说，索引即表，表即索引。
• 物理存储： 数据的物理存储顺序与索引的逻辑顺序完全一致。
• 唯一性： 因为数据行只能按照一种物理顺序存储，所以一个表只能有一个聚簇索引。

二级索引（非聚集索引）

将数据与索引分开存储，索引结构的叶子节点关联的是对应的主键。可以存在多个。

非聚簇索引也叫辅助索引（Secondary Index）或者二级索引。

• 核心逻辑： 索引结构与数据行分开存储。B+ 树的叶子节点不存储真实的整行数据。
• 叶子节点存什么：
  • 在 InnoDB 中：叶子节点存储的是该索引列的值 + 对应的主键值。
  • 在 MyISAM 中：叶子节点存储的是该索引列的值 + 数据的磁盘地址（物理指针）。
• 数量： 一个表可以拥有多个非聚簇索引（如对 name、age 分别建索引）。

回表查询

通过二级索引找到对应的主键值，到聚集索引中查找整行数据，这个过程就是回表。再实际开发中尽可能要避免回表查询。

比如我上面的表结构，聚簇索引是主键ID，非聚簇索引是name，那么看如下SQL：

select *
from t_user
where name = 'Kit';

该SQL会先走非聚簇索引，拿到主键ID，然后由于我是select的所有字段，所以，还会拿着这个主键ID去走一遍聚簇索引，拿到剩余字段。

注意这里的Extra是null，所以肯定是回表了的。

覆盖索引

是指查询使用了索引，并且需要返回的列，在该索引中已经全部能够找到 。

-- 第一句
select * from tb_user where id = 1; 覆盖索引

-- 第二句
select id, name from tb_user where name = 'Arm'; 覆盖索引

-- 第三句
select id, name, gender from tb_user where name = 'Arm'; 非覆盖索引需要回表

覆盖索引处理MySQL超大分页问题

• 问题：当在进行分页查询时，如果执行 limit 9000000,10 ，此时需要MySQL排序前9000010 记录，仅仅返回 9000000 - 9000010 的记录，其他记录丢弃，查询排序的代价非常大 。
• 优化思路: 一般分页查询时，通过创建 覆盖索引 能够比较好地提高性能，可以通过覆盖索引加子查询形式进行优化

select *
from tb_sku t,
    (select id from tb_sku order by id limit 9000000,10) a
where t.id = a.id;

这段代码展示了 MySQL 大分页查询优化的一种常见技巧（延迟关联）：

• 子查询部分：(select id from tb_sku order by id limit 9000000,10)。这步只查询 id 字段，可以利用覆盖索引快速定位到第 9,000,000 行开始的 10 个 ID，避免了全表扫描和大量的回表操作。
• 主查询部分：通过 where t.id = a.id 将这 10 个 ID 与原表关联，从而获取这 10 条记录的所有字段信息。

相比于直接执行 select * from tb_sku limit 9000000, 10，这种方式能显著提升超大偏移量分页的查询性能。

索引创建原则

• 针对于数据量较大，且查询比较频繁的表建立索引。
• 针对于常作为查询条件（where）、排序（order by）、分组（group by）操作的字段建立索引。
• 尽量选择区分度高的列作为索引，尽量建立唯一索引，区分度越高，使用索引的效率越高。
• 如果是字符串类型的字段，字段的长度较长，可以针对于字段的特点，建立前缀索引。
• 尽量使用联合索引，减少单列索引，查询时，联合索引很多时候可以覆盖索引，节省存储空间，避免回表，提高查询效率。
• 要控制索引的数量，索引并不是多多益善，索引越多，维护索引结构的代价也就越大，会影响增删改的效率。
• 如果索引列不能存储NULL值，请在创建表时使用NOT NULL约束它。当优化器知道每列是否包含NULL值时，它可以更好地确定哪个索引最有效地用于查询。

索引失效

假设我们有一张用户表 tb_user，并针对 profession (职业)、age (年龄)、status (状态) 三个字段建立了联合索引： CREATE INDEX idx_user_pro_age_sta ON tb_user(profession, age, status);

索引失效的情况：

1. 违反最左前缀法则

规则：查询必须从索引的最左列开始，且不能跳过中间列。

• 完全失效：跳过了最左列 profession。

  -- 失效：直接从 age 开始，没有 profession
  select * from tb_user where age = 31 and status = '0';
  

• 部分失效：跳过了中间列 age。

  -- 只有 profession 走索引，status 不走索引（中间断开了）
  select * from tb_user where profession = 'Software Engineering' and status = '0';
  

2. 范围查询右边的列失效

规则：联合索引中，出现范围查询（>、<）后的列索引失效。

• 例子：

  -- profession 和 age 走索引，但 status 索引失效
  -- 因为 age 使用了范围查询 '>'
  select * from tb_user where profession = 'Software Engineering' and age > 30 and status = '0';
  

  提示：在业务允许的情况下，使用 >= 或 <= 通常可以规避部分失效问题。

3. 在索引列上进行运算操作

规则：对索引字段使用函数或数学计算，MySQL 将无法利用索引。

• 例子：

  -- 失效：对 phone 字段进行了截取操作
  select * from tb_user where substring(phone, 10, 2) = '15';
  
  -- 失效：对 age 进行了数学运算
  select * from tb_user where age + 1 = 30;
  

4. 字符串不加单引号（隐式类型转换）

规则：如果字段类型是字符串，但查询时未加引号，MySQL 会进行隐式转换，导致索引失效。

• 例子：

  -- 假设 phone 是 varchar 类型
  -- 失效：未加单引号，发生了类型转换
  select * from tb_user where phone = 17612345678;
  

5. Like 模糊查询以 % 开头

规则：头部模糊匹配会导致全表扫描。

• 失效例子（头部模糊）：

  -- 失效：百分号在前面
  select * from tb_user where profession like '%Engineering';
  

• 有效例子（尾部模糊）：

  -- 走索引：百分号只在后面
  select * from tb_user where profession like 'Software%';
  

sql优化

• 表的设计优化

  比如设置合适的数值（tinyint int bigint），要根据实际情况选择

  比如设置合适的字符串类型（char和varchar）char定长效率高，varchar可变长度，效率稍低

• 索引优化（参考优化创建原则和索引失效）

• SQL语句优化

  1. SELECT语句务必指明字段名称（避免直接使用select * ）
  2. SQL语句要避免造成索引失效的写法
  3. 尽量用union all代替union，union all会展示重复的数据，而union会多一次过滤，效率低
  4. 避免在where子句中对字段进行表达式操作（可能会导致索引失效）
  5. Join优化 能用innerjoin 就不用left join right join，如必须使用 一定要以小表为驱动，内连接会对两个表进行优化，优先把小表放到外边，把大表放到里边。left join 或 right join，不会重新调整顺序

• 主从复制、读写分离

  如果数据库的使用场景读的操作比较多的时候，为了避免写的操作所造成的性能影响 可以采用读写分离的架构。读写分离解决的是，数据库的写入，影响了查询的效率。

• 分库分表

事务隔离级别

在数据库的并发控制中，事务隔离级别（Transaction Isolation Levels） 是为了平衡数据一致性与系统并发性能而设计的规范。

MySQL 的 InnoDB 存储引擎完全支持 SQL:1992 标准定义的四个隔离级别。

一、 并发事务带来的三大问题

在聊隔离级别之前，我们需要先了解如果不进行隔离，并发事务同时操作同一行数据会发生什么“惨案”：

1. 脏读 (Dirty Read)： 事务 A 读取了事务 B 还没提交的数据。如果事务 B 随后回滚，事务 A 读到的就是非法数据。
2. 不可重复读 (Non-repeatable Read)： 事务 A 在同一个事务内多次读取同一条数据，结果不一致。这是因为在两次读取之间，事务 B 修改并提交了该数据。
3. 幻读 (Phantom Read)： 事务 A 按某个范围查询数据，发现多了或少了几行。这是因为在查询期间，事务 B 插入或删除了符合条件的行并提交了。

二、 MySQL 的四大隔离级别

为了解决上述问题，隔离级别从低到高分为四层，级别越高，数据越安全，但性能开销也越大。

1. 读未提交 (Read Uncommitted)

• 特性： 一个事务可以读取到另一个未提交事务修改的数据。
• 存在问题： 脏读、不可重复读、幻读。
• 评价： 性能最高，但几乎没人用，安全性太低。

2. 读已提交 (Read Committed, RC)

• 特性： 只能读取到已经提交的数据。
• 解决问题： 解决了脏读。
• 存在问题： 不可重复读、幻读。
• 应用场景： 许多主流数据库（如 Oracle, SQL Server）的默认隔离级别。

3. 可重复读 (Repeatable Read, RR) — MySQL 默认级别

• 特性： 在同一个事务中，多次读取同一记录的结果是一致的。
• 解决问题： 解决了脏读、不可重复读。
• 特殊点： MySQL 的 InnoDB 通过 MVCC（多版本并发控制）和 Next-Key Locks 很大程度上解决了幻读问题。 这是它相比于标准 SQL 规范的强大之处。

4. 串行化 (Serializable)

• 特性： 所有的事务都按顺序执行。它会对读取的每一行数据都加锁（读写冲突）。
• 解决问题： 解决所有并发问题。
• 评价： 性能最差，通常只在对数据绝对敏感且并发量极低的场景下使用。

虽然 MySQL InnoDB 在 可重复读 (RR) 级别下通过 MVCC (多版本并发控制) 和 Next-Key Locks (临键锁) 已经解决了绝大多数场景下的幻读，但在一些特殊的并发操作序列下，幻读依然会“现身”。

我们可以把 InnoDB 解决幻读的方案分成两套“拳法”：

1. 快照读 (Snapshot Read)： 普通的 SELECT 语句。靠 MVCC 解决，它让你看到的是事务开始时的快照，别人新插的数据你看不到。
2. 当前读 (Current Read)： SELECT ... FOR UPDATE、UPDATE、DELETE 等。靠 Gap Lock (间隙锁) 解决，它会在范围内加锁，不准别人插新数据。

但当这两套拳法“混用”或者顺序不对时，幻读就钻了空子。

幻读依然发生的两个典型场景：

一、“后发制人”的更新操作 (最经典)

假设表 user 中原本没有 id=5 的记录。

• 事务 A： 先执行 SELECT * FROM user WHERE id=5。由于是快照读，结果是空。
• 事务 B： 插入一条 id=5 的数据并 提交。
• 事务 A： 此时执行 UPDATE user SET name='new' WHERE id=5。
  • 关键点： UPDATE 是当前读。它会去磁盘读最新的数据，结果它竟然发现并成功更新了事务 B 刚插进去的那行！
• 事务 A： 再次执行 SELECT * FROM user WHERE id=5。
  • 炸裂点： 根据 MVCC 的规则，一个事务能看到自己修改过的数据。因为事务 A 刚才更新了这行，它现在的版本号属于事务 A 了。于是，事务 A 的第二次查询竟然查出了这行数据！

结论： 在事务 A 看来，就像凭空变出来的一样，这就是幻读。

二、快照读切换到当前读

• 事务 A： 执行普通 SELECT 查询某个范围（快照读），没发现新行。
• 事务 B： 插入新行并 提交。
• 事务 A： 突然想给这些行加锁，执行了 SELECT ... FOR UPDATE（当前读）。
  • 结果： 由于当前读会读取数据库中最新的记录，事务 A 这一次查询会立刻看到事务 B 插入的数据。

结论： 同一个事务内，查询结果集变了。

什么是快照读和当前读？

简单来说，快照读（Snapshot Read）让你看到的是“过去”，而当前读（Current Read）让你看到的是“现在”。

在 MySQL InnoDB 引擎中，为了同时兼顾高并发性能和数据一致性，设计了这两套不同的读取机制。

一、 快照读 (Snapshot Read)

快照读就是普通的 SELECT 查询。它不需要加锁，而是通过 MVCC（多版本并发控制） 来实现。

• 核心逻辑： 它读取的是数据的“快照版本”。即便当前有其他事务在修改这些数据，快照读也会去 Undo Log（回滚日志） 里找之前的老版本，从而实现非阻塞的并发读。

• 适用场景： 普通的、对实时性要求不是极高的查询。

• 代表语句：

  SELECT * FROM table WHERE id = 1;
  

• 特点：

  • 不加锁： 性能极高，不会被其他事务的写操作阻塞。
  • 可见性受隔离级别影响：
    • RC（读已提交）： 每次执行 SELECT 都会生成一个新的快照，所以能读到别人刚提交的修改。
    • RR（可重复读）： 整个事务只在第一次 SELECT 时生成快照，后面再查都用同一个，所以能保证“可重复读”。

二、 当前读 (Current Read)

当前读是指读取数据库中最新、最真实的数据，并且为了防止在读取过程中数据被别人改掉，它会对读取的行进行加锁。

• 核心逻辑： 必须读取到磁盘上已经提交的最新的那一行记录，不能读回滚日志里的老版本。
• 适用场景： 涉及修改操作（更新、删除、插入）或者需要保证绝对数据实时的查询。
• 代表语句：
  1. SELECT ... FOR UPDATE (加排他锁/X锁)
  2. SELECT ... LOCK IN SHARE MODE (加共享锁/S锁)
  3. INSERT
  4. UPDATE
  5. DELETE
• 特点：
  • 加锁： 会阻塞其他事务对这些行的修改（或获取锁）。
  • 保证一致性： 强制读最新，不会因为版本快照而产生数据延迟。

三大log文件

在 MySQL（尤其是使用 InnoDB 存储引擎时）中，redolog、undolog 和 binlog 是保证数据库事务 ACID 特性、崩溃恢复和主备复制的核心机制。

三大日志概览

Redo Log：保证“不丢数据”的硬汉

作用： Redo Log 是为了实现事务的持久性（Durability）。当数据库宕机时，内存中尚未刷到磁盘的数据（脏页）会丢失，重启后通过 Redo Log 重新执行操作，确保数据不丢失。这就是所谓的 WAL（Write-Ahead Logging，预写日志） 技术。

• 产生时机： 只要有数据修改，就会先写到 redo log buffer，然后根据策略（如 innodb_flush_log_at_trx_commit）刷到磁盘文件。
• 清除时机： Redo Log 的大小是固定的（通常是几个文件组成的环形结构）。当日志对应的“脏页”已经被真正刷新到磁盘数据文件（.ibd）后，这部分日志就失效了，空间可以被覆盖重用。

Undo Log：后悔药与多版本管理

作用： Undo Log 主要负责原子性（Atomicity）和 MVCC（多版本并发控制）。

1. 回滚： 如果事务失败或执行了 ROLLBACK，MySQL 利用 Undo Log 将数据改回原来的样子（记录相反的操作：比如你执行了 INSERT，它记录一个 DELETE）。
2. MVCC： 当一个事务在读取数据时，如果有另一个事务正在修改，它可以通过 Undo Log 读取到之前的版本。

• 产生时机： 在事务开始修改数据之前，会先记录该行的原始状态到 Undo Log 中。
• 清除时机： 事务提交后，Undo Log 不会立刻删除。它需要等待 purge 线程 确认没有其他事务再需要这个版本（用于 MVCC）时，才会异步地进行清理。

Binlog：集群复制与数据溯源

作用： Binlog 记录了所有修改数据库结构的 DDL 和 DML 语句，属于 MySQL Server 层，与引擎无关。

1. 主从复制： Master 将 Binlog 发送给 Slave，Slave 重放实现数据同步。
2. 数据恢复： 如果数据库被误删，可以结合全备和 Binlog 进行“增量恢复”到指定时间点。

• 产生时机： 事务提交时，一次性将整个事务的日志写入 Binlog 文件。
• 清除时机： 通过配置项 expire_logs_days（或新版本的 binlog_expire_logs_seconds）设置保存天数。超过时间后，系统会自动删除旧文件。

MVCC

MVCC（Multi-Version Concurrency Control，多版本并发控制）是 MySQL InnoDB 存储引擎实现隔离级别（主要是 RC 读已提交 和 RR 可重复读）的核心机制。

串行化和读未提交这两个事务级别没有用到MVCC

简单来说，它的目的是：让数据库在处理读写冲突时，不用加锁也能保证数据的安全性，从而大幅提升并发性能。

MVCC 的核心实现原理

MVCC 的实现依赖于三个关键组件：隐藏列、Undo Log（回滚日志） 和 ReadView（一致性视图）。

隐藏列

InnoDB 在每行数据后面都会默默添加几个隐藏字段：

• DB_TRX_ID：最近修改这条数据的事务 ID。
• DB_ROLL_PTR：回滚指针，指向这条记录的上一个版本（存放在 Undo Log 中）。
• DB_ROW_ID：如果表没有主键，InnoDB 会自动生成的隐藏主键。

Undo Log（版本链）

当一个事务修改数据时，InnoDB 不会直接覆盖旧数据，而是先把旧数据写入 Undo Log。 通过隐藏列中的 DB_ROLL_PTR 指针，将这些旧版本的数据串联起来，形成一个版本链。

ReadView（一致性视图）

ReadView 是事务在进行“快照读”时产生的一个结构，它定义了哪些数据版本对当前事务是可见的。它包含四个核心字段：

1. m_ids：生成 ReadView 时，系统中当前正在活跃（未提交）的事务 ID 列表。
2. min_trx_id：活跃事务中最小的 ID。
3. max_trx_id：系统即将分配给下一个事务的 ID 值。
4. creator_trx_id：创建这个 ReadView 的事务 ID。

可见性判断规则

当事务想读某行数据时，会拿着该行当前的 trx_id 与 ReadView 进行比对：

1. trx_id == creator_trx_id：这个版本是我自己改的，可见。
2. trx_id < min_trx_id：说明这个事务在 ReadView 创建前已经提交了，可见。
3. trx_id >= max_trx_id：说明这个事务在 ReadView 创建后才启动，不可见。
4. min_trx_id <= trx_id < max_trx_id：
   • 如果 trx_id 在 m_ids 列表中：说明事务还没提交，不可见。
   • 如果不在：说明事务已提交，可见。

如果当前版本不可见，就顺着版本链（Undo Log）往回找，直到找到可见的版本。

图示：

下面我结合图片来解释这一个过程，图片主要参考的是黑马程序员的MySQL相关课程：

假设当前我有五个事务，他们同时开始，但是事务提交的时间不一致，如下图表格所示：

我们先来看一下Undo Log版本链的产生过程：

最开始我们的记录如图所示：

然后事务二开始了，它需要把id为30的数据的age改为3：

此时，InnoDB 会将旧版本数据写入 Undo Log，并让当前记录的 DB_ROLL_PTR 指向该快照，形成版本链。

接着事务三来了，它把id为30的数据的name改为A3,同样需要在UndoLog里产生一个快照记录。并调整指针的指向，最终如下图所示：

同样的道理，当事务四也修改了记录，所以也会有一个“快照记录”，我这里就直接给出最后的图：

不同的是事务或相同事务对同一条数据进行刘修改，会导致该记录的undolog生成一条记录版本的链表，链表的头部是最新的旧记录，链表的尾部是最早的旧记录。

到这里我觉得你肯定已经明白这个Undo Log版本链是如何产生的了，那么接下来我们来看看事务五的两个查询究竟会返回哪条记录！

回顾一下前面说的一致性视图（ReadView）有的地方也叫读视图，它是快照读SQL执行的时，MVCC提取数据的依据，记录并维护当前系统活跃的事务（未提交）的id。这个视图和隔离级别有一定的关系，比如在RC（Read Committed）级别下：每次select都会生成一个快照读。而在RR（Repeatable Read）开启事务后的第一个select语句才是产生快照读的地方。

ReadView维护了四个字段：

这里我来再说一下这个活跃的事务ID是啥意思，以我开始的那个表格为例：当我的事务五的第一个查询语句时刻，那个时刻，活跃的事务ID一共有3，4，5。因为事务一已经commit了。

我现在先以RC隔离级别来说一下这个ReadView是如何生成的：

在RC模式下，每次select都会有一个属于自己的ReadView。

然后获取记录，需要按照如下的规则，并结合开始版本链来完成，先看规则，规则如下：

现在我针对第一个读视图来，看一下它获取的是哪一条数据：

目前版本链中有 4 条记录（1 条当前记录，3 条在 Undo Log 中）。

ReadView 状态： m\_ids: \{3, 4, 5\}，min\_trx\_id: 3，max\_trx\_id: 6，creator\_trx\_id: 5。

我们从最新版本（当前记录）开始按顺序往后找：

1. 分析当前记录（trx\_id = 4）

• 规则①（是否是自己）： trx\_id(4) \neq creator\_trx\_id(5)，不是当前事务修改的。
• 规则②（是否已提交）： trx\_id(4) \nless min\_trx\_id(3)，说明该版本在 ReadView 生成时可能还未提交。
• 规则③（是否太新）： trx\_id(4) < max\_trx\_id(6)，说明该事务不是在 ReadView 生成后才开启的。
• 规则④（活跃事务判断）： 虽然 trx\_id 在 3 和 6 之间，但 4 \in m\_ids。结论： 说明 ReadView 生成时，事务 4 还处于“活跃未提交”状态，不可见。

2. 分析 Undo Log 版本链

• trx\_id = 3 的记录： 同理，虽然 3 < 6，但 3 \in m\_ids，说明事务 3 当时也未提交，不可见。
• trx\_id = 2 的记录： 此时 trx\_id(2) < min\_trx\_id(3)。
  • 结论： 根据规则 ②，该版本在 ReadView 生成前就已经提交，可见。

最终结果：第一个 ReadView 最终获取的是 事务 2 提交的数据。

其实这里我觉得去套这个公式有点蠢了，你自己看你的事务隔离级别，你事务隔离级别不是读已提交吗，那么ReadView读的肯定就是最新提交的数据呀。一眼就能判断出读取的是哪个数据。RC就是找事务比自己先开启的，并且已经提交的，就可以读。

同理：如果是在RR级别下，由于会复用第一次select产生的ReadView，所以无论你读多少次，都以第一次select到的数据为准。

RC 级别： 本质上就是“取最新已提交的版本”。每次 SELECT 都重新生成 ReadView，所以它能看到别人刚提交的修改。

RR 级别： 本质上是“静态快照”。只在第一次 SELECT 时生成 ReadView，后续无论别人怎么改，它都只认第一次看到的世界。

数据库主从同步

MySQL 的主从同步（Replication）是实现高可用、负载均衡和读写分离的核心机制。其核心原理可以概括为：主库（Master）记录变更日志，从库（Slave）读取并重放这些日志。

日志文件：

• Binary Log (Binlog)：存在于主库，记录了所有修改数据库结构的 DDL 和修改数据的 DML 操作。
• Relay Log (中继日志)：存在于从库，它是从主库拿过来的 Binlog 的临时“中转站”。

线程：

• Binlog Dump Thread (主库)：当从库连接时，主库会创建该线程，负责发送 Binlog 内容给从库。
• I/O Thread (从库)：负责连接主库，请求 Binlog 内容，并将其写入本地的 Relay Log。
• SQL Thread (从库)：负责读取 Relay Log 中的内容，并在从库本地执行，从而保持数据一致。

三种同步方式

分库分表

当单表数据量达到千万级，或者单库并发请求过高时，MySQL 的性能会显著下降。这时候就需要考虑分库分表。

分库分表的核心思想是：化整为零，分而治之。

1. 拆分的两个维度

分库分表通常分为“垂直拆分”和“水平拆分”两种方式：

垂直拆分（Vertical Splitting）

• 垂直分库：按业务模块将表拆分到不同的数据库中。例如：将用户表、订单表、商品表分别放在 user_db、order_db、product_db。
• 垂直分表：将一张表中的字段拆分到多张表中。通常将 高频访问列 和 低频/大字段列（如 text 类型的备注、详情）分开，以减少单行数据的体积。

水平拆分（Horizontal Splitting）

• 水平分表：表的结构不变，按某种规则将数据行存入不同的表中（如 order_0, order_1）。
• 水平分库：将不同的数据行存入不同的物理数据库实例中，主要解决单机高并发和磁盘 IO 的瓶颈。

2. 数据的分片策略（Sharding Strategy）

如何决定一条数据该去哪个表？常见的策略有：

1. 取模（Hash）：
   • 原理：user_id % 4，将数据均匀分布在 4 个分片。
   • 优点：数据分布均匀，不易产生热点。
   • 缺点：扩容极其麻烦（需要全量数据迁移）。
2. 范围（Range）：
   • 原理：按时间（如每月一张表）或按自增 ID 范围。
   • 优点：扩容简单，无需迁移历史数据。
   • 缺点：容易产生热点问题（比如最近一个月的数据会被疯狂读写，而老的表却很闲）。
3. 查找表（Map）：
   • 原理：在元数据库中记录每条数据对应的分片位置。虽然灵活，但维护成本高且有性能损耗。

3. 分库分表带来的技术挑战

这是面试和实际架构中最难的部分，因为拆分后会破坏原生数据库的特性：

• 分布式事务问题：原本一个事务就能解决的写操作，现在跨了库。通常需要引入 Seata 这种分布式事务中间件，或者使用 TCC、可靠消息最终一致性 等方案。
• 跨节点 Join 问题：无法直接在 SQL 里 Join 不同库的表。
  • 对策：字段冗余（空间换时间）、全局表（每个库都存一份小表）、在应用层（Java 代码）多次查询后组装。
• 分页与排序（Max/Count/Order By）：
  • 对策：需要在每个分片执行后，在中间件层面进行归并排序。如果偏移量（Offset）很大，性能会急剧下降。
• 全局唯一 ID：单表自增 ID 失效。
  • 对策：使用 雪花算法（Snowflake） 或分布式 ID 生成器。

4. 常见的中间件解决方案

目前主流的方案分为两类：

5. 什么时候该分库分表？

不要为了“高大上”而分。阿里巴巴开发手册建议：单表行数超过 500 万行或者单表容量超过 2GB 时才考虑。

在动手之前，应优先考虑以下顺序：

1. SQL 优化与索引优化。
2. 读写分离（利用主从架构缓解读压力）。
3. 缓存（Redis）。
4. 冷热数据分离（将历史旧数据归档）。
5. 最后才是分库分表

Redis面试常见题

缓存穿透

定义：查询一个不存在的数据，DB查询不到数据也不会直接写入缓存，就会导致每次请求都查数据库（如果有人恶意攻击，会击垮数据库）。

解决办法：

1. 缓存空数据，查询返回的数据为空，仍然把这个空结果进行缓存

   优点：实现简单。

   缺点：消耗内存，可能发生数据不一致的问题

2. 使用布隆过滤器

   优点：内存占用较少，没有多余key

   缺点：实现复杂，存在一定误判

布隆过滤器

布隆过滤器（Bloom Filter） 是一种非常节省空间的概率型数据结构，主要用于判断 “一个元素是否在一个集合中”。它的核心特点是：高效、省空间，但存在一定的误报率。

1. 核心原理

布隆过滤器的本质是一个 位数组（Bit Array） 和一系列 无偏哈希函数（Hash Functions）。

• 初始化：开始时，位数组的所有位都设为 0。

• 添加元素：当一个元素被加入集合时，通过多个哈希函数计算出多个索引值，并将位数组中对应这些索引的位置全部设为 1。

• 查询元素：查询时，同样用这些哈希函数计算索引。

  • 如果这些位置中有任何一个为 0，那么该元素一定不在集合中。
  • 如果这些位置全部为 1，那么该元素可能在集合中（也可能是因为其他多个元素凑巧把这些位置都染红了，这就是“误报”）。

为啥会误判？

缓存击穿

定义：给某一个key设置了过期时间，当key过期的时候，恰好这时间点对这个key有大量的并发请求过来，这些并发的请求可能会瞬间把DB压垮

解决方案：

1. 互斥锁：互斥地读取redis缓存，使得每次只能有一条请求，它没有找到数据后跨过缓存去数据库找数据，进行缓存重建。

   sequenceDiagram participant C as Client (客户端) participant R as Redis (缓存) participant L as Lock (分布式锁) participant DB as Database (数据库) C->>R: 1. 查询缓存 (Key) R-->>C: 返回空 (缓存失效/击穿) C->>L: 2. 尝试获取分布式锁 alt 获取锁成功 C->>R: 3. 二次检查 (Double Check) Note over C,R: 防止在拿锁期间其他线程已更新缓存 alt 缓存依然为空 C->>DB: 4. 查询数据库 DB-->>C: 返回数据 C->>R: 5. 回写缓存 (带过期时间) else 缓存已有数据 Note right of R: 直接使用新产生的缓存数据 end C->>L: 6. 释放分布式锁 C-->>C: 7. 返回结果给业务层 else 获取锁失败 C->>C: 8. 休眠等待 (如 50ms) C->>R: 9. 重试：重新查询缓存 R-->>C: 返回数据 (此时前序线程通常已填好) C-->>C: 10. 返回结果 end

2. 逻辑过期：会有一条请求拿了锁之后去开一个新线程尝试重建内存，请求不会等待，直接返回逻辑过期的数据

总结

优先选择“互斥锁”的场景：

• 对数据一致性要求极高：例如金融账户余额、库存精准扣减、活动起止时间等。
• 并发量大但可控：虽然有阻塞，但在配置好连接池和超时时间的情况下，系统可以承受。

优先选择“逻辑过期”的场景：

• 用户体验高于实时性：例如热点新闻浏览、社交平台大 V 的主页、商品详情页的非核心信息。这些场景下，用户多看几秒钟“半分钟前”的数据通常没关系，但如果页面转圈圈（阻塞等待）则无法接受。
• 极高并发请求：当瞬间流量大到排队重试会导致系统线程耗尽（雪崩隐患）时，逻辑过期这种“立即返回”的策略更为安全。

缓存雪崩

定义：缓存雪崩是指在同一时段大量的缓存key同时失效或者Redis服务宕机，导致大量请求到达数据库，带来巨大压力。

解决方案：

1. 给不同的Key的TTL添加随机值（就不会突然大量key同时失效了）
2. 利用Redis集群提高服务的可用性（哨兵模式、集群模式）
3. 给缓存业务添加降级限流策略（ngxin或spring cloud gateway，这个可以保底，三个都能用这个尝试解决
4. 给业务添加多级缓存（Guava或Caffeine）

缓存一致性

缓存一致性解决方案

Redis持久化

• RDB全称Redis Database Backup file（Redis数据备份文件），也被叫做Redis数据快照。简单来说就是把内存中的所有数据都记录到磁盘中。当Redis实例故障重启后，从磁盘读取快照文件，恢复数据
• AOF全称为Append Only File（追加文件）。Redis处理的每一个写命令都会记录在AOF文件，可以看做是命令日志文件。

RDB的执行原理

• bgsave开始时会fork主进程得到子进程，子进程共享主进程的内存数据（复制页表）。完成fork后读取内存数据并写入 RDB 文件。

• fork采用的是copy-on-write技术：

  • 当主进程执行读操作时，访问共享内存；
  • 当主进程执行写操作时，则会拷贝一份数据，执行写操作。

AOF

• AOF默认是关闭的，需要修改redis.conf配置文件来开启AOF
• AOF的命令记录的频率也可以通过redis.conf文件来配
• 因为是记录命令，AOF文件会比RDB文件大的多。而且AOF会记录对同一个key的多次写操作，但只有最后一次写操作才有意义。通过执行bgrewriteaof命令，可以让AOF文件执行重写功能，用最少的命令达到相同效果。

Redis AOF 配置项

# 是否开启AOF功能，默认是no
appendonly yes

# AOF文件的名称
appendfilename "appendonly.aof"

# 表示每执行一次写命令，立即记录到AOF文件
# appendfsync always

# 写命令执行完先放入AOF缓冲区，然后表示每隔1秒将缓冲区数据写到AOF文件，是默认方案
appendfsync everysec

# 写命令执行完先放入AOF缓冲区，由操作系统决定何时将缓冲区内容写回磁盘
# appendfsync no

AOF 刷盘策略对比表

bgrewriteaof命令触发设置

# AOF文件比上次文件 增长超过多少百分比则触发重写
auto-aof-rewrite-percentage 100

# AOF文件体积最小多大以上才触发重写
auto-aof-rewrite-min-size 64mb

默认选择：在生产环境下，Redis 官方默认推荐使用 everysec，因为它在性能和可靠性之间取得了极佳的平衡。

配合 RDB 使用：通常建议将 AOF 与 RDB 快照配合使用，以获得更快的故障恢复速度和更高的数据安全性。

总结

RDB 与 AOF 持久化方式对比

Redis过期策略

惰性删除

• **定义：**设置该key过期时间后，我们不去管它，当需要该key时，我们在检查其是否过期，如果过期，我们就删掉它，反之返回该key
• 优点 ：对CPU友好，只会在使用该key时才会进行过期检查，对于很多用不到的key不用浪费时间进行过期检查
• 缺点 ：对内存不友好，如果一个key已经过期，但是一直没有使用，那么该key就会一直存在内存中，内存永远不会释放

定期删除

• **定义：**每隔一段时间，我们就对一些key进行检查，删除里面过期的key(从一定数量的数据库中取出一定数量的随机key进行检查，并删除其中的过期key)。
• SLOW模式是定时任务，执行频率默认为10hz，每次不超过25ms，以通过修改配置文件redis.conf 的hz 选项来调整这个次数
• FAST模式执行频率不固定，但两次间隔不低于2ms，每次耗时不超过1ms
• 优点：可以通过限制删除操作执行的时长和频率来减少删除操作对 CPU 的影响。另外定期删除，也能有效释放过期键占用的内存。
• 缺点：难以确定删除操作执行的时长和频率。

数据的淘汰策略

当Redis中的内存不够用时，此时在向Redis中添加新的key，那么Redis就会按照某一种规则将内存中的数据删除掉，这种数据的删除规则被称之为内存的淘汰策略。

• noeviction： 不淘汰任何key，但是内存满时不允许写入新数据，默认就是这种策略。
• volatile-ttl： 对设置了TTL的key，比较key的剩余TTL值，TTL越小越先被淘汰
• allkeys-random：对全体key ，随机进行淘汰。
• volatile-random：对设置了TTL的key ，随机进行淘汰。
• allkeys-lru： 对全体key，基于LRU算法进行淘汰
• volatile-lru： 对设置了TTL的key，基于LRU算法进行淘汰
• allkeys-lfu： 对全体key，基于LFU算法进行淘汰
• volatile-lfu： 对设置了TTL的key，基于LFU算法进行淘汰

数据的淘汰策略使用建议

• 优先使用 allkeys-lru 策略。充分利用 LRU 算法的优势，把最近最常访问的数据留在缓存中。如果业务有明显的冷热数据区分，建议使用。
• 如果业务中数据访问频率差别不大，没有明显冷热数据区分，建议使用 allkeys-random，随机选择淘汰。
• 如果业务中有置顶的需求，可以使用 volatile-lru 策略，同时置顶数据不设置过期时间，这些数据就一直不被删除，会淘汰其他设置过期时间的数据。
• 如果业务中有短时高频访问的数据，可以使用 allkeys-lfu 或 volatile-lfu 策略。

Redisson

• 底层是setnx和lua脚本（保证原子性）
• 获取锁：SET lock value NX EX 10 ，注意：NX是互斥、EX是设置超时时间
• *释放锁：*DEL key
• 超时事件可以自己设置控制；也可以靠看门狗帮忙做续期
• redisson实现的分布式锁-可重入（同一线程可以获取同一把锁，会记录重入次数，重入次数到0才会删除这个锁）

redisson实现的分布式锁

注意：主从一致性问题，Redisson无法解决主从一致性问题。

为啥会出现主从一致性问题？

Redis 的主从复制是异步的。这就导致了一个潜在的“锁丢失”风险：

1. 客户端 A 在 Redis 主节点（Master）上成功获取了锁。
2. 主节点在将这个锁的数据同步给从节点（Slave）之前，突然宕机了。
3. 从节点被哨兵提升为新的主节点。
4. 客户端 B 请求获取同一个锁，由于新主节点上没有该锁的数据，客户端 B 也能获取成功。

此时，系统中同时有两个客户端持有同一把锁，分布式锁的互斥性宣告失效。

如何解决？

Redisson 提供了两种主要的思路来应对这个问题：

1. Wait 机制（不常用）

   Redisson 允许在发送命令后使用 WAIT 命令，要求主节点必须将数据同步到指定数量的从节点后才返回成功。虽然提高了可靠性，但牺牲了性能，且在极端网络分区下仍有风险。

2. 红锁算法（Redlock）—— 不推荐

   红锁不再依赖“主从架构”，而是要求部署 N 个完全独立的 Redis 节点（通常为 5 个，这些节点之间没有任何主从关系）。

   1. 获取时间戳：客户端获取当前系统时间。
   2. 轮询加锁：客户端尝试在 N 个节点上依次申请加锁。加锁时使用很短的超时时间（比如几十毫秒），防止在某个宕机的节点上耗时太久。
   3. 过半成功原则：只有当客户端在大多数（​N/2 + 1）节点上加锁成功，且总耗时小于锁的有效期时，才认为最终获取锁成功。
   4. 计算有效期：实际锁的有效时间 = 初始有效时间 - 加锁消耗的时间。
   5. 失败释放：如果获取锁失败，客户端必须向所有节点发起解锁请求（即使有些节点加锁没成功）。

但是红锁有如下缺点，所有目前官方不推荐使用红锁来解决：

1. 运维成本：维护 5 个独立的 Redis 实例非常麻烦。
2. 性能损耗：多次网络交互会导致延迟增加。
3. 实际场景：大多数业务场景下，主从切换导致的瞬时锁丢失可以通过业务幂等性或数据库唯一索引来兜底。

若要强一致性，可以使用zookeeper这种CP模式的分布式锁：

Redis 分布式锁的核心设计目标是 AP（可用性），而 ZooKeeper 的核心设计目标是 CP（一致性）。在 ZK 中，只要写入成功，就意味着超过半数节点已同步，且 Leader 宕机后，只有数据最新的节点才能当选新 Leader，因此不会出现类似 Redis 主从异步复制导致的锁丢失问题。

ZooKeeper 实现分布式锁的原理

ZK 实现分布式锁主要依赖其 临时顺序节点（Ephemeral Sequential Nodes） 和 监听机制（Watcher）。

核心步骤：

1. 创建父节点：在 ZK 中创建一个持久节点 /MyLock。

2. 创建临时顺序节点：每个尝试加锁的客户端，都会在 /MyLock 下创建一个临时顺序节点。

   • 客户端 A 创建节点 /MyLock/lock-0000001
   • 客户端 B 创建节点 /MyLock/lock-0000002

3. 判断最小节点：客户端获取 /MyLock 下的所有子节点，判断自己创建的节点序号是否是最小的。

   • 如果是最小的，则获得锁。
   • 如果不是最小的，则等待锁。

4. 监听前一个节点：关键点在于： 没拿到锁的客户端不会轮询，而是向它序号前一个的节点注册一个 Watcher 监听。

5. 释放锁：当持有锁的客户端操作完成或意外断开连接（Session 超时）时，该临时节点会自动删除。

6. 触发回调：ZK 通知监听了该节点的后续客户端。后续客户端再次检查自己是否为最小节点，如果是，则获取锁。

为什么 ZK 能保证强一致性？

• 顺序性：ZK 保证所有的更新操作都是全局有序的。
• 非异步丢失：ZK 使用 ZAB 协议，只有过半节点写入成功才会返回确认。
• 自动释放：由于使用的是“临时节点”，如果客户端所在的服务器挂了，ZK 感知到 Session 断开会立刻删除节点，从而自动释放锁，避免死锁。
• 无羊群效应：每个节点只监听前一个节点，当锁释放时，只会唤醒一个客户端，不会造成全集群的惊群效应（Thundering Herd）。

Redis主从复制

单节点Redis的并发能力是有上限的，要进一步提高Redis的并发能力，就需要搭建主从集群，实现读写分离。

全量同步

关键步骤解析：

• Replication Id (replid): 数据集的标记。如果 Slave 的 replid 与 Master 不一致，说明是第一次同步或需要全量同步。
• Offset (偏移量): 随着 repl_baklog 中数据的增多而增大。如果 Slave 的 offset 小于 Master，说明数据落后，需要更新。
• RDB 生成与传输: Master 在后台生成快照（bgsave），并将其发送给 Slave。这是最耗时的阶段。
• repl_baklog: 在生成和传输 RDB 文件的过程中，新产生的写命令会被缓存在这个日志中，确保 Slave 在加载完 RDB 后能补全这段时间的增量数据。

增量同步

流程要点分析：

• 触发条件：主要用于 Slave 节点重启或网络闪断后恢复连接的情况。
• psync 命令：Slave 会主动告知 Master 自己目前的 replid 和已经同步到的 offset（偏移量）。
• 判断逻辑：Master 检查 replid 是否匹配。如果一致，且请求的 offset 仍在 Master 的 repl_baklog（积压缓冲区）范围内，则执行增量同步。
• 效率优势：相比全量同步（需要生成和传输巨大的 RDB 文件），增量同步只传输断开期间缺失的少量写命令，极大地降低了带宽消耗和系统压力。

Redis哨兵模式（其实不常用）

Redis提供了哨兵（Sentinel）机制来实现主从集群的自动故障恢复

• 监控：Sentinel 会不断检查您的master和slave是否按预期工作
• 自动故障恢复：如果master故障，Sentinel会将一个slave提升为master。当故障实例恢复后也以新的master为主
• 通知：Sentinel充当Redis客户端的服务发现来源，当集群发生故障转移时，会将最新信息推送给Redis的客户端
• Sentinel基于心跳机制监测服务状态，每隔1秒向集群的每个实例发送ping命令
• 主观下线：如果某sentinel节点发现某实例未在规定时间响应，则认为该实例主观下线。
• 客观下线：若超过指定数量（quorum）的sentinel都认为该实例主观下线，则该实例客观下线。quorum值最好超过Sentinel实例数量的一半。

哨兵选主规则

• 首先判断主与从节点断开时间长短，如超过指定值就排该从节点
• 然后判断从节点的slave-priority值，越小优先级越高
• 如果slave-prority一样，则判断slave节点的offset值，越大优先级越高
• 最后是判断slave节点的运行id大小，越小优先级越高。

redis集群（哨兵模式）脑裂

• 集群脑裂是由于主节点和从节点和sentinel处于不同的网络分区，使得sentinel没有能够心跳感知到主节点，所以通过选举的方式提升了一个从节点为主，这样就存在了两个master，就像大脑分裂了一样，这样会导致客户端还在老的主节点那里写入数据，新节点无法同步数据，当网络恢复后，sentinel会将老的主节点降为从节点，这时再从新master同步数据，就会导致数据丢失
• **解决：**我们可以修改redis的配置，可以设置最少的从节点数量以及缩短主从数据同步的延迟时间，达不到要求就拒绝请求，就可以避免大量的数据丢失

Redis分片集群结构

主从和哨兵可以解决高可用、高并发读的问题。但是依然有两个问题没有解决

• 海量数据存储问题
• 高并发写的问题

使用分片集群可以解决上述问题，分片集群特征

• 集群中有多个master，每个master保存不同数据
• 每个master都可以有多个slave节点
• master之间通过ping监测彼此健康状态
• 客户端请求可以访问集群任意节点，最终都会被转发到正确节点（自动路由）

分片集群结构-数据读写

• Redis 分片集群引入了哈希槽的概念，Redis 集群有 16384 个哈希槽，每个 key通过 CRC16 校验后对 16384 取模来决定放置哪个槽，集群的每个节点负责一部分 hash 槽。

Redis是单线程的，为什么还那么快

• redis是纯内存操作，执行速度非常快
• 采用单线程，避免不必要的上下文切换可竞争条件，多线程还要考虑线程安全问题
• 使用I/O多路复用模型，非阻塞IO
• Redis是纯内存操作，执行速度非常快，它的性能瓶颈是网络延迟而不是执行速度， I/O多路复用模型主要就是实现了高效的网络请求

I/O模型

• 阻塞IO：阻塞IO模型中，用户进程在两个阶段都是阻塞状态。
• 非阻塞IO：非阻塞IO模型中，用户进程在第一个阶段是非阻塞，第二个阶段是阻塞状态。虽然是非阻塞，但性能并没有得到提高。而且忙等机制会导致CPU空转，CPU使用率暴增。
• IO多路复用

阻塞IO

非阻塞IO

IO多路复用

• 概念：是利用单个线程来同时监听多个Socket ，并在某个Socket可读、可写时得到通知，从而避免无效的等待，充分利用CPU资源。

• 实现：不过监听Socket的方式、通知的方式有多种实现

  • select
  • poll
  • epoll

• 差异

  • select和poll只会通知用户进程有Socket就绪，但不确定具体是哪个Socket ，需要用户进程逐个遍历Socket来确认

Redis网络模型：就是使用I/O多路复用结合事件的处理器来应对多个Socket请求

• 连接应答处理器
• 命令回复处理器，在Redis6.0之后，为了提升更好的性能，使用了多线程来处理回复事件
• 命令请求处理器，在Redis6.0之后，将命令的转换使用了多线程，增加命令转换速度，在命令执行的时候，依然是单线程

Redis网络模型

Java之JUC学习--part5

无锁

CAS

原理

无锁编程：Lock Free

CAS 的全称是 Compare-And-Swap，是 CPU 并发原语

• CAS 并发原语体现在 Java 语言中就是 sun.misc.Unsafe 类的各个方法，调用 UnSafe 类中的 CAS 方法，JVM 会实现出 CAS 汇编指令，这是一种完全依赖于硬件的功能，实现了原子操作
• CAS 是一种系统原语，原语属于操作系统范畴，是由若干条指令组成 ，用于完成某个功能的一个过程，并且原语的执行必须是连续的，执行过程中不允许被中断，所以 CAS 是一条 CPU 的原子指令，不会造成数据不一致的问题，是线程安全的

底层原理：CAS 的底层是 lock cmpxchg 指令（X86 架构），在单核和多核 CPU 下都能够保证比较交换的原子性

• 程序是在单核处理器上运行，会省略 lock 前缀，单处理器自身会维护处理器内的顺序一致性，不需要 lock 前缀的内存屏障效果

• 程序是在多核处理器上运行，会为 cmpxchg 指令加上 lock 前缀。当某个核执行到带 lock 的指令时，CPU 会执行总线锁定或缓存锁定，将修改的变量写入到主存，这个过程不会被线程的调度机制所打断，保证了多个线程对内存操作的原子性

作用：比较当前工作内存中的值和主物理内存中的值，如果相同则执行规定操作，否则继续比较直到主内存和工作内存的值一致为止

CAS 特点：

• CAS 体现的是无锁并发、无阻塞并发，线程不会陷入阻塞，线程不需要频繁切换状态（上下文切换，系统调用）
• CAS 是基于乐观锁的思想

CAS 缺点：

• 执行的是循环操作，如果比较不成功一直在循环，最差的情况某个线程一直取到的值和预期值都不一样，就会无限循环导致饥饿，使用 CAS 线程数不要超过 CPU 的核心数，采用分段 CAS 和自动迁移机制
• 只能保证一个共享变量的原子操作
  • 对于一个共享变量执行操作时，可以通过循环 CAS 的方式来保证原子操作
  • 对于多个共享变量操作时，循环 CAS 就无法保证操作的原子性，这个时候只能用锁来保证原子性
• 引出来 ABA 问题

乐观锁

CAS 与 synchronized 总结：

• synchronized 是从悲观的角度出发：总是假设最坏的情况，每次去拿数据的时候都认为别人会修改，所以每次在拿数据的时候都会上锁，这样别人想拿这个数据就会阻塞（共享资源每次只给一个线程使用，其它线程阻塞，用完后再把资源转让给其它线程），因此 synchronized 也称之为悲观锁，ReentrantLock 也是一种悲观锁，性能较差
• CAS 是从乐观的角度出发：总是假设最好的情况，每次去拿数据的时候都认为别人不会修改，所以不会上锁，但是在更新的时候会判断一下在此期间别人有没有去更新这个数据。如果别人修改过，则获取现在最新的值，如果别人没修改过，直接修改共享数据的值，CAS 这种机制也称之为乐观锁，综合性能较好

Atomic

常用API

常见原子类：AtomicInteger、AtomicBoolean、AtomicLong

构造方法：

• public AtomicInteger()：初始化一个默认值为 0 的原子型 Integer
• public AtomicInteger(int initialValue)：初始化一个指定值的原子型 Integer

常用API：

原理分析

AtomicInteger 原理：自旋锁 + CAS 算法

CAS 算法：有 3 个操作数（内存值 V， 旧的预期值 A，要修改的值 B）

• 当旧的预期值 A == 内存值 V 此时可以修改，将 V 改为 B
• 当旧的预期值 A != 内存值 V 此时不能修改，并重新获取现在的最新值，重新获取的动作就是自旋

分析 getAndSet 方法：

• AtomicInteger：

  public final int getAndSet(int newValue) {
      /**
      * this: 		当前对象
      * valueOffset:	内存偏移量，内存地址
      */
      return unsafe.getAndSetInt(this, valueOffset, newValue);
  }
  

  valueOffset：偏移量表示该变量值相对于当前对象地址的偏移，Unsafe 就是根据内存偏移地址获取数据

  valueOffset = unsafe.objectFieldOffset
                  (AtomicInteger.class.getDeclaredField("value"));
  //调用本地方法   -->
  public native long objectFieldOffset(Field var1);
  

• unsafe 类：

  // val1: AtomicInteger对象本身，var2: 该对象值得引用地址，var4: 需要变动的数
  public final int getAndSetInt(Object var1, long var2, int var4) {
      int var5;
      do {
          // var5: 用 var1 和 var2 找到的内存中的真实值
          var5 = this.getIntVolatile(var1, var2);
      } while(!this.compareAndSwapInt(var1, var2, var5, var4));
  
      return var5;
  }
  

  var5：从主内存中拷贝到工作内存中的值（每次都要从主内存拿到最新的值到本地内存），然后执行 compareAndSwapInt() 再和主内存的值进行比较，假设方法返回 false，那么就一直执行 while 方法，直到期望的值和真实值一样，修改数据

• 变量 value 用 volatile 修饰，保证了多线程之间的内存可见性，避免线程从工作缓存中获取失效的变量

  private volatile int value
  

  CAS 必须借助 volatile 才能读取到共享变量的最新值来实现比较并交换的效果

分析 getAndUpdate 方法：

• getAndUpdate：

  public final int getAndUpdate(IntUnaryOperator updateFunction) {
      int prev, next;
      do {
          prev = get();	//当前值，cas的期望值
          next = updateFunction.applyAsInt(prev);//期望值更新到该值
      } while (!compareAndSet(prev, next));//自旋
      return prev;
  }
  

• compareAndSet：

  public final boolean compareAndSet(int expect, int update) {
      /**
      * this: 		当前对象
      * valueOffset:	内存偏移量，内存地址
      * expect:		期望的值
      * update: 		更新的值
      */
      return unsafe.compareAndSwapInt(this, valueOffset, expect, update);
  }
  

原子引用

原子引用：对 Object 进行原子操作，提供一种读和写都是原子性的对象引用变量

原子引用类：AtomicReference、AtomicStampedReference、AtomicMarkableReference

AtomicReference 类：

• 构造方法：AtomicReference<T> atomicReference = new AtomicReference<T>()

• 常用 API：

  • public final boolean compareAndSet(V expectedValue, V newValue)：CAS 操作
  • public final void set(V newValue)：将值设置为 newValue
  • public final V get()：返回当前值

public class AtomicReferenceDemo {
    public static void main(String[] args) {
        Student s1 = new Student(33, "z3");
        
        // 创建原子引用包装类
        AtomicReference<Student> atomicReference = new AtomicReference<>();
        // 设置主内存共享变量为s1
        atomicReference.set(s1);

        // 比较并交换，如果现在主物理内存的值为 z3，那么交换成 l4
        while (true) {
            Student s2 = new Student(44, "l4");
            if (atomicReference.compareAndSet(s1, s2)) {
                break;
            }
        }
        System.out.println(atomicReference.get());
    }
}

class Student {
    private int id;
    private String name;
    //。。。。
}

原子数组

原子数组类：AtomicIntegerArray、AtomicLongArray、AtomicReferenceArray

AtomicIntegerArray 类方法：

/**
*   i		the index
* expect 	the expected value
* update 	the new value
*/
public final boolean compareAndSet(int i, int expect, int update) {
    return compareAndSetRaw(checkedByteOffset(i), expect, update);
}

原子更新器

原子更新器类：AtomicReferenceFieldUpdater、AtomicIntegerFieldUpdater、AtomicLongFieldUpdater

利用字段更新器，可以针对对象的某个域（Field）进行原子操作，只能配合 volatile 修饰的字段使用，否则会出现异常 IllegalArgumentException: Must be volatile type

常用 API：

• static <U> AtomicIntegerFieldUpdater<U> newUpdater(Class<U> c, String fieldName)：构造方法
• abstract boolean compareAndSet(T obj, int expect, int update)：CAS

public class UpdateDemo {
    private volatile int field;
    
    public static void main(String[] args) {
        AtomicIntegerFieldUpdater fieldUpdater = AtomicIntegerFieldUpdater
            		.newUpdater(UpdateDemo.class, "field");
        UpdateDemo updateDemo = new UpdateDemo();
        fieldUpdater.compareAndSet(updateDemo, 0, 10);
        System.out.println(updateDemo.field);//10
    }
}

原子累加器

原子累加器类：LongAdder、DoubleAdder、LongAccumulator、DoubleAccumulator

LongAdder 和 LongAccumulator 区别：

相同点：

• LongAddr 与 LongAccumulator 类都是使用非阻塞算法 CAS 实现的
• LongAddr 类是 LongAccumulator 类的一个特例，只是 LongAccumulator 提供了更强大的功能，可以自定义累加规则，当accumulatorFunction 为 null 时就等价于 LongAddr

不同点：

• 调用 casBase 时，LongAccumulator 使用 function.applyAsLong(b = base, x) 来计算，LongAddr 使用 casBase(b = base, b + x)

• LongAccumulator 类功能更加强大，构造方法参数中

  • accumulatorFunction 是一个双目运算器接口，可以指定累加规则，比如累加或者相乘，其根据输入的两个参数返回一个计算值，LongAdder 内置累加规则
  • identity 则是 LongAccumulator 累加器的初始值，LongAccumulator 可以为累加器提供非0的初始值，而 LongAdder 只能提供默认的 0

Adder

优化机制

LongAdder 是 Java8 提供的类，跟 AtomicLong 有相同的效果，但对 CAS 机制进行了优化，尝试使用分段 CAS 以及自动分段迁移的方式来大幅度提升多线程高并发执行 CAS 操作的性能

CAS 底层实现是在一个循环中不断地尝试修改目标值，直到修改成功。如果竞争不激烈修改成功率很高，否则失败率很高，失败后这些重复的原子性操作会耗费性能（导致大量线程空循环，自旋转）

优化核心思想：数据分离，将 AtomicLong 的单点的更新压力分担到各个节点，空间换时间，在低并发的时候直接更新，可以保障和 AtomicLong 的性能基本一致，而在高并发的时候通过分散减少竞争，提高了性能

分段 CAS 机制：

• 在发生竞争时，创建 Cell 数组用于将不同线程的操作离散（通过 hash 等算法映射）到不同的节点上
• 设置多个累加单元（会根据需要扩容，最大为 CPU 核数），Therad-0 累加 Cell[0]，而 Thread-1 累加 Cell[1] 等，最后将结果汇总
• 在累加时操作的不同的 Cell 变量，因此减少了 CAS 重试失败，从而提高性能

自动分段迁移机制：某个 Cell 的 value 执行 CAS 失败，就会自动寻找另一个 Cell 分段内的 value 值进行 CAS 操作

伪共享

Cell 为累加单元：数组访问索引是通过 Thread 里的 threadLocalRandomProbe 域取模实现的，这个域是 ThreadLocalRandom 更新的

// Striped64.Cell
@sun.misc.Contended static final class Cell {
    volatile long value;
    Cell(long x) { value = x; }
    // 用 cas 方式进行累加, prev 表示旧值, next 表示新值
    final boolean cas(long prev, long next) {
    	return UNSAFE.compareAndSwapLong(this, valueOffset, prev, next);
    }
    // 省略不重要代码
}

Cell 是数组形式，在内存中是连续存储的，64 位系统中，一个 Cell 为 24 字节（16 字节的对象头和 8 字节的 value），每一个 cache line 为 64 字节，因此缓存行可以存下 2 个的 Cell 对象，当 Core-0 要修改 Cell[0]、Core-1 要修改 Cell[1]，无论谁修改成功都会导致当前缓存行失效，从而导致对方的数据失效，需要重新去主存获取，影响效率

@sun.misc.Contended：防止缓存行伪共享，在使用此注解的对象或字段的前后各增加 128 字节大小的 padding，使用 2 倍于大多数硬件缓存行让 CPU 将对象预读至缓存时占用不同的缓存行，这样就不会造成对方缓存行的失效

源码解析

Striped64 类成员属性：

// 表示当前计算机CPU数量
static final int NCPU = Runtime.getRuntime().availableProcessors()
// 累加单元数组, 懒惰初始化
transient volatile Cell[] cells;
// 基础值, 如果没有竞争, 则用 cas 累加这个域，当 cells 扩容时，也会将数据写到 base 中
transient volatile long base;
// 在 cells 初始化或扩容时只能有一个线程执行, 通过 CAS 更新 cellsBusy 置为 1 来实现一个锁
transient volatile int cellsBusy;

工作流程：

• cells 占用内存是相对比较大的，是惰性加载的，在无竞争或者其他线程正在初始化 cells 数组的情况下，直接更新 base 域

• 在第一次发生竞争时（casBase 失败）会创建一个大小为 2 的 cells 数组，将当前累加的值包装为 Cell 对象，放入映射的槽位上

• 分段累加的过程中，如果当前线程对应的 cells 槽位为空，就会新建 Cell 填充，如果出现竞争，就会重新计算线程对应的槽位，继续自旋尝试修改

• 分段迁移后还出现竞争就会扩容 cells 数组长度为原来的两倍，然后 rehash，数组长度总是 2 的 n 次幂，默认最大为 CPU 核数，但是可以超过，如果核数是 6 核，数组最长是 8

方法分析：

• LongAdder#add：累加方法

  public void add(long x) {
      // as 为累加单元数组的引用，b 为基础值，v 表示期望值
      // m 表示 cells 数组的长度 - 1，a 表示当前线程命中的 cell 单元格
      Cell[] as; long b, v; int m; Cell a;
      
      // cells 不为空说明 cells 已经被初始化，线程发生了竞争，去更新对应的 cell 槽位
      // 进入 || 后的逻辑去更新 base 域，更新失败表示发生竞争进入条件
      if ((as = cells) != null || !casBase(b = base, b + x)) {
          // uncontended 为 true 表示 cell 没有竞争
          boolean uncontended = true;
          
          // 条件一: true 说明 cells 未初始化，多线程写 base 发生竞争需要进行初始化 cells 数组
          //		  fasle 说明 cells 已经初始化，进行下一个条件寻找自己的 cell 去累加
          // 条件二: getProbe() 获取 hash 值，& m 的逻辑和 HashMap 的逻辑相同，保证散列的均匀性
          // 		  true 说明当前线程对应下标的 cell 为空，需要创建 cell
          //        false 说明当前线程对应的 cell 不为空，进行下一个条件【将 x 值累加到对应的 cell 中】
          // 条件三: 有取反符号，false 说明 cas 成功，直接返回，true 说明失败，当前线程对应的 cell 有竞争
          if (as == null || (m = as.length - 1) < 0 ||
              (a = as[getProbe() & m]) == null ||
              !(uncontended = a.cas(v = a.value, v + x)))
              longAccumulate(x, null, uncontended);
          	// 【uncontended 在对应的 cell 上累加失败的时候才为 false，其余情况均为 true】
      }
  }
  

• Striped64#longAccumulate：cell 数组创建

  							// x  			null 			false | true
  final void longAccumulate(long x, LongBinaryOperator fn, boolean wasUncontended) {
      int h;
      // 当前线程还没有对应的 cell, 需要随机生成一个 hash 值用来将当前线程绑定到 cell
      if ((h = getProbe()) == 0) {
          // 初始化 probe，获取 hash 值
          ThreadLocalRandom.current(); 
          h = getProbe();	
          // 默认情况下 当前线程肯定是写入到了 cells[0] 位置，不把它当做一次真正的竞争
          wasUncontended = true;
      }
      // 表示【扩容意向】，false 一定不会扩容，true 可能会扩容
      boolean collide = false; 
      //自旋
      for (;;) {
          // as 表示cells引用，a 表示当前线程命中的 cell，n 表示 cells 数组长度，v 表示 期望值
          Cell[] as; Cell a; int n; long v;
          // 【CASE1】: 表示 cells 已经初始化了，当前线程应该将数据写入到对应的 cell 中
          if ((as = cells) != null && (n = as.length) > 0) {
              // CASE1.1: true 表示当前线程对应的索引下标的 Cell 为 null，需要创建 new Cell
              if ((a = as[(n - 1) & h]) == null) {
                  // 判断 cellsBusy 是否被锁
                  if (cellsBusy == 0) {   
                      // 创建 cell, 初始累加值为 x
                      Cell r = new Cell(x);  
                      // 加锁
                      if (cellsBusy == 0 && casCellsBusy()) {
                          // 创建成功标记，进入【创建 cell 逻辑】
                          boolean created = false;	
                          try {
                              Cell[] rs; int m, j;
                              // 把当前 cells 数组赋值给 rs，并且不为 null
                              if ((rs = cells) != null &&
                                  (m = rs.length) > 0 &&
                                  // 再次判断防止其它线程初始化过该位置，当前线程再次初始化该位置会造成数据丢失
                                  // 因为这里是线程安全的判断，进行的逻辑不会被其他线程影响
                                  rs[j = (m - 1) & h] == null) {
                                  // 把新创建的 cell 填充至当前位置
                                  rs[j] = r;
                                  created = true;	// 表示创建完成
                              }
                          } finally {
                              cellsBusy = 0;		// 解锁
                          }
                          if (created)			// true 表示创建完成，可以推出循环了
                              break;
                          continue;
                      }
                  }
                  collide = false;
              }
              // CASE1.2: 条件成立说明线程对应的 cell 有竞争, 改变线程对应的 cell 来重试 cas
              else if (!wasUncontended)
                  wasUncontended = true;
              // CASE 1.3: 当前线程 rehash 过，如果新命中的 cell 不为空，就尝试累加，false 说明新命中也有竞争
              else if (a.cas(v = a.value, ((fn == null) ? v + x : fn.applyAsLong(v, x))))
                  break;
              // CASE 1.4: cells 长度已经超过了最大长度 CPU 内核的数量或者已经扩容
              else if (n >= NCPU || cells != as)
                  collide = false; 		// 扩容意向改为false，【表示不能扩容了】
              // CASE 1.5: 更改扩容意向，如果 n >= NCPU，这里就永远不会执行到，case1.4 永远先于 1.5 执行
              else if (!collide)
                  collide = true;
              // CASE 1.6: 【扩容逻辑】，进行加锁
              else if (cellsBusy == 0 && casCellsBusy()) {
                  try {
                      // 线程安全的检查，防止期间被其他线程扩容了
                      if (cells == as) {     
                          // 扩容为以前的 2 倍
                          Cell[] rs = new Cell[n << 1];
                          // 遍历移动值
                          for (int i = 0; i < n; ++i)
                              rs[i] = as[i];
                          // 把扩容后的引用给 cells
                          cells = rs;
                      }
                  } finally {
                      cellsBusy = 0;	// 解锁
                  }
                  collide = false;	// 扩容意向改为 false，表示不扩容了
                  continue;
              }
              // 重置当前线程 Hash 值，这就是【分段迁移机制】
              h = advanceProbe(h);
          }
  
          // 【CASE2】: 运行到这说明 cells 还未初始化，as 为null
          // 判断是否没有加锁，没有加锁就用 CAS 加锁
          // 条件二判断是否其它线程在当前线程给 as 赋值之后修改了 cells，这里不是线程安全的判断
          else if (cellsBusy == 0 && cells == as && casCellsBusy()) {
              // 初始化标志，开始 【初始化 cells 数组】
              boolean init = false;
              try { 
                 	// 再次判断 cells == as 防止其它线程已经提前初始化了，当前线程再次初始化导致丢失数据
                  // 因为这里是【线程安全的，重新检查，经典 DCL】
                  if (cells == as) {
                      Cell[] rs = new Cell[2];	// 初始化数组大小为2
                      rs[h & 1] = new Cell(x);	// 填充线程对应的cell
                      cells = rs;
                      init = true;				// 初始化成功，标记置为 true
                  }
              } finally {
                  cellsBusy = 0;					// 解锁啊
              }
              if (init)
                  break;							// 初始化成功直接跳出自旋
          }
          // 【CASE3】: 运行到这说明其他线程在初始化 cells，当前线程将值累加到 base，累加成功直接结束自旋
          else if (casBase(v = base, ((fn == null) ? v + x :
                                      fn.applyAsLong(v, x))))
              break; 
      }
  }
  

• sum：获取最终结果通过 sum 整合，保证最终一致性，不保证强一致性

  public long sum() {
      Cell[] as = cells; Cell a;
      long sum = base;
      if (as != null) {
          // 遍历 累加
          for (int i = 0; i < as.length; ++i) {
              if ((a = as[i]) != null)
                  sum += a.value;
          }
      }
      return sum;
  }
  

ABA

ABA 问题：当进行获取主内存值时，该内存值在写入主内存时已经被修改了 N 次，但是最终又改成原来的值

其他线程先把 A 改成 B 又改回 A，主线程仅能判断出共享变量的值与最初值 A 是否相同，不能感知到这种从 A 改为 B 又 改回 A 的情况，这时 CAS 虽然成功，但是过程存在问题

• 构造方法：

  • public AtomicStampedReference(V initialRef, int initialStamp)：初始值和初始版本号

• 常用API：

  • public boolean compareAndSet(V expectedReference, V newReference, int expectedStamp, int newStamp)：期望引用和期望版本号都一致才进行 CAS 修改数据
  • public void set(V newReference, int newStamp)：设置值和版本号
  • public V getReference()：返回引用的值
  • public int getStamp()：返回当前版本号

public static void main(String[] args) {
    AtomicStampedReference<Integer> atomicReference = new AtomicStampedReference<>(100,1);
    int startStamp = atomicReference.getStamp();
    new Thread(() ->{
        int stamp = atomicReference.getStamp();
        atomicReference.compareAndSet(100, 101, stamp, stamp + 1);
        stamp = atomicReference.getStamp();
        atomicReference.compareAndSet(101, 100, stamp, stamp + 1);
    },"t1").start();

    new Thread(() ->{
        try {
            Thread.sleep(1000);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }
        if (!atomicReference.compareAndSet(100, 200, startStamp, startStamp + 1)) {
            System.out.println(atomicReference.getReference());//100
            System.out.println(Thread.currentThread().getName() + "线程修改失败");
        }
    },"t2").start();
}

Unsafe

Unsafe 是 CAS 的核心类，由于 Java 无法直接访问底层系统，需要通过本地（Native）方法来访问

Unsafe 类存在 sun.misc 包，其中所有方法都是 native 修饰的，都是直接调用操作系统底层资源执行相应的任务，基于该类可以直接操作特定的内存数据，其内部方法操作类似 C 的指针

模拟实现原子整数：

public static void main(String[] args) {
    MyAtomicInteger atomicInteger = new MyAtomicInteger(10);
    if (atomicInteger.compareAndSwap(20)) {
        System.out.println(atomicInteger.getValue());
    }
}

class MyAtomicInteger {
    private static final Unsafe UNSAFE;
    private static final long VALUE_OFFSET;
    private volatile int value;

    static {
        try {
            //Unsafe unsafe = Unsafe.getUnsafe()这样会报错，需要反射获取
            Field theUnsafe = Unsafe.class.getDeclaredField("theUnsafe");
            theUnsafe.setAccessible(true);
            UNSAFE = (Unsafe) theUnsafe.get(null);
            // 获取 value 属性的内存地址，value 属性指向该地址，直接设置该地址的值可以修改 value 的值
            VALUE_OFFSET = UNSAFE.objectFieldOffset(
                		   MyAtomicInteger.class.getDeclaredField("value"));
        } catch (NoSuchFieldException | IllegalAccessException e) {
            e.printStackTrace();
            throw new RuntimeException();
        }
    }

    public MyAtomicInteger(int value) {
        this.value = value;
    }
    public int getValue() {
        return value;
    }

    public boolean compareAndSwap(int update) {
        while (true) {
            int prev = this.value;
            int next = update;
            //							当前对象  内存偏移量    期望值 更新值
            if (UNSAFE.compareAndSwapInt(this, VALUE_OFFSET, prev, update)) {
                System.out.println("CAS成功");
                return true;
            }
        }
    }
}

final

原理

public class TestFinal {
	final int a = 20;
}

字节码：

0: aload_0
1: invokespecial #1 // Method java/lang/Object."<init>":()V
4: aload_0
5: bipush 20		// 将值直接放入栈中
7: putfield #2 		// Field a:I
<-- 写屏障
10: return

final 变量的赋值通过 putfield 指令来完成，在这条指令之后也会加入写屏障，保证在其它线程读到它的值时不会出现为 0 的情况

其他线程访问 final 修饰的变量

• 复制一份放入栈中直接访问，效率高
• 大于 short 最大值会将其复制到类的常量池，访问时从常量池获取

不可变

不可变：如果一个对象不能够修改其内部状态（属性），那么就是不可变对象

不可变对象线程安全的，不存在并发修改和可见性问题，是另一种避免竞争的方式

String 类也是不可变的，该类和类中所有属性都是 final 的

• 类用 final 修饰保证了该类中的方法不能被覆盖，防止子类无意间破坏不可变性

• 无写入方法（set）确保外部不能对内部属性进行修改

• 属性用 final 修饰保证了该属性是只读的，不能修改

  public final class String
      implements java.io.Serializable, Comparable<String>, CharSequence {
      /** The value is used for character storage. */
      private final char value[];
      //....
  }
  

• 更改 String 类数据时，会构造新字符串对象，生成新的 char[] value，通过创建副本对象来避免共享的方式称之为保护性拷贝

State

无状态：成员变量保存的数据也可以称为状态信息，无状态就是没有成员变量

Servlet 为了保证其线程安全，一般不为 Servlet 设置成员变量，这种没有任何成员变量的类是线程安全的

Java之JUC学习--part4

JMM（Java内存模型）

内存模型

Java 内存模型是 Java Memory Model（JMM），本身是一种抽象的概念，实际上并不存在，描述的是一组规则或规范，通过这组规范定义了程序中各个变量（包括实例字段，静态字段和构成数组对象的元素）的访问方式

JMM 作用：

• 屏蔽各种硬件和操作系统的内存访问差异，实现让 Java 程序在各种平台下都能达到一致的内存访问效果
• 规定了线程和内存之间的一些关系

根据 JMM 的设计，系统存在一个主内存（Main Memory），Java 中所有变量都存储在主存中，对于所有线程都是共享的；每条线程都有自己的工作内存（Working Memory），工作内存中保存的是主存中某些变量的拷贝，线程对所有变量的操作都是先对变量进行拷贝，然后在工作内存中进行，不能直接操作主内存中的变量；线程之间无法相互直接访问，线程间的通信（传递）必须通过主内存来完成

主内存和工作内存：

• 主内存：计算机的内存，也就是经常提到的 8G 内存，16G 内存，存储所有共享变量的值
• 工作内存：存储该线程使用到的共享变量在主内存的的值的副本拷贝

JVM 和 JMM 之间的关系：JMM 中的主内存、工作内存与 JVM 中的 Java 堆、栈、方法区等并不是同一个层次的内存划分，这两者基本上是没有关系的，如果两者一定要勉强对应起来：

• 主内存主要对应于 Java 堆中的对象实例数据部分，而工作内存则对应于虚拟机栈中的部分区域
• 从更低层次上说，主内存直接对应于物理硬件的内存，工作内存对应寄存器和高速缓存

内存交互

Java 内存模型定义了 8 个操作来完成主内存和工作内存的交互操作，每个操作都是原子的

非原子协定：没有被 volatile 修饰的 long、double 外，默认按照两次 32 位的操作

• lock：作用于主内存，将一个变量标识为被一个线程独占状态（对应 monitorenter）
• unclock：作用于主内存，将一个变量从独占状态释放出来，释放后的变量才可以被其他线程锁定（对应 monitorexit）
• read：作用于主内存，把一个变量的值从主内存传输到工作内存中
• load：作用于工作内存，在 read 之后执行，把 read 得到的值放入工作内存的变量副本中
• use：作用于工作内存，把工作内存中一个变量的值传递给执行引擎，每当遇到一个使用到变量的操作时都要使用该指令
• assign：作用于工作内存，把从执行引擎接收到的一个值赋给工作内存的变量
• store：作用于工作内存，把工作内存的一个变量的值传送到主内存中
• write：作用于主内存，在 store 之后执行，把 store 得到的值放入主内存的变量中

参考文章：https://github.com/CyC2018/CS-Notes/blob/master/notes/Java%20%E5%B9%B6%E5%8F%91.md

三大特性

可见性

可见性：是指当多个线程访问同一个变量时，一个线程修改了这个变量的值，其他线程能够立即看得到修改的值

存在不可见问题的根本原因是由于缓存的存在，线程持有的是共享变量的副本，无法感知其他线程对于共享变量的更改，导致读取的值不是最新的。但是 final 修饰的变量是不可变的，就算有缓存，也不会存在不可见的问题

main 线程对 run 变量的修改对于 t 线程不可见，导致了 t 线程无法停止：

static boolean run = true;	//添加volatile
public static void main(String[] args) throws InterruptedException {
    Thread t = new Thread(()->{
        while(run){
        // ....
        }
	});
    t.start();
    sleep(1);
    run = false; // 线程t不会如预想的停下来
}

原因：

• 初始状态， t 线程刚开始从主内存读取了 run 的值到工作内存
• 因为 t 线程要频繁从主内存中读取 run 的值，JIT 编译器会将 run 的值缓存至自己工作内存中的高速缓存中，减少对主存中 run 的访问，提高效率
• 1 秒之后，main 线程修改了 run 的值，并同步至主存，而 t 是从自己工作内存中的高速缓存中读取这个变量的值，结果永远是旧值

原子性

原子性：不可分割，完整性，也就是说某个线程正在做某个具体业务时，中间不可以被分割，需要具体完成，要么同时成功，要么同时失败，保证指令不会受到线程上下文切换的影响

定义原子操作的使用规则：

1. 不允许 read 和 load、store 和 write 操作之一单独出现，必须顺序执行，但是不要求连续
2. 不允许一个线程丢弃 assign 操作，必须同步回主存
3. 不允许一个线程无原因地（没有发生过任何 assign 操作）把数据从工作内存同步会主内存中
4. 一个新的变量只能在主内存中诞生，不允许在工作内存中直接使用一个未被初始化（assign 或者 load）的变量，即对一个变量实施 use 和 store 操作之前，必须先自行 assign 和 load 操作
5. 一个变量在同一时刻只允许一条线程对其进行 lock 操作，但 lock 操作可以被同一线程重复执行多次，多次执行 lock 后，只有执行相同次数的 unlock 操作，变量才会被解锁，lock 和 unlock 必须成对出现
6. 如果对一个变量执行 lock 操作，将会清空工作内存中此变量的值，在执行引擎使用这个变量之前需要重新从主存加载
7. 如果一个变量事先没有被 lock 操作锁定，则不允许执行 unlock 操作，也不允许去 unlock 一个被其他线程锁定的变量
8. 对一个变量执行 unlock 操作之前，必须先把此变量同步到主内存中（执行 store 和 write 操作）

有序性

有序性：在本线程内观察，所有操作都是有序的；在一个线程观察另一个线程，所有操作都是无序的，无序是因为发生了指令重排序

CPU 的基本工作是执行存储的指令序列，即程序，程序的执行过程实际上是不断地取出指令、分析指令、执行指令的过程，为了提高性能，编译器和处理器会对指令重排，一般分为以下三种：

源代码 -> 编译器优化的重排 -> 指令并行的重排 -> 内存系统的重排 -> 最终执行指令

现代 CPU 支持多级指令流水线，几乎所有的冯•诺伊曼型计算机的 CPU，其工作都可以分为 5 个阶段：取指令、指令译码、执行指令、访存取数和结果写回，可以称之为五级指令流水线。CPU 可以在一个时钟周期内，同时运行五条指令的不同阶段（每个线程不同的阶段），本质上流水线技术并不能缩短单条指令的执行时间，但变相地提高了指令地吞吐率

处理器在进行重排序时，必须要考虑指令之间的数据依赖性

• 单线程环境也存在指令重排，由于存在依赖性，最终执行结果和代码顺序的结果一致
• 多线程环境中线程交替执行，由于编译器优化重排，会获取其他线程处在不同阶段的指令同时执行

补充知识：

• 指令周期是取出一条指令并执行这条指令的时间，一般由若干个机器周期组成
• 机器周期也称为 CPU 周期，一条指令的执行过程划分为若干个阶段（如取指、译码、执行等），每一阶段完成一个基本操作，完成一个基本操作所需要的时间称为机器周期
• 振荡周期指周期性信号作周期性重复变化的时间间隔

Cache

缓存机制

缓存结构

在计算机系统中，CPU 高速缓存（CPU Cache，简称缓存）是用于减少处理器访问内存所需平均时间的部件；在存储体系中位于自顶向下的第二层，仅次于 CPU 寄存器；其容量远小于内存，但速度却可以接近处理器的频率

CPU 处理器速度远远大于在主内存中的，为了解决速度差异，在它们之间架设了多级缓存，如 L1、L2、L3 级别的缓存，这些缓存离 CPU 越近就越快，将频繁操作的数据缓存到这里，加快访问速度

缓存使用

当处理器发出内存访问请求时，会先查看缓存内是否有请求数据，如果存在（命中），则不用访问内存直接返回该数据；如果不存在（失效），则要先把内存中的相应数据载入缓存，再将其返回处理器

缓存之所以有效，主要因为程序运行时对内存的访问呈现局部性（Locality）特征。既包括空间局部性（Spatial Locality），也包括时间局部性（Temporal Locality），有效利用这种局部性，缓存可以达到极高的命中率。

伪共享

缓存以缓存行 cache line 为单位，每个缓存行对应着一块内存，一般是 64 byte（8 个 long），在 CPU 从主存获取数据时，以 cache line 为单位加载，于是相邻的数据会一并加载到缓存中

缓存会造成数据副本的产生，即同一份数据会缓存在不同核心的缓存行中，CPU 要保证数据的一致性，需要做到某个 CPU 核心更改了数据，其它 CPU 核心对应的整个缓存行必须失效，这就是伪共享。

解决方法：

• padding：通过填充，让数据落在不同的 cache line 中
• @Contended：原理参考 无锁 → Adder → 优化机制 → 伪共享

Linux 查看 CPU 缓存行：

• 命令：cat /sys/devices/system/cpu/cpu0/cache/index0/coherency_line_size64
• 内存地址格式：[高位组标记] [低位索引] [偏移量]

缓存一致

缓存一致性：当多个处理器运算任务都涉及到同一块主内存区域的时候，将可能导致各自的缓存数据不一样

MESI（Modified Exclusive Shared Or Invalid）是一种广泛使用的支持写回策略的缓存一致性协议，CPU 中每个缓存行（caceh line）使用 4 种状态进行标记（使用额外的两位 bit 表示)：

• M：被修改（Modified）

  该缓存行只被缓存在该 CPU 的缓存中，并且是被修改过的，与主存中的数据不一致 (dirty)，该缓存行中的内存需要写回 (write back) 主存。该状态的数据再次被修改不会发送广播，因为其他核心的数据已经在第一次修改时失效一次

  当被写回主存之后，该缓存行的状态会变成独享 (exclusive) 状态

• E：独享的（Exclusive）

  该缓存行只被缓存在该 CPU 的缓存中，是未被修改过的 (clear)，与主存中数据一致，修改数据不需要通知其他 CPU 核心，该状态可以在任何时刻有其它 CPU 读取该内存时变成共享状态 (shared)

  当 CPU 修改该缓存行中内容时，该状态可以变成 Modified 状态

• S：共享的（Shared）

  该状态意味着该缓存行可能被多个 CPU 缓存，并且各个缓存中的数据与主存数据一致，当 CPU 修改该缓存行中，会向其它 CPU 核心广播一个请求，使该缓存行变成无效状态 (Invalid)，然后再更新当前 Cache 里的数据

• I：无效的（Invalid）

  该缓存是无效的，可能有其它 CPU 修改了该缓存行

解决方法：各个处理器访问缓存时都遵循一些协议，在读写时要根据协议进行操作，协议主要有 MSI、MESI 等

处理机制

单核 CPU 处理器会自动保证基本内存操作的原子性

多核 CPU 处理器，每个 CPU 处理器内维护了一块内存，每个内核内部维护着一块缓存，当多线程并发读写时，就会出现缓存数据不一致的情况。处理器提供：

• 总线锁定：当处理器要操作共享变量时，在 BUS 总线上发出一个 LOCK 信号，其他处理器就无法操作这个共享变量，该操作会导致大量阻塞，从而增加系统的性能开销（平台级别的加锁）
• 缓存锁定：当处理器对缓存中的共享变量进行了操作，其他处理器有嗅探机制，将各自缓存中的该共享变量的失效，读取时会重新从主内存中读取最新的数据，基于 MESI 缓存一致性协议来实现

有如下两种情况处理器不会使用缓存锁定：

• 当操作的数据跨多个缓存行，或没被缓存在处理器内部，则处理器会使用总线锁定
• 有些处理器不支持缓存锁定，比如：Intel 486 和 Pentium 处理器也会调用总线锁定

总线机制：

• 总线嗅探：每个处理器通过嗅探在总线上传播的数据来检查自己缓存值是否过期了，当处理器发现自己的缓存对应的内存地址的数据被修改，就将当前处理器的缓存行设置为无效状态，当处理器对这个数据进行操作时，会重新从内存中把数据读取到处理器缓存中
• 总线风暴：当某个 CPU 核心更新了 Cache 中的数据，要把该事件广播通知到其他核心（写传播），CPU 需要每时每刻监听总线上的一切活动，但是不管别的核心的 Cache 是否缓存相同的数据，都需要发出一个广播事件，不断的从主内存嗅探和 CAS 循环，无效的交互会导致总线带宽达到峰值；因此不要大量使用 volatile 关键字，使用 volatile、syschonized 都需要根据实际场景

volatile

同步机制

volatile 是 Java 虚拟机提供的轻量级的同步机制（三大特性）

• 保证可见性
• 不保证原子性
• 保证有序性（禁止指令重排）

性能：volatile 修饰的变量进行读操作与普通变量几乎没什么差别，但是写操作相对慢一些，因为需要在本地代码中插入很多内存屏障来保证指令不会发生乱序执行，但是开销比锁要小

synchronized 无法禁止指令重排和处理器优化，为什么可以保证有序性可见性

• 加了锁之后，只能有一个线程获得到了锁，获得不到锁的线程就要阻塞，所以同一时间只有一个线程执行，相当于单线程，由于数据依赖性的存在，单线程的指令重排是没有问题的
• 线程加锁前，将清空工作内存中共享变量的值，使用共享变量时需要从主内存中重新读取最新的值；线程解锁前，必须把共享变量的最新值刷新到主内存中（JMM 内存交互章节有讲）

指令重排

volatile 修饰的变量，可以禁用指令重排

指令重排实例：

• example 1：

  public void mySort() {
  	int x = 11;	//语句1
  	int y = 12;	//语句2  谁先执行效果一样
  	x = x + 5;	//语句3
  	y = x * x;	//语句4
  }
  

  执行顺序是：1 2 3 4、2 1 3 4、1 3 2 4

  指令重排也有限制不会出现：4321，语句 4 需要依赖于 y 以及 x 的申明，因为存在数据依赖，无法首先执行

• example 2：

  int num = 0;
  boolean ready = false;
  // 线程1 执行此方法
  public void actor1(I_Result r) {
      if(ready) {
      	r.r1 = num + num;
      } else {
      	r.r1 = 1;
      }
  }
  // 线程2 执行此方法
  public void actor2(I_Result r) {
  	num = 2;
  	ready = true;
  }
  

  情况一：线程 1 先执行，ready = false，结果为 r.r1 = 1

  情况二：线程 2 先执行 num = 2，但还没执行 ready = true，线程 1 执行，结果为 r.r1 = 1

  情况三：线程 2 先执行 ready = true，线程 1 执行，进入 if 分支结果为 r.r1 = 4

  情况四：线程 2 执行 ready = true，切换到线程 1，进入 if 分支为 r.r1 = 0，再切回线程 2 执行 num = 2，发生指令重排

底层原理

缓存一致

使用 volatile 修饰的共享变量，底层通过汇编 lock 前缀指令进行缓存锁定，在线程修改完共享变量后写回主存，其他的 CPU 核心上运行的线程通过 CPU 总线嗅探机制会修改其共享变量为失效状态，读取时会重新从主内存中读取最新的数据

lock 前缀指令就相当于内存屏障，Memory Barrier（Memory Fence）

• 对 volatile 变量的写指令后会加入写屏障
• 对 volatile 变量的读指令前会加入读屏障

内存屏障有三个作用：

• 确保对内存的读-改-写操作原子执行
• 阻止屏障两侧的指令重排序
• 强制把缓存中的脏数据写回主内存，让缓存行中相应的数据失效

内存屏障

保证可见性：

• 写屏障（sfence，Store Barrier）保证在该屏障之前的，对共享变量的改动，都同步到主存当中

  public void actor2(I_Result r) {
      num = 2;
      ready = true; // ready 是 volatile 赋值带写屏障
      // 写屏障
  }
  

• 读屏障（lfence，Load Barrier）保证在该屏障之后的，对共享变量的读取，从主存刷新变量值，加载的是主存中最新数据

  public void actor1(I_Result r) {
      // 读屏障
      // ready 是 volatile 读取值带读屏障
      if(ready) {
      	r.r1 = num + num;
      } else {
      	r.r1 = 1;
      }
  }
  

  

• 全能屏障：mfence（modify/mix Barrier），兼具 sfence 和 lfence 的功能

保证有序性：

• 写屏障会确保指令重排序时，不会将写屏障之前的代码排在写屏障之后
• 读屏障会确保指令重排序时，不会将读屏障之后的代码排在读屏障之前

不能解决指令交错：

• 写屏障仅仅是保证之后的读能够读到最新的结果，但不能保证其他线程的读跑到写屏障之前

• 有序性的保证也只是保证了本线程内相关代码不被重排序

  volatile i = 0;
  new Thread(() -> {i++});
  new Thread(() -> {i--});
  

  i++ 反编译后的指令：

  0: iconst_1			// 当int取值 -1~5 时，JVM采用iconst指令将常量压入栈中
  1: istore_1			// 将操作数栈顶数据弹出，存入局部变量表的 slot 1
  2: iinc		1, 1
  

  

交互规则

对于 volatile 修饰的变量：

• 线程对变量的 use 与 load、read 操作是相关联的，所以变量使用前必须先从主存加载
• 线程对变量的 assign 与 store、write 操作是相关联的，所以变量使用后必须同步至主存
• 线程 1 和线程 2 谁先对变量执行 read 操作，就会先进行 write 操作，防止指令重排

双端检锁

检锁机制

Double-Checked Locking：双端检锁机制

DCL（双端检锁）机制不一定是线程安全的，原因是有指令重排的存在，加入 volatile 可以禁止指令重排

public final class Singleton {
    private Singleton() { }
    private static Singleton INSTANCE = null;
  
    public static Singleton getInstance() {
        if(INSTANCE == null) { // t2，这里的判断不是线程安全的
            // 首次访问会同步，而之后的使用没有 synchronized
            synchronized(Singleton.class) {
                // 这里是线程安全的判断，防止其他线程在当前线程等待锁的期间完成了初始化
                if (INSTANCE == null) { 
                    INSTANCE = new Singleton();
                }
            }
        }
        return INSTANCE;
    }
}

不锁 INSTANCE 的原因：

• INSTANCE 要重新赋值
• INSTANCE 是 null，线程加锁之前需要获取对象的引用，设置对象头，null 没有引用

实现特点：

• 懒惰初始化
• 首次使用 getInstance() 才使用 synchronized 加锁，后续使用时无需加锁
• 第一个 if 使用了 INSTANCE 变量，是在同步块之外，但在多线程环境下会产生问题

DCL问题

getInstance 方法对应的字节码为：

0: 	getstatic 		#2 		// Field INSTANCE:Ltest/Singleton;
3: 	ifnonnull 		37
6: 	ldc 			#3 		// class test/Singleton
8: 	dup
9: 	astore_0
10: monitorenter
11: getstatic 		#2 		// Field INSTANCE:Ltest/Singleton;
14: ifnonnull 27
17: new 			#3 		// class test/Singleton
20: dup
21: invokespecial 	#4 		// Method "<init>":()V
24: putstatic 		#2 		// Field INSTANCE:Ltest/Singleton;
27: aload_0
28: monitorexit
29: goto 37
32: astore_1
33: aload_0
34: monitorexit
35: aload_1
36: athrow
37: getstatic 		#2 		// Field INSTANCE:Ltest/Singleton;
40: areturn

• 17 表示创建对象，将对象引用入栈
• 20 表示复制一份对象引用，引用地址
• 21 表示利用一个对象引用，调用构造方法初始化对象
• 24 表示利用一个对象引用，赋值给 static INSTANCE

步骤 21 和 24 之间不存在数据依赖关系，而且无论重排前后，程序的执行结果在单线程中并没有改变，因此这种重排优化是允许的

• 关键在于 0:getstatic 这行代码在 monitor 控制之外，可以越过 monitor 读取 INSTANCE 变量的值
• 当其他线程访问 INSTANCE 不为 null 时，由于 INSTANCE 实例未必已初始化，那么 t2 拿到的是将是一个未初始化完毕的单例返回，这就造成了线程安全的问题

解决方法

指令重排只会保证串行语义的执行一致性（单线程），但并不会关系多线程间的语义一致性

引入 volatile，来保证出现指令重排的问题，从而保证单例模式的线程安全性：

private static volatile SingletonDemo INSTANCE = null;

ha-be

happens-before 先行发生

Java 内存模型具备一些先天的“有序性”，即不需要通过任何同步手段（volatile、synchronized 等）就能够得到保证的安全，这个通常也称为 happens-before 原则，它是可见性与有序性的一套规则总结

不符合 happens-before 规则，JMM 并不能保证一个线程的可见性和有序性

1. 程序次序规则 (Program Order Rule)：一个线程内，逻辑上书写在前面的操作先行发生于书写在后面的操作 ，因为多个操作之间有先后依赖关系，则不允许对这些操作进行重排序

2. 锁定规则 (Monitor Lock Rule)：一个 unlock 操作先行发生于后面（时间的先后）对同一个锁的 lock 操作，所以线程解锁 m 之前对变量的写（解锁前会刷新到主内存中），对于接下来对 m 加锁的其它线程对该变量的读可见

3. volatile 变量规则 (Volatile Variable Rule)：对 volatile 变量的写操作先行发生于后面对这个变量的读

4. 传递规则 (Transitivity)：具有传递性，如果操作 A 先行发生于操作 B，而操作 B 又先行发生于操作 C，则可以得出操作 A 先行发生于操作 C

5. 线程启动规则 (Thread Start Rule)：Thread 对象的 start()方 法先行发生于此线程中的每一个操作

   static int x = 10;//线程 start 前对变量的写，对该线程开始后对该变量的读可见
   new Thread(()->{	System.out.println(x);	},"t1").start();
   

6. 线程中断规则 (Thread Interruption Rule)：对线程 interrupt() 方法的调用先行发生于被中断线程的代码检测到中断事件的发生

7. 线程终止规则 (Thread Termination Rule)：线程中所有的操作都先行发生于线程的终止检测，可以通过 Thread.join() 方法结束、Thread.isAlive() 的返回值手段检测到线程已经终止执行

8. 对象终结规则（Finaizer Rule）：一个对象的初始化完成（构造函数执行结束）先行发生于它的 finalize() 方法的开始

设计模式

终止模式

终止模式之两阶段终止模式：停止标记用 volatile 是为了保证该变量在多个线程之间的可见性

class TwoPhaseTermination {
    // 监控线程
    private Thread monitor;
    // 停止标记
    private volatile boolean stop = false;;

    // 启动监控线程
    public void start() {
        monitor = new Thread(() -> {
            while (true) {
                Thread thread = Thread.currentThread();
                if (stop) {
                    System.out.println("后置处理");
                    break;
                }
                try {
                    Thread.sleep(1000);// 睡眠
                    System.out.println(thread.getName() + "执行监控记录");
                } catch (InterruptedException e) {
                   	System.out.println("被打断，退出睡眠");
                }
            }
        });
        monitor.start();
    }

    // 停止监控线程
    public void stop() {
        stop = true;
        monitor.interrupt();// 让线程尽快退出Timed Waiting
    }
}
// 测试
public static void main(String[] args) throws InterruptedException {
    TwoPhaseTermination tpt = new TwoPhaseTermination();
    tpt.start();
    Thread.sleep(3500);
    System.out.println("停止监控");
    tpt.stop();
}

Balking

Balking （犹豫）模式用在一个线程发现另一个线程或本线程已经做了某一件相同的事，那么本线程就无需再做了，直接结束返回

public class MonitorService {
    // 用来表示是否已经有线程已经在执行启动了
    private volatile boolean starting = false;
    public void start() {
        System.out.println("尝试启动监控线程...");
        synchronized (this) {
            if (starting) {
            	return;
            }
            starting = true;
        }
        // 真正启动监控线程...
    }
}

对比保护性暂停模式：保护性暂停模式用在一个线程等待另一个线程的执行结果，当条件不满足时线程等待

例子：希望 doInit() 方法仅被调用一次，下面的实现出现的问题：

• 当 t1 线程进入 init() 准备 doInit()，t2 线程进来，initialized 还为f alse，则 t2 就又初始化一次
• volatile 适合一个线程写，其他线程读的情况，这个代码需要加锁

public class TestVolatile {
    volatile boolean initialized = false;
  
    void init() {
        if (initialized) {
            return;
        }
    	doInit();
    	initialized = true;
    }
    private void doInit() {
    }
}