abp-contract-scaffolding

ABP コントラクトのスキャフォールディング

並行開発ワークフローを可能にするため、Application.Contracts レイヤーのコードを生成します。

目的

コントラクトのスキャフォールディングによってインターフェース設計と実装を分離し、次のことが可能になります。

• abp-developer が定義済みのインターフェースに基づいて実装する
• qa-engineer が実装前にインターフェースに基づいてテストを作成する
• /add-feature ワークフローで真の並行実行を行う

使用するタイミング

• コントラクト生成を含む技術設計をバックエンドアーキテクトが作成するとき
• 実装とテストの並行作業に備えるとき
• 実装開始前に 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 エージェントが /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 設計のベストプラクティス