1. 项目概述一个基于Clean Architecture与CQRS的银行信贷系统后端最近在梳理企业级应用架构时我重新审视并重构了一个银行信贷系统的后端项目。这个项目不是一个简单的CRUD演示而是一个力求贴近真实生产环境、强调架构清晰度和可维护性的实战案例。它的核心目标很明确为银行或金融机构提供一个稳定、可扩展、易于团队协作的信贷业务处理后台。无论是处理个人客户的消费贷款申请还是企业客户的大额经营贷系统都需要在保证业务逻辑正确性的同时应对高并发、需求频繁变更以及团队人员流动的挑战。为了实现这个目标我放弃了传统的、所有逻辑都堆在Controller里的三层架构转而采用了Clean Architecture整洁架构与CQRS命令查询职责分离的组合拳。Clean Architecture的核心思想是让业务逻辑领域层成为系统的核心它不依赖于任何外部框架、数据库或UI。数据库、Web API等都只是可插拔的“插件”。这样做的好处是当未来需要更换数据库比如从SQL Server迁移到PostgreSQL或者升级Web框架时核心的业务规则几乎不需要改动。而CQRS则进一步将“写操作”如创建客户、提交贷款申请和“读操作”如查询客户列表、查看申请详情在架构上分离开使用不同的模型来处理。这不仅能优化读写性能更重要的是让复杂的业务逻辑命令端和灵活的查询需求查询端可以独立演化代码意图更加清晰。整个技术栈基于**.NET 8构建这是目前LTS的稳定版本。数据访问层使用了Entity Framework Core 8作为ORM它大大简化了与SQL Server数据库的交互。为了优雅地实现CQRS模式我引入了MediatR这个轻量级的进程内中介者库它就像系统内部的“消息总线”将请求Command/Query自动路由到对应的处理器Handler。对象映射交给了AutoMapper**避免了我们手动在Entity和DTO之间进行繁琐的属性赋值。输入验证则使用FluentValidation它以流畅的接口方式提供了强大且可读性极高的验证规则定义能力。最后通过JWTJSON Web Token来实现API的安全认证。这套技术选型在.NET生态中经过了大量生产环境的检验成熟、稳定且社区活跃能有效支撑起一个严肃的后端项目。2. 架构设计与核心思路拆解2.1 为什么选择Clean Architecture在项目初期我面临的首要抉择就是架构选型。传统的“数据库驱动”开发模式先设计表再写代码虽然上手快但长期来看隐患很大。业务逻辑会逐渐渗透到数据访问层甚至UI层导致代码高度耦合。一旦业务规则变化或者需要支持新的数据源比如增加一个缓存或搜索引擎改动就会牵一发而动全身测试也变得异常困难。Clean Architecture也称为洋葱架构提供了一个截然不同的视角。它将系统划分为同心圆层依赖关系严格地由外向内。最内层是领域层Domain这里包含了最纯粹的业务实体如CustomerLoanApplication和业务规则。它不应该引用任何外层如数据库、Web框架的代码。向外一层是应用层Application它负责协调领域对象来完成具体的用例Use Case比如“提交贷款申请”这个用例它会调用领域实体进行信用评分计算然后通过接口通知基础设施层持久化数据。再外层是基础设施层Infrastructure/Persistence和表现层Web API它们实现领域层或应用层定义的接口比如具体的数据库操作、发送邮件的服务等。这种架构带来的最大好处是可测试性和持久化无关性。因为领域逻辑不依赖任何外部东西你可以轻松地为其编写单元测试无需启动数据库或Web服务器。同时今天用SQL Server明天想换MongoDB你只需要在基础设施层实现一个新的IRepository领域和应用层的代码完全不用动。这为系统的长期演进打下了坚实的基础。注意Clean Architecture的学习曲线相对陡峭初期需要投入更多时间在分层和设计接口上。但对于一个业务逻辑复杂、且预期生命周期较长的系统如金融系统这笔投资是绝对值得的。它强迫开发者深入思考业务边界产出更高质量的代码。2.2 CQRS模式在信贷系统中的实践CQRS常常被误解为必须搭配事件溯源Event Sourcing或者读写分离数据库。其实在最基本的层面上CQRS只是一种模式将修改状态的操作命令和读取数据的操作查询使用不同的对象模型来处理。在信贷系统中这个模式的应用场景非常自然。命令端Command Side处理写操作CreateCustomerCommandSubmitLoanApplicationCommandApproveLoanCommand。这些命令通常对应着复杂的业务流程。例如提交贷款申请时系统需要验证客户资质、计算初步利率、生成申请流水号并可能触发风控初审。这些操作具有事务性并且会改变系统的状态。在实现上一个命令对应一个CommandHandler里面封装了完整的业务逻辑。查询端Query Side处理读操作GetCustomerDetailQueryGetLoanApplicationListQuery。查询通常很简单就是获取数据并展示不改变任何状态。它的模型可以和命令端的领域实体完全不同可以是为了满足前端页面展示而高度定制化的DTO数据传输对象。例如客户列表查询可能只需要IdNameCreditScore三个字段而命令端操作的是包含数十个属性的完整Customer实体。我使用MediatR来统一调度这些Command和Query。在Controller中你不再需要注入一堆Service只需要注入一个IMediator然后发送相应的请求对象即可。这使得Controller变得极其瘦小和专注只负责HTTP协议相关的事情如路由、模型绑定、返回状态码业务逻辑全部转移到了应用层的Handler中。这种设计让代码的职责划分无比清晰新人接手项目时很容易就能找到业务逻辑的入口。2.3 项目分层结构详解根据Clean Architecture的原则我将项目解耦为以下几个独立的类库.csproj每个都有明确的职责边界BankingCreditSystem.Domain (领域层)核心实体Entities如IndividualCustomer个人客户、CorporateCustomer企业客户、LoanApplication贷款申请、LoanType贷款类型。这些是富领域模型包含数据和与之相关的行为方法如Customer.CalculateCreditScore()。值对象Value Objects如Address地址、Money金额。它们没有唯一标识通过属性值来定义。领域服务Domain Services当某个业务逻辑不适合放在任何单个实体内部时如复杂的信用评分规则引擎会放在这里。仓储接口Repository Interfaces如ICustomerRepositoryILoanApplicationRepository。这里只定义接口具体实现在基础设施层。BankingCreditSystem.Application (应用层)用例Use Cases这是CQRS模式的核心体现层。包含Commands、Queries以及它们的Handlers。Commands定义写操作如CreateIndividualCustomerCommand。包含执行该命令所需的数据。Queries定义读操作如GetIndividualCustomerDetailQuery。包含查询参数。Handlers包含具体的业务逻辑。一个Handler处理一个Command或Query。它会调用领域实体、领域服务并通过接口调用基础设施层完成持久化或外部服务调用。DTOs专门用于在层间传输数据的对象如IndividualCustomerDto。映射配置ProfilesAutoMapper的配置文件定义领域实体与DTO之间的转换规则。行为管道Behaviors利用MediatR的管道行为可以方便地实现横切关注点如日志、性能监控、验证等。我在项目中就用它来统一处理FluentValidation。BankingCreditSystem.Persistence (基础设施层 - 持久化)DbContextEntity Framework Core的数据库上下文定义了DbSet和模型关系配置。仓储实现Repository Implementations具体实现领域层定义的仓储接口如CustomerRepository。内部使用DbContext进行数据操作。数据库迁移MigrationsEF Core的代码优先迁移文件。配置类数据库连接字符串等配置的读取和注册。BankingCreditSystem.WebApi (表现层)ControllersASP.NET Core的API控制器。它们非常精简主要工作就是接收HTTP请求将其转换为MediatR的Command/Query发送出去然后返回结果。中间件Middleware如全局异常处理中间件。当系统任何地方抛出未处理异常时这个中间件会捕获它并返回一个格式统一、友好的错误响应而不是暴露堆栈信息给客户端。启动配置Startup/Program依赖注入容器配置、中间件管道配置、Swagger文档生成、JWT认证配置等都在这里完成。BankingCreditSystem.Core (共享内核)这是一个可选的层用于放置所有其他层都可能用到的通用代码。通用接口如IEntity所有实体的基接口、IAuditableEntity审计接口包含CreatedDateCreatedBy等字段。自定义异常如NotFoundExceptionValidationException。工具类与扩展方法一些通用的帮助方法。这种分层确保了依赖的方向是WebApi - Application - Domain 同时Persistence和WebApi都引用Application和Domain。Domain是绝对的核心它不依赖于任何其他层。3. 核心模块实现细节与实操要点3.1 领域模型设计客户与信贷申请领域模型是系统的灵魂。在信贷系统中我设计了几个核心的聚合根Aggregate RootCustomer客户抽象基类作为一个抽象类包含客户通用信息如唯一标识Id、基础联系信息。它有两个派生类IndividualCustomer个人客户增加NationalId身份证号、BirthDate、MonthlyIncome等属性。CorporateCustomer企业客户增加TaxNumber税号、CompanyEstablishmentDate、AnnualRevenue等属性。 使用继承是为了清晰地表达“是一个is-a”的关系并且在业务逻辑上对个人和企业的信用评估方式截然不同。LoanApplication贷款申请这是一个状态丰富的聚合根。它包含ApplicationNumber申请编号业务唯一标识按规则生成。ApplicantId关联的客户ID。LoanTypeId申请的贷款类型ID如抵押贷、信用贷。Amount申请金额、Term贷款期限。Status状态枚举类型如Draft草稿、Submitted已提交、UnderReview审核中、Approved已批准、Rejected已拒绝。CreditScore系统计算的信用评分。行为方法如Submit()方法会将状态从Draft改为Submitted并可能触发领域事件如LoanApplicationSubmittedEvent。LoanType贷款类型定义产品如“个人消费贷”、“企业经营贷”包含NameInterestRateRange利率范围、MaxAmount最高额度等。在设计时我遵循了“将关联设计为ID引用而非对象引用”的原则。例如LoanApplication中只保存ApplicantId而不是整个Customer对象。这保证了聚合的边界清晰加载一个贷款申请时不会无意中加载出庞大的客户对象图提升了性能。3.2 应用层CQRS与MediatR的协同应用层是业务流程的协调者。我们以“创建个人客户”这个用例来看CQRS命令端的实现。首先在Application层下的Features/IndividualCustomers/Commands/Create目录中我们定义命令及其处理器1. Command命令// CreateIndividualCustomerCommand.cs public class CreateIndividualCustomerCommand : IRequestGuid // 返回新客户的ID { public string FirstName { get; set; } public string LastName { get; set; } public string NationalId { get; set; } public DateTime BirthDate { get; set; } public decimal MonthlyIncome { get; set; } // ... 其他属性 }2. Validator验证器// CreateIndividualCustomerCommandValidator.cs public class CreateIndividualCustomerCommandValidator : AbstractValidatorCreateIndividualCustomerCommand { public CreateIndividualCustomerCommandValidator() { RuleFor(v v.NationalId) .NotEmpty().WithMessage(身份证号不能为空) .Length(18).WithMessage(身份证号必须为18位) .Must(BeAValidNationalId).WithMessage(无效的身份证号格式); // 自定义校验逻辑 RuleFor(v v.MonthlyIncome) .GreaterThan(0).WithMessage(月收入必须大于0); RuleFor(v v.BirthDate) .LessThan(DateTime.Now.AddYears(-18)).WithMessage(客户必须年满18周岁); // ... 更多规则 } private bool BeAValidNationalId(string nationalId) { /* 校验逻辑 */ } }3. Handler处理器// CreateIndividualCustomerCommandHandler.cs public class CreateIndividualCustomerCommandHandler : IRequestHandlerCreateIndividualCustomerCommand, Guid { private readonly IIndividualCustomerRepository _customerRepository; private readonly IMapper _mapper; public CreateIndividualCustomerCommandHandler(IIndividualCustomerRepository customerRepository, IMapper mapper) { _customerRepository customerRepository; _mapper mapper; } public async TaskGuid Handle(CreateIndividualCustomerCommand request, CancellationToken cancellationToken) { // 1. 业务规则校验可选复杂规则可放在领域实体中 // 例如检查身份证号是否已存在 var existingCustomer await _customerRepository.GetByNationalIdAsync(request.NationalId, cancellationToken); if (existingCustomer ! null) { throw new ValidationException(该身份证号已注册。); } // 2. 映射Command到领域实体 var customer _mapper.MapIndividualCustomer(request); // 或者使用更显式的方式 var customer new IndividualCustomer(request.FirstName, ...); // 3. 调用领域实体的行为如果有 customer.InitializeCreditScore(); // 假设有一个初始化信用评分的方法 // 4. 持久化 await _customerRepository.AddAsync(customer, cancellationToken); await _customerRepository.SaveChangesAsync(cancellationToken); // 5. 返回结果 return customer.Id; } }查询端的实现类似但更简单。例如GetIndividualCustomerDetailQueryHandler它接收一个ID通过仓储接口获取数据然后用AutoMapper映射成IndividualCustomerDetailDto返回。DTO的结构完全由前端需求决定可能只包含部分字段。3.3 基础设施层Entity Framework Core与仓储模式在Persistence层我实现了领域层定义的仓储接口。这里的关键是DbContext的设计和仓储的实现。DbContext(AppDbContext.cs)public class AppDbContext : DbContext { public DbSetIndividualCustomer IndividualCustomers { get; set; } public DbSetCorporateCustomer CorporateCustomers { get; set; } public DbSetLoanApplication LoanApplications { get; set; } public DbSetLoanType LoanTypes { get; set; } public AppDbContext(DbContextOptionsAppDbContext options) : base(options) { } protected override void OnModelCreating(ModelBuilder modelBuilder) { // 应用所有在当前程序集中定义的IEntityTypeConfiguration modelBuilder.ApplyConfigurationsFromAssembly(Assembly.GetExecutingAssembly()); // 或者单独配置 modelBuilder.EntityIndividualCustomer(entity { entity.ToTable(IndividualCustomers); entity.HasIndex(e e.NationalId).IsUnique(); // 为身份证号创建唯一索引 entity.Property(e e.MonthlyIncome).HasPrecision(18, 2); // 精确小数位 }); // 配置继承关系TPHTable-Per-Hierarchy模式 modelBuilder.EntityCustomer() .HasDiscriminatorstring(CustomerType) .HasValueIndividualCustomer(Individual) .HasValueCorporateCustomer(Corporate); } }仓储实现(IndividualCustomerRepository.cs)public class IndividualCustomerRepository : IIndividualCustomerRepository { private readonly AppDbContext _dbContext; public IndividualCustomerRepository(AppDbContext dbContext) { _dbContext dbContext; } public async TaskIndividualCustomer GetByIdAsync(Guid id, CancellationToken cancellationToken) { return await _dbContext.SetIndividualCustomer() .FirstOrDefaultAsync(e e.Id id, cancellationToken); } public async TaskIndividualCustomer GetByNationalIdAsync(string nationalId, CancellationToken cancellationToken) { return await _dbContext.SetIndividualCustomer() .FirstOrDefaultAsync(e e.NationalId nationalId, cancellationToken); } public async Task AddAsync(IndividualCustomer entity, CancellationToken cancellationToken) { await _dbContext.SetIndividualCustomer().AddAsync(entity, cancellationToken); } // ... 其他方法Update, Delete, GetList等 }仓储实现通常很薄只是对DbContext的简单封装。它的价值在于抽象数据访问应用层不直接依赖EF Core如果未来要换Dapper只需修改仓储实现。聚合根边界一个仓储通常对应一个聚合根明确了数据修改的入口点。便于测试可以轻松为仓储接口创建Mock或Stub。3.4 Web API层精简的控制器与全局配置在Clean Architecture下Controller的责任被极大简化。以IndividualCustomersController为例[ApiController] [Route(api/[controller])] public class IndividualCustomersController : ControllerBase { private readonly IMediator _mediator; public IndividualCustomersController(IMediator mediator) { _mediator mediator; } [HttpPost] [ProducesResponseType(typeof(Guid), StatusCodes.Status201Created)] [ProducesResponseType(StatusCodes.Status400BadRequest)] public async TaskActionResultGuid Create(CreateIndividualCustomerCommand command) { var customerId await _mediator.Send(command); return CreatedAtAction(nameof(GetById), new { id customerId }, customerId); } [HttpGet({id})] [ProducesResponseType(typeof(IndividualCustomerDetailDto), StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status404NotFound)] public async TaskActionResultIndividualCustomerDetailDto GetById(Guid id) { var query new GetIndividualCustomerDetailQuery { Id id }; var result await _mediator.Send(query); if (result null) return NotFound(); return Ok(result); } // ... 其他Action: GetList, Update, Delete }可以看到每个Action几乎只是将HTTP请求参数包装成对应的Command或Query然后通过IMediator发送出去。所有的业务逻辑、验证、数据访问都发生在应用层的Handler中。这使得Controller变得极其可读和可维护。在Program.cs或Startup.cs中我们需要完成所有依赖的装配var builder WebApplication.CreateBuilder(args); // 1. 配置数据库上下文 builder.Services.AddDbContextAppDbContext(options options.UseSqlServer(builder.Configuration.GetConnectionString(DefaultConnection))); // 2. 注册MediatR并指定从Application层扫描Handler builder.Services.AddMediatR(cfg cfg.RegisterServicesFromAssembly(typeof(CreateIndividualCustomerCommandHandler).Assembly)); // 3. 注册AutoMapper从Application层扫描Profile builder.Services.AddAutoMapper(typeof(IndividualCustomerProfile).Assembly); // 4. 注册FluentValidation并将其注入MediatR的Pipeline builder.Services.AddValidatorsFromAssembly(typeof(CreateIndividualCustomerCommandValidator).Assembly); builder.Services.AddTransient(typeof(IPipelineBehavior,), typeof(ValidationBehavior,)); // 5. 注册仓储 builder.Services.AddScopedIIndividualCustomerRepository, IndividualCustomerRepository(); // ... 注册其他仓储 // 6. 配置JWT认证 builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options { /* 配置Token验证参数 */ }); // 7. 添加Swagger/OpenAPI支持 builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(c { c.SwaggerDoc(v1, new OpenApiInfo { Title Banking Credit API, Version v1 }); // 配置JWT Bearer Token支持 c.AddSecurityDefinition(Bearer, new OpenApiSecurityScheme { /* ... */ }); }); var app builder.Build(); // 8. 配置中间件管道 if (app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(); } app.UseHttpsRedirection(); // 9. 使用自定义的全局异常处理中间件 app.UseMiddlewareExceptionHandlingMiddleware(); app.UseAuthentication(); app.UseAuthorization(); app.MapControllers(); app.Run();4. 关键配置、部署与测试策略4.1 数据库迁移与种子数据使用EF Core的代码优先迁移是管理数据库 schema 变更的标准做法。在开发过程中当你修改了领域实体后可以通过以下命令创建迁移# 在Persistence项目目录下 dotnet ef migrations add AddCreditScoreFieldToCustomer --startup-project ../BankingCreditSystem.WebApi这条命令会分析当前DbContext模型与上次迁移的差异并在Persistence/Migrations文件夹下生成一个新的迁移文件。审查生成的Up和Down方法以确保符合预期然后应用迁移到数据库dotnet ef database update --startup-project ../BankingCreditSystem.WebApi对于生产环境通常会将迁移脚本生成SQL文件由DBA审核后执行。种子数据对于系统初始化至关重要比如初始的贷款类型LoanType、管理员用户等。我通常在Persistence层创建一个SeedData类并在Program.cs中应用迁移后自动运行种子逻辑public static class SeedData { public static async Task InitializeAsync(IServiceProvider serviceProvider) { using var scope serviceProvider.CreateScope(); var context scope.ServiceProvider.GetRequiredServiceAppDbContext(); // 确保数据库已创建并应用了最新迁移 await context.Database.MigrateAsync(); if (!context.LoanTypes.Any()) { context.LoanTypes.AddRange( new LoanType { Name 个人信用消费贷, MaxAmount 200000m, InterestRateMin 0.039m, InterestRateMax 0.15m }, new LoanType { Name 个人房屋抵押贷, MaxAmount 5000000m, InterestRateMin 0.035m, InterestRateMax 0.06m }, new LoanType { Name 企业经营性贷款, MaxAmount 10000000m, InterestRateMin 0.04m, InterestRateMax 0.08m } ); await context.SaveChangesAsync(); } } } // 在Program.cs的app.Run()之前调用 await SeedData.InitializeAsync(app.Services);4.2 JWT认证与授权配置在金融系统中安全是重中之重。我使用JWT Bearer Token进行无状态认证。生成JWT配置在appsettings.json中配置密钥和有效期。JwtSettings: { Secret: YourSuperSecretKeyHere_MustBeLongAndComplex!, Issuer: BankingCreditSystem, Audience: BankingCreditSystemClients, ExpiryInMinutes: 60 }配置认证服务builder.Services.AddAuthentication(options { options.DefaultAuthenticateScheme JwtBearerDefaults.AuthenticationScheme; options.DefaultChallengeScheme JwtBearerDefaults.AuthenticationScheme; }) .AddJwtBearer(options { options.TokenValidationParameters new TokenValidationParameters { ValidateIssuer true, ValidateAudience true, ValidateLifetime true, ValidateIssuerSigningKey true, ValidIssuer builder.Configuration[JwtSettings:Issuer], ValidAudience builder.Configuration[JwtSettings:Audience], IssuerSigningKey new SymmetricSecurityKey(Encoding.UTF8.GetBytes(builder.Configuration[JwtSettings:Secret])) }; });创建登录端点创建一个AuthController接收用户名密码验证后生成Token返回。保护API在需要认证的Controller或Action上添加[Authorize]特性。重要安全提示生产环境中Secret必须通过安全的密钥管理服务如Azure Key Vault AWS Secrets Manager或环境变量获取绝对不要硬编码在代码或配置文件中。同时务必使用HTTPS来传输Token。4.3 单元测试与集成测试策略良好的架构为测试提供了便利。我的测试策略如下领域层单元测试针对领域实体和领域服务中的核心业务规则进行测试。由于它们不依赖外部资源测试速度快且稳定。使用xUnit或NUnit框架。public class LoanApplicationTests { [Fact] public void Submit_Should_ChangeStatusToSubmitted() { // Arrange var application new LoanApplication(...) { Status ApplicationStatus.Draft }; // Act application.Submit(); // Assert Assert.Equal(ApplicationStatus.Submitted, application.Status); } }应用层单元测试测试CommandHandler和QueryHandler。这里需要使用Mock框架如Moq来模拟仓储接口等外部依赖专注于测试Handler内部的业务协调逻辑。public class CreateIndividualCustomerCommandHandlerTests { [Fact] public async Task Handle_GivenValidCommand_ShouldCreateCustomerAndReturnId() { // Arrange var mockRepo new MockIIndividualCustomerRepository(); mockRepo.Setup(repo repo.GetByNationalIdAsync(It.IsAnystring(), It.IsAnyCancellationToken())) .ReturnsAsync((IndividualCustomer)null); // 模拟身份证号不存在 mockRepo.Setup(repo repo.AddAsync(It.IsAnyIndividualCustomer(), It.IsAnyCancellationToken())) .Returns(Task.CompletedTask); // ... 模拟SaveChangesAsync等 var handler new CreateIndividualCustomerCommandHandler(mockRepo.Object, ...); var command new CreateIndividualCustomerCommand { ... }; // Act var result await handler.Handle(command, CancellationToken.None); // Assert Assert.NotEqual(Guid.Empty, result); mockRepo.Verify(repo repo.AddAsync(It.IsAnyIndividualCustomer(), It.IsAnyCancellationToken()), Times.Once); } }集成测试针对整个API端点或涉及数据库的流程进行测试。我会使用WebApplicationFactory来启动一个内存中的测试服务器并使用一个独立的测试数据库如SQLite In-Memory或LocalDB。这可以测试从Controller到数据库的完整链路。public class IndividualCustomersControllerIntegrationTests : IClassFixtureCustomWebApplicationFactory { private readonly HttpClient _client; public IndividualCustomersControllerIntegrationTests(CustomWebApplicationFactory factory) { _client factory.CreateClient(); } [Fact] public async Task Post_ShouldCreateCustomerAndReturnId() { // Arrange var command new { ... }; var content new StringContent(JsonSerializer.Serialize(command), Encoding.UTF8, application/json); // Act var response await _client.PostAsync(/api/IndividualCustomers, content); // Assert response.EnsureSuccessStatusCode(); var customerId await response.Content.ReadFromJsonAsyncGuid(); Assert.NotEqual(Guid.Empty, customerId); } }4.4 使用Docker容器化部署为了确保环境一致性我强烈推荐使用Docker进行部署。创建一个Dockerfile放在解决方案根目录或WebApi项目下# 使用.NET 8 SDK镜像来构建 FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build WORKDIR /src COPY [BankingCreditSystem.WebApi/BankingCreditSystem.WebApi.csproj, BankingCreditSystem.WebApi/] COPY [BankingCreditSystem.Application/BankingCreditSystem.Application.csproj, BankingCreditSystem.Application/] COPY [BankingCreditSystem.Domain/BankingCreditSystem.Domain.csproj, BankingCreditSystem.Domain/] COPY [BankingCreditSystem.Persistence/BankingCreditSystem.Persistence.csproj, BankingCreditSystem.Persistence/] COPY [BankingCreditSystem.Core/BankingCreditSystem.Core.csproj, BankingCreditSystem.Core/] RUN dotnet restore BankingCreditSystem.WebApi/BankingCreditSystem.WebApi.csproj COPY . . WORKDIR /src/BankingCreditSystem.WebApi RUN dotnet build BankingCreditSystem.WebApi.csproj -c Release -o /app/build FROM build AS publish RUN dotnet publish BankingCreditSystem.WebApi.csproj -c Release -o /app/publish # 使用运行时镜像 FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS final WORKDIR /app EXPOSE 80 EXPOSE 443 COPY --frompublish /app/publish . ENTRYPOINT [dotnet, BankingCreditSystem.WebApi.dll]然后使用docker build和docker run命令即可运行。结合docker-compose.yml可以轻松地将API与SQL Server数据库容器一起启动。5. 常见问题、性能优化与扩展思考5.1 开发与部署中的常见问题依赖注入错误无法解析服务问题启动时或运行时提示Unable to resolve service for type X。排查首先检查Program.cs中是否注册了该服务AddScopedAddTransient等。然后检查服务生命周期是否匹配例如在Singleton服务中注入了Scoped服务。最后确保所有项目引用正确特别是接口和实现在正确的层中。AutoMapper映射配置错误问题运行时抛出AutoMapper.AutoMapperMappingException。排查检查Profile类中的CreateMap配置确保源类型和目标类型的属性名能正确匹配或已显式配置。对于嵌套对象或集合映射需要更详细的配置。建议在单元测试中覆盖主要的映射场景。MediatR请求未找到Handler问题发送Command或Query时提示No handler registered。排查确认AddMediatR注册时指定的程序集包含了你的Handler。确保Handler类实现了IRequestHandlerTRequest TResponse接口并且请求对象TRequest与Handler定义的完全一致。EF Core迁移冲突或数据库更新失败问题执行dotnet ef database update失败。排查检查迁移文件是否与当前模型同步。可以尝试dotnet ef migrations remove移除最近迁移修正模型后重新添加。检查连接字符串是否正确数据库服务器是否可访问。检查是否有未应用的旧迁移dotnet ef migrations list。在生产环境务必先备份数据库并在测试环境验证迁移脚本。JWT Token无效或过期问题前端收到的401 Unauthorized错误。排查检查Token是否在请求头的Authorization字段中格式是否为Bearer token。使用 jwt.io 等工具解码Token检查exp过期时间、iss签发者、aud接收方是否与服务器配置一致。确保服务器时钟是准确的JWT验证依赖时间。5.2 性能优化建议数据库查询优化避免N1查询这是EF Core中最常见的性能问题。例如查询贷款申请列表时如果循环内又去查询每个申请对应的客户信息就会产生N1次查询。务必使用.Include()或投影.Select()到DTO来一次性加载所需数据。使用异步方法所有数据库调用ToListAsyncFirstOrDefaultAsyncSaveChangesAsync都应使用异步版本避免阻塞线程。索引策略为经常用于查询条件WHERE、连接JOIN和排序ORDER BY的字段创建数据库索引。例如Customer.NationalIdLoanApplication.StatusLoanApplication.ApplicantId。应用层优化分页查询对于列表查询API如GET /api/IndividualCustomers必须实现分页。在Query对象中加入PageNumber和PageSize参数在Handler中使用EF Core的.Skip()和.Take()方法。永远不要一次性查询所有数据。缓存策略对于不经常变化但频繁读取的数据如LoanType贷款类型可以使用内存缓存IMemoryCache或分布式缓存如Redis。在对应的QueryHandler中先尝试从缓存获取未命中则查询数据库并存入缓存。MediatR与CQRS的扩展对于极其复杂的查询如多表关联报表可以考虑将查询端完全独立使用专门的读模型数据库可以是另一个SQL Server实例甚至是Elasticsearch这样的搜索引擎。写模型命令端在数据变更时通过发布领域事件异步更新读模型。这属于高级CQRS模式能极大提升查询性能和系统可扩展性。5.3 项目扩展与演进方向这个项目提供了一个坚实的起点但一个完整的银行系统远不止于此。以下是一些可以继续深入的方向领域事件Domain Events与最终一致性当贷款申请状态变为Approved时可能需要触发“发送合同邮件”、“通知客户经理”等后续操作。这些操作不应该阻塞主业务流程。可以在领域实体中定义领域事件如LoanApplicationApprovedEvent在保存更改后通过MediatR发布这些事件。然后创建相应的EventHandler来异步处理这些事件实现系统的解耦和最终一致性。微服务拆分当系统规模增长可以考虑按业务边界拆分为微服务。例如客户服务专门管理客户信息。信贷产品服务管理贷款类型、利率模型。信贷审批工作流服务处理复杂的贷款审批流程。 每个服务都拥有独立的数据库并通过API网关和事件总线进行通信。Clean Architecture为这种拆分做好了准备因为每个服务的领域层都是高度内聚的。更强大的安全与合规操作审计实现详细的日志记录记录谁在什么时候做了什么尤其是敏感操作。可以通过实现IAuditableEntity接口在SaveChanges时自动填充CreatedByLastModifiedBy等字段或使用EF Core的拦截器。数据加密对数据库中的敏感信息如身份证号、手机号进行加密存储。API限流与防刷使用像AspNetCoreRateLimit这样的中间件来防止恶意请求。引入GraphQL如果前端需要极其灵活的数据查询能力例如一次请求获取客户及其所有贷款申请的详细信息可以考虑在现有的REST API旁边引入GraphQL端点。这可以作为查询端Query Side的一个强大补充。这个基于Clean Architecture和CQRS的银行信贷系统后端其价值不仅在于实现的功能更在于它展示了一种清晰、可维护、可测试的架构方式。从领域驱动设计出发严格的分层和职责分离使得代码在面对复杂业务逻辑和频繁变更时依然能够保持优雅和健壮。在实际开发中最大的挑战往往不是技术实现而是如何与团队就架构原则和编码规范达成一致并坚持执行。一旦这套模式成为团队习惯开发效率和代码质量将会得到质的提升。