从0到1搭建.NET Core Web API项目

1. 设置 .NET 8 Web API 项目

概念

使用 .NET CLI 创建新的 Web API 项目。这设置了一个基本的项目结构，包括启动和 WeatherForecast 控制器作为示例。Program.cs

代码示例

dotnet new webapi -n MyWebApi

2. Program.cs — 最低限度的 API 配置

概念

.NET 8 延续了最小 API 的趋势，允许你直接在 Program.cs 文件中以简化和简洁的方式配置服务和终结点。

代码示例

var builder = WebApplication.CreateBuilder(args);  
var app = builder.Build();  
app.MapGet("/", () => "Hello, World!");

app.Run();

3. 定义控制器

概念

控制器处理传入的 HTTP 请求并响应客户端。它们是通过继承自 ControllerBase 并使用 进行注释来定义的。[ApiController]

代码示例

[ApiController]  
[Route("[controller]")]  
public class MyController : ControllerBase  
{  
    [HttpGet]  
    public IActionResult Get() => Ok("Hello from MyController");  
}

4. 控制器中的依赖注入

概念

.NET Core 的内置依赖项注入 （DI） 使管理依赖项变得容易。您可以通过控制器的构造函数将服务注入控制器。

代码示例

public class MyService  
{  
    public string GetMessage() => "Injected message";  
}  
public class MyController : ControllerBase

{

private readonly MyService _myService;

public MyController(MyService myService)

{

_myService = myService;

}

[HttpGet]

public IActionResult Get() => Ok(_myService.GetMessage());

}

5. 配置服务

概念

服务（如数据库上下文、自定义服务等）在 Program.cs 文件中配置，使它们可用于整个应用程序的依赖项注入。

代码示例

builder.Services.AddScoped();

6. 基于环境的配置

概念

.NET 支持特定于环境的配置文件 （appsettings.json、appsettings.Development.json等），允许根据应用程序的环境进行不同的设置。

代码示例

// appsettings.Development.json  
{  
  "Logging": {  
    "LogLevel": {  
      "Default": "Debug"  
    }  
  }  
}

7. 中间件

概念

中间件组件形成一个处理请求和响应的管道。可以为日志记录或错误处理等跨领域问题创建自定义中间件。

代码示例

app.Use(async (context, next) =>  
{  
    // Custom logic before passing to the next middleware  
    await next();  
    // Custom logic after executing the next middleware  
});

8. 路由

概念

.NET Web API 中的路由是通过控制器和操作方法上的属性路由实现的。这允许将 URL 直接映射到控制器操作。

代码示例

[HttpGet("myaction/{id}")]  
public IActionResult GetAction(int id) => Ok($"Action with ID = {id}");

9. 模型绑定

概念

模型绑定自动将数据从 HTTP 请求映射到操作方法参数。它支持复杂类型，包括 JSON 正文和查询字符串参数。

代码示例

public class MyModel  
{  
    public int Id { get; set; }  
    public string Name { get; set; }  
}  
[HttpPost]

public IActionResult PostAction([FromBody] MyModel model) => Ok(model);

10. 数据验证

概念

数据注释可用于验证模型数据。该属性会自动强制执行验证，如果模型无效，则以 400 进行响应。[ApiController]

代码示例

public class MyModel  
{  
    [Required]  
    public int Id { get; set; }  
[StringLength(100)]  
public string Name { get; set; }  

}

11. 异步操作

概念

异步操作通过在等待 I/O 操作完成时释放线程来提高可伸缩性。使用关键字并返回 或 。asyncTaskTask

代码示例

[HttpGet("{id}")]  
public async Task GetAsync(int id)  
{  
    var result = await _service.GetByIdAsync(id);  
    return Ok(result);  
}

12. 全局处理异常

概念

全局异常处理允许对未处理的异常进行集中式错误处理、日志记录和标准化的 API 响应。

代码示例

app.UseExceptionHandler(a => a.Run(async context =>  
{  
    var exceptionHandlerPathFeature = context.Features.Get();  
    var exception = exceptionHandlerPathFeature.Error;  
    // Log the exception, generate a custom response, etc.  
    context.Response.StatusCode = 500;  
    await context.Response.WriteAsJsonAsync(new { Error = "An unexpected error occurred" });  
}));

13. API 版本控制

概念

API 版本控制有助于管理随时间推移对 API 的更改。.NET 平台支持通过查询字符串、URL 路径或请求标头进行版本控制。

代码示例

builder.Services.AddApiVersioning(options =>  
{  
    options.AssumeDefaultVersionWhenUnspecified = true;  
    options.DefaultApiVersion = new ApiVersion(1, 0);  
    options.ReportApiVersions = true;  
});

14. 内容协商

概念

内容协商允许 API 根据请求中的标头提供不同格式的响应，从而支持 JSON、XML 等格式。Accept

代码示例

builder.Services.AddControllers()  
    .AddXmlDataContractSerializerFormatters();

15. 自定义 JSON 序列化设置

概念

通过配置 JSON 序列化程序设置，自定义 JSON 响应格式，例如 camelCase 命名或忽略 null 值。

代码示例

builder.Services.AddControllers()  
    .AddJsonOptions(options =>  
    {  
        options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;  
        options.JsonSerializerOptions.IgnoreNullValues = true;  
    });

16. 配置 CORS

概念

跨域资源共享 （CORS） 允许从托管在不同域上的 Web 应用程序调用 API。根据您的要求配置 CORS 策略。

代码示例

builder.Services.AddCors(options =>  
{  
    options.AddPolicy("AllowSpecificOrigin",  
        builder => builder.WithOrigins("http://example.com"));  
});  
app.UseCors("AllowSpecificOrigin");

17. 身份验证

概念

通过启用身份验证来保护 API，身份验证可验证发出请求的用户或服务的身份。

代码示例

builder.Services.AddAuthentication("Bearer")  
    .AddJwtBearer(options =>  
    {  
        options.Authority = "https://your-auth-server";  
        options.Audience = "your-api";  
    });

18. 授权

概念

身份验证后，授权确定经过身份验证的用户是否有权执行操作或访问资源。

代码示例

[Authorize]  
public class SecureController : ControllerBase  
{  
    // Action methods here  
}

19. Swagger/OpenAPI 集成

概念

Swagger （OpenAPI） 为您的 API 提供交互式文档，使开发人员能够轻松理解和使用它。

代码示例

builder.Services.AddEndpointsApiExplorer();  
builder.Services.AddSwaggerGen();  
app.UseSwagger();  
app.UseSwaggerUI();

20. 日志记录

概念

.NET Core 提供了一个内置的日志记录框架，该框架可以将消息记录到各种输出（控制台、调试窗口、外部服务等）。

代码示例

logger.LogInformation("This is an informational message");  
app.Use(async (context, next) =>

{

logger.LogError("This is an error message before the next middleware");

await next.Invoke();

// Log after calling the next middleware

});

21. 使用 Entity Framework Core

概念

Entity Framework Core 是用于 .NET 应用程序中的数据访问的 ORM。它允许您使用强类型对象查询和操作数据。

代码示例

public class MyDbContext : DbContext  
{  
    public MyDbContext(DbContextOptions options) : base(options) {}  
    public DbSet MyModels { get; set; }  
}

22. Entity Framework Core 中的迁移

概念

迁移允许您通过跟踪数据模型中的更改将版本控制应用于数据库架构。

代码示例

dotnet ef migrations add InitialCreate  
dotnet ef database update

23. 存储库模式

概念

Repository 模式将数据层抽象化，使应用程序更加模块化且更易于维护。

代码示例

public interface IRepository  
{  
    Task<IEnumerable> GetAllAsync();  
    Task GetByIdAsync(int id);  
    // Other methods...  
}  
public class MyRepository : IRepository where T : class

{

private readonly MyDbContext _context;

public MyRepository(MyDbContext context)

{

_context = context;

}

// Implement methods...

}

24. 单元测试

概念

单元测试通过单独测试单个代码单元来确保 Web API 正常运行。

代码示例

public class MyControllerTests  
{  
    [Fact]  
    public async Task Get_ReturnsExpectedValue()  
    {  
        // Arrange  
        var serviceMock = new Mock();  
        serviceMock.Setup(service => service.GetAsync()).ReturnsAsync("test");  
        var controller = new MyController(serviceMock.Object);  
        // Act  
        var result = await controller.Get();  
        // Assert  
        Assert.Equal("test", result.Value);  
    }  
}

25. 与前端集成

概念

.NET Web API 可以充当前端应用程序的后端，提供 RESTful 服务。

代码示例

fetch('https://localhost:5001/mycontroller')  
  .then(response => response.json())  
  .then(data => console.log(data));

26. 健康检查

概念

运行状况检查提供了一种监视应用程序及其依赖项状态的方法，对微服务体系结构非常有用。

代码示例

builder.Services.AddHealthChecks();  
app.MapHealthChecks("/health");

27. 使用 SignalR 进行实时通信

概念

SignalR 启用实时 Web 功能，允许服务器端代码将异步通知发送到客户端 Web 应用程序。

代码示例

public class MyHub : Hub  
{  
    public async Task SendMessage(string user, string message)  
    {  
        await Clients.All.SendAsync("ReceiveMessage", user, message);  
    }  
}

28. 配置响应缓存

概念

响应缓存通过存储以前请求的资源的副本来减少服务器必须处理的请求数。

代码示例

[HttpGet("{id}")]  
[ResponseCache(Duration = 60)]  
public IActionResult GetById(int id)  
{  
    // Retrieve and return your resource  
}

29. 静态文件

概念

提供静态文件（HTML、CSS、JavaScript 等）对于使用 .NET Web API 支持前端应用程序至关重要。

代码示例

app.UseStaticFiles(); // Enable static file serving

30. 高级配置和选项模式

概念

选项模式使用类来表示相关设置的组。使用 ，您可以在应用程序中的任何位置访问这些设置。IOptions

代码示例

public class MySettings  
{  
    public string Setting1 { get; set; }  
    // Other settings  
}  
builder.Services.Configure(builder.Configuration.GetSection("MySettings"));

public class MyService

{

private readonly MySettings _settings;

public MyService(IOptions settings)

{

_settings = settings.Value;

}

// Use _settings.Setting1

}

31. 自定义中间件

概念

中间件是组装到应用程序管道中以处理请求和响应的软件。可以创建自定义中间件来执行特定任务。

代码示例

public class MyCustomMiddleware  
{  
    private readonly RequestDelegate _next;  
    public MyCustomMiddleware(RequestDelegate next)  
    {  
        _next = next;  
    }  
    public async Task Invoke(HttpContext httpContext)  
    {  
        // Pre-processing logic here  
        await _next(httpContext); // Call the next middleware in the pipeline  
        // Post-processing logic here  
    }  
}  
// Extension method for easy middleware registration  
public static class MyCustomMiddlewareExtensions  
{  
    public static IApplicationBuilder UseMyCustomMiddleware(this IApplicationBuilder builder)  
    {  
        return builder.UseMiddleware();  
    }  
}

32. 速率限制

概念

速率限制通过限制用户在特定时间范围内发出请求的频率来保护您的 API 免于过度使用。

代码示例

// Assume using a third-party library like AspNetCoreRateLimit  
builder.Services.AddInMemoryRateLimiting();  
builder.Services.Configure(options =>  
{  
    options.GeneralRules = new List  
    {  
        new RateLimitRule  
        {  
            Endpoint = "*",  
            Limit = 100,  
            Period = "1h"  
        }  
    };  
});

33. API 密钥身份验证

概念

API 密钥是验证和授权 API 调用的简单方法。它们在查询字符串或标头中从客户端传递到服务器。

代码示例

public class ApiKeyMiddleware  
{  
    private readonly RequestDelegate _next;  
    private const string APIKEYNAME = "x-api-key";  
    public ApiKeyMiddleware(RequestDelegate next)  
    {  
        _next = next;  
    }  
    public async Task Invoke(HttpContext context)  
    {  
        if (!context.Request.Headers.TryGetValue(APIKEYNAME, out var extractedApiKey))  
        {  
            context.Response.StatusCode = 401;  
            await context.Response.WriteAsync("API Key was not provided.");  
            return;  
        }  
        // Validate the extracted API Key here...  
        await _next(context);  
    }  
}

34. 输出缓存

概念

输出缓存允许您存储对请求的响应。可以从缓存中处理后续请求，从而显著提高性能。

代码示例

[HttpGet]  
[ResponseCache(Duration = 120, Location = ResponseCacheLocation.Client, NoStore = false)]  
public IActionResult Get()  
{  
    // Your logic here  
}

35. 后台任务

概念

后台任务使操作能够在后台运行，独立于用户请求，例如发送电子邮件或处理长时间运行的作业。

代码示例

public class MyBackgroundService : BackgroundService  
{  
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)  
    {  
        while (!stoppingToken.IsCancellationRequested)  
        {  
            // Your background task logic here  
            await Task.Delay(TimeSpan.FromHours(1), stoppingToken);  
        }  
    }  
}

36. 网络套接字

概念

WebSocket 通过单个长期连接提供全双工通信通道，是实时应用程序的理想选择。

代码示例

app.UseWebSockets();  
app.Use(async (context, next) =>  
{  
    if (context.WebSockets.IsWebSocketRequest)  
    {  
        WebSocket webSocket = await context.WebSockets.AcceptWebSocketAsync();  
        // Handle the WebSocket request here  
    }  
    else  
    {  
        await next();  
    }  
});

37. 请求本地化

概念

请求本地化提供了一种基于请求信息针对不同文化和语言本地化内容的方法。

代码示例

var supportedCultures = new[] { "en-US", "fr-FR" };  
var localizationOptions = new RequestLocalizationOptions()  
    .SetDefaultCulture(supportedCultures[0])  
    .AddSupportedCultures(supportedCultures)  
    .AddSupportedUICultures(supportedCultures);  
app.UseRequestLocalization(localizationOptions);

38. 与 GraphQL 集成

概念

GraphQL 是 API 的查询语言。将 .NET Web API 与 GraphQL 集成可以更高效地检索数据。

代码示例

// Assume using a library like HotChocolate  
builder.Services  
    .AddGraphQLServer()  
    .AddQueryType();  
app.MapGraphQL();

39. 监控和遥测

概念

监视和遥测涉及收集、分析和处理有关应用程序性能和使用情况的数据。

代码示例

// Assume using Application Insights  
builder.Services.AddApplicationInsightsTelemetry("YOUR_INSTRUMENTATION_KEY");

40. SignalR 集线器和实时通信

概念

SignalR 是一个库，可简化向应用添加实时 Web 功能的过程。实时 Web 功能是指服务器代码在内容发生时立即将内容推送到连接的客户端的能力，而不需要服务器等待客户端请求新数据。SignalR 非常适合开发聊天应用程序、实时仪表板和更具交互性的 Web 应用程序。

代码示例

public class ChatHub : Hub  
{  
    public async Task SendMessage(string user, string message)  
    {  
        // Call the broadcastMessage method to update clients.  
        await Clients.All.SendAsync("broadcastMessage", user, message);  
    }  
}  
// Startup or Program.cs

app.MapHub("/chathub");

集成Program.cs：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)  
{  
    // Other configurations...  
    app.UseEndpoints(endpoints =>  
    {  
        endpoints.MapHub("/chathub");  
    });  
}

41. 高级实体框架核心 — 关系

概念

Entity Framework Core 允许映射实体之间的复杂关系，例如一对一、一对多和多对多。

代码示例

public class Author  
{  
    public int AuthorId { get; set; }  
    public string Name { get; set; }  
    public ICollection\ Books { get; set; }  
}  
public class Book

{

public int BookId { get; set; }

public string Title { get; set; }

public int AuthorId { get; set; }

public Author Author { get; set; }

}

42. 自定义验证属性

概念

自定义验证属性允许您定义数据模型的验证逻辑，从而扩展内置验证属性。

代码示例

public class MyCustomValidationAttribute : ValidationAttribute  
{  
    protected override ValidationResult IsValid(object value, ValidationContext validationContext)  
    {  
        // Your custom validation logic here  
        if (value is int intValue && intValue > 0)  
        {  
            return ValidationResult.Success;  
        }  
        return new ValidationResult("Value must be positive");  
    }  
} 
public class MyModel

{

[MyCustomValidationAttribute]

public int MyProperty { get; set; }

}

43. 高级配置方案

概念

.NET 的选项模式支持复杂的配置方案，包括嵌套对象、列表和验证。

代码示例

public class MyOptions  
{  
    public MyNestedOptions Nested { get; set; }  
    public List Items { get; set; }  
}  
public class MyNestedOptions  
{  
    public string Key { get; set; }  
}  
// In Program.cs or Startup.cs  
builder.Services.Configure(builder.Configuration.GetSection("MyOptions"));

44. 性能监控和分析

概念

监视和分析应用程序可以识别瓶颈和效率低下，这对于优化性能至关重要。

代码示例

app.UseMiniProfiler();

45. 带有 Swagger 和 XML 注释的 API 文档

概念

通过将 XML 注释集成到 Swagger UI 中来增强 API 文档，为使用 API 的开发人员提供更丰富的体验。

代码示例

builder.Services.AddSwaggerGen(c =>  
{  
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";  
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);  
    c.IncludeXmlComments(xmlPath);  
});

46. 全球化和本地化

概念

全球化和本地化使您的应用程序能够支持多种语言和文化，使其可供全球受众访问。

代码示例

builder.Services.AddLocalization(options => options.ResourcesPath = "Resources");  
app.UseRequestLocalization(app.Services.GetRequiredService<IOptions>().Value);

47. 安全标头

概念

通过添加各种 HTTP 标头来提高 Web 应用程序的安全性可以防止常见的攻击和漏洞。

代码示例

app.UseHsts();  
app.UseXContentTypeOptions();  
app.UseReferrerPolicy(opts => opts.NoReferrer());  
app.UseXXssProtection(options => options.EnabledWithBlockMode());  
app.UseXfo(options => options.Deny());

48. 功能标志

概念

功能标志允许您在不部署新代码的情况下打开和关闭应用程序的功能，从而简化测试和推出。

代码示例

// Using a library like Microsoft.FeatureManagement  
builder.Services.AddFeatureManagement();

49. Blazor 集成

概念

Blazor 允许使用 C# 而不是 JavaScript 生成交互式 Web UI。将 Blazor 与 Web API 集成可提供无缝的全栈开发体验。

代码示例

// In a Blazor Server app  
@code {  
    private IEnumerable forecasts;  
    protected override async Task OnInitializedAsync()  
    {  
        forecasts = await Http.GetFromJsonAsync<WeatherForecast\[\]>("WeatherForecast");  
    }  
}

50. 用于响应压缩的高级中间件

概念

响应压缩可以减小 API 响应的大小，从而缩短客户端在慢速网络上的加载时间。

代码示例

builder.Services.AddResponseCompression(options =>  
{  
    options.Providers.Add();  
    options.EnableForHttps = true;  
});  
app.UseResponseCompression();

来源：从0到1搭建.NET Core Web API项目 https://www.iwmyx.cn/c0d1cjnetcorewebap.html