movingsam b8d2a93c9f docs: 添加代码库分析文档（中文）

- STACK.md - 技术栈和依赖
- INTEGRATIONS.md - 外部集成
- ARCHITECTURE.md - 架构设计
- STRUCTURE.md - 代码库结构
- CONVENTIONS.md - 编码规范
- TESTING.md - 测试模式
- CONCERNS.md - 技术债务和问题

2026-02-28 18:38:17 +08:00

2.2 KiB

Raw Blame History

编码规范

分析日期： 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

导入组织

顺序：

System 命名空间
项目内部命名空间
第三方库

示例：

using System;
using System.Collections.Generic;
using Fengling.Console.Services;
using Fengling.Platform.Domain;
using Microsoft.AspNetCore.Mvc;

错误处理

模式：

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

示例：

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

模式：

private readonly ILogger<UsersController> _logger;

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

注释

何时注释：

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

XML 注释示例：

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

函数设计

大小：

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

参数：

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

返回值：

使用 Task 返回异步结果
集合使用 IEnumerable

模块设计

导出：

公开接口：I[Xxx]Service
实现类：XxxService

依赖注入：

构造函数注入
接口+实现配对

规范分析：2026-02-28

2.2 KiB Raw Blame History Unescape Escape