什么是 Niche？

在计算机的世界中，某些数据类型在二进制层面有一些逻辑上不会被使用的值，这些未被使用的值就是 Niche。

例如，Rust 规定 Box、引用等不为空，0 就是它们的 Niche。

Rust 编译器可以利用这些 Niche 来存储额外的信息，如枚举的标签，从而优化内存布局和性能。

assert_eq!(size_of::<Option<Box<i32>>>(), size_of::<Box<i32>>());

enum MyEnum2 {
  Zero,
  NonZero(std::num::NonZeroU8),
}
assert_eq!(size_of::<MyEnum2>(), size_of::<u8>());

哪些类型能被优化？

理论上，只要类型存在“空隙”，就能被优化。常见的类型包括：

指针与引用类型

Rust 保证所有的指针和引用都是非空的，因此内存地址 0 就是一个天然的“空隙”。

• 引用：&T 和 &mut T
• 智能指针：Box<T>, Rc<T>, Arc<T>
• 非空指针：ptr::NonNull<T>
• 函数指针：fn() 等

非零整数类型

标准库在 std::num 模块下提供了一系列专门设计的类型，它们通过类型系统保证了值不为 0。

• NonZeroU8, NonZeroU16, NonZeroU32, NonZeroU64, NonZeroU128, NonZeroUsize
• NonZeroI8, NonZeroI16, NonZeroI32, NonZeroI64, NonZeroI128, NonZeroIsize

布尔类型

bool 只有两个可能的值：true 和 false，其余值（2 - 255）都是 Niche。

字符类型

Unicode 标准并没有使用全部的 32 位空间。 例如，范围在 0xD800 到 0xDFFF 之间的值是代理对，它们是无效的 Unicode 标量值。

Rust 的 char 类型保证会是有效的 Unicode 字符，因此可以利用这些“空隙”作为 Niche。

部分标准库 IO 类型

在 Unix 平台上，文件描述符是一个非负整数，-1 用于报告错误。因此 -1 就是它的 Niche。

assert_eq!(size_of::<Option<std::fs::File>>(), size_of::<std::fs::File>());

很多标准库 IO 类型都具有类型的特定，例如：

• std::fs::File
• std::net::TcpStream
• std::process::Child
• std::io::Stdin, std::io::Stdout, std::io::Stderr

枚举类型

用户可以通过自定义枚举来创建具有 Niche 的类型。 只要枚举定义的变体数量少于其底层表示所能容纳的状态数量，就会产生“空隙”。

enum MyEnum {
  Variant1 = 0,
  Variant2 = 1,
}

结构体

Niche 优化具有传递性。如果一个结构体包含了一个具有 Niche 的字段，那么这个结构体本身也具有 Niche。

struct MyStruct {
  ptr: ptr::NonNull<u32>, // Niche: 0
  val: u32,
}

嵌套类型

此外，Niche 优化也支持嵌套枚举。一个已经被 Niche 优化的枚举如果还存在 Niche，那它依旧能被继续优化：

enum MyEnum {
  Variant1,
  Variant2,
}

assert_eq!(size_of::<Option<MyEnum>>(), size_of::<MyEnum>());
assert_eq!(size_of::<Option<Option<MyEnum>>>(), size_of::<MyEnum>()); // Option<Option<T>> 也能被优化

不过，这种优化虽然节约了内存，但也可能带来一些性能上的开销。 相比于直接使用标签，编译器可能需要进行一些位操作来判断当前枚举类型，增加了运行时复杂性。

如何实现自定义 Niche？

利用标准库内部特性

可以使用不稳定属性 #[rustc_layout_scalar_valid_range_start] 和 #[rustc_layout_scalar_valid_range_end] 来告诉编译器该类型的有效值范围。范围之外的值就被视为 Niche。

这需要使用 nightly 版本的 Rust，因为这些属性不稳定（官方明确说明只供 libcore/libstd 使用）。

下面是一个示例，定义了 NonMaxU32 类型，它的有效值范围是 0 到 u32::MAX - 1。

#![feature(rustc_attrs)]

#[repr(transparent)]
#[rustc_layout_scalar_valid_range_start(0)]
#[rustc_layout_scalar_valid_range_end(4_294_967_294)]  // u32::MAX - 1
pub struct NonMaxU32(u32);

impl NonMaxU32 {
    pub const fn new(value: u32) -> Option<Self> {
        if value == u32::MAX {
            None
        } else {
            Some(NonMaxU32(value))
        }
    }

    pub const fn get(self) -> u32 {
        self.0
    }
}

验证优化效果：

assert_eq!(std::mem::size_of::<NonMaxU32>(), 4);
assert_eq!(std::mem::size_of::<Option<NonMaxU32>>(), 4);

使用第三方库

• nomany：nonany 库允许用于指定任意一个 Niche 值，其内部通过 NonZero* + XOR 技巧实现。
• nonmax: 提供了 NonMax* 等以最大值为 Niche 的整数类型。
• nook：该库提供了 BalancedI* 类型，具有相等范围的正负值，其 Niche 是最小的负数。

可视化

Niche.rs 提供了一个可视化界面，用于展示 Rust 类型内存布局与 Niche 优化细节。

参考文献

• Niche optimizations in Rust

与传统服务端 Session 不同，JWT 是无状态的，服务端无需存储会话信息，因此非常适合分布式系统和微服务架构。

JWT 的结构

JWT 主要由三部分构成，每部分均采用 Base64 编码存储，中间用 . 分隔：

Header.Payload.Signature

1. Header：包含 Token 的元数据，例如用于签名的算法。
2. Payload：存储声明，例如用户的身份和权限、Token 过期时间等。
3. Signature：使用密码加密后得到的签名，用于保证数据的真实性和完整性。

可以在 JWT Debugger 中在线尝试下 JWT 的编解码过程。

Header

Header 中存储了 Token 的元数据，包括签名算法和令牌类型：

{
  "alg": "HS256",
  "typ": "JWT"
}

• alg：指定签名算法。常用：
  • HS256（HMAC + SHA-256）：对称加密算法，兼顾效率与安全性，适合小项目。
  • RS256（RSA + SHA-256）或 ES256（ECDSA + SHA-256）：非对称加密，适合高安全需求。
• typ：指定类型，一般设置为 JWT，应用程序可通过该项来区分不同类型的对象。

Payload

Payload 中可以存储任意字段，供服务端获取用户身份、检验用户权限等需求：

{
  "sub": 328913,
  "aud": "web",
  "role": "admin",
  "exp": 1733631682
}

此外，RFC 7519 中定义了一些标准字段，推荐使用但不强制：

| 字段 | 全称 | 含义 | |

引言：与 Option 的比较

本质上，Result 相当于 Option 的一个扩展版本。 因此，Option 中的方法在 Result 中大多也有对应的实现。

这些相似的方法可以分为以下几类：

• 完全相同的方法，如 unwrap、filter 等。 它们只处理 Option 中的 Some 分支或 Result 中的 Ok 分支，本质上没有区别。

• 除了名称不同外，功能完全相同的方法。 这是由于 Option 和 Result 中的命名不同所致，例如 Option::is_some 对应 Result::is_ok。

• Error 所特有的方法。 与 Option::None 不同，Result 中的 Err 可以存储值，与 Ok 和 Some 具有相同的地位，因此也提供了类似的方法。 这些方法都以 _err 结尾，功能相同，例如 unwrap_err、inspect_err、map_err 等。

因此，如果你已经熟悉 Option 的相关方法，可以更容易地理解 Result 中的方法。

为了避免重复，这里我们只列出 Result 中独有的、或与 Option 中不同的方法。

安全提取值

这两个方法用于将 Result 中的 Ok 或 Err 分支转换为 Option 类型，用于从 Result 中安全地提取值。

fn ok(self) -> Option<T>
fn err(self) -> Option<E>

静态提取值

这两个方法利用了类型系统本身的安全性，可以将 Result 转换为 T 或 E 类型，但要求另一个类型必须是不可实例化的类型 !（即永远不会有值的类型）。

const fn into_ok(self) -> T where E: into<!>
const fn into_err(self) -> E where T: into<!>

作为程序返回值

Result 实现了 Termination trait，可以作为主函数的返回值。 由于 main 函数只支持整数类型的退出码，Result 会通过 report 方法将自身转换为 ExitCode。

impl<T: Termination, E: Debug> Termination for Result<T, E> {
  fn report(self) -> ExitCode
}

Result 中不存在的方法

下面这些方法在 Option 中存在，但在 Result 中并不存在类似方法：

• is_none_or（但存在 is_err_and）
• as_pin_ref 和 as_pin_mut
• as_slice 和 as_mut_slice
• filter
• zip、zip_with 和 unzip
• insert、get_or_insert、get_or_insert_default 和 get_or_insert_with
• take、replace 和 take_if

这些方法的缺失，主要是因为 Result 和 Option 的定位不同导致的。 Option 更接近一个值的容器，因此提供了更多与容器相关的方法。 而 Result 更侧重于错误处理和结果传递，因此其方法更多地围绕这两个方面展开。

参考链接

• Enum Result | Rust std
• Module result | Rust std

以上两处官方文档是最权威的参考资料。 在不确定具体行为或需要查看最新稳定版 API 时，优先以官方文档为准。

在查阅资料时，我发现了 Caddy 这个轻量级的 Web 服务器，配置文件简洁明了，内置自动 HTTPS 功能，非常适合个人和小型项目使用。

为什么选择 Caddy？

Caddy 是一款基于 Go 语言编写的强大且可扩展的平台，提供“开箱即用”的使用体验，相比 Ngnix 有以下优势：

• 配置文件简洁：Caddy 的配置文件非常直观，提供了合理的默认值，减少了配置的复杂度。
• 自动 HTTPS：Caddy 内置了 Let's Encrypt 支持，能够自动获取和续期 SSL 证书，无需额外配置。
• 文档易读：Caddy 官方文档清晰易懂，不像 Nginx 那样零散臃肿。

尽管 Caddy 可能在性能上不如 Nginx，特别是在高并发场景下，但对于个人网站和小型项目来说，Caddy 已经足够强大。

使用 Caddy

首先，按照官方文档的指引，安装好 Caddy 并启用。

在当前目录下，创建名为 Caddyfile 的配置文件，编辑该文件：

www.sunirein.tech {
  redir https://sunirein.tech{uri}
}

sunirein.tech {
  root * /var/www
  file_server
  encode gzip zstd
}

ttrss.sunirein.tech {
  reverse_proxy localhost:1081
  encode gzip zstd
}

上面这份配置文件实现了以下功能：

1. 将 www.sunirein.tech 重定向到 sunirein.tech。
2. 为 sunirein.tech 提供静态文件服务，文件根目录为 /var/www，并启用 gzip 和 zstd 压缩。
3. 将 ttrss.sunirein.tech 的请求反向代理到本地的 1081 端口，并启用 gzip 和 zstd 压缩。

此外，Caddy 会自动为这些域名获取和续期 SSL 证书，自动处理 HTTPS 重定向等问题，无需额外配置，非常省心。

如果需要为其他域名添加服务，只需在 Caddyfile 中添加相应的块即可。

之后，使用以下命令加载 Caddy 配置，使其生效：

caddy reload

可选：配置阿里云 DNS

Caddy 默认通过 HTTP 质询或 TLS-ALPN 质询来验证域名所有权，从而自动获取证书。

但是，由于我配置了 DNS 分流，国外的访问流量会被解析到 Github Page，因此 Let's Encrypt 无法验证域名所有权。

这时，可以通过配置 DNS 质询来解决这个问题。这里我以阿里云 DNS 为例，其他 DNS 服务商的配置方法类似。

参考资料

• Caddy 官方文档
• Caddy v2 中文文档
• caddy 配置反向代理和 ssl 证书申请 | 博客园 turingguo

存在性与谓词判断

下面两个方法用于快速判断 Option 的变体或在判断时对内部值做简单谓词检查。 它们能避免显式的模式匹配，从而使代码更紧凑。

const fn is_some(&self) -> bool
const fn is_none(&self) -> bool

fn is_some_and(self, f: impl FnOnce(T) -> bool) -> bool
fn is_none_or(self, f: impl FnOnce(T) -> bool) -> bool

不过，当判断逻辑较复杂时，仍然建议使用 match 或 if let 以提高可读性。

引用适配器

as_ref/as_mut 用于将 Option<T> 转换为对内部值的引用形式，从而避免移动所有权。

const fn as_ref(&self) -> Option<&T>
const fn as_mut(&mut self) -> Option<&mut T>

as_deref 系列在处理 Option<Box<String>> 这类嵌套可解引用类型时十分便捷，能直接得到目标类型的引用，避免 map(|b| b.deref()) 的繁琐写法。

fn as_deref(&self) -> Option<&<T as Deref>::Target>
where T: Deref

fn as_deref_mut(&mut self) -> Option<&<T as Deref>::Target>
where T: Deref

as_pin 系列适用于与 Pin 相关的 API，简化相关操作。

const fn as_pin_ref(self: Pin<&Option<T>>)     -> Option<Pin<&T>>
const fn as_pin_mut(self: Pin<&mut Option<T>>) -> Option<Pin<&mut T>>

as_slice 系列在内部有元素时返回一个单元素切片，为空则返回空切片。 它们可以方便地 Option<T> 作为切片，参与迭代或切片 API。

const fn as_slice(&self) -> &[T]
const fn as_mut_slice(&mut self) -> &mut [T]

提取内部元素

触发 panic 的取值

expect 与 unwrap 在调试或明确能保证存在时使用较为方便，但在生产代码中需谨慎，建议在无法合理处理 None 情形时才用，以避免运行时 panic。

const fn expect(self, msg: &str) -> T
const fn unwrap(self) -> T

提供默认值的取值

fn unwrap_or(self, default: T) -> T                  // 立即求值
fn unwrap_or_else(self, f: impl FnOnce() -> T) -> T  // 延迟求值
fn unwrap_or_default(self) -> T where T: Default     // 使用 T:Default

不做检查的取值

该方法在 None 时会导致未定义行为，仅应在经过严格分析并能保证不为 None 的极端性能路径中使用。

const unsafe fn unwrap_unchecked(self) -> T

转换、映射与链式操作

转换成 Result

当需要将 Option 上升为 Result 时（例如在错误传播链中），常需要用到这两个方法。 若错误值构造代价大应选择 ok_or_else。

在链式错误处理时，ok_or_else 常与 ? 操作符结合使用以保持代码简洁。

// 直接映射
fn ok_or<E>(self, err: E) -> Result<T, E>                       // 立即求值
fn ok_or_else<E>(self, err: impl FnOnce() -> E) -> Result<T, E> // 延迟求值

transpose 用于进行 Option<Result<_>> 和 Result<Option<_>> 的互换，常用于从可能失败的解析或异步接口收集结果。

impl<T, E> Option<Result<T, E>> {
  const fn transpose(self) -> Result<Option<T>, E>
}

// 相当于
match self {
  Some(Ok(val))  => Ok(Some(val))
  Some(Err(err)) => Err(err)
  None           => Ok(None)
}

条件过滤

filter 在满足谓词时返回内部值，否则返回 None，是函数式风格中的常见表达。

fn filter<P>(self, predicate: P) -> Option<T>
where
  P: FnOnce(&T) -> bool

扁平化

flatten 能消除一层 Option 嵌套，用于处理多层 Option 嵌套，避免手动 unwrap 或嵌套匹配。

impl<T> Option<Option<T>> {
  const fn flatten(self) -> Option<T>
}

观察

inspect 会使用内部值来调用 f，并原样返回，不做任何修改。 它适合在链式调用中添加日志、断言或调试操作等不改变原值的操作。

fn inspect<F>(self, f: F) -> Option<T>
where
  F: FnOnce(&T)

映射

map 用于对内部值进行纯映射，结果会被自动封装回 Option。

fn map<U, F>(self, f: F) -> Option<U>
where
  F: FnOnce(T) -> U

标准库还提供了下面两个带默认值的映射版本，当输入为 None 时将返回提供的默认值。

fn map_or<U, F>(self, default: U, f: F) -> U
where
  F: FnOnce(T) -> U

fn map_or_else<U, D, F>(self, default: D, f: F) -> U
where
  D: FnOnce() -> U,
  F: FnOnce(T) -> U

压缩和解压缩

zip 只有在两个 Option 均有值的情况下才会返回 Some((s, o))，其余情况均返回 None。 它适合需要同时存在两个可选值才能继续处理的场景，例如同时从两个来源获取配置项。

fn zip<U>(self, other: Option<U>) -> Option<(T, U)>

zip_with 提供了更灵活的压缩行为，允许在存在两个值时直接进行合并转换，避免额外的元组构造。

const fn zip_with<U, F, R>(self, other: Option<U>, f: F) -> Option<R>
where
  F: FnOnce(T, U) -> R

unzip 则是 zip 的逆操作，将 Some((s, o)) 解包为 (Some(s), Some(o))

impl<T, U> Option<(T, U)> {
  fn unzip(self) -> (Option<T>, Option<U>)
}

布尔运算

与、或

and 方法当自身是 Some 时返回 optb，是 None 时返回 None（相当于什么也不做）。
or 方法当自身是 None 时返回 optb，是 Some 时返回自己（相当于什么也不做）。

fn and<U>(self, optb: Option<U>) -> Option<U>
fn or(self, optb: Option<T>) -> Option<T>

and_then 和 or_else 则是它们的函数版本。

fn and_then<U, F>(self, f: F) -> Option<U>
where F: FnOnce(T) -> Option<U>

fn or_else<F>(self, f: F) -> Option<T>
where F: FnOnce() -> Option<T>

异或

除了上面的方法外，Rust 还提供了一个不太常见的 xor 方法。 该方法接受两个 Option，当其中只有一个是 Some 时返回该值，否则返回 None。

fn xor(self, optb: Option<T>) -> Option<T>

xor 在某些需要“互斥存在”的场景很有用，但在日常编码中较少见，使用时应确保语义清晰以免误解。

比较运算符

如果 T 实现了 PartialOrd 或 Ord，Option<T> 会自动派生相应的实现。

在这种语境下，两个 Some 之间的比较遵循 T 原有的规则，而 None 小于任何的 Some。

该实现主要用于简化一些比较逻辑，例如对 Vec<Option<T>> 进行排序。 需要注意的是，这一约定会影响排序与集合操作的结果，在需要不同语义时应显式处理 None（例如在比较前将 None 映射为特定的哨值）。

作为迭代器使用

你可以直接将 Option 作为迭代器使用。 对于 Some，将作为一个单值迭代器；对于 None，将作为一个空迭代器。

该用法常见于串联迭代器，例如：

let mayby_num = Some(42);
let nums: Vec<i32> = (0..4).chain(mayby_num).chain(4..8).collect();
assert_eq!(nums, [0, 1, 2, 3, 42, 4, 5, 6, 7])

以这种方式串联迭代器，可以获得一致的返回值类型，从而作为 impl Iterator 的返回值。

fn make_iter(do_insert: bool) -> impl Iterator<Item = i32> {
    match do_insert {
        true => (0..4).chain(Some(42)).chain(4..8)
        false => (0..4).chain(None).chain(4..8)
    }
}

从迭代器聚合为 Option

容器聚合

Option 实现了 FromIterator<Option<T>> trait，可以将任何 Option 的迭代器收集成一个包含值的容器的 Option。

如果迭代器内的值全是 Some，将返回包含这些值的容器；否则，返回 None。

let v = [Some(4), Some(3), Some(11)];
let res: Option<Vec<_>> = v.into_iter().collect();
assert_eq!(res, Some(vec![4, 3, 11]));

let v = [Some(4), None, Some(11)];
let res: Option<Vec<_>> = v.into_iter().collect();
assert_eq!(res, None);

聚合运算（求积、求和）

Option 实现了 Product<Option<T>> 和 Sum<Option<T>> trait，可以通过 product 或 sum 方法来对 Option 迭代器求积或求和。

let input = ["123", "invalid", "2"];
let res: Option<i32> = input.into_iter().map(|s| s.parse::<i32>().ok()).product();
assert_eq!(res, None);

let input = ["123", "2", "2"];
let res: Option<i32> = input.into_iter().map(|s| s.parse::<i32>().ok()).product();
assert_eq!(res, Some(492));

就地修改与所有权操作

插入与可变引用

insert 会用新值替换内部值并返回可变引用，适合希望在容器中就地构造或更新值的场景。

fn insert(&mut self, value: T) -> &mut T

下面几个方法与 insert 类似，但仅在为 None 时更新内部值。

fn get_or_insert(&mut self, value: T) -> &mut T
fn get_or_insert_default(&mut self) -> &mut T where T: Default
fn get_or_insert_with(&mut self, f: impl FnOnce() -> T) -> &mut T

这些方法在处理缓存、懒初始化或复用 Option 内部存储时非常有用。

移动与替换

take 将值移动出去并把容器置为 None，这是实现可复用容器或交换逻辑的常见手段。

const fn take(&mut self) -> Option<T>

replace 则会直接用新值替换旧值，并同时获取旧值进行处理。

const fn replace(&mut self, value: T) -> Option<T>

与 take 不同，replace 保证容器最终有新值，因此常用于更新缓存或重置状态。

fn take_if<P>(&mut self, predicate: P) -> Option<T>
where
  P: FnOnce(&mut T) -> bool

参考链接

• Enum Option | Rust std
• Module option | Rust std

以上两处官方文档是最权威的参考资料。 在不确定具体行为或需要查看最新稳定版 API 时，优先以官方文档为准。

表示路径的类型

Rust 中有两种表示路径的类型：

• PathBuf：拥有所有权且可变的路径，类似于 String。
• Path：路径的切片，类似于 str。

这两种类型实际上是 OsString 和 OsStr 的封装，而非使用 Rust 默认的字符串类型，因此在转换为 String 或 str 时比较麻烦。

路径转换为字符串的方法

由于 PathBuf 实现了 Deref<Target=Path>，因此这里仅介绍 Path 的方法。

获取 OsStr 后转化

impl Path {
  pub fn as_os_str(&self) -> &OsStr
}

可以调用上面提供的方法先将路径转化为 OsStr 再转换为字符串。

impl OsStr {
  /// 如果为有效的 Unicode 编码，返回内部 str，否则返回 None
  /// 该方法不会涉及拷贝或重编码，但是需要对字符串做有效性检查
  pub fn to_str(&self) -> Option<&str>

  /// 如果为有效的 Unicode 编码，返回内部 str，不作任何转换
  /// 否则，会将所有无效部分替换为 U+FFFD(�) 再返回，这需要分配新的内存
  pub fn to_string_lossy(&self) -> Cow<'_, str>
}

如果最终需要得到 String，还需再做额外的转换，完整代码如下：

let path = Path::new("./foo/bar.txt");
assert_eq!(
  String::new("./foo/bar.txt"),
  path.as_os_str().to_str().unwrap().to_string()
);
assert_eq!(
  String::new("./foo/bar.txt"),
  path.as_os_str().to_string_lossy().into_owned()
);

通常如果使用 to_str 会搭配 unwrap，表示我们预期输入是合法 Unicode。

而如果只是想要一个可用的字符串用于打印/日志，一般建议使用 to_string_lossy。 它只会在必要的时候进行有损转换，大多数情况下与 to_str 没有性能差异。

直接调用 Path 的转换方法

由于将 Path 转换为字符串的操作很普遍，Rust 为上面的操作提供了以下便携方法：

impl Path {
  pub fn to_str(&self) -> Option<&str>
  pub fn to_string_lossy(&self) -> Cow<'_, str>
}

在使用时可以直接调用这两个方法，无需经过 OsStr 的转换。

Display 接口

impl Path {
  pub fn display(&self) -> std::path::Display<'_>
}

Path 提供了一个专门用于打印路径的方法，其行为类似 to_string_lossy，返回一个实现了 Display trait 的类型。 因此也可以使用该方法来获取字符串：

let path = Path::new("./foo/bar.txt");
assert_eq!(
  String::new("./foo/bar.txt"),
  path.display().to_string()
);

不过一般不建议使用该方法，更推荐使用意义更为明确的 to_string_lossy。

个人实践

一般我会根据需要选择 to_str 和 to_string_lossy：

• 如果要保证输入为合法 Unicode，选择 to_str。
• 如果无法确认输入的编码，或者需要用于打印/日志，选择 to_string_lossy。

使用这些方法将路径转换为字符串会比较冗长，因此我会将其封装为对应的 trait:

pub trait PathStr {
  fn to_utf8_string(&self) -> String
}

impl PathStr for Path {
  fn to_utf8_string(&self) -> String {
    self.to_str().unwrap().to_string()
  }
}

你可以根据自己的需要调整上面函数，只需在使用时导入对应的 trait 即可。

什么是签名？

大家平时在 Github 上查看提交信息时，应该会注意到，在提交列表里有些提交上面会显示一个 Verified 状态。 这表示其经过签名且被 Github 验证通过。

签名是 Git 的一项安全机制，用于验证提交是由用户本人发起的。 用户可以在本地对 Commit 和标签进行签名，经过验证的签名便会在 Github 在被显示为 Verified 状态。

生成签名

Git 为个人用户提供了 GPG 和 SSH 两种签名方式。

GPG

在命令行键入下列命令即可创建 GPG 签名：

gpg --full-generate-key

之后按照提示，依次输入密钥类型、密钥大小、有效期、用户信息等信息。 注意这里的用户信息应该与你在 Git 中设置的信息一致。

最后再输入使用该密钥所需的安全密钥，在每次使用该密钥时 GPG 都会要求你键入该安全密钥。

密钥生成完后可以使用下面的命令来查看已经生成的密钥：

gpg --list-secret-keys --keyid-format=long

生成的密钥类似下面这样：

pub   ed25519/EFBD20CF51E1A4A0 2025-08-17 [SC]
      C53C71B1F960AFD0DD770485EFBD90CF51E1A4A0
uid                      User <email@example.com>
sub   cv25519/1F3FD0F56C3D54B3 2025-08-17 [E]

这里 EFBD20CF51E1A4A0 是该密钥的 ID。输入下列命令，替换相应的密钥 ID，以获取完整的 GPG 密钥：

gpg --armor --export EFBD20CF51E1A4A0

之后打开 Github，将生成的 GPG 密钥上传到你的账户，这样 Github 才会信任这个签名。

SSH

SSH 签名的生成较为简单，替换下面的邮箱为你实际使用的邮箱即可：

ssh-keygen -t ed25519 -C "your_email@example.com"

如果你已经使用 SSH 生成过签名，这里 SSH 会提示你键入新的文件来保存签名，请记住这个文件的位置。

之后同样需要将签名上传到 Github 上， 注意 SSH 密钥那一栏要选择 Signing Key 而不是 Authentication Key。

设置 Git 使用签名

在提交时使用签名

在提交时，使用 -S 标志对该提交进行签名：

git commit -S -m "COMMIT_MESSAGE"

如果是标签，则使用 -s 标志：

git tag -s MYTAG

如果设置成功，你便可以在 Github 上看到对应的 Verified 标志。

自动签名

如果你觉得手动签名比较麻烦，且容易遗忘，可以通过下面的配置让 Git 在提交和创建标签时自动帮你签名：

git config --global commit.gpgsign true
git config --global tag.gpgSign true

为已提交的 commit 签名

有时你的 commit 已经提交，而你需要为这些提交签名。

首先找到你需要签名的最早的 commit，选择该 commit，启动交互式变基：

git rebase -i <commit-hash>

之后给该 commit 及其后面的所有 commit 签名：

git commit --amend -S

GPG 和 SSH 密钥如何选择？

GPG 提供了更多高级的安全功能，例如密钥本身会携带用户信息、支持设置有效期等，而 SSH 则相对简单。 但两者的安全性更多取决于你使用的加密算法与密钥长度，并无优劣之分。

此外，GPG 密钥每次使用都需要用户键入相应的安全密钥，较为繁琐。 尽管有专门的工具可以帮你跳过这一过程，但配置起来也比较麻烦，不如 SSH 密钥简单。

如果你只是需要简单的签名功能以满足某些仓库的需求，配置较为简单的 SSH 密钥就已经够用了。

参考文献

• About commit signature verification | GitHub Docs

GNU Stow 是一个符号链接农场管理器，它可以将位于文件系统不同目录中的不同软件包和数据，伪装成安装在同一个位置。

使用 GNU/Stow 这一简单的工具，可以帮我们实现 Linux 上的两大难题：

• 管理手动编译安装的程序
• 管理复杂的用户配置文件

安装

各大发行版的包管理器都有 GNU/Stow，不过我更推荐直接从官网下载源代码， 手动编译安装，以获取最新版本。

使用

GNU/Stow 会自动在当前目录的上一级目录创建软链接。 例如，如果当前目录是 ~/dotfiles，当我们运行 stow bash 时，GNU/Stow 会在上一级目录，即 ~ 中， 为 ~/dotfiles/bash 中的所有文件创建软链接。 如果目标是文件夹，当对应文件夹存在时，GNU/Stow 会为文件夹下的所有文件创建软链接，否则直接创建该文件夹的软链接。

在执行具体命令前，可以使用 -nv 来检查将要执行的操作，而不执行这些操作。

使用 --delete 参数可以删除对应包的软链接。

更多的参数和用法详见官方文档。

管理编译安装程序

在 Linux 中，如果我们要手动安装一个程序，通常有两种做法：

• 将其安装到 /opt/xxx/ 中，并手动添加到环境目录。这可以是全局环境相对整洁，但需要手动设置大量的相关配置。
• 直接将其安装到 /usr/local/ 中。这种方法最直接，不需要进行任何额外配置，但在卸载程序时较为麻烦。

GNU/Stow 为我们提供了第三个选择。

这里以安装 hello 程序为例：

管理用户配置文件

Linux 下用户配置文件通常以 dotfiles 的形式来管理。 但不同软件的配置位置通常不太一样，难以统一地管理，这时就可以借助 GNU/Stow。

例如，下面是一个配置文件的示例：

这样就将配置文件全部集中到一个文件夹中，方便管理，之后可以使用 stow package 来加载对应的配置文件。

相关链接

• GNU/Stow 官网
• GNU/Stow 用户手册

在终端日常操作中，我们经常需要使用一些重复的特定操作，而且这些操作与项目绑定，不方便放在全局环境中。 例如，我在编辑博客时，就经常需要运行 vuepress dev docs 来实时预览，使用 vuepress build docs 来构建。

总是键入这些命令不仅繁琐，而且一些平时使用频率相对较少的命令也容易遗忘，just 就是这样一个简化在命令行中重复操作的工具。

介绍

just 是一个使用 rust 编写的，语法类似 make 的任务运行器。

很多人应该都用 make 来运行一些简单任务，但是 make 毕竟是一个构造系统，本身也具有一定的复杂性，例如需要指定 .PHONY。 just 避免了很多 make 的复杂性，更专注于任务管理。

与 make 类似，just 使用 justfile 来定义任务：

dev:
    pnpm run dev --open

deploy:
    @echo "Deploying to aliyun..."
    pnpm run build
    rsync -avz --delete -e ssh ./docs/.vuepress/dist aliyun:Page

    @echo "Deploying to github..."
    git push

lint:
    pnpm run lint

运行 just install 时，just 会在当前目录和父目录寻找文件寻找 justfile 并运行它。

此外，just 还具有以下 make 不具备的特性：

• 指定运行命令的 shell，甚至可以使用 python 解释器等
• 更友好的语法
• 每个配方使用独立的环境，互不干扰
• 接受命令行参数
• 用户友好的错误报告
• 加载 .env 环境变量文件

与 npm 脚本的比较

并非每个项目都具有 package.json，而且 npm 脚本的功能有限，只能运行一些简单的命令。

相关链接

• 官网
• Github 仓库

建议阅读 Just 用户指南了解更多细节。

本系列为 GoogleTest 官方文档的非官方中文翻译，在 AI 辅助下由人工雕琢完成。

GoogleTest 是当下 C++ 最流行的测试框架，但却缺少较好的中文学习资料。 译者对官方文档进行了翻译，希望能对要学习 GoogleTest 的中文用户有所帮助。

文章尽量保留了原文的结构，对于一些原文中含糊易引发歧义或存在错误的地方进行了注释与修正。 由于官方文档本身缺乏维护，加上译者水平有限，难免存在一些翻译不好或不容易理解的地方，望谅解。

如果存在疑问，或发现任何问题，可在文章下面留言，译者将及时回复。

文档架构

GoogleTest 是 Google 的 C++ 测试与模拟框架。 本用户指南包含以下内容：

• ：讲授如何使用 GoogleTest 编写简单的测试。推荐初学者首先阅读该指南。
• ：当你读完初学者指南，且希望更充分利用 GoogleTest 时，阅读该指南。
• ：描述了一些 GoogleTest 的代码示例。
• ：使用时遇到问题想要获得帮助？请查看这里。
• ：讲授如何创建并在测试中使用模拟对象。
• ：包含常见模拟用例的技巧和方法。
• ：匹配器、动作和不变量等的便捷索引。
• ：包含对一些特定 gMock 问题的解答。

• Googlemock Insights， 作者：ElectricRCAircraftGuy

在 CMake 中使用 pkg-config 的典型配置如下：

find_package(PkgConfig)
pkg_search_module(GTEST REQUIRED gtest_main)

add_executable(testapp)
target_sources(testapp PRIVATE samples/sample3_unittest.cc)
target_link_libraries(testapp PRIVATE ${GTEST_LDFLAGS})
target_compile_options(testapp PRIVATE ${GTEST_CFLAGS})

enable_testing()
add_test(first_and_only_test testapp)

建议优先使用 target_compile_options 与 _CFLAGS，而非 target_include_directories 与 INCLUDE_DIRS， 因为前者不仅包含 -I 标志（GoogleTest 可能需要特定宏来告知内部头文件是否启用线程支持）。 此外，编译阶段可能仍需 -pthread 参数，若拆分 pkg-config 的 Cflags 变量可能导致该标志丢失。 同理，推荐使用 _LDFLAGS 而非更常见的 _LIBRARIES，以避免丢失 -L 标志和 -pthread。

GoogleTest 提供了 pkg-config 配置文件，可用于确定编译和链接 GoogleTest（及 GoogleMock）所需的所有标志参数。 pkg-config 采用标准化的纯文本格式，包含以下关键信息：

• 包含目录路径（-I）
• 必要的宏定义（-D）
• 其他必需标志（-pthread）
• 库文件路径（-L）
• 待链接库名称（-l）

当前主流构建系统均支持 pkg-config。

本文所有示例均假设你需要编译 samples/sample3_unittest.cc 示例文件。

故障排除：pkg-config 找不到 GoogleTest

执行上述 CMakeLists.txt 文件时可能会遇到以下错误：

-- Checking for one of the modules 'gtest_main'
CMake Error at /usr/share/cmake/Modules/FindPkgConfig.cmake:640 (message):
  None of the required 'gtest_main' found

此错误常见于用户手动安装 GoogleTest 而非通过发行版包管理器安装的情况。 解决方法是配置 pkg-config 的 .pc 文件搜索路径。 假设 GoogleTest 安装于 /usr/local，则 .pc 文件可能位于 /usr/local/lib64/pkgconfig。 此时，应设置环境变量：

export PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig

pkg-config 将自动搜索 PKG_CONFIG_PATH 路径来定位 gtest_main.pc。

交叉编译环境配置

pkg-config 同样支持交叉编译场景。 假定目标系统的最终安装前缀为 /usr，sysroot 路径为 /home/MYUSER/sysroot。 用户可按以下步骤配置安装 GoogleTest：

mkdir build && cmake -DCMAKE_INSTALL_PREFIX=/usr ..

使用 DESTDIR 参数将其安装到 sysroot：

make -j install DESTDIR=/home/MYUSER/sysroot

在继续操作前，强烈建议在交叉编译环境中定义以下两个 pkg-config 变量：

export PKG_CONFIG_ALLOW_SYSTEM_CFLAGS=yes
export PKG_CONFIG_ALLOW_SYSTEM_LIBS=yes

否则 pkg-config 将自动过滤针对标准前缀（如 /usr）的 -I 和 -L 标志 （阅读 https://bugs.freedesktop.org/show_bug.cgi?id=28264#c3 了解该过滤的作用）。

观察按上述操作生成的 pkg-config 文件示例：

libdir=/usr/lib64
includedir=/usr/include

Name: gtest
Description: GoogleTest (without main() function)
Version: 1.11.0
URL: https://github.com/google/googletest
Libs: -L${libdir} -lgtest -lpthread
Cflags: -I${includedir} -DGTEST_HAS_PTHREAD=1 -lpthread

这里 sysroot 路径未被包含在 libdir 和 includedir 中！ 若使用 PKG_CONFIG_LIBDIR=/home/MYUSER/sysroot/usr/lib64/pkgconfig 执行 pkg-config，则：

$ pkg-config --cflags gtest
-DGTEST_HAS_PTHREAD=1 -lpthread -I/usr/include
$ pkg-config --libs gtest
-L/usr/lib64 -lgtest -lpthread

显然输出结果有误，其指向了 CBUILD 而非 CHOST 根路径。 为正确配置交叉编译，需告知 pkg-config 将实际 sysroot 路径注入至 -I 和 -L 参数：

export PKG_CONFIG_DIR=
export PKG_CONFIG_SYSROOT_DIR=/home/MYUSER/sysroot
export PKG_CONFIG_LIBDIR=${PKG_CONFIG_SYSROOT_DIR}/usr/lib64/pkgconfig

之后再执行 pkg-config 将获得正确结果：

$ pkg-config --cflags gtest
-DGTEST_HAS_PTHREAD=1 -lpthread -I/home/MYUSER/sysroot/usr/include
$ pkg-config --libs gtest
-L/home/MYUSER/sysroot/usr/lib64 -lgtest -lpthread

输出结果包含了正确的 sysroot 路径。 关于包含 ${CHOST} 参数的完整配置指南，请参考 Diego Elio Pettenò 的权威教程：https://autotools.io/pkgconfig/cross-compiling.html。

• 示例 1 演示使用 GoogleTest 测试 C++ 函数的基本步骤。
• 示例 2 演示对包含多个成员函数的类进行复杂单元测试。
• 示例 3 使用测试夹具。
• 示例 4 指导如何联合使用 googletest 与 googletest.h 实现最佳实践。
• 示例 5 在基类测试夹具中封装共享测试逻辑，并在派生夹具中复用。
• 示例 6 演示类型参数化测试。
• 示例 7 介绍值参数化测试的基础应用。
• 示例 8 展示值参数化测试中 Combine() 方法的使用。
• 示例 9 使用监听器 API 定制 GoogleTest 控制台输出，并利用反射 API 检查测试结果。
• 示例 10 通过监听器 API 实现简单内存泄漏检测器。

要使方法能够被模拟，该方法必须声明为虚函数，除非使用。

能否模拟可变参数函数？

gMock 无法直接模拟可变参数函数（即使用省略号（...）参数的函数）。

问题在于，模拟对象通常无法知道可变参数方法接收的参数数量及其类型。 只有基类作者了解参数协议，而我们不能揣测其实现意图。

因此，要模拟此类函数，用户需要自行指导模拟对象如何解析参数数量和类型。 一种实现方式是提供函数的重载版本。

省略号参数继承自 C 语言，并非真正的 C++ 特性。 这类参数存在安全隐患，且不适用于带有构造函数或析构函数的参数。 因此我们建议在 C++ 中尽量避免使用。

定义带有 const 参数的模拟方法时，MSVC 报 C4301 或 C4373 警告。这是为什么？

使用 Microsoft Visual C++ 2005 SP1 编译以下代码时：

class Foo {
  ...
  virtual void Bar(const int i) = 0;
};

class MockFoo : public Foo {
  ...
  MOCK_METHOD(void, Bar, (const int i), (override));
};

可能出现以下警告：

warning C4301: 'MockFoo::Bar': overriding virtual function only differs from 'Foo::Bar' by const/volatile qualifier

这是 MSVC 的 bug。 相同代码在 gcc 等编译器上可正常编译。 若使用 Visual C++ 2008 SP1 则会出现：

warning C4373: 'MockFoo::Bar': virtual function overrides 'Foo::Bar', previous versions of the compiler did not override when parameters only differed by const/volatile qualifiers

在 C++ 中，若声明函数参数为 const，该修饰符将被忽略。 因此上述 Foo 基类代码等效于：

class Foo {
  ...
  virtual void Bar(int i) = 0;  // int 或 const int 实际上没有区别
};

实际使用中，可以在声明 Bar() 时使用 int 参数，而定义时使用 const int 参数，编译器仍能正确匹配。

既然在方法声明中使用 const 修饰参数没有实际意义，我们建议在 Foo 和 MockFoo 中移除该修饰符。 这也可以绕过 VC 的编译器问题。

void Bar(int* p);        // p 和 *p 都非 const
void Bar(const int* p);  // p 不是 const，但 *p 是

如何排查 gMock 认为期望未满足的问题？

可在运行测试时添加 --gmock_verbose=info 参数。 该参数会输出 gMock 接收的所有模拟函数调用信息，通过分析这些信息可定位期望未满足的原因。

若出现提示信息 The mock function has no default action set, and its return type has no default value set.， 请尝试。 由于已知问题，没有默认动作的模拟函数在遇到意外调用时，不会打印实际参数与期望参数的详细对比。

程序崩溃时 ScopedMockLog 输出了大量信息。这是 gMock 的 bug 吗？

gMock 和 ScopedMockLog 在此情况下的行为是符合预期的。

当测试崩溃时，故障信号处理器会尝试记录大量信息（如堆栈跟踪和地址映射）。 若存在多个堆栈较深的线程，信息量会剧增。 当 ScopedMockLog 拦截到这些信息并发现其不匹配任何期望时，会打印每条信息的错误。

可以选择忽略这些错误，或者通过改进期望条件增强测试鲁棒性。 例如，添加：

using ::testing::AnyNumber;
using ::testing::Not;
...
  // 
  EXPECT_CALL(log, Log(_, Not(EndsWith("/my_file.cc")), _))
      .Times(AnyNumber());

如何断言某个函数从未被调用？

using ::testing::_;
...
  EXPECT_CALL(foo, Bar(_))
      .Times(0);

测试失败时 gMock 对同一期望报错了两次，这是否冗余？

当 gMock 检测到失败时，会输出相关信息（模拟函数参数、相关期望状态等）辅助调试。 若后续再次检测到失败，会重复输出相关信息，包括期望的状态。

虽然有时两次输出的期望状态描述相同，但这并非冗余，因为它们对应不同的时间节点。 相同的期望报错本身即是重要的调试信息。

使用模拟对象时出现堆检查错误，但使用真实对象则正常，可能是什么原因？

请检查被模拟的基类（应为纯接口类）是否声明了虚析构函数。

当继承基类时，必须确保其析构函数为虚函数，否则会导致严重问题。 参考以下代码：

class Base {
 public:
  // 非虚函数，但本应为虚函数
  ~Base() { ... }
  ...
};

class Derived : public Base {
 public:
  ...
 private:
  std::string value_;
};

...
  Base* p = new Derived;
  ...
  delete p;  // 此处仅调用 ~Base()，未调用 ~Derived()
             // value_ 发生泄露

将 ~Base() 改为虚函数后，执行 delete p 会正确调用 ~Derived()，堆检查即可通过。

"新期望覆盖旧期望"规则导致编写不便。为何如此设计？

开发者常抱怨如下场景：

using ::testing::Return;
...
  // 要求 foo.Bar() 被调用两次，首次返回 1，第二次返回 2
  // 但必须逆序编写期望，非常反直觉！
  EXPECT_CALL(foo, Bar())
      .WillOnce(Return(2))
      .RetiresOnSaturation();
  EXPECT_CALL(foo, Bar())
      .WillOnce(Return(1))
      .RetiresOnSaturation();

问题根源在于没有采用最佳方法表达测试意图。

默认情况下，期望的匹配顺序是任意的。 如需指定匹配顺序，必须显式声明。 这是 gMock（及 jMock）的核心设计哲学：用户易过度指定测试顺序导致测试脆弱，因此需增加实现难度。

推荐两种改进方式。 其一，使用顺序块：

using ::testing::Return;
...
  // 这里使用顺序块，实现自然顺序编写
  {
    InSequence s;
    EXPECT_CALL(foo, Bar())
        .WillOnce(Return(1))
        .RetiresOnSaturation();
    EXPECT_CALL(foo, Bar())
        .WillOnce(Return(2))
        .RetiresOnSaturation();
  }

其二，在同一期望中声明多个动作：

using ::testing::Return;
...
  EXPECT_CALL(foo, Bar())
      .WillOnce(Return(1))
      .WillOnce(Return(2))
      .RetiresOnSaturation();

设置 ON_CALL 但未设置 EXPECT_CALL 时，gMock 会警告。是否应抑制此类警告？

在简洁与安全之间，gMock 选择后者，因此保留警告输出是合理的设计。

在模拟对象构造函数或 SetUp() 中设置 ON_CALL 作为默认行为，而具体测试用例中通过 EXPECT_CALL 定义特殊预期是一种常见做法。 设置了 ON_CALL 并不表示预期调用，若未设置 EXPECT_CALL 却发生调用，可能意味着潜在错误。 静默放行此类调用易导致问题不被发现。

如果用户确信调用是合理的，可用以下方式：

using ::testing::_;
...
  EXPECT_CALL(foo, Bar(_))
      .WillRepeatedly(...);

而非：

using ::testing::_;
...
  ON_CALL(foo, Bar(_))
      .WillByDefault(...);

这会告知 gMock 该调用属于预期行为，不再触发警告。

用户也可以在调试时可通过 --gmock_verbose=error 调节输出级别（可选值包括 info 或 warning）。 若调试时日志信息过多，只需降低输出级别。

如何在动作中 delete 模拟函数参数？

若需 delete 模拟函数中的指针参数，可使用 testing::DeleteArg<N>()：

using ::testing::_;
  ...
  MOCK_METHOD(void, Bar, (X* x, const Y& y));
  ...
  EXPECT_CALL(mock_foo_, Bar(_, _))
      .WillOnce(testing::DeleteArg<0>()));

如何对模拟函数参数执行自定义操作？

如需执行 gMock 未直接支持的操作，可通过以下方式实现：

• 使用 或 定义自定义操作。
• 编写桩函数并通过 调用。

using ::testing::_;
using ::testing::Invoke;
  ...
  MOCK_METHOD(void, Bar, (X* p));
  ...
  EXPECT_CALL(mock_foo_, Bar(_))
      .WillOnce(Invoke(MyAction(...)));

能否模拟静态/全局函数？

技术上可行，但建议重构代码。

静态函数调用通常意味着模块耦合度过高，同时也意味着更低的灵活性、可复用性、可测试性等。 推荐用小型接口进行封装，通过接口实现模拟。 这需要一些额外的初始投入，但很快就能感受到其带来的好处。

可以参考这篇 Google Testing Blog 的博客。

模拟对象需要执行复杂操作时配置繁琐——gMock 很难用！

虽然这不是一个问题，但我们仍将给出解答。😃

使用 gMock 可以轻松创建 C++ 模拟对象。 开发者可能倾向于随处使用它们。 某些场景下它们效果良好，但有时你可能会觉得使用体验欠佳。 那么问题出在哪里？

当你编写不使用模拟的测试时，会执行代码并断言其返回正确值或系统处于预期状态。 这种测试方式被称为“基于状态的测试”。

模拟对象在“基于交互的测试”中表现卓越： 不同于最终检查系统状态的方式，模拟对象会验证其是否被正确调用，并在问题出现时立即报错，使你能精准定位错误发生的上下文环境。 相较于基于状态的测试，这种方式通常更高效、更经济。

若你正在进行基于状态的测试，且仅使用测试替身来模拟真实对象，则更适合使用伪对象（fake）。 此时使用模拟对象会导致不便，因为执行复杂操作并非模拟对象的强项。 如果你遇到此类问题，并因此认为模拟对象难用，说明你可能选错了工具，或者试图解决错误的问题。

出现 Uninteresting function call encountered - default action taken.. 警告时，需要担忧吗？

完全不需要！这只是提示信息。😃

该警告表示：你定义的模拟函数未被设置任何期望 （根据 gMock 规则，这意味着你不关注此函数的调用，因此可被任意次数调用）， 但该函数确实被调用了。 这完全正常——你从未声明禁止调用此函数！

但如果你实际意图是禁止调用该函数，却忘记编写 EXPECT_CALL(foo, Bar()).Times(0)，该怎么办？ 虽然这可以归咎于用户的失误，但 gMock 仍会友好地输出提示信息。

因此，当你看到此消息并确信不应存在未关注的调用时，应当调查具体原因。 为便于调试，gMock 会在遇到无趣调用时输出堆栈跟踪信息。 通过该信息，可以定位具体的模拟函数及其调用方式。

定义自定义动作时，应该使用 Invoke() 还是实现 ActionInterface 接口？

两种方式均可，用户应根据具体场景选择最便捷的方式。

通常，若动作针对特定函数类型，使用 Invoke() 定义更简便。 若动作需适用于多种函数类型（例如 Return(value)），则使用 MakePolymorphicAction() 最合适。 当需要精确控制动作适用的函数类型时，实现 ActionInterface 接口是最佳选择。 具体示例可参考 gmock-actions.h 中 Return() 的实现。

在 WillOnce() 中使用 SetArgPointee() 时，gcc 报错 conflicting return type specified。这是什么意思？

此错误源于 gMock 无法确定模拟方法调用时应返回的值。 SetArgPointee() 仅设置副作用，未指定返回值。 你需要使用 DoAll() 来组合 SetArgPointee() 与提供适当返回值的 Return()。

更多细节和示例详见。

大型模拟类导致 Microsoft Visual C++ 编译时内存不足，如何解决？

我们注意到当使用 /clr 编译选项时，Visual C++ 会消耗 5~6 倍内存来编译模拟类。 建议在编译 C++ 模拟对象时避免使用 /clr 选项。

下划线（_）具有特殊性，因为 C++ 保留以下情况供编译器和标准库使用：

1. 任何以 _ 开头后跟大写字母的标识符
2. 任何名称中包含连续两个下划线（即 __）的标识符

用户代码被严格禁止使用此类标识符。

现在让我们看看这对 TEST 和 TEST_F 意味着什么。

目前 TEST(TestSuiteName, TestName) 会生成名为 TestSuiteName_TestName_Test 的类。 如果 TestSuiteName 或 TestName 包含 _ 会发生什么？

1. 如果 TestSuiteName 以 _ 开头后跟大写字母（例如 _Foo），将生成 _Foo_TestName_Test。
2. 如果 TestSuiteName 以 _ 结尾（例如 Foo_），将生成 Foo__TestName_Test。
3. 如果 TestName 以 _ 开头（例如 _Bar），将生成 TestSuiteName__Bar_Test。
4. 如果 TestName 以 _ 结尾（例如 Bar_），将生成 TestSuiteName_Bar__Test。

这些都是保留标识符，不能使用。

因此显然 TestSuiteName 和 TestName 不能以 _ 开头或结尾 （实际上，只要 _ 后不跟大写字母，TestSuiteName 就可以以 _ 开头。 但这样会使规则复杂化。 为简单起见，我们统一规定不能以 _ 开头）。

看起来在名称中间使用 _ 没有问题。 但考虑以下情况：

TEST(Time, Flies_Like_An_Arrow) { ... }
TEST(Time_Flies, Like_An_Arrow) { ... }

这两个 TEST 宏会生成相同的类名（Time_Flies_Like_An_Arrow_Test），从而产生问题。

因此，为简化规则，我们要求用户在 TestSuiteName 和 TestName 中完全避免使用 _。 虽然该规则比实际需求更严格，但简单易记。 这也为 GoogleTest 未来的实现变化留有余地。

如果违反此规则，可能不会立即出现问题， 但使用新编译器（或新版本编译器）或新版本 GoogleTest 时，测试可能会崩溃。 因此最好遵守此规则。

为什么 GoogleTest 支持 EXPECT_EQ(NULL, ptr) 和 ASSERT_EQ(NULL, ptr)，但不支持 EXPECT_NE(NULL, ptr) 和 ASSERT_NE(NULL, ptr)？

首先，你可以使用 nullptr 来配合这些宏， 例如 EXPECT_EQ(ptr, nullptr)、EXPECT_NE(ptr, nullptr)、ASSERT_EQ(ptr, nullptr)、ASSERT_NE(ptr, nullptr)。 这是风格指南推荐的方式，因为 nullptr 没有 NULL 的类型问题。

由于 C++ 的特殊性，支持在 EXPECT_XX() 和 ASSERT_XX() 宏中使用 NULL 需要复杂的模板元编程技巧。 因此我们只在最需要的地方实现它（否则会使 GoogleTest 的实现更难维护且更易出错）。

历史上，EXPECT_EQ() 宏曾将预期值作为第一个参数，实际值作为第二个参数，不过现在不鼓励这种参数顺序。 用户确实需要编写 EXPECT_EQ(NULL, some_expression) 的需求是合理的，也确实被多次提出，因此我们实现了它。

对 EXPECT_NE(NULL, ptr) 的需求并不强烈。 当断言失败时，ptr 必为 NULL，因此打印 ptr 的值不会提供额外信息。 这意味着，EXPECT_TRUE(ptr != NULL) 同样有效。

如果支持 EXPECT_NE(NULL, ptr)，为了保持一致性也需要支持 EXPECT_NE(ptr, NULL)。 这将使实现中的模板元编程技巧使用次数翻倍，显著增加理解和维护难度。 我们认为收益不值得付出这样的成本。

最后，随着 gMock 匹配器库的发展，我们鼓励用户更多使用统一的 EXPECT_THAT(value, matcher) 语法。 匹配器方法的重要优势是可以轻松组合新匹配器，而 EXPECT_NE 等宏无法轻松组合。 因此我们更倾向于在匹配器上投入精力。

我需要测试接口的不同实现是否满足共同要求，应该使用类型化测试还是值参数化测试？

要验证同一接口的不同实现是否满足共同要求，类型化测试和值参数化测试均可适用。 具体选择取决于实际场景：

• 若不同实现实例的创建方式仅类型不同则类型化测试更易编写。例如：

  • 所有实现都具有公有默认构造函数（可使用 new TypeParam）。
  • 工厂函数形式统一（如 CreateInstance<TypeParam>()）。

• 若不同实现实例需要不同的创建模式则值参数化测试更适用。 例如：new Foo vs new Bar(5)。 要消除这种差异，可以编写工厂函数包装器，并将函数指针作为参数传递给测试。

• 调试信息差异：

  • 类型化测试失败时会默认输出类型名称，便于快速定位问题实现。
  • 值参数化测试默认仅显示失败迭代的编号。 用户需通过定义迭代名称函数，作为第三个参数传递给 INSTANTIATE_TEST_SUITE_P 来加强输出信息。

• 使用类型化测试时，需确保测试是针对接口类型而非具体实现类型 （即需验证 implicit_cast<MyInterface*>(my_concrete_impl) 有效，而不仅是 my_concrete_impl 有效）。 值参数化测试在此方面更不易出错。

建议实践两种方法以深入理解其细微差异，通过实际体验更易做出合适选择。

死亡测试中的状态修改为何在测试结束后丢失？

死亡测试（EXPECT_DEATH 等）在子进程中执行，以确保预期的崩溃不会终止主测试进程。 因此，任何内存副作用仅存在于子进程中，主进程无法观测子进程状态变化。 可以将死亡测试视为在"平行宇宙"中运行。

特别指出，若在死亡测试调用模拟方法，主进程会认为调用从未发生。 因此，可能需要将 EXPECT_CALL 语句移动到 EXPECT_DEATH 内部。

在优化模式下使用 EXPECT_EQ(htonl(blah), blah_blah) 为何报编译错误？

该问题源于 htonl() 的实现缺陷：

根据 'man htonl' 文档，htonl() 本应作为函数存在，因此可被用作函数指针。 但在优化模式下，htonl() 被定义为宏，这违反了规范要求。

更严重的是，htonl() 的宏实现使用了 gcc 扩展语法，不符合标准 C++ 规范。 这种非标准实现存在特定限制， 例如无法在模板参数中使用 Foo<sizeof(htonl(x))> 这样的表达式（其中 Foo 是接受整型参数的模板）。

EXPECT_EQ(a, b) 的实现会在模板参数中使用 sizeof(... a ...)。 因此，当参数 a 包含 htonl() 调用时，在优化模式下将无法通过编译。 由于需要兼容不同编译器和平台，很难让 EXPECT_EQ 绕过这个 htonl() 的缺陷。

编译器报 undefined references 错误，但我已在类内定义相应的静态常量成员变量。问题出在哪里？

当类包含静态数据成员时：

class Foo {
  ...
  static const int kBar = 100;
};

仍需在 foo.cc 文件中进行外部定义：

const int Foo::kBar; // 此处不需要初始化

否则将产生无效的 C++ 代码，可能导致意外错误。 特别是在 GoogleTest 的断言宏（如 EXPECT_EQ）中使用时，会引发 undefined reference 链接错误。 之前能运行并不意味着代码正确，只是侥幸成功。

若使用 constexpr 声明静态成员，则会隐式生成 inline 定义，此时无需在 foo.cc 中重复定义：

class Foo {
  ...
  static constexpr int kBar = 100;  // 直接定义 kBar，无需在 foo.cc 中重复
};

能否让测试夹具继承另一个夹具？

可以。

每个测试夹具对应唯一的一个同名测试套件，这意味着一个测试夹具只有一个测试套件可以使用。 但有时多个测试用例需要共享相似的夹具逻辑。 例如，确保 GUI 库的所有测试套件都不会泄漏字体、画笔等系统资源。

在 GoogleTest 中，可将共享逻辑放在基类夹具，然后为每个测试套件派生子类夹具。 使用 TEST_F() 编写基于派生夹具的测试。

典型实现如下：

// 定义基类测试夹具
class BaseTest : public ::testing::Test {
 protected:
  ...
};

// 从 BaseTest 派生 FooTest 夹具
class FooTest : public BaseTest {
 protected:
  void SetUp() override {
    BaseTest::SetUp();  // 先初始化基类夹具
    // ... 扩展初始化逻辑 ...
  }

  void TearDown() override {
    // ... FooTest 的清理逻辑 ...
    BaseTest::TearDown();  // 最后清理基类夹具
  }

  // ... FooTest 的成员函数和变量 ...
};

// 使用 FooTest 夹具的测试用例
TEST_F(FooTest, Bar) { ... }
TEST_F(FooTest, Baz) { ... }

// ... 其他从 BaseTest 派生的夹具 ...

如有需要，可继续继承派生夹具。 GoogleTest 对继承层次深度没有限制。

完整示例参见 sample5_unittest.cc。

编译器报 void value not ignored as it ought to be 是什么意思？

此错误通常意味着您在非 void 函数中使用了 ASSERT_*() 断言。 由于 Google 的构建系统禁用了异常机制，ASSERT_*() 系列断言仅可在返回类型为 void 的函数中使用。 更多技术细节请参阅。

死亡测试卡死（或段错误）如何修复？

GoogleTest 的死亡测试在子进程中运行，其工作机制较为特殊。 编写死亡测试前必须理解其工作原理——详见断言参考中的章节。

特别要注意，死亡测试无法兼容父进程中存在多线程的情况。 首要解决方法是消除在 EXPECT_DEATH() 外部创建线程的行为，例如在测试中使用模拟对象替代真实对象。

有时这种情况不可避免，例如必须使用的某些库在 main() 函数执行前就创建线程时。 这时可通过两种方式降低冲突概率： 尽可能将更多操作移至 EXPECT_DEATH() 内部（极端情况下需移入全部操作），或尽量减少其外部依赖。 此外，可将死亡测试风格设为 "threadsafe"，这更安全但更慢。

若使用 "threadsafe" 死亡测试，需注意其会在子进程中从头重新运行测试程序。 因此必须确保程序能并行执行自身副本且具有确定性行为。

本质上，这属于并发编程的范畴。 用户必须确保程序中不存在竞态条件或死锁。 很遗憾，此问题没有通用解决方案！

我应该使用测试夹具的构造函数/析构函数还是 SetUp()/TearDown()？

首先需要明确：GoogleTest 不会在多个测试之间复用同一个测试夹具对象。 对于每个 TEST_F 测试用例，GoogleTest 都会创建一个全新的测试夹具对象， 调用 SetUp() 方法，运行测试主体，调用 TearDown() 方法，然后删除该测试夹具对象。

当需要编写每个测试专用的设置和清理逻辑时， 可以选择使用测试夹具的构造函数/析构函数或 SetUp()/TearDown() 方法。 通常推荐使用前者，因为它具有以下优势：

• 通过在构造函数中初始化成员变量，可以将其声明为 const 类型， 这有助于防止意外修改其值，使测试逻辑更加明确可靠。
• 当需要派生测试夹具类时，子类构造函数会首先调用基类构造函数，子类析构函数会最后调用基类析构函数。 若使用 SetUp()/TearDown() 方法，子类可能忘记调用基类的对应方法或在错误时机调用。

不过，在以下场景中，则建议使用 SetUp()/TearDown()：

• C++ 不允许在构造函数和析构函数中调用虚函数。 虽然可以调用声明为 virtual 的方法，但不会使用动态派发机制，而是使用当前执行构造函数所属类中的定义。 这是因为，在派生类构造函数执行前调用虚函数可能操作未初始化数据，存在风险。 因此，若需要调用会被派生类重写的方法，必须使用 SetUp()/ TearDown() 。
• 在构造函数（或析构函数）体内无法使用 ASSERT_xx 断言宏。 如果设置操作可能导致需要中止当前测试的致命错误，必须使用 abort 终止整个测试程序， 或改用 SetUp() 替代构造函数。
• 如果清理操作可能抛出异常，必须使用 TearDown() 而非析构函数， 因为在析构函数中抛出异常会导致未定义行为（通常直接终止程序）。 注意，当编译器启用异常时，许多标准库（如 STL）都可能抛出异常。 因此，若需要编写兼容异常启用/禁用环境的可移植测试代码，应优先选择 TearDown() 。
• GoogleTest 团队正考虑在启用异常的平台上（如 Windows、Mac OS 和 Linux 客户端），将断言宏改为抛出异常。 这将消除用户需要手动将子程序错误传递到调用方的需求。 因此，如果代码可能运行在此类平台，不应在析构函数中使用 GoogleTest 断言。

使用 ASSERT_PRED* 时编译器报错 no matching function to call，如何解决？

请查阅断言参考中的 一节。

调用 RUN_ALL_TESTS() 时编译器警告 ignoring return value，原因为何？

有些开发者会忽略 RUN_ALL_TESTS() 的返回值，即不写：

return RUN_ALL_TESTS();

而是写成：

RUN_ALL_TESTS();

这是错误且危险的。 测试框架需要通过检查 RUN_ALL_TESTS() 的返回值来判断测试是否通过。 如果 main() 函数忽略该返回值，即使存在 GoogleTest 断言失败，测试仍会被判定为成功。

我们已决定修复此问题（感谢 Michael Chastain 的建议）。 现在，使用 gcc 编译时，代码将无法忽略 RUN_ALL_TESTS() 的返回值。 如果忽略，会导致编译错误。

如果编译器提示 ignoring return value，解决方法很简单：确保将其返回值作为 main() 函数的返回结果。

但这种改动是否会破坏现有测试？ 事实上，此类代码原本就是错误的，因此我们并没有破坏现有有效代码。😃

编译器提示构造函数（或析构函数）不能返回值，这是怎么回事？

由于 C++ 的语法限制，为了支持向 ASSERT_* 断言流式传输消息的语法，例如：

ASSERT_EQ(1, Foo()) << "blah blah" << foo;

我们不得不禁止在构造函数和析构函数中使用 ASSERT* 和 FAIL* 系列宏（但 EXPECT* 和 ADD_FAILURE* 仍可用）。 解决方法是将构造函数/析构函数中的相关内容移至私有 void 成员函数中，或改用 EXPECT_*() 断言。 用户指南中的中对此有详细解释。

SetUp() 函数未被调用，原因为何？

C++ 语言大小写敏感。 请检查是否误写为 Setup()？

类似地，有时开发者会将 SetUpTestSuite() 误拼为 SetupTestSuite()，导致该方法未被调用。

多个测试套件共享相同的测试夹具逻辑时，必须为每个套件定义新的夹具类吗？这样似乎太繁琐了

不需要重复定义。 你可以使用类型别名替代继承。

原始写法：

class FooTest : public BaseTest {};

TEST_F(FooTest, Abc) { ... }
TEST_F(FooTest, Def) { ... }

class BarTest : public BaseTest {};

TEST_F(BarTest, Abc) { ... }
TEST_F(BarTest, Def) { ... }

优化写法（使用 typedef）：

typedef BaseTest FooTest;

TEST_F(FooTest, Abc) { ... }
TEST_F(FooTest, Def) { ... }

typedef BaseTest BarTest;

TEST_F(BarTest, Abc) { ... }
TEST_F(BarTest, Def) { ... }

GoogleTest 输出被大量 LOG 消息淹没，如何解决？

GoogleTest 的输出设计被为简洁易读的测试报告。 若测试代码自身产生文本输出，会与框架输出混杂影响可读性。

由于 LOG 消息输出到 stderr，而 GoogleTest 的输出默认送往 stdout，可通过重定向分离两者：

./my_test > gtest_output.txt

为什么应该优先使用测试夹具而非全局变量？

有以下原因：

1. 测试修改全局变量状态，易导致副作用溢出进而影响其他测试，增加调试难度。 使用夹具可为每个测试提供独立变量集（同名但不同实例），确保测试的隔离性。
2. 全局变量会污染全局命名空间。
3. 测试夹具可通过子类化复用，而全局变量难以实现此特性。 这在多个测试套件存在共性时特别有用。

ASSERT_DEATH() 中的 statement 参数可以是哪些形式？

ASSERT_DEATH(statement, matcher)（及所有死亡断言宏）可对任何有效 statement 使用。 statement 可以是当前上下文中任意有效的 C++ 语句。 它可以引用全局或局部变量，可以是：

• 简单的函数调用（常见形式）
• 复杂表达式
• 复合语句

示例如下：

// 简单的函数调用
TEST(MyDeathTest, FunctionCall) {
  ASSERT_DEATH(Xyz(5), "Xyz failed");
}

// 引用变量和函数的复杂表达式
TEST(MyDeathTest, ComplexExpression) {
  const bool c = Condition();
  ASSERT_DEATH((c ? Func1(0) : object2.Method("test")),
               "(Func1|Method) failed");
}

// 死亡断言可在函数内任意位置使用（包括循环内部）
TEST(MyDeathTest, InsideLoop) {
  // 验证 Foo(0) 到 Foo(4) 均会崩溃
  // Verifies that Foo(0), Foo(1), ..., and Foo(4) all die.
  for (int i = 0; i < 5; i++) {
    EXPECT_DEATH_M(Foo(i), "Foo has \\d+ errors",
                   ::testing::Message() << "where i is " << i);
  }
}

// 死亡断言可包含复合语句
TEST(MyDeathTest, CompoundStatement) {
  // 验证 Bar(0) 到 Bar(4) 至少有一个崩溃
  ASSERT_DEATH({
    for (int i = 0; i < 5; i++) {
      Bar(i);
    }
  },
  "Bar has \\d+ errors");
}

我定义了测试夹具类 FooTest，但 TEST_F(FooTest, Bar) 依旧报错 no matching function for call to FooTest::FooTest()，这是为什么？

GoogleTest 需要能够创建测试夹具类的对象，因此该类必须包含默认构造函数。 通常编译器会自动生成默认构造函数，但在以下情况需要手动定义：

• 如果为 FooTest 显式声明了非默认构造函数（例如使用 DISALLOW_EVIL_CONSTRUCTORS() 宏）， 则必须定义默认构造函数，即使为空实现。
• 如果 FooTest 包含 const 修饰的非静态数据成员， 则必须定义默认构造函数，并在构造函数的初始化列表中初始化该成员。 （早期 gcc 版本存在不强制要求初始化 const 成员的缺陷，该问题已在 gcc 4 中修复。）

为什么使用 ASSERT_DEATH 时 GoogleTest 要求将整个测试套件（而非单个测试）命名为 *DeathTest？

GoogleTest 不会交错运行不同测试套件中的测试。 也就是说，它会先运行完某个测试套件中的所有测试，在接着运行另一个测试套件中的所有测试，依此类推。 这样因为 GoogleTest 需要在首个测试运行前完成测试套件初始化，并在最后测试完成后执行清理工作。 如果拆分测试套件，会导致多次重复的初始化和清理操作，既降低效率又破坏语义清晰度。

如果允许测试名称为 *DeathTest，以下场景会产生矛盾：

TEST_F(FooTest, AbcDeathTest) { ... }
TEST_F(FooTest, Uvw) { ... }

TEST_F(BarTest, DefDeathTest) { ... }
TEST_F(BarTest, Xyz) { ... }

由于需要保证 FooTest.AbcDeathTest 在 BarTest.Xyz 之前运行，同时不同测试套件不交叉执行， 就必须先执行完整套件 FooTest 再执行 BarTest 。 这与 BarTest.DefDeathTest 需要在 FooTest.Uvw 之前运行的要求冲突。

我的测试套件同时包含死亡测试与普通测试，但我不想使用 *DeathTest 来命名整个套件，该怎么做？

可以使用类型别名将测试套件拆分为 FooTest 和 FooDeathTest：

class FooTest : public ::testing::Test { ... };

TEST_F(FooTest, Abc) { ... }
TEST_F(FooTest, Def) { ... }

using FooDeathTest = FooTest;

TEST_F(FooDeathTest, Uvw) { ... EXPECT_DEATH(...) ... }
TEST_F(FooDeathTest, Xyz) { ... ASSERT_DEATH(...) ... }

GoogleTest 只会在死亡测试失败时打印子进程的日志信息，如何在测试成功时查看日志？

打印 EXPECT_DEATH() 中语句的日志信息会影响主进程的日志可读性， 因此 GoogleTest 只会在死亡测试失败时打印这些信息。

如需查看成功时的日志，可以尝试临时破坏死亡测试（例如，改变某个正则匹配要求）。 这确实有点不方便。 我们可能会在完成 fork-and-exec 风格死亡测试后提供一个永久解决方案。

使用断言时编译器报错 no match for 'operator<<'，如何解决？

当在断言中使用自定义类型 FooType 时，必须确保实现对应的流输出运算符，否则无法打印该类型：

std::ostream& operator<<(std::ostream&, const FooType&)

此外，该 << 运算符必须定义在与 FooType 相应的命名空间中。 详见 Tip of the Week #49。

如何屏蔽 Windows 平台的内存泄漏警告？

由于静态初始化的 GoogleTest 单例对象需要申请堆内存， Visual C++ 内存检测器会在程序结束时报告内存泄漏。 最简单的解决方法是使用 _CrtMemCheckpoint 和 _CrtMemDumpAllObjectsSince 来抑制所有静态初始化的堆内存对象的报告。 更多细节与堆检测/调试例程说明详见 MSDN 文档。

如何让代码检测是否运行在测试环境中？

若你编写代码来嗅探是否处于测试环境并据此执行不同操作， 相当于将测试专用逻辑泄漏到生产代码中，且无法保证测试专用逻辑不会意外在生产环境中运行。 这种“聪明”的做法还会导致海森堡缺陷。 因此我们强烈反对这种做法，GoogleTest 也不提供相关支持。

通常，推荐使用依赖注入来实现不同环境下的差异化行为。 你可以为测试代码和生产代码分别注入不同功能。 由于生产代码完全不会链接测试逻辑（BUILD 目标的 testonly 属性可确保这点），因此不会存在误执行风险。

不过，如果你确实别无选择，且遵循了测试程序名以 _test 结尾的命名规范， 则可以使用检测可执行文件名（main() 中的 argv[0]）这种极不推荐的黑客方法来判断代码是否处于测试环境。

如何临时禁用某个测试？

对于无法立即修复的故障测试，可在测试名前添加 DISABLED_ 前缀。 这将禁用测试的执行。 此方法优于注释代码或使用 #if 0，因为被禁用的测试仍会参与编译（避免代码腐化）。

要执行被禁用的测试，只需在运行测试程序时添加 --gtest_also_run_disabled_tests 标志。

是否允许在不同命名空间中定义同名 TEST(Foo, Bar) 测试？

允许。

核心原则是：同一测试套件中的所有测试必须使用相同的夹具类。 以下示例允许存在，因为两个测试都使用相同的夹具类（::testing::Test）：

namespace foo {
TEST(CoolTest, DoSomething) {
  SUCCEED();
}
}  // namespace foo

namespace bar {
TEST(CoolTest, DoSomething) {
  SUCCEED();
}
}  // namespace bar

但以下代码不被允许，这将导致 GoogleTest 运行时错误，因为测试位于相同测试套件但使用了不同的夹具类：

namespace foo {
class CoolTest : public ::testing::Test {};  // Fixture foo::CoolTest
TEST_F(CoolTest, DoSomething) {
  SUCCEED();
}
}  // namespace foo

namespace bar {
class CoolTest : public ::testing::Test {};  // Fixture: bar::CoolTest
TEST_F(CoolTest, DoSomething) {
  SUCCEED();
}
}  // namespace bar

返回值类

| 动作 | 描述 | | :

| 宏 | 描述 | | :

大多数宏以 EXPECT_ 和 ASSERT_ 两种形式存在：

• EXPECT_ 宏在失败时生成非致命错误，允许当前函数继续执行。
• ASSERT_ 宏在失败时生成致命错误，终止当前函数。

所有断言宏都支持通过 << 运算符流式传输自定义错误信息，例如：

EXPECT_TRUE(my_condition) << "My condition is not true";

流式传输支持所有可输出到 ostream 的类型（特别是 C 风格字符串和 string 对象）。 若流式传输宽字符串（wchar_t*、Windows 在 Unicode 模式下的 TCHAR* 或 std::wstring）， 输出时将自动转换成 UTF-8 编码。

显式成功与失败

本节的断言将直接生成成功或失败，而不是测试值或表达式。 这些在使用控制流（而非布尔表达式）决定测试成功或失败时非常有用，如下例所示：

switch(expression) {
  case 1:
    // ... 一些检查项 ...
  case 2:
    // ... 另一些检查项 ...
  default:
    FAIL() << "We shouldn't get here.";
}

SUCCEED

SUCCEED()

生成成功。 这不会使整个测试成功，要使测试成功需要所有断言通过。

目前，SUCCEED 断言仅作为文档说明，不会产生可见输出。 未来版本可能会为它添加输出信息。

FAIL

FAIL()

生成致命失败，并从当前函数返回。

仅限在返回类型为 void 的函数中使用。 详见。

ADD_FAILURE

ADD_FAILURE()

生成非致命失败，这允许当前函数继续运行。

ADD_FAILURE_AT

ADD_FAILURE_AT(file_path, line_number)

在指定文件和行号位置生成非致命失败。

泛用断言

本节的断言允许使用来验证值。

EXPECT_THAT

EXPECT_THAT(value, matcher)
ASSERT_THAT(value, matcher)

验证值 value 满足 matcher 的条件。

例如，下面的代码验证了字符串 value1 以 "Hello" 开头， value2 匹配给定正则表达式，且 value3 位于 5 和 10 之间：

#include <gmock/gmock.h>

using ::testing::AllOf;
using ::testing::Gt;
using ::testing::Lt;
using ::testing::MatchesRegex;
using ::testing::StartsWith;

...
EXPECT_THAT(value1, StartsWith("Hello"));
EXPECT_THAT(value2, MatchesRegex("Line \\d+"));
ASSERT_THAT(value3, AllOf(Gt(5), Lt(10)));

匹配器形式的断言具有更好的可读性，且能生成易读的错误信息。 例如，如果上述对 value1 的断言失败，会产生类似下面的错误信息：

Value of: value1
  Actual: "Hi, world!"
Expected: starts with "Hello"

GoogleTest 提供了内置匹配器库（见）， 同时也支持用户自定义匹配器（见）。 与匹配器配合，使得 EXPECT_THAT 功能强大且扩展性强。

布尔条件

本节的断言用于验证布尔条件。

EXPECT_TRUE

EXPECT_TRUE(condition)
ASSERT_TRUE(condition)

验证 condition 为真。

EXPECT_FALSE

EXPECT_FALSE(condition)
ASSERT_FALSE(condition)

验证 condition 为假。

二元比较

本节的断言用于比较两个值。 值参数必须支持断言对应的比较运算符，否则会导致编译错误。

若参数支持 << 运算符，当断言失败时将调用该运算符以输出参数值。 否则，GoogleTest 会自动选择最佳的输出方式， 见。

参数只会被计算一次，因此允许存在副作用。 不过，参数的求值顺序未定义，程序不应依赖特定的求值顺序。

断言同时支持窄、宽字符串（string 和 wstring）。

要避免浮点数比较时的精度问题，请参阅浮点数比较。

EXPECT_EQ

EXPECT_EQ(val1, val2)
ASSERT_EQ(val1, val2)

验证 val1 == val2。

在比较指针时会比较其地址。 对于 C 字符串，会验证其具有相同地址，而不是相同值。 若要验证 C 字符串的值相等，请使用 EXPECT_STREQ。

若要验证指针为空，请使用 EXPECT_EQ(ptr, nullptr) 而非 EXPECT_EQ(ptr, NULL)。

EXPECT_NE

EXPECT_NE(val1, val2)
ASSERT_NE(val1, val2)

验证 val1 != val2。

在比较指针时会比较其地址。 对于 C 字符串，会验证其具有不同地址，而不是不同值。 若要验证 C 字符串的值不相等，请使用 EXPECT_STRNE。

若要验证指针非空，请使用 EXPECT_NE(ptr, nullptr) 而非 EXPECT_NE(ptr, NULL)。

EXPECT_LT

EXPECT_LT(val1, val2)
ASSERT_LT(val1, val2)

验证 val1 < val2。

EXPECT_LE

EXPECT_LE(val1, val2)
ASSERT_LE(val1, val2)

验证 val1 <= val2。

EXPECT_GT

EXPECT_GT(val1, val2)
ASSERT_GT(val1, val2)

验证 val1 > val2。

EXPECT_GE

EXPECT_GE(val1, val2)
ASSERT_GE(val1, val2)

验证 val1 >= val2。

字符串比较

本节的断言用于比较两个 C 字符串。 要比较 string，请使用 EXPECT_EQ 或 EXPECT_NE。

断言也支持宽字符串（wchar_t*），在失败时将输出 UTF-8 编码结果。

若要比较 C 字符串与 NULL，请使用 EXPECT_EQ(c_string, nullptr) 或 EXPECT_NE(c_string, nullptr)。

EXPECT_STREQ

EXPECT_STREQ(str1, str2)
ASSERT_STREQ(str1, str2)

验证两 C 字符串 str1 与 str2 内容相同。

EXPECT_STRNE

EXPECT_STRNE(str1, str2)
ASSERT_STRNE(str1, str2)

验证两 C 字符串 str1 与 str2 内容不同。

EXPECT_STRCASEEQ

EXPECT_STRCASEEQ(str1, str2)
ASSERT_STRCASEEQ(str1, str2)

验证两 C 字符串 str1 与 str2 内容相同（忽略大小写）。

EXPECT_STRCASENE

EXPECT_STRCASENE(str1, str2)
ASSERT_STRCASENE(str1, str2)

验证两 C 字符串 str1 与 str2 内容不同（忽略大小写）。

浮点数比较

本节的断言用于比较两个浮点数。

由于存在舍入误差，浮点数无法精确比较，因此不适用 EXPECT_EQ。 通常，要对浮点数进行有意义的比较，需要谨慎选择合适的误差边界（error bound）。

GoogleTest 还提供了基于最小精度单位（Unit in the Last Place，ULP）设置默认误差边界的断言。 要了解更多关于 ULP 的信息，请参阅文章 Comparing Floating Point Numbers。

EXPECT_FLOAT_EQ

EXPECT_FLOAT_EQ(val1, val2)
ASSERT_FLOAT_EQ(val1, val2)

验证两个 FLOAT 值 val1 和 val2 近似相等，彼此相差不超过 4 个 ULP。 无穷大与最大有限浮点数值视为相差 1 个 ULP。

EXPECT_DOUBLE_EQ

EXPECT_DOUBLE_EQ(val1, val2)
ASSERT_DOUBLE_EQ(val1, val2)

验证两个 double 值 val1 和 val2 近似相等，彼此相差不超过 4 个 ULP。 无穷大与最大有限双精度浮点数值视为相差 1 个 ULP。

EXPECT_NEAR

EXPECT_NEAR(val1, val2, abs_error)
ASSERT_NEAR(val1, val2, abs_error)

验证 val1 和 val2 的差值不超过绝对误差限 abs_error。

若 val1 和 val2 为符号相同的无穷大，则差值视为 0。 否则，若任一值为无穷大，则差值视为无穷大。 所有非 NaN 值（包括无穷大）都不会超过无穷大的 abs_error。

异常断言

本节的断言用于验证代码段抛出（或不抛出）异常。 使用时需保证构建环境启用了异常机制。

EXPECT_NO_THROW({
  int n = 5;
  DoSomething(&n);
});

EXPECT_THROW

EXPECT_THROW(statement, exception_type)
ASSERT_THROW(statement, exception_type)

验证 statement 抛出类型为 exception_type 的异常。

EXPECT_ANY_THROW

EXPECT_ANY_THROW(statement)
ASSERT_ANY_THROW(statement)

验证 statement 抛出任意类型的异常。

EXPECT_NO_THROW

EXPECT_NO_THROW(statement)
ASSERT_NO_THROW(statement)

验证 statement 不抛出任何异常。

谓词断言

本节的断言用于验证复杂谓词，相比单独使用 EXPECT_TRUE 能提供更清晰的错误信息。

EXPECT_PRED*

EXPECT_PRED1(pred, val1)
EXPECT_PRED2(pred, val1, val2)
EXPECT_PRED3(pred, val1, val2, val3)
EXPECT_PRED4(pred, val1, val2, val3, val4)
EXPECT_PRED5(pred, val1, val2, val3, val4, val5)

ASSERT_PRED1(pred, val1)
ASSERT_PRED2(pred, val1, val2)
ASSERT_PRED3(pred, val1, val2, val3)
ASSERT_PRED4(pred, val1, val2, val3, val4)
ASSERT_PRED5(pred, val1, val2, val3, val4, val5)

验证谓词 pred 在接受给定参数时返回 true。

参数 pred 是一个接受相应宏参数数量的函数或仿函数。 若 pred 对给定参数返回 true，则断言成功，否则断言失败。

断言失败时会打印每个参数的值。 保证每个参数只会被计算一次。

示例：

// 当 m 和 n 没有非 1 公因数时返回 true
bool MutuallyPrime(int m, int n) { ... }
...
const int a = 3;
const int b = 4;
const int c = 10;
...
EXPECT_PRED2(MutuallyPrime, a, b);  // 成功
EXPECT_PRED2(MutuallyPrime, b, c);  // 失败

上述示例中，第二个断言失败，将输出：

MutuallyPrime(b, c) is false, where
b is 4
c is 10

若给定谓词是重载函数或模板函数，断言宏可能无法解析出合适的谓词，需要显示指定类型。 例如，对于接受 int 或 double 类型的 IsPositive 重载函数，需使用：

EXPECT_PRED1(static_cast<bool (*)(int)>(IsPositive), 5);
EXPECT_PRED1(static_cast<bool (*)(double)>(IsPositive), 3.14);

直接使用 EXPECT_PRED1(IsPositive, 5) 会导致编译错误。 类似地，使用模板函数需指定模板参数：

template <typename T>
bool IsNegative(T x) {
  return x < 0;
}
...
EXPECT_PRED1(IsNegative<int>, -5);  // 必须指定模板参数

多个模板参数需用括号包裹以确保宏正确解析：

ASSERT_PRED2((MyPredicate<int, int>), 5, 0);

EXPECT_PRED_FORMAT*

EXPECT_PRED_FORMAT1(pred_formatter, val1)
EXPECT_PRED_FORMAT2(pred_formatter, val1, val2)
EXPECT_PRED_FORMAT3(pred_formatter, val1, val2, val3)
EXPECT_PRED_FORMAT4(pred_formatter, val1, val2, val3, val4)
EXPECT_PRED_FORMAT5(pred_formatter, val1, val2, val3, val4, val5)

ASSERT_PRED_FORMAT1(pred_formatter, val1)
ASSERT_PRED_FORMAT2(pred_formatter, val1, val2)
ASSERT_PRED_FORMAT3(pred_formatter, val1, val2, val3)
ASSERT_PRED_FORMAT4(pred_formatter, val1, val2, val3, val4)
ASSERT_PRED_FORMAT5(pred_formatter, val1, val2, val3, val4, val5)

验证谓词格式化器 pred_formatter 在接受给定参数时返回 true。

参数 pred_formatter 是谓词格式化器，其签名为：

testing::AssertionResult PredicateFormatter(const char* expr1,
                                            const char* expr2,
                                            ...
                                            const char* exprn,
                                            T1 val1,
                                            T2 val2,
                                            ...
                                            Tn valn);

其中 val1、val2、...、valn 是参数值，expr1、expr2、...、exprn 是源代码中相应的表达式。 T1、T2、...、Tn 既可以是值类型，也可以是引用类型。 关于返回类型 testing::AssertionResult，请参阅 。

示例：

// 返回 m 和 n 的最小公质因数，互质则返回 1
int SmallestPrimeCommonDivisor(int m, int n) { ... }

// 当 m 和 n 没有非 1 公因数时返回 true
bool MutuallyPrime(int m, int n) { ... }

// 断言两个整数互质的谓词格式化器
testing::AssertionResult AssertMutuallyPrime(const char* m_expr,
                                             const char* n_expr,
                                             int m,
                                             int n) {
  if (MutuallyPrime(m, n)) return testing::AssertionSuccess();

  return testing::AssertionFailure() << m_expr << " and " << n_expr
      << " (" << m << " and " << n << ") are not mutually prime, "
      << "as they have a common divisor " << SmallestPrimeCommonDivisor(m, n);
}

...
const int a = 3;
const int b = 4;
const int c = 10;
...
EXPECT_PRED_FORMAT2(AssertMutuallyPrime, a, b);  // 成功
EXPECT_PRED_FORMAT2(AssertMutuallyPrime, b, c);  // 失败

上述示例中，第二个断言失败，将输出：

b and c (4 and 10) are not mutually prime, as they have a common divisor 2

Windows HRESULT 断言

本节的断言用于验证 HARSULT 成功或失败。 例如：

CComPtr<IShellDispatch2> shell;
ASSERT_HRESULT_SUCCEEDED(shell.CoCreateInstance(L"Shell.Application"));
CComVariant empty;
ASSERT_HRESULT_SUCCEEDED(shell->ShellExecute(CComBSTR(url), empty, empty, empty, empty));

断言失败时将输出可读的 HRESULT 错误信息。

EXPECT_HRESULT_SUCCEEDED

EXPECT_HRESULT_SUCCEEDED(expression)
ASSERT_HRESULT_SUCCEEDED(expression)

验证 expression 是成功的 HRESULT。

EXPECT_HRESULT_FAILED

EXPECT_HRESULT_FAILED(expression)
ASSERT_HRESULT_FAILED(expression)

验证 expression 是失败的 HRESULT。

死亡断言

本节的断言用于验证代码段导致进程终止。 详见。

这些断言会创建新进程来执行被测代码。 断言的具体行为取决于平台和变量 ::testing::GTEST_FLAG(death_test_style) （通过命令行参数 --gtest_death_test_style 初始化）。

• 在 POSIX 系统中，使用 fork()（Linux 上为 clone()）创建子进程，之后：
  • 若变量值为 "fast"，立即执行死亡测试语句。
  • 若变量值为 "threadsafe"，子进程会重新执行测试程序，但只运行单个死亡测试。
• 在 Windows 上，使用 CreateProcess() 创建子进程，行为类似 POSIX 的 "threadsafe" 模式。

其它变量值视为无效值，会导致死亡测试失败。 目前，变量值默认为 "fast"。

若死亡测试语句执行完毕后未终止，子进程依旧会终止，而断言失败。

EXPECT_DEATH({
  int n = 5;
  DoSomething(&n);
}, "Error on line .* of DoSomething()");

EXPECT_DEATH

EXPECT_DEATH(statement, matcher)
ASSERT_DEATH(statement, matcher)

验证 statement 导致进程以非零退出码终止，且 stderr 输出匹配 matcher。

参数 matcher 可以是 const std::string& 的， 或正则表达式（参见）。 裸字符串 s 将被视为 ， 而非 。

例如，下列代码验证 DoSomething(42) 导致进程终止并输出包含 "My error" 的错误信息：

EXPECT_DEATH(DoSomething(42), "My error");

EXPECT_DEATH_IF_SUPPORTED

EXPECT_DEATH_IF_SUPPORTED(statement, matcher)
ASSERT_DEATH_IF_SUPPORTED(statement, matcher)

若支持死亡测试，行为同 EXPECT_DEATH，否则不作验证。

EXPECT_DEBUG_DEATH

EXPECT_DEBUG_DEATH(statement, matcher)
ASSERT_DEBUG_DEATH(statement, matcher)

调试模式下，行为同 EXPECT_DEATH。 非调试模式（定义了 NDEBUG 宏）下，仅执行 statement。

EXPECT_EXIT

EXPECT_EXIT(statement, predicate, matcher)
ASSERT_EXIT(statement, predicate, matcher)

验证 statement 导致进程终止，且退出状态满足 predicate，stderr 输出匹配 matcher。

参数 predicate 是接受 int 退出状态并返回 bool 的函数或仿函数。 GoolgeTest 提供了两个常用谓词：

// 当程序以指定退出码正常终止时返回 true
::testing::ExitedWithCode(exit_code);

// 当程序被以指定信号终止时 返回 true（Windows 上不可用）
::testing::KilledBySignal(signal_number);

参数 matcher 可以是 const std::string& 的， 或正则表达式（参见）。 裸字符串 s 将被视为 ， 而非 。

例如，下列代码验证 NormalExit() 导致进程输出包含 "Success" 的错误信息并以状态码 0 退出：

EXPECT_EXIT(NormalExit(), testing::ExitedWithCode(0), "Success");

宏

GoogleTest 定义了以下宏来辅助操作模拟对象。

MOCK_METHOD

MOCK_METHOD(return_type, method_name, (args...));
MOCK_METHOD(return_type, method_name, (args...), (specs...));

在模拟类中定义具有参数 arg.. 和返回类型 return_type 的模拟方法 method_name。

MOCK_METHOD 的参数与方法的声明结构对应。 可选的第四个参数 specs... 是以逗号分隔的限定符列表。 接受的限定符包括：

| 限定符 | 含义 | |

宏

GoogleTest 定义了以下宏来辅助编写测试。

TEST

TEST(TestSuiteName, TestName) {
  // ... statements ...
}

在测试套件 TestSuiteName 中定义一个名为 TestName 的测试单元，包含指定的语句集合。

参数 TestSuiteName 和 TestName 必须是有效的 C++ 标识符，且不得包含下划线（_）。 位于不同测试套件的测试单元可以拥有相同的名称。

测试体内的语句可以是任意被测代码。 测试结果由测试体内使用的决定。

TEST_F

TEST_F(TestFixtureName, TestName) {
  // ... statements ...
}

定义一个使用测试夹具类 TestFixtureName 的测试单元 TestName。 相应测试套件的名称为 TestFixtureName。

参数 TestFixtureName 和 TestName 必须是有效的 C++ 标识符，且不得包含下划线（_）。 TestFixtureName 必须是测试夹具类的名称（参见）。

测试体内的语句可以是任意被测代码。 测试结果由测试体内使用的决定。

TEST_P

TEST_P(TestSuiteName, TestName) {
  // ... statements ...
}

定义一个使用值参数化测试夹具类 TestFixtureName 的测试单元 TestName。 相应测试套件的名称为 TestFixtureName。

参数 TestSuiteName 和 TestName 必须是有效的 C++ 标识符，且不得包含下划线（_）。 TestFixtureName 必须是值参数化测试夹具类的名称（参见）。

测试体内的语句可以是任意被测代码。 在测试体内，可通过 GetParam() 函数来访问测试参数（参见WithParamInterface）。 例如：

TEST_P(MyTestSuite, DoesSomething) {
  ...
  EXPECT_TRUE(DoSomething(GetParam()));
  ...
}

测试结果由测试体内使用的决定。

另见 INSTANTIATE_TEST_SUITE_P。

INSTANTIATE_TEST_SUITE_P

INSTANTIATE_TEST_SUITE_P(InstantiationName, TestSuiteName, param_generator)
INSTANTIATE_TEST_SUITE_P(InstantiationName, TestSuiteName, param_generator, name_generator)

实例化使用 TEST_P 定义的值参数化测试套件 TestSuiteName。

参数 InstantiationName 是该测试套件实例的唯一标识，用于区分不同实例。 在测试输出中，实例名称将作为前缀添加到测试套件名称 TestSuiteName 中。 若 InstantiationName 为空（INSTANTIATE_TEST_SUITE_P(, ...)），则不添加前缀。

参数 param_generator 必须是下列 GoogleTest 提供的参数生成函数之一（均定义于 ::testing 命名空间）：

| 参数生成器 | 行为 | |

模拟普通类

给定

class Foo {
 public:
  virtual ~Foo();
  virtual int GetSize() const = 0;
  virtual string Describe(const char* name) = 0;
  virtual string Describe(int type) = 0;
  virtual bool Process(Bar elem, int count) = 0;
};

我们可以定义其模拟类为：

#include <gmock/gmock.h>

class MockFoo : public Foo {
 public:
  MOCK_METHOD(int, GetSize, (), (const, override));
  MOCK_METHOD(string, Describe, (const char* name), (override));
  MOCK_METHOD(string, Describe, (int type), (override));
  MOCK_METHOD(bool, Process, (Bar elem, int count), (override));
};

要创建忽略所有无趣调用的“友好”模拟、警告所有无趣调用的“唠叨”模拟，或将无趣调用视为失败的“严格”模拟：

using ::testing::NiceMock;
using ::testing::NaggyMock;
using ::testing::StrictMock;

NiceMock<MockFoo> nice_foo;      // 类型为 MockFoo 的子类
NaggyMock<MockFoo> naggy_foo;    // 类型为 MockFoo 的子类
StrictMock<MockFoo> strict_foo;  // 类型为 MockFoo 的子类

模拟类模板

类模板可以像普通类一样进行模拟。

给定模板类

template <typename Elem>
class StackInterface {
 public:
  virtual ~StackInterface();
  virtual int GetSize() const = 0;
  virtual void Push(const Elem& x) = 0;
};

（注意所有需要模拟的成员函数，包括 ~StackInterface() 必须为虚函数）

template <typename Elem>
class MockStack : public StackInterface<Elem> {
 public:
  MOCK_METHOD(int, GetSize, (), (const, override));
  MOCK_METHOD(void, Push, (const Elem& x), (override));
};

指定模拟函数的调用约定

若需为模拟函数指定非默认调用约定，可为 MOCK_METHOD 添加第四个参数 Calltype(convention)。 例如：

MOCK_METHOD(bool, Foo, (int n), (Calltype(STDMETHODCALLTYPE)));
MOCK_METHOD(int, Bar, (double x, double y),
            (const, Calltype(STDMETHODCALLTYPE)));