属性

属性（property） 是类、结构体或接口的成员。调用方以order.Total或order.Status = value这样的字段式语法使用它，声明类型则通过访问器控制读取或赋值。属性本身不等于字段：它可以返回存储值、计算结果，也可以拒绝一次赋值。

属性解决的是公开数据与保留控制权之间的矛盾。公开字段一旦成为API，声明类型就无法在同一访问点增加验证、计算或更严格的写权限；成对的GetName()、SetName()方法又会让简单数据访问变得笨重。属性把这些控制点放在稳定的成员语法后面。

你会在领域对象、配置类型、DTO、序列化模型和UI绑定对象中遇到属性。调用代码看起来相同，不代表契约相同：自动属性通常只保存值，计算属性每次读取都求值，而自定义访问器可以运行任意代码。审查属性时，要从声明而不是调用语法推断行为。

属性适合表达对象在某一时刻具有的特征。一次网络请求、数据库查询、长时间计算或明显的状态转换通常更适合方法，因为方法调用能让成本与动作更可见。

访问器定义读写能力

属性访问器（property accessor） 是属性中的get、set或init部分。读取属性会执行get；普通赋值会执行set；init只允许在对象构造阶段的合法位置赋值。set与init中的隐式参数value就是调用方提供的新值。

访问器组合直接构成公开契约。只有get的属性对调用方只读；get加set可以反复赋值；get加init允许构造阶段赋值，之后不再允许普通赋值。C#也允许仅写属性，但调用方无法读回状态，实际API中很少需要这种形状。

属性和访问器还可以使用不同的可访问性。public decimal Balance { get; private set; }允许所有调用方读取，却只允许声明类型修改。较严格的访问修饰符只能放在其中一个访问器上，而且属性必须同时具有读取与写入访问器。

存储属性与计算属性

自动属性省略访问器主体，例如public string Name { get; set; }。编译器为它创建隐藏的 幕后字段（backing field） ，并生成读取和写入该存储的访问器。属性初始值设定项会在构造过程中为这份存储赋值。

需要控制逻辑时，可以显式声明幕后字段，再在访问器中引用它。这样适合范围检查、规范化输入或维护简单不变量。访问器应先验证，再写入字段，否则抛出异常时对象可能已经进入部分更新状态。

计算属性不需要自己的存储。public decimal Total => UnitPrice * Quantity;每次读取都会根据当前状态求值，因此不会出现独立缓存过期的问题。计算很昂贵或需要I/O时，应改用名称明确的方法，或者设计带清晰失效规则的缓存。

C# 14的field上下文关键字提供第三种形状。访问器可以通过field使用编译器合成的幕后字段，同时保留自动实现的另一个访问器。这减少了只为一小段验证逻辑而声明字段的样板代码。

init与required回答不同问题

init访问器（init accessor） 限制属性可以在哪里赋值。调用方可以在对象初始化器中设置它，类型的构造过程也可以建立初始状态；构造阶段结束后，普通代码不能再次给它赋值。这个限制针对属性赋值，不会冻结属性引用的对象。

必需成员（required member） 要求创建表达式初始化某个字段或属性，除非所调用的构造函数声明自己已经满足全部必需成员。required不决定之后能否修改，因此既可配合set，也可配合init。它也不会自动验证字符串非空、数值范围或业务关系。

非可空引用类型、required和运行时验证各自处理一层问题。非可空注解参与编译器的空状态分析，required检查对象创建语法是否遗漏成员，访问器或构造函数则执行真正的运行时不变量。健壮的边界类型经常需要三者配合，而不是选择其中一个。

调用语法隐藏了方法调用

编译后，读取和写入属性对应特殊名称的方法，通常可在元数据中看到get_Name与set_Name。反射把属性作为属性元数据公开，同时也能取得相应访问器。调用方仍写customer.Name，编译器负责绑定到访问器调用。

这解释了为什么属性能够出现在接口中，也能声明为virtual或abstract。实现或重写提供的是访问行为，不是要求所有类型具有同名字段。它也解释了为什么调试器读取一个属性可能执行用户代码。

从自动属性开始

第一个例子把简单状态交给自动属性，把派生值写成计算属性，并把库存变化放进方法。private set让调用方不能绕过TrySell直接替换库存。

Name必须出现在创建表达式中，之后也不能通过普通赋值修改。UnitPrice没有required，所以遗漏它仍能编译，并得到decimal的默认值0；真实领域若不接受零价，还需要构造或验证契约。

InventoryValue始终根据当前Stock计算。库存只有私有setter，但TrySell仍能在类型内部使用复合赋值；方法集中处理数量范围，并以返回值表达一次预期的拒绝。

用field验证赋值

第二个例子使用C# 14的字段支持属性。调用方仍然面对普通属性，init和私有set则分别规范化名称与保护积分变化入口。

// # not executed here: the .NET SDK and C# compilers are unavailable
using System;

var profile = new CustomerProfile
{
    DisplayName = "  Ada  "
};

profile.AddPoints(25);
Console.WriteLine($"{profile.DisplayName}: {profile.LoyaltyPoints}");

try
{
    profile.AddPoints(-1);
}
catch (ArgumentOutOfRangeException)
{
    Console.WriteLine("negative points rejected");
}

public sealed class CustomerProfile
{
    public required string DisplayName
    {
        get;
        init => field = string.IsNullOrWhiteSpace(value)
            ? throw new ArgumentException("Display name is required")
            : value.Trim();
    }

    public int LoyaltyPoints
    {
        get;
        private set => field = value >= 0
            ? value
            : throw new ArgumentOutOfRangeException(nameof(value));
    }

    public void AddPoints(int points) => LoyaltyPoints += points;
}

# not executed here: the .NET SDK and C# compilers are unavailable

DisplayName的required检查创建代码没有遗漏成员，init主体才负责拒绝空白并保存裁剪后的值。这两个约束不能互相替代。调用方即使显式写入null，required条件也算满足，因此运行时验证仍然必要。

AddPoints把结果写回LoyaltyPoints，所以私有setter会检查相加后的最终值。这里的负数调用被拒绝，是因为结果小于零；若业务规则规定参数本身必须为正，还应在方法入口单独检查points。

保护集合所有权

第三个例子把列表保留在对象内部，只通过只读包装公开。属性只读并不等于对象深度不可变，因此类型仍用方法控制集合变化。

// # not executed here: the .NET SDK and C# compilers are unavailable
using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Linq;

var order = new PurchaseOrder { Number = "PO-42" };
order.AddLine(new OrderLine("Keyboard", 2, 79.90m));
order.AddLine(new OrderLine("Cable", 1, 12.50m));

Console.WriteLine($"{order.Number}: {order.Lines.Count} lines");
Console.WriteLine($"total: {order.Total:F2}");

public sealed class PurchaseOrder
{
    private readonly List<OrderLine> _lines = [];

    public PurchaseOrder()
    {
        Lines = _lines.AsReadOnly();
    }

    public required string Number { get; init; }
    public ReadOnlyCollection<OrderLine> Lines { get; }
    public decimal Total => _lines.Sum(line => line.Quantity * line.UnitPrice);

    public void AddLine(OrderLine line)
    {
        ArgumentNullException.ThrowIfNull(line);
        if (line.Quantity <= 0 || line.UnitPrice < 0)
            throw new ArgumentOutOfRangeException(nameof(line));
        _lines.Add(line);
    }
}

public sealed record OrderLine(string Product, int Quantity, decimal UnitPrice);

# not executed here: the .NET SDK and C# compilers are unavailable

Lines没有setter，调用方不能替换包装对象；ReadOnlyCollection<T>也不公开添加和删除操作。内部列表改变时，包装视图会反映最新内容，这正是此API选择的实时视图语义。

元素使用不可变记录，避免调用方取得某一行后再偷偷修改数量。若元素本身可变，只读集合只能保护集合结构，不能保护元素状态；这种所有权决策必须在类型契约中明确。

访问器递归调用自身

修复方法： 显式实现时写入幕后字段，或者在C# 14中使用field。搜索访问器主体中的属性自身名称，并为一次读写添加最小测试；不要把这种错误当成普通验证异常来捕获。

在getter中隐藏I/O或状态变化

修复方法： 有明显成本、失败模式或副作用的操作使用方法，例如LoadReportAsync()。计算属性保持可预测；必须缓存时，明确缓存的所有者、线程行为与失效条件。

把init或私有setter当成深度不可变

修复方法： 对外暴露不可变集合、只读包装或快照，并控制元素本身的可变性。审查属性类型形成的整个对象图，不要只看setter的可访问级别。

把required当成验证器

修复方法： 在可信边界内执行空值、格式和跨字段验证。把required当作调用方体验与编译时完整性工具，不要把它当作运行时数据验证或安全边界。

在验证前修改幕后状态

修复方法： 先在局部值上完成验证和规范化，再提交字段更新。涉及多个成员的原子状态转换应使用方法或工厂，把全部条件检查完后再一次性修改对象。

让可写属性破坏哈希或集合身份

修复方法： 用稳定且不可变的值定义键身份，或者在修改前移出、修改后重新加入。记录类型也要检查参与值相等性的属性是否会引用可变对象。

• C#编程指南：属性
• 自动实现的属性
• init关键字参考
• required修饰符参考
• C#语言规范：属性