常见问题与排错

这份 FAQ 现在改成“诊断首页 + 分组正文”的结构。

原因是当前问题已经覆盖了：

• 主案例入门
• 目标筛选和语义分析
• 生成代码排错
• 测试和驱动结果
• AdditionalFiles、配置、诊断、SourceText

把这些内容继续放在一个文件里，会让真正排错时的定位速度变慢。

学习卡点诊断

flowchart TD
    A["我现在卡住了"] --> B{"主要症状是什么"}
    B --> C["看不懂概念或不会起步"]
    B --> D["不知道怎么找到目标类"]
    B --> E["生成的代码有问题"]
    B --> F["不知道怎么验证、调试、测试"]
    B --> G["已经超出主案例，开始碰高级输入"]

    C --> C1["faq/01-getting-started.md"]
    D --> D1["faq/02-target-discovery.md"]
    E --> E1["faq/03-generation-errors.md"]
    F --> F1["faq/04-testing-and-debugging.md"]
    G --> G1["faq/05-advanced-inputs.md"]

从这里进入哪一组

1. 入门与起步

适合这些情况：

• 不明白什么是编译时生成
• 不确定为什么要用源生成器
• 看不到 .g.cs
• 生成器似乎根本没有运行
• 不理解 partial
• 不知道从哪里开始调试

进入：faq/01-getting-started.md

2. 目标筛选与信息提取

适合这些情况：

• ForAttributeWithMetadataName(...) 找不到类
• 分不清 SyntaxNode 和 ISymbol
• 不知道怎么读取属性类型
• GetMembers() 结果太多
• 不知道怎么读取特性参数

进入：faq/02-target-discovery.md

3. 生成代码错误

适合这些情况：

• 生成代码编译失败
• 可空处理不对
• 泛型类或嵌套类生成错误
• hintName、命名空间、类声明恢复不完整

进入：faq/03-generation-errors.md

4. 测试、调试与驱动结果

适合这些情况：

• 不知道测试工程在验证什么
• 不知道 Compilation 和 CSharpCompilation 的关系
• 想知道某个生成器到底生成了什么
• 已经加了 WithTrackingName(...) 仍然看不到步骤跟踪

进入：faq/04-testing-and-debugging.md

5. 高级输入与扩展链路

适合这些情况：

• 想读取 .graphql、.json 等附加文件
• 想读取项目配置或构建属性
• 想让生成器报错误、警告、提示
• 不知道何时用 SourceText.From(...)
• 不知道何时选 CreateSyntaxProvider(...)

进入：faq/05-advanced-inputs.md

最常用的回查顺序

1. 先按症状进入对应分组
2. 如果问题仍然偏“对象不理解”，切到 术语与 API 手册
3. 如果问题已经超出主案例收口，切到：
   • advanced/01-driver-run-result.md
   • advanced/02-incremental-tracking.md
   • advanced/03-additional-files-and-config.md
   • advanced/04-diagnostics-sourcetext-and-syntax-provider.md

如果你只是想顺着学

• 返回 零基础主教程目录
• 主案例收口看 第 12 章