Sarmkadan/roslyn-guard-analyzer

# Roslyn Guard Analyzer    **一款为 .NET 项目打造的、基于 Roslyn 的生产级架构代码分析器** 通过灵活、可扩展的分析引擎，在整个代码库中强制执行架构规则、命名规范、异步模式和空安全。专为高度重视代码质量的团队而构建。 ## 目录 - [概述](#overview) - [功能](#features) - [快速开始](#quick-start) - [安装说明](#installation) - [使用示例](#usage-examples) - [架构](#architecture) - [API 参考](#api-reference) - [配置参考](#configuration-reference) - [CLI 参考](#cli-reference) - [故障排除](#troubleshooting) - [测试](#testing) - [性能](#performance) - [文档](#documentation) - [相关项目](#related-projects) - [贡献](#contributing) ## 概述 Roslyn Guard Analyzer 是一款全面的静态分析工具，用于在 .NET 代码库中强制执行架构模式和最佳实践。它构建于 Microsoft Roslyn 编译器平台之上，提供深入的语法和语义分析功能，以便在问题进入生产环境之前识别出违规情况。 ### 为什么选择 Roslyn Guard Analyzer？ - **架构强制执行**：定义并强制执行层级依赖关系，防止循环依赖和架构违规 - **命名规范验证**：自动在整个代码库中强制执行一致的命名模式 - **异步模式检测**：识别不正确的 async/await 模式、阻塞调用和 Task 处理问题 - **空安全验证**：强制执行可空引用类型模式和空安全最佳实践 - **团队可扩展性**：作为 CI/CD pipeline 的一部分运行分析，以维护跨分布式团队的标准 - **零配置**：开箱即用，具有合理的默认设置 - **完全可定制**：定义量身定制的自定义规则以满足您的架构需求 - **多种输出格式**：生成 Text、JSON、CSV、XML 和 HTML 格式的报告 ### 完美适用于 - 维护共享架构标准的大型团队 - 需要严格分层隔离的微服务架构 - 采用 async/await 优先模式的项目 - 实现可空引用类型的团队 - 用于代码质量阈值的 CI/CD 集成 ## 功能 ### 核心分析能力 | 功能 | 描述 | |---------|-------------| | **层级依赖分析** | 强制执行架构分层并防止非法的跨层依赖 | | **命名规范强制执行** | 验证类、方法、属性和字段的命名规范 | | **异步模式检测** | 识别异步上下文中不正确的 async/await 模式和阻塞调用 | | **空安全验证** | 强制执行可空引用类型处理和空安全模式 | | **项目分析** | 通过自动文件发现和并行处理来分析整个项目 | | **多格式报告** | 生成 Text、JSON、CSV、XML 和 HTML 格式的报告 | | **规则注册表** | 用于定义自定义架构规则的可扩展规则系统 | | **配置管理** | 具有规则自定义功能的灵活配置系统 | | **性能指标** | 内置性能分析和分析统计 | | **事件驱动架构** | 用于可扩展性和监控的发布/订阅系统 | ### 内置规则 该分析器附带了四项涵盖最常见架构问题的基础规则： | 规则 ID | 类别 | 描述 | |---------|----------|-------------| | `LYR001` | 层级依赖 | 防止 repository 依赖 service 或 controller | | `NAM001` | 命名规范 | 强制类/方法使用 PascalCase，字段使用 snake_case | | `ASY001` | 异步模式 | 验证 async/await 模式和正确的 Task 处理 | | `NUL001` | 空安全 | 检查可空引用类型处理和空合并模式 | ## 高级功能 ### 自定义规则构建器 DSL 使用流式 API 定义基于谓词的规则，并像内置规则一样注册它们： ``` var rule = CustomRuleBuilder.Create("CUS001", "Async suffix rule") .For(RuleCategory.AsyncPattern) .WithSeverity(SeverityLevel.Warning) .WithDescription("Requires async methods to end with Async") .When(element => element.ElementType == CodeElementType.Method && element.IsAsync && !element.Name.EndsWith("Async")) .WithMessage(element => $"Method '{element.Name}' must end with Async") .Build(); ruleRegistry.RegisterRule(rule); var violations = await ruleEngine.ExecuteRuleAsync(rule, elements); ``` ### 抑制管理器 持久化规则抑制并过滤掉已知例外，包含理由和可选的过期时间： ``` var suppression = new SuppressionRecord { RuleId = "LYR001", TargetFile = "src/Legacy/LegacyRepository.cs", Justification = "Legacy dependency scheduled for refactor", Author = "team-maintainer", CreatedAt = DateTime.UtcNow, ExpiresAt = DateTime.UtcNow.AddDays(30), IsActive = true }; suppressionManager.AddSuppression(suppression); await suppressionManager.SaveAsync("suppressions.json"); await suppressionManager.LoadAsync("suppressions.json"); var visibleViolations = suppressionManager.FilterSuppressed(violations); ``` ### 全部修复提供程序 预览或应用批量修复，带有严重程度和规则过滤器： ``` var result = await fixAllProvider.ApplyAllAsync( violations, new FixAllOptions { DryRun = false, MinimumSeverity = SeverityLevel.Warning, RuleIds = new[] { "RG-N001", "RG-A001" }, SkipBreakingChanges = true, MaxFixes = 25 }); ``` ### 诊断代码示例 #### LYR001: 层级依赖 **不合规：** ``` public class UserRepository { private readonly UserService _service; // RGD001: Repository depends on service } ``` **合规：** ``` public class UserService { private readonly UserRepository _repository; // OK } ``` #### NAM001: 命名规范 **不合规：** ``` public class my_class { private int PublicField; } ``` **合规：** ``` public class MyClass { private int _publicField; } ``` #### ASY001: 异步模式 (RGD003, RGD004) **不合规：** ``` public Task DoWork() // Returns Task but not marked async { return Task.FromResult(0); } public async Task DoWork2() // Missing Async suffix { } ``` **合规：** ``` public async Task DoWorkAsync() { } ``` #### NUL001: 空安全 (RGD008, RGD009) **不合规：** ``` public class MyClass { public string Name { get; set; } // Non-nullable without initialization } ``` **合规：** ``` public class MyClass { public string Name { get; set; } = string.Empty; // Initialized } ``` ## 快速开始 ### 前置条件 - **.NET 10.0** 或更高版本 - **C# 语言支持**（最新语言特性） - Visual Studio Code、Visual Studio 或任何 .NET IDE ### 一条命令安装 ``` # Clone 和 build git clone https://github.com/sarmkadan/roslyn-guard-analyzer.git cd roslyn-guard-analyzer dotnet build -c Release # 对 project 运行分析 dotnet run --project src/RoslynGuardAnalyzer -- /path/to/your/project.csproj ``` ### 30 秒示例 ``` # 分析你当前的 project cd ~/MyProject roslyn-guard-analyzer . # 以 JSON 格式查看结果 roslyn-guard-analyzer . --format json # 导出到文件 roslyn-guard-analyzer . --output analysis-report.json ``` ## 安装说明 ### 方法 1：从源码克隆并构建 ``` git clone https://github.com/sarmkadan/roslyn-guard-analyzer.git cd roslyn-guard-analyzer dotnet build -c Release # 创建一个方便的 alias alias roslyn-guard='dotnet /path/to/roslyn-guard-analyzer/src/RoslynGuardAnalyzer/bin/Release/net10.0/RoslynGuardAnalyzer.dll' ``` ### 方法 2：NuGet 包（发布后） ``` dotnet tool install --global roslyn-guard-analyzer roslyn-guard-analyzer --version ``` ### 方法 3：Docker 容器 在容器化环境中运行分析器，无需安装 .NET： ``` # Build Docker image docker build -t roslyn-guard-analyzer . # 快速开始：分析此 repository # (挂载当前目录并分析 analyzer 本身) docker run --rm -v $(pwd):/workspace roslyn-guard-analyzer /workspace/src/RoslynGuardAnalyzer/RoslynGuardAnalyzer.csproj # 分析你自己的 project (将 PROJECT_PATH 替换为你的 .csproj 文件或目录) docker run --rm -v /path/to/your/project:/workspace roslyn-guard-analyzer /workspace/YourProject.csproj # 或者在更复杂的场景中使用 docker-compose # 复制并自定义 docker-compose 配置 cp docker-compose.yml docker-compose.override.yml # 编辑 docker-compose.override.yml 以设置你的 project 路径 nano docker-compose.override.yml # 运行 analyzer docker-compose up analyzer # 在 detached mode 中运行 docker-compose up -d analyzer ``` **使用说明：** - Docker 镜像包含 Roslyn Guard Analyzer CLI 工具 - 使用 `-v` 标志挂载您的源代码以分析您的项目 - 容器以非 root 用户运行以确保安全 - 配置了资源限制以实现最佳性能 - 报告可以保存到 `./reports` 目录 ### 方法 4：使用 Makefile ``` make build make install roslyn-guard-analyzer --help ``` ## 使用示例 ### 示例 1：基本项目分析 分析整个项目目录： ``` roslyn-guard-analyzer ~/MyProject # 输出： # === Roslyn Guard Analyzer === # 正在开始架构 rule 分析... # # File: src/Domain/UserRepository.cs:42 # Rule: LYR001 (Layer Dependencies) # Violation: Repository 依赖于 service 层 # # 分析完成：发现 3 个 violation ``` ### 示例 2：分析特定文件 ``` roslyn-guard-analyzer ~/MyProject/src/Services/UserService.cs ``` ### 示例 3：用于工具集成的 JSON 输出 ``` roslyn-guard-analyzer ~/MyProject --format json > analysis.json # 内容： # { # "timestamp": "2026-05-04T10:30:00Z", # "projectPath": "/home/user/MyProject", # "totalFilesAnalyzed": 125, # "violations": [ # { # "ruleId": "LYR001", # "category": "Layer Dependencies", # "filePath": "src/Domain/UserRepository.cs", # "line": 42, # "column": 5, # "message": "Repository class depends on service layer", # "severity": "error" # } # ] # } ``` ### 示例 4：用于电子表格分析的 CSV 导出 ``` roslyn-guard-analyzer ~/MyProject --format csv --output violations.csv # 在 Excel/Sheets 中打开以进行排序和筛选： # RuleID,Category,File,Line,Column,Message,Severity # LYR001,Layer Dependencies,src/Domain/UserRepository.cs,42,5,Repository depends on service,error # NAM001,Naming,src/Services/userService.cs,15,7,Field should be snake_case,warning ``` ### 示例 5：生成 HTML 报告 ``` roslyn-guard-analyzer ~/MyProject --format html --output report.html open report.html ``` ### 示例 6：按规则过滤 ``` # 仅分析 naming convention violations roslyn-guard-analyzer ~/MyProject --rules NAM001 # 分析多个特定的 rule roslyn-guard-analyzer ~/MyProject --rules LYR001,ASY001 ``` ### 示例 7：严格模式（遇到任何违规即失败） ``` roslyn-guard-analyzer ~/MyProject --strict # 如果发现任何 violations，Exit code 为 1 ``` ### 示例 8：自定义配置文件 创建 `.roslyn-guard.json`： ``` { "projectPath": "./src", "analysisTimeout": 600, "maxViolationsToReport": 1000, "rules": { "LYR001": { "enabled": true, "severity": "error" }, "NAM001": { "enabled": true, "severity": "warning" }, "ASY001": { "enabled": false }, "NUL001": { "enabled": true, "severity": "error" } }, "excludePatterns": [ "**/bin/**", "**/obj/**", "**/*.Generated.cs" ] } ``` ``` roslyn-guard-analyzer --config .roslyn-guard.json ``` ### 示例 9：持续集成 Pipeline GitHub Actions 工作流： ``` - name: Run Roslyn Guard Analyzer run: | dotnet run --project RoslynGuardAnalyzer -- ./src \ --format json \ --output analysis.json # Fail if critical violations found if [ $(jq '.violations | map(select(.severity=="error")) | length' analysis.json) -gt 0 ]; then echo "Architecture violations found!" exit 1 fi ``` ### 示例 10：自定义规则集成 通过扩展 `AnalysisRule` 实现自定义规则： ``` public class CustomLayerRule : AnalysisRule { public override string Id => "CUSTOM001"; public override string Category => "Custom"; public override string Description => "Enforce custom architectural rule"; public override async Task> ValidateAsync( CodeElement element, RuleConfiguration config) { var violations = new List(); // Implement your custom logic if (element.Name.Contains("Temp")) { violations.Add(new RuleViolation { RuleId = Id, FilePath = element.FilePath, Line = element.Line, Message = "Temporary classes should not be committed" }); } return violations; } } ``` ## 基于代码的示例 除了基于 CLI 的示例外，您还可以将 Roslyn Guard Analyzer 直接集成到您的 .NET 应用程序中。请在 [examples/](./examples/) 目录中查看以下示例： - [BasicUsage.cs](./examples/BasicUsage.cs)：演示了最小设置和运行基本项目分析。 - [AdvancedUsage.cs](./examples/AdvancedUsage.cs)：展示了如何使用自定义配置、自定义规则注册、抑制管理以及全部修复提供程序。 - [IntegrationExample.cs](./examples/IntegrationExample.cs)：说明了如何将分析器接入 ASP.NET Core DI 容器。 ## 架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ Roslyn Guard Analyzer │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ CLI & Command Processing │ │ │ │ (CliArgumentParser, CliOptions, CommandLineProcessor) │ │ │ └──────────────────────────────────────────────────────┘ │ │ ↓ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Configuration & Validation Layer │ │ │ │ (ConfigurationLoader, ConfigurationValidator) │ │ │ └──────────────────────────────────────────────────────┘ │ │ ↓ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Analysis Middleware Pipeline │ │ │ │ • ErrorHandling │ │ │ │ • Logging │ │ │ │ • PerformanceMetrics │ │ │ └──────────────────────────────────────────────────────┘ │ │ ↓ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Core Analysis Service Layer │ │ │ │ • AnalysisService (Orchestration) │ │ │ │ • RuleEngine (Rule Execution) │ │ │ │ • RuleRegistry (Rule Management) │ │ │ │ • DiagnosticsService (Roslyn Integration) │ │ │ └──────────────────────────────────────────────────────┘ │ │ ↓ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Domain Models & Entities │ │ │ │ • AnalysisRule │ │ │ │ • RuleViolation │ │ │ │ • CodeElement │ │ │ │ • AnalysisResult │ │ │ │ • ViolationReport │ │ │ └──────────────────────────────────────────────────────┘ │ │ ↓ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Output Formatting & Reporting │ │ │ │ • JsonFormatter │ │ │ │ • CsvFormatter │ │ │ │ • HtmlFormatter │ │ │ │ • FormatterRegistry │ │ │ └──────────────────────────────────────────────────────┘ │ │ ↓ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Data Persistence Layer │ │ │ │ • AnalysisResultRepository │ │ │ │ • ProjectRepository │ │ │ │ • RuleRepository │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Cross-Cutting Concerns │ │ │ │ • EventBus (Pub/Sub) │ │ │ │ • CacheService │ │ │ │ • BackgroundTaskQueue │ │ │ │ • WebhookHandler │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### 层级职责 **CLI 层**：解析命令行参数，处理用户交互，并委托给服务 **配置层**：从文件和环境变量加载并验证配置 **中间件 Pipeline**：横切关注点（日志记录、错误处理、性能指标） **分析层**：用于规则执行和违规检测的核心业务逻辑 **领域层**：不依赖基础设施的纯业务实体 **Repository 层**：对数据存储的抽象（目前为内存中，可扩展） **输出层**：格式化结果以供不同工具和用户使用 ## API 参考 ### IAnalysisService 用于编排分析工作流的主服务。 ``` public interface IAnalysisService { ///

/// Analyzes a project or file asynchronously ///

/// Path to project.csproj or individual .cs file /// Analysis results including violations found Task AnalyzeProjectAsync(string projectPath); ///

/// Analyzes with custom configuration ///

Task AnalyzeWithConfigAsync( string projectPath, RuleConfiguration configuration); } ``` ### IRuleRegistry 管理可用的规则及其配置。 ``` public interface IRuleRegistry { ///

/// Gets all registered rules ///

IEnumerable GetAllRules(); ///

/// Registers a new rule ///

void RegisterRule(AnalysisRule rule); ///

/// Gets a specific rule by ID ///

AnalysisRule? GetRule(string ruleId); ///

/// Enables or disables a rule ///

void SetRuleEnabled(string ruleId, bool enabled); } ``` ### IRuleEngine 针对代码元素执行规则。 ``` public interface IRuleEngine { ///

/// Executes all enabled rules against a code element ///

/// Violations found by all rules Task> ExecuteRulesAsync( CodeElement element); ///

/// Executes a specific rule ///

Task> ExecuteRuleAsync( string ruleId, CodeElement element); } ``` ### IReportingService 根据分析结果生成格式化的报告。 ``` public interface IReportingService { ///

/// Generates a human-readable text report ///

string GenerateReport(AnalysisResult result); ///

/// Generates a JSON report ///

string GenerateJsonReport(AnalysisResult result); ///

/// Generates a CSV report ///

string GenerateCsvReport(AnalysisResult result); ///

/// Generates an HTML report ///

string GenerateHtmlReport(AnalysisResult result); } ``` ### IValidationService 验证配置和代码元素。 ``` public interface IValidationService { ///

/// Validates a rule configuration ///

/// Validation errors, empty if valid IEnumerable ValidateConfiguration(RuleConfiguration config); ///

/// Validates a code element ///

bool IsValidCodeElement(CodeElement element); } ``` ### 领域模型 #### AnalysisRule 用于实现自定义规则的基类： ``` public abstract class AnalysisRule { public abstract string Id { get; } public abstract string Category { get; } public abstract string Description { get; } public virtual RuleSeverity DefaultSeverity => RuleSeverity.Error; public abstract Task> ValidateAsync( CodeElement element, RuleConfiguration config); } ``` #### RuleViolation 代表单个违规： ``` public class RuleViolation { public string RuleId { get; set; } public string FilePath { get; set; } public int Line { get; set; } public int Column { get; set; } public string Message { get; set; } public RuleSeverity Severity { get; set; } public CodeElement? Element { get; set; } } ``` #### AnalysisResult 分析的完整结果： ``` public class AnalysisResult { public string ProjectPath { get; set; } public DateTime TimestampUtc { get; set; } public int TotalFilesAnalyzed { get; set; } public List Violations { get; set; } public int ViolationCount => Violations.Count; public AnalysisStatistics Statistics { get; set; } } ``` ## 配置参考 ### JSON 配置文件格式 在您的项目根目录中创建 `.roslyn-guard.json`： ``` { "projectPath": "./src", "analysisTimeout": 600, "maxViolationsToReport": 1000, "logLevel": 2, "rules": { "LYR001": { "enabled": true, "severity": "error", "configuration": { "allowedDependencies": ["Domain", "Infrastructure"] } }, "NAM001": { "enabled": true, "severity": "warning" }, "ASY001": { "enabled": true, "severity": "error" }, "NUL001": { "enabled": true, "severity": "warning" } }, "excludePatterns": [ "**/bin/**", "**/obj/**", "**/*.Generated.cs", "**/*.Designer.cs" ] } ``` ### 配置属性 | 属性 | 类型 | 默认值 | 描述 | |----------|------|---------|-------------| | `projectPath` | string | `./` | 分析的根路径 | | `analysisTimeout` | int | `600` | 超时时间（秒） | | `maxViolationsToReport` | int | `500` | 报告中包含的最大违规数量 | | `logLevel` | int | `2` | 详细程度（0=无，1=错误，2=警告，3=信息，4=调试） | | `excludePatterns` | string[] | `["**/bin/**", "**/obj/**"]` | 要排除的 Glob 模式 | ### 规则配置 每个规则都可以单独配置： ``` { "rules": { "LYR001": { "enabled": true, "severity": "error" } } } ``` ## CLI 参考 ### 全局选项 ``` roslyn-guard-analyzer [options] ``` | 选项 | 简写 | 描述 | |--------|-------|-------------| | `--format` | `-f` | 输出格式：`text`、`json`、`csv`、`xml`、`html` | | `--output` | `-o` | 输出文件路径（可选） | | `--config` | `-c` | 配置文件路径 | | `--rules` | `-r` | 要执行的逗号分隔规则 ID | | `--strict` | `-s` | 遇到任何违规即失败（退出码 1） | | `--quiet` | `-q` | 禁止控制台输出 | | `--verbose` | `-v` | 详细日志记录 | | `--help` | `-h` | 显示帮助信息 | | `--version` | | 显示版本信息 | ### 示例 ``` # 使用默认设置进行基本分析 roslyn-guard-analyzer ./src # 用于 CI/CD 的 JSON 输出 roslyn-guard-analyzer ./src -f json -o report.json # 仅限特定的 rule roslyn-guard-analyzer ./src -r LYR001,NAM001 # 使用 config 文件 roslyn-guard-analyzer -c ./analyzer.json # 用于 debugging 的 Verbose output roslyn-guard-analyzer ./src -v # 如果发现 violations 则失败 roslyn-guard-analyzer ./src -s && echo "Analysis passed" || echo "Violations found" ``` ## 故障排除 ### 问题：“找不到项目路径” **解决方案**：验证路径是否存在且可访问： ``` ls -la /path/to/project.csproj roslyn-guard-analyzer /path/to/project.csproj ``` ### 问题：“未发现违规，但预期会有一些” **解决方案**：检查配置中是否启用了规则： ``` # Verbose output 显示哪些 rule 处于活动状态 roslyn-guard-analyzer ./src -v # 验证 rule 未被禁用 cat .roslyn-guard.json | grep -A2 '"LYR001"' ``` ### 问题：“分析超时” **解决方案**：在配置中增加超时时间： ``` { "analysisTimeout": 1800 } ``` ### 问题：“大型项目内存不足” **解决方案**：分批分析文件： ``` # 一次分析一个目录 roslyn-guard-analyzer ./src/Domain roslyn-guard-analyzer ./src/Services roslyn-guard-analyzer ./src/Presentation ``` ### 问题：“生成的代码中出现误报” **解决方案**：排除生成的文件： ``` { "excludePatterns": [ "**/*.Generated.cs", "**/*.Designer.cs", "**/obj/**" ] } ``` ### 问题：“自定义规则未执行” **解决方案**：验证规则是否已注册： ``` var ruleRegistry = serviceProvider.GetRequiredService(); var myRule = ruleRegistry.GetRule("CUSTOM001"); if (myRule == null) throw new Exception("Rule not registered"); ``` ## 测试 测试套件涵盖了规则引擎、字符串实用程序和类型名称匹配逻辑。 ### 运行测试 ``` # 运行所有测试 dotnet test # 运行带 verbose output 的测试 dotnet test --logger "console;verbosity=detailed" # 运行带 coverage 的测试 dotnet test --collect:"XPlat Code Coverage" ``` ### 测试结构 | 测试文件 | 涵盖内容 | |-----------|----------------| | `RuleRegistryTests.cs` | 规则注册、查找、启用/禁用 | | `StringExtensionsTests.cs` | 分析中使用的字符串实用程序助手 | | `TypeNameMatcherTests.cs` | 规则评估中类型名称的模式匹配 | ### 为自定义规则编写测试 ``` [Fact] public async Task MyCustomRule_WhenNameContainsTemp_ReturnsViolation() { var rule = new MyCustomRule(); var element = new CodeElement { Name = "TempService", FilePath = "src/TempService.cs", Line = 1 }; var config = new RuleConfiguration { Enabled = true }; var violations = await rule.ValidateAsync(element, config); Assert.Single(violations); Assert.Equal("CUSTOM001", violations.First().RuleId); } ``` ## 性能 Roslyn Guard Analyzer 专为快速、低开销的分析而设计，适用于本地开发和 CI/CD pipeline。 ### 基准测试 | 场景 | 平均值 | 误差 | 标准差 | 已分配内存 | |----------|-----:|------:|-------:|----------:| | 单条规则执行 | 6.841 us | 0.136 us | 0.228 us | 2.98 KB | | 完整规则套件执行 | 18.102 us | 0.358 us | 0.815 us | 8.76 KB | *基准测试在 .NET 10.0、AMD EPYC-Rome 处理器、Ubuntu 26.04 上测量。* 您可以使用 `tests/roslyn-guard-analyzer.Benchmarks` 项目自行运行这些基准测试： ``` dotnet run --project tests/roslyn-guard-analyzer.Benchmarks/roslyn-guard-analyzer.Benchmarks.csproj -c Release ``` ## 文档 [`/`](./docs/) 目录中提供了详细指南： | 文档 | 描述 | |---|---| | [入门指南](./docs/getting-started.md) | 安装、首次分析和内置规则 | | [自定义规则开发](./docs/custom-rule-development.md) | 编写、配置和测试您自己的规则 | | [API 参考](./docs/api-reference.md) | 完整的接口和模型文档 | | [架构指南](./docs/architecture.md) | 内部设计决策 | | [部署指南](./docs/deployment.md) | CI/CD 和生产环境设置 | | [常见问题解答](./docs/faq.md) | 常见问题和故障排除 | | [v2 迁移指南](./docs/MIGRATION_v2.md) | 从 v1 升级到 v2 | ## 相关项目 这是一系列 .NET 库和工具的一部分。在 [github.com/sarmkadan](https://github.com/sarmkadan) 查看更多内容。 ### 集成示例 **将分析器嵌入自定义构建工具或 pre-commit 钩子中：** ``` var host = Host.CreateDefaultBuilder() .ConfigureServices(services => services.AddRoslynGuardAnalyzer()) .Build(); var analyzer = host.Services.GetRequiredService(); var result = await analyzer.AnalyzeProjectAsync("./src/MyApp.csproj"); if (result.Violations.Any(v => v.Severity == RuleSeverity.Error)) Environment.Exit(1); ``` **在内置规则集旁注册特定于项目的规则：** ``` var registry = host.Services.GetRequiredService(); registry.RegisterRule(new DomainEventsNamingRule()); // custom rule registry.RegisterRule(new OutboxPatternRule()); // custom rule var engine = host.Services.GetRequiredService(); var violations = await engine.ExecuteRulesAsync(codeElement); Console.WriteLine($"{violations.Count()} violation(s) found."); ``` ## 贡献 欢迎贡献！以下是入门指南： ### 开发设置 ``` git clone https://github.com/sarmkadan/roslyn-guard-analyzer.git cd roslyn-guard-analyzer dotnet restore dotnet build ``` ### 添加自定义规则 1. 在 `src/RoslynGuardAnalyzer/Rules/` 中创建一个规则类： ``` public class MyCustomRule : AnalysisRule { public override string Id => "CUSTOM001"; public override string Category => "Custom"; public override string Description => "My custom rule"; public override async Task> ValidateAsync( CodeElement element, RuleConfiguration config) { // Implementation here return new List(); } } ``` 2. 在 `ServiceCollectionExtensions.cs` 中注册它： ``` services.AddSingleton(); ``` 3. 在 `tests/` 目录中添加测试 4. 提交包含以下内容的 pull request： - 规则实现 - 单元测试（>80% 覆盖率） - 文档 - 使用示例 ### 报告问题 请包括： - .NET 版本 - 项目类型（.csproj 结构） - 复现步骤 - 预期与实际的行为对比 - 配置文件（如果适用） ### 代码风格 - 遵循 C# 命名规范 - 全面使用 async/await - 添加 XML 文档注释 - 最低目标定为 .NET 10.0 - 启用可空引用类型 ## 许可证 MIT 许可证 - 版权所有 © 2026 Vladyslav Zaiets 特此免费授予任何获得本软件及相关文档文件（以下简称“软件”）副本的人，不受限制地处理本软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利，并允许向其提供软件的人这样做，但须符合以下条件： 上述版权声明和本许可声明应包含在软件的所有副本或实质性部分中。 有关完整详细信息，请参阅 [LICENSE](LICENSE)。 **由 [Vladyslav Zaiets](https://sarmkadan.com) 构建 - CTO 兼软件架构师** [作品集](https://sarmkadan.com) | [GitHub](https://github.com/Sarmkadan) | [Telegram](https://t.me/sarmkadan)

标签：LNA, Roslyn, SOC Prime, 代码规范, 多人体追踪, 开发工具, 架构守护, 请求拦截, 错误基检测, 静态代码分析