# 编码规范

**分析日期：** 2026-02-28

## 命名模式

**文件：**
- PascalCase：`UserService.cs`、`UsersController.cs`

**类/接口：**
- PascalCase：`UserService`、`IUserService`

**方法：**
- PascalCase：`GetUsersAsync`、`CreateUserAsync`

**变量：**
- camelCase：`userService`、`userName`

## 代码风格

**格式化：**
- 使用 .editorconfig 或 Rider/VS 默认格式化
- 花括号风格：K&R

**命名空间：**
- 层级式：`Fengling.Console.Controllers`

## 导入组织

**顺序：**
1. System 命名空间
2. 项目内部命名空间
3. 第三方库

**示例：**
```csharp
using System;
using System.Collections.Generic;
using Fengling.Console.Services;
using Fengling.Platform.Domain;
using Microsoft.AspNetCore.Mvc;
```

## 错误处理

**模式：**
- 使用 try-catch 捕获异常
- 按异常类型返回不同 HTTP 状态码
- 记录日志：`_logger.LogError(ex, "...")`

**示例：**
```csharp
try {
    await _userService.CreateUserAsync(dto);
} catch (InvalidOperationException ex) {
    return BadRequest(new { message = ex.Message });
} catch (Exception ex) {
    _logger.LogError(ex, "Error creating user");
    return StatusCode(500, new { message = ex.Message });
}
```

## 日志

**框架：** Microsoft.Extensions.Logging + ILogger<T>

**模式：**
```csharp
private readonly ILogger<UsersController> _logger;

_logger.LogError(ex, "Error message");
_logger.LogWarning(ex, "Warning message");
```

## 注释

**何时注释：**
- 公开 API 方法使用 XML 文档注释
- 复杂业务逻辑添加说明

**XML 注释示例：**
```csharp
/// <summary>
/// 获取用户列表
/// </summary>
/// <param name="query">分页查询参数</param>
/// <returns>分页的用户列表</returns>
[HttpGet]
public async Task<ActionResult<PagedResultDto<UserDto>>> GetUsers(...)
```

## 函数设计

**大小：** 
- 保持方法简洁，单一职责
- 复杂逻辑拆分到私有方法

**参数：**
- 使用 DTO 进行参数分组
- 异步方法使用 Async 后缀

**返回值：**
- 使用 Task<T> 返回异步结果
- 集合使用 IEnumerable<T>

## 模块设计

**导出：**
- 公开接口：I[Xxx]Service
- 实现类：XxxService

**依赖注入：**
- 构造函数注入
- 接口+实现配对

---

*规范分析：2026-02-28*