放个MD文件测试一下

.NET Web API 项目创建与核心结构解析

一、CLI 初始化项目

在终端执行以下命令建立全新的 Web API 解决方案。建议先创建解决方案文件，再添加具体项目，这样便于后续扩展为多层架构：

dotnet new sln -n StoreMgmt
dotnet new webapi -n StoreMgmt.Backend --framework net8.0 --use-controllers
dotnet sln add StoreMgmt.Backend/StoreMgmt.Backend.csproj

参数拆解：

• new sln：生成解决方案文件，用于多项目管理
• --framework net8.0：明确目标框架，避免默认版本差异
• --use-controllers：启用基于控制器的传统模式，便于后续分层

若需添加类库作为领域层，可继续执行：

dotnet new classlib -n StoreMgmt.Core
dotnet sln add StoreMgmt.Core/StoreMgmt.Core.csproj

二、目录组织建议

项目创建完成后，推荐按以下方式调整文件夹结构：

StoreMgmt.Backend/
├── Controllers/        # API 控制器层，处理 HTTP 请求
├── Models/             # 实体与 DTO，定义数据契约
├── Data/               # DbContext 与迁移脚本
├── Services/           # 业务逻辑接口及实现
├── Middleware/         # 自定义中间件
├── Properties/         # 启动配置与 launchSettings
├── appsettings.json    # 运行时配置
└── Program.cs          # 启动入口

这种结构将关注点分离，方便单元测试和后期维护。Controllers 只负责接收请求与返回响应，不应包含复杂业务逻辑。

三、Program.cs 启动文件详解

.NET 8 采用隐式 using 与顶级语句，启动代码极为精简，但背后仍遵循经典的双阶段模式：

var builder = WebApplication.CreateBuilder(args);

// 1. 服务注册阶段（DI 容器构建）
builder.Services.AddControllers();
builder.Services.AddOpenApi();

// 2. 构建应用实例
var app = builder.Build();

// 3. 中间件流水线配置
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

// 4. 启动服务器并监听请求
app.Run();

关键点说明：

• CreateBuilder 读取 appsettings.json、环境变量、命令行参数等配置源
• AddControllers 将控制器发现、模型绑定、验证等服务注入容器
• UseHttpsRedirection 强制重定向到 HTTPS 端口，生产环境建议保留
• MapControllers 扫描并注册所有带有 [ApiController] 的路由特性

四、launchSettings.json 的作用

Properties/launchSettings.json 控制本地调试行为，典型内容如下：

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "profiles": {
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "https://localhost:7123;http://localhost:5123"
    }
  }
}

调试时可通过 --launch-profile https 指定监听地址。applicationUrl 同时监听 HTTP 与 HTTPS 两个端口，便于本地切换测试。

五、appsettings 多环境管理

ASP.NET Core 支持按环境加载不同配置：

• appsettings.json：公共默认配置
• appsettings.Development.json：开发环境覆盖项
• appsettings.Production.json：生产环境覆盖项

加载优先级为：环境变量 > appsettings.{Environment}.json > appsettings.json。利用此机制，可将开发数据库与生产连接字符串隔离存放。

六、依赖注入基础

框架内置的 DI 容器支持三种生命周期：

生命周期	注册方法	适用场景
单例	AddSingleton	全局共享、无状态服务
作用域	AddScoped	每个 HTTP 请求一个实例
瞬时	AddTransient	轻量级、无状态工具类

在控制器中通过构造函数注入即可使用：

public class ProductsController : ControllerBase
{
    private readonly IProductService _svc;
    public ProductsController(IProductService svc) => _svc = svc;
}

七、常用 CLI 命令备忘

命令	用途
dotnet run	编译并启动项目
dotnet watch	热重载调试，文件变更自动重启
dotnet build	仅编译，不运行
dotnet clean	清除生成的二进制文件
dotnet add package <包名>	安装 NuGet 依赖
dotnet list package	查看已安装包列表

八、中间件执行顺序

中间件的注册顺序至关重要，请求按注册顺序进入，响应则逆序返回。典型顺序如下：

app.UseExceptionHandler();
app.UseHttpsRedirection();
app.UseCors();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();

若将 UseAuthentication 放在 UseAuthorization 之后，授权逻辑会因缺少用户身份而失效。因此务必遵循官方推荐顺序。

九、API 版本控制建议

对于长期维护的项目，可在路由中引入版本号：

[Route("api/v1/[controller]")]
public class ProductsController : ControllerBase { }

这样后续发布 v2 时，不会破坏现有客户端调用，实现平滑升级。

掌握上述内容即可搭建一个干净、可扩展的 Web API 工程骨架，为后续数据访问层与业务层开发奠定基础。