现有 C# 项目启用可空引用类型并系统消除 CS86xx…

在已有 C# 项目或解决方案中启用可空引用类型并逐文件/全项目修复所有可空引用警告，且保持运行时行为不变。

适用场景

解决思路

1. 迁移期间保持零运行时行为变化：只允许可空注解（?）、可空属性（[NotNullWhen] 等）、! 操作符（仅元数据）和 #nullable 指令；不得新增分支、null 检查、改变控制流、增删方法调用。
2. 若发现缺失运行时 null guard 或潜在 bug，不要内联修复；提议在位置插入 // TODO: Consider adding ArgumentNullException.ThrowIfNull(param) 注释，让用户作为单独变更处理。
3. 按逻辑边界提交：启用 <Nullable> 后、修复解引用警告后、注解声明后、应用可空属性后、清理抑制后分别提交；file-by-file 迁移时每个文件或相关文件批次单独提交。
4. Step 1 可选运行 scripts/Get-NullableReadiness.ps1 -Path <project-or-solution> 自动检查；用 -Json 获取机器可读输出；脚本报告 <Nullable>、<LangVersion>、<TargetFramework>、<WarningsAsErrors> 设置，并统计 #nullable disable 指令、! 操作符、#pragma warning disable CS86xx 抑制。
5. 识别项目构建和测试方式：查找 build.cmd、build.sh、Makefile、.sln 或单个 .csproj；若仓库使用自定义构建脚本，则全程使用它而不是 dotnet build。
6. 运行 dotnet --version 确认 SDK 已安装；NRT 需要 C# 8.0+（.NET Core 3.0 / .NET Standard 2.1 或更高）。
7. 打开 .csproj 或 Directory.Build.props 检查 <LangVersion> 和 <TargetFramework>；若多目标，记录所有 TFM。
8. 若 <LangVersion> 低于 8.0，或目标框架默认 C# 7.x（如未显式 <LangVersion> 的 .NET Framework 4.x），停止并告知：需设置 <LangVersion>8.0</LangVersion> 或更高，或重定向到 .NET Core 3.0+ / .NET 5+；询问用户是否更新并继续或中止。
9. 检查 <Nullable> 是否已设置；若已为 enable，跳到 Step 5 审计剩余警告。
10. 按项目类型调整注解优先级：Library 先专注 public API 契约；Application 关注反序列化、数据库查询、用户输入、外部 API 响应等边界；Test project 注解精度优先级低，可在测试 setup 和断言中更自由使用 !，确保测试代码干净编译。
11. Step 2 选择 rollout 策略并向用户推荐、确认后再继续。
12. 多项目解决方案按依赖顺序迁移：先共享库和核心项目，再迁移依赖它们的项目；先注解依赖可消除消费者中的级联警告，避免重复工作。
13. 无论策略，从中心向外开始：先迁移核心领域模型、DTO、共享工具类型等依赖少但被广泛使用的类型，再迁移依赖核心类型的高级服务、控制器、UI 代码；每步最小化警告数量，避免项目级启用后警告泛滥。
14. 尽量每个项目或每层至少一个 PR；若所需注解较少，可单次项目级启用并单个 PR。
15. Strategy A（中小项目）：在 .csproj 的 <PropertyGroup> 中添加 <Nullable>enable</Nullable>；构建并一次处理所有警告。
16. Strategy B（大型或活跃项目）：在 .csproj 中添加 <Nullable>warnings</Nullable>；构建并按 Step 3 起修复所有警告；改为 <Nullable>enable</Nullable> 激活注解并触发第二波警告；按 Step 4 起处理注解阶段警告。
17. Strategy C（超大项目）：项目级设置 <Nullable>disable</Nullable> 或省略；每个迁移文件顶部添加 #nullable enable；按依赖顺序优先迁移共享工具和模型，再迁移高层消费者。
18. 启用 <Nullable> 或给首批文件加 #nullable enable 后执行 clean build（如 dotnet build --no-incremental，或先删除 bin/obj）；增量构建只重编译变更文件，会隐藏未改文件中的警告；记录初始警告数作为基线。
19. 在修复警告前确认项目仍可编译；后续所有构建检查点都使用 clean build。
20. Step 3 修复解引用警告：按依赖顺序处理文件，先核心模型和共享工具，再高层消费者；每个文件先处理 public 和 protected 成员（定义契约），再处理 internal 和 private 成员。
21. CS8602（解引用可能为 null 的引用）：优先仅注解修复——若上游 null 有效，改为 T?；若可验证此处永不为 null，用 !；添加 null 检查或 ?. 会改变运行时行为，留到单独提交。
22. CS8600（将可能 null 转换为非空类型）：若 null 有效，给目标类型加 ?；若可验证值永不为 null，用 !；添加 null guard 会改变运行时行为。
23. CS8603（可能返回 null 引用）：若方法确实可能返回 null，把返回类型改为 T?；不要用 ! 抑制真正可返回 null 的方法——非空返回类型是对所有调用者的承诺。
24. CS8604（可能 null 引用参数）：若 null 有效，把参数标记为 nullable；若参数可验证非空，用 !；在传递前添加 null 检查会改变运行时行为。
25. 不要用 ?. 作为解引用警告的快速修复：把 obj.Method() 改成 obj?.Method() 会静默跳过调用、改变运行时行为；只有确实想容忍 null 时才用 ?.。
26. 不要撒 ! 来消警告；每个 ! 都是值永不为 null 的声明，错误声明会隐藏 NullReferenceException；应添加 null 检查或把类型改为 nullable。
27. 永远不要用 return null! 保持非空返回类型；若方法返回 null，返回类型必须是 T?；这适用于 null!、default! 以及任何让编译器接受 null 放入非空位置的转换；仅当返回值可证明永不为 null 但编译器看不到原因时才可对返回值用 !。
28. 不要给值类型加 ?，除非确实想改变运行时类型；引用类型 ? 是元数据，值类型（int、enum、struct）加 ? 会变成 Nullable<T>，改变方法签名、二进制布局和装箱行为。
29. 对每个警告执行决策流程：先问 null 在此设计上是否有效；是则加 ?；否则进入下一步；不确定则问用户。
30. 继续决策：能否证明此处值永不为 null；能但编译器看不到代码路径时，加 ! 并注释原因；能通过 guard 证明时，加 null 检查（if、??、is not null）；不能则类型应为 nullable（回到上一问的「是」）。
31. 优先使用显式 null 检查（if、is not null、??）而不是 null-forgiving 操作符 !。
32. 仅当能证明值永不为 null 但编译器不能时使用 !，并添加注释解释原因。
33. 使用 Guard clause 库（如 Ardalis.GuardClauses、Dawn.Guard）时，其参数常带 [NotNull]；调用 Guard.Against.NullOrEmpty(value, nameof(value)) 后，编译器已将 string? 缩窄为 string，不要在后继赋值加冗余 !；先检查 guard 方法是否使用 [NotNull]。
34. 方法确实可返回 null 时，把返回类型改为 T?，不要用非空签名隐藏 null。
35. Debug.Assert(x != null) 可作为编译器 null-state hint，像 if 检查一样；在方法或块顶部使用它告知流分析不变量并消除后续 !；注意 Debug.Assert 在 Release 构建被剥离，不防运行时 null；public API 边界优先显式 null 检查或 ArgumentNullException。
36. 如果对内部方法每个调用点都加 !，考虑把该参数设为 nullable；仅在编译器确实无法证明非 null 时使用 !。
37. 当布尔 helper 的结果保证 nullable 参数非 null（如 if (IsValid(x)) 蕴含 x != null），优先给 helper 参数加 [NotNullWhen(true)]，而不是每个调用点用 !；这是无行为变化的元数据修改，能消除下游 ! 并给编译器真实流信息。
38. 对于构造后总是被设置的字段（如框架、Init() 方法或 builder 模式），优先在字段声明用 = null!，而不是每个使用点加 !；字段访问 50 次应有一个 = null!，而非 50 个 field!；尽量配合初始化方法上的 [MemberNotNull]。
39. 对于无约束泛型类型参数返回 default 的泛型方法（如 FirstOrDefault<T>），用 [return: MaybeNull] T 而不是 T?；在无约束泛型上写 T? 会把值类型签名变成 Nullable<T>，改变签名和二进制布局；[return: MaybeNull] 保留原签名并说明引用类型返回可能为 null。
40. LINQ 的 Where(x => x != null) 不会把 T? 缩窄为 T；用 source.OfType<T>() 过滤 null 并进行正确类型缩窄。
41. Step 3 后 build，确认零 CS8602/CS8600/CS8603/CS8604 警告，再进入注解警告。
42. Step 4 注解声明：先根据成员设计目的决定预期可空性——该参数是否接受 null、该返回是否可能为 null——再注解并处理产生的警告。
43. 不要猜测 API 契约：不要只根据使用频率或命名约定推断可空意图；若代码或文档未明确意图，问用户。
44. 在以下情况前必须问用户：把 public 方法返回类型改为 nullable 或给 public 参数加 ?；在属性应 nullable 还是 required 的设计意图不清时；无法从上下文判断 null 是有效状态时选择 null 检查还是 !；对 internal/private 成员若用法明显可直接继续。
45. 不要让警告驱动注解：先决定每个成员的预期可空性再注解；到处加 ? 会使调用者加不必要 null 检查，到处加 ! 会隐藏 bug。
46. 返回类型必须反映语义可空性而非只满足编译器：*OrDefault 方法（FirstOrDefault、SingleOrDefault、FindOrDefault）返回类型必须 nullable（T?、object?、dynamic?），因为引用类型的「or default」意味着 null。
47. ExecuteScalar 及类似数据库方法返回类型必须是 object?，因为无匹配行时结果可为 DBNull.Value 或 null。
48. Find、TryGet*（out 参数）和 lookup 方法在项可能不存在时返回类型应为 nullable。
49. 任何文档或设计为在失败、未找到或空输入时返回 null 的方法，返回类型必须 nullable。
50. 不要删除现有 ArgumentNullException 检查；非空参数注解只是编译时提示，不能阻止运行时 null；使用旧 C# 版本、其他 .NET 语言、反射或 ! 的调用者仍可传 null。
51. 标记 public API 方法缺失运行时 null 验证，但不要添加检查：对每个 public 和 protected 方法，若参数非空（T 而非 T?），应有运行时 null 检查（如 ArgumentNullException.ThrowIfNull(param) 或 if (param is null) throw new ArgumentNullException(...)）。
52. 若 public/protected 方法缺失上述运行时检查，添加 null guard 是运行时行为变化，不能作为 NRT 迁移一部分；询问用户是否要在位置插入 // TODO: Consider adding ArgumentNullException.ThrowIfNull(param) 注释；对调用者可能未启用 NRT 的库尤其重要。
53. 对 null 有定义行为的方法应接受 nullable 参数：若方法优雅处理 null（返回 null、默认值或失败结果而非抛异常），参数应为 T? 而非 T；BCL 惯例如 Path.GetPathRoot(string?) 对 null 返回 null，Path.GetFullPath(string) 抛异常；只有 null 导致异常时才用非空参数；方法容忍 null 却标非空会迫使调用者加不必要检查。
54. 处理灰区：当参数未验证、未清理、未文档化 null 时，判断 (1) 自己代码是否传 null，若是则 nullable；(2) 调用者是否可能用 null 作为默认或 no-op 占位，若是则 nullable；(3) 同区域类似方法是否接受 null，若是则为一致性 nullable；(4) 方法基本忽略 null 只是碰巧工作，但 null 对 API 目的无语义意义则非空。
55. 参数在 nullable 与非空之间拿不准时优先 nullable，更安全且以后可收紧。
56. 解引用警告解决后处理注解警告：CS8618 非空字段/属性未在构造函数初始化，需初始化成员、改为 nullable（?）或使用 required（C# 11+）。
57. 对构造后但在构造函数外设置的字段（如框架生命周期方法、Init() 调用或 builder 模式），用 = null! 声明意图并保持字段在使用点非空；若 helper 方法初始化字段，装饰 [MemberNotNull(nameof(field))] 让编译器知道调用后字段非空。
58. CS8625 无法把 null 字面量转换为非空类型：使目标 nullable 或提供非空值。
59. CS8601 可能 null 引用赋值：使用与 CS8600 相同的技术。
60. 对每个类型决定成员是否可 null：是则加 ?；否则确保每个构造路径都初始化或标记 required（C# 11+）；否则但构造后设置则用字段声明 = null!，优于每个使用点加 !；若特定方法初始化，考虑 [MemberNotNull(nameof(field))]。
61. 注解优先 public 和 protected API，因为它们定义消费者依赖的契约；internal 和 private 代码可更自由使用 !，不影响外部调用者。
62. 若项目是被他人消费的库，创建 nullable-breaking-changes.md 或等价文件，记录每个可能影响消费者的 public API 变更。
63. 在 nullable-breaking-changes.md 中记录：返回类型从 T 改为 T?（消费者必须处理 null）；参数从 T? 改为 T（消费者不能再传 null）；参数从 T 改为 T?（调用者现有 null 检查变得不必要，低影响但值得记录）；值类型参数或返回加 ?（T 变 Nullable<T>，二进制破坏）；新增原本没有的 ArgumentNullException guard；注解期间发现并修复的行为变化（如静默接受 null 的方法现在抛异常）。
64. 把 nullable-breaking-changes.md 交由用户 review，并可作为 release notes 基础。
65. DTO 与领域模型用不同可空策略：DTO 和序列化模型跨信任边界（JSON、表单、外部 API），属性默认 nullable，除非序列化器强制；用 required（C# 11+）、[JsonRequired]（.NET 7+）或运行时验证强制非空约束。
66. 领域模型表示内部不变量，偏好非空属性并构造函数强制，使非法状态不可表示；不要把 DTO 当领域模型或反之——前者会导致运行时 NullReferenceException，后者会导致到处不必要 null 检查。
67. 事件处理器和委托：使用 EventHandler? handler = SomeEvent; handler?.Invoke(...) 这种惯用法。
68. Struct 中的引用类型字段：使用 default(T) 时字段为 null；若 default 对该 struct 是合法用法，这些字段必须 nullable；若从不期望 default（struct 仅由特定 API 创建），保持非空，避免让每个消费者加不必要 null 检查。
69. Post-Dispose 状态：字段或属性在对象有用生命周期内非空但 Dispose 后可能变 null，保持非空；Dispose 后使用对象是契约违规，不要为该情况弱化注解。
70. Overrides 和 interface implementations：override 可比基方法声明更严格（非空）的返回类型；若实现从不返回 null 但基类/接口返回 T?，override 可声明返回 T；参数类型必须与基类完全匹配。
71. 广泛被 override 的 virtual 返回类型：考虑现有 override 是否实际返回 null；若常见（如 Object.ToString()）注解返回 T?，因为调用者需要知道；若极少（如 Exception.Message）注解 T；对广泛 override 的 virtual 拿不准时优先 T?。
72. 引用类型实现 IEquatable<T> 和 IComparable<T> 时，应实现 IEquatable<T?> 和 IComparable<T?>（T 可空），因为调用者常传 null 给 Equals 和 CompareTo。
73. 重写 Equals(object?) 时给参数加 [NotNullWhen(true)]：若 Equals 返回 true，参数保证非空；这让调用者在相等测试后跳过冗余 null 检查。
74. Step 4 后 build，确认零 CS8618/CS8625/CS8601 警告，再进入 nullable attributes。
75. Step 5 当简单 ? 注解无法表达 null 契约时，应用 System.Diagnostics.CodeAnalysis 属性；参考 references/nullable-attributes.md 获取完整属性表（[NotNullWhen]、[MaybeNullWhen]、[MemberNotNull]、[AllowNull]、[DisallowNull]、[DoesNotReturn] 等）及用法指导。
76. 应用 nullable attributes 后 build，验证属性解决了目标警告且未引入新警告。
77. Step 6 可选重跑 scripts/Get-NullableReadiness.ps1 获取当前 #nullable disable 指令、! 操作符、#pragma warning disable CS86xx 抑制的计数。
78. 搜索作为临时 workaround 添加的 #nullable disable 指令或 ! 操作符；逐个判断抑制是否仍需要；移除不再需要的抑制；对保留的每个抑制加注释说明原因。
79. 搜索 #pragma warning disable CS86 找出被抑制的可空警告，评估是否能修复底层问题而不是保留抑制。
80. 移除抑制后 build；移除 #nullable disable 或 ! 可能暴露新警告，需要继续修复。
81. Step 7 验证：build 项目并确认零 nullable 警告。
82. 添加 <WarningsAsErrors>nullable</WarningsAsErrors> 到项目文件（或整个仓库的 Directory.Build.props），永久防止可空回归；等价于 dotnet build /warnaserror:nullable。
83. 运行现有测试确认无回归。
84. 若项目是库，检查 public API surface，验证可空注解匹配预期契约（接受 null 的参数为 T?，拒绝 null 的参数为 T）。
85. 声称迁移完成前验证零警告不等于正确：抽查 public API 签名确认 ? 注解匹配实际设计意图而非仅编译器安静；搜索 diff 中 ?. 确认没有添加改变运行时行为的 ?.；确认没有移除 ArgumentNullException 检查；检查 ! 操作符很少且每个有解释注释。
86. 完成 Validation checklist：项目文件含 <Nullable>enable</Nullable>（或 file-by-file 每文件 #nullable enable）；build 产生零 CS86xx 警告；添加 <WarningsAsErrors>nullable</WarningsAsErrors>；测试通过无回归；无 #nullable disable 除非有注释理由；! 操作符很少且每个有理由；public API 签名准确反映 null 契约；库的 breaking changes 记录在 nullable-breaking-changes.md 并由用户 review。
87. Code review 时先验证无行为变化：确认新增只有 ? 和 !，没有意外 ?.，没有移除 null 检查，没有新分支；生成 IL 除 nullable metadata 外应不变。
88. Code review 时审查显式注解变更：对每个加到参数或返回类型的 ?，确认符合预期设计；方法真的接受 null？真的可返回 null？
89. Code review 时审查范围内未改 API：启用 <Nullable>enable</Nullable> 会让该范围内所有未注解引用类型隐式非空；扫描未改 public 成员，找实际接受 null 但未注解的参数。
90. 生成代码警告：生成文件若含 <auto-generated> 注释会自动排除在可空分析外；若仍有警告，在生成文件顶部加 #nullable disable 或配置 .editorconfig 的 generated_code = true。
91. 多目标和旧 TFM：NRT 注解可在旧 TFM（如 .NET Standard 2.0）用 C# 8.0+ 编译，但 [NotNullWhen] 等可空属性可能不存在；使用 NuGet polyfill 包如 Nullable，或在内部定义这些属性。
92. 依赖升级后警告重现：因为依赖新增可空注解；这是预期且有益的，按 Step 3–5 修复新警告。
93. 使用 var 时注意：var 从赋值表达式推断可空性，可能与显式声明 T 或 T? 不同；若声明处的精确可空性重要，用显式类型而不是 var。
94. 消费未注解（nullable-oblivious）库：编译器把所有类型视为 oblivious，不会对解引用或赋 null 给出警告，产生虚假安全感；将 oblivious API 返回值视为可能 null，尤其字典查找、FirstOrDefault 风格调用；尽量升级依赖或包装调用。
95. 若项目使用 EF Core，参考 references/ef-core.md：启用 NRT 可能改变数据库 schema 推断和 migration 输出。
96. 若项目使用 ASP.NET Core，参考 references/aspnet-core.md：启用 NRT 可能改变 MVC 模型验证和 JSON 序列化行为。

适用边界 · 注意事项

• 项目已启用 <Nullable>enable</Nullable> 且零警告时不要迁移；除非要审计并移除不必要的抑制。
• 只想抑制可空警告而不修复底层问题时不要使用（应劝阻）。
• 代码目标为 C# 7.3 或更早时不适用，因为不支持可空引用类型；已启用 NRT 且只需修少量警告时也不必走完整迁移。