abp-contract-scaffolding

ABP 契约脚手架

生成 Application.Contracts 层代码，以支持并行开发工作流。

用途

契约脚手架将接口设计与实现分离，从而支持：

• abp-developer 根据已定义的接口进行实现
• qa-engineer 针对接口编写测试（即使尚未实现）
• 在 /add-feature 工作流中实现真正的并行执行

适用场景

• Backend-architect 在生成契约的同时进行技术设计
• 为并行实现和测试做准备
• 在开始实现前定义 API 契约
• 采用接口优先的开发方式

项目结构

{Project}.Application.Contracts/
├── {Feature}/
│   ├── I{Entity}AppService.cs      # Service interface
│   ├── {Entity}Dto.cs              # Output DTO
│   ├── Create{Entity}Dto.cs        # Create input
│   ├── Update{Entity}Dto.cs        # Update input
│   └── Get{Entity}sInput.cs        # List filter/pagination
└── Permissions/
    └── {Entity}Permissions.cs      # Permission constants

模板

1. 服务接口

using System;
using System.Threading.Tasks;
using Volo.Abp.Application.Dtos;
using Volo.Abp.Application.Services;

namespace {ProjectName}.{Feature};

/// <summary>
/// Application service interface for {Entity} management.
/// </summary>
public interface I{Entity}AppService : IApplicationService
{
    /// <summary>
    /// Gets a paginated list of {entities}.
    /// </summary>
    Task<PagedResultDto<{Entity}Dto>> GetListAsync(Get{Entity}sInput input);

    /// <summary>
    /// Gets a single {entity} by ID.
    /// </summary>
    Task<{Entity}Dto> GetAsync(Guid id);

    /// <summary>
    /// Creates a new {entity}.
    /// </summary>
    Task<{Entity}Dto> CreateAsync(Create{Entity}Dto input);

    /// <summary>
    /// Updates an existing {entity}.
    /// </summary>
    Task<{Entity}Dto> UpdateAsync(Guid id, Update{Entity}Dto input);

    /// <summary>
    /// Deletes a {entity} by ID.
    /// </summary>
    Task DeleteAsync(Guid id);
}

2. 输出 DTO

using System;
using Volo.Abp.Application.Dtos;

namespace {ProjectName}.{Feature};

/// <summary>
/// DTO for {Entity} output.
/// Inherits audit fields from FullAuditedEntityDto.
/// </summary>
public class {Entity}Dto : FullAuditedEntityDto<Guid>
{
    /// <summary>
    /// {Property description}
    /// </summary>
    public {Type} {PropertyName} { get; set; }

    // Add properties matching entity definition
}

3. 创建输入 DTO

using System;

namespace {ProjectName}.{Feature};

/// <summary>
/// DTO for creating a new {Entity}.
/// Validation is handled by FluentValidation in Application layer.
/// </summary>
public class Create{Entity}Dto
{
    /// <summary>
    /// {Property description}
    /// </summary>
    /// <remarks>Required. Max length: {N} characters.</remarks>
    public string {PropertyName} { get; set; } = string.Empty;

    // Add required properties for creation
}

4. 更新输入 DTO

using System;

namespace {ProjectName}.{Feature};

/// <summary>
/// DTO for updating an existing {Entity}.
/// Validation is handled by FluentValidation in Application layer.
/// </summary>
public class Update{Entity}Dto
{
    /// <summary>
    /// {Property description}
    /// </summary>
    public string {PropertyName} { get; set; } = string.Empty;

    // Add updatable properties
}

5. 列表筛选输入 DTO

using Volo.Abp.Application.Dtos;

namespace {ProjectName}.{Feature};

/// <summary>
/// Input DTO for filtering and paginating {Entity} list.
/// </summary>
public class Get{Entity}sInput : PagedAndSortedResultRequestDto
{
    /// <summary>
    /// Optional text filter for searching by name or description.
    /// </summary>
    public string? Filter { get; set; }

    /// <summary>
    /// Optional filter by active status.
    /// </summary>
    public bool? IsActive { get; set; }

    // Add entity-specific filters
}

6. 权限常量

namespace {ProjectName}.Permissions;

/// <summary>
/// Permission constants for {Entity} management.
/// These are registered in {ProjectName}PermissionDefinitionProvider.
/// </summary>
public static class {Entity}Permissions
{
    /// <summary>
    /// Permission group name.
    /// </summary>
    public const string GroupName = "{ProjectName}.{Entities}";

    /// <summary>
    /// Default permission (view/list).
    /// </summary>
    public const string Default = GroupName;

    /// <summary>
    /// Permission to create new {entities}.
    /// </summary>
    public const string Create = GroupName + ".Create";

    /// <summary>
    /// Permission to edit existing {entities}.
    /// </summary>
    public const string Edit = GroupName + ".Edit";

    /// <summary>
    /// Permission to delete {entities}.
    /// </summary>
    public const string Delete = GroupName + ".Delete";
}

常见模式

激活/停用模式

当实体支持激活生命周期时：

// In interface
Task<{Entity}Dto> ActivateAsync(Guid id);
Task<{Entity}Dto> DeactivateAsync(Guid id);

// In permissions
public const string Activate = GroupName + ".Activate";
public const string Deactivate = GroupName + ".Deactivate";

// In filter DTO
public bool? IsActive { get; set; }

层级实体模式

当实体具有父子关系时：

// In output DTO
public Guid? ParentId { get; set; }
public string? ParentName { get; set; }
public List<{Entity}Dto> Children { get; set; } = new();

// In interface
Task<List<{Entity}Dto>> GetChildrenAsync(Guid parentId);
Task MoveAsync(Guid id, Guid? newParentId);

// In filter DTO
public Guid? ParentId { get; set; }
public bool IncludeChildren { get; set; }

查找/引用模式

用于下拉列表和引用：

// Lightweight DTO for dropdowns
public class {Entity}LookupDto
{
    public Guid Id { get; set; }
    public string Name { get; set; } = string.Empty;
}

// In interface
Task<List<{Entity}LookupDto>> GetLookupAsync();

批量操作模式

需要批量操作时：

// In interface
Task<int> DeleteManyAsync(List<Guid> ids);
Task<List<{Entity}Dto>> CreateManyAsync(List<Create{Entity}Dto> inputs);

// In permissions
public const string DeleteMany = GroupName + ".DeleteMany";

生成检查清单

生成契约时，请确认：

• 接口继承 IApplicationService
• 所有 DTO 均位于正确的命名空间 {ProjectName}.{Feature}
• 输出 DTO 继承 FullAuditedEntityDto<Guid>（或适当的基类）
• 筛选 DTO 继承 PagedAndSortedResultRequestDto
• 权限常量遵循 {Project}.{Resource}.{Action} 模式
• 包含 XML 文档注释
• 属性符合技术设计规范
• 正确标记必需属性与可选属性
• 集合属性已初始化（= new() 或 = []）

与 /add-feature 集成

此技能由 backend-architect Agent 在 /add-feature 的第 1 阶段使用：

Phase 1: backend-architect generates:
├── docs/features/{feature}/technical-design.md
├── Application.Contracts/{Feature}/I{Entity}AppService.cs
├── Application.Contracts/{Feature}/{Entity}Dto.cs
├── Application.Contracts/{Feature}/Create{Entity}Dto.cs
├── Application.Contracts/{Feature}/Update{Entity}Dto.cs
├── Application.Contracts/{Feature}/Get{Entity}sInput.cs
└── Application.Contracts/Permissions/{Entity}Permissions.cs

Phase 2 (parallel):
├── abp-developer: Implements against interface
└── qa-engineer: Writes tests against interface

命名约定

组件	模式	示例
接口	I{Entity}AppService	IBookAppService
输出 DTO	{Entity}Dto	BookDto
创建 DTO	Create{Entity}Dto	CreateBookDto
更新 DTO	Update{Entity}Dto	UpdateBookDto
筛选 DTO	Get{Entity}sInput	GetBooksInput
查找 DTO	{Entity}LookupDto	BookLookupDto
权限	{Entity}Permissions	BookPermissions

相关技能

• abp-framework-patterns - 完整的 ABP 模式，包括实现
• technical-design-patterns - 技术设计文档模板
• api-design-principles - REST API 设计最佳实践