⚡

Perigon后端开发规范Skill perigon-backend

这是一套用于指导Perigon项目后端开发的详细技术规范与架构指南。它定义了基于ASP.NET Core、Entity Framework Core和Aspire框架的代码组织方式、实体设计、数据库访问、业务逻辑分层、API控制器编写以及应用部署的完整流程。关键词包括：ASP.NET Core, EF Core, Aspire, 后端架构, 代码规范, 微服务, 数据库设计, REST API, 依赖注入, 代码优先。

后端开发 0 次安装 1 次浏览 更新于 3/2/2026

名称: perigon-backend 描述: Perigon ASP.NET Core + EF Core + Aspire 项目规范

何时使用

  • 在 src/Definition、src/Modules、src/Services 和 src/AppHost 目录下进行后端开发时使用（涉及实体、DTO、管理器、控制器、EF、托管等）。

使用规范

  • 架构：Definition（实体/EF/共享/服务默认值） -> Modules（管理器 + DTO） -> Services（控制器）。使用 Code First 并启用 <Nullable>enable。
  • 实体：继承 EntityBase（Id、CreatedAt、UpdatedAt、IsDeleted）；Id 使用客户端生成的 Guid v7。字符串需指定最大长度；小数需设置精度（10,2 或 18,6）；枚举需要 [Description] 特性；优先使用 DateTimeOffset/DateOnly/TimeOnly。
  • 数据库：优先使用 SQL Server（商业版）或 PostgreSQL；在领域内使用外键；避免使用字符串分隔的列表（使用数组/JSON）。通过 scripts/EFMigrations.ps1 进行迁移；迁移文件位于 Definition/EntityFramework/Migrations 目录下。
  • 数据访问：DbContext 位于 Definition/EntityFramework/AppDbContext；默认使用 TenantDbFactory/UniversalDbFactory 进行创建。优先使用带 Select 投影的 Queryable；默认使用 AsNoTracking；批量操作使用 EFCore.BulkExtensions。
  • 管理器：放置在 src/Modules/{模块名}/Managers 目录下；继承 ManagerBase（当与实体绑定时使用泛型）以支持依赖注入。不要返回 ActionResult 或接触 HttpContext；避免管理器之间的相互引用。使用基础操作（FindAsync、ExistAsync、ListAsync、PageListAsync、InsertAsync、UpdateAsync、DeleteAsync、BulkInsertAsync、ExecuteInTransactionAsync）。业务错误抛出 BusinessException；将第三方调用/辅助工具放在共享/服务中。
  • DTO：存储在 src/Modules/{模块名}/Models/{实体名}Dtos 目录下，包含 Detail/Add/Update/Item/Filter 等形态；通过 Mapster 进行映射。
  • 控制器：位于 src/Services/*/Controllers 目录下；继承 RestControllerBase。使用 HTTP 动词属性和方法名 AddAsync/UpdateAsync/DeleteAsync/GetDetailAsync/FilterAsync。返回 ActionResult<T>；使用 Problem/NotFound 处理错误；避免使用 ApiResponse 包装器；业务逻辑保持在管理器中；在此处理身份验证/权限/验证。
  • Aspire/AppHost：AppHost 负责编排基础设施/服务；确保 Docker/Podman 正在运行。通过 appsettings*.json 进行配置。除非被要求，否则避免使用构建/运行命令；更改后检查编辑器诊断信息。