目录

1. Koupleless 简介
2. 合并部署概述
3. 环境准备
4. 基座改造
5. 模块改造
6. 模块瘦身
7. 部署与验证
8. 常见问题与解决方案
9. 最佳实践
10. 生产环境部署

Koupleless 简介

Koupleless 是一种模块化的 Serverless 技术解决方案，它能让普通应用以较低的代价演进为 Serverless 研发模式，让代码与资源解耦，轻松独立维护，同时支持秒级构建部署、合并部署、动态伸缩等能力，为用户提供极致的研发运维体验。

适用场景

1. 应用构建发布慢或 SDK 升级繁琐：传统应用构建发布需要 6-10 分钟，使用 Koupless 可降至 10 秒级
2. 长尾应用资源浪费：企业 80% 的应用 CPU 使用率低于 10%，合并部署可显著降低资源成本
3. 研发协作效率低：多人开发一个应用时，需要统一时间窗口发布， Koupless 支持模块独立迭代
4. 中台应用难以沉淀业务资产：通过基座沉淀公共能力，模块实现具体业务逻辑
5. 微服务演进成本高：支持应用在单体、模块化、微服务架构间平滑过渡

合并部署概述

什么是合并部署

合并部署是指将多个独立的应用（在 Koupless 中称为"模块"）部署到同一个 JVM 进程中，共享基座的资源和依赖，但保持代码和运行时的隔离。

合并部署的优势

• 节省资源：多个模块共享基座的内存（Metaspace 和 Heap），CPU 使用率有效提升
• 快速启动：模块构建产物从数百 MB 瘦身到几十 MB，启动时间大幅缩短
• 简化运维：统一管理多个模块，降低维护成本
• 灵活扩展：支持动态添加、移除模块，无需重启基座

架构原理

Koupleless 基于 SOFAArk 框架实现类隔离和合并部署：

• 基座（Base）：提供公共依赖和基础能力，如 SpringBoot 框架、中间件 SDK 等
• 模块（Biz）：业务功能模块，依赖基座提供的公共能力
• 类加载机制：模块优先从自己的 ClassLoader 查找类，找不到再委托给基座 ClassLoader

环境准备

前置条件

• JDK 8 或更高版本
• Maven 3.6+
• SpringBoot 2.x 或 3.x
• 可用的 IDE（IntelliJ IDEA、Eclipse 等）

版本选择

当前 Koupleless 主要版本：

<koupleless.runtime.version>0.5.6</koupleless.runtime.version>
<sofa.ark.version>2.2.14</sofa.ark.version>

工具准备

下载 Arkctl 工具（用于模块部署）：

# Mac/Linux
wget https://github.com/koupleless/koupleless/releases/download/arkctl-release-0.2.0/arkctl-darwin-amd64
mv arkctl-darwin-amd64 /usr/local/bin/arkctl
chmod +x /usr/local/bin/arkctl

# Linux
wget https://github.com/koupleless/koupleless/releases/download/arkctl-release-0.2.0/arkctl-linux-amd64
mv arkctl-linux-amd64 /usr/local/bin/arkctl
chmod +x /usr/local/bin/arkctl

基座改造

1. 添加依赖

在基座的 pom.xml 中添加 Koupleless 基座依赖：

<properties>
    <koupleless.runtime.version>0.5.6</koupleless.runtime.version>
    <sofa.ark.version>2.2.14</sofa.ark.version>
</properties>

<dependencies>
    
    <dependency>
        <groupId>com.alipay.sofa.koupleless</groupId>
        <artifactId>koupleless-base-starter</artifactId>
        <version>${koupleless.runtime.version}</version>
    </dependency>
    
    
    <dependency>
        <groupId>com.alipay.sofa</groupId>
        <artifactId>web-ark-plugin</artifactId>
    </dependency>
</dependencies>

2. 配置应用名

在 application.properties 或 application.yml 中配置应用名：

# application.properties
spring.application.name=base-application

3. 配置基座构建插件

在 pom.xml 的 build 部分添加基座构建插件：

<build>
    <plugins>
        
        <plugin>
            <groupId>com.alipay.sofa.koupleless</groupId>
            <artifactId>koupleless-base-build-plugin</artifactId>
            <version>${koupleless.runtime.version}</version>
            <executions>
                <execution>
                    <goals>
                        <goal>add-patch</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                
                <dependencyArtifactId>${baseAppName}-dependencies-starter</dependencyArtifactId>
                
                <dependencyVersion>0.0.1-SNAPSHOT</dependencyVersion>
            </configuration>
        </plugin>
        
        
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <executions>
                <execution>
                    <goals>
                        <goal>repackage</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

4. 生成依赖 Starter

执行以下命令生成基座的依赖 starter：

mvn com.alipay.sofa.koupleless:koupleless-base-build-plugin::packageDependency -f pom.xml

这个命令会生成一个 ${baseAppName}-dependencies-starter 的依赖包，模块项目可以将其作为 parent 来继承基座的所有依赖。

5. 启动基座

完成上述配置后，可以直接通过 IDE 或命令行启动基座：

mvn spring-boot:run

模块改造

1. 创建模块项目

模块可以是现有的 SpringBoot 应用，也可以是新创建的项目。建议使用 Maven 多模块结构管理多个模块。

2. 配置模块依赖

在模块的 pom.xml 中添加模块依赖和打包插件：

<properties>
    <koupleless.runtime.version>0.5.6</koupleless.runtime.version>
    <sofa.ark.version>2.2.14</sofa.ark.version>
</properties>

<dependencies>
    
    <dependency>
        <groupId>com.alipay.sofa.koupleless</groupId>
        <artifactId>koupleless-app-starter</artifactId>
        <version>${koupleless.runtime.version}</version>
        <scope>provided</scope>
    </dependency>
    
    
    <parent>
        <groupId>com.example</groupId>
        <artifactId>base-application-dependencies-starter</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    </parent>
</dependencies>

3. 配置打包插件

在模块的 pom.xml 中添加 SOFAArk 打包插件：

<build>
    <finalName>${project.artifactId}</finalName>
    <plugins>
        
        <plugin>
            <groupId>com.alipay.sofa</groupId>
            <artifactId>sofa-ark-maven-plugin</artifactId>
            <version>${sofa.ark.version}</version>
            <executions>
                <execution>
                    <id>default-cli</id>
                    <goals>
                        <goal>repackage</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                
                <skipArkExecutable>true</skipArkExecutable>
                
                <outputDirectory>./target</outputDirectory>
                
                <bizName>module1</bizName>
                
                <webContextPath>/module1</webContextPath>
                
                <declaredMode>true</declaredMode>
                
                <packExcludesConfig>rules.txt</packExcludesConfig>
            </configuration>
        </plugin>
        
        
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <executions>
                <execution>
                    <goals>
                        <goal>repackage</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

4. 配置模块瘦身

下载自动排包配置文件 rules.txt，放在模块的 conf/ark/ 目录下：

# 创建目录
mkdir -p conf/ark

# 下载配置文件
wget https://github.com/koupleless/samples/raw/master/springboot-samples/slimming/log4j2/biz1/conf/ark/rules.txt -O conf/ark/rules.txt

rules.txt 内容示例：

# 排除的依赖（groupId:artifactId:version）
excludes=org.springframework.boot:spring-boot-starter-logging,commons-logging:commons-logging

# 排除的 groupId
excludeGroupIds=org.slf4j

# 排除的 artifactId
excludeArtifactIds=logback-classic

5. 开发模块代码

创建模块的业务代码，例如 REST Controller：

package com.example.module1.controller;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.context.ApplicationContext;

@RestController
@RequestMapping("/")
public class SampleController {
    
    private static final Logger LOGGER = LoggerFactory.getLogger(SampleController.class);
    
    @Autowired
    private ApplicationContext applicationContext;
    
    @GetMapping("/")
    public String hello() {
        String appName = applicationContext.getApplicationName();
        LOGGER.info("{} web test: into sample controller", appName);
        return String.format("hello to %s deploy", appName);
    }
    
    @GetMapping("/health")
    public String health() {
        return "OK";
    }
}

6. 配置应用名

在模块的 application.properties 中配置应用名：

spring.application.name=module1

模块瘦身

为什么要模块瘦身

模块瘦身可以：

• 减小模块包大小：从数百 MB 降低到几十 MB
• 减少内存占用：降低 Metaspace 占用，基座可以安装更多模块
• 加快启动速度：模块启动时间从分钟级降低到秒级
• 提高部署效率：小体积包更容易传输和部署

瘦身原理

模块瘦身的核心思想是：移除模块中与基座重复的依赖，让模块复用基座的类

通过以下方式实现：

1. 继承基座依赖 starter：模块以 ${baseAppName}-dependencies-starter 作为 parent
2. 自动排包：使用 rules.txt 配置文件排除不需要的依赖
3. 依赖委托：模块依赖设置为 provided 作用域，委托给基座加载

配置方法

方法一：继承基座依赖 starter（推荐）

在模块的 pom.xml 中配置：

<parent>
    <groupId>com.example</groupId>
    <artifactId>base-application-dependencies-starter</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</parent>

这样模块会自动继承基座的所有依赖，无需手动配置版本。

方法二：手动配置依赖作用域

在模块的 pom.xml 中，将基座已有的依赖设置为 provided 作用域：

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

方法三：使用排除配置

在 sofa-ark-maven-plugin 中配置排除项：

<configuration>
    <excludeGroupIds>org.springframework,org.slf4j</excludeGroupIds>
    <excludeArtifactIds>spring-boot-starter-logging</excludeArtifactIds>
</configuration>

验证瘦身效果

构建模块并查看包大小：

# 构建模块
mvn clean package

# 查看构建产物
ls -lh target/*.jar

# 瘦身前
-rw-r--r--  1 user  staff   250M  1 15 10:00 module1-1.0.0.jar
-rw-r--r--  1 user  staff   180M  1 15 10:00 module1-1.0.0-ark-biz.jar

# 瘦身后
-rw-r--r--  1 user  staff   250M  1 15 10:30 module1-1.0.0.jar
-rw-r--r--  1 user  staff    15M  1 15 10:30 module1-1.0.0-ark-biz.jar

可以看到，瘦身后的 ark-biz.jar 从 180M 降低到 15M，效果显著。

部署与验证

1. 启动基座

首先启动基座应用：

cd base-application
mvn spring-boot:run

或使用 IDE 启动主类。

2. 构建模块

在模块项目中执行构建：

cd module1
mvn clean package

构建成功后会生成两个 jar 包：

• module1-1.0.0.jar：普通 SpringBoot fat jar，可独立运行
• module1-1.0.0-ark-biz.jar：Koupleless 模块包，用于合并部署

3. 使用 Arkctl 部署模块

使用 Arkctl 工具将模块部署到基座：

# 部署模块
arkctl deploy target/module1-1.0.0-ark-biz.jar

# 或者使用 curl 命令
curl -X POST http://localhost:1238/installBiz \
  -H "Content-Type: application/json" \
  -d '{"bizName":"module1","bizVersion":"1.0.0","bizUrl":"file:///path/to/module1-1.0.0-ark-biz.jar"}'

4. 验证部署

部署成功后，可以通过以下方式验证：

查看模块状态

arkctl status

输出示例：

Biz count: 1
bizName: module1
bizVersion: 1.0.0
bizState: ACTIVATED
mainClass: com.example.module1.Module1Application
webContextPath: /module1

访问模块接口

# 访问模块1的接口
curl http://localhost:8080/module1/
# 输出: hello to module1 deploy

curl http://localhost:8080/module1/health
# 输出: OK

查看日志

在基座控制台可以看到模块启动日志：

[INFO] Install biz: module1, version: 1.0.0, state: ACTIVATED
[INFO] Module module1 started successfully

5. 部署多个模块

重复上述步骤部署 module2：

cd module2
mvn clean package
arkctl deploy target/module2-1.0.0-ark-biz.jar

验证多模块部署：

# 查看所有模块
arkctl status

# 访问不同模块
curl http://localhost:8080/module1/
curl http://localhost:8080/module2/

6. 卸载模块

# 卸载指定模块
arkctl uninstall --bizName=module1 --bizVersion=1.0.0

# 或者使用 curl
curl -X POST http://localhost:1238/uninstallBiz \
  -H "Content-Type: application/json" \
  -d '{"bizName":"module1","bizVersion":"1.0.0"}'

常见问题与解决方案

1. 类冲突问题

问题描述：模块和基座存在相同类名的类，导致类冲突。

解决方案：

• 使用类隔离机制，模块优先加载自己的类
• 公共类下沉到基座，模块通过依赖委托复用
• 避免在模块和基座中定义相同包名和类名的类

2. 静态字段共享问题

问题描述：多个模块共享静态字段，导致数据混乱。

解决方案：

使用 StaticFieldMapWrapper 适配静态字段：

import java.util.concurrent.ConcurrentHashMap;
import java.util.function.Supplier;

public class StaticFieldMapWrapper<T> {
    private final ConcurrentHashMap<ClassLoader, T> classLoaderTMap = new ConcurrentHashMap<>();
    private Supplier<T> getDefaultMethod;
    
    public StaticFieldMapWrapper(Supplier<T> getDefaultMethod) {
        this.getDefaultMethod = getDefaultMethod;
    }
    
    public T getOrPutDefault() {
        T t = classLoaderTMap.get(Thread.currentThread().getContextClassLoader());
        if (t == null && getDefaultMethod != null) {
            t = getDefaultMethod.get();
            classLoaderTMap.put(Thread.currentThread().getContextClassLoader(), t);
        }
        return t;
    }
}

3. Dubbo 兼容性问题

问题描述：模块中使用 Dubbo 泛化调用时出现问题。

解决方案：

• 确保 Dubbo 相关依赖下沉到基座
• 为 Dubbo 配置正确的 ClassLoader 切换
• 参考官方 adapter 仓库的解决方案

4. Nacos 线程过多

问题描述：每个模块启动时创建 Nacos 客户端，导致线程数过多。

解决方案：

在基座中缓存 Nacos 客户端：

private static final Map<Properties, ConfigService> CONFIG_SERVICE_MAP = new ConcurrentHashMap<>();

public static ConfigService getConfigService(Properties properties) {
    return CONFIG_SERVICE_MAP.computeIfAbsent(properties, k -> {
        try {
            return NacosFactory.createConfigService(k);
        } catch (NacosException e) {
            throw new RuntimeException(e);
        }
    });
}

5. 模块启动顺序问题

问题描述：模块之间有依赖关系，需要按顺序启动。

解决方案：

• 在基座中配置模块启动顺序
• 使用依赖关系控制启动顺序
• 避免循环依赖

6. 内存泄漏

问题描述：模块卸载后，内存没有释放，导致 Metaspace 持续增长。

解决方案：

• 确保模块卸载时清理所有资源（线程池、连接等）
• 使用弱引用管理缓存
• 定期重启基座或进行内存整理

7. Spring 上下文冲突

问题描述：模块和基座的 Spring Bean 冲突。

解决方案：

• 使用不同的 Bean 名称
• 模块中使用 @Primary 注解明确优先级
• 避免模块和基座定义相同的 Bean

生产环境部署

1. 部署架构

生产环境推荐部署架构：

用户流量 -> Nginx/SLB -> 基座应用（K8s Pod）
                                    |
                                    +-> 模块1
                                    +-> 模块2
                                    +-> 模块3

2. K8s 部署配置

基座 Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: base-application
spec:
  replicas: 3
  selector:
    matchLabels:
      app: base-application
  template:
    metadata:
      labels:
        app: base-application
    spec:
      containers:
      - name: base-application
        image: registry.example.com/base-application:1.0.0
        ports:
        - containerPort: 8080
        env:
        - name: MODULE_AUTO_INSTALL
          value: "true"
        - name: MODULE_OSS_ENDPOINT
          value: "oss-cn-region.aliyuncs.com"
        - name: MODULE_OSS_BUCKET
          value: "koupleless-modules"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 5
        volumeMounts:
        - name: module-storage
          mountPath: /opt/modules
      volumes:
      - name: module-storage
        persistentVolumeClaim:
          claimName: module-pvc

模块发布流水线

# 模块 CI/CD Pipeline
stages:
  - build
  - test
  - package
  - deploy

build_module:
  stage: build
  script:
    - mvn clean compile

test_module:
  stage: test
  script:
    - mvn test

package_module:
  stage: package
  script:
    - mvn clean package
    - cp target/*.ark-biz.jar module.ark-biz.jar
  artifacts:
    paths:
      - module.ark-biz.jar

deploy_module:
  stage: deploy
  script:
    # 上传模块到 OSS
    - ossutil cp module.ark-biz.jar oss://koupleless-modules/module1/${CI_COMMIT_SHA}.ark-biz.jar
    
    # 通知基座更新模块
    - curl -X POST http://base-service:8080/install \
        -H "Content-Type: application/json" \
        -d '{"module":"module1","version":"'${CI_COMMIT_SHA}'"}'

3. 模块动态部署

方案一：OSS 监听模式

基座监听 OSS 目录变化，自动部署新模块：

@Service
public class ModuleDeploymentService {
    
    @Autowired
    private OssClient ossClient;
    
    @Scheduled(fixedDelay = 5000)
    public void checkModuleUpdates() {
        // 检查 OSS 上的模块版本
        List<String> modules = getModuleList();
        
        for (String module : modules) {
            String latestVersion = getLatestVersion(module);
            String currentVersion = getCurrentVersion(module);
            
            if (!latestVersion.equals(currentVersion)) {
                // 下载新模块
                downloadModule(module, latestVersion);
                
                // 卸载旧模块
                uninstallModule(module, currentVersion);
                
                // 安装新模块
                installModule(module, latestVersion);
            }
        }
    }
}

方案二：配置中心模式

通过配置中心控制模块部署：

# 配置中心配置
modules:
  module1:
    version: 1.0.0
    enabled: true
    healthCheck: /health
  module2:
    version: 2.0.0
    enabled: true
    healthCheck: /health

基座监听配置变化：

@NacosConfigListener(dataId = "modules.json")
public void onModuleConfigChange(String config) {
    ModulesConfig modulesConfig = JSON.parseObject(config, ModulesConfig.class);
    
    // 对比配置差异
    List<ModuleChange> changes = compareModuleConfig(modulesConfig);
    
    // 应用变更
    for (ModuleChange change : changes) {
        switch (change.getType()) {
            case INSTALL:
                installModule(change.getModule());
                break;
            case UNINSTALL:
                uninstallModule(change.getModule());
                break;
            case UPDATE:
                updateModule(change.getModule());
                break;
        }
    }
}

下面把教程里没展开的两件事一次讲透：

1. 静态合并部署（Static Packaged Deployment）——一次性把基座 + N 个模块打成一个可执行 Fat Jar，启动即“全员就位”；
2. 端口隔离——让每个模块真的监听自己的端口，实现“进程内多 WebServer”。

方案三、静态合并部署（Static Packaged Deployment）

适用场景

• 上线流程极简，不允许运维侧再敲 arkctl deploy；
• 容器镜像只启一个进程，K8s liveness/readiness 探针直接探测基座即可；
• 模块版本固定，不需要热卸载/热加载。

1. 打包思路
   基座 pom 里把各模块的 ark-biz.jar 当资源一起打进 BOOT-INF/lib 目录；
   基座启动时借助 SOFAArk 的 “static-biz” 机制，让这些 ark-biz.jar 随基座生命周期一起 install + start。

2. 实操步骤
   step-1 模块端正常 mvn package 得到 moduleX-1.0.0-ark-biz.jar
   step-2 基座 pom 增加 profile（只在打静态包时激活）

<profiles>
  <profile>
    <id>static-pack</id>
    <dependencies>
      
      <dependency>
        <groupId>com.example</groupId>
        <artifactId>module1</artifactId>
        <version>1.0.0</version>
        <classifier>ark-biz</classifier>
        <type>jar</type>
      </dependency>
      <dependency>
        <groupId>com.example</groupId>
        <artifactId>module2</artifactId>
        <version>1.0.0</version>
        <classifier>ark-biz</classifier>
        <type>jar</type>
      </dependency>
    </dependencies>
  </profile>
</profiles>

step-3 基座启动类加 @StaticBiz 注解（0.5.6+ 支持），告诉 SOFAArk 把 classpath 下所有 ark-biz.jar 静态安装：

@SpringBootApplication
@StaticBiz   // 关键
public class BaseApplication {
    public static void main(String[] args) {
        SpringApplication.run(BaseApplication.class, args);
    }
}

step-4 打静态包

mvn clean package -Pstatic-pack

生成的 base-application-1.0.0-exec.jar 里同时包含 module1-ark-biz.jar & module2-ark-biz.jar；
java -jar base-application-1.0.0-exec.jar 启动后，arkctl status 能看到两个模块已经是 ACTIVATED，无需再 deploy。

让模块监听自己的端口

默认行为

• 所有模块与基座共用同一个嵌入式 Tomcat（端口 8080），仅靠 webContextPath 区分；
• 好处：节省线程、节省内存；
• 坏处：无法“端口级”隔离，也做不到“模块单独暴露管理口”。

Koupleless 0.5.6 开始支持 “多 WebServer 模式”，即每个模块可以起独立的 Netty/Tomcat，真正 bind 自己的端口。

1. 模块端增加依赖

<dependency>
    <groupId>com.alipay.sofa</groupId>
    <artifactId>web-ark-plugin</artifactId>
    <classifier>multi-web</classifier>   
    <scope>provided</scope>
</dependency>

2. 配置端口 & 上下文

# module1/application.yml
server:
  port: 8081          # 模块独占
  servlet:
    context-path: /   # 可以为 /
spring:
  application:
    name: module1

3. 打包插件声明

<plugin>
  <groupId>com.alipay.sofa</groupId>
  <artifactId>sofa-ark-maven-plugin</artifactId>
  <configuration>
    <bizName>module1</bizName>
    <webContextPath>/</webContextPath>
    
    <webMultiFlag>true</webMultiFlag>
  </configuration>
</plugin>

4. 部署验证
   基座仍跑 8080，module1 会额外监听 8081，module2 可再配 8082，互不影响；
   curl http://localhost:8081/ 直接返回模块 1 的响应，无需再加前缀。

注意

• 端口多占 n 个，内存/线程也会相应增加，按需权衡；
• 生产环境需在 K8s Service 里把 8081、8082… 也声明出来，或走 Istio 多端口即可。

参考资源

• 官方文档：https://koupleless.io/docs/
• GitHub 仓库：https://github.com/koupleless/koupleless
• 示例代码：https://github.com/koupleless/samples
• 社区支持：https://github.com/koupleless/koupleless/issues

看完了？说点什么呢

https://www.cnblogs.com/throwable/p/16758997.html

看完了？说点什么呢

源码之旅

Java

spring security 99%

Tomcat 10%

openfeign 20%

spring boot 50%

spring 70%

mybatis 99%

springmvc 80%

netty

spring cloud

spring cloud alibaba sentinel 40%

nacos

spring loadbalance

opentrace

看完了？说点什么呢

一、SqlSession 与执行器 Executor

SqlSession 是 MyBatis 的门面接口，我们在业务代码里最常打交道的家伙。它不直接执行 SQL，而是委托给内部的 Executor 来干活。Executor 负责 SQL 的实际执行、事务控制和缓存管理。

看看 DefaultSqlSession 的实现：

public class DefaultSqlSession implements SqlSession {
    private final Configuration configuration;
    private final Executor executor;
    private final boolean autoCommit;
    // ... 其他字段

    public DefaultSqlSession(Configuration configuration, Executor executor, boolean autoCommit) {
        this.configuration = configuration;
        this.executor = executor;
        this.autoCommit = autoCommit;
        // ... 初始化
    }

    @Override
    public <T> T selectOne(String statement, Object parameter) {
        try {
            MappedStatement ms = configuration.getMappedStatement(statement);
            List<T> list = executor.query(ms, wrapCollection(parameter), RowBounds.DEFAULT, Executor.NO_RESULT_HANDLER);
            if (list.size() == 1) {
                return list.get(0);
            } else if (list.size() > 1) {
                throw new TooManyResultsException("Expected one result (or null) to be returned by selectOne(), but found: " + list.size());
            } else {
                return null;
            }
        } catch (Exception e) {
            throw ExceptionFactory.wrapException("Error querying database.  Cause: " + e, e);
        }
    }
    // ... 其他方法如 update、insert 等类似
}

这里的关键是 executor.query()，它会根据 MappedStatement（封装了 SQL 配置）来执行查询。SqlSession 还管理事务：commit() 会调用 executor.commit()，rollback() 同理。如果 autoCommit 为 true，就不会自动提交事务——这在批量操作时特别有用，避免了频繁的 JDBC commit 开销。

Executor 类型详解

MyBatis 提供了几种 Executor 实现，每种针对不同场景优化：

SimpleExecutor

最基础的，每次执行 SQL 都会新建 Statement 对象。简单粗暴，适合单次查询，不用担心资源复用。但在循环执行时性能差，因为反复创建 Statement 会增加 JDBC 开销。源码里 doQuery() 方法每次都调用 statementHandler.prepare() 来创建新 Statement。

ReuseExecutor

聪明点，它会复用 PreparedStatement。对于相同的 SQL，它用一个 Map 来缓存 Statement 对象，避免重复 prepare。看代码：

private final Map<String, Statement> statementMap = new HashMap<>();

@Override
protected int doUpdate(MappedStatement ms, Object parameterObject) throws SQLException {
    // ... 获取 BoundSql
    String sql = boundSql.getSql();
    Statement stmt = statementMap.get(sql);
    if (stmt == null) {
        stmt = handler.prepare(connection, transaction.getTimeout());
        statementMap.put(sql, stmt);
    }
    // ... 设置参数并执行
}

这在高频相同 SQL 的场景下（如循环插入相同结构的数据）能省不少时间。我在项目里用过，确实能感觉到性能提升，但要注意事务结束时要清空 statementMap，否则内存泄漏。

BatchExecutor

专为批量操作设计。它会缓冲多个 SQL 操作，直到 flushStatements() 或 commit() 时一次性发送到数据库。内部用一个 List 来收集结果。适合大批量 insert/update，比如导入 Excel 数据时用这个能把性能从 O(n) 的 JDBC 调用降到接近 O(1)。

CachingExecutor

这是一个装饰器（Decorator），包裹其他 Executor 来添加二级缓存逻辑。如果配置了二级缓存，它会在 query 前先查缓存，miss 后再执行底层 Executor。

Executor 基类 BaseExecutor 还内置了一级缓存（PerpetualCache，默认 HashMap 实现），查询时用 queryStack 来防止循环查询（比如嵌套查询）。事务管理也在 BaseExecutor 里：localCache 在 commit/rollback 时清空。

感悟：MyBatis 的 Executor 体系体现了策略模式，不同执行策略无缝切换，业务代码零感知。

二、SqlSource 与动态 SQL

MyBatis 的 SQL 构建是其亮点之一，分静态和动态两种。静态 SQL 简单高效，动态 SQL 则通过树状结构处理复杂逻辑。

静态 SQL

直接的 SQL 字符串，比如：

String sql = "SELECT * FROM user WHERE id = ?";
StaticSqlSource sqlSource = new StaticSqlSource(configuration, sql, parameterMappings);
BoundSql boundSql = sqlSource.getBoundSql(parameterObject);  // 直接返回固定 SQL 和参数

参数映射在解析 XML 时就固定了，运行时零开销。适合不变的查询。

动态 SQL

动态 SQL 用 SqlNode 树表示，DynamicSqlSource 在 getBoundSql() 时遍历树生成最终 SQL。SqlNode 是接口，有各种实现：

• TextSqlNode：纯文本 SQL 片段
• IfSqlNode：条件判断，内部持有一个 SqlNode 和表达式（如 “id != null”）
• ChooseSqlNode：类似 switch，包含 When 和 Otherwise
• ForEachSqlNode：处理集合迭代，生成 IN 子句或批量插入
• TrimSqlNode：去除多余的 AND/OR 前缀
• MixedSqlNode：容器，持有子节点列表

示例构建树：

List<SqlNode> contents = new ArrayList<>();
contents.add(new StaticTextSqlNode("SELECT * FROM user WHERE 1=1 "));
if (condition) {
    contents.add(new IfSqlNode(new StaticTextSqlNode("AND id = #{id}"), "id != null"));
}
MixedSqlNode mixedSqlNode = new MixedSqlNode(contents);
DynamicSqlSource dynamicSqlSource = new DynamicSqlSource(configuration, mixedSqlNode);

getBoundSql(parameterObject) 时，会用 DynamicContext 上下文递归 apply() 每个节点，收集 SQL 和 ParameterMapping。BoundSql 最终封装 SQL、参数列表和映射。

动态 SQL 的灵活性来自于 OGNL 的表达式求值（详见下节），但性能稍差，因为每次执行都要解析树。优化点：如果参数固定，可以预编译，但 MyBatis 默认运行时解析。

个人吐槽：第一次看动态 SQL 源码时，被 SqlNode 树的递归搞晕了，但用习惯后觉得这设计太优雅了——XML 配置直接转成树，运行时动态组装，避免了字符串拼接的 SQL 注入风险。

三、ParameterMapping 与 OGNL

参数处理是 MyBatis 安全的核心。SQL 中的 #{} 被解析成 ParameterMapping 对象，包含属性名、Java 类型、JDBC 类型等。

ParameterMapping mapping = ParameterMapping.builder(configuration, "id", Integer.class)
    .javaType(Integer.class)
    .jdbcType(JdbcType.INTEGER)
    .build();

在 StatementHandler.setParameters() 时，用 TypeHandler 设置参数：

TypeHandler<Object> typeHandler = parameterMapping.getTypeHandler();
typeHandler.setParameter(ps, i + 1, value, parameterMapping.getJdbcType());

值从 parameterObject 取，用 OGNL：

OGNL (Object Graph Navigation Language)

OGNL 是 MyBatis 的表达式引擎，OgnlCache.getValue(expression, parameterObject) 可以解析 “user.address.street” 这样的嵌套属性。内部用 OgnlRuntime 缓存解析结果，避免重复解析。OGNL 支持方法调用、集合访问等，比反射灵活。

TypeHandler 负责类型转换，TypeHandlerRegistry 注册了常见类型（如 StringTypeHandler、IntegerTypeHandler），自定义类型可扩展。参数映射确保了 preparedStatement 的安全，防 SQL 注入。

感悟：OGNL 的强大让我在业务中也用类似表达式引擎来处理配置，超级方便。

四、ResultMap 与结果映射

ResultMap 是结果集到对象的桥梁。XML 转成 ResultMap 对象，包含 ResultMapping 列表（列名到属性名的映射）。

在 ResultSetHandler.handleResultSets() 时，用 DefaultResultSetHandler 处理：

while (rs.next()) {
    Object rowValue = createResultObject(rsw, resultMap, lazyLoader, columnPrefix);
    // ... 通过 MetaObject 设置属性
    metaObject.setValue(resultMapping.getProperty(), value);
}

支持：

• 自动映射：列名匹配属性名（下划线转驼峰）
• 嵌套结果：association/collection 处理一对一/一对多
• 构造函数注入
• 鉴别器（discriminator）：基于列值选择映射
• 自定义 TypeHandler

ResultMap 解耦了 SQL 和 POJO，改表结构只需调映射，不动代码。懒加载（lazyLoadingEnabled）在访问时再查嵌套对象。

吐槽：复杂嵌套映射时，调试 ResultSetWrapper 的列类型匹配真是个坑，但一旦搞懂，处理复杂查询如鱼得水。

五、缓存机制

MyBatis 缓存分两级，设计精妙。

一级缓存

SqlSession 级，默认开启。在 BaseExecutor.query() 中，先查 localCache（PerpetualCache，HashMap）。key 是 [MappedStatement id + offset + limit + SQL + params]。命中直接返回，miss 执行 SQL 后 put。update/commit 清空。防止脏读，在事务内有效。

二级缓存

Namespace 级（Mapper.xml），需配置 <cache/> 或 cacheEnabled=true。CachingExecutor 装饰底层 Executor，先查二级缓存（可配置如 FifoCache、LruCache），miss 后执行并 put。支持序列化（Serializable），集群时可集成 Redis 等。flushCache/selective 配置控制刷新。

缓存 key 生成用 CacheKey，包含 hashCode、multiplier 等，确保唯一。事务提交时才同步到二级缓存。

优化：读写锁（SynchronizedCache）防止并发问题。

个人经验：在高并发读场景，用二级缓存能把数据库压力降 80%，但要注意失效策略。

缓存装饰器模式实现

public class Cache {
    // 基础缓存实现
    PerpetualCache delegate;
    
    // 可选的装饰器链
    LruCache lru;
    FifoCache fifo;
    SynchronizedCache sync;
    
    // 装饰器包装
    cache = new SynchronizedCache(new LruCache(new PerpetualCache(id)));
}

六、插件与拦截器

插件用责任链模式扩展核心组件。Interceptor 接口：

@Intercepts({@Signature(type = Executor.class, method = "query", 
    args = {MappedStatement.class, Object.class, RowBounds.class, ResultHandler.class})})
public class MyPlugin implements Interceptor {
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        // 前置逻辑
        Object result = invocation.proceed();  // 调用下一个
        // 后置逻辑
        return result;
    }

    @Override
    public Object plugin(Object target) {
        return Plugin.wrap(target, this);  // 动态代理
    }
}

Plugin.wrap() 用 JDK 动态代理包装目标（如 Executor）。多个插件链式执行。

常见用例

• 分页插件：拦截 query，修改 SQL 添加 LIMIT
• 分库分表插件：修改 SQL，路由到不同库表
• 性能监控插件：记录执行时间，慢查询报警
• 数据脱敏插件：结果集处理，敏感数据打码

启发：这让我在设计业务框架时也用拦截器来加日志、权限检查，核心代码干净。

七、事务管理

事务在 Transaction 接口，JdbcTransaction 实现 JDBC commit/rollback。Executor 持 Transaction：

public void commit(boolean required) throws SQLException {
    if (transaction != null) {
        transaction.commit();
    }
}

SqlSessionFactory.openSession(autoCommit) 决定是否自动提交。BatchExecutor 在 flush 时批量 commit。支持 Spring 集成，通过 TransactionManager。

底层：getConnection() 从 DataSource 取连接，setAutoCommit(false) 开启手动事务。回滚时 close 连接释放资源。

事务隔离级别

public enum TransactionIsolationLevel {
    NONE(Connection.TRANSACTION_NONE),
    READ_COMMITTED(Connection.TRANSACTION_READ_COMMITTED),
    READ_UNCOMMITTED(Connection.TRANSACTION_READ_UNCOMMITTED),
    REPEATABLE_READ(Connection.TRANSACTION_REPEATABLE_READ),
    SERIALIZABLE(Connection.TRANSACTION_SERIALIZABLE);
}

坑点：嵌套事务不支持，需小心多 SqlSession 场景。

八、反射与工具类

MyBatis 重度依赖反射简化对象操作。

核心反射组件

• Reflector/MetaClass：Reflector 缓存类元数据（getter/setter），MetaClass 找属性路径
• MetaObject：统一读写对象，支持嵌套：“user.address.street”。内部用 ObjectWrapper（BeanWrapper for POJO, MapWrapper for Map, CollectionWrapper for List）
• Invoker：抽象 get/set，如 MethodInvoker、GetFieldInvoker

// 使用示例
MetaObject metaObject = SystemMetaObject.forObject(user);
metaObject.setValue("name", "grok");
String name = (String) metaObject.getValue("address.street");

PropertyTokenizer

解析属性表达式 “user.address[0].street”：

public class PropertyTokenizer implements Iterator<PropertyTokenizer> {
    private String name;      // user
    private String indexedName; // address[0] 
    private String index;     // 0
    private String children;  // street
}

这些工具让参数/结果映射通用化，避免硬编码反射调用。

启发：业务中用类似 MetaObject 处理动态表单，省时省力。

九、类型处理

TypeHandlerRegistry

管理类型转换：

registry.register(Integer.class, new IntegerTypeHandler());
registry.register(String.class, new StringTypeHandler());
// 自定义枚举处理
registry.register(MyEnum.class, new EnumTypeHandler<>(MyEnum.class));

getTypeHandler() 根据 JavaType/JdbcType 找。内置 40+ handler，支持自定义如 EnumTypeHandler。JDBC null 处理用 NullTypeHandler。

常见 TypeHandler

// 基础类型
IntegerTypeHandler, LongTypeHandler, StringTypeHandler
// 日期时间  
DateTypeHandler, LocalDateTimeTypeHandler, InstantTypeHandler
// 大对象
BlobTypeHandler, ClobTypeHandler
// 数组
ArrayTypeHandler

自定义 TypeHandler 示例

public class JsonTypeHandler implements TypeHandler<Object> {
    @Override
    public void setParameter(PreparedStatement ps, int i, Object parameter, JdbcType jdbcType) {
        ps.setString(i, JSON.toJSONString(parameter));
    }

    @Override
    public Object getResult(ResultSet rs, String columnName) {
        return JSON.parseObject(rs.getString(columnName));
    }
}

类型别名 TypeAliasRegistry 简化配置，如 “int” alias Integer。

十、日志与调试

日志抽象

日志用 Log 接口，适配多种框架（SLF4J、Log4J 等）。配置 logImpl=SLF4J。

public interface Log {
    boolean isDebugEnabled();
    void debug(String s);
    void debug(String s, Throwable e);
    // ... 其他级别
}

具体实现

• Slf4jImpl
• Log4jImpl
• Log4j2Impl
• JdkLoggingImpl
• CommonsLoggingImpl
• StdOutImpl（标准输出）
• NoLoggingImpl（无日志）

SQL 日志

StatementLog 在 prepare/execute 前后 log SQL 和 params。调试时，开启 trace 级别看绑定参数：

2023-01-01 10:00:00.001 [main] DEBUG c.example.mapper.UserMapper.selectById - ==>  Preparing: SELECT * FROM user WHERE id = ?
2023-01-01 10:00:00.002 [main] DEBUG c.example.mapper.UserMapper.selectById - ==> Parameters: 1(Integer)
2023-01-01 10:00:00.005 [main] DEBUG c.example.mapper.UserMapper.selectById - <==      Total: 1

感悟：日志设计早，帮我排查过无数 SQL 问题。框架日志抽象让我学到：日志别硬编码，适配器模式永不过时。

十一、SQL 重用与优化

性能优化策略

• ReuseExecutor 缓存 Statement，减少 prepare 调用
• BatchExecutor 批量 addBatch()，executeBatch() 一次性发
• 预编译 SQL 用 #{}，参数复用安全
• 一级缓存 避重复查询，二级缓存跨 Session
• RowBounds 内存分页（不推荐大结果集，用物理分页）
• 懒加载 延迟嵌套查询

SQL 执行流程优化

// 1. SQL 解析缓存
MappedStatement ms = configuration.getMappedStatement(statement);

// 2. 参数处理优化
BoundSql boundSql = ms.getBoundSql(parameter);
CacheKey cacheKey = createCacheKey(ms, parameter, rowBounds, boundSql);

// 3. 缓存命中检查  
List<E> list = resultHandler == null ? (List<E>) localCache.getObject(cacheKey) : null;
if (list != null) {
    // 缓存命中，直接返回
    return list;
}

// 4. 数据库查询
list = doQuery(ms, parameter, rowBounds, resultHandler, boundSql);
localCache.putObject(cacheKey, list);

优化建议

1. 监控 slow SQL：用插件加执行时间 log
2. 高负载调优：调 cache size，避免 OOM
3. 连接池配置：合理设置 maxActive、maxIdle
4. 批量操作：使用 BatchExecutor，避免 N+1 查询
5. 结果集优化：只查需要的字段，避免 SELECT *

十二、配置与初始化

Configuration 核心配置

Configuration 是 MyBatis 的配置中心，包含所有配置信息：

public class Configuration {
    // 核心组件
    protected Environment environment;
    protected boolean safeRowBoundsEnabled;
    protected boolean safeResultHandlerEnabled = true;
    protected boolean mapUnderscoreToCamelCase;
    protected boolean aggressiveLazyLoading;
    protected boolean multipleResultSetsEnabled = true;
    protected boolean useGeneratedKeys;
    protected boolean useColumnLabel = true;
    protected boolean cacheEnabled = true;
    protected boolean callSettersOnNulls;
    protected boolean useActualParamName = true;
    
    // 注册中心
    protected final TypeHandlerRegistry typeHandlerRegistry = new TypeHandlerRegistry(this);
    protected final TypeAliasRegistry typeAliasRegistry = new TypeAliasRegistry();
    protected final LanguageDriverRegistry languageRegistry = new LanguageDriverRegistry();
    
    // 映射语句
    protected final Map<String, MappedStatement> mappedStatements = new StrictMap<>();
    protected final Map<String, Cache> caches = new StrictMap<>();
    protected final Map<String, ResultMap> resultMaps = new StrictMap<>();
    protected final Map<String, ParameterMap> parameterMaps = new StrictMap<>();
}

XML 解析流程

// 1. 解析 mybatis-config.xml
XMLConfigBuilder configBuilder = new XMLConfigBuilder(inputStream);
Configuration config = configBuilder.parse();

// 2. 解析 Mapper XML
XMLMapperBuilder mapperBuilder = new XMLMapperBuilder(inputStream, config, resource);
mapperBuilder.parse();

// 3. 构建 SqlSessionFactory
SqlSessionFactory factory = new DefaultSqlSessionFactoryBuilder().build(config);

注解解析

@Select("SELECT * FROM user WHERE id = #{id}")
@Results({
    @Result(property = "id", column = "id"),
    @Result(property = "name", column = "user_name")
})
User selectById(@Param("id") Integer id);

MapperAnnotationBuilder 解析注解，转换成 MappedStatement。

十三、对日常开发的启发

设计模式应用

1. 接口优先，解耦模块：SqlSession 接口隐藏实现，换 Executor 零成本。业务中多用接口，易测试/扩展
2. 关注点分离：SQL 构建、参数、结果、事务、缓存各模块独立。避免 monolithic 代码
3. 可插拔设计：插件让扩展 non-invasive。业务用 AOP 类似
4. 装饰器模式：CachingExecutor、各种 Cache 装饰器
5. 策略模式：多种 Executor 实现，运行时选择
6. 模板方法：BaseExecutor 定义执行模板，子类实现具体逻辑

架构思想

1. 动态静态平衡：静态高性能，动态灵活。项目中混用
2. 抽象复杂性：反射/OGNL/TypeHandler 藏细节。业务抽象工具类
3. 透明执行：业务无感知 JDBC，专注逻辑
4. 配置驱动：XML/注解配置，代码零侵入
5. 缓存分层：一级/二级缓存，不同粒度不同策略

实战经验总结

// 1. 善用批量操作
SqlSession batchSession = factory.openSession(ExecutorType.BATCH);
for (User user : users) {
    batchSession.insert("insertUser", user);
}
batchSession.commit();

// 2. 合理使用缓存
@CacheNamespace(
    size = 512,
    flushInterval = 60000,
    eviction = LRU.class,
    readWrite = false
)

// 3. 自定义类型处理
@MappedTypes({MyEnum.class})
@MappedJdbcTypes({JdbcType.VARCHAR})
public class MyEnumTypeHandler implements TypeHandler<MyEnum> {
    // 实现类型转换逻辑
}

// 4. 插件扩展
@Intercepts(@Signature(type = StatementHandler.class, method = "prepare"))  
public class SqlPrintPlugin implements Interceptor {
    // 打印执行的 SQL
}

十四、进阶主题

MyBatis-Spring 集成

@Configuration
@MapperScan("com.example.mapper")
public class MyBatisConfig {
    
    @Bean
    public SqlSessionFactory sqlSessionFactory(DataSource dataSource) {
        SqlSessionFactoryBean factory = new SqlSessionFactoryBean();
        factory.setDataSource(dataSource);
        return factory.getObject();
    }
    
    @Bean
    public SqlSessionTemplate sqlSessionTemplate(SqlSessionFactory factory) {
        return new SqlSessionTemplate(factory);
    }
}

分页插件实现原理

@Intercepts(@Signature(type = Executor.class, method = "query"))
public class PageInterceptor implements Interceptor {
    
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        Object[] args = invocation.getArgs();
        MappedStatement ms = (MappedStatement) args[0];
        Object parameter = args[1];
        RowBounds rowBounds = (RowBounds) args[2];
        
        if (rowBounds != RowBounds.DEFAULT) {
            // 构造 COUNT SQL
            String countSql = "SELECT COUNT(*) FROM (" + originalSql + ") tmp_count";
            // 构造分页 SQL  
            String pageSql = originalSql + " LIMIT " + rowBounds.getOffset() + "," + rowBounds.getLimit();
            
            // 先查总数，再查分页数据
            // ...
        }
        
        return invocation.proceed();
    }
}

看完了？说点什么呢