abp-contract-scaffolding

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ABP Contract Scaffolding

ABP 契约脚手架

Generate Application.Contracts layer code to enable parallel development workflows.

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

Purpose

用途

Contract scaffolding separates interface design from implementation, enabling:

```
abp-developer
```
to implement against defined interfaces
```
qa-engineer
```
to write tests against interfaces (before implementation exists)
True parallel execution in
```
/add-feature
```
workflow

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

```
abp-developer
```
基于定义好的接口进行实现
```
qa-engineer
```
针对接口编写测试（无需等待实现完成）
在
```
/add-feature
```
工作流中实现真正的并行执行

When to Use

适用场景

Backend-architect creating technical design with contract generation
Preparing for parallel implementation and testing
Defining API contracts before implementation starts
Interface-first development approach

后端架构师创建技术设计并生成契约时
准备并行实现与测试时
在开发开始前定义API契约时
采用接口优先的开发方式时

Project Structure

项目结构

{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

{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

Templates

模板

1. Service Interface

1. 服务接口

csharp

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);
}

csharp

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. Output DTO

2. 输出DTO

csharp

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
}

csharp

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. Create Input DTO

3. 创建输入DTO

csharp

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
}

csharp

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. Update Input DTO

4. 更新输入DTO

csharp

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
}

csharp

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. List Filter Input DTO

5. 列表筛选输入DTO

csharp

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
}

csharp

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. Permission Constants

6. 权限常量

csharp

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";
}

csharp

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";
}

Common Patterns

常见模式

Activation/Deactivation Pattern

激活/停用模式

When entity supports activation lifecycle:

csharp

// 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; }

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

csharp

// 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; }

Hierarchical Entity Pattern

层级实体模式

When entity has parent-child relationships:

csharp

// 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; }

当实体存在父子关系时：

csharp

// 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; }

Lookup/Reference Pattern

查找/引用模式

For dropdown lists and references:

csharp

// 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();

适用于下拉列表和引用场景：

csharp

// 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();

Bulk Operations Pattern

批量操作模式

When bulk operations are needed:

csharp

// 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";

当需要批量操作时：

csharp

// 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";

Generation Checklist

生成检查清单

When generating contracts, verify:

Interface extends
```
IApplicationService
```
All DTOs in correct namespace
```
{ProjectName}.{Feature}
```
Output DTO extends
```
FullAuditedEntityDto<Guid>
```
(or appropriate base)
Filter DTO extends
```
PagedAndSortedResultRequestDto
```
Permission constants follow
```
{Project}.{Resource}.{Action}
```
pattern
XML documentation comments included
Properties match technical design specification
Required vs optional properties marked correctly
Collection properties initialized (
```
= new()
```
or
```
= []
```
)

生成契约时，请验证：

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

Integration with /add-feature

与/add-feature的集成

This skill is used by

backend-architect

agent in Phase 1 of

/add-feature

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

该技能由

backend-architect

代理在

/add-feature

的第一阶段使用：

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

Naming Conventions

命名规范

Component	Pattern	Example
Interface	`I{Entity}AppService`	`IBookAppService`
Output DTO	`{Entity}Dto`	`BookDto`
Create DTO	`Create{Entity}Dto`	`CreateBookDto`
Update DTO	`Update{Entity}Dto`	`UpdateBookDto`
Filter DTO	`Get{Entity}sInput`	`GetBooksInput`
Lookup DTO	`{Entity}LookupDto`	`BookLookupDto`
Permissions	`{Entity}Permissions`	`BookPermissions`

组件	模式	示例
接口	`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-contract-scaffolding

Original

Translation

ABP Contract Scaffolding

ABP 契约脚手架

Purpose

用途

When to Use

适用场景

Project Structure

项目结构

Templates

模板

1. Service Interface

1. 服务接口

2. Output DTO

2. 输出DTO

3. Create Input DTO

3. 创建输入DTO

4. Update Input DTO

4. 更新输入DTO

5. List Filter Input DTO

5. 列表筛选输入DTO

6. Permission Constants

6. 权限常量

Common Patterns

常见模式

Activation/Deactivation Pattern

激活/停用模式

Hierarchical Entity Pattern

层级实体模式

Lookup/Reference Pattern

查找/引用模式

Bulk Operations Pattern

批量操作模式

Generation Checklist

生成检查清单

Integration with /add-feature

与/add-feature的集成

Naming Conventions

命名规范

Related Skills

相关技能