在实际企业级开发中.NET 平台因其成熟的生态、稳定的性能和丰富的工具链成为构建高可用后端服务的优选方案。但很多初学者在环境配置、项目结构设计和部署上线环节容易遇到版本冲突、依赖管理混乱、配置缺失等问题。本文将围绕一个完整的订单管理系统开发流程从环境准备开始逐步实现用户认证、数据持久化、API 设计、异常处理到生产部署帮助读者建立可复用的工程化开发习惯。1. 环境准备与工具链配置1.1 选择适合长期维护的开发环境虽然 Visual Studio 提供了完整的 .NET 开发体验但在团队协作和持续集成场景下更推荐使用 VS Code 命令行工具的组合。这种组合能让你更清楚每个操作背后的实际命令便于后续编写自动化脚本。首先确认操作系统版本和架构# Windows 用户查看系统信息 eer systeminfo | findstr /B /C:OS 名称 /C:OS 版本 # macOS/Linux 用户查看系统信息 uname -a根据系统类型下载安装 .NET SDK建议选择长期支持版本Windows x64下载 .NET 8.0 SDK 安装包macOS ARM64使用 Homebrew 安装brew install --cask dotnet-sdkLinux Ubuntu按照微软官方文档添加包源后安装验证安装是否成功dotnet --version # 预期输出8.0.100 或更高版本 dotnet --list-sdks # 查看所有已安装的 SDK 版本1.2 配置开发工具和必要插件在 VS Code 中安装以下核心扩展C# Dev Kit提供项目管理、测试运行器和调试支持C#语言智能提示和语法高亮.NET Extension Pack包含常用 .NET 开发工具NuGet Package Manager可视化管理依赖包创建全局 NuGet 配置避免每次手动添加源!-- ~/.nuget/NuGet/NuGet.Config -- ?xml version1.0 encodingutf-8? configuration packageSources add keynuget.org valuehttps://api.nuget.org/v3/index.json / add keycompany-internal valuehttps://nuget.company.com/v3/index.json / /packageSources /configuration1.3 设置项目工作目录结构企业级项目需要清晰的目录分离避免后期维护混乱OrderManagementSystem/ ├── src/ │ ├── OrderManagement.API/ # Web API 项目 │ ├── OrderManagement.Core/ # 核心业务逻辑 │ ├── OrderManagement.Infrastructure/ # 数据访问和外部服务 │ └── OrderManagement.Shared/ # 公共模型和工具类 ├── tests/ │ ├── OrderManagement.API.Tests/ # API 集成测试 │ ├── OrderManagement.Core.Tests/ # 单元测试 │ └── TestHelpers/ # 测试辅助类 ├── scripts/ # 构建和部署脚本 ├── docs/ # 项目文档 └──pipeline/ # CI/CD 配置2. 创建领域模型和数据库设计2.1 定义核心业务实体从订单管理的核心需求出发先设计领域模型。在OrderManagement.Core/Entities/目录下创建基础实体类// 基础实体抽象类 public abstract class BaseEntity { public int Id { get; set; } public DateTime CreatedAt { get; set; } DateTime.UtcNow; public DateTime? UpdatedAt { get; set; } public bool IsDeleted { get; set; } } // 用户实体 public class User : BaseEntity { public string Username { get; set; } string.Empty; public string Email { get; set; } string.Empty; public string PasswordHash { get; set; } string.Empty; public UserRole Role { get; set; } UserRole.Customer; // 导航属性 public virtual ICollectionOrder Orders { get; set; } new ListOrder(); } public enum UserRole { Customer, Admin, Manager }2.2 配置 Entity Framework Core 数据上下文在 Infrastructure 项目中配置数据库上下文和实体映射// OrderManagement.Infrastructure/Data/ApplicationDbContext.cs public class ApplicationDbContext : DbContext { public ApplicationDbContext(DbContextOptionsApplicationDbContext options) : base(options) { } public DbSetUser Users SetUser(); public DbSetOrder Orders SetOrder(); public DbSetProduct Products SetProduct(); protected override void OnModelCreating(ModelBuilder modelBuilder) { // 配置软删除查询过滤器 modelBuilder.EntityUser().HasQueryFilter(u !u.IsDeleted); modelBuilder.EntityOrder().HasQueryFilter(o !o.IsDeleted); modelBuilder.EntityProduct().HasQueryFilter(p !p.IsDeleted); // 配置索引提升查询性能 modelBuilder.EntityUser() .HasIndex(u u.Email) .IsUnique(); modelBuilder.EntityOrder() .HasIndex(o new { o.UserId, o.CreatedAt }); } }2.3 数据库迁移和种子数据创建初始迁移并添加必要的测试数据# 在 Infrastructure 项目目录下执行 dotnet ef migrations add InitialCreate --context ApplicationDbContext dotnet ef database update --context ApplicationDbContext配置开发环境种子数据// OrderManagement.Infrastructure/Data/SeedData.cs public static class SeedData { public static void Initialize(ApplicationDbContext context) { if (context.Users.Any()) return; // 避免重复种子数据 var users new[] { new User { Username admin, Email adminorders.com, Role UserRole.Admin }, new User { Username manager, Email managerorders.com, Role UserRole.Manager } }; context.Users.AddRange(users); context.SaveChanges(); } }3. 实现分层架构和依赖注入3.1 配置依赖注入容器在 API 项目的 Program.cs 中注册所有必要的服务// OrderManagement.API/Program.cs var builder WebApplication.CreateBuilder(args); // 数据库配置 builder.Services.AddDbContextApplicationDbContext(options options.UseSqlServer(builder.Configuration.GetConnectionString(DefaultConnection))); // 注册仓储和服务 builder.Services.AddScopedIUserRepository, UserRepository(); builder.Services.AddScopedIOrderService, OrderService(); builder.Services.AddScopedIJwtService, JwtService(); // 配置 JWT 认证 builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options { options.TokenValidationParameters new TokenValidationParameters { ValidateIssuer true, ValidateAudience true, ValidateLifetime true, ValidateIssuerSigningKey true, ValidIssuer builder.Configuration[Jwt:Issuer], ValidAudience builder配置[Jwt:Audience], IssuerSigningKey new SymmetricSecurityKey( Encoding.UTF8.GetBytes(builder.Configuration[Jwt:SecretKey])) }; }); // 添加 Swagger 文档 builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(c { c.SwaggerDoc(v1, new OpenApiInfo { Title Order Management API, Version v1 }); }); var app builder.Build();3.2 实现仓储模式和数据访问层在 Infrastructure 项目中实现具体的仓储类// OrderManagement.Infrastructure/Repositories/UserRepository.cs public class UserRepository : IUserRepository { private readonly ApplicationDbContext _context; public UserRepository(ApplicationDbContext context) { _context context; } public async TaskUser? GetByIdAsync(int id) { return await _context.Users .FirstOrDefaultAsync(u u.Id id !u.IsDeleted); } public async TaskUser? GetByEmailAsync(string email) { return await _context.Users .FirstOrDefaultAsync(u u.Email email !u.IsDeleted); } public async Task AddAsync(User user) { await _context.Users.AddAsync(user); await _context.SaveChangesAsync(); } public async Task UpdateAsync(User user) { user.UpdatedAt DateTime.UtcNow; _context.Users.Update(user); await _context.SaveChangesAsync(); } public async Task DeleteAsync(int id) { var user await GetByIdAsync(id); if (user ! null) { user.IsDeleted true; await UpdateAsync(user); } } }3.3 实现业务逻辑服务层在 Core 项目中定义服务接口和实现// OrderManagement.Core/Interfaces/Services/IOrderService.cs public interface IOrderService { TaskOrderResult CreateOrderAsync(CreateOrderRequest request); TaskOrderDetailResult GetOrderDetailAsync(int orderId, int userId); TaskPagedResultOrderSummary GetUserOrdersAsync(int userId, int page, int pageSize); } // OrderManagement.Core/Services/OrderService.cs public class OrderService : IOrderService { private readonly IOrderRepository _orderRepository; private readonly IProductRepository _productRepository; private readonly ILoggerOrderService _logger; public OrderService(IOrderRepository orderRepository, IProductRepository productRepository, ILoggerOrderService logger) { _orderRepository orderRepository; _productRepository productRepository; _logger logger; } public async TaskOrderResult CreateOrderAsync(CreateOrderRequest request) { // 验证产品是否存在和库存充足 var product await _productRepository.GetByIdAsync(request.ProductId); if (product null) { return OrderResult.Failure(产品不存在); } if (product.StockQuantity request.Quantity) { return OrderResult.Failure($库存不足当前库存{product.StockQuantity}); } // 创建订单 var order new Order { UserId request.UserId, TotalAmount product.Price * request.Quantity, OrderItems new ListOrderItem { new OrderItem { ProductId product.Id, Quantity request.Quantity, UnitPrice product.Price } } }; try { await _orderRepository.AddAsync(order); // 更新产品库存 product.StockQuantity - request.Quantity; await _productRepository.UpdateAsync(product); _logger.LogInformation(订单创建成功订单号{OrderId}, order.Id); return OrderResult.Success(order.Id); } catch (Exception ex) { _logger.LogError(ex, 创建订单时发生错误); return OrderResult.Failure(创建订单失败); } } }4. 设计 RESTful API 和控制器4.1 实现认证和授权控制器创建用户认证相关的 API 端点// OrderManagement.API/Controllers/AuthController.cs [ApiController] [Route(api/[controller])] public class AuthController : ControllerBase { private readonly IUserService _userService; private readonly IJwtService _jwtService; public AuthController(IUserService userService, IJwtService jwtService) { _userService userService; _jwtService jwtService; } [HttpPost(register)] public async TaskIActionResult Register(RegisterRequest request) { var result await _userService.RegisterAsync(request); if (!result.Success) { return BadRequest(new { errors result.Errors }); } return Ok(new { message 注册成功 }); } [HttpPost(login)] public async TaskIActionResult Login(LoginRequest request) { var user await _userService.ValidateCredentialsAsync(request.Email, request.Password); if (user null) { return Unauthorized(new { error 用户名或密码错误 }); } var token _jwtService.GenerateToken(user); return Ok(new { token token, user new { id user.Id, email user.Email, role user.Role } }); } }4.2 实现订单管理 API创建需要认证的订单相关端点// OrderManagement.API/Controllers/OrdersController.cs [ApiController] [Route(api/[controller])] [Authorize] public class OrdersController : ControllerBase { private readonly IOrderService _orderService; private readonly ILoggerOrdersController _logger; public OrdersController(IOrderService orderService, ILoggerOrdersController logger) { _orderService orderService; _logger logger; } [HttpPost] public async TaskIActionResult CreateOrder(CreateOrderRequest request) { var userId int.Parse(User.FindFirst(Claim
在实际企业级开发中.NET 平台因其成熟的生态、稳定的性能和丰富的工具链成为构建高可用后端服务的优选方案。但很多初学者在环境配置、项目结构设计和部署上线环节容易遇到版本冲突、依赖管理混乱、配置缺失等问题。本文将围绕一个完整的订单管理系统开发流程从环境准备开始逐步实现用户认证、数据持久化、API 设计、异常处理到生产部署帮助读者建立可复用的工程化开发习惯。1. 环境准备与工具链配置1.1 选择适合长期维护的开发环境虽然 Visual Studio 提供了完整的 .NET 开发体验但在团队协作和持续集成场景下更推荐使用 VS Code 命令行工具的组合。这种组合能让你更清楚每个操作背后的实际命令便于后续编写自动化脚本。首先确认操作系统版本和架构# Windows 用户查看系统信息 eer systeminfo | findstr /B /C:OS 名称 /C:OS 版本 # macOS/Linux 用户查看系统信息 uname -a根据系统类型下载安装 .NET SDK建议选择长期支持版本Windows x64下载 .NET 8.0 SDK 安装包macOS ARM64使用 Homebrew 安装brew install --cask dotnet-sdkLinux Ubuntu按照微软官方文档添加包源后安装验证安装是否成功dotnet --version # 预期输出8.0.100 或更高版本 dotnet --list-sdks # 查看所有已安装的 SDK 版本1.2 配置开发工具和必要插件在 VS Code 中安装以下核心扩展C# Dev Kit提供项目管理、测试运行器和调试支持C#语言智能提示和语法高亮.NET Extension Pack包含常用 .NET 开发工具NuGet Package Manager可视化管理依赖包创建全局 NuGet 配置避免每次手动添加源!-- ~/.nuget/NuGet/NuGet.Config -- ?xml version1.0 encodingutf-8? configuration packageSources add keynuget.org valuehttps://api.nuget.org/v3/index.json / add keycompany-internal valuehttps://nuget.company.com/v3/index.json / /packageSources /configuration1.3 设置项目工作目录结构企业级项目需要清晰的目录分离避免后期维护混乱OrderManagementSystem/ ├── src/ │ ├── OrderManagement.API/ # Web API 项目 │ ├── OrderManagement.Core/ # 核心业务逻辑 │ ├── OrderManagement.Infrastructure/ # 数据访问和外部服务 │ └── OrderManagement.Shared/ # 公共模型和工具类 ├── tests/ │ ├── OrderManagement.API.Tests/ # API 集成测试 │ ├── OrderManagement.Core.Tests/ # 单元测试 │ └── TestHelpers/ # 测试辅助类 ├── scripts/ # 构建和部署脚本 ├── docs/ # 项目文档 └──pipeline/ # CI/CD 配置2. 创建领域模型和数据库设计2.1 定义核心业务实体从订单管理的核心需求出发先设计领域模型。在OrderManagement.Core/Entities/目录下创建基础实体类// 基础实体抽象类 public abstract class BaseEntity { public int Id { get; set; } public DateTime CreatedAt { get; set; } DateTime.UtcNow; public DateTime? UpdatedAt { get; set; } public bool IsDeleted { get; set; } } // 用户实体 public class User : BaseEntity { public string Username { get; set; } string.Empty; public string Email { get; set; } string.Empty; public string PasswordHash { get; set; } string.Empty; public UserRole Role { get; set; } UserRole.Customer; // 导航属性 public virtual ICollectionOrder Orders { get; set; } new ListOrder(); } public enum UserRole { Customer, Admin, Manager }2.2 配置 Entity Framework Core 数据上下文在 Infrastructure 项目中配置数据库上下文和实体映射// OrderManagement.Infrastructure/Data/ApplicationDbContext.cs public class ApplicationDbContext : DbContext { public ApplicationDbContext(DbContextOptionsApplicationDbContext options) : base(options) { } public DbSetUser Users SetUser(); public DbSetOrder Orders SetOrder(); public DbSetProduct Products SetProduct(); protected override void OnModelCreating(ModelBuilder modelBuilder) { // 配置软删除查询过滤器 modelBuilder.EntityUser().HasQueryFilter(u !u.IsDeleted); modelBuilder.EntityOrder().HasQueryFilter(o !o.IsDeleted); modelBuilder.EntityProduct().HasQueryFilter(p !p.IsDeleted); // 配置索引提升查询性能 modelBuilder.EntityUser() .HasIndex(u u.Email) .IsUnique(); modelBuilder.EntityOrder() .HasIndex(o new { o.UserId, o.CreatedAt }); } }2.3 数据库迁移和种子数据创建初始迁移并添加必要的测试数据# 在 Infrastructure 项目目录下执行 dotnet ef migrations add InitialCreate --context ApplicationDbContext dotnet ef database update --context ApplicationDbContext配置开发环境种子数据// OrderManagement.Infrastructure/Data/SeedData.cs public static class SeedData { public static void Initialize(ApplicationDbContext context) { if (context.Users.Any()) return; // 避免重复种子数据 var users new[] { new User { Username admin, Email adminorders.com, Role UserRole.Admin }, new User { Username manager, Email managerorders.com, Role UserRole.Manager } }; context.Users.AddRange(users); context.SaveChanges(); } }3. 实现分层架构和依赖注入3.1 配置依赖注入容器在 API 项目的 Program.cs 中注册所有必要的服务// OrderManagement.API/Program.cs var builder WebApplication.CreateBuilder(args); // 数据库配置 builder.Services.AddDbContextApplicationDbContext(options options.UseSqlServer(builder.Configuration.GetConnectionString(DefaultConnection))); // 注册仓储和服务 builder.Services.AddScopedIUserRepository, UserRepository(); builder.Services.AddScopedIOrderService, OrderService(); builder.Services.AddScopedIJwtService, JwtService(); // 配置 JWT 认证 builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options { options.TokenValidationParameters new TokenValidationParameters { ValidateIssuer true, ValidateAudience true, ValidateLifetime true, ValidateIssuerSigningKey true, ValidIssuer builder.Configuration[Jwt:Issuer], ValidAudience builder配置[Jwt:Audience], IssuerSigningKey new SymmetricSecurityKey( Encoding.UTF8.GetBytes(builder.Configuration[Jwt:SecretKey])) }; }); // 添加 Swagger 文档 builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(c { c.SwaggerDoc(v1, new OpenApiInfo { Title Order Management API, Version v1 }); }); var app builder.Build();3.2 实现仓储模式和数据访问层在 Infrastructure 项目中实现具体的仓储类// OrderManagement.Infrastructure/Repositories/UserRepository.cs public class UserRepository : IUserRepository { private readonly ApplicationDbContext _context; public UserRepository(ApplicationDbContext context) { _context context; } public async TaskUser? GetByIdAsync(int id) { return await _context.Users .FirstOrDefaultAsync(u u.Id id !u.IsDeleted); } public async TaskUser? GetByEmailAsync(string email) { return await _context.Users .FirstOrDefaultAsync(u u.Email email !u.IsDeleted); } public async Task AddAsync(User user) { await _context.Users.AddAsync(user); await _context.SaveChangesAsync(); } public async Task UpdateAsync(User user) { user.UpdatedAt DateTime.UtcNow; _context.Users.Update(user); await _context.SaveChangesAsync(); } public async Task DeleteAsync(int id) { var user await GetByIdAsync(id); if (user ! null) { user.IsDeleted true; await UpdateAsync(user); } } }3.3 实现业务逻辑服务层在 Core 项目中定义服务接口和实现// OrderManagement.Core/Interfaces/Services/IOrderService.cs public interface IOrderService { TaskOrderResult CreateOrderAsync(CreateOrderRequest request); TaskOrderDetailResult GetOrderDetailAsync(int orderId, int userId); TaskPagedResultOrderSummary GetUserOrdersAsync(int userId, int page, int pageSize); } // OrderManagement.Core/Services/OrderService.cs public class OrderService : IOrderService { private readonly IOrderRepository _orderRepository; private readonly IProductRepository _productRepository; private readonly ILoggerOrderService _logger; public OrderService(IOrderRepository orderRepository, IProductRepository productRepository, ILoggerOrderService logger) { _orderRepository orderRepository; _productRepository productRepository; _logger logger; } public async TaskOrderResult CreateOrderAsync(CreateOrderRequest request) { // 验证产品是否存在和库存充足 var product await _productRepository.GetByIdAsync(request.ProductId); if (product null) { return OrderResult.Failure(产品不存在); } if (product.StockQuantity request.Quantity) { return OrderResult.Failure($库存不足当前库存{product.StockQuantity}); } // 创建订单 var order new Order { UserId request.UserId, TotalAmount product.Price * request.Quantity, OrderItems new ListOrderItem { new OrderItem { ProductId product.Id, Quantity request.Quantity, UnitPrice product.Price } } }; try { await _orderRepository.AddAsync(order); // 更新产品库存 product.StockQuantity - request.Quantity; await _productRepository.UpdateAsync(product); _logger.LogInformation(订单创建成功订单号{OrderId}, order.Id); return OrderResult.Success(order.Id); } catch (Exception ex) { _logger.LogError(ex, 创建订单时发生错误); return OrderResult.Failure(创建订单失败); } } }4. 设计 RESTful API 和控制器4.1 实现认证和授权控制器创建用户认证相关的 API 端点// OrderManagement.API/Controllers/AuthController.cs [ApiController] [Route(api/[controller])] public class AuthController : ControllerBase { private readonly IUserService _userService; private readonly IJwtService _jwtService; public AuthController(IUserService userService, IJwtService jwtService) { _userService userService; _jwtService jwtService; } [HttpPost(register)] public async TaskIActionResult Register(RegisterRequest request) { var result await _userService.RegisterAsync(request); if (!result.Success) { return BadRequest(new { errors result.Errors }); } return Ok(new { message 注册成功 }); } [HttpPost(login)] public async TaskIActionResult Login(LoginRequest request) { var user await _userService.ValidateCredentialsAsync(request.Email, request.Password); if (user null) { return Unauthorized(new { error 用户名或密码错误 }); } var token _jwtService.GenerateToken(user); return Ok(new { token token, user new { id user.Id, email user.Email, role user.Role } }); } }4.2 实现订单管理 API创建需要认证的订单相关端点// OrderManagement.API/Controllers/OrdersController.cs [ApiController] [Route(api/[controller])] [Authorize] public class OrdersController : ControllerBase { private readonly IOrderService _orderService; private readonly ILoggerOrdersController _logger; public OrdersController(IOrderService orderService, ILoggerOrdersController logger) { _orderService orderService; _logger logger; } [HttpPost] public async TaskIActionResult CreateOrder(CreateOrderRequest request) { var userId int.Parse(User.FindFirst(Claim
