流浪小鱼1. .NET编码规范的重要性与价值
在十多年的.NET开发实践中，我深刻体会到编码规范绝不是简单的格式约束。它是一套经过千锤百炼的工程实践结晶，直接影响着项目的可维护性、团队协作效率和代码质量。特别是在企业级应用中，规范的代码能显著降低技术债务，让系统在5年甚至10年后依然保持可扩展性。
.NET生态经过20多年发展，已经从最初的Framework演进到跨平台的.NET Core/.NET 5+时代。不同版本的运行时虽然语法兼容，但最佳实践却在持续进化。比如异步编程模式从早期的Begin/End到Task-based，再到现在的async/await，规范的迭代反映了技术发展的趋势。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 基础命名规范与代码结构
2.1 命名约定的核心原则
PascalCase和camelCase的选择不是随意的：
- 类、方法、属性等公开成员使用PascalCase（如
CustomerRepository） - 参数、局部变量使用camelCase（如
orderDetails） - 私有字段推荐使用
_camelCase前缀（如_connectionString）
匈牙利命名法在.NET中已被明确废弃，类型信息不应通过名称表达（避免使用strName、iCount等）。现代IDE的智能提示已经解决了类型可视化的需求。
2.2 类型与成员的组织规范
文件结构应该遵循"单一职责原则"：
csharp复制// Customer.cs
public class Customer
{
// 常量字段
private const int MaxRetryCount = 3;
// 私有字段
private readonly ILogger _logger;
// 构造函数
public Customer(ILogger logger) { ... }
// 属性
public string Name { get; set; }
// 公共方法
public void PlaceOrder(Order order) { ... }
// 私有方法
private bool Validate() { ... }
}
重要提示：避免使用
#region来组织代码，这通常是类型承担过多职责的信号。如果发现需要频繁使用region，应该考虑拆分类型。
3. 现代C#特性使用规范
3.1 空安全与模式匹配
随着.NET Core的普及，空引用异常的处理有了更优雅的方式：
csharp复制// 传统方式
if (customer != null && customer.Address != null)
{
var city = customer.Address.City;
}
// 现代方式（C# 8.0+）
var city = customer?.Address?.City;
// 配合模式匹配
if (customer is { Address: { City: string city } })
{
Console.WriteLine(city);
}
3.2 集合与LINQ最佳实践
LINQ极大提升了代码表达力，但也容易滥用：
csharp复制// 不推荐：多次迭代同一集合
var activeUsers = users.Where(u => u.IsActive);
var count = activeUsers.Count();
var names = activeUsers.Select(u => u.Name);
// 推荐：物化结果避免重复计算
var activeUsers = users.Where(u => u.IsActive).ToList();
对于大型集合，应考虑使用IAsyncEnumerable进行流式处理：
csharp复制await foreach (var item in GetLargeDataStream())
{
Process(item);
}
4. 异步编程规范
4.1 async/await的正确使用
异步编程已经成为.NET高性能应用的基石，但常见误区包括：
csharp复制// 反模式1：async void
async void ButtonClick() { ... }
// 反模式2：阻塞异步调用
var result = GetDataAsync().Result;
// 正确方式
private async Task OnButtonClick()
{
try
{
var result = await GetDataAsync();
// 处理结果
}
catch (Exception ex)
{
_logger.LogError(ex, "操作失败");
}
}
4.2 取消令牌的应用
健壮的异步操作应该支持取消：
csharp复制public async Task ProcessDataAsync(
IEnumerable<Data> data,
CancellationToken cancellationToken = default)
{
foreach (var item in data)
{
cancellationToken.ThrowIfCancellationRequested();
await ProcessItemAsync(item, cancellationToken);
}
}
5. 性能关键代码规范
5.1 内存分配优化
在高性能场景中，应避免不必要的内存分配：
csharp复制// 不推荐：频繁分配新字符串
string path = root + "/" + sub + "/" + file;
// 推荐：使用StringBuilder或字符串插值
string path = $"{root}/{sub}/{file}";
对于热点路径，可以考虑使用ArrayPool<T>或Memory<T>：
csharp复制var buffer = ArrayPool<byte>.Shared.Rent(1024);
try
{
// 使用buffer...
}
finally
{
ArrayPool<byte>.Shared.Return(buffer);
}
5.2 结构体与ref关键字
值类型可以显著减少GC压力：
csharp复制public readonly struct Point
{
public double X { get; }
public double Y { get; }
public Point(double x, double y) => (X, Y) = (x, y);
}
// 通过in关键字避免复制
public double CalculateDistance(in Point a, in Point b)
{
var dx = a.X - b.X;
var dy = a.Y - b.Y;
return Math.Sqrt(dx * dx + dy * dy);
}
6. 测试代码规范
6.1 单元测试命名模式
测试方法名应该明确表达测试场景：
csharp复制[Fact]
public void Transfer_ShouldDeductFromSource_WhenAmountIsValid()
{
// 测试代码
}
[Theory]
[InlineData(0)]
[InlineData(-1)]
public void Transfer_ShouldThrow_WhenAmountIsInvalid(decimal amount)
{
Assert.Throws<ArgumentException>(() => _service.Transfer(amount));
}
6.2 集成测试注意事项
集成测试需要特殊处理：
csharp复制public class DatabaseTests : IAsyncLifetime
{
private SqlConnection _connection;
public async Task InitializeAsync()
{
_connection = new SqlConnection(_config.GetConnectionString("Test"));
await _connection.OpenAsync();
await InitializeTestData();
}
public async Task DisposeAsync()
{
await CleanupTestData();
await _connection.CloseAsync();
_connection.Dispose();
}
[Fact]
public async Task Query_ShouldReturnCorrectResults()
{
// 使用_connection进行测试
}
}
7. 项目结构与构建规范
7.1 解决方案组织建议
现代.NET项目推荐采用分层结构：
code复制src/
├── Application/ # 业务逻辑层
├── Domain/ # 领域模型
├── Infrastructure/ # 基础设施实现
└── Web/ # 表现层
tests/
├── UnitTests/ # 单元测试
└── IntegrationTests/ # 集成测试
7.2 构建配置优化
Directory.Build.props文件可以集中管理公共属性：
xml复制<Project>
<PropertyGroup>
<LangVersion>latest</LangVersion>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
</Project>
8. 安全编码规范
8.1 输入验证原则
所有外部输入都应视为不可信的：
csharp复制public class OrderController : Controller
{
public IActionResult Create([FromBody] OrderDto dto)
{
if (dto == null || !ModelState.IsValid)
return BadRequest();
if (dto.Items.Count == 0)
return BadRequest("订单必须包含商品");
// 业务处理...
}
}
8.2 密码与敏感数据处理
敏感信息处理需要特别小心：
csharp复制// 使用SecureString处理密码（已过时，.NET Core中推荐使用专门的加密库）
var securePassword = new NetworkCredential("", password).SecurePassword;
// 现代方式：使用ASP.NET Core Data Protection
public class CreditCardService
{
private readonly IDataProtector _protector;
public CreditCardService(IDataProtectionProvider provider)
{
_protector = provider.CreateProtector("CreditCard");
}
public string Encrypt(string cardNumber) => _protector.Protect(cardNumber);
public string Decrypt(string protectedText) => _protector.Unprotect(protectedText);
}
9. 异常处理规范
9.1 异常分类与处理策略
异常应该分层处理：
csharp复制try
{
// 业务操作
}
catch (ValidationException ex)
{
// 预期内的业务异常，返回400
return BadRequest(ex.Message);
}
catch (DbUpdateException ex) when (ex.IsConcurrencyError())
{
// 并发冲突，返回409
return Conflict();
}
catch (Exception ex)
{
// 未预期异常，记录后返回500
_logger.LogError(ex, "处理请求时发生错误");
return StatusCode(500);
}
9.2 日志记录最佳实践
结构化日志能极大提升排查效率：
csharp复制_logger.LogInformation("处理订单 {OrderId} 来自用户 {UserId}", order.Id, user.Id);
// 使用作用域添加上下文
using (_logger.BeginScope(new Dictionary<string, object>
{
["OrderId"] = order.Id,
["UserId"] = user.Id
}))
{
// 该范围内的所有日志都会自动包含上下文
}
10. 代码审查要点
10.1 常见问题检查清单
审查时应重点关注：
- 是否存在
async void方法 - 是否缺少
CancellationToken参数 - 是否正确处理了
IDisposable对象 - 是否对集合进行了不必要的重复迭代
- 是否在循环中创建了不必要的对象
10.2 自动化检查工具
除了人工审查，应该配置：
xml复制<ItemGroup>
<PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="6.0.0" PrivateAssets="all" />
<PackageReference Include="StyleCop.Analyzers" Version="1.2.0-beta.406" PrivateAssets="all" />
</ItemGroup>
.editorconfig文件示例：
code复制[*.cs]
dotnet_diagnostic.CA1305.severity = warning # 文化敏感的字符串操作
dotnet_diagnostic.CA2007.severity = warning # 直接等待Task
dotnet_diagnostic.CA1848.severity = error # 使用LoggerMessage定义的日志方法
11. 跨平台开发注意事项
11.1 文件系统路径处理
避免硬编码路径分隔符：
csharp复制// 不推荐
var path = "data\\files\\config.json";
// 推荐
var path = Path.Combine("data", "files", "config.json");
11.2 环境特定代码处理
使用条件编译要谨慎：
csharp复制#if WINDOWS
// Windows特定代码
#elif LINUX
// Linux特定代码
#else
// 通用回退
#endif
更好的方式是通过依赖注入抽象平台差异：
csharp复制public interface IFileSystem
{
Stream OpenFile(string path);
}
// Windows实现
public class WindowsFileSystem : IFileSystem { ... }
// Linux实现
public class LinuxFileSystem : IFileSystem { ... }
12. 容器化部署规范
12.1 Dockerfile优化
多阶段构建可以减小镜像体积：
dockerfile复制FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish -c Release -o /app
FROM mcr.microsoft.com/dotnet/aspnet:6.0
WORKDIR /app
COPY --from=build /app .
ENTRYPOINT ["dotnet", "MyApp.dll"]
12.2 健康检查配置
确保容器健康状态可观测：
csharp复制app.MapHealthChecks("/health", new HealthCheckOptions
{
ResponseWriter = async (context, report) =>
{
context.Response.ContentType = "application/json";
await context.Response.WriteAsync(JsonSerializer.Serialize(new
{
status = report.Status.ToString(),
checks = report.Entries.Select(e => new
{
name = e.Key,
status = e.Value.Status.ToString(),
duration = e.Value.Duration.TotalMilliseconds
})
}));
}
});
13. 性能诊断技巧
13.1 基准测试方法
使用BenchmarkDotNet进行可靠测量：
csharp复制[MemoryDiagnoser]
public class StringBenchmarks
{
[Benchmark]
public string StringConcat() => "a" + "b" + "c";
[Benchmark]
public string StringInterpolation() => $"{1}{2}{3}";
}
13.2 生产环境诊断
ASP.NET Core内置了丰富的诊断工具：
csharp复制app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
endpoints.MapPrometheusScrapingEndpoint();
});
14. 代码演进与重构
14.1 过时代码处理策略
使用[Obsolete]标记待淘汰代码：
csharp复制[Obsolete("改用新的ProcessAsync方法", error: false)]
public void Process() { ... }
14.2 重大变更管理
通过扩展方法平滑过渡：
csharp复制public static class LegacyExtensions
{
public static Task ProcessAsync(this LegacyService service)
{
// 新实现包装旧方法
return Task.Run(() => service.Process());
}
}
15. 团队协作规范
15.1 Git工作流建议
功能分支开发流程：
code复制git checkout -b feature/xxx
# 开发提交...
git fetch origin
git rebase origin/main
git push -u origin feature/xxx
# 创建PR合并到main
15.2 提交消息规范
遵循Conventional Commits：
code复制feat: 添加用户管理模块
fix(api): 修复分页参数验证问题
chore: 更新NuGet包依赖
在大型.NET项目中，编码规范不是限制创造力的枷锁，而是保证软件长期健康发展的基石。我见过太多因为忽视规范而导致项目最终难以维护的案例。规范的价值不在于形式，而在于它背后蕴含的工程智慧。