ABP教程 - 通过ABP Boilerplate模板创建项目

目录#

引言
前置条件
通过ABP模板创建项目
- 3.1 使用ABP CLI（命令行）
- 3.2 使用ABP Suite（可视化工具）
项目结构深度解析
ABP核心功能快速上手
运行并验证项目
自定义功能示例：图书管理模块
ABP开发最佳实践
常见问题排查
结论
参考资料

前置条件#

开始前，请确保你的开发环境满足以下要求：

.NET SDK：安装.NET 8（或更高LTS版本），下载地址：https://dotnet.microsoft.com/zh-cn/download
Node.js & npm：用于运行Angular/Vue前端，推荐v18+，下载地址：https://nodejs.org/
数据库：SQL Server（或SQLite、PostgreSQL），本地开发推荐使用SQL Server LocalDB（VS默认安装）
开发工具：Visual Studio 2022（推荐）、Rider或VS Code
ABP CLI：全局安装ABP命令行工具
```
dotnet tool install -g Volo.Abp.Cli
```

通过ABP模板创建项目#

ABP提供CLI命令行和ABP Suite可视化工具两种方式创建项目。我们先从CLI开始（更灵活），再简要介绍Suite。

3.1 使用ABP CLI（命令行）#

ABP CLI的abp new命令可快速生成项目模板，支持自定义UI框架、数据访问技术等。

示例：创建一个Angular + EF Core + SQL Server的应用#

运行以下命令：

abp new BookStore -t app -u angular -d efcore -dbms sqlserver

参数说明：#

BookStore：项目名称（解决方案名称）
-t app：模板类型为应用程序（其他类型：module模块、console控制台）
-u angular：前端UI框架（可选：blazor-server、blazor-webassembly、mvc）
-d efcore：数据访问技术（可选：mongodb）
-dbms sqlserver：数据库类型（可选：sqlite、postgresql）

生成结果：#

命令执行完成后，会生成以下结构的解决方案：

BookStore/
├─ src/                      # 源文件目录
│  ├─ BookStore.Domain/      # 领域层
│  ├─ BookStore.Application.Contracts/ # 应用层契约（接口+DTO）
│  ├─ BookStore.Application/ # 应用层实现
│  ├─ BookStore.Infrastructure/ # 基础设施层（EF Core、外部服务）
│  ├─ BookStore.Web/         # 后端API（.NET Web项目）
│  └─ BookStore.Angular/     # Angular前端项目
├─ test/                     # 测试项目
├─ BookStore.DbMigrator/     # 数据库迁移工具（控制台应用）
└─ BookStore.sln             # 解决方案文件

3.2 使用ABP Suite（可视化工具）#

ABP Suite是ABP的可视化开发工具，适合更直观的项目初始化与模块生成。

安装与启动：#

dotnet tool install -g Volo.Abp.Suite
abp suite

操作步骤：#

打开Suite后，点击Create New Project；
填写项目名称、选择模板类型（Application）；
选择UI框架（Angular）、数据访问（EF Core）、数据库（SQL Server）；
点击Create Project，Suite会自动生成项目并打开VS。

项目结构深度解析#

ABP严格遵循分层架构与领域驱动设计（DDD），各层职责明确。以下是核心层的详细说明：

4.1 解决方案层级结构#

项目	职责
`Domain`	核心业务逻辑（实体、值对象、领域服务、仓储接口）
`Application.Contracts`	应用层契约（DTO、应用服务接口，用于前后端/模块间通信）
`Application`	应用层实现（调用领域层，协调业务流程）
`Infrastructure`	基础设施实现（EF Core DbContext、仓储实现、第三方服务集成）
`Web`	后端API（自动生成控制器、CORS配置、中间件）
`Angular`	前端UI（基于Angular Material，集成ABP预构建组件）
`DbMigrator`	数据库迁移工具（应用迁移+初始化种子数据）

4.2 领域层（Domain）#

领域层是应用的核心，包含业务规则与概念模型。关键文件：

实体（Entity）：代表业务对象（如Book、User），继承ABP的基类（如AggregateRoot<Guid>）。
示例：BookStore.Domain/Books/Book.cs

public class Book : AuditedAggregateRoot<Guid>
{
    // 聚合根ID（Guid类型）
    public Guid Id { get; set; }
    // 书名（必填）
    public string Name { get; set; }
    // 作者（必填）
    public string Author { get; set; }
    // 价格
    public decimal Price { get; set; }
    // 出版日期
    public DateTime PublishDate { get; set; }
}

AuditedAggregateRoot：ABP提供的基类，自动添加审计字段（CreationTime、CreatorId、LastModificationTime）。

仓储接口：定义数据访问契约（如IBookRepository），由基础设施层实现。
示例：BookStore.Domain/Books/IBookRepository.cs
```
public interface IBookRepository : IRepository<Book, Guid>
{
    // 自定义查询方法（如按作者查询图书）
    Task<List<Book>> GetBooksByAuthorAsync(string author);
}
```
- IRepository：ABP提供的通用仓储接口，包含Get、GetList、Insert等基础方法。

4.3 应用层（Application）#

应用层负责协调业务流程，不包含核心业务规则（核心逻辑在领域层）。分为两个子项目：

4.3.1 Application.Contracts（契约）#

DTO：数据传输对象（用于前后端数据交换，避免暴露领域实体）；
应用服务接口：定义应用层对外提供的功能（如IBookAppService）。

示例：BookStore.Application.Contracts/Books/IBookAppService.cs

public interface IBookAppService : ICrudAppService<
    BookDto,          // 返回DTO
    Guid,             // 主键类型
    PagedAndSortedResultRequestDto, // 分页查询DTO
    CreateUpdateBookDto>            // 新增/修改DTO
{
    // 可添加自定义方法（如导出Excel）
}

ICrudAppService：ABP提供的通用CRUD接口，自动实现GetList、Get、Create、Update、Delete方法。

4.3.2 Application（实现）#

实现应用服务接口，调用领域层或仓储完成业务逻辑。

示例：BookStore.Application/Books/BookAppService.cs

public class BookAppService : CrudAppService<Book, BookDto, Guid, PagedAndSortedResultRequestDto, CreateUpdateBookDto>, IBookAppService
{
    public BookAppService(IRepository<Book, Guid> repository)
        : base(repository) // 注入通用仓储
    {
    }
 
    // 可选：覆盖默认方法（如自定义查询过滤）
    protected override IQueryable<Book> CreateFilteredQuery(PagedAndSortedResultRequestDto input)
    {
        return base.CreateFilteredQuery(input)
            .Where(b => b.Price > 0); // 仅返回价格>0的图书
    }
}

4.4 基础设施层（Infrastructure）#

基础设施层负责技术细节实现，如数据库访问、第三方服务集成。

关键文件：#

DbContext：EF Core上下文，配置实体映射。
BookStore.Infrastructure/BookStoreDbContext.cs

public class BookStoreDbContext : AbpDbContext<BookStoreDbContext>
{
    public DbSet<Book> Books { get; set; } // 数据库表映射
 
    public BookStoreDbContext(DbContextOptions<BookStoreDbContext> options)
        : base(options)
    {
    }
 
    protected override void OnModelCreating(ModelBuilder builder)
    {
        base.OnModelCreating(builder);
        builder.ConfigureBookStore(); // 加载领域层的实体配置
    }
}

实体配置：定义实体与数据库表的映射（如字段长度、索引）。
BookStore.Domain/Books/BookEntityTypeConfiguration.cs

public class BookEntityTypeConfiguration : IEntityTypeConfiguration<Book>
{
    public void Configure(EntityTypeBuilder<Book> builder)
    {
        builder.ToTable("Books"); // 数据库表名
        builder.Property(b => b.Name).IsRequired().HasMaxLength(128); // 书名必填，最长128字符
        builder.Property(b => b.Price).HasColumnType("decimal(18,2)"); // 价格精度
    }
}

4.5 表现层（Presentation）#

表现层分为后端API与前端UI：

4.5.1 后端API（Web项目）#

ABP自动为应用服务生成RESTful API控制器，无需手动编写。例如：

IBookAppService会生成/api/app/book接口，支持GET（查询）、POST（新增）、PUT（修改）、DELETE（删除）。

4.5.2 前端UI（Angular）#

Angular项目基于ABP Angular库，集成了Material Design、路由、身份认证等功能。核心文件：

src/app/app.module.ts：根模块，导入ABP模块（如AbpAuthModule、AbpRouterModule）；
src/environments/environment.ts：环境配置（API地址、客户端ID）；
src/app/proxy/：自动生成的API代理服务（通过abp generate-proxy生成）。

4.6 测试层（Test）#

ABP生成的测试项目遵循分层测试原则：

Domain.Tests：领域层单元测试（测试实体、领域服务）；
Application.Tests：应用层集成测试（测试应用服务，使用内存数据库）；
Web.Tests：API接口测试（使用WebApplicationFactory模拟请求）。

ABP核心功能快速上手#

5.1 模块化系统与预构建模块#

ABP的模块化设计是其核心优势之一。预构建模块覆盖了常见功能，无需重复开发：

模块	功能
Identity	用户、角色、权限管理
Tenant Management	多租户支持（Saas场景）
Audit Logging	操作日志记录与查询
Feature Management	动态功能开关（如“ premium 功能”）
File Management	文件上传下载

使用模块：#

通过[DependsOn]属性在模块中引入依赖。例如，在BookStoreWebModule中引入Identity模块：

[DependsOn(
    typeof(BookStoreApplicationModule),
    typeof(BookStoreInfrastructureModule),
    typeof(AbpIdentityWebModule) // 引入Identity模块
)]
public class BookStoreWebModule : AbpModule
{
}

5.2 身份认证与授权（Identity模块）#

ABP的Identity模块提供基于OAuth2/OpenID Connect的身份认证，以及细粒度权限控制。

示例：获取用户列表#

在应用服务中注入IIdentityUserAppService：

public class MyAppService : ApplicationService
{
    private readonly IIdentityUserAppService _userService;
 
    public MyAppService(IIdentityUserAppService userService)
    {
        _userService = userService;
    }
 
    public async Task<List<UserDto>> GetUsersAsync()
    {
        var result = await _userService.GetListAsync(new GetIdentityUsersInput());
        return result.Items;
    }
}

权限控制：#

定义权限：在Domain项目中添加权限常量：

public static class BookStorePermissions
{
    public const string Books = "BookStore.Books"; // 图书管理权限
}

配置权限：通过PermissionDefinitionProvider注册权限：

public class BookStorePermissionDefinitionProvider : PermissionDefinitionProvider
{
    public override void Define(IPermissionDefinitionContext context)
    {
        var group = context.AddGroup("BookStore");
        group.AddPermission(BookStorePermissions.Books, L("Permission:Books"));
    }
}

应用权限：在应用服务或控制器上添加[Authorize]属性：

[Authorize(BookStorePermissions.Books)]
public class BookAppService : CrudAppService<Book, BookDto, Guid, ...>
{
}

5.3 数据访问与EF Core集成#

ABP通过IRepository接口抽象数据访问，支持EF Core与MongoDB。以下是EF Core的常用操作：

1. 查询数据#

var book = await _repository.GetAsync(id); // 根据ID查询
var books = await _repository.GetListAsync(b => b.Author == "鲁迅"); // 条件查询

2. 新增数据#

var book = new Book { Name = "呐喊", Author = "鲁迅", Price = 39.9m };
await _repository.InsertAsync(book);

3. 事务处理#

ABP通过IUnitOfWork接口管理事务：

[UnitOfWork] // 自动开启事务
public async Task UpdateBookAsync(Guid id, CreateUpdateBookDto input)
{
    var book = await _repository.GetAsync(id);
    ObjectMapper.Map(input, book);
    await _repository.UpdateAsync(book);
}

5.4 自动API控制器与DTO映射#

自动API控制器#

ABP自动为实现IApplicationService的类生成API控制器。例如：

应用服务BookAppService会生成/api/app/book接口；
HTTP方法映射：GetList→GET、Create→POST、Update→PUT、Delete→DELETE。

DTO映射#

ABP使用AutoMapper自动映射领域实体与DTO。例如：

Book（实体）→BookDto（DTO）的映射由ABP自动完成；

自定义映射：在Application模块中配置：

public override void ConfigureServices(ServiceConfigurationContext context)
{
    Configure<AbpAutoMapperOptions>(options =>
    {
        options.AddMap<Book, BookDto>(map =>
        {
            map.ForMember(dest => dest.AuthorName, opt => opt.MapFrom(src => src.Author));
        });
    });
}

运行并验证项目#

6.1 数据库迁移与种子数据#

ABP提供DbMigrator工具自动应用迁移并初始化数据：

打开BookStore.DbMigrator项目的appsettings.json，配置数据库连接字符串：

"ConnectionStrings": {
    "Default": "Server=(localdb)\\mssqllocaldb;Database=BookStore;Trusted_Connection=True;"
}

运行DbMigrator项目（设置为启动项目，或执行dotnet run）；
工具会自动：
- 应用所有未执行的EF Core迁移；
- 种子初始化数据（如admin用户：admin/1q2w3E*）。

6.2 启动API服务#

打开BookStore.Web项目的appsettings.json，确认连接字符串正确；
运行BookStore.Web项目（或执行dotnet run）；
API服务将运行在https://localhost:5001，可通过/swagger访问Swagger文档。

6.3 启动前端UI#

进入BookStore.Angular目录，安装依赖：
```
npm install
```
启动Angular开发服务器：
```
npm start
```
浏览器访问http://localhost:4200，使用admin/1q2w3E*登录。

自定义功能示例：图书管理模块#

接下来，我们通过添加“图书管理”功能演示ABP的自定义开发流程。

7.1 定义领域实体（Book）#

在BookStore.Domain/Books目录下创建Book.cs：

using Volo.Abp.Domain.Entities.Auditing;
 
public class Book : AuditedAggregateRoot<Guid>
{
    public string Name { get; set; } = string.Empty;
    public string Author { get; set; } = string.Empty;
    public decimal Price { get; set; }
    public DateTime PublishDate { get; set; }
}

AuditedAggregateRoot<Guid>：继承后自动添加审计字段（CreationTime、CreatorId、LastModificationTime）。

7.2 配置EF Core上下文#

在BookStore.Domain/Books目录下创建实体配置BookEntityTypeConfiguration.cs：

using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Metadata.Builders;
 
public class BookEntityTypeConfiguration : IEntityTypeConfiguration<Book>
{
    public void Configure(EntityTypeBuilder<Book> builder)
    {
        builder.ToTable("Books");
        builder.Property(b => b.Name).IsRequired().HasMaxLength(128);
        builder.Property(b => b.Author).IsRequired().HasMaxLength(64);
        builder.Property(b => b.Price).HasColumnType("decimal(18,2)");
    }
}

在BookStoreDomainModule中注册配置：

public static class BookStoreDomainDbContextModelCreatingExtensions
{
    public static void ConfigureBookStore(this ModelBuilder builder)
    {
        builder.ApplyConfiguration(new BookEntityTypeConfiguration()); // 注册Book配置
    }
}

7.3 创建应用服务（BookAppService）#

在BookStore.Application.Contracts/Books目录下创建IBookAppService.cs：

using Volo.Abp.Application.Services;
 
public interface IBookAppService : ICrudAppService<
    BookDto,
    Guid,
    PagedAndSortedResultRequestDto,
    CreateUpdateBookDto>
{
}

在BookStore.Application/Books目录下创建BookAppService.cs：

using Volo.Abp.Application.Services;
using Volo.Abp.Domain.Repositories;
 
public class BookAppService : CrudAppService<Book, BookDto, Guid, PagedAndSortedResultRequestDto, CreateUpdateBookDto>, IBookAppService
{
    public BookAppService(IRepository<Book, Guid> repository)
        : base(repository)
    {
    }
}

7.4 定义DTO（数据传输对象）#

在BookStore.Application.Contracts/Books目录下创建BookDto.cs：

using Volo.Abp.Application.Dtos;
 
public class BookDto : AuditedEntityDto<Guid>
{
    public string Name { get; set; } = string.Empty;
    public string Author { get; set; } = string.Empty;
    public decimal Price { get; set; }
    public DateTime PublishDate { get; set; }
}

创建CreateUpdateBookDto.cs（新增/修改图书的DTO）：

using System.ComponentModel.DataAnnotations;
 
public class CreateUpdateBookDto
{
    [Required]
    [StringLength(128)]
    public string Name { get; set; } = string.Empty;
 
    [Required]
    [StringLength(64)]
    public string Author { get; set; } = string.Empty;
 
    [Range(0, 1000)]
    public decimal Price { get; set; }
 
    [Required]
    public DateTime PublishDate { get; set; }
}

7.5 生成前端代理与UI页面#

7.5.1 生成API代理#

在Angular项目目录下运行：

abp generate-proxy -t ng

此命令会生成src/app/proxy/services/book.service.ts，封装了/api/app/book接口的调用。

7.5.2 创建Angular组件#

在Angular项目中创建BooksComponent，使用生成的代理服务查询图书：

import { Component, OnInit } from '@angular/core';
import { BookService, BookDto } from '@proxy/books';
import { PagedAndSortedResultRequestDto } from '@abp/ng.core';
 
@Component({
  selector: 'app-books',
  template: `
    <abp-table [dataSource]="books$" [loading]="loading">
      <ng-container matColumnDef="name">
        <th mat-header-cell *matHeaderCellDef>书名</th>
        <td mat-cell *matCellDef="let book">{{ book.name }}</td>
      </ng-container>
      <ng-container matColumnDef="author">
        <th mat-header-cell *matHeaderCellDef>作者</th>
        <td mat-cell *matCellDef="let book">{{ book.author }}</td>
      </ng-container>
      <ng-container matColumnDef="price">
        <th mat-header-cell *matHeaderCellDef>价格</th>
        <td mat-cell *matCellDef="let book">{{ book.price | currency }}</td>
      </ng-container>
      <tr mat-header-row *matHeaderRowDef="displayedColumns"></tr>
      <tr mat-row *matRowDef="let row; columns: displayedColumns;"></tr>
    </abp-table>
  `,
})
export class BooksComponent implements OnInit {
  displayedColumns = ['name', 'author', 'price'];
  books$ = this.bookService.getList(new PagedAndSortedResultRequestDto());
  loading = false;
 
  constructor(private bookService: BookService) {}
 
  ngOnInit(): void {}
}

7.6 测试自定义功能#

运行DbMigrator应用，应用图书表的迁移；
启动API服务与Angular UI；
登录后导航到/books页面，尝试新增、修改、删除图书，验证功能是否正常。

ABP开发最佳实践#

严格遵循DDD原则：
- 领域逻辑放在Domain层，应用服务仅协调流程；
- 使用值对象（如Money、Address）表示不可变数据；
- 避免在应用服务中直接操作数据库（通过仓储接口）。
优先使用ABP内置服务：
- 不要重复造轮子（如用户管理用IIdentityUserAppService）；
- 使用IRepository而非直接操作DbContext。
模块化设计：
- 将独立功能封装为模块（如“支付模块”）；
- 模块间通过契约（Application.Contracts）通信，避免直接依赖。
权限与审计：
- 为每个功能添加权限（如BookStore.Books）；
- 使用AuditedAggregateRoot自动记录操作日志。
测试分层：
- 单元测试覆盖领域层（实体、领域服务）；
- 集成测试覆盖应用层（使用内存数据库）；
- E2E测试覆盖关键业务流程（如“下单”）。

常见问题排查#

9.1 数据库迁移失败#

原因：连接字符串错误、数据库权限不足、迁移文件过时；
解决：
1. 检查DbMigrator与Web项目的appsettings.json连接字符串；
2. 确保SQL Server服务已启动；
3. 重新生成迁移：dotnet ef migrations add AddBookTable --project ../BookStore.Infrastructure。

9.2 前端无法连接API#

原因：CORS配置错误、API地址错误、身份认证失败；
解决：
1. 检查Web项目的CORS配置（允许http://localhost:4200）；
2. 确认Angular项目的environment.ts中apiUrl为https://localhost:5001；
3. 检查浏览器控制台的401错误（身份认证失败，重新登录）。

9.3 依赖注入错误#

原因：服务未注册、接口与实现不匹配；
解决：
1. 确保服务类标记了[Dependency]属性（或在模块中注册）；
2. 检查接口与实现的命名（如IBookAppService对应BookAppService）。

9.4 权限未生效#

原因：权限未注册、未分配给用户/角色；
解决：
1. 检查PermissionDefinitionProvider是否注册了权限；
2. 在UI的“权限管理”中为admin角色分配BookStore.Books权限；
3. 确保应用服务添加了[Authorize]属性。

结论#

通过本教程，你已经掌握了ABP的核心工作流：

使用CLI/Suite初始化项目；
理解ABP的分层架构与DDD实践；
快速开发自定义模块（图书管理）；
应用最佳实践与排查常见问题。

ABP的强大之处在于模块化与** conventions over configuration**（约定优于配置），让你专注于业务逻辑而非技术细节。后续可以继续探索ABP的高级功能：

多租户支持；
背景任务（IBackgroundJob）；
本地化（多语言）；
微服务架构。

参考资料#

ABP官方文档：https://docs.abp.io/zh-Hans/abp/latest/
ABP CLI命令参考：https://docs.abp.io/zh-Hans/abp/latest/CLI
ABP Angular文档：https://docs.abp.io/zh-Hans/abp/latest/UI/Angular
EF Core文档：https://learn.microsoft.com/zh-cn/ef/core/
ABP GitHub仓库：https://github.com/abpframework/abp

Happy Coding！ 🚀