Linux线程间消息队列实战：从互斥锁到SPSC无锁队列与批量优化

写这个系列到今天，算上这一篇已经有四个实用组件落地了。写第一篇的时候，我的想法很简单：把日常开发里反复用到的东西攒成一个可以直接抄的代码集，避免每次重新造轮子。到了线程间消息队列这个主题，我一开始以为写个“互斥锁+条件变量+消息链表”的经典模型就算完事，结果写成第二篇才发现，能跑的队列和真正敢放上生产环境的队列，中间差的不是一点点。

这篇就是“Linux实用功能代码集（4）——线程间消息队列（2）”的完整内容。重点不是再贴一遍基础版，而是在第一篇的基础模型之上，把设计思路、性能瓶颈、无锁优化、批量收发的改造过程讲透。适合正在写Linux下C/C++服务端和嵌入式程序的朋友，尤其是那些线程多、消息频繁、对延迟和CPU占用有要求的场景。

先说结论：消息队列在系统里本质上就是干三件事——解耦、异步、削峰。但具体怎么实现，是拿锁硬扛，还是用无锁环形队列，还是锁批量版，完全取决于你的生产者和消费者模型是什么样。这篇会给你一套可落地的选择方法，以及两套能直接抄的代码。

1. 为什么上一篇的队列还不够“实用”

1.1 回顾基础模型的三处硬伤

上一篇给的初版代码，我这里先用文字描述一下：一个 pthread_mutex_t 保护消息链表，一个 pthread_cond_t 负责唤醒消费者，消费者拿到一条消息就处理一条。功能上没有任何问题，消息不会丢，线程安全也没毛病，但放到实际项目里跑一段时间，问题就出来了。

第一处硬伤是锁竞争。当生产者和消费者都在高频访问队列时，这个锁就是全场的瓶颈。生产者要拿锁塞消息，消费者要拿锁取消息，两边互相等待，CPU很大一部分时间不是在处理业务数据，而是在自旋抢锁。我见过最夸张的情况，某个采集程序在消息量起来后，光锁的等待时间就占了总耗时的四成。

第二处硬伤是唤醒风暴。基础版里的做法是每生产一条消息，就马上 pthread_cond_signal 一次。如果生产者每秒塞几千条消息，消费者线程就要被唤醒几千次，每次唤醒都伴随着一次线程调度和上下文切换。消息量越大，这个开销越疼。

第三处硬伤藏得比较深，是内存分配。链表节点的 malloc/free，消息对象本身的 new/delete，在高频收发下会频繁发生。系统压力一大，内存碎片就会冒出来，缓存命中率也跟着下降。这个问题不容易在功能测试里暴露，但跑长时间压测时，性能曲线会越来越难看。

1.2 生产环境对“队列”的真实要求

我说“实用”，不是口头说说，得把它拆成具体指标。站在开发者的角度看，一个真正能投入生产环境的线程间消息队列，至少要满足三方面要求：

功能上，要支持阻塞和非阻塞收发，要支持超时等待，要能在多生产者多消费者场景下正常工作，还要有明确的关闭接口，让线程能安全退出而不是永远卡在等待里。

性能上，要尽量降低锁竞争和上下文切换，要有良好的缓存局部性，不能让数据在两个线程之间传递时频繁穿过内存而消耗带宽。

工程上，队列满时要可控，不能无限堆积内存，要能方便地做压力测试，要保证消息恰好被处理一次，既不能丢，也不能重复处理。

后面我所有代码和设计选型，都是拿这三条标准来检查的。

2. 锁、无锁还是混合方案：先把场景想清楚

2.1 无锁队列不是银弹

很多人一听到“无锁队列”就两眼放光，觉得只要锁一去掉，性能就起飞。实际上无锁方案的应用范围远没有想象的宽，用不好还会踩坑。

真正适合无锁队列的，是单生产者单消费者（SPSC）模型。比如网卡收包线程往协议栈塞包，传感器采集线程往处理线程传数据，音频采集线程往编码线程送PCM数据。这种场景下数据流向单一，队列两端都只有一个线程碰，不需要CAS原子比较交换，也就没有ABA问题，实现起来简单又高效。

一旦变成多生产者多消费者，无锁的复杂度会立刻上来。你要用CAS去维护同一个尾指针，要处理ABA，要考虑多个消费者同时取数据时谁拿走了什么，要小心内存序导致的数据不可见。我在一个项目里试过用无锁队列实现多写入，代码量翻了一倍，性能相比“锁+批量处理”并没有质变，反而排查问题的时候难度激增。

打个比方，无锁队列像一条只走一辆车的单车道，单向通行的时候又稳又快。可一旦路口来了好几个方向的车流，你反而需要红绿灯来维持秩序。这个红绿灯就是锁。多生产者多消费者场景下，老老实实上锁，把精力花在减少持锁时间上，才是性价比最高的路子。

2.2 我的选择：SPSC无锁快速通道 + 锁队列批量兜底

考虑到工程实用，我最后确定的是混合方案：

核心队列是一个基于环形缓冲区的 SPSC 无锁队列，负责两个线程之间的高频数据传递。它只提供 try_push 和 try_pop 的非阻塞接口，也就是队列满或空时立刻返回。这个通道不承担让生产者等待的职责，也不承担唤醒消费者的职责。

多生产者多消费者场景则单独上一把锁，但不在锁里逐条收发消息，而是实现了批量的 pop_all 接口，让消费者一次性把队列里积压的消息全部取出来，统一处理。这样把“取一条处理一条”改成“一把抓走一批”，锁的获取次数和条件变量通知次数都大幅下降。

这个方案的好处很明显：消费侧和消息真正的传输路径是无锁的，延迟很低；多生产者的竞争被转移到了一把短临界区的锁上；队列满时行为可预测。后面三个小节，我分别把这两个核心组件的实现讲清楚。

3. SPSC环形无锁队列：Linux下的落地实现

3.1 数据结构怎么摆，性能差距很大

SPSC无锁队列的实现基础是环形缓冲区。我不多讲空泛的概念，直接给代码开刀：

c复制#define RING_CAPACITY 4096

typedef struct {
    _Alignas(64) atomic_size_t tail;
    _Alignas(64) atomic_size_t head;
    void *slots[RING_CAPACITY];
} spsc_ring;

这里有几个关键点，每一个都影响性能。

首先，容量必须是2的幂。这样当我们需要计算数组下标时，可以用 t & (RING_CAPACITY - 1) 代替 t % RING_CAPACITY。取模运算在CPU里要走除法指令，成本比位与高出很多倍。这条规则同样适用于其他环形缓冲区的设计，算是一个通用经验。

其次，tail 和 head 这两个原子变量必须各自独占一个缓存行。CPU缓存行在x86_64平台上一般是64字节，_Alignas(64) 就是强制把变量对齐到64字节边界。如果 head 和 tail 落在同一个缓存行里，生产者每次更新 tail 都会使包含 head 的那个缓存行失效，消费者要读 head 时就得从内存重新加载，性能会断崖式下跌。这个坑太隐蔽了，不用 perf 观察缓存缺失事件都发现不了。

最后，代码里我把 tail 放在 head 前面。这也是有意为之的，让两个变量隔开，进一步避免它们在缓存系统中互相干扰。

3.2 push/pop的核心实现

核心代码很短，短到很多人第一眼会觉得“就这么点”？是的，SPSC无锁队列就是可以这么简单：

c复制int spsc_push(spsc_ring *r, void *msg)
{
    size_t t = atomic_load_explicit(&r->tail, memory_order_relaxed);
    size_t h = atomic_load_explicit(&r->head, memory_order_acquire);

    if (t - h >= RING_CAPACITY)
        return -1;

    r->slots[t & (RING_CAPACITY - 1)] = msg;
    atomic_store_explicit(&r->tail, t + 1, memory_order_release);
    return 0;
}

void *spsc_pop(spsc_ring *r)
{
    size_t h = atomic_load_explicit(&r->head, memory_order_relaxed);
    size_t t = atomic_load_explicit(&r->tail, memory_order_acquire);

    if (h == t)
        return NULL;

    void *msg = r->slots[h & (RING_CAPACITY - 1)];
    atomic_store_explicit(&r->head, h + 1, memory_order_release);
    return msg;
}

我解释一下里面的内存序选择，因为这是无锁编程最容易出错的地方。

消费者读取 tail 时用 memory_order_acquire，目的是保证：当它看到生产者更新的 tail 之后，生产者在此之前写入 slots 的数据一定已经可见。这就像快递员把包裹放进快递柜之后，才发出一声“我放好了”的提示，收件人听到提示去取件时，包裹肯定已经在柜子里了。

生产者读取 head 时也用 memory_order_acquire，作用是对称的：保证消费者已经完成对某个槽位的读取之后，生产者才可以去覆盖这个槽位。

tail 和 head 的写入都用 memory_order_release，含义就是发布。这种 release/acquire 配对，构成了无锁队列的核心内存屏障，足以保证在只有一对生产者消费者的情况下，数据不会出现“取了空壳”或者“覆盖了还没读走的数据”这种问题。

需要注意，这个实现里我用 t - h 来判断满和空，不再因为需要区分满空而牺牲一个槽位。因为这里只有一个生产者和一个消费者，索引不会被并发修改，所以可以直接让队列填满 RING_CAPACITY 个消息。这个细节和网上很多教科书版本不同，但它是对的，而且多出来的容量意味着更好的缓存命中率。

3.3 无锁队列如何配合“等待唤醒”

无锁队列本身只提供非阻塞的 try 接口，但实际业务里消费者不可能一直死循环轮询，那会把一个CPU核心跑到满。最好的办法是配合一个事件通知机制，让消费者在队列空的时候睡过去，在有消息时被唤醒。

Linux下最经典的组合是信号量：

c复制#include <semaphore.h>

static sem_t g_sem;
static spsc_ring g_ring;

void producer_thread(void)
{
    while (1) {
        void *msg = produce_data();
        if (spsc_push(&g_ring, msg) == 0)
            sem_post(&g_sem);
        else
            handle_queue_full(msg);
    }
}

void consumer_thread(void)
{
    while (1) {
        sem_wait(&g_sem);
        void *msg = spsc_pop(&g_ring);
        if (msg)
            process_data(msg);
    }
}

这个模式里，信号量的计数恰好对应队列里待处理的消息数。每次生产成功就 sem_post 一次，消费者先 sem_wait 再取消息，逻辑是严格配对的，不会出现信号量计数和实际消息数量偏差的情况。

如果你在写的是事件驱动型服务，比如已经用 epoll 管理了一批 fd，那可以用 eventfd 替代信号量。eventfd 的好处是可以直接丢进 epoll 集合里，让队列的消息到达事件和网络事件走同一条唤醒链路。代码差别不大，把 sem_post 换成 uint64_t one = 1; write(fd, &one, 8)，消费者那边在 epoll 事件里 read(fd) 计数值后，再走 spsc_pop 即可。

有一点必须说清楚：这种模式下，如果队列满了，我不会强行让生产者阻塞，因为SPSC队列需要保证“永远只有一个生产者”才成立。队列满在业务上通常意味着消费端跟不上了，最合理的做法是进 handle_queue_full，根据业务决定是丢弃旧消息、覆盖旧消息，还是短暂让生产者降速。这个问题必须在设计时定好，而不是等压测出了问题再补。

4. MPMC场景：锁队列的批量收发改造

4.1 多生产者多消费者真正难在哪

多生产者和多消费者的场景，就别总惦记无锁了。要处理的问题非常多：多个生产者同时往队尾加消息，必须保证尾部索引的原子递增；多个消费者同时从队头取消息，必须保证同一条消息不会发给两个人；还需要处理退出时多个等待线程的唤醒问题。

这些问题并非不能全部用CAS解决，但代码会变得极难证明正确。我见过一个项目用无锁方式实现多生产者队列，线上偶尔出现消息“消失”的诡异现象，查了两周，最后发现是CAS循环里一个边界条件在处理线程抢占切换时出现了ABA问题的变种。为了几微秒的性能提升搭进去两周排查时间，这笔账不划算。

多生产者多消费者场景下，一把互斥锁依然是最可靠的同步原语。关键在于控制持锁时间，别在锁里面做耗时操作，别一有消息就马上 notify。

4.2 批量取出接口：把锁竞争降到最低

我的做法是把互斥锁和条件变量包在一个紧凑结构里，核心接口只有 push、pop_all、close 三个：

c复制typedef struct {
    pthread_mutex_t lock;
    pthread_cond_t  not_empty;
    msg_node_t     *head;
    msg_node_t     *tail;
    int             closed;
} mpmc_queue_t;

int mpmc_push(mpmc_queue_t *q, void *msg)
{
    pthread_mutex_lock(&q->lock);
    if (q->closed) {
        pthread_mutex_unlock(&q->lock);
        return -1;
    }
    msg_node_t *node = malloc(sizeof(*node));
    node->data = msg;
    node->next = NULL;
    if (q->tail)
        q->tail->next = node;
    else
        q->head = node;
    q->tail = node;
    pthread_mutex_unlock(&q->lock);

    pthread_cond_signal(&q->not_empty);
    return 0;
}

size_t mpmc_pop_all(mpmc_queue_t *q, void **out, size_t max)
{
    pthread_mutex_lock(&q->lock);
    while (!q->head && !q->closed)
        pthread_cond_wait(&q->not_empty, &q->lock);

    if (!q->head && q->closed) {
        pthread_mutex_unlock(&q->lock);
        return 0;
    }

    size_t n = 0;
    msg_node_t *cur = q->head;
    while (cur && n < max) {
        out[n++] = cur->data;
        cur = cur->next;
    }
    q->head = cur;
    if (!cur)
        q->tail = NULL;

    pthread_mutex_unlock(&q->lock);
    return n;
}

void mpmc_close(mpmc_queue_t *q)
{
    pthread_mutex_lock(&q->lock);
    q->closed = 1;
    pthread_mutex_unlock(&q->lock);
    pthread_cond_broadcast(&q->not_empty);
}

这段代码里有三个值得展开的设计点。

第一个是 push 里先解锁再 signal。如果持锁时 signal，消费者会在锁还没释放时就被唤醒，然后发现锁被占着又睡回去，白白多一次上下文切换。先解锁再 signal，消费者被唤醒时锁已经空闲，可以立即进入临界区。这个顺序调整对性能的影响很直接。

第二个是 pop_all 取出全部消息时，只拿走链表头到指针的引用关系，并不逐个释放节点。真正释放节点的工作交给消费者在临界区外完成。这样锁里面的操作只是改几个指针，持锁时间极短。对于同一批消息，批量取出后的处理流程完全无锁，处理多少条都不会阻塞生产者。

第三个是 close 时必须用 broadcast 而不是 signal。因为可能有多个消费者线程同时阻塞在 pthread_cond_wait 里等待消息，如果只唤醒一个，它消费完队列里剩余消息后也会退出，其他消费者线程根本没收到关闭通知，会永远睡眠下去。用 broadcast 一次唤醒所有等待者，每个人检查 closed 标志后自行退出，这才是干净的线程关闭流程。

5. 消息对象设计与内存管理

5.1 消息里放指针还是放对象

队列里空转传送的，其实不应该是数据本身，而是消息的引用。很多人初写队列时喜欢把完整对象拷进去，比如在栈上构造一个结构体，直接塞进队列。这在对象很小、且是 POD 类型时问题不大，但一旦消息变成复杂结构、字符串、容器，拷贝的开销就会放大。

工程上我建议在队列里传递指针。分两种写法：

一种是用裸指针 void *。队列本身完全不关心消息内容，只是搬运指针。这是最灵活也是最朴素的做法。但这要求消息的释放必须由消费者严格负责，否则很容易泄漏。

另一种是用引用计数的智能指针。如果项目是 C++，可以直接在队列节点里放 std::shared_ptr 或 std::unique_ptr。前者允许一条消息被多个消费者共享，后者表达的是所有权的转移，语义清晰，也更安全。唯一要注意的是智能指针本身有原子操作开销，在超高频场景下需要实测一下是否值得。

如果既有性能要求又希望类型安全，我可以给出一个折中方案，定义统一的消息头：

c复制typedef struct {
    uint16_t type;
    uint16_t len;
    uint32_t seq;
    char     data[];
} mq_msg_t;

所有消息只传 mq_msg_t*，前面带固定头部，后面跟变长数据。这样生产者不再复制整包，消费者用 flex array 直接访问数据，内存开销小，而且调试时能通过 type 和 seq 做追踪。

5.2 减少动态分配的三板斧

队列节点频繁 malloc/free 是性能杀手，这个前面已经提过。我总结了三招来缓解。

第一招是对象池。队列内部维护一个已经分配好的节点池，push 时从池里拿一个空闲节点，pop_all 后把节点归还池子。严格意义上，这个对象池本身的并发也要加锁，但因为池子的操作比消息处理轻量得多，收益依然客观。

第二招是预留缓冲区。如果消息类型固定，而且单条消息长度有上限，那可以让生产者在压测阶段分配一批固定大小的内存块，整个队列周期内重复利用，而不是收发一次就释放一次。

第三招是批处理。这是最立竿见影的。消费者拿到一批消息后，尽量对整批数据做统一的资源释放，而不是一条消息一次 free。批量释放配合批量收发，内存分配次数可以降一个数量级。

无论用哪一招，都要记住一点：先用 profile 工具定位，再决定要不要优化。我见过有人把队列节点优化得花团锦簇，结果一测发现瓶颈根本不在队列，而在下游数据库写入。优化之前先量化，这是做性能工作最基本的态度。

6. 正确性验证与压测方法

6.1 先证明队列是对的

无锁代码不经过严格验证，我是不敢直接放上生产环境的。我一般做三层测试。

第一层是功能正确性。生产线程往队列里塞 100 万个序号连续的整数，消费者线程取出来校验序号是否从 0 到 999999 连续且不重复。这个测试跑十遍，一遍都不能出错。这能顺带验证 release/acquire 内存序是否真的生效，避免那种“偶尔看到旧数据”的隐性竞态。

第二层是退出安全性。生产者在队列还有未消费消息时调用 close，消费者必须把剩余消息全部处理完才退出，不能扔消息。这个逻辑在锁队列里由 pop_all 的循环保证，在 SPSC 队列里就要靠外部协调了，我一般会让消费者先把环形队列置空再退出。

第三层是并发压力。开多个生产者和多个消费者线程，在锁批量版的队列里同时灌数据，观察是否有消息重复或丢失。为了能检测重复，每条消息上都带一个全局唯一的 seq，消费者用一个 bitmap 来标记哪些序号已经出现过，一出现重复立刻上报错误。

这些测试我都建议在编译时开启 -fsanitize=thread 跑一遍。TSAN 能抓出很多微妙的竞态条件，虽然运行时开销大，但作为开发期检查工具非常值。内存问题再用 -fsanitize=address 检查一遍。两道消毒做完，代码质量基本就有底了。

6.2 性能压测怎么跑

压测时我用 clock_gettime(CLOCK_MONOTONIC) 记录整段时间，用原子计数器统计生产和消费的消息数，跑 10 秒后算出每秒吞吐量。为了得到有说服力的数据，生产者和消费者各绑定一个独立CPU核心，用 pthread_setaffinity_np 防止线程被调度器来回迁移，避免缓存行在不同核之间频繁迁移带来的噪声。

下面这个表是我在 x86_64 平台（主频3.0GHz左右、L3缓存较大的服务器CPU）上测得的一组示意数据，用来给大家一个数量级的概念，不同机器上结果会差很多：

我只把这组数据当作“自己机器的参考值”，从来不会跟别人说“这个方案能跑 X 万并发”。因为压测结果受编译器版本、CPU架构、消息对象大小、缓存命中率的影响太大，真正要比较的是优化前后在同一台机器上的相对提升倍数。如果 SPSC 版本比基础版提升了5倍以上，批量版在并发场景下翻了一倍以上，方向就是对的。

压测时还有一个容易被忽略的点：要同时观察 CPU 占用率。有些版本吞吐量很高，但多个 CPU 核心被打满，这种情况下吞吐是“烧 CPU 烧出来的”，不是低延迟换来的。真正健康的队列应该是消费者线程CPU占用平稳，生产者在大部分时间里不会因为队列满而空转。

6.3 几个常见并发问题的排查

丢消息。如果 SPSC 队列出现丢消息，第一个怀疑对象是内存序用错。有人图省事把 head 和 tail 的 load 全部写成 relaxed，在编译器的激进优化下，consumer 可能看到过期的 tail，导致队列明明有数据却以为空。解决方法是严格按 3.2 节的内存序来，不要自行“优化”掉 acquire 和 release。

重复消费。本地队列里直接传递指针本身不会产生重复，问题往往出在“多个消费者共享同一个消息对象”的场景。比如多个消费者线程从同一个队列里 batch 取出消息，如果下游做了重试逻辑，就可能把同一条消息处理两次。这个不是队列能解决的，必须在下游接口设计里保证幂等性。

唤醒丢失。条件变量使用不当会出现这种情况。比如生产者先 pthread_mutex_unlock，然后 consumer 进入 pthread_cond_wait，之后 producer signal，看起来信号丢了。实际上条件变量的超集语义要求，wait 调用必须在持有锁时进行，signal 时不必持锁。所以只要遵循“先持锁判断条件，再 wait”这个规范写法，就不会丢唤醒。这里最容易错的是把判断条件的代码写到了 pthread_mutex_lock 之前，那种代码我在代码评审里见过好几次。

6.4 队列满时的策略

队列满的问题，很多人写队列时才想起来。我建议在设计接口时就要想清楚，因为不同业务对满队列的容忍度完全不同。

日志类场景，消息攒着没用，可以丢弃最老的消息，保证新消息能进来。用环形缓冲区天然支持这种覆盖策略，只需要在 push 时允许生产者把 head 往前推。

订单交易类场景，一条消息都不能丢，必须让生产者在队列满时阻塞，直到有空间。这其实又回到了加锁模式，因为无锁的 try_push + 外部等待组合太麻烦了。对可靠性要求极高的场景，我不会硬套无锁方案。

监控指标类场景，可以丢弃最新消息，保留较旧的数据，避免监控曲线出现断点。不过更合理的做法是记录丢弃计数，让运维人员知道队列曾经满过。

我把这些策略总结成一句话：队列满不是 bug，而是一种信号。它告诉你系统的生产者或消费者两侧出现了不平衡，这时候最该做的不是无限扩容队列，而是赶紧找出是谁拖慢了整体链路。

7. 实战中的六条避坑心得

写这篇博客的时候，我又翻了翻前两年排掉的队列相关的线上问题，有几条经验值得在这里单独列出来。

第一，容量一定选2的幂。这不是为了炫技，而是位与运算在热路径上实打实地比取模快。同时，如果有条件，把容量配成可配置项，压测时用工具自动跑一遍不同容量下的吞吐曲线，你会发现容量从 256 加到 1024 时性能会有一个跳变，这个点就是你当前场景下的甜点值。

第二，SPSC无锁队列要配合 CPU 亲和性使用才能发挥最大威力。生产线程和消费线程分别绑定到不同物理核心上。绑核之后，两个线程各自的读写缓存行不会互相抢夺，吞吐量有时能再涨 30% 以上。但注意，绑核是手段不是目的，如果机器上还跑着其他高负载任务，就要先评估全局的资源分配。

第三，无锁队列别轻易扩展成 MPMC。遇到“多生产者想无锁”的需求，先冷静一下，把 CAS、ABA、内存序的复杂度换算成人力成本，大概率会发现用“锁+批量”解决更划算。我亲眼见过有人为了无锁，硬是把代码写得无人能维护，最后整个模块重写。

第四，线性队列要小心“队首阻塞”。当消费者遇到一条耗时特别长的消息时，后面的所有消息都会排队等待。如果你不能保证每条消息的处理时间都差不多，就应该在队列节点里加入优先级字段，或者在消息进入队列前先做分类，用多个队列分别处理不同类型、不同耗时的任务。

第五，测试队列正确性时，一定要开 TSAN。不要相信“这个代码我看了几十遍应该没问题”，线程问题看是看不出来的。TSAN 第一次跑我的 SPSC 队列就报了一个潜在的数据竞争，检查后才发现是我在某个分支里漏写了原子操作。没有工具做兜底，光靠人肉 review，早晚出事。

第六，eventfd + 无锁队列是 Linux 下事件驱动服务里非常顺手的组合。它能让队列消息唤醒和 epoll 事件唤醒统一，代码结构会干净很多。如果你在维护一套大型长连接服务，建议优先用这个方案，而不是自己起一批线程在那里死等队列。

这套代码我拿到一个采集系统里实际跑了半年，从最开始的 mutex+链表版换成 SPSC + 批量版之后，采集端的 CPU 使用率降了三成，队列堆积的消息数在峰值时也没再超过两位数。最后再提一个可能对你有帮助的小细节：所有队列接口的命名，我统一用了 try_push、pop_all、close 这种语义明确的动词，而不是 put、get、stop 这样含糊的叫法。命名清晰了，接口的基本语义就表达了一半，调用方不会误解，后续维护也不会迷路。