XericLibrary-WebGL-Publish/Documentation~/MacroObjectAnalyzerReadme.md

XericUnityAnalyzer 规则文档

所有诊断规则一览

本文档列出 com.lrss3.deconstruction 包中 XericUnityAnalyzer Roslyn 分析器的所有诊断规则， 涵盖 MacroObject（Unity 层级/组件操作）和 MacroString（TextBlockBuilder 富文本）的优化建议。

---

XRX0001 — 重复访问 Transform.parent 属性

属性	值
分类	Usage
严重性	Warning

触发条件： 对 Transform 对象的 .parent 属性进行重复链式访问（直接链式、变量中转、赋值链）。

示例：

// 触发警告
transform.parent.parent;
Transform p = transform.parent;
p.parent;  // ← 这里报警

建议方案： MacroObject.GetParents() 扩展方法，返回 IEnumerable<Transform>。

---

XRX0002 — 重复调用 GetParents()

属性	值
分类	Performance
严重性	Warning

触发条件： 在同一方法中对同一对象调用 GetParents() 超过 1 次。

示例：

// 触发警告
transform.GetParents();
transform.GetParents();  // ← 第二次调用报警

建议方案： MacroObject.GetParentsSafety() 扩展方法，返回 IList<Transform> 可复用。

---

XRX0003 — 重复调用 GetChild()

属性	值
分类	Performance
严重性	Warning

触发条件： 在同一方法中对同一对象调用 Transform.GetChild() 超过 1 次。

示例：

// 触发警告
transform.GetChild(0);
transform.GetChild(1);  // ← 第二次调用报警

建议方案： MacroObject.GetChildren() 扩展方法，一次性获取所有子节点。

---

XRX0004 — for 循环 + GetChild 遍历子节点

属性	值
分类	Usage
严重性	Warning

触发条件： 使用 for (int i = 0; i < xxx.childCount; i++) 配合 GetChild(i) 遍历子节点。

示例：

// 触发警告
for (int i = 0; i < transform.childCount; i++)
{
    transform.GetChild(i);  // ← 建议替换为 foreach
}

建议方案： MacroObject.GetChildren() 扩展方法，配合 foreach 更简洁。

---

XRX0005 — 重复调用 GetChildren()

属性	值
分类	Performance
严重性	Warning

触发条件： 在同一方法中对同一对象调用 GetChildren() 超过 1 次。

示例：

// 触发警告
transform.GetChildren();
transform.GetChildren();  // ← 第二次调用报警

建议方案： MacroObject.GetChildrenSafety() 扩展方法，返回 IList<Transform> 可复用。

---

XRX0006 — GetChildren 后提取 gameObject

属性	值
分类	Usage
严重性	Warning

触发条件： 对 GetChildren() 结果使用 .Select(x => x.gameObject) 或 LINQ 查询提取 gameObject。

示例：

// 触发警告
transform.GetChildren().Select(c => c.gameObject);
// 或
from c in transform.GetChildren() select c.gameObject;

建议方案： MacroObject.GetChildrenGameObject() 扩展方法，直接返回 IEnumerable<GameObject>。

---

XRX0007 — 嵌套遍历子节点层级

属性	值
分类	Usage
严重性	Warning

触发条件： 嵌套调用 GetChildren() 或嵌套使用 for + GetChild 遍历多层子节点。

示例：

// 触发警告
foreach (var child in transform.GetChildren())
{
    foreach (var grandchild in child.GetChildren())  // ← 嵌套报警
    {
        // ...
    }
}

建议方案： MacroObject.GetChildrenBFS() 扩展方法，BFS 一步到位返回所有层级子节点。

---

XRX0008 — 在 parent 和 GetChild 之间跳跃访问

属性	值
分类	Usage
严重性	Warning

触发条件： 在同一方法中对同一对象同时访问 .parent 属性和调用 GetChild() 方法。

示例：

// 触发警告
var p = transform.parent;      // ← 访问父级
var c = transform.GetChild(0); // ← 访问子级
// 可能在寻找兄弟节点

建议方案： MacroObject.GetBrother() 扩展方法，返回所有兄弟节点。

---

XRX0009 — GetComponent 判空后 AddComponent

属性	值
分类	Usage
严重性	Warning

触发条件： 先调用 GetComponent<T>()，判空后再调用 AddComponent<T>() 的"获取或添加"模式。

示例：

// 触发警告
var comp = obj.GetComponent<Image>();
if (comp == null)
    comp = obj.AddComponent<Image>();

建议方案： MacroObject.GetComponentAnyway<T>() 扩展方法，一步完成获取或添加。

---

XRX0010 — 对枚举器逐项 GetComponent

属性	值
分类	Usage
严重性	Warning

触发条件： 在 .Select() / foreach / for 循环中对成员逐项调用 GetComponent。

示例：

// 触发警告
transform.GetChildren().Select(c => c.GetComponent<Image>());
// 或
foreach (var child in transform.GetChildren())
    child.GetComponent<Image>();  // ← 逐项报警

建议方案： MacroObject.IEnumerable.GetComponent<T>() 扩展方法，针对枚举器直接提取组件。

---

XRX0011 — 循环中查找特定组件后跳出

属性	值
分类	Usage
严重性	Warning

触发条件： 在循环中逐项 GetComponent 并在找到后判空 break 的"搜索组件"模式。

示例：

// 触发警告
Image found = null;
foreach (var child in transform.GetChildren())
{
    found = child.GetComponent<Image>();
    if (found != null) break;  // ← 搜索模式报警
}

建议方案： MacroObject.IEnumerable.GetComponent<T>(out T comp) 扩展方法，一次完成搜索。

---

XRX0012 — 通过名称查找返回对象

属性	值
分类	Usage
严重性	Warning

触发条件： 遍历子节点并比较 .name 来查找特定名称的对象（foreach + name == "xxx" + return）。

示例：

// 触发警告
foreach (var child in transform.GetChildren())
{
    if (child.name == "Target")      // ← 名称比较
        return child;                 // ← 找到返回
}
// 或 LINQ:
transform.GetChildren().FirstOrDefault(c => c.name == "Target");

建议方案： MacroObject.FindFamilyMember() / FindFamilyMemberExact() / FindFamilyMemberFuzzy() 扩展方法。

---

XRX0101 — 富文本字符串字面量

属性	值
分类	Usage
严重性	Warning

触发条件： 检测到字符串字面量中包含类似 XML 的 Unity 富文本标签（如 <b>, <color=...>, <line-height=...> 等）。

示例：

// 触发警告
var text = "<b>abc</b>";

建议方案： 使用 TextBlockBuilder 包裹器语法 或 BlockUtilKit 框架语法 进行类型安全构建：

// 优化为 TextBlockBuilder 语法
new TextBlockBuilder()
{
    new BBlock("abc")
}

// 优化为框架语法（配合 using static BlockUtilKit）
Pure(
    B(Label("abc"))
).BuildBlockByAgentOnce()

注意： 此规则提供两个 CodeFix 选项——"转换为 TextBlockBuilder 语法"和"转换为框架语法"，可通过 IDE 的自动修复功能直接应用。

---

规则索引

ID	规则标题	文件
XRX0001	重复访问 parent 属性	ObjectRelation
XRX0002	重复调用 GetParents()	ObjectRelation
XRX0003	重复调用 GetChild()	ObjectRelation
XRX0004	for 循环 + GetChild 遍历	ObjectRelation
XRX0005	重复调用 GetChildren()	ObjectRelation
XRX0006	GetChildren + Select gameObject	ObjectRelation
XRX0007	嵌套遍历子节点层级	ObjectRelation
XRX0008	parent 和 GetChild 跳跃访问	ObjectRelation
XRX0009	GetComponent + AddComponent	ComponentSearch
XRX0010	枚举器逐项 GetComponent	ComponentSearch
XRX0011	循环查找特定组件	ComponentSearch
XRX0012	名称查找返回对象	FamilyNaming
XRX0101	富文本字符串字面量	RichTextDetection