Liangbk's blog

spring-ai练习

Fri, 06 Mar 2026 00:00:00 GMT

Chat流程

新版本spring-ai（1.1.2）中，ChatClient底层依托ChatModel发送请求和接收响应

与chatModel相关的主要包括call()和stream()，前者是一次性返回对话的所有的内容，后者是流式的（类似一个字一个字）返回对话的内容

其他的调用与上下文信息（prompt）、RAG（advisors）、MCP（tools）、AGENT相关

总览图：

只需要记住这张图：
ChatClient.Builder（Spring自动注入，前提是配置里只有一个Client）
    │
    ├── .defaultSystem(...)       → 默认系统提示
    ├── .defaultAdvisors(...)     → 默认拦截器（记忆/RAG）
    ├── .defaultTools(...)        → 默认工具（MCP/Function）
    └── .build()
            │
            ▼
        ChatClient（你拿来用的）
            │
            └── .prompt()
                    ├── .system(...)    → 覆盖默认系统提示
                    ├── .user(...)      → 用户输入
                    ├── .advisors(...)  → 本次请求的拦截器参数
                    ├── .call()         → 普通调用
                    └── .stream()       → 流式调用

POM

<properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <spring-ai.version>1.1.2</spring-ai.version>
</properties>
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

单模型

POM中导入open-ai模型：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>


    <!--   使用openai模型  -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-openai</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

分别使用ChatModel和ChatClient发送请求（以deepseek api为例）：

配置文件（application.yml）

server:
  port: 8090

spring:
  ai:
    openai:
      base-url: https://api.deepseek.com
      api-key: sk-xxx
      chat:
        options:
          model: deepseek-chat

配置类

@Configuration
public class AiConfig {
    @Bean
    public ChatClient chatClient(ChatClient.Builder builder) {
        return builder
                .defaultSystem("你是一个专业的技术助手，请用中文回答。")
                .build();
    }
}

测试

@SpringBootTest
public class ChatTest {
    // 第三方Bean自动注入
    @Resource
    private ChatModel chatModel;
    // 配置类注入
    @Resource
    private ChatClient chatClient;
    // ==================== ChatModel 测试 ====================
    /**
     * 测试：ChatModel 使用 Prompt，携带系统提示
     */
    @Test
    public void test_chatModel_withPrompt() {
        Prompt prompt = new Prompt(List.of(
                new SystemMessage("你是一个专业的 Java 开发助手，回答请简洁专业"),
                new UserMessage("Spring AI 和 LangChain 有什么区别？")
        ));

        ChatResponse response = chatModel.call(prompt);

        // 获取回复文本
        String content = response.getResult().getOutput().getText();
        System.out.println("回复：" + content);

        // 打印 token 用量
        var usage = response.getMetadata().getUsage();
        System.out.println("输入 tokens：" + usage.getPromptTokens());
        System.out.println("输出 tokens：" + usage.getCompletionTokens());
    }
    // ==================== ChatClient 测试 ====================

    /**
     * 测试：ChatClient 链式调用流式输出（最常用写法）
     */
    @Test
    public void test_chatClient_stream() throws InterruptedException {
        Flux<String> flux = chatClient.prompt()
            	.system("你是一个幽默的程序员，回答时适当加入编程梗")
                .user("解释一下什么是递归")
                .stream()
                .content();

        // 同步阻塞订阅，测试环境用 blockLast()
        flux.doOnNext(token -> System.out.print(token))
                .blockLast();

        System.out.println(); // 换行
    }
}

解释一下需要了解的类和api

Prompt：提示词，由单条或多条有序的Message组成，基本可以看做是对话内容
Message：根据类型分为System（系统设置），User（用户消息），Assistant（模型回复消息）
ChatModel：对话模型客户端，负责给大模型发送消息和接收响应
- call()
- stream()
ChatClient：封装了ChatModel和prompt以及其他的一些可能用到的工具流程（比如设置，RAG等），使其支持链式调用，而不必单独手动组合在一起
- prompt()：输入的提示词
- system()：语法糖，就是输入的System Message
- user()：语法糖，就是输入的User Message
- call()
- stream()

多模型

当需要使用多个厂商的模型时（或者不同厂商提供的不同组件），在配置上以及第三方Bean的使用上与单模型有差别：

POM引入：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-ollama</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

配置文件需要配置多个厂商：

spring:
  ai:
    ollama:
      base-url: http://127.0.0.1:11434
      embedding:
        options:
          num-batch: 512
        model: nomic-embed-text	# 本地ollama提供的嵌入模型, 见RAG流程
    openai:
      base-url: https://api.deepseek.com
      api-key: sk-xxx
      chat:
        options:
          model: deepseek-chat	# deepseek api提供的对话模型

第三方Bean导入：

使用各厂商的ChatModel作为参数，然后导入对应的ChatClient：

@Configuration
public class AiConfig {
    @Bean("openAiChatClient")
    public ChatClient chatClient(OpenAiChatModel model) {
        return ChatClient.builder(model)
                .defaultSystem("你是 OpenAI 驱动的助手")
                .build();
    }

    @Bean("ollamaChatClient")
    public ChatClient ollamaChatClient(OllamaChatModel model) {
        return ChatClient.builder(model)
                .defaultSystem("你是本地 Ollama 驱动的助手")
                .build();
    }
}

可以使用chatOption指定各厂商提供的模型：

@Test
public void test_chatClientOption() {
    String content = ollamaChatClient.prompt()
        .options(OllamaChatOptions.builder()
                 .model("deepseek-r1:1.5b")	// 指定本地ollama提供的1.5b模型
                 .build())
        .user("你是什么助手？")
        .call()
        .content();
    System.out.println("ollama助手回答:" +  content);
}

RAG流程

以对话模型为例，当发送的消息比如“帮我写xxx算法的代码”，对话模型内部处理并不是自然语言，而是一堆数据（向量），也就是先有一个模型将各种自然语言转为[0.1,0.2,0.3....]之类的向量，然后对话模型内部才去处理，这个将自然语言转为向量的模型叫嵌入模型（embedding-model）

RAG（Retrieval-Augmented-Generation）提前将资料（文本文档，图片，音频等）通过各类嵌入模型转为向量，然后存入专门的向量数据库中，在用户向对话模型提问时，将问题也经过嵌入模型转为向量后，去向量数据库中去比对，然后找到相似的信息，最后将数据库中的信息和用户消息同时作为prompt交给对话模型，以此让对话模型能够获取外部资料增强输出

POM引入：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-tika-document-reader</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-pgvector</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-advisors-vector-store</artifactId>
</dependency>

介绍上述提到的概念对应到spring-ai中的类：

嵌入模型：EmbeddingModel，使用方式跟ChatModel类似，不过返回的内容是数组
上传以及检索出来的资料：Document，文件资料可能以各种方式存在（txt，md，pdf），Document负责将其统一
文本分割器：TokenTextSplitter，一个文件可能过大，需要将内容按指定规则分割多个小块，这些小块以Document的形式存在
向量数据库：PgVectorStore，负责连接向量数据库并进行操作，其需要指定一个嵌入模型，之后在上传和检索时都会使用该模型进行文本转向量的处理

配置

配置文件：

spring:
  datasource:
    driver-class-name: org.postgresql.Driver
    username: postgres
    password: postgres
    url: jdbc:postgresql://127.0.0.1:15432/ai-rag-mcp
    type: com.zaxxer.hikari.HikariDataSource
    # hikari连接池配置
    hikari:
      #连接池名
      pool-name: HikariCP
      #最小空闲连接数
      minimum-idle: 5
      # 空闲连接存活最大时间，默认10分钟
      idle-timeout: 600000
      # 连接池最大连接数，默认是10
      maximum-pool-size: 10
      # 此属性控制从池返回的连接的默认自动提交行为,默认值：true
      auto-commit: true
      # 此属性控制池中连接的最长生命周期，值0表示无限生命周期，默认30分钟
      max-lifetime: 1800000
      # 数据库连接超时时间,默认30秒
      connection-timeout: 30000
      # 连接测试query
      connection-test-query: SELECT 1
  ai:
    ollama:
      base-url: http://127.0.0.1:11434
      embedding:
        options:
          num-batch: 512
        model: nomic-embed-text	# ollama的嵌入模型

配置类：

@Bean
public PgVectorStore pgVectorStore(JdbcTemplate jdbcTemplate, OllamaEmbeddingModel ollamaEmbeddingModel) {
    return PgVectorStore.builder(jdbcTemplate, ollamaEmbeddingModel)
        .initializeSchema(true)
        .dimensions(768)
        .distanceType(PgVectorStore.PgDistanceType.COSINE_DISTANCE)
        .indexType(PgVectorStore.PgIndexType.HNSW)
        .build();
}

@Bean
public TokenTextSplitter  tokenTextSplitter() {
    return new TokenTextSplitter();
}

向量数据库：

使用docker启动一个vector_db，这里启动的是PGVector

在docker终端创建并连接数据库，创建表：

# 连接
psql -h 127.0.0.1 -p 5432 -U postgres

# 创建数据库
\l # 查看数据库列表
create databse ai-rag-mcp;
\c ai-rag-mcp # 使用对应数据库

# 创建表
CREATE EXTENSION IF NOT EXISTS vector; # 安装pgvector扩展
SELECT * FROM pg_extension WHERE extname = 'vector'; # 验证是否安装成功（应该能看到一条记录）
\dt vector_store	# 检查表是否存在
DROP TABLE IF EXISTS vector_store;	# 删除表

CREATE TABLE IF NOT EXISTS vector_store (
    id UUID PRIMARY KEY,
    content TEXT,
    metadata JSONB,
    embedding vector(768)
);

上传

reader读取文档
tokenTextSplitter分割文档
给文档打标签（也叫元信息，会一起存储到数据库里，可以根据这个进行检索前的过滤）
vectorstore.add()将文档上传到向量数据库

@Resource
private PgVectorStore pgVectorStore;
@Resource
private TokenTextSplitter tokenTextSplitter;
@Test
public void test_upload_file_to_db() {
    
    TikaDocumentReader reader = new TikaDocumentReader("./data/env-build.md");
    List<Document> documents = reader.get();
    List<Document> chunks = tokenTextSplitter.apply(documents);
    chunks.forEach(document -> {
        document.getMetadata().put("description", "java-env-build");
    });
    pgVectorStore.add(chunks);
}

检索

在向量数据库中进行问题的相似度查询，得到结果
将检索结果和问题一起拼装到prompt中，然后通过chatmodel发送

@Test
public void test_chat_with_db() {
    String question = "如何进行微信鉴权？";
    List<Document> documents = pgVectorStore.similaritySearch(
        SearchRequest.builder()
        .query(question)
        .topK(5)
        .similarityThreshold(0.5)
        .filterExpression("description == 'java-env-build'")
        .build()
    );
    log.info("=======检索到的相关文档=======");
    documents.forEach(document -> {
        System.out.println("· " + document.getText());
    });
    String context = documents.stream()
        .map(Document::getText)
        .collect(Collectors.joining("\n\n"));
    String ragPromptText = """
        请根据以下参考资料回答问题，资料中没有的内容请如实说明。

        参考资料：
        %s

        问题：%s
        """.formatted(context, question);

        Prompt prompt = new Prompt(List.of(
            new SystemMessage("你是一个知识库助手，请用中文简洁回答。"),
            new UserMessage(ragPromptText)
        ));

    ChatResponse chatResponse = openAiChatModel.call(prompt);
    // Step5: 提取结果
    String answer = chatResponse.getResult().getOutput().getText();
    log.info("\n=== 模型回答 ===");
    log.info(answer);

    // 额外：查看 token 用量
    Usage usage = chatResponse.getMetadata().getUsage();
    log.info("\n输入tokens: " + usage.getPromptTokens());
    log.info("输出tokens: " + usage.getCompletionTokens());
}

如果使用chatclient，则使用Advisors类来封装这个过程：

@Test
public void test_chat_client_rag() {
    String question = "如何进行微信鉴权？";
    String content = openAiChatClient.prompt()
        .user(question)
        .advisors(QuestionAnswerAdvisor.builder(pgVectorStore)
                  .searchRequest(
                      SearchRequest.builder()
                      .topK(5)
                      .similarityThreshold(0.5)
                      .filterExpression("description == 'java-env-build'")
                      .build()
                  )
                  .build())
        .call()
        .content();
    log.info("advisors rag content: {}", content);
}

MCP流程

模型上下文协议（MCP）是一种使AI模型能够以结构化方式与外部工具和资源交互的协议（这个外部工具可能是本地进程，可能是服务器或其他遵循协议的程序）。

说人话就是，有一个服务，对外暴露接口或api，把这些服务提供的api信息交给对话模型，模型的输出（json格式字符串）会自动调用工具（在json中表明要调用），然后客户端会调用对应的服务api，收到调用的结果后再发给对话模型去分析

基本流程

spring-ai将流程封装到了ChatClient的调用内部（也就是call()和stream()具体实现做的事），只提供几个类给开发人员调用，不易于理解流程，这里使用deepseek官网中的python进行阐述：

from openai import OpenAI

def send_messages(messages):
    response = client.chat.completions.create(
        model="deepseek-chat",
        messages=messages,
        tools=tools
    )
    return response.choices[0].message

client = OpenAI(
    api_key="<your api key>",
    base_url="https://api.deepseek.com",
)
# tools数组，和对话消息一起发送给对话模型
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get weather of a location, the user should supply a location first.",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    }
                },
                "required": ["location"]
            },
        }
    },
]

messages = [{"role": "user", "content": "How's the weather in Hangzhou, Zhejiang?"}]
message = send_messages(messages)
print(f"User>\t {messages[0]['content']}")

tool = message.tool_calls[0]
messages.append(message)

messages.append({"role": "tool", "tool_call_id": tool.id, "content": "24℃"})
message = send_messages(messages)
print(f"Model>\t {message.content}")

准备好tools（待调用的api说明），这里的python代码直接给出，平常需要由对话客户端主动向MCP服务器进行请求获取tools信息
将tools和问题一起发送给对话模型

查看返回结果：

===response===
{
  "id": "2beffab1-837e-4031-b137-d1d49b6f7800",
  "choices": [
    {   
      "finish_reason": "tool_calls",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "I'll check the weather in Hangzhou, Zhejiang for you.",
        "refusal": null,
        "role": "assistant",
        "annotations": null,
        "audio": null,
        "function_call": null,
        "tool_calls": [
          {
            "id": "call_00_oUNn7rFGaMXqENDHP3vC2ZRC",
            "function": {
              "arguments": "{\"location\": \"Hangzhou, Zhejiang\"}",
              "name": "get_weather"
            },
            "type": "function",
            "index": 0
          }
        ]
      }
    }
  ],
  "created": 1772699828,
  "model": "deepseek-chat",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": "fp_eaab8d114b_prod0820_fp8_kvcache",
  "usage": {
    "completion_tokens": 62,
    "prompt_tokens": 333,
    "total_tokens": 395,
    "completion_tokens_details": null,
    "prompt_tokens_details": {
      "audio_tokens": null,
      "cached_tokens": 320
    },
    "prompt_cache_hit_tokens": 320,
    "prompt_cache_miss_tokens": 13
  }
}

主要查看"finish_reason"，这里表明是"tool_calls"，也就是模型在分析之后决定要进行api调用了，然后是里面的"tool_calls"数组，里面表明了要调用的api信息

由客户端（主程序）去调用这个api，将得到的信息拼接，并重新发给对话模型，得到最终结果：


User>	 How's the weather in Hangzhou, Zhejiang?
===response===
{
  "id": "12f0a8df-cb1b-4391-917f-1b190914ab6f",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "The current weather in Hangzhou, Zhejiang is 24°C (about 75°F). It's a pleasant, mild temperature - perfect for outdoor activities!",
        "refusal": null,
        "role": "assistant",
        "annotations": null,
        "audio": null,
        "function_call": null,
        "tool_calls": null
      }
    }
  ],
  "created": 1772699833,
  "model": "deepseek-chat",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": "fp_eaab8d114b_prod0820_fp8_kvcache",
  "usage": {
    "completion_tokens": 34,
    "prompt_tokens": 414,
    "total_tokens": 448,
    "completion_tokens_details": null,
    "prompt_tokens_details": {
      "audio_tokens": null,
      "cached_tokens": 384
    },
    "prompt_cache_hit_tokens": 384,
    "prompt_cache_miss_tokens": 30
  }
}
Model>	 The current weather in Hangzhou, Zhejiang is 24°C (about 75°F). It's a pleasant, mild temperature - perfect for outdoor activities!

可以看到模型返回的结果，"finish_reason"已经变为了"stop"，代表模型回复完了此次对话

spring-ai封装

POM引入：

客户端：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>

服务端：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server</artifactId>
</dependency>

客户端MCP

配置文件：新增mcp项，可以使用外部文件的方式引入mcp server，也可以直接写在yaml中，这里直接写在yaml中

spring:
    mcp:
      client:
        stdio:
          # servers-configuration: classpath:/config/mcp-servers-config.json
            connections:
              test-server:
                command: npx.cmd
                args:
                  - "-y"
                  - "@modelcontextprotocol/server-filesystem"
                  - "C:\\Users\\86183\\Desktop\\mcp-test"           # 授权访问的目录
        enabled: true

前面提到，在spring-ai中，ChatModel的调用已经封装了工具的调用，因此开发者只需要提供工具，这涉及到以下类：

McpSyncClient：与MCP Server对接的客户端对象，负责获取工具信息，调用工具等（理解有这个东西就好，一般工具在载入后会直接到SyncMcpToolCallbackProvider里）
SyncMcpToolCallbackProvider：字面意思，调用工具提供方，也就是解析响应，通过mcpclient拿到工具列表，并连接client和每一个toolcallback
ToolCallback[]：基本上可以理解是python流程中的tools数组，不过数组中的每一个tool都可以请求对应的mcp server api（通过McpSyncClient）

@Resource(name = "openAiChatClient")
private ChatClient openAiChatClient;

@Resource(name = "openAiChatModel")
private ChatModel openAiChatModel;

@Resource
private List<McpSyncClient> mcpSyncClients;

private ToolCallback[] getMcpTools() {
    return mcpSyncClients.stream()
        .map(SyncMcpToolCallbackProvider::new)
        .flatMap(p -> Arrays.stream(p.getToolCallbacks()))
        .toArray(ToolCallback[]::new);
}
@Test
public void test_dynamic_mcp_tools() {
    String answer = openAiChatClient.prompt()
        .user("列出允许访问的目录并读取Desktop\\mcp-test\\mcp.txt 的内容")
        .toolCallbacks(List.of(getMcpTools()))      // ← 本次请求附加工具
        .call()
        .content();

    System.out.println("回答：" + answer);
}

服务端MCP

配置文件：在日志配置文件中不能让日志文件作为

spring:
  application:
    name: mcp-server-computer

  ai:
    mcp:
      server:
        name: ${spring.application.name}
        version: 1.0.0
        
  main:
    banner-mode: off
    web-application-type: none

  server:
    servlet:
      encoding:
        charset: UTF-8
        force: true
        enabled: true

logging:
  config: classpath:logback-spring.xml

流程：

在spring能够扫描的组件里的方法上加上注解@Tool(description = "xxx")（代表是一个可调用的工具）

@Service
public class ComputerService {

    @Tool(description = "获取电脑配置")
    public ComputerFunctionResponse queryConfig(ComputerFunctionRequest request) {
        log.info("获取电脑配置信息 {}", request.getComputer());
        // 获取系统属性
        Properties properties = System.getProperties();

        // 操作系统名称
        String osName = properties.getProperty("os.name");
        // 操作系统版本
        String osVersion = properties.getProperty("os.version");
        // 操作系统架构
        String osArch = properties.getProperty("os.arch");
        // 用户的账户名称
        String userName = properties.getProperty("user.name");
        // 用户的主目录
        String userHome = properties.getProperty("user.home");
        // 用户的当前工作目录
        String userDir = properties.getProperty("user.dir");
        // Java 运行时环境版本
        String javaVersion = properties.getProperty("java.version");

        String osInfo = "";
        // 根据操作系统执行特定的命令来获取更多信息
        if (osName.toLowerCase().contains("win")) {
            // Windows特定的代码
            osInfo = getWindowsSpecificInfo();
        } else if (osName.toLowerCase().contains("mac")) {
            // macOS特定的代码
            osInfo = getMacSpecificInfo();
        } else if (osName.toLowerCase().contains("nix") || osName.toLowerCase().contains("nux")) {
            // Linux特定的代码
            osInfo = getLinuxSpecificInfo();
        }

        ComputerFunctionResponse response = new ComputerFunctionResponse();
        response.setOsName(osName);
        response.setOsVersion(osVersion);
        response.setOsArch(osArch);
        response.setUserName(userName);
        response.setUserHome(userHome);
        response.setUserDir(userDir);
        response.setJavaVersion(javaVersion);
        response.setOsInfo(osInfo);

        return response;
    }
}

@Bean
public ToolCallbackProvider computerTools(ComputerService computerService) {
    return MethodToolCallbackProvider.builder()
        .toolObjects(computerService)
        .build();
}

Agent

java项目环境配置

Thu, 15 Jan 2026 00:00:00 GMT

基本环境

我用的是windows + WSL2(ubuntu22) + docker

windows负责写代码

WSL提供Linux环境（类似服务器）

Docker提供MYSQL，Redis镜像，将这些组件容器化，方便启动，停止或者删除

如果是云服务器，操作基本类似

ssh客户端

ssh客户端直接用vscode，轻量级，自带文件传输（直接拖或者复制粘贴），自带图形界面好管理

WSL2

jdk和maven都要直接安装到wsl2环境上

JDK

java直接安装jdk17的包：

sudo apt-get install openjdk-17-jdk

如果想搜索有什么版本的jdk能安装，可以用：

sudo apt-cache search java sdk

maven

ubuntu22默认安装maven3.6，一般需要maven3.8版本往上

在github仓库中有对应的环境安装包：env

clone下来，在environment/maven目录下，有3.8版本安装包，目前里面的安装脚本有点问题（默认使用apt下载），不要使用

在environment/maven目录打开终端：

新建一个安装脚本，安装的maven会被放在/opt目录下：

#!/usr/bin/env bash
set -e

# ===== 配置区 =====
MAVEN_VERSION="3.8.8"
MAVEN_ARCHIVE="apache-maven-${MAVEN_VERSION}.zip"
INSTALL_BASE="/opt"
INSTALL_DIR="${INSTALL_BASE}/apache-maven-${MAVEN_VERSION}"
PROFILE_FILE="$HOME/.bashrc"

# ===== 工具函数 =====
info()  { echo -e "\033[0;34m[INFO]\033[0m $1"; }
ok()    { echo -e "\033[0;32m[OK]\033[0m   $1"; }
warn()  { echo -e "\033[0;33m[WARN]\033[0m $1"; }
err()   { echo -e "\033[0;31m[ERR]\033[0m  $1"; exit 1; }

# ===== 前置检查 =====
info "检查 Java 环境"
command -v java >/dev/null 2>&1 || err "未检测到 Java，请先安装 JDK"

info "检查 Maven 安装包"
[[ -f "$MAVEN_ARCHIVE" ]] || err "未找到 $MAVEN_ARCHIVE"

# ===== 解压并安装 =====
info "安装 Maven 到 $INSTALL_DIR"
sudo mkdir -p "$INSTALL_BASE"

if [[ -d "$INSTALL_DIR" ]]; then
    warn "已存在 $INSTALL_DIR，跳过解压"
else
    sudo unzip -q "$MAVEN_ARCHIVE" -d "$INSTALL_BASE"
    ok "解压完成"
fi

[[ -x "$INSTALL_DIR/bin/mvn" ]] || err "mvn 可执行文件不存在"

# ===== 配置环境变量（用户级）=====
info "配置环境变量到 $PROFILE_FILE"

# 删除旧配置（仅 Maven）
sed -i '/# >>> maven >>>/,/# <<< maven <<</d' "$PROFILE_FILE"

cat >> "$PROFILE_FILE" <<EOF

# >>> maven >>>
export MAVEN_HOME=$INSTALL_DIR
export PATH=\$MAVEN_HOME/bin:\$PATH
# <<< maven <<<
EOF

# 立即生效
export MAVEN_HOME="$INSTALL_DIR"
export PATH="$MAVEN_HOME/bin:$PATH"

# ===== 验证 =====
info "验证 Maven"
mvn -v | head -n 1

ok "Maven ${MAVEN_VERSION} 安装完成"
info "如新终端中 mvn 不生效，请执行: source ~/.bashrc"

如果想卸载：

#!/usr/bin/env bash
set -e

# ===== 配置区 =====
MAVEN_VERSION="3.8.8"
INSTALL_DIR="/opt/apache-maven-${MAVEN_VERSION}"
PROFILE_FILE="$HOME/.bashrc"

info() { echo -e "\033[0;34m[INFO]\033[0m $1"; }
ok()   { echo -e "\033[0;32m[OK]\033[0m   $1"; }
warn() { echo -e "\033[0;33m[WARN]\033[0m $1"; }

# ===== 删除 Maven =====
if [[ -d "$INSTALL_DIR" ]]; then
    info "删除 $INSTALL_DIR"
    sudo rm -rf "$INSTALL_DIR"
    ok "Maven 文件已删除"
else
    warn "$INSTALL_DIR 不存在，跳过"
fi

# ===== 清理环境变量 =====
info "清理 ~/.bashrc 中的 Maven 配置"
sed -i '/# >>> maven >>>/,/# <<< maven <<</d' "$PROFILE_FILE"

ok "环境变量已清理"
info "请执行: source ~/.bashrc 或重新打开终端"

docker

docker上需要做的事：拉取mysql，redis，mq等镜像，然后直接启动，还有就是部署一整个项目

windows上安装docker直接参考WSL 上的 Docker 容器入门 | Microsoft Learn

按教程一路点下去（先配置WSL2再安装docker，这样docker会自动在wsl2配好对应docker环境）

之后要使用docker的时候先在windows上启动docker desktop，然后在wsl2中操作

mysql

拉取mysql镜像

docker pull registry.cn-hangzhou.aliyuncs.com/xfg-studio/mysql:8.0.32

在clone下来的env环境中，找到run_install_software.sh

添加可执行权限后运行

选择安装mysql

默认用户：root

默认密码：123456

默认端口：wsl2的13306

redis

拉取redis镜像

docker pull registry.cn-hangzhou.aliyuncs.com/xfg-studio/redis:6.2

在clone下来的env环境中，找到run_install_software.sh

添加可执行权限后运行

选择安装redis

无用户名无密码

默认端口：wsl2的16379

可以使用docker tag给镜像起其他名称

项目部署

内网穿透

下载地址：NATAPP-内网穿透

使用方式也很简单，下载exe客户端放到一个固定位置，配置config.ini：

# https://natapp.cn/ - 支持免费使用，但付费会更稳定一些
# 将本文件放置于natapp同级目录 程序将读取 [default] 段
# 在命令行参数模式如 natapp -authtoken=xxx 等相同参数将会覆盖掉此配置
# 命令行参数 -config= 可以指定任意config.ini文件
[default]
authtoken=      #对应一条隧道的authtoken，你需要更换为你的。否则不能正常启动。
clienttoken=                    #对应客户端的clienttoken,将会忽略authtoken,若无请留空,
log=none                        #log 日志文件,可指定本地文件, none=不做记录,stdout=直接屏幕输出 ,默认为none
loglevel=ERROR                  #日志等级 DEBUG, INFO, WARNING, ERROR 默认为 DEBUG
http_proxy=                     #代理设置 如 http://10.123.10.10:3128 非代理上网用户请务必留空

微信鉴权

配置NATAPP：在NATAPP中购买一个VIP隧道，顺道买一个二级域名，配置本地web端口为本地web服务的端口

微信测试平台：测试平台

注册之后：

记录右上角的微信号
接口配置信息的URL配置为本地web服务中处理微信鉴权的controller地址：组合以下两个

二级域名：http://baishui.nat100.top/

本地接口：api/v1/weixin/portal/receive
接口配置信息的Token随便设置就行
JS接口安全域名就填上面二级域名

配置完之后，启动本地服务，此时提交接口配置信息会成功，失败的话查看本地服务的报错即可

扫描测试号二维码，关注，发送信息，此时信息会被微信服务器转发给本地服务处理

Fuzzing101-xpdf

Tue, 13 Jan 2026 00:00:00 GMT

环境准备

这里的环境还是使用第一次构建的docker环境

在物理机上创建目录下载文件：

cd ~/github
mkdir fuzzing_xpdf && cd fuzzing_xpdf
# 下载xpdf3.02版本并解压
wget https://dl.xpdfreader.com/old/xpdf-3.02.tar.gz
tar -xvzf xpdf-3.02.tar.gz

创建docker环境，--name参数会给该容器命名为"fuzzing101"
```
docker run --name "fuzzing101" -it \
  -v "$(pwd)":/target \
  aflpp-built
```
这表示将会使用aflpp-built镜像来创建一个容器，同时将本地的~/github/fuzzing_xpdf目录挂载在容器内的/target目录下

由于没有了--rm参数，所以该容器在关闭后不会自行删除，如果需要重新启动，需要使用docker start fuzzing101命令，同时，无法更改挂载的本地目录，如果需要更改，最好删除容器并重新构建一个
aflpp-built镜像里预先编译过了AFLPLUSPLUS项目，直接使用对应的编译器来编译xpdf3.02

有几个需要注意的点：
- AFL++一直在更新，LLVM_CONFIG需要使用对应的版本，我这里是19
- 如果之前AFL++项目安装过，可以不必指定afl编译器的完整路径，只指定编译器名
```
export LLVM_CONFIG="llvm-config-19"
CC=afl-clang-fast CXX=afl-clang-fast++ ./configure --prefix="./fuzzing_xpdf/install/"
make
make install
```

准备测试文件：

在fuzzing_xpdf目录下：

cd $HOME/fuzzing_xpdf
mkdir pdf_examples && cd pdf_examples
wget https://github.com/mozilla/pdf.js-sample-files/raw/master/helloworld.pdf
# 剩下两个网址已失效, 直接github找一个仓库拉取即可
# wget http://www.africau.edu/images/default/sample.pdf
# wget https://www.melbpc.org.au/wp-content/uploads/2017/10/small-example-pdf-file.pdf

测试启动

环境准备完毕后，使用下面的命令运行模糊测试器：

afl-fuzz -i ./fuzzing_xpdf/pdf_examples/ -o ./fuzzing_xpdf/out/ -s 123 -- ./fuzzing_xpdf/install/bin/pdftotext @@ ./fuzzing_xpdf/output

-i 指示我们需要放置输入案例（即文件示例）的目录，这里就是fuzzing_xpdf/pdf_examples
-o 就是AFL++记录运行结果的目录，包括编译后的文件，统计路径信息等
-s 表示要使用的静态随机种子，这使得模糊测试的过程是可复现的。如果你使用相同的种子、相同的输入和相同的目标程序再次运行 AFL，它将以完全相同的方式生成和测试输入。这对于复现和调试特定的崩溃很有用
@@ 是占位符目标命令行，AFL 会将其替换为每个输入文件名，xpdf3.02需要接受一个命令行参数（也就是pdf文件路径），AFL++在每次执行xpdf的时候会把@@换成对应的文件路径

测试结果

空指针错误

先用AFL++测了一个小时，前3个漏洞大致都相同，只能单独使程序出错，但不会耗尽资源

漏洞出错的主要原因是流读取时出错，break之后没有做错误检查，导致的空指针异常

这次使用镜像内自带的lldb-19来调试程序：

# --参数就相当于gdb的--args参数
lldb-19 -- ./install/bin/pdftotext
# 禁用地址随机化以调试程序
(lldb) settings set target.disable-aslr false
# 运行程序
(lldb) run out/default/crashes/id:000000,sig:11,src:001033,time:276919,execs:242688,op:havoc,rep:3
Process 93421 launched: '/target/install/bin/pdftotext' (x86_64)

查看栈帧：

(lldb) bt
* thread #1, name = 'pdftotext', stop reason = signal SIGSEGV: address not mapped to object (fault address: 0x0)
  * frame #0: 0x000055814c6dfcdc pdftotext`EmbedStream::getChar(this=0x0000558177919510) at Stream.cc:787:22
    frame #1: 0x000055814c6915a4 pdftotext`Gfx::opBeginImage(this=0x0000558177917600, args=0x00007ffc97979b30, numArgs=0) at Gfx.cc:3880:44
    frame #2: 0x000055814c67f639 pdftotext`Gfx::execOp(this=0x0000558177917600, cmd=0x00007ffc97979b20, args=0x00007ffc97979b30, numArgs=0) at Gfx.cc:690:20
    frame #3: 0x000055814c67f008 pdftotext`Gfx::go(this=0x0000558177917600, topLevel=1) at Gfx.cc:581:13
    frame #4: 0x000055814c67ede1 pdftotext`Gfx::display(this=0x0000558177917600, obj=0x00007ffc97979e80, topLevel=1) at Gfx.cc:553:5
    frame #5: 0x000055814c6d8c10 pdftotext`Page::displaySlice(this=0x00005581779156e0, out=0x0000558177914e80, hDPI=72, vDPI=72, rotate=0, useMediaBox=0, crop=0, sliceX=-1, sliceY=-1, sliceW=-1, sliceH=-1, printing=0, catalog=0x00005581779144b0, abortCheckCbk=0x0000000000000000, abortCheckCbkData=0x0000000000000000) at Page.cc:317:17
    frame #6: 0x000055814c6d87e6 pdftotext`Page::display(this=0x00005581779156e0, out=0x0000558177914e80, hDPI=72, vDPI=72, rotate=0, useMediaBox=0, crop=1, printing=0, catalog=0x00005581779144b0, abortCheckCbk=0x0000000000000000, abortCheckCbkData=0x0000000000000000) at Page.cc:264:15
    frame #7: 0x000055814c6db49b pdftotext`PDFDoc::displayPage(this=0x0000558177914fe0, out=0x0000558177914e80, page=1, hDPI=72, vDPI=72, rotate=0, useMediaBox=0, crop=1, printing=0, abortCheckCbk=0x0000000000000000, abortCheckCbkData=0x0000000000000000) at PDFDoc.cc:317:34
    frame #8: 0x000055814c6db519 pdftotext`PDFDoc::displayPages(this=0x0000558177914fe0, out=0x0000558177914e80, firstPage=1, lastPage=1, hDPI=72, vDPI=72, rotate=0, useMediaBox=0, crop=1, printing=0, abortCheckCbk=0x0000000000000000, abortCheckCbkData=0x0000000000000000) at PDFDoc.cc:330:16
    frame #9: 0x000055814c6ff0f9 pdftotext`main(argc=2, argv=0x00007ffc9797a218) at pdftotext.cc:237:22

在最后一个栈帧发现str是一个null，对应的代码：

int EmbedStream::getChar() {
  if (limited && !length) {
    return EOF;
  }
  --length;
  // str为null, 这里进行的空指针调用
  return str->getChar();
}

向上找栈帧，找到了str被赋值的代码：

void Gfx::opBeginImage(Object args[], int numArgs) {
  Stream *str;
  int c1, c2;

  // build dict/stream
  // str变量在这里被赋值
  str = buildImageStream();
  ...
  // 崩溃点
  c1 = str->getUndecodedStream()->getChar();
}

继续找这个buildImageStream函数：

Stream *Gfx::buildImageStream() {
  Object dict;
  Object obj;
  char *key;
  Stream *str;

  // build dictionary
  dict.initDict(xref);
  parser->getObj(&obj);
  while (!obj.isCmd("ID") && !obj.isEOF()) {
    if (!obj.isName()) {
      error(getPos(), "Inline image dictionary key must be a name object");
      obj.free();
    } else {
      key = copyString(obj.getName());
      obj.free();
      parser->getObj(&obj);
      if (obj.isEOF() || obj.isError()) {
	gfree(key);
	break;
      }
      dict.dictAdd(key, &obj);
    }
    parser->getObj(&obj);
  }
  if (obj.isEOF()) {
    error(getPos(), "End of file in inline image");
    obj.free();
    dict.free();
    return NULL;
  }
  obj.free();

  // make stream
  str = new EmbedStream(parser->getStream(), &dict, gFalse, 0);
  str = str->addFilters(&dict);

  return str;
}

可以看到str是一个EmbedStream类型的对象，才搞清楚这里new出来的str（也就是EmbedStream类型有一个成员也叫str），所以实际上是str->str为一个空指针

打上断点，调试发现，问题出在buildImageStream里的while循环，在里面break的时候是由于obj.isError()，但是break之后没有检查这个条件，导致构建对象时由于出错错误的设置了成员变量的初始值

修复：while循环之后额外检查obj.isError，如果为真就return NULL

栈溢出错误

第4个漏洞是重量级漏洞：栈溢出漏洞

使用lldb-19启动调试，输入崩溃文件，stack很明显的溢出

由于栈帧没法从main开始看，只能使用bt命令在终端打印所有栈帧

从栈帧看出来，在XRef::getCatalog中调用XRef::fetch之后，启动了一个递归调用过程，导致了栈溢出

从PDFDoc::setup看出，传了一个文档拥有者的密码和用户密码，下一个调用是catalog = new Catalog(xref)，传入的xref对象是用str->reset()初始化的，并且经过了检查，密码也经过了检查，继续深入

GBool PDFDoc::setup(GString *ownerPassword, GString *userPassword) {
  str->reset();

  // check header
  checkHeader();

  // read xref table
  xref = new XRef(str);
  if (!xref->isOk()) {
    error(-1, "Couldn't read xref table");
    errCode = xref->getErrorCode();
    return gFalse;
  }

  // check for encryption
  if (!checkEncryption(ownerPassword, userPassword)) {
    errCode = errEncrypted;
    return gFalse;
  }

  // read catalog
  catalog = new Catalog(xref);
  if (!catalog->isOk()) {
    error(-1, "Couldn't read page catalog");
    errCode = errBadCatalog;
    return gFalse;
  }

#ifndef DISABLE_OUTLINE
  // read outline
  outline = new Outline(catalog->getOutline(), xref);
#endif

  // done
  return gTrue;
}

catalog只看构造函数中的一部分即可，构造函数中会调用xref->getCatalog(&catDict)，这个catDict重点关注一下，其是一个Object类型的对象

Catalog::Catalog(XRef *xrefA) {
  Object catDict, pagesDict, pagesDictRef;
  Object obj, obj2;
  char *alreadyRead;
  int numPages0;
  int i;

  ok = gTrue;
  xref = xrefA;
  pages = NULL;
  pageRefs = NULL;
  numPages = pagesSize = 0;
  baseURI = NULL;
  // 这里是出问题的地方
  xref->getCatalog(&catDict);
  if (!catDict.isDict()) {
    error(-1, "Catalog object is wrong type (%s)", catDict.getTypeName());
    goto err1;
  }
  ...
}

Object类型的私有数据：

private:

  ObjType type;			// object type
  union {			// value for each type:
    GBool booln;		//   boolean
    int intg;			//   integer
    double real;		//   real
    GString *string;		//   string
    char *name;			//   name
    Array *array;		//   array
    Dict *dict;			//   dictionary
    Stream *stream;		//   stream
    Ref ref;			//   indirect reference
    char *cmd;			//   command
  };

catDict调用了Object的构造函数，只会将其type设置为None，推测xref->getCatalog(&catDict)是为这个catDict赋值，继续查看下一个调用链

fetch函数，其中obj就是上面的catDict

无限循环发生在switch语句中，在case xrefEntryUncompressed: 里：

其首先初始化了一个parser
从parser中初始化三个object
检查过后，进入parser->getObj(obj, encrypted ? fileKey : (Guchar *)NULL, encAlgorithm, keyLength, num, gen);无开始无限递归

Object *XRef::fetch(int num, int gen, Object *obj) {
  XRefEntry *e;
  Parser *parser;
  Object obj1, obj2, obj3;

  // check for bogus ref - this can happen in corrupted PDF files
  if (num < 0 || num >= size) {
    goto err;
  }

  e = &entries[num];
  switch (e->type) {

  case xrefEntryUncompressed:
    if (e->gen != gen) {
      goto err;
    }
    obj1.initNull();
    parser = new Parser(this,
	       new Lexer(this,
		 str->makeSubStream(start + e->offset, gFalse, 0, &obj1)),
	       gTrue);
    parser->getObj(&obj1);
    parser->getObj(&obj2);
    parser->getObj(&obj3);
    if (!obj1.isInt() || obj1.getInt() != num ||
	!obj2.isInt() || obj2.getInt() != gen ||
	!obj3.isCmd("obj")) {
      obj1.free();
      obj2.free();
      obj3.free();
      delete parser;
      goto err;
    }
    // 从这里开始就进入无限循环了
    parser->getObj(obj, encrypted ? fileKey : (Guchar *)NULL,
		   encAlgorithm, keyLength, num, gen);
    obj1.free();
    obj2.free();
    obj3.free();
    delete parser;
    break;
    ...
}

通过调试，parser->getObj(obj, encrypted ? fileKey : (Guchar *)NULL, encAlgorithm, keyLength, num, gen);中的参数分别为：

继续跟踪到Parser中，这里先初始化了obj，也就是传入的catDict这个字典，然后向这个字典中添加数据，在进行了一系列的递归初始化数据与添加之后，执行了makeStream函数
在makeStream函数中执行addFilters函数
最后找到Dict.cc文件中的Object *Dict::lookup(char *key, Object *obj)函数

当该函数被调用时，比如Stream.cc文件中调用dict->dictLookup()函数，

该函数负责在一个字典对象中根据"key"找一个"value"，并将该"value"赋值给一个对象，但是"value"本身可能是一个间接引用（就像指针一样指向别的地方），这个时候就需要继续去找，此时如果出现循环引用的问题，就会不停的找下去（类似两个类对象互相持有std::shared_ptr最后无法释放），AFL++恶意构造的坏PDF文件中出现了这种引用并被xpdf程序记录到字典对象中，导致parser解析失败并进行循环调用，最后爆栈

修复：这是parser本身设计的失误，改起来应该比较困难，看了一下新版本源码，直接限制了dictLookup的次数，这样就限制了找间接引用的次数，从而不会爆栈

HELP. vscode进行图形化调试

直接使用lldb-19这样的终端调试工具在打断点和调试的过程中可能不顺手，可以借用codelldb插件

直接F5自动创建一个launch.json，填写以下内容：

{
    // 使用 IntelliSense 了解相关属性。 
    // 悬停以查看现有属性的描述。
    // 欲了解更多信息，请访问: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug pdftotext",
            "type": "lldb",
            "request": "launch",
            "program": "${workspaceRoot}/install/bin/pdftotext",
            "args": [
                // 这里是可执行程序需要的命令行参数 "${workspaceRoot}/out/default/crashes/id:000000,sig:11,src:001033,time:276919,execs:242688,op:havoc,rep:3",
                // 将转换后的文本输出到标准输出
                "-" 
            ],
            "cwd": "${workspaceRoot}",
            "sourceMap": {
                // 将编译时记录的源码路径映射到当前工作区的实际路径
                // 假设编译时的源码根目录是 /target/xpdf-3.02
                "/target/xpdf-3.02": "${workspaceRoot}/xpdf-3.02"
            }
        }
    ]
}

AFL++ Fuzzing-Module模糊测试入门

Sat, 03 Jan 2026 00:00:00 GMT

1. 环境准备

1.1 配置docker

安装参考这一篇：

Ubuntu 安装 Docker 的方法（基于Ubuntu 24.04 LTS测试） - 星尘的博客 - 博客园

镜像站使用的是1ms，貌似能够下载AFL++的image：

{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.m.daocloud.io"
  ]
}

1.2 配置AFL++容器

拉AFL++镜像：docker pull aflplusplus/aflplusplus

然后执行docker images应该能看到aflplusplus/aflplusplus:latest这个标识
运行AFL++的镜像：docker run -it --name aflpp aflplusplus/aflplusplus

该命令会自动创建一个容器
- -it表示自动进入容器内的终端
- --name表示给这个容器起名叫aflpp
- aflplusplus/aflplusplus表示指定了镜像名称
在容器内的终端里进入/AFLplusplus文件夹，然后执行make命令构建即可
退出容器exit
查看容器ID：docker ps- a

该命令会查看当前创建的所有容器（包括正在运行的和停止的）
提交该容器：docker commit aflpp aflpp-built
- aflpp：指定容器名
- aflpp-built：指定新镜像名字
作用是将一个容器提交为一个新镜像
克隆fuzzing-module项目：git clone https://github.com/alex-maleno/Fuzzing-Module.git
进入fuzzing-module项目的根目录，执行命令：
```
docker run --rm -it \
  -v "$(pwd)":/target \
  aflpp-built
```
这表示使用aflpp-built启动一个容器，将本地的fuzzing-module所在目录挂载到容器的/target目录中，并在容器退出后自动删除该容器

至此，AFL++容器的配置都已经完成

2. 练习1

2.1 编译代码

在fuzzing-module项目根目录进容器：

docker run --rm -it \
  -v "$(pwd)":/target \
  aflpp-built

进入target目录：cd /target
可以看到原先的exercisexxx都在该目录下，进入exercise1
mkdir build && cd build

编译项目，指定AFL++项目构建出的编译器：

CC=/AFLplusplus/afl-clang-fast CXX=/AFLplusplus/afl-clang-fast++ cmake ..
make

2.2 运行AFL++

构建种子文件：

# 回到exercise1目录下，创建seeds目录并进入，将种子文件生成在该目录下
cd ..
mkdir seeds && cd seeds
for i in {0..4}; do dd if=/dev/urandom of=seed_$i bs=64 count=10; done
cd ..
cd build

使用AFL++运行分析目标程序/target/exercise1/build/simple_crash：

/AFLplusplus/afl-fuzz -i /target/exercise1/seeds -o out -m none -d -- /target/exercise1/build/simple_crash

然后会有一个终端图形界面出来，显示正在运行，当上面的crashes数字变更后，就可以强制停止了，生成的文件在target/exercise1/build/out/default目录里，其中/crashes目录是需要重点关注的文件夹

2.3 分析

2.3.1 目录介绍

首先依次解释一下default目录下各个文件夹的作用：

结果目录：
- crashes/: （最重要） 这是一个目录，存放导致目标程序崩溃（例如，段错误 SIGSEGV、中止 SIGABRT 等）的输入文件。你应该首先分析这里的文件，因为它们直接指向了潜在的安全漏洞。
- hangs/: 这是一个目录，存放导致目标程序超时（未在指定时间内完成执行）的输入文件。这些输入可能触发了死循环或非常耗时的操作，可能对应于拒绝服务（DoS）漏洞。
语料库和状态：
- queue/: 这是一个目录，包含了所有“有趣”的测试用例（也称为语料库）。AFL++ 会将任何能够触发新代码路径（即覆盖新的“边”）的输入文件保存在这里。这些文件是 fuzzer 进行变异的基础。
- fuzz_bitmap: 这是一个二进制文件，记录了整个测试过程中所有被触发过的代码路径的“位图”。fuzzer 通过检查新输入是否会在此位图中点亮新的比特位，来判断该输入是否“有趣”。
- fastresume.bin: 这是 AFL++ 的一个特性文件。它存储了 queue 目录中每个文件的元数据摘要，使得在恢复或重启 fuzzer 时可以非常快速地加载语料库，而无需重新分析每个文件。
统计和监控：
- fuzzer_stats: 一个人类可读的文本文件，包含了 fuzzer 运行时的详细统计信息。你可以通过 cat build/out/default/fuzzer_stats 查看，内容包括运行时间、执行速度、总路径数、崩溃数、周期数等。这是监控 fuzzer 状态的主要文件。
- plot_data: 一个逗号分隔值（CSV）格式的文本文件，用于绘制 fuzzer 运行状态图。它记录了随时间变化的各种统计数据（如路径数、崩溃数等）。你可以使用 afl-plot 工具来将此文件可视化，例如：afl-plot build/out/default /path/to/plot/output。
配置和信息：
- cmdline: 记录了启动本次 fuzzer 时所使用的完整命令行参数。这对于复现测试环境非常有用。
- fuzzer_setup: 记录了 fuzzer 启动时的一些关键设置和检测到的环境信息，例如 CPU 亲和性、内存限制等。
- target_hash: 包含了目标二进制文件的 SHA256 哈希值。AFL++ 使用它来检测目标程序是否在 fuzzer 运行期间被修改过。

2.3.2 补充模糊测试基本知识

在分析之前，补充一些模糊测试的基本知识：

为什么必须使用 AFL++ 的编译器？

简而言之：为了插桩 (Instrumentation)。

AFL++ 不是一个“盲目”的 fuzzer。它是一个覆盖率引导 (Coverage-guided) 的 fuzzer。这意味着它需要知道一个输入执行了程序的哪些代码路径，从而判断这个输入是否“有趣”（即是否探索了新的代码区域）。如果一个输入触发了新的代码路径，AFL++ 就会将其保留下来，并作为未来变异的基础。

为了实现这一点，AFL++ 提供了一套编译器包装器（如 afl-clang-fast++, afl-gcc 等）。当你使用这些编译器来构建你的目标程序时，它们会在编译过程中向你的程序中注入（或称“插入”）一些额外的代码。这些被注入的代码非常轻量，主要做一件事：
- 在程序的每个基本块（或分支跳转）处，插入一小段代码来更新一个共享的内存区域（称为“位图”或 bitmap）。
这样，当你的程序运行时：
1. 每执行到一个新的代码分支，插桩代码就会被触发。
2. 它会根据当前位置和上一个位置计算一个哈希值，并用这个哈希值作为索引，在共享内存位图中对应的位置做一个标记。
3. afl-fuzz 主进程会监控这个位图。如果一个变异后的输入导致位图中出现了之前从未有过的标记，afl-fuzz 就知道这个输入发现了一条新路径。
结论： 如果不使用 AFL++ 的编译器进行插桩，afl-fuzz 就无法获得代码覆盖率的反馈。它会退化成一个“哑”fuzzer，只能随机生成输入，效率极低，也无法有效地探索程序深处的逻辑。
种子 (Seed) 的作用和内容是什么？

种子是模糊测试的起始点。afl-fuzz 不会从零开始完全随机地生成输入，而是会读取你提供的种子文件，将它们作为初始的测试用例集合。然后，它会对这些种子进行各种变异（比特翻转、算术运算、拼接、删除等）来生成新的输入，再去测试目标程序。

一个好的种子集合可以极大地提升模糊测试的效率，因为：
- 提供初始覆盖率：如果种子本身就是合法的、能够被程序正确解析的输入（例如，一个有效的 PNG 图片作为图片解析器的种子），那么 fuzzer 从一开始就能覆盖到程序的核心处理逻辑，而不是浪费时间去“猜”出一个合法的文件格式。
- 提供变异的“原材料”：基于一个结构良好的种子进行小幅变异，更有可能产生能通过初始解析并触发更深层逻辑的有效输入。
种子的内容可以看做是程序的输入

比如程序接受一个字符串，那就种子的内容就是一个字符串

程序接受一个64×64的图片，种子的内容就可以是64×64的，数值在0~255之间的二维数组

dd 命令生成的内容：
```
for i in {0..4}; do dd if=/dev/urandom of=seed_$i bs=64 count=10; done
```
这个命令的作用是创建 5 个（seed_0 到 seed_4）种子文件。每个文件包含 64 * 10 = 640 字节的完全随机的数据，这些数据来源于 urandom（Linux 系统中的一个高质量随机数生成器）。

在这种情况下，生成的种子是随机的、无结构的二进制数据。这适用于测试那些期望接收任意二进制流的程序。但对于需要特定文件格式（如 XML, JSON, PNG）的程序，使用完全随机的数据作为种子效果很差。更好的做法是提供一些结构合法、内容简单的真实文件作为种子。
afl-fuzz 命令和参数的解释
```
afl-fuzz -i [seeds directory] -o out -m none -d -- [path to the executable]
```
这个命令是启动 AFL++ fuzzer 的核心指令。
- afl-fuzz: 启动 fuzzer 的主程序。
- -i [full path to your seeds directory]: 指定**输入（input）**目录，也就是你存放种子文件的目录。afl-fuzz 会从这里加载初始测试用例。
- -o out: 指定**输出（output）**目录。所有 fuzzer 的发现和状态都会保存在这个名为 out 的目录中，包括我们之前讨论的 crashes/, queue/, fuzzer_stats 等。
- -m none: 设置内存限制（memory limit）。none 表示不为目标程序设置内存限制。这通常在你知道程序本身内存占用较大，或者在受控环境（如 Docker）中已经有全局内存限制时使用，以避免 fuzzer 因误判而频繁杀死正常运行的子进程。默认情况下，AFL++ 会设置一个比较严格的内存限制。
- -d: 启用**“确定性”变异阶段（deterministic** stages）。在进行完全随机的“havoc”变异之前，AFL++ 会先尝试一些简单的、可预测的变异策略，如按位翻转、整数加减等。这是一个非常高效的阶段，通常能很快找到浅层的 bug。-d 标志可以跳过这个阶段，直接进入随机性更强的 havoc 阶段。在某些情况下，如果种子文件非常大或者确定性变异阶段耗时过长，可以使用 -d 来加速。但在大多数情况下，建议保留确定性阶段。
- --: 这是一个分隔符。它告诉 afl-fuzz，后面的所有参数都属于要执行的目标程序命令，而不是 afl-fuzz 自身的参数。
- [full path to the executable]: 你要测试的目标程序的路径和名称。afl-fuzz 会反复执行这个程序。AFL++ 通常会通过 @@ 来指定输入文件的位置，例如 /path/to/my_app @@。如果省略 @@，AFL++ 默认会通过标准输入（stdin）将测试用例喂给目标程序。

2.3.3 调试程序找出bug

文件解释：

导致程序崩溃的文件都在build/out/default/crashes下，其文件名即各种元信息的组合：

以 id:000000,sig:06,src:000004,time:160,execs:116,op:flip4,pos:7 为例：
- id:000000: 崩溃的唯一标识符，从 0 开始递增。
- sig:06: （关键信息） 导致程序终止的信号编号。06 代表 SIGABRT (Abort)，通常由断言失败 assert() 或其他库检测到的内部错误触发。另一个常见的是 sig:11，代表 SIGSEGV (Segmentation Fault)，即段错误，通常由无效的内存访问（如空指针解引用、越界读写）引起。
- src:000004: 源输入文件的 ID。这个崩溃是由 queue/id:000004 文件经过变异得到的。
- time:160: 发现此崩溃时，fuzzer 已经运行的时间（毫秒）。
- execs:116: 发现此崩溃时，fuzzer 已经执行的总次数。
- op:flip4: 产生这个崩溃的最后一个变异操作是 flip4（翻转了文件中的 4 个比特位）。
- pos:7: 变异操作发生在源文件的偏移量 7 处。
文件内容即导致目标崩溃的内容
gdb调试程序

进入/build目录下
- 开启调试：gdb --args ./simple_crash
- 在 GDB 提示符 (gdb) 后，输入 run 命令并重定向输入：run < build/out/default/crashes/id:000000,sig:06,src:000004,time:160,execs:116,op:flip4,pos:7
- 分析崩溃点：程序会在崩溃处停下来。GDB 会显示导致崩溃的代码行。然后你可以使用以下命令来检查程序状态：
 - bt (backtrace): 显示函数调用栈。这是最有用的命令，可以让你看到函数是如何一步步调用到崩溃点的。
 - p <variable> (print): 打印变量的值。
 - info registers: 显示寄存器的值。
 - info locals: 显示当前栈帧的局部变量。
 - x/i $pc: 查看当前指令。

通过源码和接收的字符串来看，程序接受一行字符串，如果该字符串有效范围内的的第一个字符和最后一个字符都是\x00，或者字符串内有递增的数字字符出现（比如"0@1"），就会崩溃

3. 练习2

和练习1没什么区别，就是封装了一个类，在interact函数里面接收标准输入流

初始有两个乘员，Captain，CoPilot
t：飞机有乘员则起飞
l：飞机有乘员则降落
h：增加一个乘员
f：减少一个乘员

指定l命令时，如果没有乘员就abort

4. 练习3

该练习主要介绍slice-fuzzing的办法，人话就是只针对部分代码片段进行模糊测试

exercise3中给了一个例子：

/*
 *
 *
 * This file isolates the Specs class and tests out the 
 * choose_color function specifically.
 * 
 * 
 * 
 */

#include "specs.h"

int main(int argc, char** argv) {
    // In order to call any functions in the Specs class, a Specs
    // object is necessary. This is using one of the constructors
    // found in the Specs class.
    Specs spec(505, 110, 50);
    // By looking at all the code in our project, this is all the 
    // necessary setup required. Most projects will have much more
    // that is needed to be done in order to properly setup objects.

    // This section should be in your code that you write after all the 
    // necessary setup is done. It allows AFL++ to start from here in 
    // your main() to save time and just throw new input at the target.
    #ifdef __AFL_HAVE_MANUAL_CONTROL
        __AFL_INIT();
    #endif

    spec.choose_color();
    //spec.min_alt();

    return 0;
}

该代码独立main.cpp，在cmake中被额外添加构建可执行文件的规则，这相当于主动编写模糊测试驱动程序，在这个程序中，只去测试Specs类的choose_color()功能, 然后连接 Fuzzer：它包含接收 fuzzer 输入并传递给目标函数的逻辑（这部分通常是隐式的，例如目标函数从标准输入读取数据）

AFL++持久模式：

标准的模糊测试流程中：AFL++ 每测试一个输入，都需要：

启动一个全新的进程。
在那个新进程里，从main函数开始完整地执行一遍程序。
程序执行完毕后，销毁进程。

如果在 fuzz 的关键步骤前面有诸如“载入配置文件”等步骤，仍然会造成效率浪费。因此，我们可以自行选择 fuzz 入口，然后添加以下代码：

#ifdef __AFL_HAVE_MANUAL_CONTROL
  __AFL_INIT();
#endif

该代码之前的部分只被执行一次，之后的部分才是测试的重点，会不断执行，以此来提高fuzzing的效率

自定义切片代码：

类似给出的样例，可以创建cpp文件来测试需要的函数：

#include "specs.h"

int main(int argc, char** argv) {
    Specs spec(505, 110, 50);
    
    #ifdef __AFL_HAVE_MANUAL_CONTROL
        __AFL_INIT();
    #endif

    spec.fuel_cap();

    return 0;
}

在cmake添加构建规则，然后指定fuzz的目标即可

linux环境下cmake + clangd + lldb搭建cpp开发环境

Mon, 03 Nov 2025 00:00:00 GMT

linux环境下cmake + clangd + lldb搭建cpp开发环境

一. 基础环境

wsl2
ubuntu22
ubuntu24

以上均可（其他没试过，不过理论上都可以）

二. 源配置

如果要配置多编译器环境或者更想用gcc/g++，这里的源配置主要针对需要下载高等级的gcc版本

由于一些低版本的ubuntu（如22）默认下载gcc11版本，如果想要下载更高的版本，12以及往上，可以使用下面两条命令：

sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo add-apt-repository ppa:ubuntu-toolchain-r/ppa

然后可以安装高版本的gcc和g++

apt search gcc-12
# apt search gcc-13
sudo apt install gcc-12
sudo apt install g++-12

不过由于是国外源，下载的会比较慢，需要额外配置镜像（这个镜像不是/etc/apt/sources.list文件）

执行上面两条add-apt-repository命令后，查看/etc/apt/sources.list.d目录：

ll /etc/apt/sources.list.d

如下图所示（一个ppa，一个test）：

以ppa-jammy.list为例，里面的内容原本是：

deb https://ppa.launchpadcontent.net/ubuntu-toolchain-r/ppa/ubuntu/ jammy main 
# deb-src https://ppa.launchpadcontent.net/ubuntu-toolchain-r/ppa/ubuntu/ jammy main

使用如下命令换为中科大的源（最后两个参数是ppa和test两个文件名）：

sudo sed -i 's|https://ppa.launchpadcontent.net|https://launchpad.proxy.ustclug.org|g' /etc/apt/sources.list.d/ubuntu-toolchain-r-ubuntu-ppa-jammy.list /etc/apt/sources.list.d/ubuntu-toolchain-r-ubuntu-test-jammy.list

然后执行：

sudo apt update
sudo apt install gcc-12 g++-12

就会快很多了

三. gcc/g++版本切换（可选）

如果电脑下有多个gcc/g++，想要切换版本，首先查看各个gcc/g++的版本号：

ls -l /usr/bin | grep gcc

如下图：

使用update-alternatives命令设置各个gcc/g++的优先级：

# 13的权值是100, 11是80...
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-13 100 --slave /usr/bin/g++ g++ /usr/bin/g++-13 --slave /usr/bin/gcov gcov /usr/bin/gcov-13
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 80 --slave /usr/bin/g++ g++ /usr/bin/g++-11 --slave /usr/bin/gcov gcov /usr/bin/gcov-11
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 60 --slave /usr/bin/g++ g++ /usr/bin/g++-10 --slave /usr/bin/gcov gcov /usr/bin/gcov-10

设置完毕后再执行gcc -v就能看到当前是gcc-13

如果想要切换版本：

sudo update-alternatives --config gcc

如下图，选择对应版本即可：

四. llvm配置

国外的网址：apt llvm

找到下图中的脚本命令：

和版本：

（我安装的时候stable版本是20）

但不要执行，同样是由于国外源太慢的问题，这次换清华源：tsinghua apt llvm

在LLVM版本选为20（一般选stable版本就对了）

将上面的命令逐行粘贴到终端执行：

sudo wget https://mirrors.tuna.tsinghua.edu.cn/llvm-apt/llvm.sh
sudo chmod +x llvm.sh
sudo ./llvm.sh all -m https://mirrors.tuna.tsinghua.edu.cn/llvm-apt

之后再安装libstdc++，配置gcc/g++使用

sudo apt-get install libc++-20-dev libc++abi-20-dev

这样就安装好了llvm全套（clang/clang++/clangd/lldb）和libc++

五. cmake配置

不推荐直接从apt下载cmake，版本一般比较旧

一般从源码安装或者作者仓库中拉取，具体参考下面这篇文章：

ubuntu 22.04环境中cmake安装 - 知乎

六. vscode配置

插件安装列表（自行安装），还有一个Test Explorer UI插件没有截进来：

6.1 clangd

6.1.1 clangd path

刚下载完clangd，会弹窗提示没有下载clangd-server，这时候不要点击，直接去clangd设置中：

不是用户的设置而是wsl2或者虚拟机的设置中，找到Clangd: Path选项，之前下载llvm组件时已经下载了clangd-<version>（<version>是stable的版本号），直接填入到选项中：

6.1.2 .clangd配置系统文件寻找路径

使用clang/clang++头文件

在项目目录下创建.clangd文件，然后填入下面的内容：

CompileFlags:
  Add:
    - "-stdlib=libc++"  # 主要是这行
    - "-ferror-limit=0"
  Compiler: clang++-20

使用gcc，可以这么写（不需要配置-stdlib，因为linux下默认用libstdc++）：

CompileFlags:
  Add:
    - "-I/usr/include/c++/13" # 
    - "-ferror-limit=0"
  Compiler: g++-13

6.2 codelldb

6.2.1 安装vsix

下载插件后，可能会报错，弹窗open ... url，点击后在浏览器下载一个.vsix文件

然后在扩展中安装：

6.2.2 调试

配置好cmake tools之前的cmake项

打断点，按F5调试，一开始会报错，让创建launch.json文件，跟着步骤创建：

{
    // 使用 IntelliSense 了解相关属性。 
    // 悬停以查看现有属性的描述。
    // 欲了解更多信息，请访问: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "lldb",
            "request": "launch",
            "name": "Debug",
            "program": "${workspaceFolder}/<executable file>",
            "args": [],
            "cwd": "${workspaceFolder}"
        }
    ]
}

把"program"项换为可执行文件的位置，就可以正常调试了

6.3 cmake

6.3.1 cmake path

在CMake插件中的设置中，找到Cmake: Cmake Path选项，设置为cmake的可执行文件路径：

6.3.2 cmake快速创建项目

创建一个文件夹，然后使用vscode打开
Ctrl + Shift + P唤出命令面板
输入cmake:quick，找到CMake: Quick Start
按提示步骤完成剩余操作

6.3.3 CMAKE_EXPORT_COMPILE_COMMANDS

使用git下载一个cmake项目，比如fmt: git clone https://github.com/fmtlib/fmt.git

如果要使用clang++，则找到项目根目录下的CMakeLists.txt，加入：

# 生成 compile_commands.json
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

上述命令会在build目录下生成compile_commands.json，clangd会根据这个文件生成索引，存放在项目的.cache目录下，如果没有，可能不会正常工作

至此，clangd应该能够正常工作了

6.3.4 cmake tools

使用过clion和vs2022都清楚有比较方便的切换启动哪个可执行程序的功能，借助cmake tools插件，可以做到这一点，修改launch.json（主要是"program"项）：

{
    // 使用 IntelliSense 了解相关属性。 
    // 悬停以查看现有属性的描述。
    // 欲了解更多信息，请访问: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "lldb",
            "request": "launch",
            "name": "Debug",
            "program": "${command:cmake.launchTargetPath}",
            "args": [],
            "cwd": "${workspaceFolder}"
        }
    ]
}

在vscode左侧cmake-tools的图标中，选择启动和调试的目标即可：

6.4 unit-test

安装C++ TestMate和Test Explorer UI后，在左侧测试按钮中可以进行对应的测试：

在编译后也可以在对应的测试文件中直接使用图形化运行按钮进行测试

但是测试文件（指可执行文件）的识别默认为build或者out目录下的带有test名的文件，所以在生成可执行文件时要注意正确的命名：

七. windows下环境配置

请参考VSCode C/C++开发环境配置 Clang/LLVM+LLDB+CMake

windows上使用lldb和msvc stl只能看到stl组件的地址，看不到内容，建议直接使用cmake-tools自带的cppdbg，或者用lldb配合MinGW使用，个人认为window上还是直接用msvc工具链比较好

八. vcpkg配置

8.1 下载与环境配置

下载：

git clone https://github.com/microsoft/vcpkg.git # 克隆仓库
cd vcpkg
./bootstrap-vcpkg.sh # Linux bash

环境配置：

在~/.bashrc文件最后添加：

export VCPKG_ROOT=/path/to/vcpkg # vcpkg文件夹的实际路径
export PATH=$VCPKG_ROOT:$PATH

8.2 案例

创建vcpkg依赖

mkdir vcpkg_test && cd vcpkg_test
vcpkg new --application # 初始化vcpkg项目
vcpkg add port fmt # 添加 fmt 依赖项

创建cmake项目

Ctrl + Shift + P唤出vscode命令行，使用CMake: Quick Start创建cmake项目

设置CMakePresets.json

项目目录创建CMakePresets.json

{
    "version": 2,
    "configurePresets": [
        {
            "name": "vcpkg",
            "generator": "Ninja",
            "binaryDir": "${sourceDir}/build",
            "cacheVariables": {
                "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
            },
        }
    ]
}

如有需要可以再创建CMakeUserPresets.json

{
    "version": 2,
    "configurePresets": [
        {
            "name": "default",
            "inherits": "vcpkg",
            "environment": {
                "VCPKG_ROOT": "" // 填vcpkg的实际路径
            }
        }
    ]
}

此时可以在CMake-Tools提供的配置中选择对应的配置：

CMakeLists.txt，main.cpp

cmake_minimum_required(VERSION 3.10)

project(Helloworld)
# 生成 compile_commands.json
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -stdlib=libc++")
# 设置链接标志
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -stdlib=libc++ -lc++abi")
find_package(fmt CONFIG REQUIRED) # 指定vcpkg的查找的库

add_executable(Helloworld helloworld.cpp)

target_link_libraries(Helloworld PRIVATE fmt::fmt)

#include <fmt/core.h>
int main()
{
    fmt::print("Hello World!\n");
    return 0;
}

编译即可

如果要下载到全局可以直接：

vcpkg install fmt

路径在：

xxx/vcpkg/installed/x64-linux

如果要让clangd解析到对应的头文件，需要额外配置.clangd

CompileFlags:
  Add:
    - "-I/usr/include/c++/13" #
    - "-Isystem/xxx/vcpkg/installed/x64-linux/include"
    - "-ferror-limit=0"
  Compiler: g++-13

8.3 其他配置

8.3.1 适配clang与libc++

警告：

如果不是非使用libc++库不可，就不需要下面的内容，直接CMakePresets.json里面指定编译器就好了，反正clang++和libstdc++也能一块用

vcpkg安装和主动拉取依赖默认用gcc工具链（如果有的话），编译链接也一样

如果要配clang和libc++，需要修改以下几个配置：

CC，CXX：

改一下两个环境变量所指的编译器（在~/.bashrc）：
```
export CC=clang-20
export CXX=clang++-20
```

CMakePresets.json，原先写在CMake中的内容，现在要放在该文件里：

{
    "version": 2,
    "configurePresets": [
        {
            "name": "vcpkg",
            "generator": "Ninja",
            "binaryDir": "${sourceDir}/build",
            "cacheVariables": {
                "VCPKG_TARGET_TRIPLET": "x64-linux-clang-libcxx",
                "CMAKE_BUILD_TYPE": "Debug",
                "CMAKE_C_COMPILER": "clang-20",
                "CMAKE_CXX_COMPILER": "clang++-20",
                "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
            },
            "environment": {
                "CC": "clang-20",
                "CXX": "clang++-20"
            }
        }
    ]
}

xxx/vcpkg/triplets/community中新建x64-linux-clang-libcxx.cmake

set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE static)
set(VCPKG_CMAKE_SYSTEM_NAME Linux)

# 注意：VCPKG_CXX_FLAGS 是会被传入编译器的变量
set(VCPKG_C_FLAGS "${VCPKG_C_FLAGS}")
set(VCPKG_CXX_FLAGS "${VCPKG_CXX_FLAGS} -stdlib=libc++")
set(VCPKG_LINKER_FLAGS "${VCPKG_LINKER_FLAGS} -stdlib=libc++")
set(VCPKG_EXE_LINKER_FLAGS "${VCPKG_EXE_LINKER_FLAGS} -stdlib=libc++ -lc++abi")

直接用vcpkg install命令默认使用/vcpkg/triplets/x64-linux.cmake文件

使用vcpkg install fmt:x64-linux-clang-libcxx安装对应的包，同样的CMakeLists.txt指定链接标志，见9.1的解决方案

8.3.2 先找全局再拉依赖

案例中vcpkg的使用方式属于manifest，属于自动下载依赖到项目中，不会去vcpkg的已经安装的包里找，工作模式类似一般CMake项目中的third_party文件夹，优点是版本能控制，缺点就是每次修改CMakeLists.txt重新载入的时间就比较长

查了一下好像没办法在这种模式下直接的先找全局包，没找到再拉依赖

问了下gemini给出的答案是：

配置二进制缓存。

虽然这依然会在项目下生成 vcpkg_installed 目录，但它不会重新编译代码，而是直接从缓存（或全局缓存）中拷贝编译好的二进制文件。这是 vcpkg 官方推荐的复用机制。

设置环境变量： 在你的系统环境变量中添加（或确保默认已启用）：

Bash

VCPKG_DEFAULT_BINARY_CACHE=<你的缓存路径>
# Windows 默认通常在 %LOCALAPPDATA%\vcpkg\archives
# Linux/Mac 默认通常在 $HOME/.cache/vcpkg/archives

效果： 当你在全局 vcpkg install xxx 时，编译产物会存入 Cache。当你在项目中 build 时，vcpkg 发现 vcpkg.json 需要同样的库（且版本、编译器参数一致），它会直接从 Cache 极速解压到 vcpkg_installed，跳过编译过程。

8.4 常用指令

list
install
remove
search
update

九. 常见问题

9.1 llvm标准库头文件内报错

问题描述

此问题针对强迫症患者，如果你点进去头文件碰到了下面的情况：

那么在项目下配置.clangd已经没用了

解决方案

在~/目录下新增.config/clangd/config.yaml文件，把.clangd的内容复制过来

这个全局文件的优先级比项目下.clangd要高，所以配置之后项目路径下里面相同的配置会被全局的覆盖掉，所以可以在全局配置配clangd去解析哪个编译器的头文件，然后项目的.clangd配置第三方库的头文件。至于为什么内容头文件会爆这么多错，搜了一堆也没找到答案，所以该方法就凑活用吧

9.2 codelldb调试无法正常显示STL内容

问题描述

比如源码为：

struct node {
    unordered_map<int, int> map;
};
int main() {
    node node;
    node.map.insert({1, 1});
    return 0;
}

在return 0处打断点，显示的是：

可以看到内嵌到struct或者class内的STL组件可能无法正常显示

解决方案

https://github.com/vadimcn/codelldb/issues/707

原因还是llvm工具链的问题，clang++，lldb，libc++对应的是g++，gdb，libstdc++，虽然llvm支持使用libstdc++做链接，但是多少有些小问题，比如性能上，再比如这个lldb不能正确显示unordered_map，最新的llvm-21中的lldb已经把这个问题修复了：

[lldb] Fix StdUnorderedMapSynthProvider for GCC #164251

有两种解决办法：

修改CMakeLists.txt，使用llvm组件（这些组件在llvm配置时应该就配置完成了）：
```
# 设置编译器
set(CMAKE_CXX_COMPILER clang++-20)
# 添加编译标志 库名 libc++.so
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -stdlib=libc++")
# 设置链接标志 库名 libc++abi.so
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -stdlib=libc++ -lc++abi")
```
重新编译，再调试：

这么做会强制程序链接libc++库，但是linux上一般会默认链接libstdc++，因此每个cmake项目都要搞一遍，尤其是再去配vcpkg环境或者是xmake的项目（默认都是链接libstdc++的），都得额外搞一套配置，不然到时候libstdc++和libc++链接冲突了很难搞，考虑到库切换起来很麻烦，切换编译器很简单（而且兼容），推荐还是用第二种方法

修改本地的lldb formatter，然后改codelldb的后端

用下面的命令找gnu_libstdcpp.py这个文件：

find /usr -name "gnu_libstdcpp.py" 2>/dev/null

复制一份备用，然后拉取llvm项目上最新的文件：

# 复制一份备用
sudo cp /usr/lib/llvm-20/lib/python3.10/site-packages/lldb/formatters/cpp/gnu_libstdcpp.py \
        /usr/lib/llvm-20/lib/python3.10/site-packages/lldb/formatters/cpp/gnu_libstdcpp.py.bak
# 下载github最新文件
sudo wget https://raw.githubusercontent.com/llvm/llvm-project/main/lldb/examples/synthetic/gnu_libstdcpp.py \
          -O /usr/lib/llvm-20/lib/python3.10/site-packages/lldb/formatters/cpp/gnu_libstdcpp.py

vscode修改codelldb，使用本地的lldb：

Ctrl + Shift + P
>LLDB: Use Alternate Backend
输入lldb-<version>（下哪个版本就用哪个版本）

codelldb自己会解析后端，完事，之后codelldb会调用本地修改后的lldb来调试，一劳永逸

ps：在linux上使用llvm工具链还是不太方便，修改了好多配置，不想折腾还是默认使用g++和gdb比较好

9.3 clangd设置代码补全

问题描述

clangd默认配置在代码补全的时候会把模板或函数的所有参数都补全出来，例如，当你输入了

std::set

并试图使用clangd提供的代码补全时，它会补全为：

std::set<class, class, class>

可以使用Tab一个一个填充或删除参数，但这样比较麻烦

解决方案

在.vscode文件夹下新增settings.json，内容为：

{
    "clangd.arguments": [
        "--function-arg-placeholders=false",
        "--completion-style=bundled"
    ]
}

这样会影响在当前项目目录下clangd的补全功能，当输入std::set时，会补全为std::set<>

也可以直接在clangd插件的设置中找到arguments项，设置上面两个参数，这样会影响所有目录下的补全行为

参考

c++20制作简易协程库3

Fri, 14 Nov 2025 22:00:00 GMT

io_info

lab2中提到过sqe数据结构中可以传入一个数据指针，该指针会cqe中原封不动的返回，如果我们想要设置提交的IO类型，与IO绑定的协程句柄等等，使用该数据指针绑定一个结构体就会很方便：

// 执行的IO类型
enum io_type
{
    nop,
    tcp_accept,
    tcp_connect,
    tcp_read,
    tcp_write,
    tcp_close,
    stdin,
    timer,
    none
};

struct io_info
{
    coroutine_handle<> handle; // IO 绑定的协程句柄
    int32_t            result; // IO 执行完的结果
    io_type            type; // IO 类型
    uintptr_t          data; // IO 绑定的内存区域
    cb_type            cb; // IO 绑定的回调函数
};

io_awaiter

要想在协程中发起一个异步IO操作，需要使用co_await关键字，其后跟一个awaiter或awaitable对象

这里设置对应的io_await，实现内部的ready，suspend，resume逻辑，完成基础IO框架：

class base_io_awaiter
{
public:
    base_io_awaiter() noexcept : m_urs(coro::detail::local_engine().get_free_urs())
    {
        assert(m_urs != nullptr && "io submit rate is too high");
    }

    constexpr auto await_ready() noexcept -> bool { return false; }

    auto await_suspend(std::coroutine_handle<> handle) noexcept -> void { m_info.handle = handle; }

    auto await_resume() noexcept -> int32_t { return m_info.result; }

protected:
    io_info             m_info;
    coro::uring::ursptr m_urs;
};

base_io_awaiter为所有 IO 相关的awaiter提供了一个基类并实现了 awaiter 的全部调度逻辑。当base_io_awaiter被构造时会自动从当前线程绑定的 engine 获取一个sqe，当其被co_await时base_io_awaiter会在await_suspend中记录调用协程的句柄并使该协程陷入 suspend 状态。而在 IO 完成后会通过await_resume返回 IO 的执行结果。

tcp_accept_awaiter

考虑服务器要做一个异步连接的动作：

class tcp_accept_awaiter : public detail::base_io_awaiter
{
public:
    tcp_accept_awaiter(int listenfd, int io_flag = 0, int sqe_flag = 0) noexcept {
        m_info.type = io_type::tcp_accept;
        m_info.cb   = &tcp_accept_awaiter::callback;

        io_uring_sqe_set_flags(m_urs, sqe_flag);
        io_uring_prep_accept(m_urs, listenfd, nullptr, &len, io_flag);
        io_uring_sqe_set_data(m_urs, &m_info); // old uring version need set data after prep
        local_engine().add_io_submit();
    }

    static auto callback(io_info* data, int res) noexcept -> void {
        data->result = res;
    	submit_to_context(data->handle);
    }

private:
    inline static socklen_t len = sizeof(sockaddr_in);
};

将m_info的IO类型绑定为accpet类型，标识这是一个连接动作
绑定IO完成后的回调函数，该回调函数在IO执行完成后，应由engine执行：
```
auto engine::handle_cqe_entry(urcptr cqe) noexcept -> void
{
 auto data = reinterpret_cast<io::detail::io_info*>(io_uring_cqe_get_data(cqe));
 data->cb(data, cqe->res);
 m_running_io--;
}
```
回调做两件事：
- 将IO执行的结果（成功，失败或其他信息）存回io_info结构体，这样在协程恢复的时候，执行await_resume()就可以获取IO执行的结果
- 将协程再次提交回原context
使用获取的sqe，填充数据，并告知当前线程所绑定的engine，当前有IO任务需要提交执行

剩余的awaiter都大同小异，都使用对应的io_uring_pre_*系列函数填充相应数据

如果需要扩展IO类型，只需要在此基础之上，继承base_io_awaiter，在io_uring上寻找对应的函数，填充数据即可

c++20制作简易协程库5

Fri, 14 Nov 2025 22:00:00 GMT

协程高级同步组件

高级同步组件，这里指的是需要配合的各种同步组件，比如：

条件变量condition_variable的实现要和互斥锁mutex配合

通道channel的实现要使用互斥锁mutex和条件变量condition_variable共同实现

condition_variable

协程意义下的条件变量，与std::condition_variable类似，主要api为wait和notify()，当在协程中调用wait()函数时，应该让当前协程陷入suspend状态，而线程可以继续运行

auto wait(mutex& mtx) noexcept -> awaiter; // 协程调用，awaiter 的 await_resume 返回 void
auto wait(mutex& mtx, cond_type&& cond) noexcept -> awaiter; // 协程调用，awaiter 的 await_resume 返回 void
auto wait(mutex& mtx, cond_type& cond) noexcept -> awaiter; // 协程调用，awaiter 的 await_resume 返回 void
auto notify_one() noexcept -> void; // 普通调用
auto notify_all() noexcept -> void; // 普通调用

wait：阻塞当前协程，直到另一个协程调用同一个condition_variable实例的notify系方法，或者直到指定的谓词函数 (即条件) 返回 true。如果没有收到通知，即使条件为 true 也不会继续执行。如果收到通知了，但是条件不成立将仍然被阻塞，不会执行
notify_one：唤醒一个等待该条件变量的协程
notify_all：唤醒所有等待该条件变量的线程

条件变量通常需要和互斥量mutex共同使用：

co_await cv.wait(mutex)：将获得的锁释放，将协程加入条件变量的等待队列，等待被唤醒，然后获取锁，继续执行

co_await cv.wait(mutex, pred)：语义即：

while (!pred()) {
    co_await wait(mutex);
}

notify_xxx：唤醒条件变量的等待队列中一个协程

从上面的介绍可以看出，在使用wait系列的函数之前，必须先获得mutex锁：

condition_variable cv;
mutex mtx;
int global_id;
task<> func(int id) {
  auto guard = co_await mtx.lock_guard();
  co_await cv.wait(mtx, [&](){id==global_id;});
  global_id+=1;
  cv.notify_all();
}

实现里特别需要注意的点在于：condition_variable本身会维护一个等待队列，但如果其被唤醒了，需要等锁，那么该协程应该转移到mutex的等待队列中，不再由condition_variable的等待队列负责

同时，notify系列的函数，可以在不获取互斥锁的情况下被调用，也就是说，notify是可以被并行执行的，那就需要保证状态的线程安全性，因此，设计状态时，无法像mutex一样，只使用一个原子变量就能保证协程的等待与恢复是以FIFO实现的，综合性能和实用性来考虑，这里使用自旋锁spinlock和队列头尾指针来作为状态（使用锁的逻辑比直接使用原子变量的逻辑更加清晰）

状态设计：

detail::spinlock m_spin;	// 自旋锁
cv_awaiter* m_awaiter_head{nullptr}; // 队列头指针
cv_awaiter* m_awaiter_tail{nullptr}; // 队列尾指针

状态变化：

安全的含义是使用自旋锁来保证头尾指针读写的线程安全
- wait：其状态变化很简单，就是安全的将awaiter指针加入条件变量的等待队列，然后释放协程锁
- 带条件的wait：先检查条件是否为true，如果为true了，那么不应该等待，直接恢复这个协程，否则像wait一样，安全的将awaiter指针加入条件变量的等待队列，然后释放协程锁
- notify_one：从条件变量的等待队列中取出第一个awaiter指针，尝试让它获取锁（即让它尝试加入协程锁的等待队列中），如果成功加入了协程锁的等待队列，那么该awaiter携带的协程将由协程锁mutex的unlock负责恢复，否则（没有加入协程锁的等待队列，代表获取了锁），直接恢复
- notify_all：首先安全的替换条件变量的队列头指针，然后一次性对所有awaiter指针做尝试获取锁的操作即可

关于尝试让condition_variable的awaiter获取锁的操作，可以选择将其设置为mutex的的友元类，然后通过复现mutex的awaiter对mutex的状态来将其加入mutex的等待队列

另一种方式是，令condition_variable的awaiter继承自mutex的awaiter，自动复用其中的代码

cv_awaiter的实现

struct cv_awaiter : public mutex::mutex_awaiter {
    condition_variable& cv;
    cond_type pred;
    using mutex_awaiter::mutex_awaiter;
    cv_awaiter(mutex& mutex, condition_variable& condition_variable): 
    mutex::mutex_awaiter(mutex), cv(condition_variable), pred(nullptr) {}

    cv_awaiter(mutex& mutex, condition_variable& condition_variable, cond_type& cond): 
    mutex::mutex_awaiter(mutex), cv(condition_variable), pred(cond) {}

    cv_awaiter(mutex& mutex, condition_variable& condition_variable, cond_type&& cond): 
    mutex::mutex_awaiter(mutex), cv(condition_variable), pred(std::move(cond)) {}

    ~cv_awaiter() override {}

    auto await_ready() noexcept -> bool {
        ctx.register_wait();
        return false;
    }

    auto await_suspend(std::coroutine_handle<> awaiting_handle) noexcept -> bool {
        handle = awaiting_handle;
        return add_waiting_list();
    }
    auto await_resume() noexcept -> void {
        ctx.unregister_wait();
    }
	// cv_awaiter自己的add_waiting_list
    auto add_waiting_list() noexcept -> bool {
        if (!pred || pred() == false) {
            // 挂起
            next = nullptr;
            {
                std::lock_guard<detail::spinlock> lock(cv.m_spin);
                if (cv.m_awaiter_head == nullptr) {
                    cv.m_awaiter_head = cv.m_awaiter_tail = this;
                } else {
                    cv.m_awaiter_tail->next = this;
                    cv.m_awaiter_tail = this;
                }
            }
            // 解锁
            mtx.unlock();
            return true;
        }
        // 不挂起, 继续执行
        return false;
    }
    // 尝试让condition_variable的awaiter获取锁
    auto try_wake() noexcept -> void {
        // 复用mutex_awaiter的add_waiting_list
        if (!mutex_awaiter::add_waiting_list()) {
            resume_coro();
        }
        // 获取失败, this会被挂载到mtx所在的链表上, 由mtx.unlock调用重载后的resume_coro
    }
    auto resume_coro() noexcept -> void override {
        // resume_coro对应的handle获得了协程锁mtx
        if (!pred || pred() == false) {
            // 虚假唤醒, 加回链表并释放锁
            next = nullptr;
            {
                std::lock_guard<detail::spinlock> lock(cv.m_spin);
                if (cv.m_awaiter_head == nullptr) {
                    cv.m_awaiter_head = cv.m_awaiter_tail = this;
                } else {
                    cv.m_awaiter_tail->next = this;
                    cv.m_awaiter_tail = this;
                }
            }
            mtx.unlock();
        } else {
            // 获取协程的mtx继续运行
            ctx.submit_task(handle);
        }
    }
};

wait和notify系列函数

auto wait(mutex& mtx) noexcept -> cv_awaiter { 
        return cv_awaiter(mtx, *this);
    }
    // 如何避免虚假唤醒?
    auto wait(mutex& mtx, cond_type&& cond) noexcept -> cv_awaiter {
        return cv_awaiter(mtx, *this, std::move(cond)); 
    }

    auto wait(mutex& mtx, cond_type& cond) noexcept -> cv_awaiter {
        return cv_awaiter(mtx, *this, cond); 
    }

    auto notify_one() noexcept -> void {
        cv_awaiter* awaiter = nullptr;
        {
            std::lock_guard<detail::spinlock> lock(m_spin);
            if (m_awaiter_head == nullptr) {
                return;
            }
            awaiter = m_awaiter_head;
            m_awaiter_head = static_cast<cv_awaiter*>(m_awaiter_head->next);
        }
        awaiter->try_wake();
    };

    auto notify_all() noexcept -> void {
        cv_awaiter* awaiter = nullptr;
        {
            std::lock_guard<detail::spinlock> lock(m_spin);
            if (m_awaiter_head == nullptr) {
                return;
            }
            awaiter = m_awaiter_head;
            m_awaiter_head = nullptr;
        }
        while (awaiter) {
            cv_awaiter* temp = static_cast<cv_awaiter*>(awaiter->next);
            awaiter->try_wake();
            awaiter = temp;
        }
    };

channel

channel是一个使用协程锁mutex和协程条件变量的多生产者多消费者的阻塞队列

c++20制作简易协程库1

Fri, 14 Nov 2025 22:00:00 GMT

task类

c++20中的协程要求用户自定义一个task类作为返回值

同时为task类必须绑定promise_type类型

对于promise_type类型，可以理解为一个官方要求实现的接口，包含以下函数：

// 创建任务对象
auto get_return_object() noexcept -> task;
// 协程创建时的调度
auto initial_suspend() noexcept -> std::suspend_always;
// 协程返回时的调度
auto final_suspend() noexcept -> std::suspend_never;
// 协程函数无返回值需使用
auto return_void() noexcept -> void;
// 协程函数有返回值需使用
// auto return_value(T val) noexcept -> void;
// 协程执行过程中出现异常
auto unhandled_exception() noexcept -> void;

promise_base

接口函数针对协程的返回值有两种不同的函数：return_xxx

并且这两种函数不能同时存在，所以对于协程有返回值和无返回值（void），至少需要构建两种不同的promise_type，于是可以将共性部分抽取到promise_base类中：

协程创建时的调度：initial_suspend()
协程返回时的调度：final_suspend()

c++协程是非对称协程，这意味着协程函数之间存在调用关系，当协程因为调度而暂停时，执行权应返回给调用该协程的一方，这么说比较抽象，以入门案例中的最后一个程序为例：

main中执行了add(1, 2, 1)，

add(1, 2, 1)中又执行了add(2, 30, 2)

期望的返回顺序应该像普通函数调用那样：

add(2, 30, 2)执行完毕，返回add(1, 2, 1)

add(1, 2, 1)执行完毕，返回main

但实际上当时的程序没有按照预想的情况进行执行

协程创建和返回时的调度应该满足以上期望的返回顺序，这就需要改造promise_base中的调度函数：

initial_suspend

对于一个协程函数来说，不希望其在创建时能够直接执行，而是在initial_suspend后暂停执行，这样协程函数会返回对应的task对象

因此返回suspend_always{}即可

final_suspend

该调度点在执行co_return后，期望的情况是当某个协程函数返回时，执行权应该交给调度它的协程函数，就像普通函数调用那样，这要求保存协程的调用链，具体做法就是在promise类中设置一个std::coroutine_handle<> caller变量，当执行final_suspend调度时，将执行权交给caller即可，这要求自定义final_suspend()的返回值final_awaiter

code：

介绍一下代码中的std::coroutine_handle<> await_suspend(std::coroutine_handle<promise_type> handle) noexcept：

在co_return时，会进入定义的final_awaiter的ready-suspend-resume三项流程

await_suspend的入参是当前执行co_return的协程句柄，返回值是当前协程句柄的调用者的句柄

如果没有调用者，会返回一个std::noop_coroutine()，该协程句柄指向一个无操作协程，之后就会按照栈帧，回到最初恢复协程的函数帧中执行

struct promise_base
{
    struct final_awaiter {
        bool await_ready() noexcept {return false;}
        template<typename promise_type>
        auto await_suspend(std::coroutine_handle<promise_type> handle) noexcept -> std::coroutine_handle<> {
            auto& promise = handle.promise();
            return promise.caller_ != nullptr ? promise.caller_ : std::noop_coroutine();
        }
        void await_resume() noexcept {}
    };
    friend final_awaiter;

    promise_base() noexcept {}
    ~promise_base() {}

    auto initial_suspend() noexcept {
        return std::suspend_always{}; 
    }

    [[CORO_TEST_USED(lab1)]] auto final_suspend() noexcept -> final_awaiter
    {
        return final_awaiter{};
    }
    void set_caller(std::coroutine_handle<> caller) {
        caller_ = caller;
    }
    
    void set_detached() {
        state_ = task_state::DETACHED;
    }

    bool is_detached() {
        return state_ == task_state::DETACHED;
    }
protected:
    std::coroutine_handle<> caller_{nullptr};
};

特化promise<>

为了处理协程函数中各种返回类型，需要使用模板类型来保存返回结果，但是函数可能返回void

当协程函数返回void时，不应该使用promise，因为里面已经定义了return_value函数，因此需要特化一个模板，专门处理没有返回值的情况

这个类相对简单，只需要定义一个void return_void()函数，并附带上记录异常的功能即可

code：

template<>
struct promise<void> : public promise_base
{
    using task_type        = task<void>;
    using coroutine_handle = std::coroutine_handle<promise<void>>;

    promise() noexcept                  = default;
    promise(const promise&)             = delete;
    promise(promise&& other)            = delete;
    promise& operator=(const promise&)  = delete;
    promise& operator=(promise&& other) = delete;
    ~promise()                          = default;

    auto get_return_object() noexcept -> task_type;

    constexpr auto return_void() noexcept -> void
    {
    }

    auto unhandled_exception() noexcept -> void
    {
        m_exception_ptr = std::current_exception();
    }
	// result函数负责获取协程返回值, 由于task<void>类型没有返回值，这里只需要抛出协程执行过程中的异常
    auto result() -> void
    {
        if (m_exception_ptr)
        {
            std::rethrow_exception(m_exception_ptr);
        }
    }

private:
    std::exception_ptr m_exception_ptr{nullptr};
};

promise

container容器

为了保存协程函数的返回值，需要定义一个容器，容器有三种状态：

unset_return_value：一个内部定义的空结构体，仅用于表示“未设置值”的初始状态。
store_type：存储协程的返回值
std::exception_ptr：存储从协程

这里直接将三种状态放在一个union中，使用std::variant来保存（更安全的union结构，这意味着任何时刻变量中只能是三者之一）

struct unset_return_value
{
    unset_return_value() {}
    unset_return_value(unset_return_value&&)      = delete;
    unset_return_value(const unset_return_value&) = delete;
    auto operator=(unset_return_value&&)          = delete;
    auto operator=(const unset_return_value&)     = delete;
};
static constexpr bool return_type_is_reference = std::is_reference_v<T>;
using stored_type =
    std::conditional_t<return_type_is_reference, std::remove_reference_t<T>*, std::remove_const_t<T>>;
using variant_type = std::variant<unset_return_value, stored_type, std::exception_ptr>;
// 保存用户通过co_return返回的数据
variant_type m_storage{};

std::is_reference_v：这是一个编译期常量，用于判断模板参数T是否是一个引用类型
std::conditional_t：这是一个编译期的 if-else。它根据第一个布尔参数，从后面两个类型中选择一个作为最终类型

store_type表示如果T是一个引用，就将存储对应的指针类型（variant不能直接存储引用），否则存储原始类型（去除const）

return_value

当协程函数co_return val;时触发，此时应将返回值保存到容器中

template<typename value_type>
        requires(return_type_is_reference and std::is_constructible_v<T, value_type &&>) or
                (not return_type_is_reference and std::is_constructible_v<stored_type, value_type &&>)
auto return_value(value_type&& value) -> void
{
    if constexpr (return_type_is_reference)
    {
        T ref = static_cast<value_type&&>(value);
        m_storage.template emplace<stored_type>(std::addressof(ref));
    }
    else
    {
        m_storage.template emplace<stored_type>(std::forward<value_type>(value));
    }
}

为什么不使用类模板T而是新增一个函数模板value_type？

这里实际上使用了一个万能引用（value_type&&）来避免不必要的拷贝，并通过requires子句确保co_return的表达式可以被用来构造上面定义好的store_type类型

根据模板T是否是引用类型（比如定义的task<int&>，T就是int&），就获取传入的值的地址，再由m_storage中的指针来接收，否则利用完美转发，将值传给m_storage

result

获取协程返回值，return_value将返回值存在容器中，但要获取它还需要主动调用promise对象的result方法，此时：

m_storage是unset_return_value，报运行时错误
m_storage是std::exception_ptr，重新抛出对应的异常
m_storage是stored_type，返回对应的值

auto result() & -> decltype(auto)
{
    if (std::holds_alternative<stored_type>(m_storage))
    {
        if constexpr (return_type_is_reference)
        {
            return static_cast<T>(*std::get<stored_type>(m_storage));
        }
        else
        {
            return static_cast<const T&>(std::get<stored_type>(m_storage));
        }
    }
    else if (std::holds_alternative<std::exception_ptr>(m_storage))
    {
        std::rethrow_exception(std::get<std::exception_ptr>(m_storage));
    }
    else
    {
        throw std::runtime_error{"The return value was never set, did you execute the coroutine?"};
    }
}

task

与promise对应，为了表达返回值，需要定义为模板类，这样在定义协程函数时：

task<void> func1() {
    ...
}
task<int> func2() {
    ...
}

task类持有一个协程句柄，指向当前与task关联的协程帧

为了让promise能够构造task对象，其需要定义一个从协程句柄转化而来的有参构造函数
在task析构函数中，如果持有的协程句柄仍然有效，应该将其销毁
不应有拷贝构造和拷贝赋值
支持移动构造和移动赋值
封装协程句柄的resume和destroy函数，对外提供操作协程的函数

提供获取promise对象和协程句柄的函数

template<typename return_type>
class task
{
public:
    using task_type        = task<return_type>;
    using promise_type     = detail::promise<return_type>;
    using coroutine_handle = std::coroutine_handle<promise_type>;

    task() noexcept : m_coroutine(nullptr) {}

    explicit task(coroutine_handle handle) : m_coroutine(handle) {}
    task(const task&) = delete;
    task(task&& other) noexcept : m_coroutine(std::exchange(other.m_coroutine, nullptr)) {}

    ~task()
    {
        if (m_coroutine != nullptr)
        {
            m_coroutine.destroy();
        }
    }

    auto operator=(const task&) -> task& = delete;

    auto operator=(task&& other) noexcept -> task&
    {
        if (std::addressof(other) != this)
        {
            if (m_coroutine != nullptr)
            {
                m_coroutine.destroy();
            }

            m_coroutine = std::exchange(other.m_coroutine, nullptr);
        }

        return *this;
    }

    /**
     * @return True if the task is in its final suspend or if the task has been destroyed.
     */
    auto is_ready() const noexcept -> bool { return m_coroutine == nullptr || m_coroutine.done(); }

    auto resume() -> bool
    {
        if (!m_coroutine.done())
        {
            m_coroutine.resume();
        }
        return !m_coroutine.done();
    }

    auto destroy() -> bool
    {
        if (m_coroutine != nullptr)
        {
            m_coroutine.destroy();
            m_coroutine = nullptr;
            return true;
        }

        return false;
    }

    auto promise() & -> promise_type& { return m_coroutine.promise(); }
    auto promise() const& -> const promise_type& { return m_coroutine.promise(); }
    auto promise() && -> promise_type&& { return std::move(m_coroutine.promise()); }

    auto handle() & -> coroutine_handle { return m_coroutine; }
    auto handle() && -> coroutine_handle { return std::exchange(m_coroutine, nullptr); }
private:
    coroutine_handle m_coroutine{nullptr};
};

最重要的是重载co_await运算符，以支持co_await语义实现协程嵌套执行和正确的调用返回

对于co_await func();的语义，其执行流程是：

auto task_func = func();

触发promise.initial_suspend()
co_await task_func;

触发task_func对象中的co_await运算符重载

所以该重载应该返回一个awaiter来实行调度，期望的调度是：将执行权由调用协程交给被调用的协程，在suspend中就需要返回被调用协程的句柄

同时为了在被调用协程返回后正确的回到调用协程的位置，需要设置promise_base的caller成员变量保存调用协程的句柄，这样在被调用协程执行final_suspend时正确的转移执行权

struct awaitable_base
{
    awaitable_base(coroutine_handle coroutine) noexcept : m_coroutine(coroutine) {}

    auto await_ready() const noexcept -> bool { return !m_coroutine || m_coroutine.done(); }

    auto await_suspend(std::coroutine_handle<> awaiting_coroutine) noexcept -> std::coroutine_handle<>
    {
        // TODO[lab1]: Add you codes
        auto& m_promise = m_coroutine.promise();
        m_promise.set_caller(awaiting_coroutine);
        return m_coroutine;
    }

    std::coroutine_handle<promise_type> m_coroutine{nullptr};
};

auto operator co_await() const& noexcept
{
    struct awaitable : public awaitable_base
    {
		// 子协程co_return -> 子协程调用result_value/result_void -> 子协程调用final_suspend()
        // -> 执行权转移给父协程 -> 父协程调用await_resume获取返回值
        auto await_resume() -> decltype(auto) { return this->m_coroutine.promise().result(); }
    };

    return awaitable{m_coroutine};
}

auto operator co_await() const&& noexcept
{
    struct awaitable : public awaitable_base
    {
        auto await_resume() -> decltype(auto) { return std::move(this->m_coroutine.promise()).result(); }
    };

    return awaitable{m_coroutine};
}

通过promise构造task

即实现promise的get_return_object()函数，只需要调用task的有参构造函数，返回task对象即可：

template<typename return_type>
inline auto promise<return_type>::get_return_object() noexcept -> task<return_type>
{
    return task<return_type>{coroutine_handle::from_promise(*this)};
}

inline auto promise<void>::get_return_object() noexcept -> task<>
{
    return task<>{coroutine_handle::from_promise(*this)};
}

c++20制作简易协程库4

Fri, 14 Nov 2025 22:00:00 GMT

协程同步组件

使用scheduler多线程执行协程任务时，仍会面临与多线程任务相同的问题：共同读写某个变量，常用的手段是使用线程同步组件如mutex，condition_variable来确保多线程下对共享变量操作的正确性

但线程同步组件会阻塞整个线程，如果协程任务使用了线程同步组件，会使整个线程陷入阻塞态，从而线程上其他的协程任务无法继续执行，那么使用协程带来的优势就将不存在

我们期望设计协程相关的同步组件，当一个协程使用对应的同步组件被阻塞时，只将自身陷入到suspend状态中，而不会将整个线程阻塞，使得同一个线程上其他能够运行的协程任务仍然能够继续运行，当同步操作完成时，再由同步组件唤醒，重新将协程提交到对应的context任务队列中，恢复原先的运行

event

event的功能与std::promise类似，带有一个返回类型模板参数且默认为空，并且提供set以及wait两个接口，set可以直接调用，但调用wait需要是协程的形式co_await wait()

event被设定为模板类，方便set函数传值

对于模板参数为空的event，功能即传递信号：

auto set() noexcept -> void; // 普通调用
auto wait() noexcept -> awaiter; // 协程调用，awaiter 的 await_resume 返回 void

不为空，传信号的同时传递对应的值：

template<typename value_type>
auto set(value_type&& value) noexcept -> void; // 普通调用
auto wait() noexcept -> awaiter; // 协程调用，awaiter 的 await_resume 返回 set 设置的值

使用方式：

event<int> ev;
task<> set_func() {
  // codes...
  ev.set(number);
}
task<> wait_func() {
  auto number = co_await ev.wait();
  // codes ...
}

锁

由于不同协程可能会运行在不同的线程上，因此event的设计要实现线程安全，使用mutex锁可以轻松的做到这一点：

成员变量：

std::mutex m_mux;
std::condition_variable m_cv;
size_t m_waited{0};		// 等待陷入suspend状态的协程
bool status{false};		// 当前event有没有被set
std::queue<base_awaiter*> awaiters;	// 保存陷入suspend状态的协程队列

struct base_awaiter：

当一个协程执行co_await ev.wait();时，执行调度流程：

如果event已经处于set的状态，协程就不应该陷入suspend状态，
否则，协程将自己陷入suspend状态，并将当前的awaiter对象放入待恢复的队列中（awaiters）

struct base_awaiter {
    friend class event_base;
    // 构造: 绑定对应的event对象和context对象, 以便后面恢复协程
    base_awaiter(event_base& event) noexcept : m_event(event), m_ctx(local_context()) {}
    auto await_ready() noexcept -> bool {
        m_ctx.unregister_wait();
        // 对event对象的互斥量上锁
        std::lock_guard<std::mutex> lock(m_event.m_mux);
        // 如果event已经被set了, 执行co_await的协程不应该陷入suspend, 而是继续运行
        if (m_event.status) {
            return true;
        }
        // 否则将awaiter添加要恢复队列中
        m_event.awaiters.push(this);
        // m_waited代表当前还有多少个加入恢复队列的协程没有进入suspend状态
        m_event.m_waited += 1;
        return false;
    }
    auto await_suspend(std::coroutine_handle<> handle) noexcept -> bool {
        // 保存要恢复的协程句柄
        m_handle = handle;
        std::unique_lock<std::mutex> lock(m_event.m_mux);
        m_event.m_waited -= 1;
        // 如果m_waited为0, 说明所有加入队列的awaiter都绑定好了要恢复的协程句柄
        // 这样event对象在set的时候就不会恢复一个没有绑定协程句柄的awaiter
        if (m_event.m_waited == 0) {
            m_event.m_cv.notify_all();
        }
        return true;
    }
    auto await_resume() noexcept -> void{
        m_ctx.unregister_wait();
    }
protected:
    event_base& m_event;	// 当前awaiter绑定的event对象
    context& m_ctx;			// 协程所在的context对象
    std::coroutine_handle<> m_handle{nullptr};	// 保存陷入suspend状态的协程句柄
};

class event_base：

class event_base {
public:
    friend struct base_awaiter;
public:
    event_base() noexcept {};
    ~event_base() noexcept {}

protected:
    // set时, 恢复所有的协程
    void resume_awaiters() noexcept {
        std::queue<base_awaiter*> to_resume;
        {
            std::unique_lock<std::mutex> lock(m_mux);
            m_cv.wait(lock, [this]() {
                return m_waited == 0;
            });
            // 记录当前event已经被set了
            status = true;
            awaiters.swap(to_resume);
        }
        // 将所有的协程句柄提交回绑定的context
        while (!to_resume.empty()) {
            auto resume_a = to_resume.front();
            to_resume.pop();
            resume_a->m_ctx.submit_task(resume_a->m_handle);
        }
    }
protected:
    std::mutex m_mux;
    std::condition_variable m_cv;
    size_t m_waited{0};
    bool status{false};
    std::queue<base_awaiter*> awaiters;
};

无锁

锁的功能很强大，但涉及到底层系统调用，开销大，同时会锁住整个线程，不利于高并发

因此考虑使用非阻塞式的原子操作、**CAS（Compare-and-Swap）**来实现对共享数据的访问和修改，其可以降低系统调用的次数，但是设计上更加复杂，需要考虑线程安全，内存模型等因素

初次接触无锁编程，仅考虑线程安全，不去考虑内存模型（统一使用最严格的内存序）

无锁编程通常使用原子变量来保存共享数据，对于event来说，需要保存的最关键的数据就是awaiter队列（这里可以用链表实现）

那么对于该原子变量来说可能有三个状态：

没有被set过，并且当前链表长度为0（kUNSETNOAWAITER）
没有被set过，并且当前链表长度为n（保存指向链表头的指针）
已经被set（kSET）

因为要保存指针类型，使用atomic<void> m_state来保存状态，其初始状态应为kUNSETNOAWAITER

状态变化：

event::set()：

该函数会将m_state强制转为kSET状态，并将m_state原先存的状态取出，如果状态是指向链表头的指针，就恢复协程的运行
event::wait()：

该函数的功能是负责等待对应的event被set，关键步骤在await_suspend()中：

将自身挂载到链表上，并让协程陷入阻塞态，但直接修改状态时会出现一些竞争状态，即在该函数执行时，可能有以下情况发生：
- 状态被修改为了kSET
- 其他协程也在执行awaiter::await_suspend()，此时两者都想改变状态，将自身添加到链表头部
对于竞争状态，需要手动进行循环CAS，即“如果值没被别人改过，那就更新成功；如果别人先一步改了，我就失败并重试。”

循环CAS的核心是失败后的重试，这要求成功之前都必须处在一个循环过程中：
```
while (true) {
    // 当前已经被set了, 就退出
    if (m_state == kSET) {
        break;
    }
    // 原子变量的CAS操作, 尝试挂载自身到链表中
	if (try_add_to_list(this, m_state)) {
        // 成功了, 退出循环
        break;
    }
    // 失败了, 循环重试
}
```
当多个线程上的协程并发执行时，使用上面的操作可以保证线程安全，但缺点也很明显：
- 需要分析状态，状态越复杂，代码就越复杂
- 竞争时cpu都处于空转状态（因为一段时间内都在循环重试）

c++中的原子变量提供了各种CAS操作，常见的有：

// expected: 期望的原子变量的状态
// desired: 替换为的状态
// 语义: 如果当前原子变量的状态为expected, 就尝试替换为desired, 替换成功返回true, 否则返回false
// 如果返回false, expected会被改为当前原子变量的新值
bool compare_exchange_strong(T& expected, T desired,
                             memory_order success_order,
                             memory_order failure_order) noexcept;

bool compare_exchange_weak(T& expected, T desired,
                           memory_order success_order,
                           memory_order failure_order) noexcept;

其中的memory_order是内存序，默认为memory_order_seq_cst，也就是保证线程安全的一档，内存序太过复杂，这里不多涉及，使用默认就好

strong和weak的区别在于weak可能会假失败（即使原子变量中存的是expected值也有可能替换失败返回false），但是执行速度会快一些，一般在循环中使用weak，因为可以容忍少数的假失败来提升速度

原子变量基本读写操作：

// 内存序默认memory_order_seq_cst
// 原子读
T load(memory_order order);
// 原子写
void store(T val, memory_order order);
// 原子交换, 返回原子变量中原先存的值
T exchange(T val, memory_order order);

为什么不直接用exchange()之类的函数？

考虑这么一种情况：协程1执行到了set()，协程2执行到了await::suspend()，协程2检查当前状态不为kSET，但在执行exchange()之前，协程1执行了CAS并把状态修改为了kSET，此时协程2的行为应该是退出await::suspend()继续运行，但实际上会执行exchange()把状态再次修改，就会出现不符合预期的情况

无锁代码：

class event_base {
public:
    struct base_awaiter {
        friend class event_base;
        base_awaiter(event_base& event) noexcept : m_event(event), m_ctx(local_context()) {}
        auto await_ready() noexcept -> bool {
            m_ctx.register_wait();
            return m_event.is_set();
        }
        auto await_suspend(std::coroutine_handle<> handle) noexcept -> bool {
            m_handle = handle;
            void *old_state = m_event.m_state.load(std::memory_order_acquire);
            while (true) {
                // 竞争情况: 准备队列时, event被set了
                if (old_state == reinterpret_cast<void*>(kSet)) {
                    return false;
                }
                // 正常情况: 把自己加入等待者链表
                m_next = (old_state == kUnsetNowaiter) ? nullptr : static_cast<base_awaiter*>(old_state);
                if (m_event.m_state.compare_exchange_strong(
                    old_state, 
                    this,
                    std::memory_order_acq_rel,
                    std::memory_order_relaxed
                )) {
                    return true;
                }
            }
        }
        auto await_resume() noexcept -> void{
            m_ctx.unregister_wait();
        }
    protected:
        event_base& m_event;
        context& m_ctx;
        std::coroutine_handle<> m_handle{nullptr};
        base_awaiter* m_next{nullptr};
    };
    friend struct base_awaiter;
public:
    event_base() noexcept : m_state(kUnsetNowaiter) {};
    ~event_base() noexcept {}

    auto is_set() const noexcept -> bool {
        return m_state.load(std::memory_order_acquire) == reinterpret_cast<void*>(kSet);
    }

    auto reset() -> void {
        void *expected_state = reinterpret_cast<void*>(kSet);
        m_state.compare_exchange_strong(expected_state, kUnsetNowaiter, std::memory_order_acq_rel);
    }

protected:
    void resume_awaiters() noexcept {
        void* old_state = m_state.exchange(reinterpret_cast<void*>(kSet), std::memory_order_acq_rel);
        if (old_state != reinterpret_cast<void*>(kSet)) {
            // 链表挂载等待的协程, 唤醒
            // base_awaiter* awaiter = static_cast<base_awaiter*>(old_state);
            base_awaiter* head = static_cast<base_awaiter*>(old_state);
            while (head != nullptr) {
                auto* next_awaiter = head->m_next;
                head->m_ctx.submit_task(head->m_handle);
                head = next_awaiter;
            }
        }
    }
protected:
    static constexpr void* kUnsetNowaiter = nullptr;
    static constexpr std::uintptr_t kSet = 1;
    std::atomic<void*> m_state;
};

mutex

协程意义上的锁，当一个协程获取锁而陷入阻塞时，只让自己陷入suspend状态，而非通常意义上整个线程陷入阻塞状态，此时，context线程仍然会继续从engine取出协程任务并执行

其api如下：

auto try_lock() noexcept -> bool; // 普通调用
auto lock() noexcept -> awaiter; // 协程调用，awaiter 的 await_resume 返回 void
auto unlock() noexcept -> void; // 普通调用
auto lock_guard() noexcept -> awaiter; // 协程调用，awaiter 的 await_resume 返回 lock_guard

try_lock即尝试获取锁，返回值表示是否成功获取锁
lock作为协程调用需要通过co_await mutex.lock()的形式调用
unlock即释放锁，并唤醒一个 suspend awaiter（如果存在的话）
lock_guard封装了一系列复合操作，通过co_await mutex.lock_guard()的形式调用来获取锁并返回 lock_guard，而 lock_guard 在生命周期结束后会自动释放锁，该函数只需要在awaiter_resume返回对应的lock_guard

首先明确的是，mutex不能像event那样，使用std::mutex来实现，毕竟不能尝试使用锁来实现锁，并且二者语义也不同，因此只能考虑无锁版本

有了event的无锁实现经验，会发现mutex与其类似，核心数据结构是一个awaiter队列，这里同样使用atomic<void> m_state来表示一个链表，接下来就是考虑它的状态：

当前锁没有被使用（kUNLOCKED）
当前锁被使用了，但没有等待者（kLOCKED_NO_WAITER）
当前锁被使用了，并且有等待者（LOCKED_HAVE_WAITER，保存指向链表头的指针）

初始状态下应为kUNLOCKED

状态变化：

lock()：

该函数负责对当前互斥量mutex上锁，其核心操作同样在await_suspend()中：

如果当前互斥量没有上锁，就上锁后，让协程继续执行；

否则将自身挂载到链表上，并让协程陷入阻塞态；

同样，直接修改状态时会出现一些竞争状态，即在该函数执行时，可能有以下情况发生：

互斥量被释放了，m_state变为了kUNLOCKED状态
其他协程也在等待互斥量，并尝试将自身挂到链表中

while (true) {
    // 当前锁没有获取, 尝试获取
    if (m_state == kUNLOCKED) {
        if (m_state.compare_exchange_weak(
                            kUNLOCKED, 
                            kLOCKED_NO_WATIER)) {
            break;
        }
        // 获取锁失败, 被别的协程获取了, 重试
        continue;
    }
    // 原子变量的CAS操作, 尝试挂载自身到链表中
	if (try_add_to_list(this, m_state)) {
        // 成功了, 退出循环
        break;
    }
    // 失败了, 循环重试
}

unlock()：

该函数负责在协程中解除锁：

m_state不能kUNLOCKED状态，因为不能解锁一个没有上锁的互斥量
如果m_state为kLOCKED_HAVE_WAITER状态，就恢复一个协程，该协程会自动获得锁，并且当前链表为空了，应该将其状态转为kLOCKED_NO_WAITER状态
如果m_state为kLOCKED_NO_WAITER状态，那么应该将其状态改为kUNLOCKED

类似lock()，使用CAS循环：

while (true) {
    // 尝试释放锁
    if (state == kLOCKED_NO_WAITER) {
        // 尝试改变状态为kUNLOCKED
        if (m_state.compare_exchange_weak(
                         kLOCKED_NO_WAITER, 
                         kUNLOCKED)) {
            return;
        }
        // 改变失败, 重试
        continue;
    }
    // 有协程尝试解锁未上锁的mutex, 应该报error
    if (state == kUNLOCKED) {
    	ERROR;
	}
    // 当前有等待者, 尝试唤醒一个等待者, 并尝试修改状态为 m_state.next 或者kLOCKED_NO_WAITER
   	if (m_state.compare_exchange_weak()) {
        resume();
    }
}

优化：

为实现方便，在kLOCKED_HAVE_WAITER状态下，m_state按照后进先出的顺序来恢复陷入suspend状态的协程，并且相比event的set函数，在unlock()函数使用了CAS循环，进一步降低了性能

考虑到unlock只会被上锁的协程来调用，这个时候是不会有多个协程同时unlock()的，于是可以设置一个awaiter指针（非原子变量），每次解锁时，如果该指针为空指针，并且当前状态为kLOCKED_HAVE_WAITER，就将链表转移给awaiter指针，之后别的协程再次释放锁时，直接从该指针恢复协程即可

// 有协程尝试解锁未上锁的mutex, 应该报error
if (m_state == kUNLOCKED) {
    ERROR;
}
// 
if (awaiter_ptr == nullptr) {
    if (m_state == kLOCKED_NO_WAITER) {
        // 尝试替代为初始状态
        if (m_state.compare_exchange_strong(
                kLOCKED_NO_WAITER,
                kUNLOCKED)) {
            // 替换成功, 退出
            return;
        }
    }
    // 否则当前状态为kLOCKED_HAVE_WAITER, m_state实际存储的是链表头指针
    void* waiting_list = m_state.exchange(kLOCKED_NO_WATIER, std::memory_order_acq_rel);
    assert(waiting_list != kUNLOCKED && "can't unlock unlocked mutex!");
    awaiter_ptr = static_cast<awaiter*>(waiting_list);
    // 如果希望FIFO, 就翻转链表
    
}
// 当前实际状态是kLOCKED_HAVE_WAITER
// 移动头结点
awaiter* to_resume = awaiter_ptr;
awaiter_ptr = to_resume->next;
// 恢复弹出的协程
to_resume->resume_coro();

为什么这里判断了m_state == kLOCKED_NO_WAITER后，之后状态不可能被设置为kLOCKED_NO_WAITER？

原因很简单，最多只有一个协程执行unlock()，且当前状态不能为kUNLOCKED，这代表lock()此时也不可能把状态设置为kLOCKED_NO_WAITER

核心成员：

成员变量：

inline static void* kUNLOCKED = nullptr;
inline static void* kLOCKED_NO_WATIER = reinterpret_cast<void*>(1);
std::atomic<void*> m_state;	
mutex_awaiter* m_awaiter_head{nullptr};

struct mutex_awaiter：

struct mutex_awaiter {
    std::coroutine_handle<> handle;
    mutex& mtx;
    context& ctx;
    mutex_awaiter* next;	// 作用类似链表的next指针
    // 其他函数见代码
};

其余函数实现都比较简单，就不再赘述

代码：

class mutex
{
public:
    struct mutex_awaiter {
        std::coroutine_handle<> handle;
        mutex& mtx;
        context& ctx;
        mutex_awaiter* next;

        explicit mutex_awaiter(mutex& mutex) noexcept : mtx(mutex), 
            ctx(local_context()), handle(nullptr), next(nullptr) {}

        virtual ~mutex_awaiter() {}    

        auto await_ready() noexcept -> bool {
            ctx.register_wait(); 
            void* expected = kUNLOCKED;
            return mtx.m_state.compare_exchange_strong(
                expected,
                 kLOCKED_NO_WATIER,
                 std::memory_order_acquire);
        }

        auto await_suspend(std::coroutine_handle<> awaiting_handle) noexcept -> bool {
            handle = awaiting_handle;
            return add_waiting_list();
        }

        auto await_resume() noexcept -> void {
            ctx.unregister_wait();
        }

        auto add_waiting_list() noexcept -> bool {
            void* old_state = mtx.m_state.load();
            while (true) {
                // 竞争情况：在我们准备排队时，锁被释放了。
                // 我们可以再次尝试获取锁，避免不必要的挂起。
                if (old_state == kUNLOCKED) {
                    if (mtx.m_state.compare_exchange_weak(
                            old_state, 
                            kLOCKED_NO_WATIER)) {
                        return false; // 成功获取锁，不要挂起。
                    }
                    // CAS 失败，意味着 old_state 被其他线程改变了，循环会用新值重试。
                    continue;
                }

                // 正常情况：锁被持有，我们需要把自己加入链表。
                // old_state 要么是 kLockedNoWaiters，要么是链表头。
                next = (old_state == kLOCKED_NO_WATIER) ? nullptr : static_cast<mutex_awaiter*>(old_state);

                // release 内存序确保了在我们挂起协程之前的代码，对唤醒我们的那个线程是可见的。
                if (mtx.m_state.compare_exchange_weak(
                        old_state, 
                        this)) {
                    return true; // 成功把自己加入队列，现在可以安全挂起了。
                }
                // CAS 失败，循环会用新的 old_state 值重试。
            }
        }

        virtual auto resume_coro() noexcept -> void {
            ctx.submit_task(handle);
        }
    };

    struct guard_awaiter : mutex_awaiter
    {
        using mutex_awaiter::mutex_awaiter;
        auto await_resume() -> detail::lock_guard<mutex> { 
            ctx.unregister_wait();
            return detail::lock_guard<mutex>(mtx); 
        }
    };
public:
    mutex() noexcept : m_state(kUNLOCKED), m_awaiter_head(nullptr) {}
    ~mutex() noexcept {
        assert(m_state.load() == kUNLOCKED);
    }
    mutex(const mutex&) = delete;
    mutex& operator=(const mutex&) = delete;

    auto try_lock() noexcept -> bool { 
        void* expected = kUNLOCKED;
        return m_state.compare_exchange_strong(
            expected, 
            kLOCKED_NO_WATIER);
    }


    auto lock() noexcept -> mutex_awaiter {
        return mutex_awaiter{*this}; 
    };

    auto unlock() noexcept -> void {
        assert(m_state != kUNLOCKED && "can't unlock unlocked mutex!");
        if (m_awaiter_head == nullptr) {
            // kLOCKED_NO_WAITER
            void* expected = kLOCKED_NO_WATIER;
            if (m_state.compare_exchange_strong(
                expected,
                kUNLOCKED,
                std::memory_order_acq_rel,
                std::memory_order_acq_rel)) {
                    // 当前没有等待者
                    return;
                }
            // HAVE WAITER
            void* waiting_list = m_state.exchange(kLOCKED_NO_WATIER, std::memory_order_acq_rel);
            assert(waiting_list != kUNLOCKED && "can't unlock unlocked mutex!");
            m_awaiter_head = static_cast<mutex_awaiter*>(waiting_list);
            // reverse the list, to implement FIFO
            mutex_awaiter* awaiter = m_awaiter_head;
            m_awaiter_head = nullptr;
            while (awaiter != nullptr) {
                auto next_awaiter = awaiter->next;
                awaiter->next = m_awaiter_head;
                m_awaiter_head = awaiter;
                awaiter = next_awaiter;
            }
        }
        // m_state is LOCKED_HAVE_WAITER
        mutex_awaiter* to_resume = m_awaiter_head;
        m_awaiter_head = to_resume->next;
        to_resume->resume_coro();
    };

    auto lock_guard() noexcept -> guard_awaiter { return guard_awaiter{*this};};
private:
    inline static void* kUNLOCKED = nullptr;
    inline static void* kLOCKED_NO_WATIER = reinterpret_cast<void*>(1);
    std::atomic<void*> m_state;
    mutex_awaiter* m_awaiter_head;
};

c++20制作简易协程库2

Fri, 14 Nov 2025 22:00:00 GMT

io_uring简介

安装

github克隆liburing项目：

git clone https://github.com/axboe/liburing.git

编译并安装：

cd liburing
./configure --cc=gcc --cxx=g++
make -j
make liburing.pc
sudo make install

在usr/include/目录下找到liburing即为成功

基本使用

liburing提供了io_uring简化后的api调用，类似epoll的工作流程：

初始化io_uring：io_uring_queue_init()
从请求队列中获取一个SQE：io_uring_get_sqe()
填充读写请求：io_uring_prep_read() / write()
提交请求：io_uring_submit()
等待结果：io_uring_wait_cqe()
标记结果已处理：io_uring_cqe_seen()

核心数据结构

io_uring：

类似epoll_create()会创建跟epoll空间关联的句柄，liburing要求使用

struct io_uring ring;定义一个操作空间，之后的IO操作（包括提交请求SQE，获取结果CQE）都在上面进行，其在用户态通过mmap映射了内核中的两个环形队列（提交队列和完成队列），从而实现了内核与用户态的高效通信

io_uring_queue_init负责对该空间进行初始化，第一个参数指定了最多可以有多少个IO任务
```
/* * entries: 队列深度。指定了最多可以有多少个“在途”未处理的 IO 任务
 * 建议是2的幂，如 4096
 * ring:    指向你定义的结构体指针，库函数会填充它
 * flags:   标志位（如 IORING_SETUP_IOPOLL 开启轮询模式）
 */
int io_uring_queue_init(unsigned entries, struct io_uring *ring, unsigned flags);
```

sqe：

类似epoll中的struct epoll_event，但它们的功能有比较大的区别：

epoll_event 是告诉内核“我要监控这个 fd 的可读事件”
sqe 是告诉内核“我要执行这个具体的 I/O 操作”。可以将 sqe 想象成一张**“任务工单”**，把要做的操作（读、写、连）填好，交给内核

申请一个IO请求：

// 从 ring 中申请一个空的工单槽位
struct io_uring_sqe *sqe = io_uring_get_sqe(&ring);

关于io_uring_sqe：通常使用 io_uring_prep_* 辅助函数（可以是accept，send，recv，read，write）来填充，但理解其内部字段有助于理解底层原理

struct io_uring_sqe {
    __u8    opcode;       // 操作码。决定是 Read, Write, Accept 还是 Connect
                          // 类似 epoll_ctl 中的 EPOLL_CTL_ADD 等动作
    __u8    flags;        // 标志位 (如 IOSQE_IO_LINK 开启链式调用)
    __u16   ioprio;       // 优先级
    __s32   fd;           // 要操作的文件描述符 (类似 epoll_ctl 的第一个参数)
    __u64   off;          // 文件的偏移量 (pread/pwrite 用)
    __u64   addr;         // 用户态缓冲区 buffer 的地址 (读写数据的存放地)
    __u32   len;          // buffer 的长度
    
    /* * 【核心字段】user_data 
     * 这是一个 64 位的“回执编号”或“上下文指针”。
     * 类似 epoll_event.data.ptr。
     * 你在这里填什么，内核在完成任务后，会原封不动地在 cqe 里还给你。
     * 通常用来存放用户自定义信息结构体的指针。
     */
    __u64   user_data;    
    
    // ... 其他联合体字段用于特定操作
};

cqe：类似于 epoll_wait 返回的就绪事件

在 epoll 中，返回意味着“你可以去读写了”（Reactor 模型）
在 io_uring 中，返回意味着“内核已经帮你读写完了，这是结果”（Proactor 模型），可以将 cqe 想象成任务完成后的**“结果回执单”**

获取完成的IO请求：

struct io_uring_cqe *cqe;
// 阻塞等待至少一个任务完成
io_uring_wait_cqe(&ring, &cqe);
// 或者非阻塞查看
io_uring_peek_cqe(&ring, &cqe);

关于io_uring_cqe：结构非常精简，只包含结果必须的信息

struct io_uring_cqe {
    /* * 【核心字段】user_data
     * 对应 sqe 中填入的 user_data。
     * 通过它，你才能知道这个结果是属于哪一个 fd 的，或者是哪一次 read 操作的。
     */
    __u64   user_data;    

    /* * 【核心字段】res
     * 操作的返回值。
     * 如果 >= 0：表示成功传输的字节数 (类似 read() 的返回值)。
     * 如果 < 0：表示出错，值为 -errno (如 -EAGAIN, -ECANCELED)。
     */
    __s32   res;          

    /* * flags
     * 元数据标志。例如在使用 Provided Buffers 时，这里会包含
     * 内核自动选用的 Buffer ID。
     */
    __u32   flags;        
};

engine

engine是协程执行单元，负责存储所有的task和异步IO并向外提供执行的接口

要存储任务，就要有对应的存储空间，这里选择使用atomic queue无锁队列来存储对应的协程任务，在这里不存储具体的task对象，然后存储std::coroutine_handle<>

初始化

engine成员：

// 封装操作后的io_uring
uring_proxy m_upxy;

// 无锁队列存储协程
mpmc_queue<coroutine_handle<>> m_task_queue;

atomic<size_t> m_submit_io{0}; // 当前待提交的io操作数量
atomic<size_t> m_running_io{0}; // 当前正在执行的io操作数量

线程局部变量

为简单处理多线程的情况，一旦某个协程句柄被提交到某个engine的任务队列中，即使其暂停恢复后，也应该继续在原先的engine上执行，所以设置一个线程局部变量：
```
struct local_info
{
    context* ctx{nullptr};
    engine*  egn{nullptr};
};
inline thread_local local_info linfo;
```

初始化和销毁：

auto engine::init() noexcept -> void
{
    // 设置线程局部变量
    linfo.egn = this;
    m_upxy.init(config::kEntryLength);
    m_submit_io.store(0, memory_order_relaxed);
    m_running_io.store(0, memory_order_relaxed);
}

auto engine::deinit() noexcept -> void
{
    linfo.egn = nullptr;
    m_upxy.deinit();
    mpmc_queue<coroutine_handle<>> empty_queue;
    m_task_queue.swap(empty_queue); // 清空任务队列
}

添加IO任务

当协程中需要执行IO任务时，分两步：

从engine中获取一个sqe
告诉engine当前提交了一个IO操作，对应的m_submit_io就要加1

auto engine::get_free_urs() noexcept -> ursptr
{
    return m_upxy.get_free_sqe();
}
auto engine::add_io_submit() noexcept -> void
{
    m_submit_io.fetch_add(1, memory_order_relaxed);
    wakeup(); // 后面解释作用
}

提交并执行协程任务

提供提交任务的接口，外部可以通过对应的接口来提交对应的协程句柄：

auto engine::submit_task(coroutine_handle<> handle) noexcept -> void
{
    if (!m_task_queue.try_push(handle)) {
        wakeup();
    } else {
        // 队列满, 应该直接运行协程或者丢掉该协程并报错
    }
}

执行协程任务：

ready() ：工作线程用来判断 engine 的任务队列是否还有待执行的任务
num_task_schedule() ：得到当前 engine 的任务队列还有多少任务
exec_one_task() ：调用schedule()，engine 会从任务队列中弹出一个任务并作为返回值返回，然后恢复对应协程的执行
empty_io() ：工作线程调用此函数来判断 engine 内部是否还有未处理的 I/O 任务，这包括未提交和正在执行但未完成的 I/O，如果empty_io()返回了 false 那么即使工作线程收到停止信号也不会直接停止，因为这表明还有任务没有执行完成。
poll_submit() ：这是 engine 最为核心的函数，实现对 I/O 的提交以及处理已经完成的 I/O，对于从 io_uring 取出的 cqe，采取批量消费的模式，使用handle_cqe_entry()函数，获取IO的结果，如果有回调，就执行对应的回调函数。而在处理 I/O 的过程中也应该变更 I/O 执行状态

auto engine::ready() noexcept -> bool
{
    return !m_task_queue.was_empty();
}

auto engine::num_task_schedule() noexcept -> size_t
{
    return m_task_queue.was_size();
}

auto engine::schedule() noexcept -> coroutine_handle<>
{
    auto handle = m_task_queue.pop();
    return handle;
}

auto engine::exec_one_task() noexcept -> void
{
    auto coro = schedule();
    coro.resume();
}

auto engine::empty_io() noexcept -> bool
{
    return m_submit_io == 0 && m_running_io == 0;
}

auto engine::poll_submit() noexcept -> void
{
    // 当前有可提交的IO任务，就提交io_uring中
    if (m_submit_io > 0) {
        m_upxy.submit();
        m_running_io += m_submit_io;
        m_submit_io.store(0, memory_order_relaxed);
    }
    // 等待任务完成, peek_uring()确保当前有IO任务完成才会消费, 否则当前engine是由于其他原因被唤醒, 跳过处理IO的部分
    if (m_upxy.wait_eventfd() && m_upxy.peek_uring()) {
        m_upxy.handle_for_each_cqe(
            std::bind(&engine::handle_cqe_entry, this, std::placeholders::_1),
            true
        );
    }
}

wakeup

当engine执行了协程任务，并提交了IO任务时，从其角度来看，当前没有协程任务了，也没有IO任务要提交了，需要做的事情就是等待新的协程或者IO任务到来，或者IO任务完成的通知

这一点通过io_uring与eventfd的配合来解决

eventfd 是Linux下的轻量级的用于事件通知的文件描述符，可以在io_uring实例中注册一个eventfd，那么每当有IO完成时，io_uring就会向其写入一个值

如果eventfd中没有数据，那么从eventfd中读数据本身是一个阻塞的操作，可以利用这一点，在poll_submit()中阻塞当前的工作线程，等待IO任务完成

如果有新的协程任务或者IO任务到来，可以利用这一机制，主动向eventfd中写入一个值，poll_submit()检查当前不是由于IO任务完成而被唤醒，就会跳过消费cqe这一行为，转而去执行新的协程任务/提交IO任务

context

engine向外提供了提交task和异步IO操作的接口，那么context需要利用这些接口，去执行协程任务或是提交IO操作，具体做法是开启一个线程来进行事件循环：

执行计算任务（exec_one_task）
提交IO任务并等待（poll_submit）
判断当前是否已经执行完所有任务，还有就阻塞，没有就退出

理想的情况是外部定义一个context，提交要执行的协程任务（要提交IO任务可以开启一个协程任务，在里面执行IO任务，原因是IO任务本身被设计成awaiter而不是task），然后调用run函数启动事件循环，等待任务执行完毕后自动退出即可

初始化

context持有一个engine对象和一个工作线程，使用工作线程是为了外部在使用context时无需关心context内部的实现（包括初始化和清理工作）

成员变量

engine   m_engine; // 执行引擎，提供执行函数的接口
unique_ptr<jthread> m_job; // jthread, 能够在析构时自动join, 也能接收停止信号
ctx_id              m_id;

atomic<int> m_waited_cnt{0}; // 记录当前有多少陷入suspend状态的协程任务
std::function<void()> m_try_stop{nullptr}; // 停止context的运行

初始化和清理：

auto context::init() noexcept -> void
{
    // 线程局部变量记录当前的context
    linfo.ctx = this;
    // 初始化执行引擎
    m_engine.init();
    m_waited_cnt = 0;
}

auto context::deinit() noexcept -> void
{
    linfo.ctx = nullptr;
    m_engine.deinit();
    m_waited_cnt = 0;
}

事件循环

三个动作：

执行计算任务（exec_one_task）
提交IO任务并等待（poll_submit）
判断当前是否已经执行完所有任务，还有就阻塞，没有就退出

auto context::run(stop_token token) noexcept -> void
{
    while (!token.stop_requested()) {
        int task_num = m_engine.num_task_schedule();
        for (int i = 0; i < task_num; i++) {
            m_engine.exec_one_task();
        }
    
        if (check_stop_sig()) {
            if (m_try_stop) {
                m_try_stop();
            }
        }
        m_engine.poll_submit();
    }
}

判断条件发生在提交IO任务之前，这是因为提交IO任务是一个阻塞函数，设想一种情况，外部通过submit接口预先提交了所有任务，但是里面没有涉及IO，那么当这一组任务在context中由exec_one_task一次性执行完毕后，没有协程任务也没有IO任务了，自然应该退出了，如果先执行poll_submit，会阻塞在eventfd的读取上，外部没有提交协程任务或者IO任务，内部也没有IO任务完成，就会一直阻塞下去

判断当前是否能够停止

三个条件：

有没有待运行的协程任务
有没有处于suspend状态的协程任务
有没有未完成/未提交的IO任务

auto context::check_stop_sig() noexcept -> bool {
    return m_engine.empty_io() && m_waited_cnt <= 0 && !m_engine.ready();
}

发送停止信号

jthread可以发送停止信号：

jthread::request_stop();

当jthread执行的函数需要循环查看stop_token，然后主动退出：

auto context::run(stop_token token) noexcept -> void
{
    while (!token.stop_requested()) {
    	...
    }
}

于是我们可以提前定义一个函数对象m_try_stop，当context符合条件时，主动发送线程停止信号，同时向eventfd写入一个值，使后面的poll_submit不会阻塞：

m_try_stop = [this]() {
    notify_stop();
};
// 
auto context::notify_stop() noexcept -> void
{
    m_job->request_stop();
    m_engine.wakeup();
}

start

start函数中运行工作线程，因为jthread使用智能指针管理，所以单个context可以实现复用（前提是jthread工作线程正常结束工作了）

auto context::start() noexcept -> void
{
    m_job = make_unique<jthread>(
        [this](stop_token token)
        {
            this->init();
            if (m_try_stop == nullptr) {
                m_try_stop = [this]() {
                    notify_stop();
                };
            }
            this->run(token);
            this->deinit();
        });
}

之后就可以使用如下方式来使用context：

context ctx;
ctx.submit_task(...);
// repeat submit...
ctx.start(); // 启动运行(非阻塞)
ctx.join(); // 主动等待 context 完成所有任务
// 后面要使用context可以继续submit然后start

scheduler

为了充分利用cpu的多核能力，创建scheduler来管理多个context，方便并发执行各个协程或IO任务，用户无需手动管理各个context，只要把任务交给scheduler，由scheduler进行任务的调度

流程：

scheduler::init(); // 入参为 context 数量，默认为当前机器的逻辑 CPU 核心数
submit_to_scheduler(task);
// more submit...
scheduler::loop(); // 等待全部 context 完成任务后再关闭全部 context 并返回(阻塞式)

当调用scheduler::loop时，程序会调用context开始执行任务，并阻塞等待所有任务完成

任务管理

当调用多个context执行任务的时候，我们不希望每个context在执行完自己的任务后，检查到队列中没有任务了就停止，而是希望由scheduler统一发送停止信号，这一点可以通过设置各个context的m_try_stop为一个空函数（非nullptr）来做到

其次，既然需要scheduler来统一发送停止信号，scheduler就必须知道什么时候停止各个context，这时候出现了一个矛盾，本来是每个context掌管自己运行任务的数量，scheduler现在要强行接管这一功能，还要同时清楚多个context上的任务数量，看上去并不易实现

接下来介绍的包装协程可以解决这一痛点

wrapper_task

lab1中介绍的通用型task类可以封装各种类型的协程任务，但有一点不好，在co_return后的final_suspend会返回给上一个协程任务，没有就暂停自身，这可能影响协程帧的释放：

task<void> func1() {
    ...
    co_await IO; // 将自身挂起等待IO完成
    co_return;
}
task<void> func2() {
    co_await func1();
    ...
    co_return;
}

试想一下，当我们将func2()提交给scheduler或者context，被执行引擎运行时：

auto engine::exec_one_task() noexcept -> void
{
    auto coro = schedule();
    coro.resume();
}

其运行过程应该是：

engine取出func2()的句柄，然后resume()执行
执行func2()
co_await func1()将执行权转移给func1()
执行func1()
co_await IO，func1()会被挂起
执行权回到engine::exec_one_task()中，继续执行

当一个IO完成，func1()的句柄被重新送入任务队列：

engine取出func1()的句柄，然后resume()执行
执行func1()
co_return将执行权转移给func2()
执行func2()
co_return将执行权转移给noop_coroutine，同时func1()对应的task被析构，释放对应的句柄
noop_coroutine什么都不做，执行权回到engine::exec_one_task()中继续执行

此时，如果外部没有保存func2()的句柄，func2()对应的协程帧就永远不会被释放（除非被外部唤醒或是由外部主动destroy释放），那么就会出现内存泄露

一个可行的解决办法是，定义一个只允许在scheduler或者context中的使用的特别task类，该类负责对用户传入的协程进行一次包装，并在final_suspend时返回suspend_never：

auto make_wrapper_task(coro::task<void> user_task) -> wrapper_task {
    co_await user_task;
    co_return;
    // user_task will be destruct, its coroutine frame will be deleted
}

这样，外部提交的协程都会由于RAII，使得协程句柄在task的析构函数中释放，而wrapper_task则由于final_suspend返回suspend_never，直接运行到clean code清除自身

wrapper_task只封装右值task<void>类型，这是因为用户提交到scheduler或context的协程任务不应该在意返回值，同时也不应该在外部持有协程句柄造成二次释放，如果协程有返回值需要处理，应该提前封装：

task<int> inner() {
    ...
    co_return 1;
}
task<void> to_submit() {
    auto n = co_await inner();
    co_return;
}
submit_to_scheduler(to_submit());
// 或者如下方式:
// auto task = to_submit();
// submit_to_scheduler(std::move(task));

具体实现：

// hpp
class wrapper_task;

class wrapper_promise {
public:
    wrapper_promise();
    ~wrapper_promise();
    // delete the copy constructor and operator
    wrapper_promise(const wrapper_promise&) = delete;
    wrapper_promise(wrapper_promise&&) = delete;
    auto operator=(const wrapper_promise&) -> wrapper_promise& = delete;
    auto operator=(wrapper_promise&&) -> wrapper_promise& = delete;
    // promise function
    auto get_return_object() noexcept -> wrapper_task;
    auto initial_suspend() noexcept -> std::suspend_always;
    auto final_suspend() noexcept -> std::suspend_never;
    auto return_void() noexcept -> void;
    auto unhandled_exception() noexcept -> void;
    auto set_before_exit_func(std::function<void()> before_exit_func) noexcept -> void;
private:
    std::function<void()> m_before_exit_func{nullptr};
    std::exception_ptr m_exception_ptr{nullptr};
};
/*
 * this class should be used to encapsulate the top-level 
 * coroutine submitted by the user.
 */
class wrapper_task {
public:
    using promise_type = wrapper_promise;
    
    explicit wrapper_task(std::coroutine_handle<wrapper_promise> handle);
    ~wrapper_task();
    // delete the copy constructor and operator
    wrapper_task(const wrapper_task&) = delete;
    wrapper_task(wrapper_task&&);
    auto operator=(const wrapper_task&) -> wrapper_task& = delete;
    auto operator=(wrapper_task&&) ->wrapper_task&;
    // nodiscard指明编译器去检查返回值有没有被使用过, 即强制调用者去使用返回值
    [[nodiscard]] auto promise() const -> const wrapper_promise& {
        return m_handle.promise();
    }
    [[nodiscard]] auto promise() -> wrapper_promise& {
        return m_handle.promise();
    }
    [[nodiscard]] auto handle() const -> const std::coroutine_handle<wrapper_promise>& {
        return m_handle;
    }
    [[nodiscard]] auto handle() -> std::coroutine_handle<wrapper_promise>& {
        return m_handle;
    }
    auto resume() -> bool {
        if (!m_handle.done()) {
        m_handle.resume();
    }
    return !m_handle.done();
    }
private:
    std::coroutine_handle<wrapper_promise> m_handle{nullptr};
};

auto make_wrapper_task(coro::task<void> user_task) -> wrapper_task;

// cpp
wrapper_promise::wrapper_promise() {

}

wrapper_promise::~wrapper_promise() {

}

auto wrapper_promise::get_return_object() noexcept -> wrapper_task {
    return wrapper_task{std::coroutine_handle<wrapper_promise>::from_promise(*this)};
}

auto wrapper_promise::initial_suspend() noexcept -> std::suspend_always {
    return std::suspend_always{};
}

auto wrapper_promise::final_suspend() noexcept -> std::suspend_never {
    if (m_before_exit_func) {
        m_before_exit_func();
    }
    return std::suspend_never{};
}

auto wrapper_promise::return_void() noexcept -> void {

}
auto wrapper_promise::unhandled_exception() noexcept -> void {
    // store it, but didn't use it, user can not touch this
    m_exception_ptr = std::current_exception();
}
auto wrapper_promise::set_before_exit_func(std::function<void()> before_exit_func) noexcept -> void {
    m_before_exit_func = std::move(before_exit_func);
}

wrapper_task::wrapper_task(std::coroutine_handle<wrapper_promise> handle)
    : m_handle(handle) {

}
wrapper_task::~wrapper_task() {
    // no-op
    // suspend_never means once co_return, coroutine frame will self-destruct
}
wrapper_task::wrapper_task(wrapper_task&& other) :m_handle(std::exchange(other.m_handle, nullptr)) {

}
auto wrapper_task::operator=(wrapper_task&& other) -> wrapper_task& {
    if (std::addressof(other) != this) {
        if (m_handle != nullptr) {
            m_handle.destroy();
            m_handle = nullptr;
        }
        m_handle = std::exchange(other.m_handle, nullptr);
    }
    return *this;
}

auto make_wrapper_task(coro::task<void> user_task) -> wrapper_task {
    co_await user_task;
    co_return;
    // user_task will be destruct, its coroutine frame will be deleted
}

任务计数

从submit_to_scheduler()提交的协程默认被视为顶层协程，只有其生命周期结束，才意味着一个协程任务的结束，这使我们可以不再关心协程内部的运行情况，因此可以设置一个原子计数器，每当submit_to_scheduler()被调用时，将计数器加1，当顶层协程结束时，借由wrapper_task，将计数器减1，当计数器为0时，代表着所有协程任务已经被执行完毕，可以退出

初始化

scheduler采用单例模式来实现，为了外部使用方便，只对外保留静态接口，将getInstance设置为私有

变量

// 静态变量
private:
	// 外部提交的顶层协程个数
    static std::atomic<int> m_task_cnt;
	// 条件变量, 负责在协程任务结束后唤醒阻塞的线程
    static std::condition_variable m_cv;
	static std::mutex m_mux;
// 成员变量
private:
	// context个数
    size_t                                              m_ctx_cnt{0};
    // 存储context
	detail::ctx_container                               m_ctxs;
    // 派发机制
	detail::dispatcher<coro::config::kDispatchStrategy> m_dispatcher;

懒汉单例：

private:
static auto get_instance() noexcept -> scheduler*
{
    static scheduler sc;
    return &sc;
}

初始化变量

inline static auto init(size_t ctx_cnt = std::thread::hardware_concurrency()) noexcept
    -> void
{
    if (ctx_cnt == 0)
    {
        ctx_cnt = std::thread::hardware_concurrency();
    }
    get_instance()->init_impl(ctx_cnt);
}
// .cpp
// 静态变量在cpp文件中初始化
std::atomic<int> scheduler::m_task_cnt = 0;
std::condition_variable scheduler::m_cv;
std::mutex scheduler::m_mux;
auto scheduler::init_impl(size_t ctx_cnt) noexcept -> void
{
    detail::init_meta_info();
    m_task_cnt = 0;
    m_ctx_cnt = ctx_cnt;
    m_ctxs    = detail::ctx_container{};
    m_ctxs.reserve(m_ctx_cnt);
    for (int i = 0; i < m_ctx_cnt; i++)
    {
        m_ctxs.emplace_back(std::make_unique<context>());
    }
    m_dispatcher.init(m_ctx_cnt, &m_ctxs);
}

提交任务

对于外部提交进来的任务，使用wrapper_task封装，增加原子计数，在wrapper_task的final_suspend函数中减少原子计数：

inline void submit_to_scheduler(task<void>&& task) noexcept
{
    scheduler::submit(std::move(task));
}
// 类函数
static inline auto submit(task<void>&& task) noexcept -> void
{
    m_task_cnt.fetch_add(1, std::memory_order_acq_rel);
    auto wrapper_task = detail::make_wrapper_task(std::move(task));
    // 设置原子计数的增减
    wrapper_task.promise().set_before_exit_func([]() {
        m_task_cnt.fetch_sub(1, std::memory_order_acq_rel);
        if(m_task_cnt.load(std::memory_order_relaxed) == 0) {
            m_cv.notify_all();
        }
    });
    auto handle = wrapper_task.handle();
    submit(handle);
}
auto scheduler::submit_task_impl(std::coroutine_handle<> handle) noexcept -> void
{
    // 获取当前要派发到context的对应id
    size_t ctx_id = m_dispatcher.dispatch();
    m_ctxs[ctx_id]->submit_task(handle);
}

执行任务

在loop函数中开启所有的context运行，利用条件变量阻塞当前线程，等待所有任务完成：

auto scheduler::loop_impl() noexcept -> void
{
    for (int i = 0; i < m_ctx_cnt; i++) {
        m_ctxs[i]->set_try_stop([]() {
            // 设置空函数体, context不会自己停止
            return;
        });
    }
    for (int i = 0; i < m_ctx_cnt; i++) {
        m_ctxs[i]->start();
    }
    {
        std::unique_lock<std::mutex> lock(m_mux);
        m_cv.wait(lock, [this]() {
            return m_task_cnt.load(std::memory_order_relaxed) == 0;
        });
    }
    // 所有任务完成, 统一发送停止信号
    stop_impl();
}

所有任务完成后，告知所有context，任务结束：

auto scheduler::stop_impl() noexcept -> void
{
    for (int i = 0; i < m_ctx_cnt; i++)
    {
        m_ctxs[i]->notify_stop();
    }
    for (int i = 0; i < m_ctx_cnt; i++) {
        m_ctxs[i]->join();
    }
}

c++20协程入门

Fri, 14 Nov 2025 22:00:00 GMT

c++20协程入门

前置语法

一个函数体内如果有下面三个关键字的任意一个将被视为协程

co_await，co_yield，co_return

协程无法直接使用void/int/vector<string>这样的形式作为函数的返回类型，而是返回Task（一个由用户自定义的类），并指定其promise_type（通过以下方式）：

class Task {
    ...
};
class promise1 {
    ...
};
struct std::coroutine_traits<Task> {
    // promise1也由用户自定义，但需要满足一些规范
    using promise_type = promise1; 
};

或者下面的方式：

class promise1 {
    ...
};
class Task {
public:
    using promise_type = promise;
    ...
};

实现Task和promise_type完毕后，利用如下语法编写一个协程函数：
```
Task run(int a, int b) {
    int c = a + b;
    co_return;
}
```
协程函数的调用者在调用协程函数之后可以拿到协程的返回值：
```
int main () {
    auto task = run(1, 2);
}
```
这里task变量是上面定义的Task类型，通过该变量，我们可以在main函数中与协程交互（如让协程恢复执行，获取结果等）

协程的创建与销毁

流程

协程函数与普通函数不同：

普通函数调用即：跳转到函数入口—执行—返回

协程函数则由编译器在某些阶段做了一些准备工作：函数调用后到用户定义代码执行前， 用户定义代码返回后到函数结束前

具体如下面的代码所示：

T some_coroutine(P param)
{
  // 为协程帧分配内存，如果 promsie 存在内存分配重载则利用 promise 的内存分配函数
  auto* f = new coroutine_frame(std::forward<P>(param));

  // returnObject即Task对象, 会在协程第一次陷入 suspend 状态后通过语句`return returnObject`返回给调用者
  auto returnObject = f->promise.get_return_object();

  // 控制协程创建时的调度逻辑
  co_await promise.initial_suspend();
    
  // 用户定义代码执行前
  try
  {
    // 用户在协程函数体内定义的逻辑
    <body-statements>
  }
  catch (...)
  {
    // 处理协程运行中抛出的异常
    promise.unhandled_exception();
  }
  // 用户定义代码返回后

FinalSuspend:
  // 控制协程结束时的调度逻辑
  co_await promise.final_suspend();
  // 清理工作, 比如释放先前创建的协程帧
  clean code;
}

https://en.cppreference.com/w/cpp/language/coroutines.html

从编译器视角揭秘 C++ 协程 | tinyCoroLab Docs

下面会从以下几个根据协程的调度阶段，一个一个介绍上述执行流程的部分：

coroutine frame
promise结构
co_await，co_return语义

协程的创建

协程函数运行之前的准备工作

从下面这个简单的协程函数开始，一步一步查看协程是如何创建的：

Task run(int a, int b) {
    int c = a + b;
    co_return;
}
int main() {
    auto task = run(1, 2);
}

当main函数调用run时，run函数不会像普通函数那样直接一路执行下去，编译器在函数体内部做了某些准备工作：

创建协程帧(co_frame)：

由于c++中是无栈协程（有栈的概念可以参考线程栈，指每创建一个协程，就有自己的栈区来支配），其运行依靠系统栈，但协程本身可以被暂停和恢复运行（此时系统栈的变化类似多次函数调用和结束），为了保存函数体内的变量，需要动态开辟内存空间，将一些数据存到堆区。

上述步骤由编译器自动生成代码执行，协程帧由一些变量来组成，包括run的函数参数，run中创建的局部变量，恢复执行后下一条要执行的指令地址（只是为了容易理解，实际存储的并不一定是这个，但仍然与指令地址具有相同的效果），以及promise_type对象，其中最重要的是promise_type对象，它与协程的生命周期绑定，并可以通过其来控制协程的行为
生成Task对象，执行第一次调度：

这一步由promise_type的函数实现，promise_type是一个需要用户实现的接口，形式如下：
```
class promise_type
{
 friend class Task;
public:
 promise_type(){}
 Task get_return_object()
 {
 return Task{std::coroutine_handle<promise_type>::from_promise(*this)};
 }
 constexpr std::suspend_always initial_suspend() { return {}; }
 
 /*
 void return_void() {}
 void unhandled_exception() {}
 constexpr std::suspend_always final_suspend() noexcept { return {}; }
 */
};
```
注释里的内容暂时不需要关注，编译器在构造了协程对应的promise_type对象后，按顺序：
1. 执行promise_type.get_return_object()函数：
 - 通过promise_type对象来构建协程句柄（coroutine_handle，可以理解为一个指针，指向协程帧）
 - 使用协程句柄构建一个Task对象（Task类需提供对应的构造函数），该Task对象将作为协程函数的返回值，在协程第一次进入暂停（suspend）状态时被自动返回
 在代码中，执行auto task = run(1, 2);后，task变量就是该Task对象，通过该对象，main函数中可以利用Task类定义的方法简单的操作协程（恢复协程执行，获取结果等等）
2. 执行co_await promise_type.initial_suspend()：
 
 该函数应返回一个Awaitable对象，关于Awaitable和Awaiter，两者关系如下图所示，std::suspend_always和std::suspend_never都属于Awaiter：
3. 返回Awaitable对象后，进入暂停—恢复流程，决定当前协程是否会立即运行，比如上面的promise_type中返回std::suspend_always，那么此时协程会立即暂停，并将自己的状态更新到协程帧中，然后将控制权交给调用者main函数，此时main函数继续执行
4. main函数拿到了可以和协程交互的对象task，但代码中并不恢复协程，那么就会直接退出程序
5. task被析构
**协程是如何根据suspend_always来把控制权交还给main函数的？**其实很简单，创建协程时除了会在堆区创建协程帧，也会像普通函数一样创建函数栈帧：

只不过在run函数执行到其函数体的第一条语句之前，编译器就检查到std::suspend_always需要让协程暂停，此时会执行类似函数内return的指令，run frame被pop，回到main frame中对应位置执行，控制权就自然而然的交回给main函数了，至于如何恢复协程的执行，会在之后的篇幅进行讲解

而如果initial_suspend返回的是std::suspend_never，run frame会保留，协程就会立即执行

协程的销毁

co_return

当run函数执行到co_return语句时，协程的逻辑执行已经完成，接下来需要主动或被动的释放协程资源（主要是协程帧的销毁）

与协程的创建类似，执行co_return语句时，会触发一系列明确的收尾动作：

class promise_type
{
    friend class Task;
public:
    /*
    promise_type(){}
    Task get_return_object()
    {
        return Task{std::coroutine_handle<promise_type>::from_promise(*this)};
    }
    constexpr std::suspend_always initial_suspend() { return {}; }
    */
    
    void return_void() {}
    void unhandled_exception() {}
    constexpr std::suspend_always final_suspend() noexcept { return {}; }
};

流程如下：

设置最终结果：

co_return;会自动调用promise_type.return_void()，这将会通知Promise对象协程已经正常结束，但没有返回值

如果需要协程返回值该怎么做？ 在promise_type类中增加一个void return_value(T v)函数和成员变量val，利用val保存v，同时co_return;变为co_return v;即可

注意：一个promise_type类中无法同时实现return_value和return_void函数

如果协程因为一个未捕获的异常而终止会怎么样？

编译器会自动调用promise::unhandle_exception()函数来存储异常信息，等待后续逻辑处理
跳转到FinalSuspend标号处，执行co_await promise_type.final_suspend()

与创建时co_await initial_suspend()类似，由编译器主动调用，函数的返回结果也是一个Awaitable对象，这个对象将直接决定协程接下来的行为，仍以std::suspend_always和std::suspend_never为例做介绍：
- 该函数返回std::suspend_always()：根据上面的介绍，返回这个对象代表着协程当前要暂停，并将执行权转移给调用者（caller），此时堆中创建的协程帧仍然存在，如果调用者之后不主动恢复该协程（大部分情况都不会再恢复，因为此时协程的逻辑生命已经结束了）或者不主动调用协程句柄的destroy()函数，将会出现内存泄露
 
 如何主动释放协程帧？
 
 答案是：协程句柄，其应与Task绑定
```
class Task {
 // ...
 std::coroutine_handle<promise_type> handle;
	Task(std::coroutine_handle<promise_type> h) : handle(h) {}
 ~Task() {
 if (handle) {
 // 协程帧还存在的话，就销毁
 handle.destroy();
 }
 }
};
```
 在上面的代码中，std::coroutine_handle<promise_type>在Task类中定义一个与promise_type类绑定的协程句柄，该协程句柄由promise_type::get_return_object()设置值
 
 在析构函数中检查句柄的有效性，并使用destroy()主动释放协程帧
 
 关于std::coroutine_handle和协程句柄的更详细的知识，将在之后进行介绍
 
 这样，在协程逻辑上退出之后，借由返回的Task对象，就能主动释放协程所占的资源
- 该函数返回std::suspend_never()，根据上面的介绍，返回这个对象代表着协程当前不会暂停，会继续执行，而当前协程已经运行到函数体末尾，在函数体的末尾之后，是编译器自动生成的清理代码（cleanup code），这部分代码负责析构所有局部变量并释放协程帧的内存。
 
 所以，协程的销毁与否，完全取决于执行流有没有机会执行到那段清理代码。
 
 但是，
 
 这是一个危险的选项，尤其是其绑定的task对象还存活的时候
 - 如果 co_return 之后，调用者仍然尝试使用协程句柄（例如，通过Task对象），这将立即导致悬垂指针和未定义行为。

协程的恢复

std::coroutine_handle

操控协程的句柄，其类似一个指针，指向一个协程帧，并向用户暴露操控对应协程的接口

std::coroutine_handle是一个类模板，有两种形式：

std::coroutine_handle<>：是对所有协程类型进行类型擦除后的版本，能表示任何协程句柄
std::coroutine_handle<promise_type<return_type>>：只能表示promise_type<return_type>对应的协程句柄

成员函数

static

from_promise(promise_type &p)：从promise_type对象中创建一个协程句柄。

该函数返回一个类型为std::coroutine_handle<promise_type<return_type>>的协程句柄，但std::coroutine_handle<>类并不具有此静态函数，无法调用该函数
from_address(void* ptr)：从协程帧地址中创建一个协程句柄

std::coroutine_handle<>和std::coroutine_handle<promise_type>类都有该函数，返回的句柄类型也与调用时的类类型相同

通常需要使用另一个协程句柄传入地址来构建新的协程句柄，不太常用

non-static

done()：判断协程是否结束，返回true或false，判断条件是协程是否在最终挂起点处暂停（即promise_type.final_suspend()）
resume()：使该协程句柄所代表的协程继续运行
destroy()：销毁该协程句柄所代表的协程（协程句柄done()必须为true）
promise()：返回该协程内部promise_type对象的引用（std::coroutine_handle<>类没有该函数）
address()：返回协程句柄对应的协程帧的地址

总之，c++通过std::coroutine_handle为用户提供了操作一个协程的接口，方便操作协程

其通常作为Task类的成员变量存在

一个简单的协程案例

了解了协程的创建和销毁，就可以创建一个简单的协程来模拟一个普通的函数：

#include <coroutine>
#include <exception>
#include <iostream>
#include <ostream>

class Task {
public:
    class promise_type; // 前向声明
    using coroutine_handle = std::coroutine_handle<promise_type>;
    class promise_type {
    public:
        // 必须实现
        Task get_return_object()
        {
            return Task { coroutine_handle::from_promise(*this) };
        }
        // 必须实现
        std::suspend_always initial_suspend() { return {}; }
        // 必须实现
        void unhandled_exception()
        {
            ex = std::current_exception();
        }
        // void 和 value选一种实现
        // void return_void() { }
        void return_value(int res) { res_ = res; }
        // 必须实现 并置为noexcept
        std::suspend_always final_suspend() noexcept { return {}; }

    public:
        std::exception_ptr ex;
        int res_;
    };

public:
    Task()
        : handle_(nullptr)
    {
    }
    explicit Task(coroutine_handle handle)
        : handle_(handle)
    {
    }
    ~Task()
    {
        if (handle_) {
            handle_.destroy();
        }
    }
    bool resume()
    {
        if (!handle_.done()) {
            handle_.resume();
        }
        return !handle_.done();
    }
    int result()
    {
        return handle_.promise().res_;
    }

private:
    coroutine_handle handle_;
};
Task add(int x, int y)
{
    int z = x + y;
    co_return z;
}
int main(int argc, char const* argv[])
{
    auto task = add(1, 2);
    task.resume();
    std::cout << "call coroutine add, result is " << task.result() << std::endl;
    return 0;
}

目前来看，创建一个普通函数所花费的功夫貌似比创建一个协程要小的多，那么为什么还要使用协程？后面会继续介绍c++协程中最重要的关键字co_await

co_await

在之前介绍的协程中创建和销毁中，刻意省略了一些过程，这些过程都与co_await相关：

co_await promise_type.initial_suspend();
co_await promise_type.final_suspend();

co_await和协程的调度相关联，和之前的Awaitable对象共同掌管着一个协程的暂停和恢复

co_await语义

co_await的语法是：co_await <expr>

co_await关键字用于暂停协程，其中<expr>必须是或返回一个Awaitable对象

在调用协程函数时，编译器为我们隐式执行了co_await promise_type::initial_suspend();

在协程co_return时，编译器也会隐式执行co_await promise_type::final_suspend();

在co_await <expr>时，编译器会展开该语句，执行跟Awaitable对象相关的固定流程：

{
	auto&& value = <expr>;
    // 伪代码, 获取awaitable和awaiter
 	auto&& awaitable = get_awaitable(promise, static_cast<decltype(value)>(value));
 	auto&& awaiter = get_awaiter(static_cast<decltype(awaitable)>(awaitable));
	// 跟awaiter相关的执行流程
  	if (!awaiter.await_ready()) {
	    using handle_t = std::coroutine_handle<P>;

    	using await_suspend_result_t =
      	decltype(awaiter.await_suspend(handle_t::from_promise(promise)));

    	// 在该处协程准备陷入 suspend 状态，编译器生成代码来保存协程当前的运行状态
    	<suspend-coroutine>

    	if constexpr (std::is_void_v<await_suspend_result_t>) {
            awaiter.await_suspend(handle_t::from_promise(promise));
            <return-to-caller-or-resumer>
    	}
    	else {
        	// 这里暂不考虑返回 std::coroutine_handle 的 await_suspend
            static_assert(
                std::is_same_v<await_suspend_result_t, bool>,
                "await_suspend() must return 'void' or 'bool'.");

            if (awaiter.await_suspend(handle_t::from_promise(promise))) {
                <return-to-caller-or-resumer>
            }
        }
        // 协程陷入 suspend 状态后恢复会从该处开始执行而不是从<suspend-coroutine>处
		<resume-point>
    }
	return awaiter.await_resume();
}

Awaiter

从协程的创建中，应大致了解了Awaiter对象和Awaitable对象的关系，现在将协程的创建与std::suspend_always与co_wait关联起来介绍：

std::suspend_always是一个Awaiter对象：

一个Awaiter对象要求实现以下三个函数**（都必须声明为noexcept）**：

await_ready()：字面意思，指执行co_await awaiter;语句的协程是否能够继续运行，true代表可以，否则进入suspend_point
await_suspend(coroutine_handle<>)：参数coroutine_handle<>指的是执行了co_await std::suspend_always的协程（这一点很重要），并执行协程暂停前的一些准备工作，调用该函数后，编译器会生成相应代码来暂停协程
await_resume()：恢复上一步suspend的协程，可以在此处做一些恢复的动作（如准备返回值），调用该函数，编译器会生成相应代码来恢复协程

struct awaiter
{
    bool await_ready() noexcept;
    void await_suspend(coroutine_handle<>) noexcept;
    void await_resume() noexcept;
};

在编译器生成的代码中，其工作流程如下，其中，await_suspend()有三种返回值，编译器根据返回值类型的不同，会做不一样的动作：

void await_suspend(std::coroutine_handle<>) noexcept ：调用完毕后立即暂停入参指向的协程
bool await_suspend(std::coroutine_handle<>) noexcept：

返回true则暂停入参指向的协程

返回fasle则继续运行入参指向的协程（仍然需要经过await_resume逻辑）
std::coroutine_handle<> await_suspend(std::coroutine_handle<>) noexcept：挂起入参指向的协程，并恢复返回值指向的协程的运行

if (!awaiter.await_ready()) {
    // 编译器会在这里准备挂起，并拿到当前协程的句柄 `h`
    // std::coroutine_handle<> h = /* ... get current handle ... */;

    // 调用 await_suspend(h)，并根据其返回值决定下一步
    // --- 情况 A: await_suspend 返回 void ---
    if constexpr (std::is_void_v<decltype(awaiter.await_suspend(h))>) {
        awaiter.await_suspend(h);
        // 编译器魔法: 保存当前所有状态，挂起协程，将控制权返回给调用者/恢复者
        COMPILER_SAVE_STATE_AND_SUSPEND(); 
        // 当协程被 .resume() 时，将从这里继续执行
        :resume_label1; 
    }

    // --- 情况 B: await_suspend 返回 bool ---
    else if constexpr (std::is_same_v<decltype(awaiter.await_suspend(h)), bool>) {
        if (awaiter.await_suspend(h)) { // 如果返回 true
            // 编译器魔法: 同上，挂起协程
            COMPILER_SAVE_STATE_AND_SUSPEND();
            :resume_label2;
        }
    }

    // --- 情况 C: await_suspend 返回另一个协程句柄 ---
    else if constexpr (std::is_convertible_v<decltype(awaiter.await_suspend(h)), std::coroutine_handle<>>) {
        auto next_coro_to_run = awaiter.await_suspend(h);
        // 编译器魔法: 对称转移。挂起当前协程，并立即调度 next_coro_to_run 恢复执行
        COMPILER_PERFORM_SYMMETRIC_TRANSFER(next_coro_to_run);
        :resume_label3;
    }
}

// 调用 await_resume() 获取最终结果
// (如果表达式有返回值的话)
// ValueType result = awaiter.await_resume();
awaiter.await_resume(); // 如果返回 void

所谓注释中的当前协程的句柄：简单理解为调用co_await awaiter;的那个协程

介绍了awaiter接口后，再看std::suspend_always的代码：
```
struct suspend_always
{
 constexpr bool await_ready() const noexcept { return false; }
 constexpr void await_suspend(coroutine_handle<>) const noexcept {}
 constexpr void await_resume() const noexcept {}
};
```
根据1中介绍的流程，co_await std::suspend_always{}：
- 调用await_ready()，结果为fasle
- 然后调用await_suspend()，返回值为void
- 保存协程状态，挂起协程，将控制权返回给调用者**（指协程函数的调用者，不是await对象方法的调用者）**

用户可以构建自己的awaiter类，只要实现了以上三个函数即可（都要标记为noexcept）

Awaitable

将一个对象称为可Awaitable，当且仅当其满足了以下三个条件中的一个：

实现了await_ready()，await_suspend(std::coroutine_handle<>)，await_resume()三个函数
重载了operator co_await()运算符，并令其返回一个Awaiter对象
实现了await_transform成员函数

为task实现operator co_await()

上面阐述了co_await是如何与awaiter协同工作的，但我们更多的时候需要让co_await后跟另一个协程函数，即：

Task func1() {
    std::cout << "func1()" << endl;
    co_return 1;
}

Task func2() {
    co_await func1();
    std::cout << "func2()" << endl;
    co_return 2;
}

那就可以考虑在Task类中实现co_await()运算符：

实现一个最简单的operator co_await()：

class Task {
public:
    class promise_type; // 前向声明
    using coroutine_handle = std::coroutine_handle<promise_type>;
    class promise_type {
    /* ... */
    };

public:
    /*...*/
    std::suspend_always operator co_await() {
      return std::suspend_always{};
    }
    /*...*/

private:
    coroutine_handle handle_;
};

自定义awaiter，在父协程调用子协程时，挂起父协程，运行子协程：

class Task {
public:
    class promise_type; // 前向声明
    using coroutine_handle = std::coroutine_handle<promise_type>;
    class promise_type {
    /* ... */
    };
public:
    struct awaiter {
        awaiter() : handle_(nullptr) {}
        explicit awaiter(coroutine_handle handle) : handle_(handle) {}
        bool await_ready() const noexcept {return false;}
        coroutine_handle await_suspend(std::coroutine_handle<> coroutine) noexcept {
            return handle_;
        }
        int await_resume() noexcept {return handle_.promise().res_;}
        std::coroutine_handle<promise_type> handle_;
    };
public:
    /*...*/
    awaiter operator co_await() {
      return awaiter{handle_};
    }
    /*...*/

private:
    coroutine_handle handle_;
};

理解operator co_await()

以func2()中co_await func1()为例（为避免混淆，我将func2()对应的返回值称为Task2，将func1()对应的返回值称为Task1）：

auto&& value = <expr>;
// 伪代码, 获取awaitable和awaiter
auto&& awaitable = get_awaitable(promise, static_cast<decltype(value)>(value));
auto&& awaiter = get_awaiter(static_cast<decltype(awaitable)>(awaitable));

编译器会执行类似上面伪代码形式的流程，具体的：

执行func1()，进行协程的创建：

auto* f = new coroutine_frame(std::forward<P>(param));
auto Task1 = f->promise.get_return_object();
co_await promise.initial_suspend(); // 将Task返回

调用Task1中的operator co_await()，获取返回的awaiter
执行co_await awaiter;

add协程实例：

Task add(int x, int y, int id)
{
    std::cout << "enter coroutine " << id << std::endl;
    int z = x + y;
    if (id == 2) {
        std::cout << "coroutine " << id << " will return\n";
        co_return z;
    }
    z += co_await add(y, 30, id + 1);
    std::cout << "coroutine " << id << " will return\n";
    co_return z;
}
int main(int argc, char const* argv[])
{
    auto task = add(1, 2, 1);
    task.resume();
    std::cout << "call coroutine 1 add, result is " << task.result() << std::endl;
    return 0;
}

在add函数里执行了加法，但是结果没有传入result中，从输出来看，嵌套的协程2正常返回了，但是main函数调用的协程1没有正常返回，解释如下：

在执行task = add(1, 2, 1)后，main函数主动恢复协程1运行，此时堆区和main线程栈区如下：
当协程1执行了co_await add(y, 30, id + 1)后：

协程1暂停，并返回协程2的句柄，这样协程2将会继续从上一次暂停中恢复运行（从initial_suspend()处恢复运行，直到co_return返回一个std::suspend_always暂停了协程2
在暂停协程2后，理应将执行权交给逻辑上的调用者（即协程1），但这里并没有，原因是：在协程2调用co_return后，执行的final_suspend()只是暂停了当前的协程，那么协程2的栈帧被pop，执行权将交给栈中的前一个栈帧（即main栈帧），从main栈帧继续执行

要注意的是，此时堆上的协程2的协程帧并没有被释放，因为它被暂停了，还没有执行清理代码
main中没有再主动恢复协程1，协程1不会运行，main结束后，先执行了协程1对应的Task1对象的析构函数，在销毁协程1帧时，协程2对应的Task2对象作为协程1帧的一部分，也会调用Task2对象的析构函数，由此来完成对两个协程帧的释放

至此，c++20中的协程的基本运行流程介绍完毕，但想要使用协程来执行异步操作，还需要将其封装成库，并将其调用封装成普通函数那样的执行顺序

javaweb 笔记

Mon, 20 Oct 2025 00:00:00 GMT

javaweb

maven

管理jar包
跨平台构建
标准化目录结构

配置

下载地址Download Apache Maven – Maven，解压目录不要有中文

apache-maven-xxx/conf/settings.xml修改：

<!--找到localRepository， 添加本地仓库地址-->
<localRepository>xxx\apache-maven-3.9.11\repo</localRepository>

<!--mirrors 标签中新增标签mirror，为阿里云-->
<mirror>
    <id>alimaven</id>
    <name>aliyun maven</name>
    <url>http://maven.aliyun.com/nexus/content/groups/public/</url>
    <mirrorOf>central</mirrorOf>
</mirror>

apache-maven-xxx/bin添加到环境变量中

idea集成

创建maven项目

setting->Build...->Build Tools->Maven

修改maven home path为maven根目录
修改setting file为setting.xml文件
修改Local repository为设置的本地仓库文件夹

创建空项目后，新创建module，build system选择maven即可

maven坐标

<groupId>org.example</groupId>
<artifactId>maven-project01</artifactId>
<version>1.0-SNAPSHOT</version>

groupId：项目隶属组织名称（域名反写）
artifactId：项目名称
version：项目版本号

这三项在后面配置依赖时会用到

导入maven项目

将文件夹复制到空项目中
File->Project Structures->Modules->+->import module->选择文件夹中的pom.xml文件

依赖管理

依赖

依赖下载官网

在<dependencies>标签下增加<dependency>标签，然后刷新xml文件即可

<dependencies>
    <!-- https://mvnrepository.com/artifact/org.springframework/spring-context -->
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context</artifactId>
        <version>6.1.4</version>
    </dependency>
</dependencies>

排除依赖

在对应的<dependecy>标签内增加<exclusions>标签：

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <version>6.1.4</version>
    <!--排除依赖-->
    <exclusions>
        <exclusion>
            <groupId>io.micrometer</groupId>
            <artifactId>micrometer-observation</artifactId>
        </exclusion>
    </exclusions>
</dependency>

依赖范围

在<dependency>标签内的maven坐标下添加<scope>标签，标签值和作用如下：

Y表示可以使用，-表示不行

比如<scope>test</scope>表示让某一个依赖包只能在项目的test包下使用，其他包不能使用

生命周期

三个周期相互独立

clean：清除之前编译的结果
default：编译->测试->打包->安装（执行后一个前会先执行前一个）
site：上线

直接在idea的maven面板中的LifeCycle运行或者在模块目录下运行以下命令：

mvn [clean/compile/test/pacakge/install]

JUnit（单测）

使用

pom.xml添加依赖：

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>5.9.1</version>
</dependency>

类名：xxxTest

位置：test/java/com.xxxx/xxxTest

方法：必须是public void，加上注解@Test

public class MainTest {
    @Test
    public void test() {
        
    }
}

断言

在Assertions包，最后一个参数通常设置为错误提示信息（String）

文档：Assertions (JUnit 5.0.1 API)

常见注解

环境准备和销毁

@BeforeAll：方法必须为static，通常作为setup初始化资源，在所有测试启动前仅运行一次
@AfterAll：方法必须为static，通常用于释放资源，在所有测试完成后仅运行一次
@BeforeEach：通常作为setup初始化资源，在每个测试启动前都运行一次
@AfterEach：通常用于释放资源，在每个测试完成后都运行一次

参数化测试

同时使用下面两个注解：

@ParameterizedTest：标识方法会使用多个参数进行测试
@ValueSource([])：在()内添加一个数组来指明使用的参数

设置测试名

@DisplayName("xxx")：显示测试类/方法名为"xxx"

Spring Boot

创建

idea可以自动化配置spring boot：

new module->Spring Boot->Type: Maven->设置项目名与jdk版本->next

->选择Spring boot版本->Dependency:Web:Spring Web

启动入口

main/java/xxx/SpringbootxxxApplication中的main方法，带有@SpringBootApplication注解

请求注解

@RestController：类注解，标识其是一个请求处理类
@RequestMapping("")：方法注解，填写对应的请求路径，标识其是该请求路径对应的处理方法

@RestController
public class HelloController {
    @RequestMapping("/hello")
    public String Hello(String name) {
        System.out.println("name: " + name);
        return "Hello " + name + "~";
    }
}

HTTP

无状态，不同请求之间相互独立
一次请求对应一次响应，请求和响应都由 行/头/体组成
基于TCP

spring boot处理请求

内置的tomcat web服务器会将http文本封装为HttpServletRequest对象，在使用时可以直接将其作为函数参数：

String method = request.getMethod();	// get/post
String url = request.getRequestURL().toString();	// http://localhost:8080/request
String uri = request.getRequestURI();	// request
String protocol = request.getProtocol();	// HTTP/1.1
String name = request.getParameter("name");	// 
String age = request.getParameter("age");
// 获取请求头参数
String accept = request.getHeader("accept");
String contentType = request.getHeader("content-type");

响应码

1xx：响应中，临时状态码
2xx：成功
3xx：重定向
4xx：客户端错误
5xx：服务端错误

spring boot返回响应

用HttpServletResponse对象来设置：

response.setStatus(HttpServletResponse.SC_OK);
response.setHeader("name", "1");
response.getWriter().write("<h1>hello response</h1>");

使用ResponseEntity对象来链式设置

@RequestMapping("/response")
public ResponseEntity<String> response(HttpServletRequest request) {
    return ResponseEntity
        .status(401)
        .header("Access-Control-Allow-Origin", "*")
        .body("");
}

一般不手动设置响应状态码和响应头

三层架构

Controller（控制层）：接受请求、响应数据
Service（业务逻辑层）：处理具体的业务逻辑
dao（数据访问层）：负责数据访问（增删改查...）

架构：

--controller
	--xxxController.java
--dao
	--impl
		xxxDaoImpl.java
	xxxDao.java
--service
	--impl
		xxxServiceImpl.java
	xxxService.java
Application.java

其中，impl存接口实现，xxxDao存的是接口，service同理

controller直接使用service的功能，将请求数据解析后调用service处理业务逻辑
service直接使用dao的功能，在处理业务逻辑时涉及数据的增删改查，最后将数据返回给controller
dao负责提供数据增删改查的接口，一般和model（模型），数据库关联
controller在调用完service完成业务逻辑处理后，将数据封装一层作为相应的数据返回给客户端

分层解耦

为了解决在Controller中主动new Service对象和在Service中主动new Dao对象导致的不方便改变接口实现的问题

通过Spring boot框架提供的Bean对象来解决上述问题**（Bean对象是容器中创建和管理的对象）**

控制反转（IOC）

将对象的创建控制权转移给外部容器

依赖注入（DI）

容器为应用程序提供运行时所依赖的资源

解决方案1

使用@Component和@Autowired注解：

被@Component标注的类，在组件扫描路径内时，会被 Spring 扫描、实例化并注册为 Bean，由容器统一管理生命周期
被@Autowired标注的依赖，Spring 会在 Bean 初始化阶段根据类型（必要时根据名字或@Qualifier）从容器中查找合适的 Bean 注入进去

// IOC: 将对象交给容器管理
@Component
public class UserDaoImpl implements UserDao {
    ...
}

// DI: 从容器中取对象
@Component
public class UserServiceImpl implements UserServcie{
    @Autowired
    private UserDao userDao;
}

// DI: 从容器中取对象
@RestController
public class UserController {
    @Autowired
    private UserDao userDao;
}

解决方案2

@Repository
public class UserDaoImpl implements UserDao {
    ...
}

@Serivce
public class UserServiceImpl implements UserService {
    @Autowired
    private UserDao userDao;
}

@RestController
public class UserController {
    @Autowired
    private UserDao userDao;
}

@Repository和@Service细化了@Component注解，controller一般只设置@RestController注解，因为其包含了@Controller

DI详解

基于@Autowired注解的三种注入：

在变量名上添加：
```
@Autowired
private UserDao userDao;
```

构造函数上添加：

@Serivce
public class UserServiceImpl implements UserService {
    private final UserDao userDao;
    @Autowired
    UserServiceImpl(UserDao userDao) {
        this.userDao = userDao;
    }
}

设置set方法（省略，一般用前两种）

@Autowired默认按照类型注入，即如果有多个类实现了同一个接口，bean对象就不知道该保存哪个类型，从而报错，解决方案如下：
- 使用@Primary注解表明哪个类是主要实现的类
```
@Primary
@Repository
public class UserDaoImpl implements UserDao {
    ...
}
```
- 要使用不同的实现：使用@Qualifier注解变量或构造函数表明使用哪个实现类
```
@Autowired
@Qualifier("userDaoImpl")
private UserDao userDao;
```
- 使用@Resource注解变量表明使用的实现类的名称（不是Spring框架的提供，推荐使用第二个实现）
```
@Resource(name = "userDaoImpl")
private UserDao userDao;
```

配置文件

将原来的.property文件换为.yml文件（键值对配置）

spring:
  applicaiton:
    name: springboot-mybatis-quickstart
  datasource:
    type: ..
    url: ..
    driver-class-name: ..

同缩进同级
键和值之间有一个空格

测试

测试类要在引导程序同包或子包下，同时对类添加@SpringBootTest注解

MYSQL

连接

mysql -u{username} -p [-h{ip} -P{port}]

{username}：要填的用户名，自用填root
{ip}：远程数据库的ip地址
{port}：远程数据库的端口

SQL基本操作

DDL/DML/DQL/DCL（定义/操作/查询/控制）

DLL

定义数据库对象（数据库，表，字段）

数据库操作

-- 查询数据库
show database;
-- 创建指定数据库
create database dbname;
-- 删除指定数据库
drop database dbname;
-- 查看数据库表
select database();
-- 使用指定数据库
use dbname;

表操作

-- 创建表 []代表可选项
create table tablename(
    字段1 字段类型 [约束] [comment 注释],
    ...
)[comment 表注释]

约束：
- 非空not null
- 唯一unique
- 主键primary key
- 默认default 跟一个值，表示字段默认值
- 外键foreign
- 自增auto increment
数据类型：
- 数字：tinyint，int，bigint
- 字符串：char（固定），varchar（不固定）
- 日期：date，datetime

-- 查看当前数据库所有表
show tables;
-- 查看表的所有字段
desc tablename;
-- 查询建表语句
show create table tablename;
-- 向表中增加，修改，重命名，删除字段以及重命名表名
alter table tablename add 字段 类型 [comment] [约束];
alter table tablename modify 字段 类型;
alter table change 旧字段名 新字段名 类型 [comment] [约束];
alter table tablename drop column 字段;
alter table tablename rename to 表名;
-- 删除表
drop table [if exists] tablename;

DML

插入

insert into tablename(字段1， 字段2) values (值1 ，值2);
insert into tablename values (值1， 值2);
-- 可叠加

更新

update tablename set 字段1 = 值1, 字段2 = 值2, ... [where ...]
-- 不加where条件表示更新所有行

删除

delete from tablename [where ...]
-- 不加where会删除所有行

DQL

select 
	-- distinct 去重
	[distinct] 字段 [AS 别名1] 
from
	tablename
where
	-- 比较 <, >, =, !=, between ... and, in(...), like _/%, is null
	-- 逻辑 &&, ||, !
	条件
group by
	-- 聚合函数 count(), max(), min(), avg(), sum(), select用
	-- 使用group by, 前面的select只能选择分组的字段或者聚合函数
	分组字段
having 
	-- 解决where后不能跟聚合函数的问题
	分组后条件列表
order by
	-- 默认asc升序排序, 要降序需指明desc
	排序字段列表 [asc]	
limit
	-- 如0, 5表示查出来的结果从第0条开始展示，最多展示5条, 第一个参数为0可以省略
	起始索引, 查询记录数

JDBC

一套接口，由数据库厂商实现，比如使用mysql要引入对应的jar包：

<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <version>8.0.33</version>
</dependency>

简单使用：

// 1. 注册
class.forName("com.mysql.cj.jdbc.Driver");
// 2. 连接
String url = "jdbc:mysql://localhost:3306/dbname";
String username = "root";
String password = "123456";
Connection conn = DriverManager.getConnection(url, username, password);
// 3. 获取sql执行对象
Statement statement = connection.createStatement();
// 4. 执行语句, i是执行语句后影响的行数
int i = statement.executeUpdate("update user set age = 25 where id = 1");
// 5. 释放连接
statement.close();
conn.close();

预编译执行查询

String sql = "select id, username from user where username = ?";
pStatement = conn.prepareStatement(sql);
// 设置sql语句中的?占位符
pStatement.setString(1, "xxx");
// 执行语句, 得到结果集
resultSet = pStatement.executeQuery();
// 遍历结果集
while (resultSet.next()) {
    // getXxx: 可以输入列标号, 也可以输入列名
    resultSet.getInt("id");
}
resultSet.close();
pStatement.close();

防sql注入
数据库会缓存语句，然后对占位符?替换，性能更高

Mybatis

ORM（对象关系映射）框架，简化数据库操作，在这里是对JDBC的进一步封装，底层使用了连接池初始化了一定数量的连接来实现资源复用

配置

在项目application文件写入：

spring.datasource.url=jdbc:mysql://localhost:3306/dbname
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
spring.datasource.username=root
spring.datasource.password=1234

使用方法

新建mapper包（代替三层架构中的dao层），定义Mapper接口，使用@Mapper注解

注解

在Mapper接口的方法中加入@Select()，@Update()，@Insert()，@Delete()注解，并填入SQL语句，以实现对应的功能

框架会在程序运行时自动为接口创建一个实现类对象（代理对象），并将该对象存入IOC容-

以查询为例：

@Mapper
public interface UserMapper {
    // #{} 在实际执行时会被替换为 ?
    // 当函数有多个参数时需要使用@Param注解为对应的参数起名， 且与#{}中一致
    @Select("select * from user where username = #{username} and password = #{password}")
    public User findByUsernameAndPassword(@Param("username") String username, @Param("password") String password);
    
    // 查询结果会被自动封装到User实体类中
    // 多行结果可以使用List接收
}

XML映射文件

注解适合写一些简单的SQL语句，复杂的一般在XML文件中写

目录结构：

同包同名
xml文件的namespace属性为Mapper接口全限定名一致
xml文件的sql语句的id与Mapper接口中的方法名一致，并保持返回类型一致

xml文件中的SQL语句写法和注解相同，使用#{}来代表参数占位，由函数参数传入，如果有多个，就在函数参数上加入@Param注解来标明

RESTful

一种规范

URL定位资源
HTTP请求方法描述操作：
- GET：select
- DELETE：delete
- POST：insert
- PUT：update

实战

日志

使用logback包（springboot框架自带依赖）

配置文件

创建src/main/resources/logback.xml：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- 控制台输出 -->
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <!--格式化输出：%d表示日期，%thread表示线程名，%-5level：级别从左显示5个字符宽度  %msg：日志消息，%n是换行符 -->
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50}-%msg%n</pattern>
        </encoder>
    </appender>

    <!-- 日志输出级别 -->
    <root level="ALL">
        <appender-ref ref="STDOUT" />
    </root>
</configuration>

输出到控制台/文件：

<!-- 控制台输出 -->
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <!--格式化输出：%d 表示日期，%thread 表示线程名，%-5level表示级别从左显示5个字符宽度，%msg表示日志消息，%n表示换行符 -->
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50}-%msg%n</pattern>
    </encoder>
</appender>
<!-- 按照每天生成日志文件 -->
<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
        <!-- 日志文件输出的文件名, %i表示序号 -->
        <FileNamePattern>D:/tlias-%d{yyyy-MM-dd}-%i.log</FileNamePattern>
        <!-- 最多保留的历史日志文件数量 -->
        <MaxHistory>30</MaxHistory>
        <!-- 最大文件大小，超过这个大小会触发滚动到新文件，默认为 10MB -->
        <maxFileSize>10MB</maxFileSize>
    </rollingPolicy>

    <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
        <!--格式化输出：%d 表示日期，%thread 表示线程名，%-5level表示级别从左显示5个字符宽度，%msg表示日志消息，%n表示换行符 -->
        <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50}-%msg%n</pattern>
    </encoder>
</appender>

开关配置

level可以为ALL，OFF，debug，info，warn，error

<!-- 日志输出级别 -->
<root level="ALL">
    <!--输出到控制台-->
    <appender-ref ref="STDOUT" />
    <!--输出到文件-->
    <appender-ref ref="FILE" />
</root>

使用日志

使用@Slf4j注解：

@Slf4j
public class DeptController {
    public Result list(){
		log.debug("");
        log.info("");
        log.warn("");
        log.error("");
        ...;
    }
}

响应结果封装

package com.itheima.pojo;

import lombok.Data;
import java.io.Serializable;

/**
 * 后端统一返回结果
 */
@Data
public class Result {

    private Integer code; //编码：1成功，0为失败
    private String msg; //错误信息
    private Object data; //数据

    public static Result success() {
        Result result = new Result();
        result.code = 1;
        result.msg = "success";
        return result;
    }

    public static Result success(Object object) {
        Result result = new Result();
        result.data = object;
        result.code = 1;
        result.msg = "success";
        return result;
    }

    public static Result error(String msg) {
        Result result = new Result();
        result.msg = msg;
        result.code = 0;
        return result;
    }

}

Controller

使用不同HTTP方法请求

在方法上增加@GetMapping注解，表示仅接受GET请求

// 两种注解都可以
// @RequestMapping(value = "/depts", method = RequestMethod.GET)
@GetMapping("/depts")

其他请求：

PostMapping
PutMapping
DeleteMapping

路由分组

（在Controller类上使用@RequestMapping注解，类中的所有方法都是以该路径为前缀）：

@RequestMapping("/depts")
@RestController
public class DeptController {
    ...
    // 相当于/depts/{id}
    @GetMapping("/{id}")
    public Result getInfo() {
        ...
    }
}

接收简单参数

参数形式：/xxx?id=1

使用@RequestParam注解

参数名（该参数名和方法参数名相同则可以省略）
required属性可设置为false，表示默认不需要该参数
defaultValue属性设置默认值

@DeleteMapping("/depts")
public Result deleteById(@RequestParam("id") Integer id) {
    System.out.println("根据id删除部门：" + id);
    return Result.success();
}

如果一次性传递的参数过多，可以将定义实体类封装，在接收参数时直接使用类对象接收（保证参数名和类成员名一致）：

// 请求参数类
@Data
public class EmpQueryParam {
    
    private Integer page = 1; //页码
    private Integer pageSize = 10; //每页展示记录数
    private String name; //姓名
    private Integer gender; //性别
    @DateTimeFormat(pattern = "yyyy-MM-dd")
    private LocalDate begin; //入职开始时间
    @DateTimeFormat(pattern = "yyyy-MM-dd")
    private LocalDate end; //入职结束时间
    
}

// 处理请求的方法, 使用类来接收传入的参数
@GetMapping
public Result page(EmpQueryParam empQueryParam) {
    log.info("查询请求参数： {}", empQueryParam);
    PageResult pageResult = empService.page(empQueryParam);
    return Result.success(pageResult);
}

接收Json数据

POST发送json数据：

{
    "name": "name"
}

使用@RequestBody注解，并指定实体对象来接收，json数据中的键名要和对象内部成员名对应

@PostMapping("/depts")
public Result add(@RequestBody Dept dept) {
    System.out.println("添加部门：" + dept.getName());
    deptService.addDept(dept);
    return Result.success();
}

接收路径参数

参数形式：/depts/1

使用@PathVariable注解（参数名和方法参数名相同可省略）：

@GetMapping("/depts/{id}")
public Result getInfo(@PathVariable("id") Integer id) {
    System.out.println("根据id查询部门数据：" + id);
    Dept dept = deptService.getInfo(id);
    return Result.success(dept);
}

Service

事务控制

本质是一组SQL操作的集合，要成功都成功，有一个失败就全部失败

-- 启动事务
start transaction; /begin;
insert ...
insert ...
-- 提交
commit;
-- 失败就回滚
rollback;

Spring的事务管理通常在Service层中，因为Dao层的操作都是针对单条SQL语句

使用@Transactional注解（业务层的方法，类，接口上都可以使用，范围从小到大分别是方法<类<接口）

事务管理日志配置（application.yml）：

#spring事务管理日志
logging: 
  level: 
    org.springframework.jdbc.support.JdbcTransactionManager: debug

异常回滚机制

一般只有RuntimeException（运行时异常）才会回滚事务

使用@Transactional(rollbackFor = Exception.class)可以指定出现何种异常类型时回滚事务（包括编译时异常）

@Transactional(rollbackFor = Exception.class)
public void doBusiness() throws Exception {
    ...
    throw new IOException("Checked Exception");
}

事务传播

一个事务里面执行另外一个事务时（比如service的一个方法调用另一个方法）

默认将新事务看做旧事务的一部分（新旧事务任一执行失败就全部失败）

在新事务上指定@Transactional(propagation = Propagation.REQUIRES_NEW)属性，原事务和新事务会被看做两个独立的事务

事务四大特性（ACID）

原子性（Atomicity）：事务是不可分割的最小单元，要么全部成功，要么全部失败。
一致性（Consistency）：事务完成时，必须使所有的数据都保持一致状态。
隔离性（Isolation）：数据库系统提供的隔离机制，保证事务在不受外部并发操作影响的独立环境下运行。
持久性（Durability）：事务一旦提交或回滚，它对数据库中的数据的改变就是永久的。

Dao

对查询结果进行数据封装

使用Mybatis查询返回的结果会被自动封装到定义的实体类中，但需要各个字段名一致，如果不一致，有如下三种解决办法：

使用@Results注解（column表示表列名，property表示实体类成员名）：

@Results({
    @Result(column = "create_time", property = "createTime"),
    @Result(column = "update_time", property = "updateTime")
})
@Select("select id, name, create_time, update_time from dept order by update_time desc")
List<Dept> findAll();

在SQL语句中为字段取别名（设置为实体类成员名）：

@Select("select id, name, create_time as createTime, update_time as updateTime from dept order by update_time desc")
List<Dept> findAll();

配置中开启驼峰命名转化（需要正确命名实体类成员名）：
```
mybatis:
  configuration:
    map-underscore-to-camel-case: true
```

多参数传递对应占位符

重点说一下方法参数是类的情况，同样使用@Param注解为入参取名，然后放入SQL语句占位符中

假如参数是两个类对象：

注解写法

@Mapper
public interface UserMapper {
	// 访问userInfo的age成员 department的id成员
    @Select("SELECT * FROM user WHERE info.age = #{userInfo.age} AND dep.id = #{department.id}")
    User selectUser(@Param("userInfo") UserInfo userInfo,
                    @Param("department") Department department);
}

xml写法

<select id="selectUser" resultType="User">
    SELECT *
    FROM user
    WHERE age = #{userInfo.age}
      AND dep_id = #{department.id}
</select>

查询结果分页

用SQL（三个参数）：
- count：获取总记录数（用select count(*)）
- page：查询的页码
- pageSize：每页记录数
由此可得limit参数start = (page - 1) * pageSize，pageSize（从第几条记录开始查，查多少条）

pagehelper插件（无需手动分页）：

pom.xml引入依赖：

<!--分页插件PageHelper-->
<dependency>
    <groupId>com.github.pagehelper</groupId>
    <artifactId>pagehelper-spring-boot-starter</artifactId>
    <version>1.4.7</version>
</dependency>

查询：

@Override
public PageResult page(Integer page, Integer pageSize) {
    //1. 设置分页参数
    PageHelper.startPage(page,pageSize);

    //2. 执行查询（不带limit的查询实现）
    List<Emp> empList = empMapper.list();
    Page<Emp> p = (Page<Emp>) empList;

    //3. 封装结果
    return new PageResult(p.getTotal(), p.getResult());
}

PageHelper只会对紧跟在其后的第一条SQL语句进行分页处理：

条件分页

即在SQL语句中使用条件模糊匹配，继续复用pagehelper

主键返回功能

Mybatis提供，执行insert语句后，自动将生成的主键封装回数据：

使用Options注解，keyProperty属性标识封装回emp的成员名称，插入语句完成后会将id封装回emp对象中

@Options(useGeneratedKeys = true, keyProperty = "id", keyColumn = "id")
@Insert("insert into emp(username, name, gender, phone, job, salary, image, entry_date, dept_id, create_time, update_time) " +
        "values (#{username},#{name},#{gender},#{phone},#{job},#{salary},#{image},#{entryDate},#{deptId},#{createTime},#{updateTime})")
void insert(Emp emp);

mapper xml文件标签

基本标签：
- <mapper>标签：
 - namespace：值是java文件中定义的mapper类路径
- <select>标签，标识查询语句
 - id：值是类中的方法名
 - resultType：值为实体类名，表示查询结果被封装到对应实体类
作用标签：
- <where>标签，表述SQL中的where条件，并去除最终语句中多余的and和or关键字
- <set>标签，表示SQL中的set关键字，设置值并去除最终语句中多余的,
- <if>标签，当test条件为真时使用定义的SQL语句，否则不使用
- <foreach>标签，遍历collection
结果标签：
- <resultMap>标签：一对多查询（一个表的一条记录对应另一个表的多个记录）使用

select + where + if

<!--定义Mapper映射文件的约束和基本结构-->
<!DOCTYPE mapper
        PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
        "http://mybatis.org/dtd/mybatis-3-mapper.dtd">

<mapper namespace="com.itheima.mapper.EmpMapper">
    <select id="list" resultType="com.itheima.pojo.Emp">
        select e.*, d.name deptName from emp as e left join dept as d on e.dept_id = d.id
        <where>
            <if test="name != null and name != ''">
                e.name like concat('%',#{name},'%')
            </if>
            <if test="gender != null">
                and e.gender = #{gender}
            </if>
            <if test="begin != null and end != null">
                and e.entry_date between #{begin} and #{end}
            </if>
        </where>
    </select>
</mapper>

insert + foreach

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper
        PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
        "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.itheima.mapper.EmpExprMapper">

    <!--批量插入员工工作经历信息-->
    <insert id="insertBatch">
        insert into emp_expr (emp_id, begin, end, company, job) values
        <foreach collection="exprList" item="expr" separator=",">
            (#{expr.empId}, #{expr.begin}, #{expr.end}, #{expr.company}, #{expr.job})
        </foreach>
    </insert>

</mapper>

collection：集合名称
item：集合遍历出来的元素/项
separator：每一次遍历使用的分隔符
open：遍历开始前要拼接的字符串
close：遍历结束后要拼接的字符串

select + resultMap

一个员工信息对应多条工作经历

<!--自定义结果集ResultMap-->
<resultMap id="empResultMap" type="com.itheima.pojo.Emp">
    <!--封装员工信息-->
    <id column="id" property="id" />
    <result column="username" property="username" />
    <result column="password" property="password" />
    <result column="name" property="name" />
    <result column="gender" property="gender" />
    <result column="phone" property="phone" />
    <result column="job" property="job" />
    <result column="salary" property="salary" />
    <result column="image" property="image" />
    <result column="entry_date" property="entryDate" />
    <result column="dept_id" property="deptId" />
    <result column="create_time" property="createTime" />
    <result column="update_time" property="updateTime" />

    <!--封装exprList-->
    <collection property="exprList" ofType="com.itheima.pojo.EmpExpr">
        <id column="ee_id" property="id"/>
        <result column="ee_company" property="company"/>
        <result column="ee_job" property="job"/>
        <result column="ee_begin" property="begin"/>
        <result column="ee_end" property="end"/>
        <result column="ee_empid" property="empId"/>
    </collection>
</resultMap>

<!--根据ID查询员工的详细信息-->
<select id="getById" resultMap="empResultMap">
    select e.*,
        ee.id ee_id,
        ee.emp_id ee_empid,
        ee.begin ee_begin,
        ee.end ee_end,
        ee.company ee_company,
        ee.job ee_job
    from emp e left join emp_expr ee on e.id = ee.emp_id
    where e.id = #{id}
</select>

update + set

<!--根据ID更新员工信息-->
<update id="updateById">
    update emp
    <set>
        <if test="username != null and username != ''">username = #{username},</if>
        <if test="password != null and password != ''">password = #{password},</if>
        <if test="name != null and name != ''">name = #{name},</if>
        <if test="gender != null">gender = #{gender},</if>
        <if test="phone != null and phone != ''">phone = #{phone},</if>
        <if test="job != null">job = #{job},</if>
        <if test="salary != null">salary = #{salary},</if>
        <if test="image != null and image != ''">image = #{image},</if>
        <if test="entryDate != null">entry_date = #{entryDate},</if>
        <if test="deptId != null">dept_id = #{deptId},</if>
        <if test="updateTime != null">update_time = #{updateTime},</if>
    </set>
    where id = #{id}
</update>

全局异常处理器

定义一个异常处理类，使用注解@RestControllerAdvice，代表定义了全局异常处理器
在类中，定义一个方法来捕获异常：使用注解@ExceptionHandler。通过@ExceptionHandler注解当中的value属性来指定我们要捕获的是哪一类型的异常。

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    //处理异常
    @ExceptionHandler
    public Result ex(Exception e){//方法形参中指定能够处理的异常类型
        e.printStackTrace();//打印堆栈中的异常信息
        //捕获到异常之后，响应一个标准的Result
        return Result.error("对不起,操作失败,请联系管理员");
    }
}

校验

JWT

HTTP无状态，多次请求-响应之间独立

为了让同一会话之间的多次请求之间共享数据（比如是否已经登录）：

Cookie：服务器下发，客户端保存

// 先请求/c1，再请求/c2，c2就能拿到c1下发的cookie
@Slf4j
@RestController
public class SessionController {

    //设置Cookie
    @GetMapping("/c1")
    public Result cookie1(HttpServletResponse response){
        response.addCookie(new Cookie("login_username","itheima")); //设置Cookie/响应Cookie
        return Result.success();
    }
        
    //获取Cookie
    @GetMapping("/c2")
    public Result cookie2(HttpServletRequest request){
        Cookie[] cookies = request.getCookies();
        for (Cookie cookie : cookies) {
            if(cookie.getName().equals("login_username")){
                System.out.println("login_username: "+cookie.getValue()); //输出name为login_username的cookie
            }
        }
        return Result.success();
    }
}

缺点：

移动端APP不适用
客户端明文存储，不安全，且用户可禁用Cookie
不支持跨域

Session：Cookie升级版，服务器下发，服务器存储

// 请求/s1，如果是初次请求，就生成session id，设置在cookie返回给客户端
// 再请求/s2，通过客户端传来的session id，服务器找到对应的session
// 从session中取数据

@Slf4j
@RestController
public class SessionController {

    @GetMapping("/s1")
    public Result session1(HttpSession session){
        log.info("HttpSession-s1: {}", session.hashCode());

        session.setAttribute("loginUser", "tom"); //往session中存储数据
        return Result.success();
    }

    @GetMapping("/s2")
    public Result session2(HttpServletRequest request){
        HttpSession session = request.getSession();
        log.info("HttpSession-s2: {}", session.hashCode());

        Object loginUser = session.getAttribute("loginUser"); //从session中获取数据
        log.info("loginUser: {}", loginUser);
        return Result.success(loginUser);
    }
}

缺点：

服务器集群不能使用
客户端可以禁用Cookie，使Session无效
移动端APP不能用
不能跨域

jwt令牌技术

服务器生成一个字符串（包含共享信息），下发给客户端，客户端可以自己选择存储方式

当客户端需要使用这些共享信息，就在请求中附加该字符串，由服务器验证是否有效

支持PC、移动端
支持集群使用
减轻服务器存储压力

组成

Header(头），记录令牌类型、签名算法等。例如：{"alg":"HS256","type":"JWT"}
Payload(有效载荷），携带一些自定义信息、默认信息等。例如：{"id":"1","username":"Tom"}
Signature(签名），防止Token被篡改、确保安全性。将header、payload，并加入指定秘钥，通过指定签名算法计算而来。

生成

引入依赖：

<!-- JWT依赖-->
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt</artifactId>
    <version>0.9.1</version>
</dependency>

生成

// claims是jwt中的payload部分，即共享信息，使用map存储
// signWith(algo, key)，指定哈希算法生成签名，并指定密钥
// addClaims(claims) 添加负载
// setExpiration() 设置过期时间
// compact() 生成对应字符串
@Test
public void testGenJwt() {
    Map<String, Object> claims = new HashMap<>();
    claims.put("id", 10);
    claims.put("username", "itheima");

    String jwt = Jwts.builder().signWith(SignatureAlgorithm.HS256, "aXRjYXN0")
        .addClaims(claims)
        .setExpiration(new Date(System.currentTimeMillis() + 12 * 3600 * 1000))
        .compact();

    System.out.println(jwt);
}

校验

需要使用生成时同样的密钥来做校验

对字符串进行了篡改或令牌失效都会导致校验失败（报异常）

@Test
public void testParseJwt() {
    Claims claims = Jwts.parser().setSigningKey("aXRjYXN0")
        .parseClaimsJws("eyJhbGciOiJIUzI1NiJ9.eyJpZCI6MTAsInVzZXJuYW1lIjoiaXRoZWltYSIsImV4cCI6MTcwMTkwOTAxNX0.N-MD6DmoeIIY5lB5z73UFLN9u7veppx1K5_N_jS9Yko")
        .getBody();
    System.out.println(claims);
}

过滤器 Filter

拦截请求（所有发送的请求，包括对静态资源的请求），不属于Spring组件

定义：

类上使用@WebFilter(urlPatterns = "")注解，附带要拦截的请求路径
实现Filter接口

@WebFilter(urlPatterns = "/*") //配置过滤器要拦截的请求路径（ /* 表示拦截浏览器的所有请求 ）
public class DemoFilter implements Filter {
    //初始化方法, web服务器启动, 创建Filter实例时调用, 只调用一次
    public void init(FilterConfig filterConfig) throws ServletException {
        System.out.println("init ...");
    }

    //拦截到请求时,调用该方法,可以调用多次
    public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain chain) throws IOException, ServletException {
        System.out.println("拦截到了请求...");
    }

    //销毁方法, web服务器关闭时调用, 只调用一次
    public void destroy() {
        System.out.println("destroy ... ");
    }
}

Springboot启动类上添加@ServletComponentScan注解

拦截后放行：chain.doFilter(request, response); return;
拦截后不放行：response.setStatus(); return;
@WebFilter(urlPatterns = "")注解配置拦截路径，前缀不同的拦截路径不会同时发挥作用：

比如/dept和/login，请求/dept不会触发/login的拦截器
前缀相同的拦截器的执行顺序：比如/*和/login，默认按类名排序（字典序靠前就先执行），手动配置需要xml文件

拦截器 Interceptor

Spring组件，可直接注入
只拦截Controller层请求

定义（新建interceptor包）：

实现HandlerInterceptor接口，并重写方法：

//自定义拦截器
@Component
public class DemoInterceptor implements HandlerInterceptor {
    //目标资源方法执行前执行。 返回true：放行    返回false：不放行
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        System.out.println("preHandle .... ");
        
        return true; //true表示放行
    }

    //目标资源方法执行后执行
    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {
        System.out.println("postHandle ... ");
    }

    //视图渲染完毕后执行，最后执行
    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {
        System.out.println("afterCompletion .... ");
    }
}

interceptor包上级目录创建WebConfig类，实现WebMvcConfigurer接口：

@Configuration  
public class WebConfig implements WebMvcConfigurer {

    //自定义的拦截器对象
    @Autowired
    private DemoInterceptor demoInterceptor;

    
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
       //注册自定义拦截器对象
        registry.addInterceptor(demoInterceptor).addPathPatterns("/**");//设置拦截器拦截的请求路径（ /** 表示拦截所有请求）
    }
}

配置类注解@Configuration：类上加上该注解表明该类是一个配置类，Springboot程序启动时会自动执行里面的某些方法（在这是实现了WebMvcConfigurer的addInteceptors方法：注册拦截器以生效）
拦截路径：addPathPatterns("url")
不拦截路径：excludePathPatterns("url")

AOP

简介

基于动态代理的方法，在不修改原代码的情况下，增强功能

pom依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-aop</artifactId>
</dependency>

注解：

类上加@Aspect

类中方法加@Around("execution...")

在里面通过ProceedingJoinPoint对象执行原始方法，并增添新功能

@Component
@Aspect //当前类为切面类
@Slf4j
public class RecordTimeAspect {
	// 代理某个方法
    @Around("execution(* com.itheima.service.impl.DeptServiceImpl.*(..))")
    public Object recordTime(ProceedingJoinPoint pjp) throws Throwable {
        // 执行原始方法之前
        
        // 执行原始方法
        Object result = pjp.proceed();
        // 执行原始方法之后
        
        // 返回原始方法的结果
        return result;
    }
}

**应用场景：**一般用于增强业务层（Service）方法的功能（日志记录、权限控制、事务管理）

概念

连接点：JointPoint，指可被AOP控制的方法，通俗点就是业务层Bean的public方法
通知：Advice，AOP层的方法，要在里面完成增强的功能，同时代理连接点的功能
切入点：PointCut，匹配连接点的条件，@Around("execution(...)")就描述了一个切入点表达式，表明要代理哪个方法
切面：Aspect，一组通知和切入点的集合
目标：Target，理解为切入点所代理的方法所在的Bean对象

通知类型

五种通知类型对应的注解：

@Around：AOP层方法参数是ProceedingJoinPoint类型，需要在里面调用proceed()来执行被代理的方法，代理方法前后都可以写自定义的功能
@Before：AOP层方法参数是JointPoint类型，只需要写自定义的功能，被代理方法前会执行
@After：同上，被代理方法后执行
@AfterReturning：同上，被代理方法正常返回后会执行
@AfterThrowing：同上，被代理方法出现异常时才会执行

预定义不同切入点（使用@PointCut注解）：

//切入点方法（公共的切入点表达式）
@Pointcut("execution(* com.itheima.service.*.*(..))")
public void pt(){}

更改通知注解形式：@Around("pt()")

执行顺序

多个切面类使用了相同的切入点，执行顺序默认按切面类类名升序执行

要指定顺序，在切面类上使用@Order(num)，指定num的相对大小

切入点表达式

指AOP方法注解里面那一坨execution(...)，作用是指定被代理的方法，有两种写法：

execution(访问修饰符? 返回值包名.类名.?方法名(方法参数) throws 异常?)
- 访问修饰符（public），包名.类名.，throws 异常这些都可以省略，但不建议省略包名.类名
- 可以用*匹配一个独立的任意符号，可以是修饰符，一个包名，一个类名，任意类型的一个参数
- 可以用..匹配任意个独立的符号
- 可以用&&，||，!连接多个表达式指明匹配的方法
- 例子：execution(* com.itheima.service.DeptService.*(..))匹配service包下的DeptService接口中的任意方法
@annotation(自定义注解全类名)
- 需要自定义注解，一般放在anno包下
- 在业务层方法需要代理的方法上加上自定义的注解
- AOP方法通知注解里的execution换成@annotation(自定义注解全类名)

SpringBoot

作用域

IOC容器中管理的Bean默认是单例（只有一个对象）

如果要求管理的Bean有多个实例：

在使用@Component注解的类上添加一个注解@Scope("prototype")

之后每一次使用该@Bean时会创建一个新的实例

第三方Bean管理

添加一个配置类
配置类上使用注解**@Configuration**标识该类是一个配置类
定义一个方法，返回值是要让IOC容器管理的对象，在方法上使用注解**@Bean**

package com.itheima.config;

import com.itheima.utils.AliyunOSSOperator;
import com.itheima.utils.AliyunOSSProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OSSConfig {
    @Bean
    public AliyunOSSOperator aliyunOSSOperator(AliyunOSSProperties ossProperties) {
        return new AliyunOSSOperator(ossProperties);
    }
}

如果方法有参数，Spring会自动去IOC容器里面找对应类型的数据

起步依赖和自动配置

起步依赖就是形如spring-boot-starter-xxxx（官方starter）或者xxxx-spring-boot-starter（第三方starter）的整合包，里面设置了一组依赖包，在引入starter时会根据maven包管理自动引入所有依赖包

自动配置指的是当在maven包管理引入包，Spring容器启动后，包中的一些配置类，bean对象自动存入到容器中，无需手动做上述的Bean管理

实现方案：

在Springboot启动类上使用**@Import**注解
- 导入普通类：@Import(Gson.class)，该类会实例化成为一个Bean被Spring容器管理
- 导入配置类：@Import(Config.class)，参考“第三方Bean管理”的配置类，类中所有配置@Bean的方法都会实例化成为一个Bean被Spring容器管理
- 导入ImportSelector接口实现类：
  
  实现ImportSelector接口
```
public class MyImportSelector implements ImportSelector {
    public String[] selectImports(AnnotationMetadata importingClassMetadata) {
        //返回值字符串数组（数组中封装了全限定名称的类）
        return new String[]{"com.example.HeaderConfig"};
    }
}
```
  导入：@Import(MyImportSelector.class)

第三方依赖通常会封装自己的@Import，对外提供**@EnableXXXX**注解，在启动类上使用该注解，相当于导入了第三方的配置类和Bean对象

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Import(MyImportSelector.class)//指定要导入哪些bean对象或配置类
public @interface EnableHeaderConfig { 
}

自动配置原理

在启动类上的@SpringBootApplication注解，这个注解封装了下面三个注解：

@SpringBootConfiguration：该注解又封装了@Configuration，声明当前类是一个配置类
@ComponentScan：通过该注解可以扫描启动类所在包及其子包中的被@Component标注的类，实例化为Bean对象管理
@EnableAutoConfiguration：重点，封装了@Import注解，会读取当前项目下所有依赖jar包中META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件里面定义的配置类，然后导入这些配置类

导入配置类时，配置类中定义的Bean不会一次性全部导入，由@Conditional注解来管理：

@ConditionalOnClass：判断环境中有对应字节码文件，才注册bean到IOC容器
@ConditionalOnMissingBean：判断环境中没有对应的bean(类型或名称)，才注册bean到IOC容器
@ConditionalOnProperty：判断配置文件中有对应属性和值，才注册bean到IOC容器

modern C++ 个人总结

Wed, 30 Apr 2025 00:00:00 GMT

reference（引用）

c++中的引用是一种给变量起别名的方法，类似于指针，原变量和引用将指向同一块内存地址

void add_three(int &a);
int a = 10;
int &b = a;	// b是a的别名

指针引用：顾名思义是对指针变量起别名，其形式通常为type* &x

// 可以这么理解，&b代表b是一个引用, 而int*是这个引用的类型
void change_pointer(int* &b);

int* a = new int;
int* &b = a;

move_semantics（移动语义）

移动语义是指在c++对象中移动资源的这一动作，普通的对象拷贝可能花费不小的时间和空间资源，而移动语义可以直接将对象A的资源转移给对象B，同时A的资源被清零

由于移动针对**类对象（class object）**之间的过程，所以对普通类型（如int，double，裸指针）之间使用移动语义并不能移动资源，移动语义也不应该在普通类型中进行使用

移动语义离不开下面要介绍的左值和右值的概念，在c++中，任何一个表达式要么是左值要么是右值，例如：

// a 是左值, 10 是右值
int a = 10;
// b 是左值, a * 2 是右值
int b = a * 2;

lvalue（左值）and rvalue（右值）

官方定义是，左值表示在内存中占据某个可识别位置的表达式（在表达式被计算完毕后仍然能够存在）

例子：

int add(int x, int y);
int a = 5;
int *p = &a;
int b = add(1, 3);
int &c = b;
vector &&d = {1,2,3}

在上面的代码中，=左边的表达式（变量）都是左值（vector &&表示一个vector的右值引用，后面会介绍）

与左值相反，是那些表达式被计算完毕后，无法继续存在的临时值，如字面量（字符串除外），或者一个函数的返回结果：

int add(int x, int y);
10;
add(1, 3);
2 * 4 + add(1, 3);
int x = 1, y = 2;
x * y;

上面的10，add(1, 3)，x * y都是右值

左值引用和右值引用

reference之前已经介绍过，就是给变量起别名

左值引用就是给左值变量起别名

右值引用就是给右值变量起别名，但右值在表达式结束后不应该存在，所以现代C++新的规则就是右值引用会延长引用的右值的生命周期，例如：

// 如果a是int类型，那么10在赋值表达式结束后，生命周期结束
int &&a = 10;
// 现在a是一个右值引用，并且引用了10，那么10在内存中不会消失，直到a消失后其再消失

// getString()会返回一个临时的string对象，如果s1是一个string类型，那么该对象在赋值结束后，生命周期结束
string getString();
string &&s1 = getString();
// 现在这个对象被s1所引用，同样的，该临时变量的生命周期只有在s1结束后才结束

tips：一个右值引用的变量仍然是一个左值（因为在赋值表达式计算完毕后其仍能存在）

std::move

头文件<utility>中的std::move函数负责将一个左值无条件的转为右值，除此之外其什么都不做（不做资源的实际转移）

// 定义一个vector对象
std::vector<int> stealing_ints = {1, 2, 3}

// std::move()将stealing_ints变为一个右值，不产生新对象，也不改变原对象的内容
std::vector<int> &&rvalue_stealing_ints = std::move(stealing_ints);
// rvalue_stealing_ints是绑定在该右值的一个右值引用

// 因为是引用，所以可以同时使用stealing_ints和rvalue_stealing_ints来访问或修改该对象
std::cout << "Printing from stealing_ints: " << stealing_ints[1] << std::endl;

移动语义

移动语义通常指在对象之间利用移动资源的方式来代替复制资源的方式，比如下面这个例子：

// 定义一个vector
std::vector<int> int_array = {1, 2, 3, 4};

// 将int_array的资源移动到stealing_ints上 
std::vector<int> stealing_ints = std::move(int_array);
// 该表达式结束之后, int_array的资源就被清空了（如底层指针变为nullptr）

上面的代码首先将int_array转为一个右值，然后将其资源转移到stealing_ints中，在此表达时候不应该直接使用int_array（除非重新构建一个对象）

为什么要先转为右值？

资源的移动实际上是通过类的移动构造函数做到的，类似深拷贝函数，而移动构造函数要求参数为一个右值引用

下面是一个将对象移动到函数中的例子：

void move_add_three_and_print(std::vector<int> &&vec) {
  // 调用vector的移动构造函数，转移资源
  std::vector<int> vec1 = std::move(vec);
  vec1.push_back(3);
  for (const int &item : vec1) {
    std::cout << item << " ";
  }
  std::cout << "\n";
}
int main() {
	std::vector<int> int_array2 = {1, 2, 3, 4};
    // vec右值引用，引用了int_array2
    move_add_three_and_print(std::move(int_array2));
    // 之后不应该直接使用int_array2,因为其资源已经被移动
}

为什么要在函数中再次调用std::move？

vec是一个右值引用，但其本身是一个左值，而移动构造函数接受一个右值作为参数，所以需要将vec先转为右值再赋值给vec1才能够正确转移，否则会调用vector的拷贝构造函数

具体可以参考下面这段代码（来源：现代c++教程）：

#include <iostream>
#include <string>

void reference(std::string& str) {
    std::cout << "左值" << std::endl;
}
void reference(std::string&& str) {
    std::cout << "右值" << std::endl;
}

int main()
{
    std::string lv1 = "string,"; // lv1 是一个左值
    // std::string&& r1 = lv1; // 非法, 右值引用不能引用左值
    std::string&& rv1 = std::move(lv1); // 合法, std::move可以将左值转移为右值
    std::cout << rv1 << std::endl; // string,

    const std::string& lv2 = lv1 + lv1; // 合法, 常量左值引用能够延长临时变量的生命周期
    // lv2 += "Test"; // 非法, 常量引用无法被修改
    std::cout << lv2 << std::endl; // string,string,

    std::string&& rv2 = lv1 + lv2; // 合法, 右值引用延长临时对象生命周期
    rv2 += "Test"; // 合法, 非常量引用能够修改临时变量
    std::cout << rv2 << std::endl; // string,string,string,Test

    reference(rv2); // 输出左值

    return 0;
}

reference(rv2)实际输出的是左值，也就代表着其实际调用了void reference(std::string& str)函数

move_constructors（移动构造）

移动构造函数和移动赋值运算符是在类内部实现的方法，用于将一个对象的资源转移到另一个对象

class Person {
public:
  Person() : age_(0), nicknames_({}), valid_(true) {}

  // 构造函数通过接受一个std::vector<std::string>右值作为参数
  // 这使得构造时比一般的会更快，因为不需要复制vector的底层数组
  Person(uint32_t age, std::vector<std::string> &&nicknames)
      : age_(age), nicknames_(std::move(nicknames)), valid_(true) {}

  // Person类的移动构造函数：接受一个Person类型的右值
  // 具体过程是：将传入的右值中的对象成员，通过std::move()转为右值
  // 再调用vector的移动构造函数，实现资源转移
  
  // vector是如何转移资源的？
  // 假设vector有一个void* arr指针用于指向开辟的动态数组
  // nicknames_(std::move(person.nicknames_))实际上做：
  // 1. nicknames_.arr = person.nicknames_.arr;
  // 2. person.nicknames_arr = nullptr;
  Person(Person &&person)
      : age_(person.age_), nicknames_(std::move(person.nicknames_)),
        valid_(true) {
    std::cout << "Calling the move constructor for class Person.\n";
    // 将被移动对象的实例标志置为false
    person.valid_ = false;
  }

  // Person类的移动赋值运算符，原理与移动构造函数相同
  Person &operator=(Person &&other) {
    std::cout << "Calling the move assignment operator for class Person.\n";
    age_ = other.age_;
    nicknames_ = std::move(other.nicknames_);
    valid_ = true;

    // 将被移动对象的实例标志置为false
    other.valid_ = false;
    return *this;
  }

  // delete关键字代表将类的指定构造函数删除
  // Person类将不再有拷贝构造函数
  Person(const Person &) = delete;
  Person &operator=(const Person &) = delete;

  uint32_t GetAge() { return age_; }

  // 返回类型中的这个 & 符号意味着我们返回对 nicknames_[i] 处字符串的引用。
  // 这也意味着我们不拷贝结果字符串，
  // 此函数返回的内存地址实际上是指向向量 nicknames_ 内存的地址。
  std::string &GetNicknameAtI(size_t i) { return nicknames_[i]; }

  void PrintValid() {
    if (valid_) {
      std::cout << "Object is valid." << std::endl;
    } else {
      std::cout << "Object is invalid." << std::endl;
    }
  }

private:
  uint32_t age_;
  std::vector<std::string> nicknames_;
  // 跟踪对象的数据是否有效，即是否所有数据都已移动到另一个实例。
  bool valid_;
};

测试：

int main() {
  // 创建一个Person对象，此时调用的是Person(uint32_t age, std::vector<std::string> &&nicknames)构造函数
  Person andy(15445, {"andy", "pavlo"});
  std::cout << "Printing andy's validity: ";
  andy.PrintValid();

  // 将andy对象转为右值，并使用移动赋值运算符将andy的资源移动到andy1
  Person andy1;
  andy1 = std::move(andy);

  // 此时andy1的资源是有效的，而andy的资源已经被转移了，不再有效
  std::cout << "Printing andy1's validity: ";
  andy1.PrintValid();
  std::cout << "Printing andy's validity: ";
  andy.PrintValid();

  // 该表达式使用Person类的移动构造函数
  
  Person andy2(std::move(andy1));

  // 跟上面一样，该表达式结束后，andy2将拥有andy1的资源，andy1资源被转移，不再有效
  // 后续不应该继续使用andy1，除非重新初始化andy1，
  std::cout << "Printing andy2's validity: ";
  andy2.PrintValid();
  std::cout << "Printing andy1's validity: ";
  andy1.PrintValid();

  // 拷贝构造函数和拷贝运算符函数被删除，下面的代码都会报编译错误
  // Person andy3;
  // andy3 = andy2;

  // Person andy4(andy2);

  return 0;
}

C++ Templates（C++模板）

模板类

在类定义前使用template<typename T>来标识模板类：

template<typename T>
class Foo {
  public:
    Foo(T var) : var_(var) {}
    void print() {
      std::cout << var_ << std::endl;
    }
  private:
    T var_;
};

其中T是传递的类型，typename用作声明类型的关键字（也可以用class），模板类型可以设置多个，如下：

template<typename T, typename U> 
class Foo2 {
  public:
    Foo2(T var1, U var2) 
      : var1_(var1)
      , var2_(var2) {}
    void print() {
      std::cout << var1_ << " and " << var2_ << std::endl;
    }
  private:
    T var1_;
    U var2_;
};

特化模板类：当模板类型为指定类型（如size_t）时单独设计的代码，当外部显示指定了类型时，会使用这部分代码：

template<typename T>
class FooSpecial {
  public:
    FooSpecial(T var) : var_(var) {}
    void print() {
      std::cout << var_ << std::endl;
    }
  private:
    T var_;
};

// 特化的模板类，专门化于float类型。
// 指定类型FooSpecial<float> foo;时，会使用下面的类
template<>
class FooSpecial<float> {
  public:
    FooSpecial(float var) : var_(var) {}
    void print() {
      std::cout << "hello float! " << var_ << std::endl;
    }
  private:
    float var_;
};

类模板的参数不一定是类型，可以是值：

// 这里的T不是类型，而是在使用时需要填入的一个值，如Bar<10>
// std::array就使用了该类模板，用于指定静态数组的大小
template<int T>
class Bar {
  public: 
    Bar() {}
    void print_int() {
      std::cout << "print int: " << T << std::endl;
    }
};

模板函数

在函数上使用模板与在类上使用模板几乎相同，也可以在一个普通的类或者类模板中声明一个模板成员函数：

template<typename T>
class Foo3 {
  public:
    Foo3(T var) : var_(var) {}
    template<typename U>
    void solve(U var) {
        // 做一些处理跟var有关的事
    }
    void print() {
      std::cout << var_ << std::endl;
    }
  private:
    T var_;
};

tips：使用模板时，声明与定义应该放在同一个文件中，通常做法都是在头文件中声明并定义模板

杂项

wrapper class（包装类）

包装类使用RAII（资源获取即初始化）的思想，将一部分资源交给包装类来管理（内存，文件，网络描述符），当包装类被实例构造时，代表其管理的底层资源是可用的，被析构时，资源自动变得不可用
包装类通常禁用拷贝构造函数，避免多个对象管理同一资源；但支持移动语义，转移资源的所有权

class IntPtrManager {
  public:
    // 包装类的所有构造函数都应该初始化一个资源。
    // 在这种情况下，这意味着分配我们正在管理的内存。
    // 这个指针数据的默认值是 0。
    IntPtrManager() {
      ptr_ = new int;
      *ptr_ = 0;
    }

    // 这个包装类的另一个构造函数，接受一个初始值。
    IntPtrManager(int val) {
      ptr_ = new int;
      *ptr_ = val;
    }

    // 包装类的析构函数。析构函数必须销毁它正在管理的资源；
    // 在这种情况下，析构函数删除指针！
    ~IntPtrManager() {
      // 注意，由于移动构造函数通过将 ptr_ 值设置为 nullptr 来标记对象无效，
      // 我们必须在析构函数中考虑这一点。
      // 我们不想对 nullptr 调用 delete！
      if (ptr_) {
        delete ptr_;
      }
    }

    // 这个包装类的移动构造函数。注意在移动构造函数被调用后，
    // 实际上将 other 的所有数据移动到被构造的指定实例中，
    // other 对象不再是 IntPtrManager 类的有效实例，
    // 因为它没有内存可以管理。
    IntPtrManager(IntPtrManager&& other) {
      ptr_ = other.ptr_;
      other.ptr_ = nullptr;
    }

    // 这个包装类的移动赋值操作符。
    // 与移动构造函数类似的技术。
    IntPtrManager &operator=(IntPtrManager &&other) {
      if (ptr_ == other.ptr_) {
        return *this;
      }
      if (ptr_) {
        delete ptr_;
      }
      ptr_ = other.ptr_;
      other.ptr_ = nullptr;
      return *this;
    }

    // 我们删除拷贝构造函数和拷贝赋值操作符，
    // 所以这个类不能被拷贝构造。
    IntPtrManager(const IntPtrManager &) = delete;
    IntPtrManager &operator=(const IntPtrManager &) = delete;

    // 设置函数。
    void SetVal(int val) {
      *ptr_ = val;
    }

    // 获取函数。
    int GetVal() const {
      return *ptr_;
    }

  private:
    int *ptr_;

};

namespace（命名空间）

命名空间主要用于提供作用域、组织代码、防止命名冲突

使用namespace xxx定义一个命名空间（可以嵌套）

namespace name1 {
    ...
    namespace name2 {
        ...
    }
}

使用::操作符访问不同命名空间的标识符，如name::name2::x
使用using关键字引入命名空间或其中的标识符，如using namespace std;，using std::cout
匿名空间，即不指定名字的命名空间：
```
namespace {
    ...
}
```
编译器会主动生成独一无二的名字
实践：
- 在头文件中定义有名字的命名空间，在源文件名定义匿名空间
  
  （匿名空间定义在头文件中，那么所有包含了头文件的源文件都将有一个对应空间的副本）
- 在头文件中适当使用using name::;，不要使用using namespace xxx;
  
  （头文件中使用using namespace xxx会影响到所有包含其的源文件）
- 如果只是想暂时使用命名空间或某个标识符，可以在函数中使用using

iterator（迭代器）

提供对容器（数组、链表、树）中的元素的统一访问方式，无需暴露容器内部结构、

形式：定义在每个容器内部，定义一个vector的迭代器std::vector<int>::iterator it
提供访问和修改：类似指针，指向容器中的某个位置，使用*操作符可以操作对应的数据，根据容器类型的不同有不同的数据类型：
- 顺序容器（如vector）：*iterator即为T类型
- 关联容器（如map）：*iterator即为pair<K, V>类型
提供移动：从容器的某个位置移动到另一个位置，前缀++，--操作符，分别表示将迭代器从当前位置向后移动一位和向前移动一位
容器提供：
算法提供：

容器

vector

priority_queue

默认是大根堆，需要重载<

使用greater指定小根堆，需要重载>

map

unordered_map

自动推导

decltype和auto是现代c++中的类型推导工具

auto

使用auto可以极大简化代码：

// 下面两行代码等价
// std::vector<int>::iterator it = nums.begin();
auto it = nums.begin();

使用auto还可以定义lambda表达式，自动推导函数类型，函数返回类型等...

auto会自动推导赋值表达式右侧的类型，类似模板参数template<typename T>，二者的推导规则几乎相同

按值传递

使用auto，默认会忽略顶层const和引用（行为与使用模板参数的函数传值类似）：

int x = 42;
int &y = x;
const int &z = y;

auto a = x; // 即int a = x;
auto b = y; // 即int b = y;
auto c = z; // 即int c = z;

引用传递

使用auto&，与普通类型引用类似，同时会保留const属性：

int x = 42;
int &y = x;
const int &z = y;

auto& a = x; // 即int& a = x;
auto& b = y; // 即int& b = y;
auto& c = z; // 即const int& c = z;

万能引用

使用auto&&，这不是上面提到的右值引用，而是遵守引用折叠规则的万能引用，它根据赋值表达式右侧的值类型（左值/右值）来决定左侧变量的类型：

int x = 42;
const int &y = x;

auto&& a = x; // 即int& a = x;
auto&& b = y; // 即const int& b = y;
auto&& c = 42; // 即int&& c = 42;

这与模板参数的推导类似：

template<typename T>
auto func1(T&& t) -> void {
    // t的类型根据传入参数决定
}
// 上面的代码
// 在传入左值时参数被推导为T& t
// 在传入右值时参数被推导为T&& t

安全实践

由于使用auto来定义变量会默认发生拷贝，比如：

auto vec = nums;（假设nums是一个vector<int>类型变量）

vec和nums就是两个不同的数组

当只需要读取而不需要修改变量，且不想要拷贝带来的开销，可以使用：

vector<vector<int>> nums1 = {
    {1, 2, 3}, 
    {4, 5, 6}
};
// 使用了容器的便利特性
for (const auto& vec : nums1) {
    // vec不会拷贝原数组
    for (const auto& i : vec) {
        cout << i << ' ';
    }
}

decltype

decltype像是一个高级的auto，它根据给定的表达式，推导出原表达式的精确类型，包括顶层const引用

对于decltype(e)来说：

如果e 是一个变量（如 x）或类成员访问（如 obj.member），那么 decltype(e) 就是该变量或成员声明的类型。
如果表达式 e 值类别是左值，decltype(e) 是 T&（引用类型），其中 T 是 e 的类型（这个T不是模板类型那个T）。
如果表达式 e 值类别是纯右值），decltype(e) 是 T（原类型）。
如果表达式e值类别是将亡值，decltype(e)是T&&（右值引用）。

int i = 0;
// 规则1 
decltype(i); // 推导为int
// 规则2
decltype((i)); // 推导为int&

int& func() {
    return i;
}
decltype(func()); //推导为int&

// 规则3
decltype(1 + 2); // 推导为int

// 规则4
decltype(std::move(i)); // 推导为int&&

函数类型推导

使用auto可以推导出迭代器，函数类型等复杂的类型：

int add_func(int a, int b) {
    return a + b;
}

int main() {
    auto minus_func = [](int a, int b) { return a - b; };

    std::vector<std::function<decltype(add_func)>> funcVec = {
        add_func,
        minus_func
    };

    funcVec[0](1, 2);
    funcVec[1](1, 2);
}

函数模板返回值推导

decltype(auto)表示使用decltype的规则来推导auto，当不确定模板的返回值时，使用其可以返回精确的类型

template <typename Container, typename Index>
decltype(auto) get(Container& c, Index i) { // 更简洁！
    return c[i]; // 如果 c[i] 返回 int&，则函数返回 int&
}

内存管理

unique_ptr

shared_ptr

weak_ptr

锁与同步

读写锁

c++中没有专用的读者-写者锁库，但可以通过std::shared_mutex，std::shared_lock和std::unique_lock来模拟

std::shared_mutex允许共享锁定和独占锁定
std::shared_lock以共享的方式来占用一个std::shared_mutex（其他线程同样可以使用std::shared_lock来获得该锁，但不允许其他线程使用std::unique_lock获得锁）
std::unique_lock以独占的方式来占用一个std::shared_mutex（其他线程此时无法获得锁，除非该锁被主动释放）

例：

#include <iostream>
#include <mutex>
#include <shared_mutex>
#include <thread>

// 定义一个全局count变量和一个供所有线程使用的shared mutex
int count = 0;
std::shared_mutex m;

// 读线程使用std::shared_lock来获得对count变量的只读共享访问，并读取count变量
// 有意思的点在于只读是人为规定的, 如果某个线程执行了写入, 可能出现一些意想不到的效果
void read_value() {
  std::shared_lock lk(m);
  std::cout << "Reading value " + std::to_string(count) + "\n" << std::flush;
}

// 这个函数使用std::unique_lock来获得对count变量的独占访问并写入值, 一旦其获得锁, 除非其主动释放, 否则其他线程无法获得锁
void write_value() {
  std::unique_lock lk(m);
  count += 3;
}

参考资料

LeetCode 每日一题

Fri, 26 Sep 2025 00:00:00 GMT

3729. 统计有序数组中可被K整除的子数组数量（2025.10.27）

原题链接

题目要求[l, r]的对数，使得：

(sum[r] - sum[l - 1]) % k == 0（sum是前缀和）
nums[l1, r2] != nums[l2, r2]（长度不同或者长度相同内容不同）

因为nums是非降序的，考虑更严苛的条件，一个升序数组，那么第二个条件就没用了，因为所有的子数组必定不相同，再来考虑如果求出满足第一个条件的[l, r]对数：

第一个条件可以转化成sum[r] % k == sum[l - 1] % k

于是可以枚举右端点r，同时在哈希表中记录左端点l(l <= r)的数量，其中key是sum[0, l - 1] % k，然后计算sum[0, r] % k，去哈希表中查有多个左端点满足条件，就能得出右端点为r时有多少个子数组满足条件，总和相加即为答案ans

如果升序数组变为非降序数组，用上面的方法计算会出现一个重复计算的问题，如样例[2, 2, 2, 2, 2, 2]和模值6，但考虑重复计数的情况，两个[l, r]：

长度相同
内容相同

换句话说，只有在子数组为[x, x, ..., x]这样的形式时才会出现重复计数，那么我们可以统计出来所有这样的子数组，以<x, length>的形式存为一个数组

对于<x, length>这样一个子数组，先前的ans中出现了重复计数，主要原因是相同长度统计了多次，考虑使用m个x能够整除k，即m * x % k == 0，容易使用最小公倍数算出m = lcm(x, k) / x，那么该子数组最少有m + 1个x，才有可能出现重复计数：

m个x，重复计数了length - m次
2m个x，重复计数了length - 2m次

...

令l = length / m（下取整），可以得到子数组<x, length>的重复计数：

repeat_x = l * length - m * (l + 1) * l / 2

使用ans减去每一个repeat_x即为答案

code：

class Solution {
    using i64 = long long;
public:
    int gcd(int x, int y) {
        return y == 0 ? x : gcd(y, x % y);
    }

    i64 lcm(int x, int y) {
        return 1ll * x * y / gcd(x, y);
    }
    long long numGoodSubarrays(vector<int>& nums, int k) {
        
        i64 ans = 0;
        // sum[r] % k == sum[l - 1] % k
        unordered_map<i64, int> u_map;
        u_map[0] = 1;
        i64 sum_r = 0;
        int n = nums.size();
        for (int i = 0; i < n; i++) {
            sum_r = (sum_r + nums[i]) % k;
            if (u_map.contains(sum_r)) {
                ans += u_map[sum_r];
            }
            u_map[sum_r]++;
        }
        // <num, length>
        vector<pair<int, int>> total;
        int num = nums[0], cnt = 0;
        for (int i = 0; i < n; i++) {
            if (nums[i] == num) {
                cnt++;
            } else {
                total.push_back({num, cnt});
                num = nums[i];
                cnt = 1;
            }
            if (i == n - 1) {
                total.push_back({num, cnt});
            }
        }
        i64 repeat = 0;
        for (int i = 0; i < total.size(); i++) {
            i64 m = lcm(total[i].first, k) / total[i].first;
            i64 l = total[i].second / m;
            repeat += l * total[i].second - (m * l * (l + 1) / 2);
        }
        ans -= repeat;
        return ans;
    }
};

时间复杂度：$O(nlog(max(nums_i, k))$，其中$log(max(nums_i, k))$是计算最小公约数的时间

3728. 边界与内部和相等的稳定子数组（2025.10.26）

原题链接

求子数组的数量，$10^4$以下能用$O(n^2)$，$10^5$以上就是$O(nlogn)$或者$O(n)$的做法，根据经验，多数与差分，前缀和有关（双指针只是在这个过程用到的技巧），从前缀和的角度去考虑两端的数l和r，找到l和r的关系后，枚举一端（通常是r），同时移动另一端使其满足先前的关系

以问题为例，长度至少为3，首尾元素需相等，中间元素的和需要等于首元素，假设已经有前缀和$sum$，那么上面的条件如下：

r - l + 1 >= 3
capacity[l] == capacity[r]
sum[r - 1] - sum[l] == capacity[l]

将最后一个式子变形得：sum[r - 1] == sum[l] + capacity[l]

于是可以在枚举r时，同时记录{capacity[l], sum[l] + capacity[l]}的数量（使用map），在满足r - l + 1 >= 3的情况下，搜索记录{capacity[r], sum[r - 1]}

如果之前记录的左端被记录过，说明是对于当前r来说，满足以上三个条件的左端点，就可以累加，累加的结果就是答案

code：

class Solution {
public:
    long long countStableSubarrays(vector<int>& capacity) {
        using i64 = long long;
        int n = capacity.size();
        i64 sum_l = 0, sum_r = 0;
        sum_r += capacity[0] + capacity[1];
        map<pair<i64, i64>, i64> map;
        i64 ans = 0;
        for (int r = 2, l = 0; r < n; r++) {
            while (r - l + 1 >= 3) {
                sum_l += capacity[l];
                pair<i64, i64> index {capacity[l], capacity[l] + sum_l};
                map[index]++;
                l++;
            }
            pair<i64, i64> index {capacity[r], sum_r};
            sum_r += capacity[r];
			if (map.contains(index)) {
                ans += map[index];
            }
        }
        return ans;
    }
};

时间复杂度：$O(nlogn)$

3347. 执行操作后元素的最高频率 II（2025.10.22）

原题链接

本题相对3346，扩大了$[s, e]$的范围，这使得无法暴力枚举来求出答案，但通过观察可以发现，$[s, e]$中并不是所有的数字都值得被枚举，这一点可以通过差分来证明：

对于每一个$nums[i]$，其能够转为的数字在$[nums[i]-k, nums[i]+k]$之间，考虑一个数轴，这表示在$[nums[i]-k, nums[i]+k]$这段数字上+1（代表这段数字可以由$num[i]$操作后得到），如下图所示：

从图中可以看出，只需要枚举$num[i], nums[i]-k, nums[i]+k$，枚举区间上的其他数字，其$sum$值不会超过枚举这三个数字得到的$sum$值，因此可以缩减枚举的区间，从$[s, e]$到所有的$nums[i], nums[i]-k, nums[i]+k$，同样使用滑动窗口来遍历原数组，做法和3346相同

code：

class Solution {
public:
    using i64 = long long;
    int maxFrequency(vector<int>& nums, int k, int numOperations) {
        sort(nums.begin(), nums.end());
        using PII = pair<int, int>;
        vector<PII> u_nums;
        int num = nums[0], cnt = 1;
        int n = nums.size();
        for (int i = 1; i < n; i++) {
            if (nums[i] != num) {
                u_nums.push_back({num, cnt});
                num = nums[i];
                cnt = 1;
            } else {
                cnt++;
            }
        }
        u_nums.push_back({num, cnt});
        vector<int> candidate;
        n = u_nums.size();
        for (int i = 0; i < n; i++) {
            candidate.push_back(u_nums[i].first - k);
            candidate.push_back(u_nums[i].first);
            candidate.push_back(u_nums[i].first + k);
        }
        sort(candidate.begin(), candidate.end());
        n = candidate.size();
        queue<int> q;
        int sum = 0, ans = 0;
        for (int s = 0, i = 0, j = 0; s < n; s++) {
            i64 l = 1ll * candidate[s] - k, r = 1ll * candidate[s] + k;
            while (!q.empty() && u_nums[q.front()].first < l) {
                int index = q.front();
                q.pop();
                sum -= u_nums[index].second;
            }
            while (j < u_nums.size() && u_nums[j].first <= r) {
                q.push(j);
                sum += u_nums[j].second;
                j++;
            }
            if (i < u_nums.size() && candidate[s] == u_nums[i].first) {
                int op = min(sum - u_nums[i].second, numOperations);
                ans = max(ans, op + u_nums[i].second);
                i++;
            } else {
                int op = min(sum, numOperations);
                ans = max(ans, op);
            }
        }
        return ans;
    }
};

时间复杂度：$O(nlogn)$，$n$是数组长度

3346. 执行操作后元素的最高频率 I（2025.10.21）

原题链接

题目中声明所有数字最多被操作一次，考虑到数据量较小，频率最高的数字的范围只可能在$[s, e] = [min(nums), max(nums)]$，这不难证明，如果操作能使得频率最高的超出这个范围设为$x$，那么在范围内一定存在一个数$y$，使得$y$的频率和$x$相等，题目只要求求出最大的频率，那么这个范围自然是越小越好

那么可以考虑枚举$[s, e]$当中的每一个数$t$，则能够通过操作变为$t$的数字范围就在$[t - k, t + k]$，只需要去原数组中查找这个范围的数有多少个即可

对原数组排序
对原数组去重，并统计相同数字的数量
在遍历$[s, e]$中，使用滑动窗口同步滑动处理后的数组，将滑动窗口内的数组限制在$[t - k, t + k]$中，统计滑动窗口内的数字数量，代表有$sum$多少个数字可以转成$t$，然后和可操作数量取最小值，代表可以有$op$个数字可以转成$t$，再比较每个$t$中的$op$最大值

需要注意的是，如果$t$在原数组中出现过，需要额外处理，因为原数组中的这些数字不再需要操作变成$t$

code：

class Solution {
public:
    int maxFrequency(vector<int>& nums, int k, int numOperations) {
        sort(nums.begin(), nums.end());
        using PII = pair<int, int>;
        vector<PII> u_nums;
        int num = nums[0], cnt = 1;
        int n = nums.size();
        for (int i = 1; i < n; i++) {
            if (nums[i] != num) {
                u_nums.push_back({num, cnt});
                num = nums[i];
                cnt = 1;
            } else {
                cnt++;
            }
        }
        u_nums.push_back({num, cnt});
        int sum = 0, ans = 0;
        n = u_nums.size();
        queue<int> q;
        int s = u_nums[0].first, e = u_nums[n - 1].first;
        for (int i = 0, j = 0; s <= e; s++) {
            int l = s - k, r = s + k;
            // [l, r]
            while (!q.empty() && u_nums[q.front()].first < l) {
                int index = q.front();
                q.pop();
                sum -= u_nums[index].second;
            }
            while (j < n && u_nums[j].first <= r) {
                q.push(j);
                sum += u_nums[j].second;
                j++;
            }
            if (i < n && s == u_nums[i].first) {
                int op = min(sum - u_nums[i].second, numOperations);
                ans = max(ans, u_nums[i].second + op);
                i += 1;
            } else {
                int op = min(sum, numOperations);
                ans = max(ans, op);
            }
        }
        return ans;
    }
};

时间复杂度：$O(nlogn + m)$，$n$是数组大小，$m$是数组中取值范围

1625. 执行操作后字典序最小的字符串（2025.10.19）

原题链接

将字符串考虑为图中的一个结点

当进行累加操作时，字符串x变为字符串y，代表从x设置一条有向边指向y

同理，进行轮转操作时，字符串u变为w，代表从u设置一条有向边指向w

那么就可以通过遍历整个图来找到初始字符串可以转换成的所有字符串，然后返回其中字典序最小的一个即可

code:

class Solution {
public:
    void bfs(const string& state, int a, int b) {
        queue<string> q;
        q.push(state);
        vis.insert(state);
        while (!q.empty()) {
            string st = std::move(q.front());
            q.pop();
            // 两条边, 累加, 或者轮转
            string tmp = st;
            int n = tmp.size();
            for (int i = 1; i < n; i += 2) {
                char ch = (tmp[i] - '0' + a) % 10 + '0';
                tmp[i] = ch;
            }
            if (!vis.contains(tmp)) {
                vis.insert(tmp);
                q.push(tmp);
            }
            tmp = st.substr(n - b);
            tmp += st.substr(0, n - b);
            if (!vis.contains(tmp)) {
                vis.insert(tmp);
                q.push(tmp);
            }
        }
        return;
    }
    string findLexSmallestString(string s, int a, int b) {
        bfs(s, a, b);
        auto it = vis.begin();
        return (*it);
    }
    set<string> vis;
};

时间复杂度：$O(100n)$，其中$n$是字符串的长度

3397. 执行操作后不同元素的最大数量（2025.10.18）

原题链接

不难想到一个贪心思路：将数组从小到大进行排序，设排序后的数组为： $$ a = [x1, x1, x2, x3, x3, ... xk] $$ 数组中可能有多个数字相同，为了尽可能让数组拥有不同元素，则应该：

$a[0] = x1 - k$

$a[1] = x1 - k + 1$

关键在于当相邻的数字不同时的处理：

表面上看，应该令$a[2] = x2 - k$，但$x1 - k + 1$有可能大于或等于$x2 - k$，这代表$x2 - k$这个数字已经被使用过了，因此下一个要使用的数字应该是$max(x1 - k + 2, x2 - k)$

因此，可以保存一个$next_value$或者$last_value$，当相邻两个数不同时，根据上一个数当前被映射为数字，决定当前数字应该变为多少，（注意，如果$x1 - k + 2 > x2 + k$，那么$x2$变或不变都无所谓了，能变的数字肯定都出现过了）

code:

class Solution {
public:
    using i64 = long long;
    int maxDistinctElements(vector<int>& nums, int k) {
        sort(nums.begin(), nums.end());
        int n = nums.size();
        i64 elem = nums[0];
        i64 last = elem - k;
        int cnt = 0;
        for (int i = 0; i < n; i++) {
            if (nums[i] != elem) {
                elem = nums[i];
                last = max(last, elem - k);
            }
            if (last <= elem + k) {
                last++;
                cnt++;
            }
        }
        return cnt;
    }
};

时间复杂度：$O(n)$

2598. 执行操作后的最大MEX（2025.10.16）

原题链接

设nums.length为n，则MEX最大只能为n（当nums = [0, 1, 2, ..., n-1]时）

数组中的每个元素都可以任意加上/减去value（value > 0），考虑每个元素对value的正模值x： $$ nums[i] \equiv x \pmod{value} $$ 如果多个元素的正模值相同，则明显可以将这些元素转化为：[x, x + value, ..., x + k * value]，使得改变后的数组尽可能被不同的数字填充

因此，可以统计不同正模值在原数组中出现的频数，然后将其转化为上述形式（只记录在n以内的数字即可），然后遍历0~n，如果某个数不能由原数组的数转化而来，则该数即是答案

code:

class Solution {
public:
    int findSmallestInteger(vector<int>& nums, int value) {
        int n = nums.size();
        if (value == 1) {
            return n;
        }
        unordered_map<int, int> frequency;
        vector<int> mex(n + 1, 0);
        for (int i = 0; i < n; i++) {
            int m = nums[i] % value;
            if (m < 0) {
                m += value;
            }
            frequency[m]++;
        }
        for (auto& [k, v] : frequency) {
            int cnt = v;
            int i = k;
            while (cnt > 0) {
                if (i <= n)
                    mex[i] = 1;
                i += value;
                cnt -= 1;
            }
        }
        for (int i = 0; i < n; i++) {
            if (mex[i] == 0) {
                return i;
            }
        }
        return n;
    }
};

时间复杂度：$O(n)$

3186. 施咒的最大总伤害（2025.10.11）

原题链接

先排序，很明显，当两个咒语的power值相同时，那两个咒语一定要一起选，所以合并power值相同的咒语**（以[power[i], k * power[i]]的方式，其中k代表有k个power值相同的咒语）**

处理完毕后，序列中所有咒语的power值各不相同，然后按照power值排序，设最后得到的序列为a，题目要求的是某个序列power值和的最大值，可以从动态规划集合论的角度来思考：

状态表示：dp[i]表示以a[i]的power值为最大power值的子序列集合（即该集合一定选择a[i]对应的咒语，并且由于a序列中power值各不相同且从小到大排序，所以dp[i]对应的集合各不相同）
状态属性：集合中的最大值
状态转移：
- 首先考虑如何划分集合，集合的相同点是子序列中最大的power值是a[i]的power值，则可以根据第二大的power值对集合进行划分，于是集合可以被划分为：
 1. 以a[0]的power值为最大的power值的子序列集合
 2. 以a[1]的power值为最大的power值的子序列集合
 
 ...
 3. 以a[j]的power值为最大的power值的子序列集合
 其中$j < i, a[j].power < a[i].power - 2$
- 转移公式： $$ dp(i) = max(dp(j)) + a[i].sumpower $$ 其中： $$ j < i, a[j].power < a[i].power - 2 $$
优化：由于a序列是排过序的，因此在遍历a[i]时，只需要一个下标指向$max(dp(j))$，随着i的移动，判断$a[j].power < a[i].power - 2$后更新$max(dp(j))$，就能实现一次遍历求出答案

code：

class Solution {
public:
    using i64 = long long;
    long long maximumTotalDamage(vector<int>& power) {
        int n = power.size();
        unordered_map<int, i64> hashmap;
        for (int i = 0; i < power.size(); i++) {
            hashmap[power[i]] += power[i];
        }
        vector<int> keys;
        for (auto& [key, _] : hashmap) {
            keys.push_back(key);
        }
        sort(keys.begin(), keys.end());
        // dp[i]: 表示用power值为keys[i]的咒语集合
        // 集合最大值
        // max(<(keys[i] - 2)) + map(keys[i])
        int m = keys.size();
        vector<i64> dp(m + 1, 0);
        dp[0] = hashmap[keys[0]];
        i64 before = 0;
        for (int i = 1, j = 0; i < m; i++) {
            while (j < i && keys[j] < keys[i] - 2) {
                before = max(before, dp[j]);
                j++;
            }
            dp[i] = hashmap[keys[i]] + before;
        }
        i64 res = 0;
        for (int i = 0; i < m; i++) {
            res = max(res, dp[i]);
        }
        return res;
    }
};

时间复杂度：$O(nlogn)$

1488. 避免洪水泛滥（2025.10.7）

原题链接

从左到右遍历抽干日，对于一个抽干日，其可能有多个湖泊进行选择，将这些可选择的湖泊（第i个可选择的湖泊）上次下雨和该次下雨时间记为$[last_i, now_i]$，按照贪心的思想，应该将其按照$now_i$从小到大进行排序，即越早可能泛洪的湖泊应该更早被抽水，$now_i$更大的湖泊可以尽可能的交给后面的抽干日去处理

但是固定抽干日，排序该日可选择的不同湖泊在代码实现上比较困难，于是可以考虑换一个角度，固定湖泊，找寻可选择的抽干日：

从左到右遍历湖泊时，假设湖泊$j$会发生洪水，根据其上一次的下雨时间$last$和本次下雨时间$now$，找寻$(last, now)$内的抽干日，假设这些抽干日有$cnt$个，将其从小到大进行排列，根据贪心思想，应该选择距离$last$最近的抽干日，而越晚的抽干日，灵活性越大，可以用于抽干更晚装满的湖，即越晚的抽水日应该留到后面给$now$更大的湖泊使用

以上两种贪心思想等价，但是第二种在代码实现上更简单：利用哈希表记录每个湖泊上次的下雨时间，并将所有的抽干日存储到set中，然后遍历下雨日，在set中找到第一个$> last$的抽干日，并判断其是否合法即可

code：

class Solution {
public:
    vector<int> avoidFlood(vector<int>& rains) {
        int n = rains.size();
        vector<int> ans(n, -1);
        unordered_map<int, int> last_rain;
        set<int> dry_days;
        for (int i = 0; i < n; i++) {
            if (rains[i] == 0) {
                dry_days.insert(i);
            }
        }
        for (int i = 0; i < n; i++) {
            if (rains[i] > 0) {
                if (last_rain.contains(rains[i])) {
                    int j = last_rain[rains[i]];
                    // > j的第一个, 要用set的upper_bound方法, algorithm的方法会退化为线性时间
                    auto it = dry_days.upper_bound(j);
                    // 必须在第i天之前
                    if (it == dry_days.end()) return {};
                    if ((*it) >= i) return {};
                    ans[(*it)] = rains[i];
                    dry_days.erase(it);
                }
                last_rain[rains[i]] = i;
            }
        }
        // 如果抽干日比下雨日更多，选择湖泊1
        for (int i = 0; i < n; i++) {
            if (rains[i] == 0 && ans[i] == -1) {
                ans[i] = 1;
            }
        }
        return ans;
    }
};

时间复杂度：$O(nlogn)$

778. 水位上升的泳池中游泳（2025.10.6）

原题链接

题目提到在方格之间移动不花费时间，求最小的时间t，使得能从(0, 0)移动到(n-1, n-1)

答案t一定有上下界（因为格子中的数值有限），下界为0，上界为$n^2 - 1$，那么可以考虑二分答案：

二分答案t
判断水位为t时，能否从(0, 0)到(n - 1, n - 1)
- 如果可以，记录答案，减小上界
- 否则，增大下界

从(0, 0)进行BFS，根据当前水位，可以判断能否到达(n-1, n-1)

code：

class Solution {
public:
    bool bfs(queue<pair<int, int>> &q, vector<vector<int>> &grid, int t) {
        int m = grid.size();
        int n = grid[0].size();
        vector<vector<int>> vis(m, vector<int>(n, 0));
        if (grid[0][0] > t) return false;
        q.push({0, 0});
        vis[0][0] = 1;
        while (!q.empty()) {
            auto point = q.front();
            q.pop();
            int h = max(t, grid[point.first][point.second]);
            for (int i = 0; i < 4; i++) {
                int nx = point.first + dx[i];
                int ny = point.second + dy[i];
                if (nx < 0 || nx >= m || ny < 0 || ny >= n || vis[nx][ny] != 0 || h < grid[nx][ny])
                    continue;
                vis[nx][ny] = 1;
                q.push({nx, ny});
            }
        }
        return vis[m - 1][n - 1] == 1;
    }
    int swimInWater(vector<vector<int>>& grid) {
        int n = grid.size();
        queue<pair<int, int>> q;
        int l = INT_MAX, r = INT_MIN;
        for (int i = 0; i < n; i++) {
            for (int j = 0; j < n; j++) {
                l = min(l, grid[i][j]);
                r = max(r, grid[i][j]);
            }
        }
        int ans = -1;
        while (l <= r) {
            int mid = l + (r - l) / 2;
            if (bfs(q, grid, mid)) {
                r = mid - 1;
                ans = mid;
            } else {
                l = mid + 1;
            }
        }
        return ans;
    }
    constexpr static int dx[] = {0, 0, 1, -1};
    constexpr static int dy[] = {1, -1, 0, 0};
};

时间复杂度：$O(n^2log(n^2))$

417. 太平洋大西洋水流问题（2025.10.5）

原题链接

可以把二维矩阵看做一个图，单元格抽象为点，设高度为$h$，针对两个相邻单元格$p_1$，$p_2$，其对应的高度为$h_1$，$h_2$，如果有$h_1 >= h2$，则从$p_1$向$p_2$连接一条边。

题目要求出能够流向PO和AO的单元格，一种想法是在原先的二维矩阵上围上一圈结点，并设置这些结点的属性（标识不同的海洋），然后从每个结点开始BFS遍历，只要其能够同时到达拥有两种属性的结点，该结点就符合题意，时间复杂度为$O(V(V + E))$，其中，$V$是结点个数，$E$是边数，在本题中都是$10^4$数量级，用于通过题目显然不现实。

可以反向思考，从PO和AO向单元格开始流，只需要翻转一下原先边的方向：

显然，第一行第一列是PO能够流向的结点，将这些结点塞入队列，进行一次BFS，就能知道有哪些结点可以流向PO
同理，最后一行最后一列是AO能流向的结点，同样一次BFS，能知道有哪些结点可以流向AO
对于上面求得的两个集合，做一个交集，就是既能流向PO，也能流向AO的结点

code：

class Solution {
public:
    void bfs(queue<pair<int, int>> &q, vector<vector<int>>& heights, vector<vector<int>>& vis) {
        int m = heights.size();
        int n = heights[0].size();
        while (!q.empty()) {
            auto point = q.front();
            q.pop();
            int h = heights[point.first][point.second];
            for (int i = 0; i < 4; i++) {
                int nx = point.first + dx[i];
                int ny = point.second + dy[i];
                if (nx < 0 || nx >= m || ny < 0 || ny >= n || vis[nx][ny] == 1 || heights[nx][ny] < h)
                    continue;
                vis[nx][ny] = 1;
                q.push({nx, ny});
            }
        }
    }

    vector<vector<int> > pacificAtlantic(vector<vector<int> > &heights) {
        int m = heights.size();
        int n = heights[0].size();
        vector<vector<int>> pacific_vis(m, vector<int>(n, 0));
        vector<vector<int>> altantic_vis(m, vector<int>(n, 0));
        queue<pair<int, int>> q_pacific, q_altantic;
        for (int i = 0; i < n; i++) {
            pacific_vis[0][i] = 1;
            q_pacific.push({0, i});
            altantic_vis[m - 1][i] = 1;
            q_altantic.push({m - 1, i});
        }
        for (int i = 0; i < m; i++) {
            if (pacific_vis[i][0] == 0) {
                pacific_vis[i][0] = 1;
                q_pacific.push({i, 0});
            }
            if (altantic_vis[i][n - 1] == 0) {
                altantic_vis[i][n - 1] = 1;
                q_altantic.push({i, n - 1});
            }
        }
        bfs(q_pacific, heights, pacific_vis);
        bfs(q_altantic, heights, altantic_vis);
        vector<vector<int>> ans;
        for (int i = 0; i < m; i++) {
            for (int j = 0; j < n; j++) {
                if (pacific_vis[i][j] && altantic_vis[i][j]) {
                    ans.push_back({i, j});
                }
            }
        }
        return ans;
    }

    constexpr static int dx[] = {-1, 1, 0, 0};
    constexpr static int dy[] = {0, 0, 1, -1};
};

时间复杂度：$O(V + E)$，其中，$V = mn$，$E = cV$（$c$是一个常数）

11. 盛最多水的容器（2025.10.4）

原题链接

不妨先考虑只有两条线，那么根据短板效应，两条线中高度最短的那个决定了水的高度：

考虑向中间插入一条线（长或短）：

分析如下：

考虑$l_1$，$l_2$中较短的那条线（假设是$l_1$），由于$l_2$在右端点，设在$l_1$和$l_2$之间的为$l_i$，则显然$l_1$与$l_i$组成的容器容量不会超过$l_1$与$l_2$组成的容器容量

于是可以跳过中间这部分的计算，直接向右移动$l_1$

同理，如果$l_2$较短，向左移动$l_2$，直到$l_1 >= l_2$

每移动一次，就计算一次容量，并保存最大容量

code：

class Solution {
public:
    int maxArea(vector<int>& height) {
        int l = 0, r = static_cast<int>(height.size()) - 1;
        int ans = 0;
        while (l < r) {
            ans = max(ans, min(height[l], height[r]) * (r - l));
            if (height[l] < height[r]) {
                l++;
            } else {
                r--;
            }
        }
        return ans;
    }
};

时间复杂度：$O(n)$

42. 接雨水

原题链接

407. 接雨水 II（2025.10.3）

原题链接

该题不能向接雨水一样使用单调栈来做（不能遍历所有的行和列然后取能接雨水的最小值）

但同样可以考虑木桶效应（因为最外面一圈格子不可能存下雨水），接雨水考虑的是一维中左右两端的木板，本题是二维，则考虑上下左右四端的木板。根据木桶效应，桶中能装多少水由最短的那块木板，那么应该从四端最短的木板找起，由于其是最短的木板，设其高度为$h$，那么：

如果与其相邻的格子是木板，不做处理
如果与其相邻的格子不是木板，考虑其高度$hn$：
- 如果$hn >= h$，那么该格子保存不了雨水，并且由于其比木板更高，原先的木板就没用了，该格子会代替原木板变为高度为$hn$的木板。
- 如果$hn < h$，那么该格子能够保存$h - hn$单位的雨水，将这些雨水加入$ans$后，该格子不会能够接更多的雨水了，可以将其看做新的高度为$h$的木板，以此来维护新的木桶。

可以使用最小堆来保存四周的木板高度，然后从最低的木板开始遍历，直到堆为空，$ans$中保存的是收集雨水的总和

code：

class Solution {
public:
    struct Point {
        int x;
        int y;
        int h;
        friend bool operator > (const Point& lhs, const Point& rhs) {
            return lhs.h > rhs.h;
        }
    };
    int trapRainWater(vector<vector<int>>& heightMap) {
        int m = heightMap.size();
        int n = heightMap[0].size();
        if (m < 3 || n < 3) return 0;
        vector<int> visited((m + 1) * (n + 1), 0);
        priority_queue<Point, vector<Point>, greater<>> heap;
        auto arrMap = [n](int i, int j) -> int {
            return i * n + j;
        };
        heap.push({0, 0, heightMap[0][0]}); visited[arrMap(0, 0)] = 1;
        heap.push({0, n - 1, heightMap[0][n - 1]}); visited[arrMap(0, n - 1)] = 1;
        heap.push({m - 1, 0, heightMap[m - 1][0]}); visited[arrMap(m - 1, 0)] = 1;
        heap.push({m - 1, n - 1, heightMap[m - 1][n - 1]}); visited[arrMap(m - 1, n - 1)] = 1;
        for (int i = 1; i < n - 1; i++) {
            heap.push({0, i, heightMap[0][i]}); visited[arrMap(0, i)] = 1;
            heap.push({m - 1, i, heightMap[m - 1][i]}); visited[arrMap(m - 1, i)] = 1;
        }
        for (int j = 1; j < m - 1; j++) {
            heap.push({j, 0, heightMap[j][0]}); visited[arrMap(j, 0)] = 1;
            heap.push({j, n - 1, heightMap[j][n - 1]}); visited[arrMap(j, n - 1)] = 1;
        }
        int remain = m * n - (2 * m + 2 * n - 4);
        int ans = 0;
        while (remain > 0) {
            auto p = heap.top();
            heap.pop();
            for (int i = 0; i < 4; i++) {
                int nx = p.x + dx[i], ny = p.y + dy[i];
                if (nx >= 0 && nx < m && ny >= 0 && ny < n) {
                    if (visited[arrMap(nx, ny)]) continue;
                    int h = heightMap[nx][ny];
                    visited[arrMap(nx, ny)] = 1;
                    remain--;
                    if (h >= p.h) {
                        heap.push({nx, ny, h});
                    } else {
                        ans += p.h - h;
                        heap.push({nx, ny, p.h});
                    }
                }
            }
        }
        return ans;
    }
    constexpr static int dx[] = {0, 0, 1, -1};
    constexpr static int dy[] = {1, -1, 0, 0};
};

时间复杂度：二维矩阵$m$行$n$列，时间复杂度为$O(mnlog(mn))$

1546. 和为目标值且不重叠的非空子数组的最大值（2025.10.2）

原题链接

子数组是连续的，所以题目要求连续子序列和为target的最大数量（连续子序列相互不重叠），于是可以抽象为以下模型（假设一条线代表从i到j的子序列和为target）：

该模型即求出最多的不相交的线段数量线段覆盖

根据贪心算法，将所有的线段以[start, end]的形式表示，根据end从小到大进行排序，然后依次遍历选择，即哪个线段在前就先选哪个

对应的本题，从头遍历nums数组，对于一个数nums[i]，如果能找到一个start，使得[start, i]的和为target，就将序列数+1，问题的关键在于如何求start坐标

可以使用前缀和，当遍历nums时，同时记录前缀和sums，如果存在start，则sums[i] - sums[start - 1] = target

即sums[start - 1] = sums[i] - target

将前缀和用哈希表保存即可快速搜寻sums[start - 1]

code：

class Solution {
public:
    int maxNonOverlapping(vector<int>& nums, int target) {
        int ans = 0;
        int i = 1;
        int n = nums.size();
        vector<int> sum(n + 1, 0);
        while (i <= n) {
            unordered_set<int> s;
            s.insert(0);
            while (i <= n) {
                sum[i] = sum[i - 1] + nums[i - 1];
                if (s.contains(sum[i] - target)) {
                    ans++;
                    break;
                }
                s.insert(sum[i]);
                i += 1;
            }
            if (i > n) break;
            sum[i] = 0;
            i = i + 1;
        }
        return ans;
    }
};

时间复杂度：$O(n)$

1948. 删除系统中的重复文件夹（2025.9.30）

原题链接

很容易想到使用Trie结构保存结点，再利用哈希表存储每个结点的子树结构，在遍历树时，如果不同节点有相同的子树结构，就将这些结点删去

问题在于如何用哈希表存储每个结点的子树结构：

一个方法是将一个结点的子树映射为相同的字符串，这需要做到

字符串需要包含子树所有节点的文件夹名
字符串要能够表达结点的父子关系

考虑针对某一个结点，对其子节点的遍历过程，将向下递的动作用一个非字母字符表示，向上归的动作用另一个非字母字符表示，就可以描述一颗树的形状，比如x结点有两个叶子节点y，z，可以表示为x(y)(z)

一般的，定义如下括号表达式：

对于叶子结点，设其文件名为S，则其括号表达式为S
对于任意子树x，设x的儿子为y1，y2，...，则子树x的括号表达式为：

x文件夹名 + (子树y1的表达式) + (子树y2的表达式) + ...
为了括号表达式的唯一性，在求出y1，y2，...的表达式后，对这些表达式进行排序再拼接，就可以避免下面这种情况（子树相同但表达式不同）
```
	  x        x
   / \      / \
  y   z    z   y
```

代码流程：

构建字典树
生成每个结点的括号表达式：

先将每个结点的子树表达式拼接（即(子树y1的表达式) + (子树y2的表达式) + ...），记录到哈希表中
- 如果该表达式是首次生成，将表达式和对应的子树根节点x保存到哈希表中
- 否则文件夹出现重复，把当前根节点x和哈希表中记录的根节点都标记为删除
DFS遍历Trie树，仅遍历未被删除的结点，同时记录路径上的文件夹名

code:

class Solution {
public:
    struct Node {
        Node() :name(""), deleted(false) {}
        Node(string ne) : name(ne), deleted(false) {}

        ~Node() {
            clear();
        }
        void clear() {
            for (auto it = children.begin(); it != children.end(); it++) {
                if (it->second) {
                    it->second->clear();
                    delete it->second;
                }
                it->second = nullptr;
            }
        }
        string name;
        unordered_map<string, Node*> children;
        bool deleted;
    };
    void constructTrie(Node *node, vector<string> &path) {
        for (string name : path) {
            if (!node->children.contains(name)) {
                node->children[name] = new Node(name);
            }
            node = node->children[name];
        }
    }
    string generateHash(unordered_map<string, Node*> &hash, Node *root) {
        if (root == nullptr) {
            return "";
        }
        if (root->children.empty()) {
            return root->name;
        }
        string res("");
        vector<string> sub_hash;
        for (auto&& child : root->children) {
            sub_hash.push_back("(" + generateHash(hash, child.second) + ")");
        }
        sort(sub_hash.begin(), sub_hash.end());
        for (auto&& sub_hash : sub_hash) {
            res += sub_hash;
        }
        // compare
        if (hash.contains(res)) {
            root->deleted = true;
            hash[res]->deleted = true;
        } else {
            hash[res] = root;
        }
        res = root->name + res;
        return res;
    }
    void dfs(Node* root, vector<string> &path, vector<vector<string>> &res) {
        if (root == nullptr || root->deleted) {
            return;
        }
        path.push_back(root->name);
        res.push_back(path);
        for (auto&& child : root->children) {
            if (!child.second->deleted)
                dfs(child.second, path, res);
        }
        path.pop_back();
    }
    vector<vector<string>> deleteDuplicateFolder(vector<vector<string>>& paths) {
        Node* node = new Node("/");
        for (auto &&path : paths) {
            constructTrie(node, path);
        }
        unordered_map<string, Node*> hash;
        generateHash(hash, node);
        vector<vector<string>> res;
        vector<string> path;
        for (auto&& child : node->children) {
            dfs(child.second, path, res);
        }
        delete node;
        return res;
    }
};

1039. 多边形三角剖分的最低得分（2025.9.29）

原题链接

该题的考点是区间动态规划，仍然从集合的角度来分析

状态表示：dp[l, r]表示由边(l, l + 1)， (l + 1, l + 2)，...，(r - 1, r)，(r, l)组成的多边形被剖分成不同的三角形集合
状态属性：集合中乘积和的最小值
状态转移：
- 首先考虑如何划分集合：
  
  由于多边形最后最划分为多个三角形，那么多边形的边都是各个三角形的边，我们以(r, l)这条边隶属于哪个三角形来划分集合：
  
  (r, l)的两个端点l, r, 只需要再加一个端点就可以组成三角形，设端点为k，则k = l + 1, ... r - 1
于是由k和边(r, l)组成的三角形将原多边形划分为了三个部分：
```
     1. [l, k]：以(l, l + 1),...,(k, l)边组成的新多边形
     2. [k, r]：以(k, k + 1),...,(r, k)边组成的新多边形
     3. k&(r, l)：以点k和边(r, l)组成的三角形
```
- 于是状态转移公式：
$$ dp[l, r] = min(dp[l, k] + dp[k, r] + v[l] * v[r] * v[k]) $$

为什么选择(r, l)边作为三角形的一个边处理？

因为状态表示中无法直接涉及到(r, l)，而直接使用(r, l)边的三角形又能够将集合划分为不同的部分来完成状态的转移

code：

class Solution {
public:
    int minScoreTriangulation(vector<int>& values) {
        constexpr int N = 50;
        constexpr int INF = 0x3f3f3f3f;
        vector<vector<int>> dp(N, vector<int>(N, INF));
        int n = values.size();
        for (int i = 0; i < n; i++) {
            dp[i][i] = 0;
            if (i + 1 < n) {
                dp[i][i + 1] = 0;
            }
        }
        for (int len = 2; len < n; len++) {
            for (int l = 0; l < n; l++) {
                int r = l + len;
                if (r >= n) continue;
                // k: l + 1 -> r - 1
                for (int k = l + 1; k < r; k++) {
                    dp[l][r] = min(dp[l][r], 
                        dp[l][k] + dp[k][r] + values[l] * values[k] * values[r]);
                }
            }
        }
        return dp[0][n - 1];
    }
};

时间复杂度：$O(n^3)$

2040. 两个有序数组的第K小乘积（2025.9.28）

原题链接

直接枚举$n^2$显然是不现实的，注意到两个数组的乘积值域在$[-10^{10}, 10^{10}]$之间

因此可以考虑对答案进行二分：

对于一个数mid，设两个数组的乘积中小于mid的数有cnt个，那么：

cnt < k，则mid有可能是答案，提高答案的下界
cnt >= k，则mid不可能是答案，降低答案的上界

于是问题转化为如何求两个数组的乘积中小于mid的个数

二分

由nums1 × nums2 < mid（nums1不为0），得：

nums2 < mid / nums1（nums1 > 0）
nums2 > mid / nums1（nums1 < 0）

两个数组都是排好序的，所以在遍历第一个数组的时候，利用二分求出小于/大于目标数的数字有多少个即可

code:

class Solution {
public:
    using i64 = long long;
    bool check(vector<int>& nums1, vector<int> &nums2, i64 k, i64 num) {
        // 找nums1 * nums2中，< num的个数cnt，与k比较
        // cnt < k -> true
        // cnt >= k -> false
        i64 cnt = 0;
        for (int n1 : nums1) {
            if (n1 == 0) {
                if (num > 0) cnt += nums2.size();
                continue;
            } 
            i64 n2 = num / n1;
            auto up_it = upper_bound(nums2.begin(), nums2.end(), n2);
            auto low_it = lower_bound(nums2.begin(), nums2.end(), n2);
            if (n1 > 0) {
                int d1 = distance(nums2.begin(), low_it);
                int d2 = distance(nums2.begin(), up_it);
                if (num > 0 && num % n1 != 0) {
                    cnt += max(0, d2);
                } else {
                    cnt += max(0, d1);
                }
            } else {
                int d1 = distance(low_it, nums2.end());
                int d2 = distance(up_it, nums2.end());
                if (num > 0 && num % n1 != 0) {
                    cnt += max(0, d1);
                } else {
                    cnt += max(0, d2);
                }
            }
        }
        return cnt < k;
    }
    long long kthSmallestProduct(vector<int>& nums1, vector<int>& nums2, long long k) {
        i64 low = min({1ll * nums1.front() * nums2.front(), 1ll * nums1.front() * nums2.back(),
                                1ll * nums1.back() * nums2.front(), 1ll * nums1.back() * nums2.back()});
        i64 high = max({1ll * nums1.front() * nums2.front(), 1ll * nums1.front() * nums2.back(),
                                1ll * nums1.back() * nums2.front(), 1ll * nums1.back() * nums2.back()});
        i64 ans = 0;
        while (low <= high) {
            i64 mid = (low + high) >> 1;
            if (check(nums1, nums2, k, mid)) {
                low = mid + 1;
                ans = mid;
            } else {
                high = mid - 1;
            }
        }
        return ans;
    }
};

时间复杂度：$O(n (logn)(logk))$

矩阵

数组单增，负数正数同时存在，我们可以将分界线列出，假设：

nums1[0~pos1]是负数，nums1[pos1~n1]是正数
nums2[0~pos2]是负数，nums1[pos1~n2]是正数

将nums1[0~pos1]与nums2[0~pos2]各个数分别相乘，观察性质(以两个数组中元素都大于0为例)：

不难发现，左上角是最小值，随行增加，随列增加，右下角为最大值，之后求该矩阵中小于mid的个数，参考leetcode-240

具体做法是利用双指针，指向矩阵右上角的坐标，计算矩阵中对应的位置元素，如果该元素大于等于mid，向左移动，否则向下移动，直到找到最后一个小于mid的元素，移动的过程中，每找到一个小于mid的元素，就累加该行的个数

code：

class Solution {
public:
    using i64 = long long;
    bool check(vector<int>& nums1, vector<int> &nums2, i64 k, i64 num) {
        // 找nums1 * nums2中，< num的个数cnt，与k比较
        // cnt < k -> true
        // cnt >= k -> false
        i64 cnt = 0;
        for (int i = 0, j = pos2; i <= pos1 && j >= 0;) {
            if (1ll * nums1[i] * nums2[j] >= num) {
                i++;
            }
            else {
                cnt += (pos1 - i + 1);
                j--;
            }
        }
        for (int i = 0, j = pos2 + 1; i <= pos1 && j < nums2.size();) {
            if (1ll * nums1[i] * nums2[j] >= num) {
                j++;
            } else {
                cnt += (nums2.size() - j);
                i++;
            }
        }
        for (int i = pos1 + 1, j = 0; i < nums1.size() && j <= pos2;) {
            if (1ll * nums1[i] * nums2[j] >= num) {
                i++;
            } else {
                cnt += (nums1.size() - i);
                j++;
            }
        }
        for (int i = pos1 + 1, j = nums2.size() - 1; i < nums1.size() && j > pos2;) {
            if (1ll * nums1[i] * nums2[j] >= num) {
                j--;
            } else {
                cnt += (j - pos2);
                i++;
            }
        }
        return cnt < k;
    }
    long long kthSmallestProduct(vector<int>& nums1, vector<int>& nums2, long long k) {
        i64 low = min({1ll * nums1.front() * nums2.front(), 1ll * nums1.front() * nums2.back(),
                                1ll * nums1.back() * nums2.front(), 1ll * nums1.back() * nums2.back()});
        i64 high = max({1ll * nums1.front() * nums2.front(), 1ll * nums1.front() * nums2.back(),
                                1ll * nums1.back() * nums2.front(), 1ll * nums1.back() * nums2.back()});
        i64 ans = 0;
        for (int i = 0; i < nums1.size(); i++) {
            if (nums1[i] < 0) pos1 = i;            
        }
        for (int i = 0; i < nums2.size(); i++) {
            if (nums2[i] < 0) pos2 = i;            
        }
        while (low <= high) {
            i64 mid = (low + high) >> 1;
            if (check(nums1, nums2, k, mid)) {
                low = mid + 1;
                ans = mid;
            } else {
                high = mid - 1;
            }
        }
        return ans;
    }
private:
    int pos1{-1};
    int pos2{-1};
};

时间复杂度：$O(nlogk)$

976. 三角形的最大周长（2025.9.28）

原题链接

枚举三条边a，b，c，三角形三边需要满足：

a + b > c
a + c > b
b + c > a

如果按边大小排序，设c >= b >= a，能简化为一个条件：

a + b > c

将边从大到小排序，在枚举一个最长边nums[i] = c时，能使得三角形周长最大的合法集合只能为nums[i], nums[i + 1], nums[i + 2]

如果nums[i], nums[i + 1], nums[i + 2]合法，则三条边组成的三角形周长最大
如果不合法，那么以nums[i] = c作为最长边将不能和nums[i + 3]及之后的边组成三角形

code:

class Solution {
public:
    int largestPerimeter(vector<int>& nums) {
        sort(nums.begin(), nums.end(), greater<>());
        int ans = 0;
        for (int i = 2; i < nums.size(); i++) {
            // a <= b <= c
            int a = nums[i], b = nums[i - 1], c = nums[i - 2];
            if (c < a + b) {
                ans = a + b + c;
                break;
            }
        }
        return ans;
    }
};

时间复杂度： $O(n)$

812. 最大三角形面积（2025.9.27）

原题链接

枚举三个点A，B，C，设三条边的边长为a，b，c

根据海伦公式（或者用余弦定理）得出：

$S = \sqrt {p (p - a) (p - b) (p - c)}$

其中，$p = \frac {a + b + c} {2}$

注意，如果三个点x坐标或y坐标相同，三角形不合法

code:

class Solution {
public:
    double getDistance(int x1, int y1, int x2, int y2) {
        double d2 = pow(x1 - x2, 2) + pow(y1 - y2, 2);
        return sqrt(d2);
    }
    double largestTriangleArea(vector<vector<int>>& points) {
        int n = points.size();
        double ans = INT_MIN;
        for (int i = 0; i < n; i++) {
            for (int j = i + 1; j < n; j++) {
                for (int k = j + 1; k < n; k++) {
                    auto &pi = points[i];
                    auto &pj = points[j];
                    auto &pk = points[k];
                    if (pi[0] == pj[0] && pi[0] == pk[0]) continue;
                    if (pi[1] == pj[1] && pi[1] == pk[1]) continue;
                    double a = getDistance(pi[0], pi[1], pj[0], pj[1]);
                    double b = getDistance(pi[0], pi[1], pk[0], pk[1]);
                    double c = getDistance(pj[0], pj[1], pk[0], pk[1]);
                    double sum = (a + b + c) / 2;
                    ans = max(ans, sqrt(sum * (sum - a) * (sum - b) * (sum - c)));
                }
            }
        }
        return ans;
    }
};

时间复杂度： $O(n^3)$

611. 有效三角形的个数（2025.9.26）

原题链接

排序 + 二分

将边长度按从小到大排序

因为需要三条边，无论如何都要枚举两条边a，b，不妨从小到大进行枚举（即a <= b）

设第三条边为c，那么c需要满足：

a + b > c
a + c > b
b + c > a

在枚举c的过程中，为了避免重复，c必须满足c >= b

故上述条件简化为：

a <= b <= c
a + b > c

设a，b对应的下标分别为i，j，那么c的下标范围是：

[l, r] = [j + 1, lower_bound(nums.begin() + j + 1, nums.end(), a + b)] ，如果r < l，则没有与a，b对应的c存在 code：

class Solution {
public:
    int triangleNumber(vector<int>& nums) {
        // 枚举a, b
        // c: a + b > c, a + c > b, b + c > a
        // -> c < a + b && c > b - a && c > a - b
        sort(nums.begin(), nums.end());
        int ans = 0;
        for (int i = 0; i < nums.size(); i++) {
            for (int j = i + 1; j < nums.size(); j++) {
                int k = j + 1;
                int start = max(nums[j] - nums[i], nums[i] - nums[j]);
                int end = nums[i] + nums[j];
                auto l = upper_bound(nums.begin() + k, nums.end(), start);
                auto r = lower_bound(nums.begin() + k, nums.end(), end);
                if (r - l < 0) continue;
                ans += (r - l);
            }
        }
        if (ans < 0) ans = 0;
        return ans;
    }
};

时间复杂度: $O(n^2logn)$

排序 + 双指针

二分的代码不难发现一个规律：枚举a，b后，寻找c时，只需要找到满足c < a + b的最大的c

换句话说，对于前一个b，有c < a + b，对于下一个b，也有可能有c < a + b

因此，我们只需要维护c所在区间的最大值下标

条件是：只要c < a + b，就让c的下标右移

c所在区间的最小值下标一定是b的下标+1

于是可以采用双指针，在枚举b的同时，维护c当前可能的最大值下标

code:

class Solution {
public:
    int triangleNumber(vector<int>& nums) {
        // 枚举a, b
        // c: a + b > c
        // a <= b <= c
        sort(nums.begin(), nums.end());
        int ans = 0;
        for (int i = 0; i < nums.size(); i++) {
            for (int j = i + 1, k = j + 1; j < nums.size(); j++) {
                // k是c合法范围内的最大值下标
                k = max(k, j + 1);
                int end = nums[i] + nums[j];
                while (k < nums.size() && nums[k] < end) {
                    k++;
                }
                ans += max(0, k - j - 1);
            }
        }
        return ans;
    }
};

时间复杂度：$O(n^2)$

120. 三角形最小路径和（2025.9.25）

原题链接

三角形dp，从集合的角度分析：

状态表示：dp(i, j)：从triangle(0, 0)走到(i, j)的不同路径组成的集合
状态计算：集合中路径总和的最小值
状态转移：根据路径中的最后一次转移来划分集合
- 从(i - 1, j)走到(i, j)
- 从(i - 1, j - 1)走到(i, j)
- 转移公式： $$ dp(i, j) = \begin{cases} triangle(i, j), & i = 0, j = 0 \ dp(i - 1, j) + triangle(i, j), & i > 0, j = 0 \ min(dp(i - 1, j), dp(i - 1, j - 1)) + triangle(i, j) & i > 0, j > 0 \ \end{cases} $$
优化：注意到在计算dp(i, ...)时，只需要dp(i - 1, ...)，所以可以将状态优化为1维数组，在计算状态时只保留上一层的状态dp(j)

code:

class Solution {
public:
    int minimumTotal(vector<vector<int>>& triangle) {
        int ans = INT_MAX;
        vector<int> dp(triangle.size(), INT_MAX / 2);
        dp[0] = triangle[0][0];
        for (int i = 1; i < triangle.size(); i++) {
            for (int j = triangle[i].size() - 1; j >= 0; j--) {
                int old_dp = INT_MAX / 2;
                if (j >= 1) old_dp = dp[j - 1];
                dp[j] = min(dp[j], old_dp) + triangle[i][j];
            }
        }
        for (int i = 0; i < dp.size(); i++) {
            ans = min(ans, dp[i]);
        }
        return ans;
    }
};

时间复杂度： $O(n^2)$

166. 分数到小数（2025.9.24）

原题链接

问题的难度在于如何判定循环小数的范围

使用长除法观察示例$\frac {4} {333} = 0.\dot 0 \dot 1 \dot 2$：

小数点后第1位为0时，对应的被除数为40
小数点后第2位为1时，对应的被除数为400
小数点后第3位为2时，对应的被除数为670

以此类推...，小数点后第4位开始循环，对应的被除数为40

不难发现，当小数点后开始循环时，对应的被除数一定已经出现过，可以使用哈希表来保存出现过的被除数，当一个被除数重复出现时，说明有循环小数并已经开始循环

于是问题来到了如何判断哪一部分是循环小数，我们可以通过存储下面两个信息来解决：

小数点后第k位对应的被除数
小数点后当前的总位数n

当被除数重复时，小数点后第k位~第n位就是循环小数所在的部分，前者可以用hashmap解决，后者可以开辟一个额外变量来记录

由于题目中分子，分母的范围在[INT_MIN, INT_MAX]，所以在计算时最好使用long long，同时将小数点前和小数点后的计算分开，更加清晰

code:

class Solution {
public:
    using i64 = long long;
    void transform_quotient(string &ans, i64 quotient) {
        string res("");
        while (quotient > 0) {
            int mod = quotient % 10;
            quotient /= 10;
            res += static_cast<char>(mod + '0');
        }
        if (res.size() == 0) return;
        for (int i = res.size() - 1; i >= 0; i--) {
            ans += res[i];
        }
    }
    string fractionToDecimal(int numerator, int denominator) {
        bool neg1 = numerator < 0;
        bool neg2 = denominator < 0;
        i64 numerator1 = abs(numerator * 1ll);
        i64 denominator1 = abs(denominator * 1ll);
        string ans("");
        // 小数点前
        if (numerator1 >= denominator1) {
            while (numerator1 >= denominator1) {
                i64 quotient = numerator1 / denominator1;
                numerator1 %= denominator1;
                transform_quotient(ans, quotient);
            }
        } else {
            ans += '0';
        }
        // 小数点后
        if (numerator1 != 0){
            ans += '.';
            int index = ans.size();
            vector<int> cycle;
            unordered_map<int, int> hash;
            while (true) {
                numerator1 *= 10;
                if (hash.contains(numerator1)) {
                    int st = hash[numerator1];
                    string tmp = ans.substr(0, cycle[st]) + '(';
                    for (int i = cycle[st]; i < ans.size(); i++) {
                        tmp += ans[i];
                    }
                    tmp += ')';
                    ans = tmp;
                    break;
                }
                int quotient = numerator1 / denominator1;
                cycle.push_back(index);
                hash[numerator1] = cycle.size() - 1;
                index++;
                numerator1 %= denominator1;
                ans += static_cast<char>(quotient + '0');
                if (numerator1 == 0) {
                    break;
                }
            }
        }
        if (neg1 != neg2 && numerator != 0) {
            ans = "-" + ans;        
        }
        return ans;
    }
};

时间复杂度：设小数点后位数数量级为n，代码时间复杂度为$O(n)$

java速成

Mon, 20 Oct 2025 00:00:00 GMT

一. 传参

java普通类型如int，double，char，与c++相同，都是值传递，方法内修改不影响外部传入的值

public class ValuePassing {
   public static void main(String[] args) {
       int x = 10;
       modifyValue(x);
       // x仍然为10
   }
   public static void modifyValue(int value) {
       value = 20; // 修改的是副本，不影响原始变量
   }
}

java对象类型如String，类似c++传递指针参数，传入的是指向对象的指针，可以在方法内修改对象，但对该对象整体重新赋值则相当于c++中让函数内指针指向新内存地址，不会改变外部对象

public class Switch {
    public static void main(String[] args) {
        String x1 = "10";
        String y1 = "20";
        System.out.println("交换前x1 = "+x1);
        System.out.println("交换前y1 = "+y1);
		// 进行数据交换
        swap(x1, y1);
		// x1, y1不会变化
        System.out.println("交换后x1 = "+x1);
        System.out.println("交换后y1 = "+y1);
 
 
    }
 	// 在c++中相当于swap(string* x, string* y)
    public static void swap(String x, String y) {
        // 跟c++类似，传递的指针实际是复制了一份指针指向对象
        // java中重新赋值相当于c++让复制的那份指针指向别的内存，但原指针不变
        String z ;
        z = x;
        x = y;
        y = z;
        System.out.println("x = "+x);
        System.out.println("y = "+y);
    }
}

void func() {
    string* s1 = new string("123");
    string* s2 = new string("456");
    swap(s1, s2);
    // s1, s2的指向仍然没变
}
void swap(string* s1, string* s2) {
    string* temp = s1;
    s1 = s2;
    s2 = temp;
}

java引用传递，即传数组，与c++行为一致

二. 继承

大致类似，主要区别：

c++使用: public ClassName表示继承，java使用extends ClassName表示继承
c++可以多继承，java只有单继承

在可见性，继承规则上基本一致：

继承规则
- 默认继承父类的成员变量和方法
- 同名变量，使用时取决于静态类型
可见性
- private：子类不可直接访问
- protect/public：子类可直接访问

2.1 方法重写

java中子类定义与父类相同的方法（方法名，形参），默认是重写行为

c++中子类与父类相同的方法，默认是两个不同的方法

2.2 super

作用：

在子类构造方法中调用父类的构造方法：

// B继承A
public B() {
    // 调用父类无参构造
    super();
}
public B(int x) {
    // 调用父类有参构造
    super(x);
}

访问父类中的变量/方法

形式：

super.var

super.method()

三. 多态

3.1 强制方法重写

java中在子类方法上使用@Override注解，可以由编译器检查是否进行了正确的重写

其行为与c++ override关键字类似，在子类方法后加上override，可以重写父类中定义的虚方法（virtual method）

java重写Object的三个方法（常用）：

// 显示更有意义的字符串:
@Override
public String toString() {
    return "";
}

// 比较当前对象和对象o是否相等: 逻辑相等
@Override
public boolean equals(Object o) {
    return false
}

// 计算hash:
@Override
public int hashCode() {
    return 0;
}

3.2 抽象类

与c++中的纯虚类概念类似，包含抽象方法/纯虚函数的类

定义：

abstract class A {
    private String s;
    public abstract void method();
    public void method2();
}

抽象类不能实例化
类和抽象方法都被abstract修饰
可以定义普通变量和方法

3.3 类型转换

子转父：直接强制类型转换即可

Child c = new Child();
Father f = (Father) c; // 去掉强制转换也生效

父转子：有风险，使用instanceof

Object obj = "hello";
if (obj instanceof String) {
    String s = (String) obj;
    System.out.println(s.toUpperCase());
}

3.4 接口

一组抽象方法的集合，所有方法默认是public abstract修饰

相当于c++的纯虚函数类只定义纯虚方法不定义变量和普通方法

定义：
```
interface A() {
    void method1();
}
```

类实现接口：

class B implements A {
    @Override
    public void method1() {
        
    }
}

接口可以继承接口
类可以实现多个接口（implements A, B）
接口可以定义default方法
```
interface A() {
    void method1();
    default void method2() {
        method1();
        System.out.println("");
    }
}
```
default方法的目的是，当我们需要给接口新增一个方法时，会涉及到修改全部子类。如果新增的是default方法，那么子类就不必全部修改，只需要在需要覆写的地方去覆写新增方法。

当一个类实现了一个接口，就可以使用接口类型指向类的实例，从而调用实际的接口方法来完成对应功能

3.5 内部类

顾名思义，就是在类A中定义类B，B被称为内部类

与c++不同，c++在类A中定义类B，除了影响类B的作用域外，两者几乎没有关系

java中三种内部类：

普通内部类，类A中明确定义类B：

class Outer {
    private String name;

    Outer(String name) {
        this.name = name;
    }

    class Inner {
        void hello() {
            System.out.println("Hello, " + Outer.this.name);
        }
    }
}

内部类可以访问外部类的private字段
内部类依附外部类，持有一个外部类的引用

静态内部类（使用static修饰内部类）：

class Outer {
    private static String NAME = "OUTER";

    private String name;

    Outer(String name) {
        this.name = name;
    }

    static class StaticNested {
        void hello() {
            System.out.println("Hello, " + Outer.NAME);
        }
    }
}

不依附外部类
可以访问外部类的静态字段

匿名内部类（简化代码，临时使用）

// 实现接口的匿名类
Runnable r = new Runnable() {
    @Override
    public void run() {
        System.out.println("Hello, " + Outer.this.name);
    }
};
// 继承父类的匿名类
HashMap<String, String> map2 = new HashMap<>() {
    // 该类继承了HashMap, 可以访问其中的所有变量和方法
};

继承父类或实现接口
可以访问父类中的变量和方法

3.5.1 lambda表达式

java与c++中的lambda表达式形式基本相同，但本质不太一样，c++的lambda表达式本质是重载了()的对象，也可以叫做函数对象，java则是对匿名内部类的一种简化写法

java lambda：本质是实现接口的方法

实现条件：
- 接口
- 单一方法
或者用@FunctionalInterface来注解一个接口
```
@FuntionalInterface
interface Swim {
    void swimming();
}

public static void main(String[] args) {
    Swim swim = () -> {
        System.out.println("swim...");
    };
}
```
如上所示，当某个方法使用Swim接口做参数时，可以这么写：
```
void func1(Swim s) {
    ...
}
void call_func1() {
    func1(() -> {
        System.out.println("swim...");
    });
}
```
由于lambda表达式是对应接口的实现，所以()是接口方法的形参列表，函数体返回值也要和接口方法保持一致

c++ lambda：

以std::sort()为例：

std::vector<int> v {1, 2, 5, 4, 3};
std::sort(v.begin(), v.end(), [](int x, int y) -> bool {
    return x > y;
});

形式为：

// -> return_type可省略
auto lambda = [捕获](形参列表) -> return_type {
    函数体
};

本质是把对象当函数用，没有java的必须实现接口的限制，还多了可捕获列表，不过二者在写法上大差不差

3.5.2 方法引用

对lambda进一步的简化，用已有的方法来代替lambda表达式成为函数式接口的方法体，参数，返回值等要和接口方法保持一致

使用形式很像c++带作用域的函数：

class Function1 {
    public static int subtraction(int a, int b) {
        return b - a;
    }
}
// 方法引用
Arrays.sort(arr, Function1::subtraction);

静态方法引用：类名::方法名
对象方法引用：对象::方法名
- 引用本类方法：this::方法名
- 引用父类方法：super::方法名
类名引用成员：跟接口中抽象方法的第一个参数有关
```
ArrayList<String> list = new ArrayList<>();
// 
list.stream.map(String::toUpperCase);
```
如上，map()里要求实现的抽象方法第一个参数是String str，那么可以直接引用String类的方法，其实际含义为调用str.toUpperCase()
构造方法引用：类名::new

四. 泛型

类似c++模板，但是伪泛型（只在编译期检查）

泛型类

// 可以指定多个类型
public class A<T, E> {
    
}

泛型方法

// 在返回值前加<T>标识方法为泛型方法
public <T> void method(T val) {
    
}

泛型接口
```
public interface B<E> {
 
}
```
实现类实现接口时，可以指定E为具体类型，也可以延续泛型，创建对象时再确定

泛型通配符

泛型不具备继承性，但数据具有继承性

? extends E：表示可以传递E和E的所有子类类型
? super E：表示可以传递E和E的所有父类类型

五. 常用数据结构和API

5.1 String

构造

public String();
public String(String original);
public String(char[] chs);
public String(byte[] chs);

常用方法

int length(); // 长度
char charAt(int index); // 指定索引字符
char[] toCharArray(); // 转为字符数组
String substring(int beginIndex, int endIndex); // 截取子字符串
String toUpperCase(); // 大小写转换
boolean equals(Object anObject); // 比较
boolean equalsIgnoreCase(String antherString); // 忽略大小写比较
String[] split(String regex); // 根据指定正则表达式分割字符串

5.2 StringBuilder

构造

public StringBuilder();
public StringBuilder(String str);

常用方法

StringBuilder append(任意类型); // 在末尾追加
StringBuilder reverse();	// 反转字符串
int length();	// 当前字符串长度
String toString();	// 转为String类型

5.3 StringJoiner

添加字符串之间需要用间隔符分开，并最终需要添加开头和结尾符号

构造

public StringJoiner(间隔符);
public StringJoiner(间隔符, 开始符, 结尾符);

常用方法

StringJoiner add(任意类型);	// 追加
int length();		// 长度
String toString();	// 转为String类型

5.4 Math

功能和cmath类似

使用时一般是Math.func()的形式：

int abs(int);	// 绝对值
double ceil(double);	// 上取整
double floor(double);	// 下取整
int round(float);		// 四舍五入
int max(int, int);		// 最大
double pow(double, double);	// 指数
double random();		// [0.0, 1.0)的随机值

5.5 System

三个：退出，当前时间，数组拷贝

System.exit(0);
long ms = System.currentTimeMillis();

System.arraycopy(src, index1, dest, index2, len);

5.6 Object

其中三个在强制方法重写里记过，toString()，equals()，hashCode()

clone()

类似c++中的拷贝构造，同样分深克隆和浅克隆
- 浅克隆：重写的clone()中直接调用super.clone()，会默认返回一个浅克隆的Object对象
- 深克隆：先super.clone()，返回的对象中的引用数据类型重新从当前对象复制一遍即可

Objects：

三个静态方法，equals，isNull，nonNull

5.6 包装类和BigInteger

就是封装一下原始的int，double，boolean数据类型，使其变为类

在保留了原数据类型的用法上，额外新增类的静态方法：

Integer valueOf(var); // 将var转为对应的类型
String toBinaryString(int); // 数字转二进制
String toOctalString(int);
String toHexString(int);
int parseInt(String); // 字符串转数字

需要注意的是，包装类和String一样是不变类，这意味着：

Integer i = 1000000;
i += 1; // 会新生成一个Integer对象, i将指向这个新对象

BigInteger

每一个BigInteger都是一个不可变对象，换句话说每一次计算都会生成新的BigInteger对象

构造：

字符串：new BigInteger("12345678")

数字（最高支持long）：BigInteger.valueOf(1234)

常用方法

BigInteger add(BigInteger val);
BigInteger substract(BigInteger val);
BigInteger multiply(BigInteger val);
BigInteger divide(BigInteger val);
BigInteger[] divideAndRemainder(BigInteger val); // 取余, 返回商和余数
BigInteger equals(BigInteger val);	//	比较两个大整数是否相同
BigInteger pow(int val);		// 次幂
BigInteger max(BigInteger val);	// 返回两个整数中大的一个
int intValue(BigInteger val);

5.7 时间

一些基本知识：

时区，以本初子午线为基准线（时间为00:00:00），划分的24个时区，中国在东八区（08:00:00），比基准线快8个小时
1秒钟的判定，用铯原子的跳动方式来计时

传统日期类有：Date（表示日期和时间，可以精确到毫秒）、Calendar（表示日历），但线程不安全

java之后使用新日期时间类：

新日期时间
时间戳
格式化

5.7.1 日期时间

LocalDate：年月日

LocalTime：时分秒

LocalDateTime：年月日时分秒

方法：

// now
LocalDate date = LocalDate.now();
LocalTime time = LocalTime.now();
LocalDateTime dateTime = LocalDateTime.now();

// of
LocalDate date = LocalDate.of(2026, 2, 3);
LocalTime time = LocalTime.of(14, 30, 0);
LocalDateTime dateTime = LocalDateTime.of(2026, 2, 3, 14, 30);

// 加减日期、 时间

// 比较前后

// 获取具体的字段

ZoneId：指定时区（字符串）

ZonedDateTime：带时区的时间

ZoneId zone = ZoneId.of("Asia/Shanghai");

ZonedDateTime zdt = ZonedDateTime.now(zone);

5.7.2 时间戳

Instant：时间线上的一个瞬时点，精确到纳秒

// now
Instant now = Instant.now();
long millis = now.toEpochMilli();

Duration：时分秒时间间隔

Period：年月日日期间隔

// duration
Duration d = Duration.between(start, end);
long seconds = d.getSeconds();

// period
Period p = Period.between(startDate, endDate);
int days = p.getDays();

5.7.3 格式化

DateTimeFormatter：格式化类

DateTimeFormatter formatter =
        DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");

格式化时间到字符串

String str = LocalDateTime.now().format(formatter);

格式化字符串到时间

LocalDateTime t = LocalDateTime.parse(
        "2026-02-03 14:30:00",
        formatter
);

5.8 Arrays

String toString([] arr); // 数组拼接为字符串
int binarySearch([] arr, elem); // 数组中找elem
int[] copyOf([] src, destLen); // 拷贝数组
int[] copyOfRange([] src, srcStart, srcEnd);
void fill([] arr, elem); // 填充
void sort([] arr);
void sort([] arr, 排序规则);

5.9 Collection

通用方法：

int size();	
boolean isEmpty();
boolean contains(Object o);
boolean add(E e);
boolean remove(Object o);
Object[] toArray();
void clear();
Iterator<E> iterator(); // 获取迭代器

三种遍历方式：

迭代器

Iterator<> it = collection.iterator();
while (it.hasNext()) {
    it.next();
}

增强for
```
for (type it : collection) {
    
}
```

forEach

collection.forEach(new Consumer<>() {
    @Override
    public void accept(type s) {
		// 
    }
});
// lambda
collection.forEach((type s) -> {
    // 
})

5.9.1 ArrayList

用法类似c++中的vector

boolean add(E e); // push_back(e);
E get(int index); // val = v[index];
E set(int index, E element); // v[index] = val;

5.9.2 LinkedList

链表结构，api稍有不同

void addFirst(E e);
void addLast(E e);
E getFirst();
E getLast();
E removeFirst();
E removeLast();

5.9.3 HashSet

套用Collection api

自定义类要重写hashCode方法，否则默认使用地址值

5.9.4 TreeSet

套用Collection api

默认升序

自定义类需要实现Comparable<E>接口：

class A implements Comparable<A> {
    @Override
    public int compareTo(A o) {
        // return 0, -1, 1
        // 0: 相等
        // -1: this 比 o 小
        // 1: this 比 o 大
        // 返回-1, 顺序是this, o
        // 返回1, 顺序是o, this
    }
}

或者指定TreeSet的排序规则（Comparator<E>）：

TreeSet<A> = new TreeSet<A>(new Comparator<A>() {
    @Override
    public int compare(A o1, A o2) {
        // 0: 相等
        // -1: o1 < o2
        // 1 : o1 > o2
        // return 0, -1, 1
        // 返回-1, 顺序是o1, o2
        // 返回1, 顺序是o2, o1
    }
})

还有一些其他的方法，第一个/最后一个元素，树上二分查找等

5.10 Map

通用方法

V put(K key, V val);	// 添加键值对
V get(Object key); 		// 取键对应值
V remove(Object key);	// 删除键
void clear();			// 清空
boolean containsKey(Object key); // 是否有键
boolean containsValue(Object val);	// 是否有值
boolean isEmpty();			// 空
int size();				// 键个数

遍历

keySet，返回一个键集合，遍历键，获取值

Set<Object> keySet = map.keySet();
for (Object obj : keySet {
	Object val = map.get(obj);
}

entrySet，返回一个键值对集合，直接遍历键值对

Set<Map.Entry<Object, Object>> entrySet = map.entrySet();
for (Map.Entry<Object, Object> entry : entrySet) {
    entry.getKey();
    entry.getValue();
}

forEach，类似Collection，接收键值两个参数

map.forEach((Object key, Object value) -> {
	//
});

5.10.1 TreeMap

按键排序，默认升序

自定义排序：

Key类实现Comparable<Key>接口
指定TreeMap的排序规则（Comparator<Key>）

第一个，最后一个键值对，树上二分查找等

5.10.2 HashMap

依赖hashCode()和equals()保证键唯一

5.11 可变参数

本质是数组

使用方法：func(Object... args)

一个方法只能有一个可变参数
可变参数在所有参数最后

5.12 Stream链式编程

目的是简化Collection和数组的操作

5.12.1 创建流

// Collection
default Stream<E> stream();
// Arrays
public static<T> Stream<T> stream(T[] array);
// Stream
public static<T> Stream<T> of (T... values);

5.12.2 中间方法

Stream<T> filter(Predicate<? super T> predicate); // 按条件过滤
Stream<T> limit(long maxSize);	// 获取前maxSize个元素
Stream<T> skip(long n);	// 跳过前n个元素
Stream<T> distinct();	// 元素去重，需要hashCode和equals
Stream<T> concat(Stream a, Stream b); // 合并a,b流为一个流
Stream<T> map(Function<T, R> mapper); //

示例：

filter：

list.stream().fiter((Object obj) -> {
    // 过滤掉返回值为false的
    // return true; 
    // return false;
});

map：

list.stream().map((Object obj) -> {
    // 对object做操作, 返回新的数据类型
    // 比如将一个String转为Integer, 之后的流上都是Integer类型的数据
    return newObj;
});

5.12.3 终结方法

void forEach(Consumer action); // 遍历
long count();	// 统计数据个数
toArray();		// 转为数组
collect(Collector collector); // 转为集合

toArray()

将流中的数据封装到Object[]中返回

toArray(IntFunction<A[]> generator)

返回对应类型的数组

list.stream().toArray((int value) -> {
    return new type[value];
});

collect(Collector collector)

封装到List中返回

List<> list = list.stream().collect(Collectors.toList());

封装到Set中

Set<> set = list.stream().collect(Collectors.toSet());

封装到Map中

Map<> map = list.stream().collect(Collectors.toMap(
    (Object obj) -> {
        // 返回键, 不能重复
    },
    (Object obj) -> {
        // 返回值
    }
));

六. 异常

c++异常一坨，java更成体系，没有类比的必要了，东西也不多，直接记住就好了

编译时异常，编译阶段给提示，必须先手动处理（见6.1-6.2）
运行时异常，运行程序可能出现异常

6.1 捕获

catch支持多级，支持同时捕获多个异常（用|分割）

e.printStackTrace()：打印异常堆栈信息

try {
    
} catch (Exception e) {
    e.printStackTrace();
} finally {
    
}

6.2 抛出

throws 异常类1, 异常类2：方法定义后，表示使用方法可能会抛出这些异常
throw 异常：方法内，手动抛出异常，停止方法运行并将异常返回给调用者

public void method() throws Exception {
    throw Exception();
}

6.3 自定义

编译时异常，继承Exception
运行时异常，继承RuntimeException

public class MyException extends RuntimeException {
    // 空参
    public MyException() {
        
    }
    // 带参
    public MyException(String messgae) {
        super(message)
    }
}

6.4 异常资源释放

类似c++中的RAII思想，自动释放资源（即使出现异常的情况下）

具体做法是：

// 基本语法
try (ResourceType resource = new ResourceType()) {
    // 使用资源的代码
} catch (Exception e) {
    // 异常处理
}

// 多个资源
try (ResourceType1 resource1 = new ResourceType1();
     ResourceType2 resource2 = new ResourceType2()) {
    // 使用资源的代码
} catch (Exception e) {
    // 异常处理
}

其中，ResourceType必须实现AutoCloseable接口

七. IO流

按数据单位分：字节流、字符流
按流向分：输入流、输出流
按角色分类：节点流、包装流

7.1 字节流

以Stream结尾的各类对象都是字节流：

7.2 字符流

以Reader和Writer结尾的各类对象都是字符流

7.3 文件

7.4 序列化

八. 多线程

8.1 创建方式：

继承Thread类，重写run方法（简单任务）

实现Runnable接口，重写run方法（要执行的方法与线程分离）

class MyTask implements Runnable {
    @Override
    public void run() {
        System.out.println("任务执行中...");
    }
}

// 使用
Thread thread = new Thread(new MyTask());
thread.start();

实现Callable<T>接口，重写call方法（支持返回值，能抛异常，配合Future使用）

class MyCallable implements Callable<String> {
    @Override
    public String call() throws Exception {
        return "任务执行结果";
    }
}

// 使用
FutureTask<String> task = new FutureTask<>(new MyCallable());
Thread thread = new Thread(task);
thread.start();
String result = task.get(); // 获取结果

8.2 锁

在java里面，任何一个对象都可以被当做mutex来使用，

九. 反射

加载类，并解剖类中的信息

9.1 获取Class对象

Class.forName("package.className")：填全类名
className.class：做参数传递
obj.getClass()：能创建对象再考虑使用

9.2 常用方法

获取构造器Constructor对象，并利用其构造类对象
获取成员变量Field对象，获取/修改类成员变量
获取方法Method对象，执行类方法

获取Constructor，Field，Method类型的对象，大部分签名都很类似，挑重点的记：

getName：获取类名
getDeclaredConstructors()：返回可用的Constructor数组

getDeclaredConstructor(xx1.class, xx2.class)：返回对应有参的Constructor对象

其他，要获取对应类的成员变量和方法，其get方法也类似上面

使用Constructor对象构造原对象

Class c1 = ArrayList.class;
// 获取无参构造器对象（可能是 private，因此使用 getDeclaredConstructor）
Constructor con = c1.getDeclaredConstructor();
// 临时设置访问权限，使得可以访问 private 构造函数
con.setAccessible(true);
// 构造对象, 需要强转，因为返回的是 Object
ArrayList s1 = (ArrayList) con.newInstance();

使用Field对象设置/获取类成员变量

Class c1 = ArrayList.class;
// 获取 ArrayList 类中的对应成员变量，例如 "size"
Field fieldSize = c1.getDeclaredField("size");
// 临时关闭 Java 权限检查
fieldSize.setAccessible(true);
// arr 是一个 ArrayList 的对象
ArrayList arr = new ArrayList();
// 设置字段值为指定内容
fieldSize.set(arr, 10);
// 获取字段值
int var = (int) fieldSize.get(arr);
System.out.println("size = " + var);

使用Method对象调用类方法

Class c1 = String.class;
// 获取 private 方法，如 String 中的 "indexOfSupplementary"
Method method = c1.getDeclaredMethod("indexOfSupplementary", int.class, int.class);
// 开放权限
method.setAccessible(true);
// 调用方法，需要传入对象和参数
String s = "hello";
int result = (int) method.invoke(s, 0x10400, 0);
System.out.println(result);

作用：

获取一个类的全部成分然后操作
破坏封装性
绕过泛型，比如在ArrayList<Integer>添加"123"
框架

十. 注解

10.1 定义

public @interface MyAnnotation {
    public String name1() default "123";
}

本质是一个接口，自定义注解是继承了Annotation接口的接口

使用

默认情况下可以在类名，方法名，变量名上直接加@MyAnnotation使用，这代表接口的一个实现类
要指定里面的属性值就用@MyAnnotation(name1="", xxx)，如果注解里面非默认属性只有一个value，可以直接把value=省略

元注解

注解在注解上的注解

形式：

@Rentention
@Target
public @interface MyAnnotation {
    public String name1() default "123";
}

Rentention：声明注解的保留周期
- @Rentention(RententionPolicy.RUNTIME)：一直保留，常用
- RententionPolicy.SOURCE：源码保留
- RententionPolicy.CLASS：字节码保留
Target：限制注解的范围
- @Target(ElementType.Type)：该注解可以在类和接口上使用
- ElementType.FIELD：成员变量
- ElementType.METHOD：成员方法
- ElementType.PARAMETER：方法参数

10.2 解析

利用反射

获取使用注解的类对象

Class c1 = Demo.class
判断对应注解是否存在

c1.isAnnotationPresent(MyAnnotation.class)
获取注解对象并获取其属性值

MyAnnotation myan = (MyAnnotation) getDeclaredAnnotation(MyAnnotation.class)

Class，Method，Field，Constructor等都实现了AnnotatedElement接口：

public Annotation[] getDeclaredAnnotations();	// 获取当前对象上的注解
public T getDeclaredAnnotation(Class<T> annotationClass);	// 获取指定的注解对象
public boolean isAnnotationPresent(Class<Annotation> annotationClass); // 判断当前对象是否存在某个注解

使用场景：

比如JUnit框架定义的@Test，加上就测试，本质就是底层利用反射，看Method上是否有@Test注解，决定是否invoke

十一. 动态代理

像是一个包装类，使用非侵入式的形式来对被代理的类增添功能代码（底层使用反射）

核心是Proxy.newPorxyInstance，简易代码如下，invoke中的proxy指的是T proxy：

class ProxyUtil {
    public static <T> T createProxy(T obj) {
        T proxy = (T) Proxy.newProxyInstance(ProxyUtil.class.getClassLoader(),
                obj.getClass().getInterfaces(), new InvocationHandler() {
                    @Override
                    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
                        // do something before method...
                        Object result = method.invoke(obj, args);
                        // do something after method...
                        return result; // return method result
                    }
                });
        return proxy;
    }
}

关于Proxy.newPorxyInstance：

public static Object newProxyInstance(ClassLoader loader,
                                      Class<?>[] interfaces,
                                      InvocationHandler h)

ClassLoader loader：指定加载代理类的类加载器
Class<?>[] interfaces：指定代理要实现的接口，一般被代理的类实现哪些，就填哪些
InvocationHandler h：匿名内部类，在内部指定生成的代理类对象要增加的功能

Hello World

Thu, 25 Sep 2025 17:20:00 GMT

测试

Using MDX

Sun, 01 Jun 2025 00:00:00 GMT

This theme comes with the @astrojs/mdx integration installed and configured in your astro.config.mjs config file. If you prefer not to use MDX, you can disable support by removing the integration from your config file.

Why MDX?

MDX is a special flavor of Markdown that supports embedded JavaScript & JSX syntax. This unlocks the ability to mix JavaScript and UI Components into your Markdown content for things like interactive charts or alerts.

If you have existing content authored in MDX, this integration will hopefully make migrating to Astro a breeze.

Example

Here is how you import and use a UI component inside of MDX.
When you open this page in the browser, you should see the clickable button below.

import { Button } from 'astro-pure/user'

Click Me

Markdown 语法支持

Wed, 26 Jul 2023 08:00:00 GMT

基本语法

Markdown 是一种轻量级且易于使用的语法，用于为您的写作设计风格。

标题

文章内容较多时，可以用标题分段：

# 标题 1

## 标题 2

## 大标题

### 小标题

标题预览会打乱文章的结构，所以在此不展示。

粗斜体

_斜体文本_

**粗体文本**

**_粗斜体文本_**

预览：

斜体文本

粗体文本

粗斜体文本

链接

文字链接 [链接名称](http://链接网址)

预览：

文字链接链接名称

行内代码

这是一条 `单行代码`

预览：

这是一条 行内代码

代码块

```js
// calculate fibonacci
function fibonacci(n) {
  if (n <= 1) return 1
  return fibonacci(n - 1) + fibonacci(n - 2)
}
```

预览：

// calculate fibonacci
function fibonacci(n) {
  if (n <= 1) return 1
  return fibonacci(n - 1) + fibonacci(n - 2)
}

当前使用 shiki 作为代码高亮插件，支持的语言请参考 shiki / languages。

行内公式

这是一条行内公式 $e^{i\pi} + 1 = 0$

预览：

这是一条行内公式 $e^{i\pi} + 1 = 0$

公式块

$$
\hat{f}(\xi) = \int_{-\infty}^{\infty} f(x) e^{-2\pi i x \xi} \, dx
$$

预览：

$$ \hat{f}(\xi) = \int_{-\infty}^{\infty} f(x) e^{-2\pi i x \xi} , dx $$

当前使用 KaTeX 作为数学公式插件，支持的语法请参考 KaTeX Supported Functions。

图片

![CWorld](https://cravatar.cn/avatar/1ffe42aa45a6b1444a786b1f32dfa8aa?s=200)

预览：

删除线

~~删除线~~

预览：

~~删除线~~

列表

普通无序列表

- 1
- 2
- 3

预览：

普通有序列表

1. GPT-4
2. Claude Opus
3. LLaMa

预览：

GPT-4
Claude Opus
LLaMa

列表里可以继续嵌套语法

引用

> 枪响，雷鸣，剑起。繁花血景。

预览：

枪响，雷鸣，剑起。繁花血景。

引用里也可以继续嵌套语法。

换行

markdown 分段落是需要空一行的。

如果不空行
就会在一段

第一段

第二段

预览：

如果不空行就会在一段

第一段

第二段

分隔符

如果你有写分割线的习惯，可以新起一行输入三个减号--- 或者星号 ***。当前后都有段落时，请空出一行：

---

预览：

高级技巧

行内 HTML 元素

目前只支持部分段内 HTML 元素效果，包括 <kdb>  ，如

键位显示

使用 <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Del</kbd> 重启电脑

预览：

使用 Ctrl + Alt + Del 重启电脑

粗斜体

<b> Markdown 在此处同样适用，如 _加粗_ </b>

预览：

Markdown 在此处同样适用，如加粗

其他 HTML 写法

折叠块

<details><summary>点击展开</summary>它被隐藏了</details>

预览：

表格

| 表头1 | 表头2 |
| ----- | ----- |
| 内容1 | 内容2 |

预览：

| 表头1 | 表头2 | | ----- | ----- | | 内容1 | 内容2 |

注释

在引用的地方使用 [^注释] 来添加注释。

然后在文档的结尾，添加注释的内容（会默认于文章结尾渲染之）。

[^注释]: 这里是注释的内容

预览：

在引用的地方使用 ^注释来添加注释。

然后在文档的结尾，添加注释的内容（会默认于文章结尾渲染之）。

To-Do 列表

- [ ] 未完成的任务
- [x] 已完成的任务

预览：

[ ] 未完成的任务
[x] 已完成的任务

符号转义

如果你的描述中需要用到 markdown 的符号，比如 _ # * 等，但又不想它被转义，这时候可以在这些符号前加反斜杠，如 \_ \# \* 进行避免。

\_不想这里的文本变斜体\_

\*\*不想这里的文本被加粗\*\*

预览：

_不想这里的文本变斜体_

**不想这里的文本被加粗**

内嵌 Astro 组件

See User Components and Advanced Components for details.