AspectCore-Framework 开发规范

July 25, 2026 · View on GitHub

本文档定义 AspectCore-Framework 项目的开发规范。所有代码变更、PR 提交都应遵循这些规范。

1. 先理解 MSBuild 工程拓扑，再动代码

AspectCore 是一个由 MSBuild、NuGet、TargetFramework 和宿主框架共同决定行为的系统，而不是"若干独立 C# 文件的集合"。

对象	作用	为什么重要
`AspectCore-Framework.sln`	solution 级入口，决定项目集合与执行边界	命令应该跑在 solution 级还是 project 级，首先看解空间结构
`src//.csproj`	项目类型、TargetFramework、包引用、生成设置	几乎所有编译行为都在这里定义
`build/common.props`	全局编译约定（LangVersion、TargetFrameworks、分析器）	改了这里影响所有项目
`tests/Directory.Build.props`	测试项目共享配置（coverlet.msbuild 注入）	测试覆盖率配置来源
`.github/workflows/*.yml`	CI/CD 定义	本地命令应与 CI 行为对齐

关键判断点： 不要跳过这些识别步骤。

2. 能根据上下文选择修改层级

改 solution 级配置（build/common.props）→ 影响所有项目，需 solution 级 build/test
改 project 级配置（csproj）→ 影响该项目及其依赖者
改单个源码文件 → 优先 project 级 + 依赖它的测试项目
只补一条测试 → --filter 精确到那个测试类

常见错误：

仓库多目标框架（net10.0;net9.0;net8.0;net6.0），只按单一 TFM 写 API → 错误
改了 build/common.props 却只编一个项目 → 错误

3. 代码生成要符合 .NET 语义，而不是只像 C#

正确传播 CancellationToken，而不是只在最外层签名里"摆一个参数"
区分 Task 与 ValueTask 的适用边界
理解 nullable reference types 的契约意义（本项目 src/ 中仅 SourceGenerator 启用 nullable，测试项目中仅 AspectCore.E2E.Tests 启用）
在热路径中控制分配、避免隐藏装箱与枚举器开销
遇到性能或稳定性问题时，先建议 benchmark / profiling / tracing，而不是拍脑袋重写

4. 项目进入后的识别顺序

4.1 先看 solution / project 结构

src/ 下的核心库：AspectCore.Abstractions、AspectCore.Core、AspectCore.SourceGenerator
src/AspectCore.Extensions.* 扩展库
tests/ 下的测试项目
sample/、benchmark/ 示例与基准项目

4.2 再看 SDK 与目标框架约定

无 global.json，SDK 未钉死
src/ 的 LangVersion=13.0（build/common.props）
测试项目 LangVersion=13.0
库目标框架：net10.0;net9.0;net8.0;net6.0（详见 AGENTS.md）

4.3 识别测试框架与质量工具链

xUnit 2.9.2 + Microsoft.NET.Test.Sdk 17.12.0
覆盖率：coverlet.msbuild 6.0.2，阈值 unit 95% / E2E 80%
无 .editorconfig，使用 dotnet format 默认风格

5. 最佳命令实践

5.1 先决定执行粒度，再跑命令

场景	推荐粒度	典型命令
新 clone、切分支、依赖变化	solution 级	`dotnet restore AspectCore-Framework.sln`
改了 `build/common.props` 或公共接口	solution 级	`dotnet build AspectCore-Framework.sln -c Release`
只改某个类库	project 级	`dotnet build src/AspectCore.Core/AspectCore.Core.csproj -c Release`
只改某个测试项目	test project 级	`dotnet test tests/AspectCore.Core.Tests/AspectCore.Core.Tests.csproj`
只验证一个测试类	test filter 级	`dotnet test tests/AspectCore.Core.Tests/AspectCore.Core.Tests.csproj --filter "FullyQualifiedName~ServiceResolverTests"`

核心原则：先缩小影响面，再缩小命令范围。

5.2 常用命令

# 还原与构建
dotnet restore AspectCore-Framework.sln
dotnet build src/AspectCore.Core/AspectCore.Core.csproj -c Release

# 测试（带覆盖率，匹配 CI）
dotnet test ./tests/AspectCore.Core.Tests/AspectCore.Core.Tests.csproj \
  --configuration Release -f net9.0 \
  /p:CollectCoverage=true /p:CoverletOutputFormat=cobertura \
  /p:CoverletOutput=./TestResults/ "/p:Include=[AspectCore.Core]*"

# 格式检查
dotnet format src/AspectCore.Core/AspectCore.Core.csproj --verify-no-changes

5.3 测试过滤

# 按类名过滤
dotnet test tests/AspectCore.Core.Tests/AspectCore.Core.Tests.csproj \
  --filter "FullyQualifiedName~ServiceResolverTests"

# 按方法名过滤
dotnet test tests/AspectCore.Core.Tests/AspectCore.Core.Tests.csproj \
  --filter "Name~Should_resolve_keyed_service"