rodri-oliveira-dev/Swa.Analyzers
GitHub: rodri-oliveira-dev/Swa.Analyzers
一套面向 .NET 的 Roslyn 分析器集合，用于在编码阶段强制执行架构约定、可靠性要求、安全规范和测试质量标准。
Stars: 2 | Forks: 0
# Swa.Analyzers
用于 .NET 的可重用 Roslyn 分析器，重点关注架构约定、可靠性和测试质量。
## 项目
- `src/Swa.Analyzers.Core`：分析器和诊断描述符的实现。
- `src/Swa.Analyzers.CodeFixes`：随包分发的代码修复实现。
- `tests/Swa.Analyzers.Tests`：分析器的自动化测试。
- `src/Swa.Analyzers.SampleApp`：每条规则的有效和无效手动示例。
每条规则在 [docs/rules](docs/rules) 中都有独立的文档。包发布的诊断信息使用指向这些文件的绝对 *help links*，以便在通过 NuGet 分发分析器时便于访问。
要将此包引入现有项目，请参阅[渐进式采用指南](docs/adoption.md)，其中包含严重性、抑制(suppressions)和遗留代码处理的示例。如果您想直接使用现成的策略，请使用[通过 `.editorconfig` 采用的配置文件](docs/editorconfig-profiles.md)。
## 代码修复
一些机械性规则在 IDE 中提供了安全的代码修复。目前已为 `ARCH001` 提供初始支持，当规则已排除标准事件处理程序和 interface/override 契约时，它将诊断出的具体方法和 `async void` 局部函数转换为 `async Task`。
## 现有规则
| ID | 标题（摘要） | 类别 | 默认严重性 | 文档 |
| ------- | ------------------------------------------------ | ----------- | ----------------- | -------------------------------- |
| ARCH001 | Avoid async void outside event handlers | Reliability | Warning | [ARCH001](docs/rules/ARCH001.md) |
| ARCH002 | Avoid Task.ContinueWith | Reliability | Warning | [ARCH002](docs/rules/ARCH002.md) |
| ARCH003 | Prohibit NotBeNull() in tests | TestQuality | Info | [ARCH003](docs/rules/ARCH003.md) |
| ARCH004 | Enforce _sut naming in unit tests | TestQuality | Info | [ARCH004](docs/rules/ARCH004.md) |
| ARCH005 | Restrict usage of NSubstitute Arg.Any() | TestQuality | Info | [ARCH005](docs/rules/ARCH005.md) |
| ARCH006 | Warn on exclusions in BeEquivalentTo() | TestQuality | Info | [ARCH006](docs/rules/ARCH006.md) |
| ARCH007 | Detect string concatenation inside loops | Performance | Info | [ARCH007](docs/rules/ARCH007.md) |
| ARCH008 | Prohibit manual path composition | Reliability | Info | [ARCH008](docs/rules/ARCH008.md) |
| ARCH009 | Prohibit sync over async blocking calls | Reliability | Warning | [ARCH009](docs/rules/ARCH009.md) |
| ARCH010 | Enforce CancellationToken propagation | Reliability | Warning | [ARCH010](docs/rules/ARCH010.md) |
| ARCH011 | Prohibit async or blocking logic in constructors | Reliability | Warning | [ARCH011](docs/rules/ARCH011.md) |
| ARCH012 | Prefer DateTimeOffset over DateTime | Reliability | Info | [ARCH012](docs/rules/ARCH012.md) |
| ARCH013 | Restrict mocking frameworks to NSubstitute | TestQuality | Info | [ARCH013](docs/rules/ARCH013.md) |
| ARCH014 | Prefer Is.Equivalent over NSubstitute Arg.Is | TestQuality | Info | [ARCH014](docs/rules/ARCH014.md) |
| ARCH015 | Prohibit verbs in HTTP routes | Design | Warning | [ARCH015](docs/rules/ARCH015.md) |
| ARCH016 | Avoid Task.Run in ASP.NET request flow | Performance | Warning | [ARCH016](docs/rules/ARCH016.md) |
| ARCH017 | Prohibit fire-and-forget in request flow | Reliability | Warning | [ARCH017](docs/rules/ARCH017.md) |
| ARCH018 | Avoid direct HttpClient instantiation | Reliability | Warning | [ARCH018](docs/rules/ARCH018.md) |
| ARCH019 | Avoid Authorize with AllowAnonymous | Security | Warning | [ARCH019](docs/rules/ARCH019.md) |
| ARCH020 | Require explicit endpoint authorization | Security | Warning | [ARCH020](docs/rules/ARCH020.md) |
| ARCH021 | Prefer AsNoTracking for read-only EF queries | Performance | Warning | [ARCH021](docs/rules/ARCH021.md) |
| ARCH022 | Avoid premature query materialization | Performance | Warning | [ARCH022](docs/rules/ARCH022.md) |
| ARCH023 | Prefer TimeProvider for current time | Testability | Warning | [ARCH023](docs/rules/ARCH023.md) |
| ARCH024 | Avoid interpolated strings in ILogger calls | Observability | Warning | [ARCH024](docs/rules/ARCH024.md) |
| ARCH025 | Enforce matching ILogger category | Observability | Warning | [ARCH025](docs/rules/ARCH025.md) |
| ARCH026 | Avoid insecure CORS configuration | Security | Warning | [ARCH026](docs/rules/ARCH026.md) |
| ARCH027 | Prevent infrastructure dependencies in core layers | Architecture | Warning | [ARCH027](docs/rules/ARCH027.md) |
| ARCH028 | Prohibit mutable properties in records | Design | Warning | [ARCH028](docs/rules/ARCH028.md) |
| ARCH029 | Prohibit public setters in domain entities | Design | Warning | [ARCH029](docs/rules/ARCH029.md) |
| ARCH030 | Detect duplicated PackageReference across projects | Maintainability | Info | [ARCH030](docs/rules/ARCH030.md) |
| ARCH031 | Prefer System.Threading.Lock over object locks | Performance | Warning | [ARCH031](docs/rules/ARCH031.md) |
| ARCH032 | Avoid duplicated MSBuild properties | Maintainability | Info | [ARCH032](docs/rules/ARCH032.md) |
| ARCH033 | Avoid BuildServiceProvider during service registration | Reliability | Warning | [ARCH033](docs/rules/ARCH033.md) |
## 配置说明
### 前置条件
- .NET SDK 10.x，由仓库的 `global.json` 固定版本。
像往常一样通过 `.editorconfig` 配置严重性：
```
[*.cs]
dotnet_diagnostic.ARCH001.severity = warning
dotnet_diagnostic.ARCH008.severity = info
```
某些规则支持通过 `.editorconfig` 设置的自定义选项。`ARCH015` 的示例：
```
[*.cs]
dotnet_diagnostic.ARCH015.route_language = pt-BR
dotnet_diagnostic.ARCH015.additional_verbs = ["ativar", "inativar", "recalcular"]
```
`ARCH020` 的示例：
```
[*.cs]
dotnet_diagnostic.ARCH020.allowed_routes = ["/internal/status", "/diagnostics/*"]
dotnet_diagnostic.ARCH020.allowed_methods = ["Ping"]
dotnet_diagnostic.ARCH020.ignored_namespaces = ["Sample.PublicEndpoints"]
```
`ARCH023` 的示例：
```
[*.cs]
dotnet_diagnostic.ARCH023.allowed_namespaces = ["MyApp.Infrastructure.Time"]
dotnet_diagnostic.ARCH023.allowed_types = ["MachineTimeSource"]
dotnet_diagnostic.ARCH023.ignore_simple_logging = true
```
`ARCH026` 的示例：
```
[*.cs]
dotnet_diagnostic.ARCH026.disallow_any_origin = true
```
`ARCH027` 的示例：
```
[*.cs]
dotnet_diagnostic.ARCH027.core_namespace_patterns = "*.Domain;*.Application"
dotnet_diagnostic.ARCH027.forbidden_namespace_patterns = "Microsoft.EntityFrameworkCore;Microsoft.AspNetCore;StackExchange.Redis;Npgsql"
dotnet_diagnostic.ARCH027.allowed_namespace_patterns =
dotnet_diagnostic.ARCH027.ignore_tests = true
```
`ARCH028` 的示例：
```
[*.cs]
dotnet_diagnostic.ARCH028.allow_non_public_setters = true
```
`ARCH029` 的示例：
```
[*.cs]
dotnet_diagnostic.ARCH029.entity_namespaces = ["MyApp.Domain.Entities", "MyApp.Domain.Aggregates"]
dotnet_diagnostic.ARCH029.entity_base_types = ["Entity", "AggregateRoot"]
dotnet_diagnostic.ARCH029.allow_internal_setters = false
```
`ARCH030` 的示例：
```
[*.csproj]
dotnet_diagnostic.ARCH030.allowed_packages = ["Microsoft.NET.Test.Sdk", "xunit", "coverlet.collector"]
dotnet_diagnostic.ARCH030.allowed_project_patterns = ["*.Tests.csproj", "*.Benchmarks.csproj"]
```
`ARCH031` 的示例：
```
[*.cs]
dotnet_diagnostic.ARCH031.minimum_target_framework = net9.0
dotnet_diagnostic.ARCH031.report_local_variables = true
```
`ARCH032` 的示例：
```
[*.csproj]
dotnet_diagnostic.ARCH032.ignored_properties = ["TargetFramework", "TargetFrameworks", "AssemblyName", "RootNamespace"]
dotnet_diagnostic.ARCH032.compare_values = true
```
`ARCH033` 的示例：
```
[*.cs]
dotnet_diagnostic.ARCH033.ignore_tests = true
```
每条规则的页面都记录了公共选项的回退机制，包括默认值、空值处理、无效值处理、意外的大小写以及格式错误的 JSON（如果适用）。通常，格式错误的 JSON 数组会被忽略，无效的布尔值会恢复为规则的默认值。
## 验证说明
- **还原**：`dotnet restore ./Swa.Analyzers.slnx`
- **构建**：`dotnet build ./Swa.Analyzers.slnx --configuration Release --no-restore`
- **测试**：`dotnet test ./Swa.Analyzers.slnx --configuration Release --no-build -m:1`（当 MSBuild 使用多个节点时，`.slnx` 中的 VSTest 编排在发现阶段之前会失败）
- **发布检查**：`pwsh -NoProfile -ExecutionPolicy Bypass -File ./scripts/Validate-Release.ps1`（检查 ARCH 规则、文档、测试、SampleApp 和发布元数据之间的一致性）
- **手动验证**：参见 [src/Swa.Analyzers.SampleApp/README.md](src/Swa.Analyzers.SampleApp/README.md)（按规则列出示例以及带有诊断的构建）
发布验证的详细信息在 [docs/release.md](docs/release.md) 中。
## 发布与版本控制
发布版本使用由 [GitVersion.yml](GitVersion.yml) 配置的 GitVersion 作为发布版本的唯一来源。发布工作流使用 GitVersion 计算出的 `semVer` 版本用于 NuGet 的 `PackageVersion`、`vX.Y.Z` 标签和 GitHub Release。
请勿手动更新 `VersionPrefix` 来准备发布。语义化提交决定了版本增量：`fix:` 和 `perf:` 生成补丁版本，`feat:` 生成次版本，而 `!` 或 `BREAKING CHANGE:` 生成主版本。`docs:`、`test:`、`style:`、`chore:` 和 `ci:` 提交不会强制增量，除非它们表明是破坏性变更。
已发布规则的元数据位于 `src/Swa.Analyzers.Core/AnalyzerReleases.Shipped.md`；尚未发布的新规则位于 `src/Swa.Analyzers.Core/AnalyzerReleases.Unshipped.md`。发布检查会验证 `RuleIdentifiers.cs`、文档、README、测试、SampleApp 以及 shipped/unshipped 元数据中的 ID 保持一致。
标签：AsyncVoid, CodeFixes, ContinueWith, CSharp, editorconfig, NuGet包, Roslyn, 代码分析, 代码可靠性, 代码规范, 代码静态检查, 凭证管理, 单元测试, 多人体追踪, 异步编程, 架构规则, 测试质量, 编译器, 自动修复, 错误基检测, 静态代码分析