C# 中的 IStructuralEquatable 接口在设计上解决了一个非常具体的问题：当对象本身就是由多个子元素组成时，如何判断两个对象在内容上相等。数组是最典型的例子。两个整型数组 new int[] { 1, 2, 3 } 在内存中是两个不同的对象，因此默认的 Equals 方法会返回 False，即使它们的元素完全相同。这种引用相等语义对于需要按内容比较集合的场景并不友好。IStructuralEquatable 的作用就是让类型能够声明自己支持结构化比较，并把逐元素比较的规则交给外部传入的 IEqualityComparer。
该接口位于 System.Collections 命名空间，.NET 中的数组、元组以及部分集合类型都实现了这个接口。理解它的工作方式，对于实现自定义集合的值语义、处理复杂缓存键和去重逻辑，都有实际帮助。
一、接口定义与设计意图
IStructuralEquatable 的声明非常精简，它只包含两个方法：Equals(object other, IEqualityComparer comparer) 和 GetHashCode(IEqualityComparer comparer)。这两个方法与 object 基类上的同名方法最大的不同在于，它们都额外接收一个比较器参数。这个设计意图很明显：相等判断和哈希码计算不再由类型内部写死，而是交给调用者提供的比较器来完成。
public interface IStructuralEquatable
{
bool Equals(object other, IEqualityComparer comparer);
int GetHashCode(IEqualityComparer comparer);
}为什么要把比较规则外部化？因为一个集合类型并不知道使用者在什么业务场景下比较元素。比如一个字符串数组，默认情况下可能希望区分大小写，但在某些场景下又需要忽略大小写。如果类型只允许一种固定规则，就无法同时满足两类需求。通过让 Equals 接收 IEqualityComparer，调用方可以使用 StringComparer.OrdinalIgnoreCase 或者任何自定义比较器，实现不同维度的结构比较。
另一个原因是哈希码的一致性。如果两个对象被判定为结构相等，它们的 GetHashCode 必须返回相同值。由于 GetHashCode 同样接收比较器，类型可以委托同一个比较器来计算各元素的哈希码，从而保证相等性和哈希码在相同规则下保持一致。这种设计在字典和哈希集合中尤为重要。
二、为什么数组默认不按内容比较
在 C# 中，数组本质上是一个引用类型，继承自 System.Array。System.Array 重写了 object.Equals 吗？实际上它并没有将其改为内容比较。对于两个数组变量，只有指向同一块内存时，Equals 才会返回 True。这导致很多开发者在单元测试或去重时遇到困惑：明明两个数组打印出来一模一样，比较结果却是 False。下面的代码可以直观看到这个差异。
int[] first = { 1, 2, 3 };
int[] second = { 1, 2, 3 };
bool defaultEquals = first.Equals(second); // False，引用比较
bool structuralEquals = first.Equals(second, StructuralComparisons.StructuralEqualityComparer); // True这里用到了 StructuralComparisons.StructuralEqualityComparer，它是 .NET 提供的一个现成比较器，能够对数组进行逐元素比较。它的工作方式并不复杂：先检查两个对象是否为 null，再检查引用是否相同，然后确认类型是否一致，最后按索引依次比较每个元素。如果元素本身也是数组，它会递归进行结构比较。因此嵌套数组也能得到符合直觉的结果。
int[][] nestedA = { new[] { 1, 2 }, new[] { 3, 4 } };
int[][] nestedB = { new[] { 1, 2 }, new[] { 3, 4 } };
bool nestedEquals = nestedA.Equals(nestedB, StructuralComparisons.StructuralEqualityComparer); // True引用比较并非没有价值。它的性能开销极小，只判断两个引用是否指向同一地址。在不需要内容比较或对象数量巨大的场景下，引用相等是高效的选择。但一旦业务语义要求值相等，结构比较就是必须的。理解这两种语义的边界，可以避免在缓存键、集合去重、断言测试中引入隐蔽 bug。
三、元组与自定义集合如何利用结构相等
元组是另一个受益于结构相等机制的类型。C# 中的 ValueTuple 和 Tuple 都已经实现了值语义比较，因此两个内容相同的元组可以用 Equals 直接得到 True。这背后同样是结构比较在起作用。例如 Tuple.Create(1, "hello") 与另一个相同内容元组比较时，内部会逐字段比较，而不是简单判断引用。
对于自定义集合类型，实现 IStructuralEquatable 可以赋予它与数组类似的结构化比较能力。下面是一个简单的 LineItem 类示例，它在内部使用字符串数组保存字段片段，并通过接口将相等判断和哈希计算委托给传入的比较器。
public sealed class LineItem : IStructuralEquatable, IEquatable<LineItem>
{
private readonly string[] parts;
public LineItem(string[] parts)
{
this.parts = parts;
}
public bool Equals(LineItem other)
{
return Equals(other, StructuralComparisons.StructuralEqualityComparer);
}
public bool Equals(object other, IEqualityComparer comparer)
{
if (other is null) return false;
if (ReferenceEquals(this, other)) return true;
var item = other as LineItem;
if (item is null) return false;
return comparer.Equals(parts, item.parts);
}
public int GetHashCode(IEqualityComparer comparer)
{
return comparer.GetHashCode(parts);
}
public override bool Equals(object obj) => Equals(obj as LineItem);
public override int GetHashCode() => GetHashCode(StructuralComparisons.StructuralEqualityComparer);
}这个实现展示了一种常见模式：类型内部维护一个数组或其它聚合结构，接口方法把比较任务整体委托给 IEqualityComparer。这里 comparer.Equals(parts, item.parts) 会调用比较器对两个数组执行结构比较。如果 parts 中的字符串需要忽略大小写比较，调用方可以传入 StringComparer.OrdinalIgnoreCase，而无需修改 LineItem 的代码。
不过这个示例中的 GetHashCode 直接使用 comparer.GetHashCode(parts)，它依赖于比较器对数组的哈希支持。对于 StructuralEqualityComparer 来说，它能够基于所有元素计算稳定哈希码。自定义比较器如果只实现了元素级比较、不支持集合哈希，这里就可能出现问题。因此在实际实现时，常常需要手动遍历元素并组合哈希值，以增强稳定性。
四、实现时需要注意的哈希码规则
在实现 IStructuralEquatable 时，有一个铁律不能违反：如果两个对象通过 Equals 判断为相等，那么它们的 GetHashCode 返回值必须相同。反之不成立，哈希码相同不代表对象一定相等，因为哈希存在冲突。这是一个适用于所有相等比较实现的通用规则，但结构比较中尤其容易因为比较器不同而破坏它。
推荐的做法是让 GetHashCode 遍历每个元素，将元素的哈希码与一个固定种子进行组合。下面是一个使用 31 和 17 这两个常见质数的组合算法，能够有效降低冲突概率。
public int GetHashCode(IEqualityComparer comparer)
{
unchecked
{
int hash = 17;
foreach (var part in parts)
{
hash = hash * 31 + comparer.GetHashCode(part);
}
return hash;
}
}需要特别注意的是，如果传入的 comparer 为 null，实现时应做好防御。虽然接口约定通常要求调用方传入有效比较器，但健壮的实现可以选择回退到 EqualityComparer<object>.Default，或者直接抛出 ArgumentNullException。显式抛异常能让调用方更早发现错误，而静默回退则可能掩盖问题，具体取舍取决于类型的使用范围。
性能方面，结构比较的开销通常显著高于引用比较。对于大数组或深层嵌套结构，逐元素比较和哈希计算的时间复杂度会随元素数量线性增长。因此，如果一个集合类型在多数场景下只关心引用相等，并不需要频繁做内容比较，就不必强制实现 IStructuralEquatable。相反，如果该类型经常作为字典键或参与去重，正确实现值语义带来的性能收益和代码清晰度往往超过比较本身的成本。
可变集合还需要考虑哈希码的稳定性。一旦对象被放入 Dictionary 或 HashSet 作为键，其哈希码就不应该再发生变化。如果集合内容被修改，基于元素计算的哈希码也会改变，轻则导致查找失败，重则破坏哈希容器的内部结构。因此，建议用于结构比较的集合内容保持不可变，或者在修改后不要继续作为哈希键使用。
五、常见误区与使用建议
第一个常见误区是以为所有集合类型都自动支持结构比较。实际上，只有实现了 IStructuralEquatable 的类型才具备这个能力。List<T> 默认并不实现该接口，两个内容相同的 List<T> 调用 Equals 仍然返回 False。如果需要列表内容比较，可以选择使用 SequenceEqual 扩展方法，或者将列表包装为自定义类型并实现接口。
第二个误区是在实现接口时只重写了 Equals，却忽略了 GetHashCode 的一致性。编译器不会强制要求两者逻辑一致，但运行时哈希容器会对这一不一致进行惩罚。例如在单元测试中只比较对象相等，可能一切正常；一旦将对象放入 HashSet，就可能出现重复元素无法去重，或者查找不到已有键的情况。这种问题排查起来往往比较耗时。
第三个误区是滥用结构比较，忽视比较器参数的作用。结构比较并不意味着一定使用元素类型的默认比较规则。通过传入自定义 IEqualityComparer，可以控制字段的比较方式、忽略某些字段，甚至实现大小写不敏感的字符串数组比较。反过来，如果不希望调用方影响比较规则，就不应暴露接口方法，而应直接实现 IEquatable<T> 或重写 Equals。
总结来说，IStructuralEquatable 是 C# 类型系统中一个制作精良的扩展点。它让数组、元组以及自定义集合能够在不绑定具体比较规则的前提下，提供内容级的相等语义。理解这个接口，并正确实现两个方法和遵守哈希一致性规则，可以显著提升集合类型在缓存、去重、断言和领域建模中的可用性。对于日常开发来说，最常见的用法仍然是借助 StructuralComparisons.StructuralEqualityComparer 快速完成数组的逐元素比较，而更深入的实现则适合那些需要自定义值语义的复杂类型。
IStructuralEquatable结构比较StructuralComparisons修改时间：2026-09-27 17:10:37