简介

在 .NET 异步编程里，Task 大多数时候都是“自动完成”的。

比如：

• async 方法执行完了，返回的 Task 自动完成；
• HttpClient.GetAsync 底层 I/O 完成了，Task 自动完成；
• Task.Run 里的委托跑完了，Task 自动完成。

但还有一类场景，不是“代码块执行完就结束”，而是：

• 某个回调什么时候被触发，不确定；
• 某个事件什么时候到来，不确定；
• 某个外部信号什么时候准备好，不确定；
• 你需要自己决定这个异步操作什么时候成功、失败或取消。

这时候，Task 就不能只靠“自动执行”来产生了，而需要一个“手动完成器”。

TaskCompletionSource<T> 就是干这个的。

一句话先给结论：

TaskCompletionSource<T> 的作用，不是启动任务，而是手动控制一个 Task<T> 什么时候完成。

这篇文章重点讲清楚几件事：

• TaskCompletionSource<T> 到底是什么；
• 它和 Task.Run、async/await 的边界在哪里；
• 回调、事件为什么经常要靠它桥接成 Task；
• SetResult、SetException、SetCanceled 到底意味着什么；
• 为什么很多代码都应该优先用 TrySet*；
• RunContinuationsAsynchronously 为什么是实战里的关键选项；
• 使用 TaskCompletionSource<T> 最容易踩的坑有哪些。

先拆几个最容易混淆的点

1. TaskCompletionSource<T> 不负责执行工作

很多人第一次看到它，会误以为它和 Task.Run 差不多，也是“创建一个异步任务”。

其实不是。

Task.Run 的重点是：

• 把一个委托扔到线程池执行；
• 由运行时去调度这段代码；
• 最终把执行结果包装成一个 Task。

而 TaskCompletionSource<T> 的重点是：

• 先生成一个还没完成的 Task<T>；
• 什么时候完成，不由委托自动决定；
• 而是由你在外部手动调用 SetResult / SetException / SetCanceled 来决定。

所以它更像：

• 一个 Task 的生产者控制器；
• 而不是一个工作执行器。

2. 它不等于“开线程”

TaskCompletionSource<T> 本身不会新开线程，也不会自动占用线程。

例如：

var tcs = new TaskCompletionSource<string>();

这行代码只是创建了一个“尚未完成的任务源”，并没有开始任何后台工作。

后面如果有别的线程、回调、事件、定时器或 I/O 完成信号去调用：

tcs.SetResult("ok");

等待这个 Task 的代码才会继续。

3. 它最适合做“桥接”

TaskCompletionSource<T> 最常见的价值，不是替代 async/await，而是补上 Task 世界和“非 Task 世界”之间的缺口。

比如：

• 老式回调 API；
• 事件通知模型；
• 某些底层协议回包；
• 自定义同步原语；
• 一个操作的完成由多个条件共同决定。

这些场景天然不是 Task 形式，但业务代码又很希望能直接：

await SomethingAsync();

这时就需要 TaskCompletionSource<T> 来做桥接。

TaskCompletionSource<T> 到底是什么？

可以把它拆成两部分理解：

1. 它持有一个 Task<T>

通过 Task 属性，你可以拿到一个供外部等待的任务：

var tcs = new TaskCompletionSource<int>();
Task<int> task = tcs.Task;

调用方拿到的只是这个 Task<int>，并不知道也不应该知道背后的完成细节。

2. 它掌握这个 Task<T> 的完成权

你可以显式控制三种完成方式：

tcs.SetResult(123);
tcs.SetException(new InvalidOperationException("failed"));
tcs.SetCanceled();

也就是说，TaskCompletionSource<T> 的本质是：

让我自己成为这个 Task<T> 的完成者。

这套模型很像生产者和消费者：

• 生产者：TaskCompletionSource<T>，负责发出完成信号；
• 消费者：await tcs.Task 的代码，负责等待结果。

它和 Task.Run 到底有什么区别？

这是最常见、也最值得单独拉出来讲的点。

最简单的判断方式是：

• 你要“让一段代码异步跑起来”，优先想 Task.Run；
• 你要“把一个外部信号转换成可 await 的任务”，优先想 TaskCompletionSource<T>。

基础用法先跑通

先看一个最小示例：

public static async Task DemoAsync()
{
    var tcs = new TaskCompletionSource<int>();

    _ = Task.Run(async () =>
    {
        await Task.Delay(1000);
        tcs.SetResult(42);
    });

    int result = await tcs.Task;
    Console.WriteLine(result);
}

这段代码真正重要的不是 Task.Run，而是流程：

1. 创建一个未完成的 TaskCompletionSource<int>；
2. 把 tcs.Task 暴露给等待方；
3. 将来某个时刻手动调用 SetResult(42)；
4. await tcs.Task 恢复执行，拿到结果。

这里的 Task.Run 只是为了模拟“未来某个时刻有外部信号到来”，真实项目里它更可能来自：

• Socket 回调；
• 消息队列回包；
• UI 事件；
• 定时器；
• 某个订阅通知。

await tcs.Task 时到底发生了什么？

理解 TaskCompletionSource<T>，最好别只停留在“能用”。

看下面这段代码：

var tcs = new TaskCompletionSource<string>();

var task = WaitAsync();
tcs.SetResult("ok");

async Task WaitAsync()
{
    string value = await tcs.Task;
    Console.WriteLine(value);
}

执行流程可以概括成这样：

1. 创建 TaskCompletionSource<string> 时，内部先有了一个未完成的 Task<string>。
2. await tcs.Task 发现任务还没完成，于是当前方法先挂起，并把“后续怎么恢复执行”注册到这个 Task 上。
3. 之后某个时刻，外部代码调用 SetResult("ok")。
4. 这个 Task 被标记为成功完成，等待它的 continuation 开始恢复。
5. await 后面的代码继续往下执行，拿到结果 "ok"。

所以更准确地说：

• await 做的是“注册后续逻辑并在未完成时先返回”；
• SetResult 做的是“宣布任务已经完成，可以恢复等待方了”。

这也是为什么 TaskCompletionSource<T> 特别适合桥接回调和事件。

因为回调、事件这类模型，本质上都缺一个东西：

• 一个能被 await 直接等待的完成信号。

而 TaskCompletionSource<T> 刚好把这个信号补出来了。

一张图看懂 TaskCompletionSource<T> 的工作流程

如果你想把上面的过程快速记成一张图，可以直接看下面这个时序图：

sequenceDiagram
    participant Caller as 调用方
    participant AsyncMethod as 异步方法
    participant TCS as TaskCompletionSource
    participant External as 外部回调/事件

    Caller->>AsyncMethod: 调用方法
    AsyncMethod->>TCS: 创建 TaskCompletionSource
    AsyncMethod-->>Caller: 返回 tcs.Task
    Caller->>TCS: await tcs.Task
    Note over Caller,TCS: Task 尚未完成，await 挂起并注册 continuation
    External->>TCS: 某个时刻触发 SetResult / SetException / SetCanceled
    Note over TCS: Task 状态变为完成
    TCS-->>Caller: 恢复 await 后续逻辑
    Caller->>Caller: 继续执行后面的代码

这张图最关键的信息只有两点：

• await 的本质不是“卡住线程等结果”，而是“先挂起，等 Task 完成后再恢复”；
• TaskCompletionSource<T> 的本质不是“执行异步工作”，而是“在合适的时机把这个 Task 变成已完成”。

三种完成方式分别意味着什么？

1. 成功完成：SetResult

var tcs = new TaskCompletionSource<string>();
tcs.SetResult("done");

string result = await tcs.Task;

此时：

• Task 状态变成成功完成；
• await 直接拿到返回值；
• 后续 continuation 会被触发。

2. 异常完成：SetException

var tcs = new TaskCompletionSource<string>();
tcs.SetException(new InvalidOperationException("bad state"));

string result = await tcs.Task;

此时 await 会重新抛出异常。

也就是说，SetException 不是“记录一下错误”，而是明确告诉等待方：

这次异步操作失败了，应该按异常路径处理。

3. 取消完成：SetCanceled

var tcs = new TaskCompletionSource<string>();
tcs.SetCanceled();

string result = await tcs.Task;

此时 await 会抛出与取消相关的异常。

这条路径和异常路径看起来相似，但语义不一样：

• SetException：操作失败了；
• SetCanceled：操作没有继续执行下去，属于取消。

如果你手里有对应的 CancellationToken，也可以带上它：

tcs.SetCanceled(cancellationToken);

这样等待方能保留更完整的取消上下文。

为什么实战里更推荐 TrySet*

SetResult、SetException、SetCanceled 都有一个共同前提：

• 这个 Task 之前还没完成过。

如果已经有别的线程或别的回调先一步完成了它，再调 Set* 就会抛异常。

所以在这些场景里，通常更推荐：

• 多个竞争路径都可能完成任务；
• 超时、取消、正常结果可能同时抢完成权；
• 事件或回调可能重复触发；
• 并发环境下存在竞态。

示例：

var tcs = new TaskCompletionSource<string>();

_ = Task.Run(async () =>
{
    await Task.Delay(1000);
    tcs.TrySetResult("success");
});

_ = Task.Run(async () =>
{
    await Task.Delay(500);
    tcs.TrySetCanceled();
});

这里最终只有一个分支会成功完成任务，另一个分支会返回 false，但不会抛异常。

因此更务实的经验是：

• 明确只有单一路径完成时，可以用 Set*；
• 只要存在竞争，优先用 TrySet*。

最经典的场景：把回调 API 包成 Task

假设你有一个老式 API：

public void BeginLoadUser(Action<User> onSuccess, Action<Exception> onError)
{
    // 某个库内部完成后回调
}

如果直接使用，调用方通常会写成回调嵌套。

更现代的写法往往希望是：

User user = await LoadUserAsync();

这时就可以这样桥接：

public Task<User> LoadUserAsync()
{
    var tcs = new TaskCompletionSource<User>(
        TaskCreationOptions.RunContinuationsAsynchronously);

    BeginLoadUser(
        user => tcs.TrySetResult(user),
        ex => tcs.TrySetException(ex));

    return tcs.Task;
}

这个例子里，TaskCompletionSource<User> 做了两件事：

• 把原本的回调模型转换成 Task<User>；
• 把成功和失败语义自然映射进 await 流程。

于是上层代码就能写成：

var user = await LoadUserAsync();

这也是 TaskCompletionSource<T> 最标准、最有价值的用法之一。

第二个高频场景：把事件变成可等待任务

比如你想“等待下一条消息到来”：

public Task<string> WaitNextMessageAsync(MessageClient client)
{
    var tcs = new TaskCompletionSource<string>(
        TaskCreationOptions.RunContinuationsAsynchronously);

    void OnMessage(object? sender, MessageEventArgs e)
    {
        client.MessageReceived -= OnMessage;
        tcs.TrySetResult(e.Text);
    }

    client.MessageReceived += OnMessage;

    return tcs.Task;
}

调用方就可以：

string message = await WaitNextMessageAsync(client);

但这种写法有一个很关键的细节：

• 事件一旦完成，要及时解绑；
• 否则可能造成重复触发、内存泄漏，甚至错误完成别的等待操作。

如果还需要支持异常和取消，就要把清理逻辑补完整。

再看一个更接近实战的版本：事件 + 取消

public Task<string> WaitNextMessageAsync(
    MessageClient client,
    CancellationToken cancellationToken = default)
{
    var tcs = new TaskCompletionSource<string>(
        TaskCreationOptions.RunContinuationsAsynchronously);

    EventHandler<MessageEventArgs>? handler = null;
    CancellationTokenRegistration registration = default;

    handler = (sender, e) =>
    {
        client.MessageReceived -= handler;
        registration.Dispose();
        tcs.TrySetResult(e.Text);
    };

    client.MessageReceived += handler;

    if (cancellationToken.CanBeCanceled)
    {
        registration = cancellationToken.Register(() =>
        {
            client.MessageReceived -= handler;
            tcs.TrySetCanceled(cancellationToken);
        });
    }

    return tcs.Task;
}

这里要注意三点：

• 事件完成后要解绑；
• 取消时也要解绑；
• CancellationTokenRegistration 也应该及时释放。

否则代码“逻辑上能跑”，但长期运行会留下资源和行为问题。

一个更像生产代码的包装模板

很多时候，真正难的不是“怎么把回调转成 Task”，而是怎么把收尾逻辑放对位置。

下面这个模板更接近实际项目里的写法：

public Task<string> SendAndWaitAsync(
    Request request,
    CancellationToken cancellationToken = default)
{
    var tcs = new TaskCompletionSource<string>(
        TaskCreationOptions.RunContinuationsAsynchronously);

    EventHandler<ResponseEventArgs>? handler = null;
    CancellationTokenRegistration registration = default;

    void Cleanup()
    {
        _client.ResponseReceived -= handler;
        registration.Dispose();
    }

    handler = (sender, e) =>
    {
        if (e.RequestId != request.Id)
        {
            return;
        }

        Cleanup();
        tcs.TrySetResult(e.Payload);
    };

    _client.ResponseReceived += handler;

    if (cancellationToken.CanBeCanceled)
    {
        registration = cancellationToken.Register(() =>
        {
            Cleanup();
            tcs.TrySetCanceled(cancellationToken);
        });
    }

    try
    {
        _client.Send(request);
    }
    catch (Exception ex)
    {
        Cleanup();
        tcs.TrySetException(ex);
    }

    return tcs.Task;
}

这个模板里有几个关键点：

• 先订阅，再发请求，避免响应回来得太快而错过事件；
• 统一抽一个 Cleanup，避免成功、失败、取消三条路径清理不一致；
• 回调里先过滤无关消息，再尝试完成 TCS；
• 发送请求本身如果同步抛错，也要把 Task 走到异常完成，而不是让等待方永远挂住。

TaskCompletionSource<T> 和超时控制怎么配合？

超时控制也是它的高频用法。

例如，我们想等待某个外部响应，但最多等 5 秒：

public async Task<string> WaitResponseAsync()
{
    var tcs = new TaskCompletionSource<string>(
        TaskCreationOptions.RunContinuationsAsynchronously);

    using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));

    using var registration = cts.Token.Register(() =>
    {
        tcs.TrySetException(new TimeoutException("等待响应超时。"));
    });

    StartRequest(response =>
    {
        tcs.TrySetResult(response);
    });

    return await tcs.Task;
}

这里本质上是两个完成路径在竞争：

• 正常回包；
• 超时触发。

所以使用 TrySet* 才更稳妥。

不过要特别注意一个边界：

你让 TaskCompletionSource<T> 超时完成，并不等于底层真实操作一定被取消了。

这点非常重要。

比如：

• 你只是让等待方不再继续等；
• 但底层网络请求、设备操作、第三方 SDK 任务，可能还在继续跑。

所以“超时了”分成两个层面：

• 等待逻辑超时；
• 底层操作真的被取消。

如果你需要两者都成立，就必须把取消信号继续传到底层系统，而不能只完成一个 TCS。

RunContinuationsAsynchronously 为什么这么重要？

这是 TaskCompletionSource<T> 最容易被忽视，也最容易在生产环境出问题的一点。

先看现象：

当你调用：

tcs.SetResult(value);

如果没有额外选项，等待这个任务的 continuation 有可能就在当前线程上同步执行。

这会带来几个风险：

• 让触发完成的线程顺带执行一大段后续逻辑；
• 回调链条彼此嵌套，增加栈深度；
• 某些锁、串行队列或单线程上下文里，更容易形成卡死或延迟放大。

所以更稳妥的构造方式通常是：

var tcs = new TaskCompletionSource<string>(
    TaskCreationOptions.RunContinuationsAsynchronously);

这个选项的意义是：

• 即使任务被完成了；
• 后续 continuation 也尽量异步调度出去；
• 而不是直接在当前 SetResult 的线程里内联执行。

这并不是说“任何时候都必须加”，但在绝大多数通用库、基础设施代码、并发协调代码里，它通常都是更安全的默认选择。

可以把它理解成：

不要让“完成任务的人”顺手把“等待任务后的整段业务逻辑”也一起跑掉。

一张图看懂 RunContinuationsAsynchronously 的区别

这个选项抽象上不复杂，但很多人第一次读文字说明时，很难立刻建立画面感。

可以直接看下面这组对比图。

未开启 RunContinuationsAsynchronously：

sequenceDiagram
    participant Producer as 完成任务的线程
    participant TCS as TaskCompletionSource
    participant Awaiter as await 后续逻辑

    Producer->>TCS: SetResult()
    TCS-->>Awaiter: 可能直接内联执行 continuation
    Awaiter-->>Producer: 当前线程继续跑后续业务代码

开启 RunContinuationsAsynchronously：

sequenceDiagram
    participant Producer as 完成任务的线程
    participant TCS as TaskCompletionSource
    participant Scheduler as 调度器 / 线程池
    participant Awaiter as await 后续逻辑

    Producer->>TCS: SetResult()
    TCS->>Scheduler: 投递 continuation
    Scheduler-->>Awaiter: 稍后异步执行 continuation

如果把这张图翻成更直白的话，就是：

• 没开 RunContinuationsAsynchronously 时，SetResult() 的那个线程，可能顺手把 await 后面的代码也一起执行了；
• 开了之后，完成任务和执行 continuation 这两件事会尽量拆开，后续逻辑改为异步调度。

这也是为什么在这些场景里，它通常更值得加上：

• 锁内部完成任务；
• 事件回调线程里完成任务；
• 单线程上下文或串行执行器里完成任务；
• 通用库、基础设施组件、并发协调组件。

一个典型坑：在锁里完成 TaskCompletionSource<T>

看一个简化例子：

private readonly object _lock = new();
private TaskCompletionSource<bool>? _waiter;

public Task WaitAsync()
{
    lock (_lock)
    {
        _waiter ??= new TaskCompletionSource<bool>();
        return _waiter.Task;
    }
}

public void Signal()
{
    lock (_lock)
    {
        _waiter?.SetResult(true);
        _waiter = null;
    }
}

这段代码的问题在于：

• SetResult(true) 可能同步执行 continuation；
• continuation 又可能回过头来访问同一个对象；
• 于是锁竞争、重入、阻塞链条都会变复杂。

更稳妥的思路通常是：

• 要么使用 RunContinuationsAsynchronously；
• 要么先把待完成对象拿到锁外，再执行完成动作。

例如：

private readonly object _lock = new();
private TaskCompletionSource<bool>? _waiter;

public Task WaitAsync()
{
    lock (_lock)
    {
        _waiter ??= new TaskCompletionSource<bool>(
            TaskCreationOptions.RunContinuationsAsynchronously);
        return _waiter.Task;
    }
}

public void Signal()
{
    TaskCompletionSource<bool>? waiter;

    lock (_lock)
    {
        waiter = _waiter;
        _waiter = null;
    }

    waiter?.TrySetResult(true);
}

这样会安全很多。

常见坑 1：把它当成“异步工作启动器”

错误方向通常长这样：

public Task DoWorkAsync()
{
    var tcs = new TaskCompletionSource<bool>();
    return tcs.Task;
}

如果后面根本没有任何地方去完成这个 tcs，那这个任务就会永远挂着。

所以使用 TaskCompletionSource<T> 时，一定要先问自己：

• 谁来完成它？
• 正常路径在哪里完成？
• 异常路径在哪里完成？
• 取消路径在哪里完成？
• 是否存在永远不完成的分支？

如果这些问题答不上来，通常说明这里还不该上 TaskCompletionSource<T>。

常见坑 2：忘记处理异常路径

很多包装代码只写了成功回调：

public Task<string> GetDataAsync()
{
    var tcs = new TaskCompletionSource<string>();

    BeginOperation(result =>
    {
        tcs.TrySetResult(result);
    });

    return tcs.Task;
}

如果底层 API 还有失败回调、错误事件或断开通知，而你没接进去，结果往往是：

• 上层代码一直等；
• 任务永远不完成；
• 问题很难排查。

因此包装时必须把可能的结束路径补全：

• 成功；
• 失败；
• 取消；
• 超时；
• 资源释放或连接关闭。

常见坑 3：事件桥接后忘记解绑

这在 UI、消息总线、长连接、订阅模型里非常常见。

如果你写了：

client.MessageReceived += handler;

但完成后没有：

client.MessageReceived -= handler;

后果可能包括：

• 同一个等待器被重复触发；
• 旧对象迟迟不能回收；
• 多次调用方法后，订阅越来越多；
• 某次消息错误地完成了别的请求。

所以事件桥接里，“解绑”不是锦上添花，而是正确性的一部分。

常见坑 4：错误理解“取消”

很多人会把这两件事混成一件事：

• tcs.TrySetCanceled()；
• 真正取消底层操作。

实际上，前者只是告诉等待方：

• 这个 Task 以取消语义结束了。

但底层操作如果没有感知 CancellationToken，它依然可能继续运行。

所以当你用 TaskCompletionSource<T> 做取消包装时，要明确自己做的是哪一层：

• 只是取消等待；
• 还是连底层工作一起取消。

如果只是前者，最好在注释或方法命名上把语义写清楚，避免误导调用方。

常见坑 5：在高并发下使用 Set* 导致额外异常

只要存在“谁先完成都行”的竞争关系，就不要轻易写：

tcs.SetResult(value);

因为只要别的路径先完成了，这里就会抛 InvalidOperationException。

更通用、更稳妥的模式通常是：

if (tcs.TrySetResult(value))
{
    // 只有真正赢得完成权时，才做一次性的收尾逻辑
}

这样异常噪音更少，也更方便在竞态场景下做清理。

它和 async/await 是什么关系？

可以这样理解：

• async/await 负责把异步流程写得像同步代码；
• TaskCompletionSource<T> 负责把“原本不是 Task 的完成信号”变成 Task。

两者不是替代关系，而是协作关系。

很多时候，真正的完整写法是：

public async Task<string> ReceiveWithTimeoutAsync(CancellationToken cancellationToken)
{
    var message = await WaitNextMessageAsync(_client, cancellationToken);
    return message.Trim();
}

其中：

• WaitNextMessageAsync 内部靠 TaskCompletionSource<string> 桥接事件；
• 外层业务方法继续用 async/await 组织流程。

所以更准确地说：

TaskCompletionSource<T> 是给 async/await 提供“可等待对象来源”的底层工具之一。

它和 ValueTaskSource 有什么关系？

如果你已经看到 ValueTask、IValueTaskSource 那一层，会发现两者有一点相似：

• 都涉及“手动控制异步完成”；
• 都不是直接执行工作；
• 都是异步基础设施的一部分。

但定位不一样：

• TaskCompletionSource<T>：给你一个手动完成的 Task<T>，易用、通用；
• IValueTaskSource / ManualResetValueTaskSourceCore<T>：给高性能组件做更底层、更可复用的异步承载，复杂很多。

所以在绝大多数业务和普通框架代码里：

• 能用 TaskCompletionSource<T> 解决的问题，通常没必要上 ValueTaskSource。

什么场景特别适合用它？

如果你遇到下面这些问题，基本都可以优先想到 TaskCompletionSource<T>：

• 把回调风格 API 包成 Task；
• 把事件模型转成 await；
• 等待某个外部信号；
• 把多条竞争路径合并成一个等待点；
• 自己实现一个异步协调原语；
• 给旧接口补上超时、取消、组合等待能力。

反过来说，如果你的需求只是：

• 跑一段 CPU 计算；
• 把同步代码临时丢到后台；

那就不该优先想到 TaskCompletionSource<T>，而更可能是：

• Task.Run；
• 线程池；
• 真正的异步 I/O API。

总结

TaskCompletionSource<T> 最重要的价值，不是“又一种创建任务的方法”，而是：

• 让你手动控制 Task 的完成；
• 让非 Task 世界的信号，能自然接入 async/await；
• 让成功、失败、取消都能被统一表示成标准异步语义。

实战里最该记住的几点是：

• 它不是工作执行器，而是任务完成控制器；
• 回调、事件、外部信号桥接，是它最核心的用途；
• 只要存在竞争，优先用 TrySet*；
• 通用库和并发协调代码里，通常应该考虑 RunContinuationsAsynchronously；
• 超时或取消一个 TCS，不等于底层操作真的被取消了。

如果你已经理解了 Task、async/await，那 TaskCompletionSource<T> 就是下一步必须掌握的关键拼图。

因为从这一层开始，你才真正拥有了：

“不是只会等待异步，而是能自己定义异步完成方式”的能力。

在日常办公和文档管理中，我们经常需要将多个独立的 PDF 文件整合成一个完整的文档。无论是将分散的章节合并成完整的报告，还是将多份合同文件整理为单一档案，PDF 合并操作都是一项非常实用的技能。

本文将介绍如何使用 Python 和 Spire.PDF 库来合并多个 PDF 文件，包括简单的顺序合并、选择性页面导入以及基于流的合并等多种方法，帮助您高效地完成文档整合任务。

为什么需要合并 PDF 文件？

合并 PDF 文件在实际工作中有着广泛的应用场景：

• 文档整合：将分散的章节、附录或补充材料合并成完整的报告或手册
• 档案管理：将相关的多份文件（如合同、附件、补充协议）整理为单一档案
• 简化分享：将多个小文件合并为一个，便于通过邮件发送或在线分享
• 批量处理：自动化合并大量 PDF 文件，提高工作效率
• 保持格式：与转换为其他格式再合并相比，直接合并 PDF 可以保持原有的排版和样式

通过 Python 自动化这一过程，可以快速处理大量文件，避免手动操作的繁琐和出错风险。

环境准备

首先，需要安装 Spire.PDF for Python 库。可以通过 pip 命令轻松完成安装：

pip install Spire.PDF

安装完成后，即可在 Python 脚本中导入该库并使用其提供的文档合并功能。

基础合并：通过选择页面构建新 PDF

使用 InsertPage 和 InsertPageRange 方法

除了简单的全文合并，Spire.PDF 还允许我们创建一个全新的 PDF 文档，并从现有的多个 PDF 文件中挑选特定页面或页面范围进行组合。这种方法非常适合需要对页面顺序进行重组或仅提取部分内容的场景。

以下代码演示了如何从三个不同的 PDF 文件中提取特定页面，并将它们整合到一个新的文档中：

from spire.pdf import *
from spire.pdf.common import *

# 定义要处理的 PDF 文件路径
file1 = "示例1.pdf"
file2 = "示例2.pdf"
file3 = "示例3.pdf"
files = [file1, file2, file3]

# 加载所有 PDF 文件
pdfs = []
for file in files:
    # 实例化 PdfDocument 对象并加载文件
    doc = PdfDocument()
    doc.LoadFromFile(file)
    pdfs.append(doc)

# 创建一个新的空 PDF 对象（用于存放合并后的页面）
newPdf = PdfDocument()

# 策略 1：插入单个页面 (InsertPage)
# 将第一个文档的第 1 页（索引 0）插入新文档
newPdf.InsertPage(pdfs[0], 0)
# 将第二个文档的第 2 页（索引 1）插入新文档
newPdf.InsertPage(pdfs[1], 1)

# 策略 2：批量插入页面范围 (InsertPageRange)
# 将第三个文档的第 1 页到第 2 页（索引 0 到 1）一次性插入新文档
newPdf.InsertPageRange(pdfs[2], 0, 1)

# 保存合并后的新 PDF 文档
newPdf.SaveToFile("output/复制页面合并PDF.pdf")

# 关闭资源
newPdf.Close()
for pdf in pdfs:
    pdf.Close()

这段代码展示了精准控制页面合并的两种核心技术：

1. InsertPage 方法：用于从源文档中提取单个特定页面。它接受源文档对象和页面索引作为参数。在示例中，我们分别从前两个文档中各取一页放入新文档。
2. InsertPageRange 方法：用于批量提取页面范围。它接受三个参数：源文档对象、起始页面索引和结束页面索引。相比多次调用 InsertPage，这种方法在处理连续章节合并时效率更高。

通过这种方式，你可以打破原有的文档结构，像积木一样自由组合来自不同来源的页面，生成一个完全定制化的新 PDF 文件。

高级合并：使用流进行合并

使用 PdfMerger.MergeByStream 方法

除了基于文档对象的合并方式，Spire.PDF 还提供了基于流的合并功能。这种方法特别适合处理来自网络或内存中的 PDF 数据，无需先将数据保存到磁盘文件。

以下示例展示了如何通过流的方式合并多个 PDF 文件：

from spire.pdf.common import *
from spire.pdf import *

# 定义输入文件路径和输出流
inputFile1 = "./Demos/Data/MergePdfsTemplate_1.pdf"
inputFile2 = "./Demos/Data/MergePdfsTemplate_2.pdf"
inputFile3 = "./Demos/Data/MergePdfsTemplate_3.pdf"
outputFile = Stream("MergeFilesByStream.pdf")

# 创建 PDF 文档流
stream1 = Stream(inputFile1)
stream2 = Stream(inputFile2)
stream3 = Stream(inputFile3)

# 将所有流放入列表
streams = [stream1, stream2, stream3]

# 创建合并选项
mergeOp = MergerOptions()

# 通过流合并 PDF 文件
PdfMerger.MergeByStream(streams, outputFile, mergeOp)

这种基于流的合并方法有以下优势：

• 内存效率：可以直接处理内存中的数据，减少磁盘 I/O 操作
• 网络友好：适合处理从网络下载的 PDF 数据，无需先保存到本地
• 简洁高效：一行代码即可完成多个文件的合并，代码更加简洁

MergerOptions 类允许您配置合并过程中的各种选项，例如是否保留书签、如何处理元数据等。虽然本示例使用了默认设置，但在实际应用中可以根据需要进行自定义配置。

实际应用

PDF 合并功能在实际工作中有广泛的应用场景：

批量合并文件夹中的所有 PDF

当需要将某个文件夹中的所有 PDF 文件按名称顺序合并时，可以编写批处理函数来自动化这一过程。以下是一个实用的批量合并示例：

from spire.pdf.common import *
from spire.pdf import *
import os
import glob

def MergePdfFolder(input_folder: str, output_file: str):
    """将文件夹中的所有 PDF 文件按名称顺序合并"""
    
    # 获取文件夹中所有的 PDF 文件并按名称排序
    pdf_files = sorted(glob.glob(os.path.join(input_folder, "*.pdf")))
    
    if not pdf_files:
        print("未找到 PDF 文件")
        return
    
    print(f"找到 {len(pdf_files)} 个 PDF 文件，开始合并...")
    
    # 加载第一个 PDF 文档作为基础文档
    main_doc = PdfDocument()
    main_doc.LoadFromFile(pdf_files[0])
    print(f"已加载基础文档: {os.path.basename(pdf_files[0])}")
    
    # 依次将其他文档追加到基础文档
    for i in range(1, len(pdf_files)):
        temp_doc = PdfDocument()
        temp_doc.LoadFromFile(pdf_files[i])
        main_doc.AppendPage(temp_doc)
        temp_doc.Close()
        print(f"已合并: {os.path.basename(pdf_files[i])}")
    
    # 保存合并后的文件
    main_doc.SaveToFile(output_file)
    main_doc.Close()
    
    print(f"\n合并完成！输出文件: {output_file}")
    print(f"总共合并了 {len(pdf_files)} 个文件")

# 使用示例
input_folder = "./PDF文档"
output_file = "合并结果.pdf"
MergePdfFolder(input_folder, output_file)

这个函数会自动扫描指定文件夹中的所有 PDF 文件，按文件名排序后依次合并，非常适合处理章节化的文档或系列报告。

生成综合报告

企业可以将各部门提交的独立报告合并成一份综合年度报告，保持整体结构的同时方便统一分发和归档。

合同文件整理

法务部门可以将主合同、附件、补充协议等相关文件合并为一个完整的合同包，便于管理和查阅。

电子书制作

将多个章节的 PDF 文件合并成完整的电子书，为读者提供连续的阅读体验。

实用技巧

在进行 PDF 合并时，以下技巧可以帮助获得更好的结果：

• 文件顺序：在合并前确保文件按照期望的顺序排列，可以通过文件名编号来控制顺序
• 页面方向：如果合并的文档有不同的页面方向（横向/纵向），合并后会保持各自的原始方向
• 书签处理：合并后的文档可能会保留各原文档的书签，注意检查书签的层级结构是否合理
• 文件大小：合并大量大文件时注意内存使用情况，考虑分批处理
• 验证结果：合并完成后务必打开结果文件进行检查，确保所有页面都正确包含且顺序无误

总结

通过本文的介绍，我们学习了使用 Python 和 Spire.PDF 库合并 PDF 文件的多种方法：

• 使用 AppendPage 方法将整个文档追加到目标文档末尾
• 使用 InsertPage 方法选择性地将特定页面插入到目标文档
• 使用 PdfMerger.MergeByStream 方法通过流进行高效合并
• 实现批量合并功能处理文件夹中的多个 PDF 文件

这些技术为 PDF 文档的整合和管理提供了强大的工具。掌握这些技能后，您将能够高效地合并多个 PDF 文件，将分散的文档资源整合为统一的完整文档，显著提升工作效率和文档管理的专业性。

很多人以为IP地址查询能直接定位到家庭门牌号，也有人觉得它什么都查不到。实际上，IP查询有明确的能力边界：它能定位到城市级或区县级，能识别网络类型（住宅宽带/数据中心/移动网络），但无法精准锁定具体街道或家庭地址。 理解这个边界，才能科学地保护隐私。本文通过三步实操，带你用IP查询工具自查暴露风险，并给出可落地的网络出口配置方案。

一、IP查询到底能查到什么？实测数据说话

IP归属地查询的本质，是将IP地址映射到运营商注册的地理位置。我们以一台连接家庭宽带的电脑为例，用IP查询工具进行一次实际查询（以IP数据云在线页面为例），使用正规IP查询工具查询IP归属地，是单向、无记录的查询过程。工具仅根据IP返回公开的地理信息，不会记录查询者的身份、不会存储查询历史，更不会暴露用户自己的隐私。返回的信息如下：

实操第一步：自查你的IP暴露信息

打开任意IP查询网站（如ipdatacloud.com），页面会自动显示你当前公网IP的归属地、运营商和网络类型。记录下显示的城市和网络类型，用于下一步评估。

二、IP查询的边界：哪些信息是查不到的？

很多人担心“别人查我的IP就能知道我住哪”，实际上这是不可能的。IP地址由运营商分配，且会动态变化。运营商对外公开的注册信息通常只到城市级。

IP查询的三大能力边界：

1. 无法定位到具体街道或门牌号：除非运营商主动泄露内部数据，否则任何公开IP库都做不到。
2. 无法实时追踪设备：IP查询只是查数据库，不是实时探测。
3. 无法绕过NAT识别具体设备：同一个家庭WiFi下的多台设备，对外显示同一个公网IP。

实操第二步：对比IP归属地与真实位置

1. 用手机连接家庭WiFi，查询IP归属地城市。
2. 断开WiFi，改用4G/5G流量再次查询。
3. 对比两次结果：不同网络出口显示不同城市，说明出口IP已天然隔离——这是配置网络出口的基础

三、如何用IP查询工具自查隐私暴露风险？

如果你担心自己的真实IP被网站或应用获取，可以主动用IP查询工具自查，了解当前网络出口暴露了哪些信息。

实操第三步：三步完成风险自查

四、安全配置网络出口：不依赖敏感工具也能降低暴露风险

理解IP查询的边界后，保护隐私的核心不是“隐藏IP”，而是合理配置网络出口。以下是几种不依赖敏感工具的安全方案，附带具体操作步骤：

实操建议（可立即执行） ：

对于普通用户，最简单的隐私保护方法是定期重启路由器获取新IP，或者在不同场景下使用不同的网络出口（如家用宽带用来看视频，手机热点用来登录敏感账号）。不需要复杂的技术，就能有效避免IP被长期关联。

五、总结

IP查询工具的价值在于帮助用户了解自己的网络暴露面，而不是制造恐慌。它能查到城市级位置和网络类型，但无法定位到具体住址。通过三步实操（查IP→对比出口→评估风险），用户可以评估当前隐私暴露程度，并通过简单的网络出口切换（重启路由器、切换WiFi/热点）来降低长期被追踪的可能。

在查询IP是也要选择专业工具，合理保护隐私，IP数据云提供城市级定位和网络类型识别能力，能帮助用户快速完成上述自查。理解IP查询的边界，配合合理的网络出口配置，就能在不依赖敏感工具的前提下，有效保护个人隐私。

如果您的软件面向Windows生态分发、涉及敏感数据或驱动开发，EV代码签名证书无疑是最优之选。选择权威CA机构（如JoySSL），完成严谨的身份核验，让您的软件从发布第一刻起便赢得系统与用户的信任。

一、什么是EV代码签名证书？

EV（Extended Validation，扩展验证）代码签名证书，是遵循最严格国际验证标准的数字证书。它不仅仅验证开发者对代码的所有权，更通过严格的线下企业身份核实流程，确认申请者是一个合法、真实存在的实体机构。

与普通代码签名证书（如OV组织验证证书）相比，EV证书的审核堪称“数字身份的政审”。CA机构会要求企业提交营业执照、法人身份证明、对公账户证明、办公场地证明等全套材料，并通过工商数据库、银行渠道交叉验证，甚至直接拨打企业公开电话与法定代表人确认申请意愿。审核周期通常为3至7个工作日。这种穿透式审核从源头杜绝了虚假身份申请证书的可能，而普通证书曾出现过“空壳公司申请证书签署恶意软件”的案例，印证了身份核验差异带来的安全鸿沟。

二、为何EV证书是开发者的首选？

1. 硬件级私钥保护：杜绝私钥泄露

EV证书最核心的安全机制在于私钥的强制硬件存储。其私钥必须存储在符合FIPS 140-2标准的硬件安全模块（HSM）或USB加密狗中，与开发者设备物理绑定，每次签名需插入加密狗并输入独立密码，形成“硬件+密码”的双重防护。普通证书的私钥若存储在本地硬盘，可能因电脑中毒导致泄露；而EV证书的私钥无法被导出或复制，从根源上杜绝了签名滥用风险。

2. 系统级即时信任：突破SmartScreen拦截

对Windows平台开发者而言，“Windows SmartScreen已阻止启动此未验证的应用”是影响软件分发与用户信任的最大障碍。普通代码签名证书需从零开始积累信誉——只有当软件被足够多用户下载且未触发安全警报时，评分才会逐步提升，这一过程可能持续数周甚至数月。而EV证书凭借CA机构的穿透式审核，在签发时就为软件注入“初始信誉分”，新软件发布即可绕过拦截。测试数据显示，使用EV证书后首次发布的软件拦截率可降至8%，安装完成率提升至76%。

此外，EV证书具备“信誉继承”能力。当企业发布新版本软件时，SmartScreen会自动识别签名信息并关联历史信誉，某ERP厂商使用EV证书后，新版本发布时的初始信誉分达到历史版本的80%，较更换证书前提升65%。

3. 强制场景适配：驱动开发与合规通行证

EV证书在以下场景中具有不可替代性：

• Windows内核驱动开发：微软要求所有64位内核模式驱动必须通过EV签名，且需通过WHQL认证，否则无法加载运行。OV证书无法满足WHQL认证的核心需求。
• 金融/医疗等高敏感行业：涉及用户隐私数据或资金安全的软件需满足等保2.0三级要求，EV证书的审核流程天然满足PCIDSS、HIPAA等行业法规的合规要求。
• 物联网与工业控制：智能汽车车载系统、工业PLC设备对软件安全性要求极高，EV证书签名的固件更新包能被设备系统直接信任并安装。

三、总结

EV代码签名证书通过穿透式身份核验、硬件级私钥保护、系统级即时信任三大核心优势，为开发者提供了从代码到用户的全链路安全屏障。虽然其审核周期较长（3-7个工作日）、成本高于OV证书，但在高安全需求场景中，它所提供的信任价值和合规保障是普通证书无法替代的。对于追求专业度与用户信任的开发者而言，EV证书不仅是一项技术投资，更是软件品牌资产的长期积累。

从代码签名的技术与合规角度，“未知开发者 / 未知发布者” 的核心原因是：你的软件没有被系统信任的数字证书签名，导致操作系统（Windows SmartScreen /macOS Gatekeeper）无法验证发布者身份与代码完整性。

下面从原理 → 证书选型 → Windows 签名 → macOS 签名 → 长期信任完整说明。

• • *

一、为什么未签名会报 “未知开发者”？

系统安全机制的核心判断：

• 身份不可信：没有权威 CA（证书颁发机构）签发的代码签名证书，系统无法确认 “软件是谁做的”
• 完整性风险：未签名文件可能被篡改、植入病毒，签名一旦被修改就会失效
• 信誉机制：Windows SmartScreen 会对新证书 / 未签名软件强制警告，EV 证书可直接绕过

只有正规代码签名才能彻底消除警告，用户端看到 “发布者：XX 公司”。

• • *

二、代码签名证书类型与选型（Windows）

1. OV 代码签名（组织验证，主流）

• 效果：显示公司名，新证书前 2–8 周仍有警告，积累信誉后自动消失
• 适用：常规软件、工具、安装包（.exe/.msi/.dll）
• 审核：1–3 天，需营业执照、法人信息

2. EV 代码签名（扩展验证，最高信任）

• 效果：立即消除 SmartScreen 警告，无过渡期
• 价格：¥4,000–8,000 / 年
• 强制场景：内核驱动、Windows 10/11 驱动签名、WHQL 认证
• 安全：私钥存USB Token 硬件（不可导出）
• 审核：5–7 天，更严格的企业核验
• • *

↓

代码签名证书：https://www.joyssl.com/certificate/select/code_signing.html?n...

↑

三、Windows 完整代码签名流程（彻底解决 “未知发布者”）

1. 申请证书（CA 机构）

主流 CA：DigiCert、Sectigo、GlobalSign、JoySSL（国内）

• 准备材料：

  • 企业：营业执照、法人身份证、对公账户验证
  • 个人：个体户执照 + 身份证

• 生成 CSR（证书签名请求）

  powershell

  # PowerShell生成
  New-SelfSignedCertificate -Type CodeSigningCert -Subject "CN=你的公司名" -KeyUsage DigitalSignature

• 提交 CA 审核 → 获取 .pfx 证书（OV）或 USB Token（EV）

2. 用 SignTool 签名（Windows SDK）

（1）安装 SignTool

• 安装 Windows SDK 或 Visual Studio（含签名工具）

（2）签名命令（必加时间戳！）

cmd

signtool sign /f 证书.pfx /p 证书密码 /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 你的软件.exe

• /f：证书文件
• /p：证书密码
• /fd SHA256：签名算法（必须 SHA256，旧 SHA1 无效）
• /tr：时间戳服务器（关键！避免证书过期后签名失效）

（3）验证签名

cmd

signtool verify /pa /v 你的软件.exe

• 成功：显示 “数字签名详细信息”→ 发布者为你的公司名

3. 提升 SmartScreen 信誉（OV 证书必做）

• 保持同一证书长期签名、持续分发
• 提交微软 SmartScreen 信誉申请
• 避免报毒：签名后用杀毒软件扫描、不捆绑恶意程序
• • *

四、macOS 代码签名（解决 “无法打开，因为来自未知开发者”）

1. 前提：苹果开发者账号

• 年费：¥688 / 年（个人 / 公司）
• 申请：Apple Developer → 实名认证

2. 证书类型

• Developer ID Application：用于非 App Store 分发（直接官网下载）Apple Developer

3. 签名 + 公证（macOS 10.15+ 必须）

（1）用 codesign 签名

bash

运行

# 签名（--deep递归签内嵌组件）
codesign --force --deep --sign "Developer ID Application: 你的公司名 (TeamID)" --timestamp 你的App.app

• --timestamp：添加时间戳（必加）
• 查看证书：security find-identity -v -p codesigning

（2）苹果公证（Notarize）—— 强制！

bash

运行

# 上传公证
xcrun notarytool submit 你的App.zip --apple-id 你的邮箱 --password 专用密码 --team-id 你的TeamID

# 查看日志
xcrun notarytool log 提交ID --apple-id 你的邮箱 --password 专用密码 --team-id 你的TeamID

#  stapler 绑定公证结果（离线也可验证）
xcrun stapler staple 你的App.app

• 公证通过后：彻底消除 Gatekeeper 警告

（3）验证

bash

运行

codesign -vvv 你的App.app
spctl -a -vvv 你的App.app

• 成功：accepted、source=Developer ID
• • *

五、关键最佳实践（必看）

1. 必须加时间戳

   • 无时间戳：证书过期 → 签名失效 → 重新报未知发布者

2. SHA256 算法

   • SHA1 已被系统弃用，必须用 SHA256

3. 证书安全

   • EV 私钥存硬件 Token，不导出、不泄露
   • OV 证书（.pfx）加密保存，权限最小化

4. 驱动程序特殊要求

   • Windows 10/11：必须 EV 签名 + WHQL 认证
   • 未签名驱动：无法安装（拦截率≈100%）

5. 避免无效方案

   • 自签名、免费 SSL 证书（Let’s Encrypt）不能用于代码签名

• • *

六、效果对比（签名 vs 未签名）

表格

• • *

七、总结（最简路径）

1. Windows

   • 常规软件：买 OV 代码签名证书 → SignTool SHA256 + 时间戳 → 积累信誉
   • 驱动：EV 证书 + WHQL

2. macOS

   • 苹果开发者账号 → Developer ID 签名 + 公证

一句话：正规代码签名是唯一彻底解决 “未知开发者” 的方法，临时绕过只是权宜之计。

问题：用其普通方法对比（图1）无法对比到其主模块内子模块（gitsubmodule）的diff（图2）

解决：
先用命令输出整体的diff
git diff --submodule=diff you-project-v1.7.7 you-project-v1.7.6 > full_diff.patch
再用apply patch（图1） ，

然后引用打的patch文件包，如下图，sub_* 相关的子模块就可以愉快的看diff了

前面一篇文章，我们手写了了一个mini版的Tomcat，接下来我们从源码和架构的角度来学习Tomcat

引入

Tomcat和Catalina是什么关系？

Tomcat的前身为Catalina，Catalina又是一个轻量级的Servlet容器。在美国，catalina是一个很美的小岛。所以Tomcat作者的寓意可能是想把Tomcat设计成一个优雅美丽且轻量级的web服务器。Tomcat从4.x版本开始除了作为支持Servlet的容器外，额外加入了很多的功能，比如：jsp、el、naming等等，所以说Tomcat不仅仅是Catalina。

什么是Servlet？

所谓Servlet，其实就是Sun为了让Java能实现动态可交互的网页，从而进入Web编程领域而制定的一套标准！

在互联网兴起之初，当时的Sun公司（后面被Oracle收购）已然看到了这次机遇，于是设计出了Applet来对Web应用的支持。不过事实却并不是预期那么得好，Sun悲催地发现Applet并没有给业界带来多大的影响。经过反思，Sun就想既然机遇出现了，市场前景也非常不错，总不能白白放弃了呀，怎么办呢？于是又投入精力去搞一套规范出来，这时Servlet诞生了！

一个Servlet主要做下面三件事情：

• 创建并填充Request对象，包括：URI、参数、method、请求头信息、请求体信息等
• 创建Response对象
• 执行业务逻辑，将结果通过Response的输出流输出到客户端

Servlet没有main方法，所以，如果要执行，则需要在一个容器里面才能执行，这个容器就是为了支持Servlet的功能而存在，Tomcat其实就是一个Servlet容器的实现。

核心架构设计

官网：https://tomcat.apache.org/tomcat-8.0-doc/architecture/overvie...

Tomcat 的架构设计以 ‌模块化、分层、解耦‌ 为核心，遵循 Java Servlet 规范，同时支持高性能、高扩展的 Web 服务。其整体架构可概括为 ‌“连接器（Connector）- 容器（Container）” 双层模型‌，并通过 ‌Lifecycle 生命周期管理机制‌ 和 ‌责任链模式（Pipeline-Valve）‌ 实现组件协同。

Tomcat的架构呈“套娃式”嵌套：Server → Service → (Connector + Engine) → Host → Context → Wrapper

核心架构组成：

• ‌Server‌：代表整个 Tomcat 实例，是顶级容器，管理多个 Service。

• ‌Service‌：将一个或多个 Connector 与一个 Engine 绑定，构成独立服务单元。

  • Manager：管理器，用于管理会话Session
  • Logger：日志器，用于管理日志
  • Loader：加载器，和类加载有关，只会开放给Context所使用
  • Pipeline：管道组件，配合Valve实现过滤器功能
  • Valve：阀门组件，配合Pipeline实现过滤器功能
  • Realm：认证授权组件
• ‌Connector（连接器）‌：负责处理外部 HTTP/AJP 请求，实现网络通信与协议解析。

• ‌Container（容器）‌：负责加载和管理 Servlet，处理业务逻辑，包含四级嵌套容器：

  • ‌Engine‌：处理所有请求，每个 Service 仅有一个。
  • ‌Host‌：虚拟主机，对应一个域名或 IP。
  • ‌Context‌：Web 应用上下文，对应一个 WAR 包或目录。
  • ‌Wrapper‌：最底层容器，封装单个 Servlet。

从web.xml配置和模块对应角度

上述模块的理解不是孤立的，它可以直接映射为Tomcat的web.xml配置，让我们联系起来看

<Server port="8005" shutdown="SHUTDOWN">
  <Listener className="org.apache.catalina.startup.VersionLoggerListener" />

  <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />

  <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener" />
  <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />
  <Listener className="org.apache.catalina.core.ThreadLocalLeakPreventionListener" />

  <GlobalNamingResources>
    <Resource name="UserDatabase" auth="Container"
              type="org.apache.catalina.UserDatabase"
              description="User database that can be updated and saved"
              factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
              pathname="conf/tomcat-users.xml" />
  </GlobalNamingResources>

  <Service name="Catalina">

    <Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443" />
    <Engine name="Catalina" defaultHost="localhost">
      <Realm className="org.apache.catalina.realm.LockOutRealm">
        <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
               resourceName="UserDatabase"/>
      </Realm>

      <Host name="localhost"  appBase="webapps"
            unpackWARs="true" autoDeploy="true">
        <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
               prefix="localhost_access_log" suffix=".txt"
               pattern="%h %l %u %t &quot;%r&quot; %s %b" />

      </Host>
    </Engine>
  </Service>
</Server>

从一个完整请求的角度来看

通过一个完整的HTTP请求，我们还需要把它贯穿起来

假设来自客户的请求为：http://localhost:8080/test/index.jsp 请求被发送到本机端口8080，被在那里侦听的Coyote HTTP/1.1 Connector,然后

• Connector把该请求交给它所在的Service的Engine来处理，并等待Engine的回应
• Engine获得请求localhost:8080/test/index.jsp，匹配它所有虚拟主机Host
• Engine匹配到名为localhost的Host(即使匹配不到也把请求交给该Host处理，因为该Host被定义为该Engine的默认主机)
• localhost Host获得请求/test/index.jsp，匹配它所拥有的所有Context
• Host匹配到路径为/test的Context(如果匹配不到就把该请求交给路径名为""的Context去处理)
• path="/test"的Context获得请求/index.jsp，在它的mapping table中寻找对应的servlet
• Context匹配到URL PATTERN为*.jsp的servlet，对应于JspServlet类，构造HttpServletRequest对象和HttpServletResponse对象，作为参数调用JspServlet的doGet或doPost方法
• Context把执行完了之后的HttpServletResponse对象返回给Host
• Host把HttpServletResponse对象返回给Engine
• Engine把HttpServletResponse对象返回给Connector
• Connector把HttpServletResponse对象返回给客户browser

从源码的设计角度看

从功能的角度将Tomcat源代码分成5个子模块，分别是:

• Jsper模: 这个子模块负责jsp页面的解析、jsp属性的验证，同时也负责将jsp页面动态转换为java代码并编译成class文件。在Tomcat源代码中，凡是属于org.apache.jasper包及其子包中的源代码都属于这个子模块;
• Servlet和Jsp模块: 这个子模块的源代码属于javax.servlet包及其子包，如我们非常熟悉的javax.servlet.Servlet接口、javax.servet.http.HttpServlet类及javax.servlet.jsp.HttpJspPage就位于这个子模块中;
• Catalina模块: 这个子模块包含了所有以org.apache.catalina开头的java源代码。该子模块的任务是规范了Tomcat的总体架构，定义了Server、Service、Host、Connector、Context、Session及Cluster等关键组件及这些组件的实现，这个子模块大量运用了Composite设计模式。同时也规范了Catalina的启动及停止等事件的执行流程。从代码阅读的角度看，这个子模块应该是我们阅读和学习的重点。
• Connector模块: 如果说上面三个子模块实现了Tomcat应用服务器的话，那么这个子模块就是Web服务器的实现。所谓连接器(Connector)就是一个连接客户和应用服务器的桥梁，它接收用户的请求，并把用户请求包装成标准的Http请求(包含协议名称，请求头Head，请求方法是Get还是Post等等)。同时，这个子模块还按照标准的Http协议，负责给客户端发送响应页面，比如在请求页面未发现时，connector就会给客户端浏览器发送标准的Http 404错误响应页面。
• Resource模块: 这个子模块包含一些资源文件，如Server.xml及Web.xml配置文件。严格说来，这个子模块不包含java源代码，但是它还是Tomcat编译运行所必需的。

从后续深入理解的角度

我们看完上述组件结构后，后续应该重点从哪些角度深入理解Tomcat呢？

• 基于组件的架构

我们知道组成Tomcat的是各种各样的组件，每个组件各司其职，组件与组件之间有明确的职责划分，同时组件与组件之间又通过一定的联系相互通信。Tomcat整体就是一个个组件的堆砌！

• 基于JMX

我们在后续阅读Tomcat源码的时候，会发现代码里充斥着大量的类似于下面的代码。

Registry.getRegistry(null, null).invoke(mbeans, "init", false);
Registry.getRegistry(null, null).invoke(mbeans, "start", false);

而这实际上就是通过JMX来管理相应对象的代码。这儿我们不会详细讲述什么是JMX，我们只是简单地说明一下JMX的概念，参考JMX百度百科。

JMX（Java Management Extensions，即Java管理扩展）是一个为应用程序、设备、系统等植入管理功能的框架。JMX可以跨越一系列异构操作系统平台、系统体系结构和网络传输协议，灵活的开发无缝集成的系统、网络和服务管理应用。

• 基于生命周期

如果我们查阅各个组件的源代码，会发现绝大多数组件实现了Lifecycle接口，这也就是我们所说的基于生命周期。生命周期的各个阶段的触发又是基于事件的方式。

启动过程详解

总体流程

我们看下整体的初始化和启动的流程，在理解的时候可以直接和Tomcat架构设计中组件关联上：

启动过程代码浅析

看了下网上关于Tomcat的文章，很多直接关注在纯代码的分析，这种是很难的；我建议你一定要把代码加载进来自己看一下，然后这里我把它转化为核心的几个问题来帮助你理解。

Bootstrap主入口？

Tomcat源码就从它的main方法开始。Tomcat的main方法在org.apache.catalina.startup.Bootstrap 里。让我们带着这个为看下Catalina的初始化的

/**
  * 初始化守护进程
  * 
  * @throws Exception Fatal initialization error
  */
public void init() throws Exception {

    // 初始化classloader（包括catalinaLoader），下文将具体分析
    initClassLoaders();

    // 设置当前的线程的contextClassLoader为catalinaLoader
    Thread.currentThread().setContextClassLoader(catalinaLoader);

    SecurityClassLoad.securityClassLoad(catalinaLoader);

    // 通过catalinaLoader加载Catalina，并初始化startupInstance 对象
    if (log.isDebugEnabled())
        log.debug("Loading startup class");
    Class<?> startupClass = catalinaLoader.loadClass("org.apache.catalina.startup.Catalina");
    Object startupInstance = startupClass.getConstructor().newInstance();

    // 通过反射调用了setParentClassLoader 方法
    if (log.isDebugEnabled())
        log.debug("Setting startup class properties");
    String methodName = "setParentClassLoader";
    Class<?> paramTypes[] = new Class[1];
    paramTypes[0] = Class.forName("java.lang.ClassLoader");
    Object paramValues[] = new Object[1];
    paramValues[0] = sharedLoader;
    Method method =
        startupInstance.getClass().getMethod(methodName, paramTypes);
    method.invoke(startupInstance, paramValues);

    catalinaDaemon = startupInstance;

}

通过上面几行关键代码的注释，我们就可以看出Catalina是如何初始化的。这里还留下一个问题，tomcat为什么要初始化不同的classloader呢？我们将在下文进行详解。

Bootstrap如何初始化Catalina的？

我们用Sequence Diagram插件来看main方法的时序图，但是可以发现它并没有帮我们画出Bootstrap初始化Catalina的过程，这和上面的组件初始化不符合？

让我们带着这个为看下Catalina的初始化的

/**
  * 初始化守护进程
  * 
  * @throws Exception Fatal initialization error
  */
public void init() throws Exception {

    // 初始化classloader（包括catalinaLoader），下文将具体分析
    initClassLoaders();

    // 设置当前的线程的contextClassLoader为catalinaLoader
    Thread.currentThread().setContextClassLoader(catalinaLoader);

    SecurityClassLoad.securityClassLoad(catalinaLoader);

    // 通过catalinaLoader加载Catalina，并初始化startupInstance 对象
    if (log.isDebugEnabled())
        log.debug("Loading startup class");
    Class<?> startupClass = catalinaLoader.loadClass("org.apache.catalina.startup.Catalina");
    Object startupInstance = startupClass.getConstructor().newInstance();

    // 通过反射调用了setParentClassLoader 方法
    if (log.isDebugEnabled())
        log.debug("Setting startup class properties");
    String methodName = "setParentClassLoader";
    Class<?> paramTypes[] = new Class[1];
    paramTypes[0] = Class.forName("java.lang.ClassLoader");
    Object paramValues[] = new Object[1];
    paramValues[0] = sharedLoader;
    Method method =
        startupInstance.getClass().getMethod(methodName, paramTypes);
    method.invoke(startupInstance, paramValues);

    catalinaDaemon = startupInstance;

}

通过上面几行关键代码的注释，我们就可以看出Catalina是如何初始化的。这里还留下一个问题，tomcat为什么要初始化不同的classloader呢？我们将在下文进行详解。

启动过程：类加载机制详解

Tomcat初始化了哪些classloader

在Bootstrap中我们可以看到有如下三个classloader

ClassLoader commonLoader = null;
ClassLoader catalinaLoader = null;
ClassLoader sharedLoader = null;

如何初始化的呢？

private void initClassLoaders() {
    try {
        // commonLoader初始化
        commonLoader = createClassLoader("common", null);
        if (commonLoader == null) {
            // no config file, default to this loader - we might be in a 'single' env.
            commonLoader = this.getClass().getClassLoader();
        }
        // catalinaLoader初始化, 父classloader是commonLoader
        catalinaLoader = createClassLoader("server", commonLoader);
        // sharedLoader初始化
        sharedLoader = createClassLoader("shared", commonLoader);
    } catch (Throwable t) {
        handleThrowable(t);
        log.error("Class loader creation threw exception", t);
        System.exit(1);
    }
}

可以看出，catalinaLoader 和 sharedLoader 的 parentClassLoader 是 commonLoader。

如何创建classLoader的？

不妨再看下如何创建的？

private ClassLoader createClassLoader(String name, ClassLoader parent)
    throws Exception {

    String value = CatalinaProperties.getProperty(name + ".loader");
    if ((value == null) || (value.equals("")))
        return parent;

    value = replace(value);

    List<Repository> repositories = new ArrayList<>();

    String[] repositoryPaths = getPaths(value);

    for (String repository : repositoryPaths) {
        // Check for a JAR URL repository
        try {
            @SuppressWarnings("unused")
            URL url = new URL(repository);
            repositories.add(new Repository(repository, RepositoryType.URL));
            continue;
        } catch (MalformedURLException e) {
            // Ignore
        }

        // Local repository
        if (repository.endsWith("*.jar")) {
            repository = repository.substring
                (0, repository.length() - "*.jar".length());
            repositories.add(new Repository(repository, RepositoryType.GLOB));
        } else if (repository.endsWith(".jar")) {
            repositories.add(new Repository(repository, RepositoryType.JAR));
        } else {
            repositories.add(new Repository(repository, RepositoryType.DIR));
        }
    }

    return ClassLoaderFactory.createClassLoader(repositories, parent);
}

方法的逻辑也比较简单就是从 catalina.property文件里找 common.loader, shared.loader, server.loader 对应的值，然后构造成Repository 列表，再将Repository 列表传入ClassLoaderFactory.createClassLoader 方法，ClassLoaderFactory.createClassLoader 返回的是 URLClassLoader，而Repository 列表就是这个URLClassLoader 可以加在的类的路径。 在catalina.property文件里

common.loader="${catalina.base}/lib","${catalina.base}/lib/*.jar","${catalina.home}/lib","${catalina.home}/lib/*.jar"
server.loader=
shared.loader=

其中 shared.loader, server.loader 是没有值的，createClassLoader 方法里如果没有值的话，就返回传入的 parent ClassLoader，也就是说，commonLoader,catalinaLoader,sharedLoader 其实是一个对象。在Tomcat之前的版本里，这三个是不同的URLClassLoader对象。

Class<?> startupClass = catalinaLoader.loadClass("org.apache.catalina.startup.Catalina");
        Object startupInstance = startupClass.getConstructor().newInstance();

初始化完三个ClassLoader对象后，init() 方法就使用 catalinaClassLoader 加载了org.apache.catalina.startup.Catalina 类，并创建了一个对象，然后通过反射调用这个对象的 setParentClassLoader 方法，传入的参数是 sharedClassLoader。最后吧这个 Catania 对象复制给 catalinaDaemon 属性。

深入理解

可以复习下类加载机制的基础：解密类加载机制：深入理解JVM如何加载你的代码

什么是类加载机制

Java是一门面向对象的语言，而对象又必然依托于类。类要运行，必须首先被加载到内存。我们可以简单地把类分为几类：

• Java自带的核心类
• Java支持的可扩展类
• 我们自己编写的类
• 为什么要设计多个类加载器？

如果所有的类都使用一个类加载器来加载，会出现什么问题呢？

假如我们自己编写一个类java.util.Object，它的实现可能有一定的危险性或者隐藏的bug。而我们知道Java自带的核心类里面也有java.util.Object，如果JVM启动的时候先行加载的是我们自己编写的java.util.Object，那么就有可能出现安全问题！

所以，Sun（后被Oracle收购）采用了另外一种方式来保证最基本的、也是最核心的功能不会被破坏。你猜的没错，那就是双亲委派模式！

• 什么是双亲委派模型？

双亲委派模型解决了类错乱加载的问题，也设计得非常精妙。

双亲委派模式对类加载器定义了层级，每个类加载器都有一个父类加载器。在一个类需要加载的时候，首先委派给父类加载器来加载，而父类加载器又委派给祖父类加载器来加载，以此类推。如果父类及上面的类加载器都加载不了，那么由当前类加载器来加载，并将被加载的类缓存起来。

所以上述类是这么加载的

• Java自带的核心类 -- 由启动类加载器加载
• Java支持的可扩展类 -- 由扩展类加载器加载
• 我们自己编写的类 -- 默认由应用程序类加载器或其子类加载

但它也不是万能的，在有些场景也会遇到它解决不了的问题，比如如下场景。

双亲委派模型问题是如何解决的？

在Java核心类里面有SPI（Service Provider Interface），它由Sun编写规范，第三方来负责实现。SPI需要用到第三方实现类。如果使用双亲委派模型，那么第三方实现类也需要放在Java核心类里面才可以，不然的话第三方实现类将不能被加载使用。但是这显然是不合理的！怎么办呢？

ContextClassLoader（上下文类加载器）就来解围了。

在java.lang.Thread里面有两个方法，get/set上下文类加载器

public void setContextClassLoader(ClassLoader cl)
public ClassLoader getContextClassLoader()

我们可以通过在SPI类里面调用getContextClassLoader来获取第三方实现类的类加载器。由第三方实现类通过调用setContextClassLoader来传入自己实现的类加载器, 这样就变相地解决了双亲委派模式遇到的问题。

为什么Tomcat的类加载器也不是双亲委派模型

我们知道，Java默认的类加载机制是通过双亲委派模型来实现的，而Tomcat实现的方式又和双亲委派模型有所区别。

原因在于一个Tomcat容器允许同时运行多个Web程序，每个Web程序依赖的类又必须是相互隔离的。因此，如果Tomcat使用双亲委派模式来加载类的话，将导致Web程序依赖的类变为共享的。

举个例子，假如我们有两个Web程序，一个依赖A库的1.0版本，另一个依赖A库的2.0版本，他们都使用了类xxx.xx.Clazz，其实现的逻辑因类库版本的不同而结构完全不同。那么这两个Web程序的其中一个必然因为加载的Clazz不是所使用的Clazz而出现问题！而这对于开发来说是非常致命的！

Tomcat类加载机制是怎么样的呢

既然Tomcat的类加载机器不同于双亲委派模式，那么它又是一种怎样的模式呢？

我们在这里一定要看下官网提供的类加载的文档

结合经典的类加载机制，我们完整的看下Tomcat类加载图

我们在这张图中看到很多类加载器，除了Jdk自带的类加载器，我们尤其关心Tomcat自身持有的类加载器。仔细一点我们很容易发现：Catalina类加载器和Shared类加载器，他们并不是父子关系，而是兄弟关系。为啥这样设计，我们得分析一下每个类加载器的用途，才能知晓。

• Common类加载器，负责加载Tomcat和Web应用都复用的类

  • Catalina类加载器，负责加载Tomcat专用的类，而这些被加载的类在Web应用中将不可见

  • Shared类加载器，负责加载Tomcat下所有的Web应用程序都复用的类，而这些被加载的类在Tomcat中将不可见

    • WebApp类加载器，负责加载具体的某个Web应用程序所使用到的类，而这些被加载的类在Tomcat和其他的Web应用程序都将不可见
    • Jsp类加载器，每个jsp页面一个类加载器，不同的jsp页面有不同的类加载器，方便实现jsp页面的热插拔

同样的，我们可以看到通过ContextClassLoader（上下文类加载器）的setContextClassLoader来传入自己实现的类加载器

public void init() throws Exception {

  initClassLoaders();

  // 看这里
  Thread.currentThread().setContextClassLoader(catalinaLoader);

  SecurityClassLoad.securityClassLoad(catalinaLoader);
...

WebApp类加载器

到这儿，我们隐隐感觉到少分析了点什么！没错，就是WebApp类加载器。整个启动过程分析下来，我们仍然没有看到这个类加载器。它又是在哪儿出现的呢？

我们知道WebApp类加载器是Web应用私有的，而每个Web应用其实算是一个Context，那么我们通过Context的实现类应该可以发现。在Tomcat中，Context的默认实现为StandardContext，我们看看这个类的startInternal()方法，在这儿我们发现了我们感兴趣的WebApp类加载器。

protected synchronized void startInternal() throws LifecycleException {
    if (getLoader() == null) {
        WebappLoader webappLoader = new WebappLoader(getParentClassLoader());
        webappLoader.setDelegate(getDelegate());
        setLoader(webappLoader);
    }
}

入口代码非常简单，就是webappLoader不存在的时候创建一个，并调用setLoader方法。我们接着分析setLoader

public void setLoader(Loader loader) {

    Lock writeLock = loaderLock.writeLock();
    writeLock.lock();
    Loader oldLoader = null;
    try {
        // Change components if necessary
        oldLoader = this.loader;
        if (oldLoader == loader)
            return;
        this.loader = loader;

        // Stop the old component if necessary
        if (getState().isAvailable() && (oldLoader != null) &&
            (oldLoader instanceof Lifecycle)) {
            try {
                ((Lifecycle) oldLoader).stop();
            } catch (LifecycleException e) {
                log.error("StandardContext.setLoader: stop: ", e);
            }
        }

        // Start the new component if necessary
        if (loader != null)
            loader.setContext(this);
        if (getState().isAvailable() && (loader != null) &&
            (loader instanceof Lifecycle)) {
            try {
                ((Lifecycle) loader).start();
            } catch (LifecycleException e) {
                log.error("StandardContext.setLoader: start: ", e);
            }
        }
    } finally {
        writeLock.unlock();
    }

    // Report this property change to interested listeners
    support.firePropertyChange("loader", oldLoader, loader);
}

这儿，我们感兴趣的就两行代码：

((Lifecycle) oldLoader).stop(); // 旧的加载器停止
((Lifecycle) loader).start(); // 新的加载器启动

启动过程：Catalina的加载

Catalina的引入

通过前面，我们知道了Tomcat的类加载机制和整体的组件加载流程；我们也知道通过Bootstrap初始化的catalinaClassLoader加载了Catalina，那么进而引入了一个问题就是Catalina是如何加载的呢？加载了什么呢？

• 先回顾下整个流程，和我们分析的阶段

• 看下Bootstrap中Load的过程

/**
  * 加载守护进程
  */
private void load(String[] arguments) throws Exception {

    // Call the load() method
    String methodName = "load";
    Object param[];
    Class<?> paramTypes[];
    if (arguments==null || arguments.length==0) {
        paramTypes = null;
        param = null;
    } else {
        paramTypes = new Class[1];
        paramTypes[0] = arguments.getClass();
        param = new Object[1];
        param[0] = arguments;
    }
    Method method =
        catalinaDaemon.getClass().getMethod(methodName, paramTypes); 
    if (log.isDebugEnabled()) {
        log.debug("Calling startup class " + method);
    }
    method.invoke(catalinaDaemon, param);// 本质上就是调用catalina的load方法
}

Catalina的加载

上一步，我们知道catalina load的触发，因为有参数所以是load(String[])方法。我们进而看下这个load方法做了什么？

• load(String[])本质上还是调用了load方法

/*
  * Load using arguments
  */
public void load(String args[]) {

    try {
        if (arguments(args)) { // 处理命令行的参数
            load();
        }
    } catch (Exception e) {
        e.printStackTrace(System.out);
    }
}

• load加载过程本质上是初始化Server的实例

/**
  * Start a new server instance.
  */
public void load() {

    // 如果已经加载则退出
    if (loaded) {
        return;
    }
    loaded = true;

    long t1 = System.nanoTime();

    // （已经弃用）
    initDirs();

    // Before digester - it may be needed
    initNaming();

    // 解析 server.xml
    parseServerXml(true);
    Server s = getServer();
    if (s == null) {
        return;
    }

    getServer().setCatalina(this);
    getServer().setCatalinaHome(Bootstrap.getCatalinaHomeFile());
    getServer().setCatalinaBase(Bootstrap.getCatalinaBaseFile());

    // Stream redirection
    initStreams();

    // 启动Server
    try {
        getServer().init();
    } catch (LifecycleException e) {
        if (Boolean.getBoolean("org.apache.catalina.startup.EXIT_ON_INIT_FAILURE")) {
            throw new java.lang.Error(e);
        } else {
            log.error(sm.getString("catalina.initError"), e);
        }
    }

    if(log.isInfoEnabled()) {
        log.info(sm.getString("catalina.init", Long.toString(TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - t1))));
    }
}

总体流程如下：

initDirs

已经弃用了，Tomcat10会删除这个方法。

/**
  * @deprecated unused. Will be removed in Tomcat 10 onwards.
  */
@Deprecated
protected void initDirs() {
}

initNaming

设置额外的系统变量

protected void initNaming() {
  // Setting additional variables
  if (!useNaming) {
      log.info(sm.getString("catalina.noNaming"));
      System.setProperty("catalina.useNaming", "false");
  } else {
      System.setProperty("catalina.useNaming", "true");
      String value = "org.apache.naming";
      String oldValue =
          System.getProperty(javax.naming.Context.URL_PKG_PREFIXES);
      if (oldValue != null) {
          value = value + ":" + oldValue;
      }
      System.setProperty(javax.naming.Context.URL_PKG_PREFIXES, value);
      if( log.isDebugEnabled() ) {
          log.debug("Setting naming prefix=" + value);
      }
      value = System.getProperty
          (javax.naming.Context.INITIAL_CONTEXT_FACTORY);
      if (value == null) {
          System.setProperty
              (javax.naming.Context.INITIAL_CONTEXT_FACTORY,
                "org.apache.naming.java.javaURLContextFactory");
      } else {
          log.debug("INITIAL_CONTEXT_FACTORY already set " + value );
      }
  }
}

Server.xml的解析

分三大块，下面的代码还是很清晰的:

protected void parseServerXml(boolean start) {
    // Set configuration source
    ConfigFileLoader.setSource(new CatalinaBaseConfigurationSource(Bootstrap.getCatalinaBaseFile(), getConfigFile()));
    File file = configFile();

    if (useGeneratedCode && !Digester.isGeneratedCodeLoaderSet()) {
        // Load loader
        String loaderClassName = generatedCodePackage + ".DigesterGeneratedCodeLoader";
        try {
            Digester.GeneratedCodeLoader loader =
                    (Digester.GeneratedCodeLoader) Catalina.class.getClassLoader().loadClass(loaderClassName).newInstance();
            Digester.setGeneratedCodeLoader(loader);
        } catch (Exception e) {
            if (log.isDebugEnabled()) {
                log.info(sm.getString("catalina.noLoader", loaderClassName), e);
            } else {
                log.info(sm.getString("catalina.noLoader", loaderClassName));
            }
            // No loader so don't use generated code
            useGeneratedCode = false;
        }
    }

    // 初始化server.xml的位置
    File serverXmlLocation = null;
    String xmlClassName = null;
    if (generateCode || useGeneratedCode) {
        xmlClassName = start ? generatedCodePackage + ".ServerXml" : generatedCodePackage + ".ServerXmlStop";
    }
    if (generateCode) {
        if (generatedCodeLocationParameter != null) {
            generatedCodeLocation = new File(generatedCodeLocationParameter);
            if (!generatedCodeLocation.isAbsolute()) {
                generatedCodeLocation = new File(Bootstrap.getCatalinaHomeFile(), generatedCodeLocationParameter);
            }
        } else {
            generatedCodeLocation = new File(Bootstrap.getCatalinaHomeFile(), "work");
        }
        serverXmlLocation = new File(generatedCodeLocation, generatedCodePackage);
        if (!serverXmlLocation.isDirectory() && !serverXmlLocation.mkdirs()) {
            log.warn(sm.getString("catalina.generatedCodeLocationError", generatedCodeLocation.getAbsolutePath()));
            // Disable code generation
            generateCode = false;
        }
    }

    // 用 SAXParser 来解析 xml，解析完了之后，xml 里定义的各种标签就有对应的实现类对象了
    ServerXml serverXml = null;
    if (useGeneratedCode) {
        serverXml = (ServerXml) Digester.loadGeneratedClass(xmlClassName);
    }

    if (serverXml != null) {
        serverXml.load(this);
    } else {
        try (ConfigurationSource.Resource resource = ConfigFileLoader.getSource().getServerXml()) {
            // Create and execute our Digester
            Digester digester = start ? createStartDigester() : createStopDigester();
            InputStream inputStream = resource.getInputStream();
            InputSource inputSource = new InputSource(resource.getURI().toURL().toString());
            inputSource.setByteStream(inputStream);
            digester.push(this);
            if (generateCode) {
                digester.startGeneratingCode();
                generateClassHeader(digester, start);
            }
            digester.parse(inputSource);
            if (generateCode) {
                generateClassFooter(digester);
                try (FileWriter writer = new FileWriter(new File(serverXmlLocation,
                        start ? "ServerXml.java" : "ServerXmlStop.java"))) {
                    writer.write(digester.getGeneratedCode().toString());
                }
                digester.endGeneratingCode();
                Digester.addGeneratedClass(xmlClassName);
            }
        } catch (Exception e) {
            log.warn(sm.getString("catalina.configFail", file.getAbsolutePath()), e);
            if (file.exists() && !file.canRead()) {
                log.warn(sm.getString("catalina.incorrectPermissions"));
            }
        }
    }
}

initStreams

替换掉System.out, System.err为自定义的PrintStream

protected void initStreams() {
    // Replace System.out and System.err with a custom PrintStream
    System.setOut(new SystemLogHandler(System.out));
    System.setErr(new SystemLogHandler(System.err));
}

Catalina 的启动

在 load 方法之后，Tomcat 就初始化了一系列的组件，接着就可以调用 start 方法进行启动了。

/**
  * Start a new server instance.
  */
public void start() {

    if (getServer() == null) {
        load();
    }

    if (getServer() == null) {
        log.fatal(sm.getString("catalina.noServer"));
        return;
    }

    long t1 = System.nanoTime();

    // Start the new server
    try {
        getServer().start();
    } catch (LifecycleException e) {
        log.fatal(sm.getString("catalina.serverStartFail"), e);
        try {
            getServer().destroy();
        } catch (LifecycleException e1) {
            log.debug("destroy() failed for failed Server ", e1);
        }
        return;
    }

    long t2 = System.nanoTime();
    if(log.isInfoEnabled()) {
        log.info(sm.getString("catalina.startup", Long.valueOf((t2 - t1) / 1000000)));
    }

    // Register shutdown hook
    if (useShutdownHook) {
        if (shutdownHook == null) {
            shutdownHook = new CatalinaShutdownHook();
        }
        Runtime.getRuntime().addShutdownHook(shutdownHook);

        // If JULI is being used, disable JULI's shutdown hook since
        // shutdown hooks run in parallel and log messages may be lost
        // if JULI's hook completes before the CatalinaShutdownHook()
        LogManager logManager = LogManager.getLogManager();
        if (logManager instanceof ClassLoaderLogManager) {
            ((ClassLoaderLogManager) logManager).setUseShutdownHook(
                    false);
        }
    }

    if (await) {
        await();
        stop();
    }
}

上面这段代码，逻辑非常简单，首先确定 getServer() 方法不为 null ，也就是确定 server 属性不为null，而 server 属性是在 load 方法就初始化了。

整段代码的核心就是 try-catch 里的 getServer().start() 方法了，也就是调用 Server 对象的 start() 方法来启动 Tomcat。本篇文章就先不对 Server 的 start() 方法进行解析了，下篇文章会单独讲。

Catalina 的关闭

调用完 Server#start 方法之后，注册了一个ShutDownHook，也就是 CatalinaShutdownHook 对象，

/**
  * Shutdown hook which will perform a clean shutdown of Catalina if needed.
  */
protected class CatalinaShutdownHook extends Thread {

  @Override
  public void run() {
      try {
          if (getServer() != null) {
              Catalina.this.stop();
          }
      } catch (Throwable ex) {
          ExceptionUtils.handleThrowable(ex);
          log.error(sm.getString("catalina.shutdownHookFail"), ex);
      } finally {
          // If JULI is used, shut JULI down *after* the server shuts down
          // so log messages aren't lost
          LogManager logManager = LogManager.getLogManager();
          if (logManager instanceof ClassLoaderLogManager) {
              ((ClassLoaderLogManager) logManager).shutdown();
          }
      }
  }
}

CatalinaShutdownHook 的逻辑也简单，就是调用 Catalina 对象的 stop 方法来停止 tomcat。

最后就进入 if 语句了，await 是在 Bootstrap 里调用的时候设置为 true 的，也就是本文开头的时候提到的三个方法中的一个。await 方法的作用是停住主线程，等待用户输入shutdown 命令之后，停止等待，之后 main 线程就调用 stop 方法来停止Tomcat。

/**
  * Stop an existing server instance.
  */
public void stop() {

    try {
        // Remove the ShutdownHook first so that server.stop()
        // doesn't get invoked twice
        if (useShutdownHook) {
            Runtime.getRuntime().removeShutdownHook(shutdownHook);

            // If JULI is being used, re-enable JULI's shutdown to ensure
            // log messages are not lost
            LogManager logManager = LogManager.getLogManager();
            if (logManager instanceof ClassLoaderLogManager) {
                ((ClassLoaderLogManager) logManager).setUseShutdownHook(
                        true);
            }
        }
    } catch (Throwable t) {
        ExceptionUtils.handleThrowable(t);
        // This will fail on JDK 1.2. Ignoring, as Tomcat can run
        // fine without the shutdown hook.
    }

    // Shut down the server
    try {
        Server s = getServer();
        LifecycleState state = s.getState();
        if (LifecycleState.STOPPING_PREP.compareTo(state) <= 0
                && LifecycleState.DESTROYED.compareTo(state) >= 0) {
            // Nothing to do. stop() was already called
        } else {
            s.stop();
            s.destroy();
        }
    } catch (LifecycleException e) {
        log.error(sm.getString("catalina.stopError"), e);
    }

}

Catalina 的 stop 方法主要逻辑是调用 Server 对象的 stop 方法。

聊聊关闭钩子

上面我们看到CatalinaShutdownHook, 这里有必要谈谈JVM的关闭钩子。

if (shutdownHook == null) {
    shutdownHook = new CatalinaShutdownHook();
}
Runtime.getRuntime().addShutdownHook(shutdownHook);

关闭钩子是指通过Runtime.addShutdownHook注册的但尚未开始的线程。这些钩子可以用于实现服务或者应用程序的清理工作，例如删除临时文件，或者清除无法由操作系统自动清除的资源。

JVM既可以正常关闭，也可以强行关闭。正常关闭的触发方式有多种，包括：当最后一个“正常（非守护）”线程结束时，或者当调用了System.exit时，或者通过其他特定于平台的方法关闭时（例如发送了SIGINT信号或者键入Ctrl-C）。

在正常关闭中，JVM首先调用所有已注册的关闭钩子。JVM并不能保证关闭钩子的调用顺序。在关闭应用程序线程时，如果有（守护或者非守护）线程仍然在执行，那么这些线程接下来将与关闭进程并发执行。当所有的关闭钩子都执行结束时，如果runFinalizersOnExit为true【通过Runtime.runFinalizersOnExit(true)设置】，那么JVM将运行这些Finalizer（对象重写的finalize方法），然后再停止。JVM不会停止或中断任何在关闭时仍然运行的应用程序线程。当JVM最终结束时，这些线程将被强行结束。如果关闭钩子或者Finalizer没有执行完成，那么正常关闭进程“挂起”并且JVM必须被强行关闭。当JVM被强行关闭时，只是关闭JVM，并不会运行关闭钩子（举个例子，类似于电源都直接拔了，还怎么做其它动作呢？）。

下面是一个简单的示例：

public class T {
    @SuppressWarnings("deprecation")
    public static void main(String[] args) throws Exception {
        //启用退出JVM时执行Finalizer
        Runtime.runFinalizersOnExit(true);
        MyHook hook1 = new MyHook("Hook1");
        MyHook hook2 = new MyHook("Hook2");
        MyHook hook3 = new MyHook("Hook3");
        
        //注册关闭钩子
        Runtime.getRuntime().addShutdownHook(hook1);
        Runtime.getRuntime().addShutdownHook(hook2);
        Runtime.getRuntime().addShutdownHook(hook3);
        
        //移除关闭钩子
        Runtime.getRuntime().removeShutdownHook(hook3);
        
        //Main线程将在执行这句之后退出
        System.out.println("Main Thread Ends.");
    }
}

class MyHook extends Thread {
    private String name;
    public MyHook (String name) {
        this.name = name;
        setName(name);
    }
    public void run() {
        System.out.println(name + " Ends.");
    }
    //重写Finalizer，将在关闭钩子后调用
    protected void finalize() throws Throwable {
        System.out.println(name + " Finalize.");
    }
}

和（可能的）执行结果（因为JVM不保证关闭钩子的调用顺序，因此结果中的第二、三行可能出现相反的顺序）：

Main Thread Ends.
Hook2 Ends.
Hook1 Ends.
Hook3 Finalize.
Hook2 Finalize.
Hook1 Finalize.

可以看到，main函数执行完成，首先输出的是Main Thread Ends，接下来执行关闭钩子，输出Hook2 Ends和Hook1 Ends。这两行也可以证实：JVM确实不是以注册的顺序来调用关闭钩子的。而由于hook3在调用了addShutdownHook后，接着对其调用了removeShutdownHook将其移除，于是hook3在JVM退出时没有执行，因此没有输出Hook3 Ends。

另外，由于MyHook类实现了finalize方法，而main函数中第一行又通过Runtime.runFinalizersOnExit(true)打开了退出JVM时执行Finalizer的开关，于是3个hook对象的finalize方法被调用，输出了3行Finalize。

注意，多次调用addShutdownHook来注册同一个关闭钩子将会抛出IllegalArgumentException:

Exception in thread "main" java.lang.IllegalArgumentException: Hook previously registered
    at java.lang.ApplicationShutdownHooks.add(ApplicationShutdownHooks.java:72)
    at java.lang.Runtime.addShutdownHook(Runtime.java:211)
    at T.main(T.java:12)

另外，从JavaDoc中得知：一旦JVM关闭流程开始，就只能通过调用halt方法来停止该流程，也不可能再注册或移除关闭钩子了，这些操作将导致抛出IllegalStateException。

如果在关闭钩子中关闭应用程序的公共的组件，如日志服务，或者数据库连接等，像下面这样：

Runtime.getRuntime().addShutdownHook(new Thread() {
    public void run() {
        try { 
            LogService.this.stop();
        } catch (InterruptedException ignored){
            //ignored
        }
    }
});

由于关闭钩子将并发执行，因此在关闭日志时可能导致其他需要日志服务的关闭钩子产生问题。为了避免这种情况，可以使关闭钩子不依赖那些可能被应用程序或其他关闭钩子关闭的服务。实现这种功能的一种方式是对所有服务使用同一个关闭钩子（而不是每个服务使用一个不同的关闭钩子），并且在该关闭钩子中执行一系列的关闭操作。这确保了关闭操作在单个线程中串行执行，从而避免了在关闭操作之前出现竞态条件或死锁等问题。

使用场景

通过Hook实现临时文件清理

public class test {

  public static void main(String[] args) {
      try {
          Thread.sleep(20000);
      } catch (InterruptedException e) {
          e.printStackTrace();
      }

      Runtime.getRuntime().addShutdownHook(new Thread(new Runnable() {
          public void run() {
              System.out.println("auto clean temporary file");
          }
      }));
  }
}

小结

Catalina 类承接了 Bootstrap 类的 load 和 start 方法，然后根据配置初始化了 Tomcat 的组件，并调用了 Server 类的 init 和 start 方法来启动 Tomcat。

一个中国AI，让硅谷最热独角兽公开道歉

它用美国顶尖实验室1%的资源，做出了让马斯克点赞、让Cursor跪地认错的模型。

你有没有想过——

当你打开 Cursor 写代码，当你在 Perplexity 搜索，当你用某个"美国产品"感叹"AI真厉害"的时候……

底层跑的，可能是一个北京团队写的模型。

这个团队叫月之暗面，他们的产品叫 Kimi。

而就在2026年开年，他们做了一件让整个全球AI圈都没想到的事。

01 | 那个让Cursor道歉的故事

3月下旬，AI编程圈发生了一件"罗生门"级别的事件。

估值500亿美元的编程工具 Cursor，推出了新一代旗舰模型 Composer 2，主打"长周期智能体编程"，宣传得有声有色。

然后——有人扒出来了。

一个网友操作了一下 base URL，发现里面藏着这样一串字符：

accounts/anysphere/models/kimi-k2p5-rl-0317-s515-fast

翻译一下：Cursor花了大价钱包装的旗舰模型，底座是 Kimi K2.5。

舆论炸了。马斯克转发评论。Cursor创始人不得不公开道歉。

月之暗面随后确认：双方通过 Fireworks AI 平台存在正式授权合作。

一个来自北京的开源模型，成了硅谷最热编程工具不敢说出口的秘密。

这一天，Kimi 赢得了任何广告都买不来的品牌溢价。

02 | K2.5到底强在哪里？

Kimi K2.5 于2026年1月27日正式发布开源。

发布20天内，Kimi的累计收入超过了2025年全年总收入。

1月订阅订单环比增长 8280%，在 Stripe 全球榜单上从百名开外直接冲进前十。

但数字背后，真正的故事是技术。

🔹 它重新定义了"Agent"

过去的AI，是你问一句、它答一句。
K2.5 不一样——它是一个指挥官。

它可以同时调度最多 100个子Agent分身，并行处理 1500个步骤，所有角色分配、任务拆解、最终验收，全部由主Agent自动完成。

这不是对话，这是自动化作战。

🔹 它解决了长文本的速度死穴

处理100万字的文档，传统Transformer的计算量会呈平方级增长——越长越慢，慢到用不起。

Kimi 团队自研了 Kimi Linear，一种混合线性注意力架构，打破了"所有层必须全注意力"的行业惯例。

结果：在128K到100万字的超长上下文中，解码速度提升5到6倍。

🔹 它用"注意力残差"重写了Transformer的记忆方式

过去模型的每一层，都无差别地叠加前面所有层的信息——重要的和不重要的一视同仁，层数越多，关键信息越被稀释。

Kimi 提出的 Attention Residuals（注意力残差），让模型像人一样"有选择地回忆"——每层根据当前需求，主动调取最值得参考的信息。

48B参数模型训练效率因此提升 1.25倍。

这篇论文发布后，马斯克公开表示"令人印象深刻"，OpenAI前研究副总裁 Jerry Tworek 评价：这标志着"深度学习2.0"时代的到来。

顺带一提，这篇论文的第一作者——是一个来自深圳的17岁在读高中生。

03 | 一家公司，做了一个反常识的选择

2025年初，DeepSeek横空出世，以极低成本开源，让整个中国AI创业圈陷入存在危机。

外界的声音是：模型公司还有独立存在的价值吗？

月之暗面创始人杨植麟的回答，不是一句话，而是一个选择——

继续死磕基础模型，坚持开源，放弃短期流量，押注技术长期主义。

他们是全球第一个在超大规模训练中跑通 Muon优化器 的公司，解决了Adam优化器十年来的扩展瓶颈。

他们把 MuonClip、Kimi Linear、Attention Residuals 全部开源，贡献给全球开发者社区。

2026年3月，英伟达GTC大会，杨植麟成为唯一受邀现场演讲的中国独立大模型公司创始人，用40分钟向全球系统披露Kimi的技术路线图。

从北京出发，站上硅谷最大的舞台。

04 | 下一步，他们盯着什么？

4月，Kimi K2.6 Code Preview 已进入内测，专攻代码生成与Agent能力，预计5月正式发布。

与此同时，下一代旗舰 Kimi K3 已在研发中——据传参数规模将达到3到4万亿，直接对标美国头部模型。

月之暗面内部信透露的目标只有一个字：

超越 Anthropic。

写在最后

有人问，中国AI和美国AI的差距到底有多大？

K2.5 给出了一个答案：

当你以为在用美国产品的时候，你可能已经在用中国技术了。

这不是一个追赶的故事，这是一个已经发生的故事。

而月之暗面，才刚开始。

如果你觉得这篇文章有价值，欢迎转发给关注AI的朋友。

关注我，持续追踪全球AI最新动态。

本文由mdnice多平台发布