b8d2a93c9f
- STACK.md - 技术栈和依赖 - INTEGRATIONS.md - 外部集成 - ARCHITECTURE.md - 架构设计 - STRUCTURE.md - 代码库结构 - CONVENTIONS.md - 编码规范 - TESTING.md - 测试模式 - CONCERNS.md - 技术债务和问题
119 lines
2.2 KiB
Markdown
119 lines
2.2 KiB
Markdown
# 编码规范
|
||
|
||
**分析日期：** 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*
|